Skip to content

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

feat(openai-codex): keep exec and turn records in byte-bounded stores

Jack Rudenkoa854eb4570d7
diff --git a/packages/cli/src/code-mode/hashes.ts b/packages/cli/src/code-mode/hashes.ts
new file mode 100644
index 00000000..a10556a8
--- /dev/null
+++ b/packages/cli/src/code-mode/hashes.ts
@@ -0,0 +1,73 @@
+/**
+ * The two hashes that tie a script's stored output to the history that
+ * produced it. One implementation, used by the resume step (5r) when it
+ * consumes a batch and by the input builder when it renders history, so both
+ * compute the same key from the same results.
+ *
+ * - `batchHash(k)` = sha256 over the canonical `(tool_use_id, is_error,
+ * content)` of batch k's nested results, in nested-call order; a missing
+ * result canonicalises as `(tool_use_id, "missing")`.
+ * - `completionKey` = sha256 over `batchHash(0) ‖ … ‖ batchHash(last)` of the
+ * batches the script consumed, in order.
+ *
+ * Identical history ⇒ identical key; a rewind that changed any batch's results
+ * ⇒ a different key, so a stale output is never rendered for new results.
+ */
+
+import { createHash } from "node:crypto";
+import { decodeNestedId } from "./ids.js";
+
+/** One nested call of a batch and Claude Code's tool_result for it, if any. */
+export interface BatchResultEntry {
+ toolUseId: string;
+ result?: { isError: boolean; content: unknown };
+}
+
+/** JSON with object keys sorted at every depth: a stable serialisation for hashing. */
+export function canonicalJson(value: unknown): string {
+ if (value === null || typeof value !== "object") {
+ return JSON.stringify(value) ?? "null";
+ }
+ if (Array.isArray(value)) {
+ return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
+ }
+ const keys = Object.keys(value as Record<string, unknown>)
+ .filter((k) => (value as Record<string, unknown>)[k] !== undefined)
+ .sort();
+ const body = keys
+ .map((k) => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`)
+ .join(",");
+ return `{${body}}`;
+}
+
+/** Nested-call order: by decoded seq, then by id for anything that does not decode. */
+function compareIds(a: string, b: string): number {
+ const da = decodeNestedId(a);
+ const db = decodeNestedId(b);
+ if (da && db && da.seq !== db.seq) return da.seq - db.seq;
+ return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** sha256 hex of one batch's canonical results. */
+export function batchHash(entries: readonly BatchResultEntry[]): string {
+ const ordered = [...entries].sort((a, b) => compareIds(a.toolUseId, b.toolUseId));
+ const hash = createHash("sha256");
+ for (const entry of ordered) {
+ const canonical = entry.result
+ ? canonicalJson([entry.toolUseId, entry.result.isError === true, entry.result.content ?? ""])
+ : canonicalJson([entry.toolUseId, "missing"]);
+ hash.update(canonical);
+ hash.update("\n");
+ }
+ return hash.digest("hex");
+}
+
+/** sha256 hex over the batch hashes of every batch the script consumed, in order. */
+export function completionKey(batchHashes: readonly string[]): string {
+ const hash = createHash("sha256");
+ for (const h of batchHashes) {
+ hash.update(h);
+ hash.update("\n");
+ }
+ return hash.digest("hex");
+}
diff --git a/packages/cli/src/code-mode/ids.ts b/packages/cli/src/code-mode/ids.ts
index 39987081..f2e00e00 100644
--- a/packages/cli/src/code-mode/ids.ts
+++ b/packages/cli/src/code-mode/ids.ts
@@ -40,3 +40,66 @@ export function accountKeyFromBinding(binding: AuthBinding | undefined): string
if (!accountId) return undefined;
return sha256Hex(`openai-codex\0${accountId}`);
}
+
+/**
+ * `sha256(session id + "\0" + accountKey)`: the key of one Claude Code
+ * session on one account. Undefined when the request carries no Claude Code
+ * session id — the process-wide `conversationKey()` fallback is a cache hint
+ * and must never key stateful execution — or when there is no account key.
+ */
+export function sessionKeyFor(
+ sessionId: string | undefined,
+ accountKey: string | undefined
+): string | undefined {
+ if (!sessionId || !accountKey) return undefined;
+ return sha256Hex(`${sessionId}\0${accountKey}`);
+}
+
+const CALL_ID_HEX = /^call_([0-9a-f]{32})$/;
+const NESTED_ID = /^toolu_cx_([0-9a-f]{32})_(\d{1,4})$/;
+
+const EXEC_KEY = /^[0-9a-f]{32}$/;
+
+/**
+ * The 32-hex key of an exec call: the suffix of a `call_<32 hex>` id (the
+ * Codex shape), else the first 32 hex of `sha256(callId)`. Records are keyed
+ * by it and keep the original id beside it. Idempotent: a key maps to itself.
+ */
+export function execKeyFor(callId: string): string {
+ if (EXEC_KEY.test(callId)) return callId;
+ const match = CALL_ID_HEX.exec(callId);
+ return match ? match[1] : sha256Hex(callId).slice(0, 32);
+}
+
+/** The tool_use id of nested call `seq` of exec `execCallId`: `toolu_cx_<hex>_<seq>`. */
+export function encodeNestedId(execCallId: string, seq: number): string {
+ return `toolu_cx_${execKeyFor(execCallId)}_${seq}`;
+}
+
+/**
+ * `{execKey, seq}` for a nested tool_use id, matching
+ * `^toolu_cx_([0-9a-f]{32})_(\d{1,4})$` exactly. Every other id — classic
+ * Claude ids, the parallel-wrapper `toolu_<id>_p<k>` ids — decodes to
+ * undefined, so history grouping never depends on the store.
+ */
+export function decodeNestedId(id: string): { execKey: string; seq: number } | undefined {
+ const match = NESTED_ID.exec(id);
+ if (!match) return undefined;
+ return { execKey: match[1], seq: Number(match[2]) };
+}
+
+/**
+ * RFC 4122 version-5 UUID of `name` in the namespace derived from `namespace`
+ * (any string; its sha256 supplies the 16 namespace bytes). Stable for stable
+ * inputs, which keeps the lite `additional_tools` item id a stable prompt-cache
+ * prefix.
+ */
+export function uuidV5(namespace: string, name: string): string {
+ const ns = createHash("sha256").update(namespace).digest().subarray(0, 16);
+ const hash = createHash("sha1").update(ns).update(name).digest();
+ const bytes = Buffer.from(hash.subarray(0, 16));
+ bytes[6] = (bytes[6] & 0x0f) | 0x50;
+ bytes[8] = (bytes[8] & 0x3f) | 0x80;
+ const hex = bytes.toString("hex");
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
diff --git a/packages/cli/src/code-mode/script-store.ts b/packages/cli/src/code-mode/script-store.ts
new file mode 100644
index 00000000..28e63400
--- /dev/null
+++ b/packages/cli/src/code-mode/script-store.ts
@@ -0,0 +1,467 @@
+/**
+ * Exec records: one per exec call relayed with code mode on, keyed
+ * `(accountKey, execCallId)`, holding the script source, its suspended runtime
+ * while it waits on Claude Code, the batches it emitted and the outputs it
+ * produced.
+ *
+ * Why keyed by account and not by session: upstream call ids are unique, so a
+ * forked session (`--fork-session`: new session id, same history, same account)
+ * still finds its execs and renders their completed outputs byte-identically.
+ * Each record stores its OWNER `sessionKey`; only the owner may resume it. A
+ * request on another account computes another `accountKey` and never finds,
+ * resumes or renders this account's records.
+ *
+ * States — the State pattern's transition-table form (`patterns/state.md`),
+ * chosen because the states differ only in which transitions are legal:
+ *
+ * running: block → suspended, finish → completed, fail → failed
+ * suspended: resume → running, terminate → terminated, abandon → terminated,
+ * evict → lost, expire → lost
+ * lost: answer → failed (tombstone stored), replay → running
+ * completed / failed / terminated: answer → same state
+ *
+ * The catalog's table throws on an illegal transition. Here it is logged and
+ * coerced to `lost`, never thrown: this runs on the request path, and a refused
+ * request is worse than a degraded script. Every transition that ends a runtime
+ * disposes it.
+ *
+ * Every store has a byte ceiling the model cannot raise (architecture §5.8):
+ * settled records (anything but running/suspended) are capped at 2,000 records
+ * AND 32 MiB, counting the UTF-8 length of the source, every stored output's
+ * text and the reasoning items' JSON (images are references, never bytes).
+ * Eviction is LRU by `lastTouched`; an evicted record's id goes to a bounded
+ * FIFO set, so the input builder can say "evicted" rather than "restart".
+ * Suspended records are bounded by the sandbox's live-runtime cap (32) and a
+ * 6 h idle TTL. A 60 s reaper applies the TTL and the caps.
+ */
+
+import { log } from "../logger.js";
+import type { ExecOutput } from "./output.js";
+import type { ScriptRuntime } from "./sandbox/script-runtime.js";
+import type { ResponsesItem } from "./types.js";
+
+export type ExecState = "running" | "suspended" | "completed" | "failed" | "terminated" | "lost";
+
+export type ExecEvent =
+ | "block"
+ | "finish"
+ | "fail"
+ | "resume"
+ | "terminate"
+ | "abandon"
+ | "evict"
+ | "expire"
+ | "answer"
+ | "replay";
+
+/** The legal transitions; anything absent is illegal (logged, coerced to `lost`). */
+const TRANSITIONS: Record<ExecState, Partial<Record<ExecEvent, ExecState>>> = {
+ running: { block: "suspended", finish: "completed", fail: "failed" },
+ suspended: {
+ resume: "running",
+ terminate: "terminated",
+ abandon: "terminated",
+ evict: "lost",
+ expire: "lost",
+ },
+ lost: { answer: "failed", replay: "running" },
+ completed: { answer: "completed" },
+ failed: { answer: "failed" },
+ terminated: { answer: "terminated" },
+};
+
+/** Events after which the runtime is gone. */
+const ENDS_RUNTIME = new Set<ExecEvent>([
+ "finish",
+ "fail",
+ "terminate",
+ "abandon",
+ "evict",
+ "expire",
+ "answer",
+]);
+
+/** An output stored for one completion key. */
+export interface StoredOutput {
+ output: ExecOutput;
+ /** `run`: the script produced it; `tombstone`: claudish answered for a lost script. */
+ origin: "run" | "tombstone";
+ /** The session that stored it (a tombstone is rendered only for that session). */
+ sessionKey: string;
+}
+
+/** One emitted batch: the nested tool_use ids, and its hash once consumed. */
+export interface ExecBatch {
+ ids: string[];
+ batchHash?: string;
+}
+
+export interface ExecRecord {
+ accountKey: string;
+ /** The owner: only this session may resume the script. */
+ sessionKey: string;
+ /** The 32-hex exec key (`execKeyFor`), the key nested ids carry. */
+ execCallId: string;
+ /** The upstream `call_id` as the model sent it. */
+ originalCallId: string;
+ source: string;
+ shape: "lite" | "classic";
+ state: ExecState;
+ runtime?: ScriptRuntime;
+ batches: ExecBatch[];
+ /** Outputs by completion key (`hashes.ts`). */
+ outputs: Map<string, StoredOutput>;
+ /** The reasoning items of the leg that produced the exec. */
+ reasoningItems?: ResponsesItem[];
+ /** The exec's output budget in tokens (pragma, else the default) when it was relayed. */
+ maxOutputTokens?: number;
+ startedAt: number;
+ lastTouched: number;
+ /** Counted bytes (source + output text + reasoning JSON). */
+ bytes: number;
+}
+
+export interface ScriptStoreLimits {
+ maxRecords: number;
+ maxBytes: number;
+ suspendedTtlMs: number;
+ maxEvictedIds: number;
+ reapIntervalMs: number;
+}
+
+export const DEFAULT_SCRIPT_STORE_LIMITS: ScriptStoreLimits = {
+ maxRecords: 2_000,
+ maxBytes: 32 * 1024 * 1024,
+ suspendedTtlMs: 6 * 60 * 60 * 1000,
+ maxEvictedIds: 20_000,
+ reapIntervalMs: 60_000,
+};
+
+export interface NewExecRecord {
+ accountKey: string;
+ sessionKey: string;
+ execCallId: string;
+ originalCallId: string;
+ source: string;
+ shape: "lite" | "classic";
+ state?: ExecState;
+ reasoningItems?: ResponsesItem[];
+ maxOutputTokens?: number;
+}
+
+function utf8Bytes(text: string): number {
+ return Buffer.byteLength(text, "utf8");
+}
+
+function outputBytes(output: ExecOutput): number {
+ let bytes = output.error ? utf8Bytes(output.error) : 0;
+ for (const part of output.parts) if (part.type === "text") bytes += utf8Bytes(part.text);
+ return bytes;
+}
+
+function recordBytes(record: ExecRecord): number {
+ let bytes = utf8Bytes(record.source);
+ for (const stored of record.outputs.values()) bytes += outputBytes(stored.output);
+ if (record.reasoningItems) bytes += utf8Bytes(JSON.stringify(record.reasoningItems));
+ return bytes;
+}
+
+function recordKey(accountKey: string, execCallId: string): string {
+ return `${accountKey}\0${execCallId}`;
+}
+
+function isLive(state: ExecState): boolean {
+ return state === "running" || state === "suspended";
+}
+
+/** A bounded FIFO set of ids. */
+class BoundedIdSet {
+ private readonly ids = new Set<string>();
+ constructor(private readonly max: number) {}
+ add(id: string): void {
+ this.ids.delete(id);
+ this.ids.add(id);
+ while (this.ids.size > this.max) {
+ const oldest = this.ids.values().next().value;
+ if (oldest === undefined) break;
+ this.ids.delete(oldest);
+ }
+ }
+ has(id: string): boolean {
+ return this.ids.has(id);
+ }
+ delete(id: string): void {
+ this.ids.delete(id);
+ }
+ get size(): number {
+ return this.ids.size;
+ }
+}
+
+export class ScriptStore {
+ private readonly records = new Map<string, ExecRecord>();
+ private readonly evicted: BoundedIdSet;
+ private readonly pins: BoundedIdSet;
+ private readonly limits: ScriptStoreLimits;
+ private readonly now: () => number;
+ private settledBytes = 0;
+ private reaper: ReturnType<typeof setInterval> | undefined;
+
+ constructor(opts: { limits?: Partial<ScriptStoreLimits>; now?: () => number } = {}) {
+ this.limits = { ...DEFAULT_SCRIPT_STORE_LIMITS, ...opts.limits };
+ this.now = opts.now ?? Date.now;
+ this.evicted = new BoundedIdSet(this.limits.maxEvictedIds);
+ this.pins = new BoundedIdSet(this.limits.maxEvictedIds);
+ }
+
+ // ─── records ────────────────────────────────────────────────────────
+
+ /** Create (or replace) the record for an exec. */
+ create(init: NewExecRecord): ExecRecord {
+ const key = recordKey(init.accountKey, init.execCallId);
+ const existing = this.records.get(key);
+ if (existing) this.remove(existing);
+ const now = this.now();
+ const record: ExecRecord = {
+ accountKey: init.accountKey,
+ sessionKey: init.sessionKey,
+ execCallId: init.execCallId,
+ originalCallId: init.originalCallId,
+ source: init.source,
+ shape: init.shape,
+ state: init.state ?? "running",
+ batches: [],
+ outputs: new Map(),
+ reasoningItems: init.reasoningItems,
+ maxOutputTokens: init.maxOutputTokens,
+ startedAt: now,
+ lastTouched: now,
+ bytes: 0,
+ };
+ record.bytes = recordBytes(record);
+ this.records.set(key, record);
+ this.evicted.delete(key);
+ if (!isLive(record.state)) {
+ this.settledBytes += record.bytes;
+ this.enforceCaps();
+ }
+ return record;
+ }
+
+ /**
+ * The record, touched. A suspended record whose runtime is gone (module
+ * poisoned, evicted by the live cap) is moved to `lost` first.
+ */
+ get(accountKey: string, execCallId: string): ExecRecord | undefined {
+ const record = this.records.get(recordKey(accountKey, execCallId));
+ if (!record) return undefined;
+ record.lastTouched = this.now();
+ if (record.state === "suspended" && (!record.runtime || !record.runtime.alive)) {
+ this.transition(record, "evict");
+ }
+ return record;
+ }
+
+ /** The record without touching it or checking its runtime. */
+ peek(accountKey: string, execCallId: string): ExecRecord | undefined {
+ return this.records.get(recordKey(accountKey, execCallId));
+ }
+
+ /** True when the record was evicted under the caps (not merely never seen). */
+ isEvicted(accountKey: string, execCallId: string): boolean {
+ return this.evicted.has(recordKey(accountKey, execCallId));
+ }
+
+ /** Every suspended record owned by `sessionKey`. */
+ suspendedOwnedBy(sessionKey: string): ExecRecord[] {
+ const out: ExecRecord[] = [];
+ for (const record of this.records.values()) {
+ if (record.state === "suspended" && record.sessionKey === sessionKey) out.push(record);
+ }
+ return out;
+ }
+
+ /**
+ * Apply `event`. An illegal transition is logged and coerced to `lost`
+ * (never thrown). Returns the new state.
+ */
+ transition(record: ExecRecord, event: ExecEvent): ExecState {
+ const from = record.state;
+ const legal = TRANSITIONS[from][event];
+ const to: ExecState = legal ?? "lost";
+ if (!legal) {
+ log(
+ `[CodeMode] exec ${record.execCallId}: illegal transition ${event} from ${from}; record coerced to lost`
+ );
+ }
+ if (!legal || ENDS_RUNTIME.has(event)) this.disposeRuntime(record);
+ const wasLive = isLive(from);
+ record.state = to;
+ record.lastTouched = this.now();
+ const nowLive = isLive(to);
+ if (wasLive && !nowLive) this.settledBytes += record.bytes;
+ else if (!wasLive && nowLive) this.settledBytes -= record.bytes;
+ if (!nowLive) this.enforceCaps();
+ return to;
+ }
+
+ /** Attach a runtime to a running record (the store disposes it on the ending transitions). */
+ attachRuntime(record: ExecRecord, runtime: ScriptRuntime): void {
+ if (record.runtime && record.runtime !== runtime) record.runtime.dispose();
+ record.runtime = runtime;
+ }
+
+ /** Store the reasoning items of the leg that produced the exec. */
+ setReasoning(record: ExecRecord, items: ResponsesItem[] | undefined): void {
+ this.rebytes(record, () => {
+ record.reasoningItems = items && items.length > 0 ? items : undefined;
+ });
+ }
+
+ /**
+ * Store `output` under `completionKey`. A tombstone never overwrites a `run`
+ * output for the same key.
+ */
+ storeOutput(
+ record: ExecRecord,
+ completionKey: string,
+ output: ExecOutput,
+ origin: StoredOutput["origin"],
+ sessionKey: string
+ ): void {
+ const existing = record.outputs.get(completionKey);
+ if (existing?.origin === "run" && origin === "tombstone") return;
+ this.rebytes(record, () => {
+ record.outputs.set(completionKey, { output, origin, sessionKey });
+ });
+ record.lastTouched = this.now();
+ if (!isLive(record.state)) this.enforceCaps();
+ }
+
+ /**
+ * The output to render for `completionKey`: a `run` output from any session
+ * (a function of source + results, so a fork with the same history renders it
+ * identically), else a tombstone stored by THIS session.
+ */
+ lookupOutput(
+ accountKey: string,
+ execCallId: string,
+ completionKey: string,
+ sessionKey: string
+ ): StoredOutput | undefined {
+ const record = this.records.get(recordKey(accountKey, execCallId));
+ const stored = record?.outputs.get(completionKey);
+ if (!stored) return undefined;
+ if (stored.origin === "run" || stored.sessionKey === sessionKey) {
+ if (record) record.lastTouched = this.now();
+ return stored;
+ }
+ return undefined;
+ }
+
+ // ─── pins ───────────────────────────────────────────────────────────
+
+ /** This session relayed an exec: keep it in code mode while its arm stays OAuth. */
+ pin(sessionKey: string): void {
+ this.pins.add(sessionKey);
+ }
+
+ isPinned(sessionKey: string): boolean {
+ return this.pins.has(sessionKey);
+ }
+
+ // ─── caps and reaping ───────────────────────────────────────────────
+
+ /** Expire idle suspended records and enforce the caps. */
+ reap(): void {
+ const now = this.now();
+ for (const record of [...this.records.values()]) {
+ if (record.state === "suspended" && now - record.lastTouched > this.limits.suspendedTtlMs) {
+ this.transition(record, "expire");
+ }
+ }
+ this.enforceCaps();
+ }
+
+ /** Start the 60 s reaper (idempotent; unref'd so it never holds the process). */
+ startReaper(): void {
+ if (this.reaper) return;
+ this.reaper = setInterval(() => {
+ try {
+ this.reap();
+ } catch (err) {
+ log(`[CodeMode] script store reaper failed: ${err}`);
+ }
+ }, this.limits.reapIntervalMs);
+ this.reaper.unref?.();
+ }
+
+ stopReaper(): void {
+ if (this.reaper) clearInterval(this.reaper);
+ this.reaper = undefined;
+ }
+
+ /** Records currently held. */
+ get size(): number {
+ return this.records.size;
+ }
+
+ /** Counted bytes of settled records (the 32 MiB cap applies to this). */
+ get bytes(): number {
+ return this.settledBytes;
+ }
+
+ /** Drop everything, disposing every runtime (tests; a process reset). */
+ clear(): void {
+ for (const record of this.records.values()) this.disposeRuntime(record);
+ this.records.clear();
+ this.settledBytes = 0;
+ }
+
+ private settledCount(): number {
+ let n = 0;
+ for (const record of this.records.values()) if (!isLive(record.state)) n++;
+ return n;
+ }
+
+ private enforceCaps(): void {
+ let count = this.settledCount();
+ if (count <= this.limits.maxRecords && this.settledBytes <= this.limits.maxBytes) return;
+ const settled = [...this.records.values()]
+ .filter((r) => !isLive(r.state))
+ .sort((a, b) => a.lastTouched - b.lastTouched);
+ for (const record of settled) {
+ if (count <= this.limits.maxRecords && this.settledBytes <= this.limits.maxBytes) break;
+ this.remove(record);
+ this.evicted.add(recordKey(record.accountKey, record.execCallId));
+ count--;
+ }
+ log(
+ `[CodeMode] script store over its cap; evicted to ${count} record(s), ${this.settledBytes} bytes`
+ );
+ }
+
+ private remove(record: ExecRecord): void {
+ this.disposeRuntime(record);
+ this.records.delete(recordKey(record.accountKey, record.execCallId));
+ if (!isLive(record.state)) this.settledBytes -= record.bytes;
+ }
+
+ private rebytes(record: ExecRecord, mutate: () => void): void {
+ const before = record.bytes;
+ mutate();
+ record.bytes = recordBytes(record);
+ if (!isLive(record.state)) this.settledBytes += record.bytes - before;
+ }
+
+ private disposeRuntime(record: ExecRecord): void {
+ const runtime = record.runtime;
+ record.runtime = undefined;
+ if (!runtime) return;
+ try {
+ runtime.dispose();
+ } catch (err) {
+ log(`[CodeMode] exec ${record.execCallId}: disposing its runtime failed: ${err}`);
+ }
+ }
+}
diff --git a/packages/cli/src/code-mode/stores.ts b/packages/cli/src/code-mode/stores.ts
new file mode 100644
index 00000000..d83e3708
--- /dev/null
+++ b/packages/cli/src/code-mode/stores.ts
@@ -0,0 +1,33 @@
+/**
+ * The process-wide code-mode stores. Created on first use (only a code-mode
+ * request reaches here), process memory only: a claudish restart loses them,
+ * and the input builder's restart rendering covers that.
+ */
+
+import { ScriptStore } from "./script-store.js";
+import { TurnRecords } from "./turn-records.js";
+
+export interface CodeModeStores {
+ scripts: ScriptStore;
+ turns: TurnRecords;
+}
+
+let stores: CodeModeStores | undefined;
+
+/** The process's stores; the script store's reaper starts with them. */
+export function getCodeModeStores(): CodeModeStores {
+ if (!stores) {
+ stores = { scripts: new ScriptStore(), turns: new TurnRecords() };
+ stores.scripts.startReaper();
+ }
+ return stores;
+}
+
+/** Drop the process's stores, disposing every runtime (tests; a process reset). */
+export function resetCodeModeStores(): void {
+ if (!stores) return;
+ stores.scripts.stopReaper();
+ stores.scripts.clear();
+ stores.turns.clear();
+ stores = undefined;
+}
diff --git a/packages/cli/src/code-mode/turn-records.ts b/packages/cli/src/code-mode/turn-records.ts
new file mode 100644
index 00000000..8fcbb7f8
--- /dev/null
+++ b/packages/cli/src/code-mode/turn-records.ts
@@ -0,0 +1,177 @@
+/**
+ * Turn records: the exact ordered Responses items of one downstream Claude
+ * message across all its upstream legs — reasoning, commentary messages,
+ * interstitial `custom_tool_call` + output pairs, the final leg's preceding
+ * items — so the next request replays them verbatim instead of the lossy view
+ * Claude Code's message keeps. A record ENDS BEFORE the final
+ * `custom_tool_call` when the message ended on nested calls: that call belongs
+ * to its exec group, which the input builder emits exactly once.
+ *
+ * Keyed by `(sessionKey, anchor)`. The anchor is the message's first tool_use
+ * id when it has one, else a hash of the session, the message it answered and
+ * its text blocks (`turnAnchorFor`), so two turns ending in the same short
+ * text after different prompts never share an anchor.
+ *
+ * Byte ceiling the model cannot raise (architecture §5.8): ≤ 2,000 records AND
+ * ≤ 32 MiB, counted as the UTF-8 length of `JSON.stringify(items)` at insert; a
+ * single record over 8 MiB is never stored (logged). Eviction is LRU by last
+ * render; an evicted anchor goes to a bounded FIFO set so the input builder
+ * renders that message from Claude Code's view, byte-stably.
+ */
+
+import { createHash } from "node:crypto";
+import { log } from "../logger.js";
+import { canonicalJson } from "./hashes.js";
+import type { ClaudeMessage, ResponsesItem } from "./types.js";
+
+export interface TurnRecord {
+ sessionKey: string;
+ anchor: string;
+ items: ResponsesItem[];
+ bytes: number;
+}
+
+export interface TurnRecordLimits {
+ maxRecords: number;
+ maxBytes: number;
+ maxRecordBytes: number;
+ maxEvictedIds: number;
+}
+
+export const DEFAULT_TURN_RECORD_LIMITS: TurnRecordLimits = {
+ maxRecords: 2_000,
+ maxBytes: 32 * 1024 * 1024,
+ maxRecordBytes: 8 * 1024 * 1024,
+ maxEvictedIds: 20_000,
+};
+
+function sha256Hex(text: string): string {
+ return createHash("sha256").update(text).digest("hex");
+}
+
+function recordKey(sessionKey: string, anchor: string): string {
+ return `${sessionKey}\0${anchor}`;
+}
+
+/**
+ * The anchor of an assistant message: its first tool_use id, else
+ * `sha256(sessionKey ‖ sha256(canonical previous message) ‖ text blocks
+ * trimmed and joined with "\n")`. `previousMessage` is the user message the
+ * assistant message answered — the last message of the request that produced
+ * it, which precedes it in every later history.
+ */
+export function turnAnchorFor(
+ sessionKey: string,
+ message: ClaudeMessage,
+ previousMessage: ClaudeMessage | undefined
+): string {
+ const blocks = Array.isArray(message.content) ? message.content : [];
+ for (const block of blocks) {
+ if (block.type === "tool_use" && typeof block.id === "string" && block.id) return block.id;
+ }
+ const texts =
+ typeof message.content === "string"
+ ? [message.content.trim()]
+ : blocks
+ .filter((b) => b.type === "text" && typeof b.text === "string")
+ .map((b) => (b.text as string).trim());
+ const previous = previousMessage ? sha256Hex(canonicalJson(previousMessage)) : "";
+ return sha256Hex(`${sessionKey}\0${previous}\0${texts.join("\n")}`);
+}
+
+export class TurnRecords {
+ /** Map order is LRU order: a render re-inserts the record at the end. */
+ private readonly records = new Map<string, TurnRecord>();
+ private readonly evicted = new Set<string>();
+ private readonly limits: TurnRecordLimits;
+ private totalBytes = 0;
+
+ constructor(opts: { limits?: Partial<TurnRecordLimits> } = {}) {
+ this.limits = { ...DEFAULT_TURN_RECORD_LIMITS, ...opts.limits };
+ }
+
+ /**
+ * Store the items of one downstream message. False (logged) when the record
+ * alone exceeds the per-record ceiling; it is then never stored.
+ */
+ put(sessionKey: string, anchor: string, items: ResponsesItem[]): boolean {
+ const bytes = Buffer.byteLength(JSON.stringify(items), "utf8");
+ if (bytes > this.limits.maxRecordBytes) {
+ log(
+ `[CodeMode] turn record ${anchor.slice(0, 16)} is ${bytes} bytes, over the ${this.limits.maxRecordBytes}-byte ceiling; not stored`
+ );
+ return false;
+ }
+ const key = recordKey(sessionKey, anchor);
+ const existing = this.records.get(key);
+ if (existing) {
+ this.records.delete(key);
+ this.totalBytes -= existing.bytes;
+ }
+ this.records.set(key, { sessionKey, anchor, items, bytes });
+ this.totalBytes += bytes;
+ this.evicted.delete(key);
+ this.enforceCaps();
+ return true;
+ }
+
+ /** The record for a message (a render: refreshes its LRU position). */
+ get(sessionKey: string, anchor: string): TurnRecord | undefined {
+ const key = recordKey(sessionKey, anchor);
+ const record = this.records.get(key);
+ if (!record) return undefined;
+ this.records.delete(key);
+ this.records.set(key, record);
+ return record;
+ }
+
+ /** True when the record was evicted under the caps. */
+ isEvicted(sessionKey: string, anchor: string): boolean {
+ return this.evicted.has(recordKey(sessionKey, anchor));
+ }
+
+ get size(): number {
+ return this.records.size;
+ }
+
+ get bytes(): number {
+ return this.totalBytes;
+ }
+
+ clear(): void {
+ this.records.clear();
+ this.evicted.clear();
+ this.totalBytes = 0;
+ }
+
+ private enforceCaps(): void {
+ let evictedNow = 0;
+ while (
+ this.records.size > this.limits.maxRecords ||
+ (this.totalBytes > this.limits.maxBytes && this.records.size > 0)
+ ) {
+ const oldestKey = this.records.keys().next().value;
+ if (oldestKey === undefined) break;
+ const oldest = this.records.get(oldestKey);
+ this.records.delete(oldestKey);
+ if (oldest) this.totalBytes -= oldest.bytes;
+ this.markEvicted(oldestKey);
+ evictedNow++;
+ }
+ if (evictedNow > 0) {
+ log(
+ `[CodeMode] turn records over their cap; evicted ${evictedNow} (now ${this.records.size}, ${this.totalBytes} bytes)`
+ );
+ }
+ }
+
+ private markEvicted(key: string): void {
+ this.evicted.delete(key);
+ this.evicted.add(key);
+ while (this.evicted.size > this.limits.maxEvictedIds) {
+ const oldest = this.evicted.values().next().value;
+ if (oldest === undefined) break;
+ this.evicted.delete(oldest);
+ }
+ }
+}
diff --git a/packages/cli/src/code-mode/types.ts b/packages/cli/src/code-mode/types.ts
new file mode 100644
index 00000000..30669435
--- /dev/null
+++ b/packages/cli/src/code-mode/types.ts
@@ -0,0 +1,32 @@
+/**
+ * Shapes shared by the code-mode modules: Responses `input` items and the
+ * parts of Claude Code's `/v1/messages` body the input builder and the stores
+ * read. Deliberately loose: both sides are external wire formats, and code mode
+ * only ever reads the fields named here.
+ */
+
+/** One Responses `input` item (message, reasoning, custom_tool_call, custom_tool_call_output, …). */
+export interface ResponsesItem {
+ type: string;
+ [field: string]: unknown;
+}
+
+/** A content block of a Claude Code message. */
+export interface ClaudeContentBlock {
+ type: string;
+ text?: string;
+ id?: string;
+ name?: string;
+ input?: unknown;
+ tool_use_id?: string;
+ content?: unknown;
+ is_error?: boolean;
+ source?: unknown;
+ [field: string]: unknown;
+}
+
+/** One message of `claudeRequest.messages`. */
+export interface ClaudeMessage {
+ role: string;
+ content: string | ClaudeContentBlock[];
+}