tumwater 0.2.0 → 0.4.0

package/dist/src/agent/codex/codex-patch-paths.js

@@ -0,0 +1,36 @@
+/** List the paths an `apply_patch` text writes, from the patch text alone (plans/
+ * codex-write-guard.md "The hook (parts 1–2)"; PLANS.md "Write guard on Codex, part 1/9").
+ * Pure: no filesystem, no imports beyond node built-ins, so a later part can call it from the
+ * hook without dragging in a registry or subprocess.
+ *
+ * Codex's PreToolUse payload carries the patch text, not a path, and a patch is applied even
+ * when it is truncated or its `*** Begin Patch` / `*** End Patch` markers are missing — so this
+ * scans every line, marker or not, and trusts only lines that begin at column 0 with a header.
+ * A hunk line (`+`, `-`, a space, `@@`) never counts as a header even when its text reads like
+ * one, because a hunk prefix shifts `*** ` off column 0. Paths are kept as written; the caller
+ * resolves relative ones against the run's directory. */
+/** Headers that name a path the patch writes, in the order a line may spell them. */
+const HEADERS = [
+    "*** Add File: ",
+    "*** Delete File: ",
+    "*** Update File: ",
+    "*** Move to: ",
+];
+/** The paths an `apply_patch` text writes, in first-appearance order, without duplicates. */
+export function patchWritePaths(patch) {
+    const seen = new Set();
+    const paths = [];
+    for (const line of patch.split("\n")) {
+        for (const header of HEADERS) {
+            if (line.startsWith(header)) {
+                const path = line.slice(header.length).replace(/[\s\r]+$/, "");
+                if (path !== "" && !seen.has(path)) {
+                    seen.add(path);
+                    paths.push(path);
+                }
+                break;
+            }
+        }
+    }
+    return paths;
+}

package/dist/src/agent/codex/codex-rollout.js

