Skip to content

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.md
index 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 the
diff --git a/packages/durable-harness/src/fx.ts b/packages/durable-harness/src/fx.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 = {}): Harne
onCap: (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 = {}): Harne
for (;;) {
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.ts
index 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.ts
index 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 t
await 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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(() => {});