Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
Pre-launch fixes: Claude Code on Claude 5.5 models, fx tools' types, errors that reach the reader (#2)
Pranay Prakashea1f5b86dfa4
diff --git a/packages/durable-harness/README.md b/packages/durable-harness/README.mdindex e8cae9d..ae297b2 100644--- a/packages/durable-harness/README.md+++ b/packages/durable-harness/README.md@@ -58,9 +58,14 @@ export const { GET, POST } = chatRoute({ open, agent, authorize: async (request)```ts// next.config.ts+import type { NextConfig } from 'next';import { withDurableHarness } from 'durable-harness/next';-export default withDurableHarness({});+const nextConfig: NextConfig = {+ // your existing config+};++export default withDurableHarness(nextConfig);```Choose your harness and framework in thediff --git a/packages/durable-harness/src/fx.ts b/packages/durable-harness/src/fx.tsindex d9d1e88..76f9e31 100644--- a/packages/durable-harness/src/fx.ts+++ b/packages/durable-harness/src/fx.ts@@ -72,6 +72,13 @@ export interface FxToolsOptions {world?: World;}+/**+ * One of `fxTools()`'s tools: a libfx host tool that says whether a call is+ * safe to run twice, as `createFxAgent()` requires of its tools (libfx's+ * `FxAgentHostTool`).+ */+export type FxKernelTool = FxHostTool & { idempotent: boolean };+/*** libfx's kernel tools on `workspace` (`virtual()` or `sandbox()`), for* `createFxAgent({ tools })`: six libfx host tools, in the order fx@@ -79,16 +86,16 @@ export interface FxToolsOptions {* app's own. Install `just-bash` for `virtual()`, `@vercel/sandbox` for* `sandbox()`.*/-export function fxTools(workspace: Workspace, options: FxToolsOptions = {}): FxHostTool[] {+export function fxTools(workspace: Workspace, options: FxToolsOptions = {}): FxKernelTool[] {const environment = resolveEnvironment(workspace);const { world } = options;const worldOf = world ? () => world : defaultWorld;// Each tool carries the workspace-tool brand, so claudeCode() and codex() refuse them.if (environment.kind === 'sandbox') {// The session factory loads (with `@vercel/sandbox`) on the first acquire.- return fxAgentTools({ kind: 'sandbox' }, { world: worldOf, acquire: environment.acquire }) as unknown as FxHostTool[];+ return fxAgentTools({ kind: 'sandbox' }, { world: worldOf, acquire: environment.acquire }) as unknown as FxKernelTool[];}- return fxAgentTools(environment.workspace, { isolation: environment.isolation, world: worldOf }) as unknown as FxHostTool[];+ return fxAgentTools(environment.workspace, { isolation: environment.isolation, world: worldOf }) as unknown as FxKernelTool[];}const LOCAL = Symbol.for('durable-harness//fx-local-world');diff --git a/packages/durable-harness/test/fx-types.test.ts b/packages/durable-harness/test/fx-types.test.tsnew file mode 100644index 0000000..cdd9040--- /dev/null+++ b/packages/durable-harness/test/fx-types.test.ts@@ -0,0 +1,6 @@+import { expectTypeOf, it } from 'vitest';+import { fxTools } from '../src/fx.ts';++it("fxTools()'s tools say whether a call is safe to run twice, as createFxAgent() requires of its tools", () => {+ expectTypeOf<ReturnType<typeof fxTools>[number]['idempotent']>().toEqualTypeOf<boolean>();+});diff --git a/packages/harness-claude-code/src/harness.ts b/packages/harness-claude-code/src/harness.tsindex c8af5a2..15e8b81 100644--- a/packages/harness-claude-code/src/harness.ts+++ b/packages/harness-claude-code/src/harness.ts@@ -436,7 +436,8 @@ export function claudeCodeHarness(options: ClaudeCodeHarnessOptions = {}): HarneonCap: (cap) => {if (cap !== 'concurrency') ctx.halt?.(spendCapped(cap));},- log: (message, fields) => log(`claude-code gateway: ${message}`, fields),+ // Without the app's own log, the handler's default: a refused model call is a warning in the Function's logs, not silence.+ ...(options.log ? { log: (message: string, fields?: Record<string, unknown>) => log(`claude-code gateway: ${message}`, fields) } : {}),});const abort = new AbortController();@@ -783,6 +784,8 @@ export function claudeCodeHarness(options: ClaudeCodeHarnessOptions = {}): Harnefor (;;) {const end = await nextTurnEnd();transcript.endTurn(end);+ // A failed turn (a refused or failed model call) says so on the live stream too, not only in the log.+ if (end.status === 'failed') ctx.live({ type: 'error', message: end.error ?? 'the turn failed' });if (end.consumed) for (const u of end.consumed) outstanding.delete(u);else outstanding.clear();if (end.queued > 0 || outstanding.size > 0) continue;diff --git a/packages/harness-claude-code/test/fake-anthropic.ts b/packages/harness-claude-code/test/fake-anthropic.tsindex d5fe267..f6764ca 100644--- a/packages/harness-claude-code/test/fake-anthropic.ts+++ b/packages/harness-claude-code/test/fake-anthropic.ts@@ -101,8 +101,10 @@ export function lastUserText(r: Pick<FakeRequest, 'messages'>): string {}/** Why `messages` breaks the Messages API's structure, or undefined when it doesn't. */-export function structureProblem(messages: unknown): string | undefined {- if (!Array.isArray(messages) || messages.length === 0) return 'messages: at least one message is required';+export function structureProblem(all: unknown): string | undefined {+ if (!Array.isArray(all) || all.length === 0) return 'messages: at least one message is required';+ // A system message after the first (Claude Code 2.1.296's environment note, to a model that takes an effort) is the API's own: the rest must still alternate.+ const messages = all.filter((m, i) => !(i > 0 && (m as Message | undefined)?.role === ('system' as Message['role'])));const seenToolUse = new Set<string>();for (let i = 0; i < messages.length; i++) {const m = messages[i] as Message;diff --git a/packages/harness-claude-code/test/sandbox-restart.test.ts b/packages/harness-claude-code/test/sandbox-restart.test.tsindex 007b95c..c8564ce 100644--- a/packages/harness-claude-code/test/sandbox-restart.test.ts+++ b/packages/harness-claude-code/test/sandbox-restart.test.ts@@ -97,6 +97,8 @@ async function invocation(builtins?: boolean;executable?: string;budget?: { turnUsd: number; sessionUsd: number };+ /** The session's model (default `MODEL`). */+ model?: string;/** Sees each machine the invocation's drives attach. */onAttach?: (machine: SessionMachine) => void;} = {}@@ -121,7 +123,7 @@ async function invocation(}: sandbox,executable: opts.executable ?? executable!,- model: MODEL,+ model: opts.model ?? MODEL,gatewayUrl: model.url,credential: async () => 'fake-gateway-credential',// The stand-in VM is this machine: no bubblewrap on macOS.@@ -295,6 +297,19 @@ describe.runIf(!!executable)('restart on a new sandbox: the real Agent SDK and tawait model?.close();});+ it("a model that takes an effort (claude-sonnet-5-5): the CLI's output_config passes the gateway, and the turn completes", async () => {+ const dataDir = await mkdtemp(join(tmpdir(), 'hwcc-effort-'));+ const api = platform();+ script = () => ({ text: 'ok' });+ const from = model.requests.length;+ const inv = await invocation(dataDir, api, model, { model: 'claude-sonnet-5-5' });+ const { sessionId } = await inv.sessions.start();+ await inv.sessions.send(sessionId, 'Say ok.');+ expect(turns(await waitTurns(inv.sessions, sessionId, 1))).toEqual([{ type: 'turn', status: 'completed' }]);+ await inv.drained();+ expect(model.messages().slice(from).find(main)?.body.output_config).toMatchObject({ effort: expect.any(String) });+ });+it('R1: a file and a code word on VM A; VM A deleted, the Drive kept; VM B reads the file and recalls the word from the log', async () => {const dataDir = await mkdtemp(join(tmpdir(), 'hwcc-r1-'));const api = platform();diff --git a/packages/harness-codex/src/harness.ts b/packages/harness-codex/src/harness.tsindex 50ee341..292d9fc 100644--- a/packages/harness-codex/src/harness.ts+++ b/packages/harness-codex/src/harness.ts@@ -450,7 +450,8 @@ export function codexHarness(options: CodexHarnessOptions = {}): Harness {onCap: (cap) => {if (cap !== 'concurrency') capped = cap;},- log: (message, fields) => log(`codex gateway: ${message}`, fields),+ // Without the app's own log, the handler's default: a refused model call is a warning in the Function's logs, not silence.+ ...(options.log ? { log: (message: string, fields?: Record<string, unknown>) => log(`codex gateway: ${message}`, fields) } : {}),});let machine: SessionMachine;try {diff --git a/packages/harness-process/src/gateway.ts b/packages/harness-process/src/gateway.tsindex 9bd749b..0267dca 100644--- a/packages/harness-process/src/gateway.ts+++ b/packages/harness-process/src/gateway.ts@@ -357,8 +357,15 @@ export const CLAUDE_BETAS: ReadonlySet<string> = new Set([]);/** Top-level keys a Messages request may carry: no `mcp_servers`, `container`, `service_tier` or provider options. */-const MESSAGES_KEYS = new Set(['model', 'messages', 'system', 'max_tokens', 'metadata', 'stop_sequences', 'stream', 'temperature', 'top_k', 'top_p', 'tools', 'tool_choice', 'thinking', 'context_management']);-const COUNT_TOKENS_KEYS = new Set(['model', 'messages', 'system', 'tools', 'tool_choice', 'thinking', 'context_management']);+const MESSAGES_KEYS = new Set(['model', 'messages', 'system', 'max_tokens', 'metadata', 'stop_sequences', 'stream', 'temperature', 'top_k', 'top_p', 'tools', 'tool_choice', 'thinking', 'context_management', 'output_config']);+const COUNT_TOKENS_KEYS = new Set(['model', 'messages', 'system', 'tools', 'tool_choice', 'thinking', 'context_management', 'output_config']);+/**+ * What `output_config` may carry: the effort, a structured output's format+ * and a task budget, as Claude Code 2.1.296 sends them (the effort on every+ * request to a model that takes one). None makes the provider fetch or run+ * anything.+ */+const OUTPUT_CONFIG_KEYS = new Set(['effort', 'format', 'task_budget']);/** Top-level keys a Responses request may carry. */const RESPONSES_KEYS = new Set(['model', 'instructions', 'input', 'tools', 'tool_choice', 'parallel_tool_calls', 'reasoning', 'store', 'stream', 'include', 'prompt_cache_key', 'text', 'max_output_tokens', 'temperature', 'top_p']);@@ -446,9 +453,18 @@ function anthropicThinking(thinking: unknown, maxTokens: number): unknown {return { ...thinking, budget_tokens: maxTokens - 1 };}+function anthropicOutputConfig(config: unknown): void {+ if (config === undefined) return;+ if (!isPlain(config)) throw refuse('bad_request', 'output_config must be an object');+ onlyKeys(config, OUTPUT_CONFIG_KEYS, 'output_config');+ if (config.effort !== undefined && typeof config.effort !== 'string') throw refuse('bad_request', 'output_config.effort must be a string');+ for (const k of ['format', 'task_budget']) if (config[k] !== undefined && !isPlain(config[k])) throw refuse('bad_request', `output_config.${k} must be an object`);+}+/** Claude's `POST /v1/messages`. */export const anthropicMessages: BodyPolicy = (body, check) => {onlyKeys(body, MESSAGES_KEYS, 'messages');+ anthropicOutputConfig(body.output_config);anthropicConversation(body, check);anthropicTools(body.tools, check);const max = check.clampTokens(body.max_tokens);@@ -458,6 +474,7 @@ export const anthropicMessages: BodyPolicy = (body, check) => {/** Claude's `POST /v1/messages/count_tokens`. */export const anthropicCountTokens: BodyPolicy = (body, check) => {onlyKeys(body, COUNT_TOKENS_KEYS, 'count_tokens');+ anthropicOutputConfig(body.output_config);anthropicConversation(body, check);anthropicTools(body.tools, check);return { ...body, model: check.model(body.model) };diff --git a/packages/harness-process/test/gateway-policy.test.ts b/packages/harness-process/test/gateway-policy.test.tsindex 659f6b0..e7085c7 100644--- a/packages/harness-process/test/gateway-policy.test.ts+++ b/packages/harness-process/test/gateway-policy.test.ts@@ -203,6 +203,21 @@ describe('gatewayHandler: the body', () => {expect(gw.seen).toHaveLength(0);});+ it("passes Claude Code 2.1.296's output_config (effort, format, task_budget), and refuses anything else in it", async () => {+ const gw = await gateway();+ const { h } = handler(gw.url);+ const config = { effort: 'high', format: { type: 'json_schema', schema: { type: 'object' } }, task_budget: { type: 'tokens', total: 64_000 } };+ await drain((await h(req('/v1/messages', messages({ output_config: config })), signal())).body);+ await drain((await h(req('/v1/messages/count_tokens', { model: MODELS.model, messages: [{ role: 'user', content: 'hi' }], output_config: { effort: 'low' } }), signal())).body);+ expect(JSON.parse(gw.seen[0]!.body).output_config).toEqual(config);+ expect(JSON.parse(gw.seen[1]!.body).output_config).toEqual({ effort: 'low' });+ await refused(h(req('/v1/messages', messages({ output_config: { effort: 'high', mcp_servers: [] } })), signal()), 'forbidden');+ for (const output_config of ['high', { effort: 3 }, { format: 'json' }, { task_budget: 64_000 }]) {+ await refused(h(req('/v1/messages', messages({ output_config })), signal()), 'bad_request');+ }+ expect(gw.seen).toHaveLength(2);+ });+it('refuses a tool type that is not a client tool, and a provider-hosted tool without the opt-in or with network deny-all', async () => {const gw = await gateway();const { h } = handler(gw.url);diff --git a/packages/harness-sandbox/src/env-check.ts b/packages/harness-sandbox/src/env-check.tsindex 8bbaf3c..7699a4d 100644--- a/packages/harness-sandbox/src/env-check.ts+++ b/packages/harness-sandbox/src/env-check.ts@@ -48,12 +48,27 @@ const SECRET_VALUE_SHAPES: readonly (readonly [string, RegExp])[] = [export const PLACEHOLDER_NAMES: ReadonlySet<string> = new Set<string>(['ANTHROPIC_AUTH_TOKEN', 'HARNESS_CODEX_GATEWAY_KEY']);/**- * Names whose values are paths or fixed names the harness sets (never- * secrets): the `process.env` equality rule skips them, so a host whose own- * `PATH` or `HOME` happens to be the VM's, or whose `npm_package_name` is the- * harness's client app name, isn't refused.+ * Names whose values are paths, model ids or fixed names the harness sets+ * (never secrets): the `process.env` equality rule skips them, so a host whose+ * own `PATH` or `HOME` happens to be the VM's, whose `npm_package_name` is the+ * harness's client app name, or that runs under Claude Code with the session's+ * model in its own `ANTHROPIC_DEFAULT_*_MODEL`, isn't refused.*/-const HARNESS_NAMES: ReadonlySet<string> = new Set(['PATH', 'HOME', 'TMPDIR', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'CLAUDE_AGENT_SDK_CLIENT_APP']);+const HARNESS_NAMES: ReadonlySet<string> = new Set([+ 'PATH',+ 'HOME',+ 'TMPDIR',+ 'XDG_CONFIG_HOME',+ 'XDG_CACHE_HOME',+ 'XDG_DATA_HOME',+ 'XDG_STATE_HOME',+ 'CLAUDE_CONFIG_DIR',+ 'CODEX_HOME',+ 'CLAUDE_AGENT_SDK_CLIENT_APP',+ 'ANTHROPIC_DEFAULT_OPUS_MODEL',+ 'ANTHROPIC_DEFAULT_SONNET_MODEL',+ 'ANTHROPIC_DEFAULT_HAIKU_MODEL',+]);const refuse = (key: string, why: string) => new TypeError(`harness-sandbox: spawn env ${JSON.stringify(key)} refused: ${why}`);diff --git a/packages/harness-sandbox/test/env-check.test.ts b/packages/harness-sandbox/test/env-check.test.tsnew file mode 100644index 0000000..5cc6b99--- /dev/null+++ b/packages/harness-sandbox/test/env-check.test.ts@@ -0,0 +1,11 @@+import { describe, expect, it } from 'vitest';+import { checkSpawnEnv } from '../src/env-check.ts';++describe('checkSpawnEnv', () => {+ it("passes Claude Code's model ids when the host holds the same ones (next dev run from Claude Code), and still refuses a host value under another name", () => {+ const host = { ANTHROPIC_DEFAULT_SONNET_MODEL: 'claude-sonnet-5-5', ANTHROPIC_MODEL: 'claude-sonnet-5-5' };+ const ids = { ANTHROPIC_DEFAULT_OPUS_MODEL: 'claude-sonnet-5-5', ANTHROPIC_DEFAULT_SONNET_MODEL: 'claude-sonnet-5-5', ANTHROPIC_DEFAULT_HAIKU_MODEL: 'claude-sonnet-5-5' };+ expect(() => checkSpawnEnv(ids, host)).not.toThrow();+ expect(() => checkSpawnEnv({ NOTE: 'claude-sonnet-5-5' }, host)).toThrow(`spawn env "NOTE" refused: the value equals one of the Function's own environment values`);+ });+});diff --git a/packages/pi-world/src/not-run.test.ts b/packages/pi-world/src/not-run.test.tsnew file mode 100644index 0000000..2aa7163--- /dev/null+++ b/packages/pi-world/src/not-run.test.ts@@ -0,0 +1,14 @@+import { describe, expect, it } from 'vitest';+import { NOT_RUN, NotRunError } from './sandbox.ts';++describe('NotRunError', () => {+ it('says "try again" only for what a retry can fix, and names any other cause (a missing project link)', () => {+ const yielded = Object.assign(new Error('contended'), { name: 'Yield' });+ expect(new NotRunError().message).toBe(NOT_RUN);+ expect(new NotRunError(yielded).message).toBe(NOT_RUN);+ expect(new NotRunError(new Error('the link was lost'), true).message).toBe(NOT_RUN);+ const missing = new NotRunError(new Error('harness-sandbox: no Vercel project for the sandbox: run `vercel link`'));+ expect(missing.message).toBe('Not run: the sandbox could not be attached (harness-sandbox: no Vercel project for the sandbox: run `vercel link`)');+ expect(missing.code).toBe('ENOTRUN');+ });+});diff --git a/packages/pi-world/src/sandbox.ts b/packages/pi-world/src/sandbox.tsindex 4151965..7722dcb 100644--- a/packages/pi-world/src/sandbox.ts+++ b/packages/pi-world/src/sandbox.ts@@ -63,11 +63,18 @@ export const SANDBOX_NO_WORLD =/** What a call says once its storage writes nothing more (closed, or another process took the session). */export const SANDBOX_ENDED = "durable-harness: this invocation of the session holds nothing more (it closed, or another one took the session over): it runs nothing in the session's sandbox";-/** A call that did not run: its sandbox could not be attached (busy, booting, contended). Nothing reached the VM. */+/**+ * A call that did not run: its sandbox could not be attached. Nothing reached+ * the VM. Busy, booting or contended (no cause, a `Yield`, or `retry`):+ * `NOT_RUN`, so the model may retry. Anything else says what failed (a+ * missing project link, a refused credential), as harness-hands' `NotRun`+ * does, so the model isn't told to retry what no retry fixes.+ */export class NotRunError extends Error {readonly code = 'ENOTRUN';- constructor(cause?: unknown) {- super(NOT_RUN, cause !== undefined ? { cause } : undefined);+ constructor(cause?: unknown, retry = cause === undefined || (cause as { name?: unknown }).name === 'Yield') {+ const reason = retry ? '' : String((cause as Error)?.message ?? cause).replace(/\s+/g, ' ').slice(0, 300);+ super(retry ? NOT_RUN : `Not run: the sandbox could not be attached (${reason})`, cause !== undefined ? { cause } : undefined);this.name = 'NotRunError';}}@@ -153,7 +160,7 @@ export class SandboxSession {if (storage.signal.aborted || machine.signal.aborted || machine.workspace.lost) {void machine.close().catch(() => {});if (storage.signal.aborted) throw new Error(SANDBOX_ENDED);- throw new NotRunError(new Error('the sandbox link was lost as it was attached'));+ throw new NotRunError(new Error('the sandbox link was lost as it was attached'), true);}if (machine.workspace.root !== WORKSPACE_ROOT) {void machine.close().catch(() => {});