@@ -0,0 +1,179 @@
+/** The codex adapter's rollout reader (plans/codex-backend.md "The rollout read that
+ * completes it"). `codex exec --json`'s stream reports usage only once, at the end, counting
+ * the WHOLE thread (finding 4) — a resume would otherwise charge its earlier run to the follow-
+ * up. The authoritative per-run figures live in `$CODEX_HOME/sessions/…/rollout-*-<id>.jsonl`,
+ * Codex's own JSONL record of a session, where each run's `task_started` .. `task_complete`
+ * block carries its own `token_usage_record`, `token_count` (the rate limits) and
+ * `turn_context` (the model that actually ran). This module reads just that block: what the
+ * stream lacks — this run's own usage, the billing and the two usage windows.
+ *
+ * Pure over text (plus one filesystem walk for `findRollout`): no spawn, no billing math, no
+ * session state. Part 7/9's adapter wires the lines into the canonical stream in `afterRun`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isJsonObject, nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
+import { windowTypeName } from "./codex-stream.js";
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function finite(value) {
+    return nonNegativeNumber(value, undefined);
+}
+/** The rate-limit status of one window: `rejected` when the account hit it outright,
+ * `allowed_warning` when it is at or past 90% full, else `allowed` (design §5, decision 7). */
+function windowStatus(windowType, rateLimitReachedType, usedPercent) {
+    if (rateLimitReachedType === windowType)
+        return "rejected";
+    if (usedPercent !== undefined && usedPercent >= 100)
+        return "rejected";
+    if (usedPercent !== undefined && usedPercent >= 90)
+        return "allowed_warning";
+    return "allowed";
+}
+/** Read the records of ONE turn out of a rollout's text. A rollout is one file per thread that
+ * appends a new `task_started` block per run, so the adapter's `afterRun` read (which knows
+ * only the thread id that names the file, never a turn id) reads the LAST block — everything
+ * after the last `task_started`. `sinceTurnStart` (optional) selects a specific turn's block
+ * instead, which pins per-turn isolation: the thread total hides a resume's own figures
+ * (finding 4). `requestedModel` is the `-m` tumwater passed; a turn whose `turn_context.model`
+ * differs reports the switch. */
+export function rolloutLines(text, opts) {
+    const { sinceTurnStart, requestedModel } = opts;
+    let currentTurn;
+    let sawTurn = false;
+    let lastUsage;
+    let lastRateLimits;
+    let model;
+    let planType;
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        const parsed = parseJsonObject(line);
+        if (!parsed)
+            continue; // a torn or foreign line belongs to no turn
+        const payload = objectOrEmpty(parsed.payload);
+        // `task_started`, `task_complete` and `token_count` come wrapped in an `event_msg` whose
+        // `payload.type` discriminates; `turn_context` and `token_usage_record` name themselves in
+        // the outer `type`. Read either.
+        const ptype = str(parsed.type) === "event_msg" ? str(payload.type) : str(parsed.type);
+        if (ptype === "task_started") {
+            currentTurn = str(payload.turn_id);
+            // Each new task_started begins a fresh turn (a resume appends a second run to the same
+            // file), so the collectors restart at the block we are reading. With no turn id (the
+            // adapter's read) every task_started restarts them and the last block wins; with one,
+            // only the requested turn's does.
+            if (sinceTurnStart === undefined || currentTurn === sinceTurnStart) {
+                sawTurn = true;
+                lastUsage = undefined;
+                lastRateLimits = undefined;
+                model = undefined;
+                planType = undefined;
+            }
+            continue;
+        }
+        if (sinceTurnStart !== undefined && currentTurn !== sinceTurnStart)
+            continue;
+        switch (ptype) {
+            case "turn_context":
+                if (model === undefined)
+                    model = str(payload.model);
+                break;
+            case "token_usage_record": {
+                const turnUsage = objectOrEmpty(payload.turn_token_usage);
+                if (isJsonObject(turnUsage) && (turnUsage.input_tokens !== undefined || turnUsage.output_tokens !== undefined)) {
+                    lastUsage = turnUsage;
+                }
+                break;
+            }
+            case "token_count": {
+                const rateLimits = objectOrEmpty(payload.rate_limits);
+                lastRateLimits = rateLimits;
+                const plan = str(rateLimits.plan_type);
+                if (plan !== undefined)
+                    planType = plan;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // No matching task_started, or the turn's usage record is missing or malformed (a truncated
+    // or torn file): there is no reading. (currentTurn will have moved on to a later run's
+    // task_started in a resume-shared file; sawTurn — not currentTurn — is the real signal.)
+    if (!sawTurn || !isJsonObject(lastUsage)) {
+        return { lines: [] };
+    }
+    const lines = [];
+    const input = finite(lastUsage.input_tokens) ?? 0;
+    const cacheRead = finite(lastUsage.cached_input_tokens) ?? 0;
+    lines.push(JSON.stringify({
+        type: "run_usage",
+        input: Math.max(0, input - cacheRead),
+        output: finite(lastUsage.output_tokens) ?? 0,
+        cacheRead,
+        cacheWrite: finite(lastUsage.cache_write_input_tokens) ?? 0,
+    }));
+    if (planType !== undefined) {
+        // A reading with a plan_type bills on the subscription (finding 5; API-key login is
+        // refused, decision 5).
+        lines.push(JSON.stringify({ type: "billing", billing: "subscription" }));
+    }
+    // Two windows when present: the primary (5 h) and the secondary (weekly). A killed run's
+    // rollout has a token_usage_record but no token_count, so it yields run_usage with no
+    // rate_limit (finding 23).
+    if (lastRateLimits !== undefined) {
+        const reached = str(lastRateLimits.rate_limit_reached_type);
+        for (const key of ["primary", "secondary"]) {
+            const windowRaw = lastRateLimits[key];
+            if (!isJsonObject(windowRaw))
+                continue;
+            const minutes = finite(windowRaw.window_minutes);
+            if (minutes === undefined)
+                continue;
+            const typeName = windowTypeName(minutes);
+            const usedPercent = finite(windowRaw.used_percent);
+            lines.push(JSON.stringify({
+                type: "rate_limit",
+                rateLimitType: typeName,
+                status: windowStatus(typeName, reached, usedPercent),
+                ...(usedPercent !== undefined ? { utilization: usedPercent / 100 } : {}),
+                ...(finite(windowRaw.resets_at) !== undefined ? { resetsAt: finite(windowRaw.resets_at) } : {}),
+            }));
+        }
+    }
+    const switchedTo = model !== undefined && requestedModel !== undefined && model !== requestedModel ? model : undefined;
+    return { lines, ...(switchedTo !== undefined ? { switchedTo } : {}) };
+}
+/** Locate the rollout file of `$CODEX_HOME` that names the session `id`: the first
+ * `sessions/…/rollout-*-<id>.jsonl` under `home`, or null. It takes no start date and does no
+ * date math — the id match alone decides (finding 5: Codex's rollout name carries local time,
+ * so a UTC-derived bound can miss the file; the sessions tree is one directory per active day,
+ * so the walk stays small). */
+export function findRollout(home, id) {
+    const sessionsRoot = path.join(home, "sessions");
+    if (!fs.existsSync(sessionsRoot))
+        return null;
+    const suffix = `-${id}.jsonl`;
+    const stack = [sessionsRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // an unreadable dir is simply no match, never a failure
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(suffix)) {
+                return full;
+            }
+        }
+    }
+    return null;
+}

