Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(openai-codex): replay an evicted exec script from history

Jack Rudenko52afe02753df
diff --git a/ai-docs/architecture/code-mode.md b/ai-docs/architecture/code-mode.md
index d2f03d0c..1e1c82ee 100644
--- a/ai-docs/architecture/code-mode.md
+++ b/ai-docs/architecture/code-mode.md
@@ -183,7 +183,8 @@ created them.
| consumed batch, same `batchHash` (a duplicate request) | the memoised step: the same synthetic reply, or the stored completion |
| consumed batch, different `batchHash` (a rewind that re-ran tools) | lost path, tombstone under the new completion key |
| suspended, owned by ANOTHER session (a fork) | untouched; the fork gets `Script failed` "this script belongs to the session this one was forked from; claudish cannot run it twice"; the owner's later run output wins every lookup |
-| record lost (eviction, poisoned module) or none (restart, another account) | `Script failed` "claudish lost this script's state (proxy restart or eviction); the nested tool results it was waiting for follow" + the results, stored as a TOMBSTONE (a minimal record when none) |
+| record lost, source kept, owned by this session, the request answers its LAST round | **replay** (`replay.ts`): the source re-runs in a fresh runtime and each batch is answered from history, provided batch k is exactly the k-th round (same ids, names and canonical inputs); then as the first row. `Math.random` is seeded by the call id; a script that branches on `Date` diverges |
+| record lost (eviction, poisoned module, or a replay that diverged) or none (restart, another account) | `Script failed` "claudish lost this script's state (proxy restart or eviction); the nested tool results it was waiting for follow" + the results, stored as a TOMBSTONE (a minimal record when none) |
| late results for a settled record | nothing; history renders its output |
For every OTHER suspended record of the session: a pending batch the conversation moved past
diff --git a/packages/cli/src/code-mode/replay.ts b/packages/cli/src/code-mode/replay.ts
new file mode 100644
index 00000000..378d95a7
--- /dev/null
+++ b/packages/cli/src/code-mode/replay.ts
@@ -0,0 +1,158 @@
+/**
+ * Replay a lost exec script from history (architecture §5.12).
+ *
+ * A suspended script whose runtime was evicted (the 32-runtime live cap, the
+ * 6 h idle TTL, a retired or poisoned module) still has its record and its
+ * SOURCE. When Claude Code's answer to its pending batch arrives, the script is
+ * re-run from the start in a fresh runtime and each batch it blocks on is
+ * answered from history: batch k must be exactly the k-th round the request
+ * carries — the same nested ids, and for each the same tool name and the same
+ * canonical input. Only then are that round's tool_results fed in. A script is
+ * deterministic enough for this: `Math.random` is seeded by its exec call id;
+ * `Date` is not, and a script that branches on it mismatches. Any mismatch, or
+ * no loaded sandbox module (this step is synchronous and never loads one),
+ * leaves the record lost and the caller takes the lost path.
+ *
+ * The record is only ever replayed by its OWNER session (the caller checks).
+ */
+
+import { log } from "../logger.js";
+import { type ClaudeToolLike, renderExecTool } from "./exec-tool.js";
+import { type BatchResultEntry, batchHash, canonicalJson, completionKey } from "./hashes.js";
+import { decodeNestedId, encodeNestedId } from "./ids.js";
+import { nestedBlocksFor, settleDone, suspendBlocked } from "./relay.js";
+import { type QuickJSModuleLease, currentQuickJSModule } from "./sandbox/quickjs-loader.js";
+import {
+ type NestedCall,
+ type NestedResult,
+ type ScriptRuntime,
+ createScriptRuntime,
+} from "./sandbox/script-runtime.js";
+import type { ExecRecord, ExecState, ScriptStore } from "./script-store.js";
+import { nestedResultFromToolResult } from "./tool-results.js";
+import type { ClaudeContentBlock, NestedToolUse } from "./types.js";
+
+/** One round of the exec in the request's history: its nested tool_use blocks, in order. */
+export interface HistoryRound {
+ ids: string[];
+ blocks: ClaudeContentBlock[];
+}
+
+export interface ReplayInput {
+ scripts: ScriptStore;
+ /** A `lost` record that still has its source and the batches it relayed. */
+ record: ExecRecord;
+ /** The exec's rounds in this request, ending with the round this request answers. */
+ rounds: HistoryRound[];
+ /** tool_use id → tool_result across the request. */
+ results: ReadonlyMap<string, ClaudeContentBlock>;
+ /** Claude Code's tools in this request (the identifiers the script calls). */
+ tools: readonly ClaudeToolLike[];
+ sessionKey: string;
+ /** Test seam; default the loaded module, if any. */
+ module?: QuickJSModuleLease;
+}
+
+export type ReplayResult =
+ | { kind: "reply"; blocks: [NestedToolUse, ...NestedToolUse[]] }
+ | { kind: "done" }
+ | undefined;
+
+function entriesOf(
+ ids: readonly string[],
+ results: ReadonlyMap<string, ClaudeContentBlock>
+): BatchResultEntry[] {
+ return ids.map((id) => {
+ const result = results.get(id);
+ return result
+ ? {
+ toolUseId: id,
+ result: { isError: result.is_error === true, content: result.content ?? "" },
+ }
+ : { toolUseId: id };
+ });
+}
+
+/** The batch the script blocked on is exactly this history round. */
+function matchesRound(execKey: string, calls: readonly NestedCall[], round: HistoryRound): boolean {
+ if (calls.length !== round.blocks.length) return false;
+ return calls.every((call) => {
+ const id = encodeNestedId(execKey, call.seq);
+ const block = round.blocks.find((b) => b.id === id);
+ return (
+ block !== undefined &&
+ block.name === call.name &&
+ canonicalJson(block.input ?? {}) === canonicalJson(call.input)
+ );
+ });
+}
+
+function resultsFor(
+ round: HistoryRound,
+ results: ReadonlyMap<string, ClaudeContentBlock>
+): NestedResult[] {
+ const out: NestedResult[] = [];
+ for (const id of round.ids) {
+ const seq = decodeNestedId(id)?.seq;
+ const block = results.get(id);
+ if (seq !== undefined && block) out.push(nestedResultFromToolResult(seq, block));
+ }
+ return out;
+}
+
+/**
+ * Re-run `record`'s script against history. A blocked step past the last
+ * round is the script's next batch (reply); a finished one is stored. Undefined
+ * when the script is not replayable or diverged: the record stays lost.
+ */
+export function replayLostScript(input: ReplayInput): ReplayResult {
+ const { record, rounds, results, scripts } = input;
+ if (record.state !== "lost" || record.batches.length === 0 || !record.source) return undefined;
+ if (rounds.length === 0) return undefined;
+ const lease = input.module ?? currentQuickJSModule();
+ if (!lease) return undefined;
+ let runtime: ScriptRuntime | undefined;
+ try {
+ const rendered = renderExecTool(input.tools);
+ runtime = createScriptRuntime({
+ tools: rendered.names,
+ allTools: rendered.allTools,
+ seed: record.originalCallId,
+ module: lease,
+ });
+ let step = runtime.start(record.source);
+ const hashes: string[] = [];
+ for (const round of rounds) {
+ if (step.kind !== "blocked" || !matchesRound(record.execCallId, step.calls, round)) {
+ log(`[CodeMode] exec ${record.originalCallId}: replay diverged from history; script lost`);
+ runtime.dispose();
+ return undefined;
+ }
+ hashes.push(batchHash(entriesOf(round.ids, results)));
+ step = runtime.resume(resultsFor(round, results));
+ }
+ scripts.transition(record, "replay");
+ scripts.attachRuntime(record, runtime);
+ record.batches = rounds.map((round, k) => ({ ids: round.ids, batchHash: hashes[k] }));
+ if (step.kind === "blocked") {
+ const blocks = nestedBlocksFor(record.execCallId, step.calls);
+ suspendBlocked(scripts, record, blocks);
+ log(`[CodeMode] exec ${record.originalCallId}: replayed from history; blocked again`);
+ return { kind: "reply", blocks };
+ }
+ settleDone(scripts, record, step.output, completionKey(hashes), input.sessionKey);
+ log(`[CodeMode] exec ${record.originalCallId}: replayed from history; ${step.output.status}`);
+ return { kind: "done" };
+ } catch (err) {
+ log(`[CodeMode] exec ${record.originalCallId}: replay failed; script lost: ${err}`);
+ try {
+ runtime?.dispose();
+ // The replay transition may already have run before the throw.
+ const state: ExecState = (record as ExecRecord).state;
+ if (state === "running") scripts.transition(record, "fail");
+ } catch {
+ // The runtime is gone either way.
+ }
+ return undefined;
+ }
+}
diff --git a/packages/cli/src/code-mode/resume.ts b/packages/cli/src/code-mode/resume.ts
index 5d51e3a1..6be5f328 100644
--- a/packages/cli/src/code-mode/resume.ts
+++ b/packages/cli/src/code-mode/resume.ts
@@ -46,12 +46,14 @@ import { extractSessionId } from "../behavior/harness.js";
import type { ClaudeToolChoice } from "../handlers/shared/format/openai-tools.js";
import { log } from "../logger.js";
import type { AuthBinding } from "../providers/transport/types.js";
+import type { ClaudeToolLike } from "./exec-tool.js";
import { type BatchResultEntry, batchHash, completionKey } from "./hashes.js";
import { accountKeyFromBinding, decodeNestedId, sessionKeyFor } from "./ids.js";
import { LOST_SCRIPT_NOTE, MOVED_ON_NOTE, reconstructExecSource } from "./input-builder.js";
import type { ExecOutput, OutputPart } from "./output.js";
import type { CodeModeSetting } from "./policy.js";
import { nestedBlocksFor, settleDone, suspendBlocked } from "./relay.js";
+import { replayLostScript } from "./replay.js";
import type { NestedResult } from "./sandbox/script-runtime.js";
import type { ExecRecord, ScriptStore } from "./script-store.js";
import type { CodeModeStores } from "./stores.js";
@@ -87,6 +89,8 @@ interface RequestView {
toolUses: Map<string, ClaudeContentBlock>;
/** tool_use id → its tool_result (first occurrence, user messages), as the input builder reads them. */
results: Map<string, ClaudeContentBlock>;
+ /** Claude Code's tools in this request (a replayed script calls them). */
+ tools: ClaudeToolLike[];
}
function blocksOf(message: ClaudeMessage | undefined): ClaudeContentBlock[] {
@@ -236,6 +240,11 @@ class Resume {
interrupted: boolean
): ResumeOutcome {
const record = this.scripts.get(this.view.accountKey, execKey);
+ // An evicted runtime whose source is kept: re-run it against history first.
+ if (record?.state === "lost" && record.sessionKey === this.view.sessionKey) {
+ const replayed = this.replay(execKey, record);
+ if (replayed) return replayed;
+ }
// Restart, another account's record, eviction or a poisoned module: the
// script state is gone; the model gets Script failed and the results.
if (!record || record.state === "lost")
@@ -346,6 +355,23 @@ class Resume {
}
}
+ /** C6: replay a lost script from history when this request answers its LAST round. */
+ private replay(execKey: string, record: ExecRecord): ResumeOutcome | undefined {
+ const rounds = this.historyRounds(execKey);
+ const answered = rounds.findIndex((r) => r.ids.some((id) => this.view.results.has(id)));
+ if (answered < 0 || answered !== rounds.length - 1) return undefined;
+ const replayed = replayLostScript({
+ scripts: this.scripts,
+ record,
+ rounds,
+ results: this.view.results,
+ tools: this.view.tools,
+ sessionKey: this.view.sessionKey,
+ });
+ if (!replayed) return undefined;
+ return replayed.kind === "reply" ? replayed : { kind: "continue" };
+ }
+
/** A duplicate of a request already answered: the memoised step. */
private replayDuplicate(record: ExecRecord, k: number): ResumeOutcome {
const [first, ...rest] = record.batches[k + 1]?.blocks ?? [];
@@ -469,7 +495,7 @@ class Resume {
* failure loses the script, never the request.
*/
export function resumeFromToolResults(
- req: { messages?: unknown; metadata?: unknown },
+ req: { messages?: unknown; metadata?: unknown; tools?: unknown },
binding: AuthBinding | undefined,
stores: CodeModeStores | undefined,
toolChoice: ClaudeToolChoice | null | undefined,
@@ -490,6 +516,7 @@ export function resumeFromToolResults(
sessionKey,
toolUses: indexToolUses(messages),
results: indexToolResults(messages),
+ tools: Array.isArray(req.tools) ? (req.tools as ClaudeToolLike[]) : [],
},
stores
);