package/dist/src/agent/codex/codex-stream.js

@@ -0,0 +1,404 @@
+/** The codex adapter's native-to-canonical stream translator (plans/codex-backend.md "The
+ * stream translator and the rollout read that completes it"). `codex exec --json` emits one
+ * JSON object per line whose vocabulary is nothing like pi's: `thread.started`, then item
+ * start/completed events (`agent_message`, `command_execution`, `file_change`, `error`), and
+ * finally `turn.completed` or `turn.failed`. Rather than teach ~fifteen readers a third
+ * dialect, every native line is translated here into pi's vocabulary — the canonical stream —
+ * so `PiStreamParser`, the raw log, the transcript, progress, and the GUI all stay unchanged.
+ *
+ * Pure translation: no spawn, no backend registration, no config. The factory keeps per-run
+ * state (the open tool calls, the turn's usage fallback, the unmapped native types seen), so
+ * call it once per run. Unmapped native types, the distinct text of `error` items, and a
+ * command abandoned at the end of its turn are recorded once each on the seam's optional
+ * `warnings()` — src/agent/run-agent.ts forwards each as an `agent_unknown_event` warning
+ * after the run. `sessionId()` reports the thread id once `thread.started` has named it.
+ */
+import { nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
+import { boundText, outputLimits } from "../../pi-extension/bounded-output.js";
+import { secondsUntil } from "../../text/datetime.js";
+/** How codex wraps every shell command — the prefix to strip (with its quoting) so the
+ * canonical `bash` call carries the model's own command, which suite-rerun detection matches. */
+const SHELL_WRAPPER = /^\/(?:bin\/)?(?:zsh|bash) -lc '(.*)'$/s;
+/** A top-level `error` line that is Codex's own WebSocket/HTTPS reconnect ("Reconnecting...
+ * n/m (reason)") — canonical `auto_retry_start`. */
+const RECONNECT = /^Reconnecting\.\.\. (\d+)\/(\d+) /;
+/** The item types dropped silently, with no canonical event and no `warnings()` entry
+ * (design §5's `item.*` row): `todo_list` and `web_search`. */
+const DROPPED_ITEM_TYPES = new Set(["todo_list", "web_search"]);
+/** HTTP status classes that mean a transient backend failure (shared with the claude and
+ * codex classifiers' reading of `codex exec`'s JSON error). */
+const SERVER_STATUS = new Set([500, 502, 503, 504, 529]);
+/** Strip codex's `/bin/zsh -lc '<cmd>'` (or `bash -lc`) wrapper and its quoting, returning
+ * the model's own command — the argument suite-rerun detection matches. Passes a command the
+ * capture did not wrap through unchanged. */
+function innerCommand(command) {
+    const m = SHELL_WRAPPER.exec(command);
+    return m ? m[1] : command;
+}
+/** The canonical window type name for a window-minutes value (shared with the rollout reader
+ * in codex-rollout.ts): Codex's 300-minute window reads as `five_hour`, its 10080-minute as
+ * `seven_day`, so a reserve reads the same on claude and codex (decision 7). */
+export function windowTypeName(windowMinutes) {
+    if (windowMinutes === 300)
+        return "five_hour";
+    if (windowMinutes === 10080)
+        return "seven_day";
+    return `${windowMinutes}_minute`;
+}
+/** One codex `error` item's distinct message → a run warning; repeated identical messages are
+ * warned once (finding 11). */
+/** How a `turn.failed` error message classifies into the canonical `tumwaterKind` (and, for a
+ * transient backend, its kind), trusted by `PiStreamParser` before its text regexes. The inner
+ * `message` is a JSON string carrying `status` and `error.type` / `error.code` (finding 11).
+ * Returns the canonical lines to emit beside the closing `message_end`: a rejected rate-limit
+ * reading when the error names a used-up window. */
+function classifyTurnFailed(parsed) {
+    const kind = {};
+    const error = objectOrEmpty(parsed.error);
+    const code = typeof error.code === "string" ? error.code : undefined;
+    const errType = typeof error.type === "string" ? error.type : undefined;
+    const message = typeof error.message === "string" ? error.message : typeof parsed.message === "string" ? parsed.message : undefined;
+    kind.errorMessage = message;
+    const status = nonNegativeNumber(parsed.status, undefined);
+    // The context-window signal is tested BEFORE the generic 400 `invalid_request_error`
+    // branch (as claude's classifyResult tests "prompt is too long" before CONFIG_STATUS): a
+    // `context_window_exceeded` code, or a 400 whose message names the context window, is
+    // `contextExceeded`, never `configError`.
+    const namesContextWindow = (t) => t !== undefined &&
+        /context window|context length|too long|exceeds? (the )?(model'?s )?context|prompt is too long/i.test(t);
+    if (code === "context_window_exceeded" || (status === 400 && errType === "invalid_request_error" && namesContextWindow(message))) {
+        kind.kind = "contextExceeded";
+        return kind;
+    }
+    if (code === "usage_limit_reached" || code === "rate_limit_exceeded" || status === 429) {
+        // Which window the account hit, from the error's own `rate_limit_reached_type` (else the
+        // five-hour window, the one Plus exhausts first). The rejected reading's wait comes from
+        // `resets_at`.
+        const minutes = nonNegativeNumber(parsed.rate_limit_reached_type, undefined);
+        const named = typeof parsed.rate_limit_reached_type === "string" ? parsed.rate_limit_reached_type : undefined;
+        const resetsAt = nonNegativeNumber(parsed.resets_at, undefined);
+        // secondsUntil folds the unix-seconds resets stamp (×1000 to epoch-ms), clamped at 0.
+        const retryAfter = resetsAt === undefined ? undefined : secondsUntil(resetsAt * 1000, Date.now());
+        kind.kind = "transientRateLimit";
+        kind.rateLimit = {
+            type: "rate_limit",
+            rateLimitType: typeof named === "string" && /_minute$|_hour$|_day$/.test(named)
+                ? named
+                : windowTypeName(minutes ?? 300),
+            status: "rejected",
+            utilization: 1,
+            ...(resetsAt !== undefined ? { resetsAt } : {}),
+            ...(retryAfter !== undefined ? { retryAfterSeconds: retryAfter } : {}),
+        };
+        return kind;
+    }
+    if (code === "usage_not_included") {
+        kind.kind = "configError";
+        return kind;
+    }
+    if (status !== undefined && SERVER_STATUS.has(status)) {
+        kind.kind = "transientBackend";
+        kind.backendKind = "server";
+        return kind;
+    }
+    // A refresh-token failure and an absent/invalid login are permanent config errors, which
+    // the doctor names with the login command (design §5).
+    if (/refresh_token_reused|invalidated refresh token/i.test(message ?? "")) {
+        kind.kind = "configError";
+        return kind;
+    }
+    if (status === 401) {
+        kind.kind = "configError";
+        return kind;
+    }
+    if (status === 400 && errType === "invalid_request_error") {
+        // A 400 `invalid_request_error` names the model as unsupported on a ChatGPT account.
+        kind.kind = "configError";
+        return kind;
+    }
+    return kind;
+}
+/** Build a fresh per-run codex translator. `cwd` (optional) lands on the canonical `session`
+ * event (design §5's `session {id, cwd}`) so part 7/9's adapter can stamp the run's own
+ * directory; when omitted the session carries no `cwd`, like the opencode translator. */
+export function codexTranslator(opts = {}) {
+    const bashLimit = outputLimits(opts.contextWindow).bash;
+    const cwd = opts.cwd;
+    let sessionIdValue;
+    let sawTurnCompleted = false;
+    let sawTurnFailed = false;
+    /** Tool calls open on this run, keyed by the item id that started them: command_execution
+     * and file_change items. A call still open when the turn ends was abandoned (finding 19).
+     * The value is the item type, so the abandonment close can name a command vs an edit. */
+    const openCalls = new Map();
+    let warnedAbandoned = false;
+    /** The last non-reconnecting top-level `error` message, held as the fallback text for a
+     * following `turn.failed` whose own message is absent (design §5). */
+    let pendingFailureText;
+    let turnUsage;
+    const seenEvents = new Set();
+    const seenItems = new Set();
+    const warnings = new Set();
+    const recordEvent = (type) => {
+        if (seenEvents.has(type))
+            return;
+        seenEvents.add(type);
+        warnings.add(type);
+    };
+    const recordItem = (item) => {
+        const key = `item:${typeof item.type === "string" ? item.type : "unknown"}`;
+        if (seenItems.has(key))
+            return;
+        seenItems.add(key);
+        warnings.add(key);
+    };
+    /** Record one distinct `error` item message as a run warning (never a failure). */
+    const recordErrorItem = (message) => {
+        if (warnings.has(message))
+            return;
+        warnings.add(message);
+    };
+    /** Close every still-open tool call as abandoned (the turn ended while they ran, finding
+     * 19): the command's open `sleep` never completed. Returns the canonical close lines.
+     * The `codex_command_abandoned` warning is recorded only when an open `command_execution`
+     * was actually closed (design §5), so a clean run's `warnings()` stays empty and a
+     * file_change abandoned on its own does not claim a command was. */
+    const abandonOpenCalls = () => {
+        const out = [];
+        let abandonedCommand = false;
+        for (const [id, type] of openCalls) {
+            openCalls.delete(id);
+            if (type === "command_execution")
+                abandonedCommand = true;
+            out.push(JSON.stringify({
+                type: "tool_execution_end",
+                toolCallId: id,
+                isError: true,
+                ...(type === "command_execution"
+                    ? { result: "abandoned: the run ended while this command was still running" }
+                    : {}),
+            }));
+        }
+        if (abandonedCommand && !warnedAbandoned) {
+            warnedAbandoned = true;
+            warnings.add("codex_command_abandoned");
+        }
+        return out;
+    };
+    const translate = (line) => {
+        const parsed = parseJsonObject(line);
+        if (!parsed)
+            return []; // Non-JSON noise on stdout; ignore, as pi's parser does.
+        const event = parsed;
+        const type = typeof event.type === "string" ? event.type : "unknown";
+        const out = [];
+        switch (type) {
+            case "thread.started": {
+                const id = typeof event.thread_id === "string" ? event.thread_id : undefined;
+                if (id === undefined) {
+                    recordEvent(type);
+                    return [];
+                }
+                sessionIdValue = id;
+                out.push(JSON.stringify({
+                    type: "session",
+                    id,
+                    ...(cwd !== undefined ? { cwd } : {}),
+                }));
+                out.push(JSON.stringify({ type: "agent_start" }));
+                return out;
+            }
+            case "turn.started":
+                return [];
+            case "turn.completed": {
+                sawTurnCompleted = true;
+                const usage = objectOrEmpty(event.usage);
+                turnUsage =
+                    usage.input_tokens !== undefined || usage.output_tokens !== undefined
+                        ? {
+                            input: nonNegativeNumber(usage.input_tokens, 0),
+                            cacheRead: nonNegativeNumber(usage.cached_input_tokens, 0),
+                            cacheWrite: nonNegativeNumber(usage.cache_write_input_tokens, 0),
+                            output: nonNegativeNumber(usage.output_tokens, 0),
+                        }
+                        : undefined;
+                return abandonOpenCalls();
+            }
+            case "turn.failed": {
+                sawTurnFailed = true;
+                // The error message is itself a JSON string (finding 11); fall back to the held
+                // top-level error text when it is not.
+                const raw = typeof event.error === "object" && event.error !== null && !Array.isArray(event.error)
+                    ? event.error.message
+                    : undefined;
+                const inner = typeof raw === "string" ? parseJsonObject(raw) : undefined;
+                const cls = inner ? classifyTurnFailed(inner) : {};
+                const errorMessage = cls.errorMessage ?? (typeof raw === "string" ? raw : pendingFailureText);
+                const closes = abandonOpenCalls();
+                const message = { role: "assistant", content: [], stopReason: "error" };
+                if (errorMessage !== undefined)
+                    message.errorMessage = errorMessage;
+                const end = {
+                    type: "message_end",
+                    message,
+                    ...(cls.kind !== undefined ? { tumwaterKind: cls.kind } : {}),
+                    ...(cls.backendKind !== undefined ? { backendKind: cls.backendKind } : {}),
+                };
+                if (cls.kind === "transientRateLimit" && typeof cls.rateLimit?.retryAfterSeconds === "number")
+                    end.retryAfterSeconds = cls.rateLimit.retryAfterSeconds;
+                return [...(cls.rateLimit !== undefined ? [JSON.stringify(cls.rateLimit)] : []), ...closes, JSON.stringify(end)];
+            }
+            case "error": {
+                const message = typeof event.message === "string" ? event.message : undefined;
+                const reconnect = message === undefined ? undefined : RECONNECT.exec(message);
+                if (reconnect) {
+                    return [
+                        JSON.stringify({
+                            type: "auto_retry_start",
+                            attempt: Number(reconnect[1]),
+                            maxAttempts: Number(reconnect[2]),
+                            errorMessage: message,
+                        }),
+                    ];
+                }
+                // Other top-level `error` lines are not fatal (design §5): held as the fallback text
+                // for a following `turn.failed`.
+                if (message !== undefined)
+                    pendingFailureText = message;
+                return [];
+            }
+            case "item.started":
+            case "item.completed": {
+                const item = objectOrEmpty(event.item);
+                const itemType = typeof item.type === "string" ? item.type : "unknown";
+                const started = type === "item.started";
+                if (itemType === "command_execution") {
+                    const command = typeof item.command === "string" ? item.command : "";
+                    if (started) {
+                        const id = typeof item.id === "string" ? item.id : `cmd-${openCalls.size}`;
+                        openCalls.set(id, "command_execution");
+                        const inner = innerCommand(command);
+                        out.push(JSON.stringify({
+                            type: "message_end",
+                            message: {
+                                role: "assistant",
+                                content: [{ type: "toolCall", id, name: "bash", arguments: { command: inner } }],
+                            },
+                        }));
+                        out.push(JSON.stringify({
+                            type: "tool_execution_start",
+                            toolCallId: id,
+                            toolName: "bash",
+                            args: { command: inner },
+                        }));
+                    }
+                    else {
+                        const id = typeof item.id === "string" ? item.id : "";
+                        openCalls.delete(id);
+                        const aggregated = typeof item.aggregated_output === "string" ? item.aggregated_output : "";
+                        const exitCode = nonNegativeNumber(item.exit_code, undefined);
+                        out.push(JSON.stringify({
+                            type: "tool_execution_end",
+                            toolCallId: id,
+                            isError: exitCode !== undefined ? exitCode !== 0 : item.status !== "completed",
+                            result: boundText(aggregated, bashLimit),
+                        }));
+                    }
+                    return out;
+                }
+                if (itemType === "file_change") {
+                    const changes = Array.isArray(item.changes) ? item.changes.filter((c) => typeof c === "object" && c !== null) : [];
+                    const id = typeof item.id === "string" ? item.id : "";
+                    if (!started) {
+                        const isError = typeof item.status === "string" && item.status !== "completed";
+                        for (let i = 0; i < changes.length; i++) {
+                            const callId = `${id}-${i}`;
+                            openCalls.delete(callId);
+                            out.push(JSON.stringify({ type: "tool_execution_end", toolCallId: callId, isError }));
+                        }
+                        return out;
+                    }
+                    const content = changes.map((c, i) => ({
+                        type: "toolCall",
+                        id: `${id}-${i}`,
+                        name: "edit",
+                        arguments: {
+                            path: typeof c.path === "string" ? c.path : undefined,
+                            kind: typeof c.kind === "string" ? c.kind : undefined,
+                        },
+                    }));
+                    if (content.length === 0)
+                        return out; // no changes to mirror, nothing else to emit
+                    out.push(JSON.stringify({ type: "message_end", message: { role: "assistant", content } }));
+                    for (let i = 0; i < content.length; i++) {
+                        const callId = `${id}-${i}`;
+                        openCalls.set(callId, "file_change");
+                        out.push(JSON.stringify({
+                            type: "tool_execution_start",
+                            toolCallId: callId,
+                            toolName: "edit",
+                            args: content[i].arguments,
+                        }));
+                    }
+                    return out;
+                }
+                if (itemType === "error") {
+                    // An error item is a non-fatal notice (finding 11); warned once per distinct message.
+                    const message = typeof item.message === "string" ? item.message : undefined;
+                    if (message !== undefined)
+                        recordErrorItem(message);
+                    return [];
+                }
+                if (itemType === "agent_message") {
+                    // The model's reply: one canonical `message_end` with one text block.
+                    const text = typeof item.text === "string" ? item.text : "";
+                    return [
+                        JSON.stringify({
+                            type: "message_end",
+                            message: { role: "assistant", content: [{ type: "text", text }] },
+                        }),
+                    ];
+                }
+                if (DROPPED_ITEM_TYPES.has(itemType))
+                    return [];
+                // mcp_tool_call / reasoning and any unknown item shape map to nothing canonical; a
+                // once-per-type warning only (design §5).
+                recordItem(item);
+                return [];
+            }
+            default:
+                recordEvent(type);
+                return [];
+        }
+    };
+    return {
+        translate,
+        sessionId() {
+            return sessionIdValue;
+        },
+        turnCompletedUsage() {
+            return turnUsage;
+        },
+        flagUsagePartial() {
+            warnings.add("codex_usage_partial");
+        },
+        flagModelSwitched(requested, ran) {
+            warnings.add(`codex_model_switched requested=${requested} ran=${ran}`);
+        },
+        finalize() {
+            // The stream ended with neither turn.completed nor turn.failed (a SIGTERM the harness
+            // did not send, finding 12): report the turn never finished.
+            if (sawTurnCompleted || sawTurnFailed)
+                return [];
+            return [
+                JSON.stringify({
+                    type: "message_end",
+                    message: { role: "assistant", content: [], stopReason: "error", errorMessage: "codex exited without finishing its turn" },
+                }),
+            ];
+        },
+        warnings() {
+            return [...warnings];
+        },
+    };
+}