tumwater 0.1.1 → 0.1.2

package/dist/src/agent/claude/claude-backend.js

@@ -0,0 +1,162 @@
+/** The claude adapter for the agent seam (plans/agent-backends.md "The seam", "Sessions",
+ * "The claude invocation"). It shapes one run's argv/stdin/env, translates claude's
+ * `stream-json` into the canonical stream, and classifies the exit's stderr — everything
+ * backend-specific. src/agent/run-agent.ts owns the spawn and records this run in the session
+ * ledger; claude mints its own session id (a fresh UUID, or the resumed record's id), which
+ * `invocation` returns so the ledger can carry it.
+ *
+ * Sessions resume by id from the cwd the session started in, so the adapter consults the
+ * ledger's newest record of this run's kind and only passes `--resume` when that record names
+ * claude, this cwd, and a transcript file that exists. Otherwise it mints a fresh id — a
+ * missing transcript, a different cwd, or another kind's newer session all review fresh rather
+ * than resuming the wrong conversation.
+ *
+ * Registration lives in src/agent/run-agent.ts beside the pi adapter, so a test can register a
+ * fake under its own id; a test selects claude by setting `config.agent = "claude"` on a run. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { resolvedAgentConfig } from "../../config/config-views.js";
+import { MODEL_TIERS } from "../../config/config-schema.js";
+import { routeModel } from "../../config/model-selector.js";
+import { agentBaseEnv } from "../../process/run-marker.js";
+import { resolveBackendBin } from "../../pi/pi-bin.js";
+import { claudeArgs } from "./claude-args.js";
+import { claudeEnv, claudeThirdPartyProvider } from "./claude-env.js";
+import { claudeTranslator } from "./claude-stream.js";
+import { resumableSession } from "../session-ledger.js";
+/** claude's per-cwd project directory name under `~/.claude/projects/`: every character that
+ * is not a letter or digit becomes `-`. Exported with `claudeTranscriptPath` so the PATH fake
+ * and the tests create and look for exactly the file the resume check reads. */
+export function claudeProjectSlug(cwd) {
+    return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+/** The transcript file claude writes for a session started in `cwd`: its resume check must find
+ * a real file before passing `--resume`. claude's own layout is
+ * `~/.claude/projects/<slug>/<sessionId>.jsonl`; exported so the fake and the resume logic
+ * cannot drift. */
+export function claudeTranscriptPath(cwd, id) {
+    return path.join(os.homedir(), ".claude", "projects", claudeProjectSlug(cwd), `${id}.jsonl`);
+}
+/** The CLI version every gated claude model needs (plans/agent-backends.md finding 9): on
+ * 2.1.216 Opus 5.5 is refused outright and Haiku 5.5 is mispriced about 250×, and fleet runs
+ * set DISABLE_AUTOUPDATER so they never update themselves. The gated models are the three
+ * tier defaults, derived from AGENT_DEFAULT_MODELS through the same routing the config uses
+ * rather than listed again, so this table cannot drift from the models a seam resolves. */
+const CLAUDE_MIN_VERSION = "2.1.280";
+const CLAUDE_GATED_MODELS = new Set(MODEL_TIERS.map((tier) => routeModel(undefined, undefined, "claude", tier).model).filter((model) => model !== undefined));
+/** The minimum CLI version `model` needs, or undefined when this adapter gates no floor for
+ * it (a model outside the three tier defaults). Doctor reads it through `claudeBackend`. */
+function claudeMinVersion(model) {
+    return CLAUDE_GATED_MODELS.has(model) ? CLAUDE_MIN_VERSION : undefined;
+}
+/** Classify claude's stderr: a nonzero exit naming a login or model problem is a permanent
+ * configuration error. The stream translator classifies the structured result signals; this is
+ * the stderr half, for a CLI that died before emitting one. A run the harness killed has its
+ * own cause and is never classified here. */
+function classifyClaudeExit(info) {
+    if (info.killed)
+        return {};
+    if (info.code !== 0 &&
+        /Not logged in|issue with the selected model|does not support this model/i.test(info.stderr)) {
+        return { configError: true };
+    }
+    return {};
+}
+/** The inline `--mcp-config` JSON that runs the bundled role-notes server (part 5/7): the
+ * same dist module pi's extension resolves to, spawned by the same node running this harness
+ * so it needs no PATH lookup. */
+function roleNotesMcpConfig() {
+    const server = fileURLToPath(new URL("../mcp/role-notes-server.js", import.meta.url));
+    return JSON.stringify({ mcpServers: { tumwater: { command: process.execPath, args: [server] } } });
+}
+/** The ledger record this run may resume, or null: the newest record of `opts.kind` for
+ * claude, at `opts.cwd` when one is given, whose transcript file exists. Shared by
+ * `resolveClaudeSession` and the backend's `resumable` hook, so the resume guard and the
+ * invocation can never drift on what counts as resumable. */
+function claudeResumableRecord(dir, opts) {
+    const record = resumableSession(dir, opts);
+    if (record === null)
+        return null;
+    if (opts.cwd !== undefined && record.cwd !== opts.cwd)
+        return null;
+    if (!fs.existsSync(claudeTranscriptPath(record.cwd, record.id)))
+        return null;
+    return record;
+}
+/** The session id this run uses: for a continue, the ledger's newest record of this kind when
+ * it is claude's, this cwd's, and its transcript file exists; otherwise a fresh UUID. Returns
+ * the id and the `--resume` id when resuming. */
+function resolveClaudeSession(run) {
+    if (run.continueSession) {
+        const record = claudeResumableRecord(run.sessionDir, {
+            kind: run.kind,
+            agent: "claude",
+            cwd: run.cwd,
+        });
+        if (record !== null)
+            return { sessionId: record.id, resumeSessionId: record.id };
+    }
+    return { sessionId: randomUUID() };
+}
+/** The agent-backend seam's claude adapter. */
+export const claudeBackend = {
+    id: "claude",
+    label: "Claude Code",
+    defaultBin: "claude",
+    binEnv: "TUMWATER_CLAUDE_BIN",
+    minVersion: claudeMinVersion,
+    resolveBin(config) {
+        return resolveBackendBin(config, this);
+    },
+    invocation(run) {
+        // Part 4b/7's config routing fills a claude tier default before the seam, so a nameless
+        // run here is a caller bug (a config that named claude without going through the views).
+        if (run.config.model === undefined) {
+            throw new Error("claude backend: no model resolved for this run");
+        }
+        const { sessionId, resumeSessionId } = resolveClaudeSession(run);
+        const { args, stdin } = claudeArgs({
+            cwd: run.cwd,
+            model: run.config.model,
+            thinking: run.config.thinking,
+            ...(resumeSessionId !== undefined ? { resumeSessionId } : { sessionId }),
+            // The operator's `agents.claude.args` passthrough, appended after the harness flags (the
+            // builder rejects any entry that repeats a harness-managed flag). resolvedAgentConfig
+            // owns the view so a caller cannot mutate the loaded config through the returned array.
+            args: resolvedAgentConfig(run.config, "claude").args,
+            prompt: run.prompt,
+            // The caller computes the remaining daily budget for an API-billed claude run and the
+            // adapter forwards it; a subscription run or the director passes none (part 7a/7).
+            ...(run.maxBudgetUsd !== undefined ? { maxBudgetUsd: run.maxBudgetUsd } : {}),
+            // claude does not load the bundled pi extensions, so a run carrying a notebook gets the
+            // role_notes MCP server instead. Passed on EVERY claude invocation that carries a
+            // notebook — fresh or resumed, a transient retry, a SUMMARY follow-up — because claude
+            // keeps no flags across --resume, so a resume without this would lose the tool.
+            ...(run.notesPath !== undefined ? { mcpConfig: roleNotesMcpConfig() } : {}),
+        });
+        // agentBaseEnv applies the run marker and the macOS preload (shared with the pi adapter);
+        // claudeEnv layers the backend's own scrub-and-set on top. The notebook path rides beside
+        // the marker the same way pi's adapter carries it (pi-backend.ts withNotesPath), so the
+        // spawned MCP server — which inherits this environment — reads the same notes file.
+        const base = run.notesPath === undefined
+            ? agentBaseEnv(run.runMarker)
+            : { ...agentBaseEnv(run.runMarker), TUMWATER_NOTES_PATH: run.notesPath };
+        const env = claudeEnv(base, {
+            quietTimeoutSeconds: run.config.quietTimeoutSeconds,
+        });
+        return { args, stdin, env, sessionId };
+    },
+    translator() {
+        // A third-party provider (Bedrock/Vertex/Foundry) bills as API even when claude's
+        // `system/init` omits a usable `apiKeySource`; seedBilling reads the same environment to
+        // seed the account file, so both must classify it the same way.
+        return claudeTranslator({ thirdPartyProvider: claudeThirdPartyProvider(process.env) });
+    },
+    resumable(dir, opts) {
+        return claudeResumableRecord(dir, opts) !== null;
+    },
+    classifyExit: classifyClaudeExit,
+};

package/dist/src/agent/claude/claude-env.js

@@ -0,0 +1,84 @@
+/** Building the environment for one claude run (plans/agent-backends.md "The claude
+ * invocation", "Findings" 2 and 4) — pure scrub-and-set over a base environment, with no
+ * subprocess. The caller layers the run-marker, the macOS LaunchServices preload, and the
+ * notebook on first (src/pi/pi-backend.ts's `withNotesPath` shows the pi adapter doing the
+ * same), then hands the result here.
+ *
+ * Inherited Claude Code session variables break auth: spawned from inside a Claude Code
+ * session, a child that keeps `CLAUDECODE`, `CLAUDE_CODE_*`, `CLAUDE_AGENT_SDK_*` or the host's
+ * `ANTHROPIC_BASE_URL` reports "Not logged in" (finding 2). Everything the host session set is
+ * scrubbed, except the operator-intent allowlist; `ANTHROPIC_BASE_URL` is dropped only when
+ * `CLAUDECODE` was set, so an operator's own proxy still reaches a run started outside a
+ * session.
+ *
+ * The set half disables auto-memory, backgrounded Bash tasks (finding 4: claude refuses a long
+ * foreground command, backgrounds it, and abandons it when `-p` ends, which would report work
+ * never verified), the auto-updater (a mid-fleet self-update must not swap the binary under a
+ * run), telemetry, and error reporting; and raises the Bash timeouts so a slow suite runs in
+ * the foreground. `BASH_MAX_TIMEOUT_MS` is derived from `quietTimeoutSeconds` so claude's own
+ * Bash timeout fires before tumwater's quiet kill and the model sees a tool error rather than a
+ * dead run. */
+/** The cloud-provider switches that make a claude run bill as API rather than a claude.ai
+ * subscription: Bedrock, Vertex, and Azure Foundry. They carry operator intent, so the run
+ * environment keeps them (the allowlist below); claude-account's seedBilling and this module's
+ * `claudeThirdPartyProvider` classify all three as API billing. */
+const THIRD_PARTY_PROVIDER_VARS = [
+    "CLAUDE_CODE_USE_BEDROCK",
+    "CLAUDE_CODE_USE_VERTEX",
+    "CLAUDE_CODE_USE_FOUNDRY",
+];
+/** True when `base` carries one of the third-party provider switches. seedBilling
+ * (claude-account.ts) and the run's stream translator (claude-backend.ts) both answer billing
+ * through this, so a provider run agrees with the account file about its own billing even when
+ * claude's `system/init` omits a usable `apiKeySource`. */
+export function claudeThirdPartyProvider(base) {
+    return THIRD_PARTY_PROVIDER_VARS.some((name) => base[name] !== undefined);
+}
+/** The host-session variables that carry operator intent rather than the session's state, so a
+ * run inherits them: which cloud provider to authenticate through (Bedrock, Vertex, or Azure
+ * Foundry), an OAuth token, and an output cap. Every other `CLAUDE_CODE_*` is the session's
+ * own. The three provider switches must all survive together: seeds that classify billing
+ * treat any of them as API, so a run that dropped one would disagree with the account file
+ * about its own provider. */
+const CLAUDE_CODE_ALLOWLIST = new Set([
+    ...THIRD_PARTY_PROVIDER_VARS,
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "CLAUDE_CODE_MAX_OUTPUT_TOKENS",
+]);
+/** claude's default foreground Bash ceiling, matching the design's `BASH_DEFAULT_TIMEOUT_MS`
+ * (finding 4: claude's own default is 2 min, too short for a real suite). */
+const BASH_DEFAULT_TIMEOUT_MS = 600_000;
+/** The floor for the derived `BASH_MAX_TIMEOUT_MS`. A positive `quietTimeoutSeconds` below 60
+ * would derive a non-positive cap, which claude rejects (or reads as unlimited); clamp to one
+ * second so a very short quiet window still hands claude a usable, positive ceiling. */
+const MIN_BASH_MAX_TIMEOUT_MS = 1_000;
+/** Build the claude process environment from `base`. Never mutates `base`. */
+export function claudeEnv(base, opts) {
+    const hadClaudeCode = base.CLAUDECODE !== undefined;
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (key === "CLAUDECODE" || key === "CLAUDE_PID" || key === "CLAUDE_EFFORT")
+            continue;
+        if (key.startsWith("CLAUDE_CODE_") && !CLAUDE_CODE_ALLOWLIST.has(key))
+            continue;
+        if (key.startsWith("CLAUDE_AGENT_SDK_"))
+            continue;
+        // The host session's proxy, not the operator's: only when CLAUDECODE says we are inside one.
+        if (key === "ANTHROPIC_BASE_URL" && hadClaudeCode)
+            continue;
+        env[key] = value;
+    }
+    env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
+    env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS = "1";
+    env.BASH_DEFAULT_TIMEOUT_MS = String(BASH_DEFAULT_TIMEOUT_MS);
+    if (opts.quietTimeoutSeconds > 0) {
+        // 60 s under the quiet kill, so claude's tool error arrives before the run is declared hung;
+        // floored so a quiet window under 60 s never derives a non-positive cap.
+        const derived = opts.quietTimeoutSeconds * 1000 - 60_000;
+        env.BASH_MAX_TIMEOUT_MS = String(Math.max(derived, MIN_BASH_MAX_TIMEOUT_MS));
+    }
+    env.DISABLE_AUTOUPDATER = "1";
+    env.DISABLE_TELEMETRY = "1";
+    env.DISABLE_ERROR_REPORTING = "1";
+    return env;
+}

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

@@ -0,0 +1,384 @@
+/** The claude adapter's native-to-canonical stream translator (plans/agent-backends.md
+ * "Canonical event stream"). Claude Code's `--output-format stream-json` vocabulary differs
+ * from pi's in every dimension the readers care about: one content block per `assistant`
+ * event (with the same `message.id` and its usage repeated on each), tool calls named `Bash`/
+ * `Read`/`File`-style, `file_path` rather than `path`, cost only in the final `result`, and
+ * errors carried as `is_error` + `api_error_status` + `terminal_reason` rather than as prose
+ * in a message. Rather than teach ~fifteen readers a second 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 pending split-block assistant message, the unmapped native types seen, whether a
+ * `run_cost` arrived), so call it once per run. Unmapped native types 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. `cost_unknown` is recorded the same way when a
+ * run produced no authoritative `run_cost`. */
+import { isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
+/** claude's tool names → the canonical pi names the readers already know. Glob/Grep are kept
+ * lower-cased; MultiEdit collapses onto edit (pi has one edit tool). Anything else is
+ * lower-cased so a future tool still reads as a name rather than as `undefined`. */
+const TOOL_NAMES = {
+    Bash: "bash",
+    Read: "read",
+    Edit: "edit",
+    MultiEdit: "edit",
+    Write: "write",
+    Glob: "glob",
+    Grep: "grep",
+};
+/** claude's HTTP status classes that mean a transient backend failure. 529 is Anthropic's
+ * "overloaded" spelling. */
+const SERVER_STATUS = new Set([500, 502, 503, 504, 529]);
+/** claude's HTTP status classes that mean a permanent configuration error. */
+const CONFIG_STATUS = new Set([400, 401, 403, 404]);
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** claude's usage block → pi's canonical usage block, with `cost.total` 0 because the run's
+ * authoritative cost rides the final `run_cost` event (a split-block message repeats its usage
+ * on every event, so summing per event would double-count — the fold takes it once). */
+function canonicalUsage(usage) {
+    const input = nonNegativeNumber(usage?.input_tokens, 0);
+    const cacheRead = nonNegativeNumber(usage?.cache_read_input_tokens, 0);
+    const cacheWrite = nonNegativeNumber(usage?.cache_creation_input_tokens, 0);
+    const output = nonNegativeNumber(usage?.output_tokens, 0);
+    return {
+        input,
+        cacheRead,
+        cacheWrite,
+        output,
+        totalTokens: input + cacheRead + cacheWrite + output,
+        cost: { total: 0 },
+    };
+}
+/** One claude content block → one pi content block, or undefined for a block pi has no
+ * vocabulary for (dropped, like any other unmapped native shape). `tool_use` becomes pi's
+ * `toolCall` with the canonical name and an `arguments` object carrying claude's `input` plus
+ * a `path` alias of `file_path` — `describeToolCall` reads either. */
+function canonicalBlock(block) {
+    switch (block.type) {
+        case "text":
+            return { type: "text", text: str(block.text) ?? "" };
+        case "thinking":
+            return { type: "thinking", thinking: str(block.thinking) ?? str(block.text) ?? "" };
+        case "tool_use": {
+            const input = objectOrEmpty(block.input);
+            const args = { ...input };
+            if (typeof input.file_path === "string")
+                args.path = input.file_path;
+            const name = str(block.name) ?? "";
+            // Own-property test, not a bare index: a tool name like `constructor`, `toString`, or
+            // `__proto__` would otherwise inherit a function (or Object.prototype) from the table's
+            // prototype chain and bypass the lower-cased fallback — JSON.stringify then drops the
+            // canonical event's toolName or turns it into an empty object. The same guard claude-args
+            // applies to EFFORT_BY_THINKING.
+            return {
+                type: "toolCall",
+                id: str(block.id) ?? "",
+                name: Object.hasOwn(TOOL_NAMES, name) ? TOOL_NAMES[name] : name.toLowerCase(),
+                arguments: args,
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+/** How a `result` event's error signals classify into the canonical `tumwaterKind` (and, for
+ * a transient backend, its kind), trusted by `PiStreamParser` before its text regexes. Empty
+ * when the result is not an error or carries no signal the vocabulary names — a SIGTERM
+ * (`terminal_reason: "aborted_tools"`) is deliberate: the harness killed the run, so no
+ * provider classification applies. `status` is `api_error_status`, which is null on the
+ * not-logged-in result, so the text checks carry that case. */
+function classifyResult(result) {
+    const terminal = str(result.terminal_reason);
+    if (terminal === "aborted_tools")
+        return {};
+    if (terminal === "error_max_budget_usd")
+        return { kind: "budgetCapped" };
+    const text = [str(result.result), str(result.error)].filter(Boolean).join(" ");
+    if (/error_max_budget_usd/i.test(text))
+        return { kind: "budgetCapped" };
+    const status = nonNegativeNumber(result.api_error_status, undefined);
+    if (status === 429)
+        return { kind: "transientRateLimit" };
+    if (status !== undefined && SERVER_STATUS.has(status))
+        return { kind: "transientBackend", backendKind: "server" };
+    // The context-overflow text wins over a configuration status: claude reports an oversized
+    // prompt as HTTP 400 ("prompt is too long"), whose status alone would read as configError.
+    if (/prompt is too long/i.test(text))
+        return { kind: "contextExceeded" };
+    if (status !== undefined && CONFIG_STATUS.has(status))
+        return { kind: "configError" };
+    // Text fallbacks, for the statuses claude leaves null or omits.
+    if (/No conversation found with session ID/i.test(text))
+        return { kind: "resumeMissing" };
+    if (/Not logged in|issue with the selected model|does not support this model/i.test(text))
+        return { kind: "configError" };
+    if (/\b429\b|rate limit/i.test(text))
+        return { kind: "transientRateLimit" };
+    if (/overloaded|internal server error|bad gateway|service unavailable|gateway timeout|\b5\d\d\b/i.test(text))
+        return { kind: "transientBackend", backendKind: "server" };
+    if (/connection|econn|refused|reset|terminated/i.test(text))
+        return { kind: "transientBackend", backendKind: "connection" };
+    if (/timed out|timeout/i.test(text))
+        return { kind: "transientBackend", backendKind: "timeout" };
+    if (/\b(400|401|403|404)\b/i.test(text))
+        return { kind: "configError" };
+    return {};
+}
+/** Build a fresh per-run claude translator. */
+export function claudeTranslator(opts = {}) {
+    /** The split-block assistant message being folded: claude emits one event per content
+     * block, so a text+tool_use turn arrives as two events with the same `message.id` and the
+     * full usage repeated on each. */
+    let pending;
+    let anonymous = 0;
+    let sawRunCost = false;
+    /** True once the run produced real work (an assistant turn or a result) — the signal that a
+     * missing `run_cost` is a gap rather than the quiet of an eventless stream. */
+    let sawActivity = false;
+    const seen = new Set();
+    const warnings = new Set();
+    /** Emit the pending assistant message (if any) as ONE canonical `message_end`. Tool calls
+     * open separately, the moment their `tool_use` block is folded (see `startToolCall`): claude
+     * emits the assistant message before it runs the tool, and the `tool_result` only after, so
+     * opening the call here at message close would expose it to the open-call trackers only when
+     * the closing `user` event carries the result — never while the tool is actually running. */
+    const flush = () => {
+        const message = pending;
+        if (!message)
+            return [];
+        pending = undefined;
+        return [
+            JSON.stringify({
+                type: "message_end",
+                message: {
+                    role: "assistant",
+                    content: message.content,
+                    usage: message.usage,
+                    ...(message.stopReason !== undefined ? { stopReason: message.stopReason } : {}),
+                },
+            }),
+        ];
+    };
+    /** One canonical `tool_execution_start`, emitted as soon as a `tool_use` block is folded —
+     * while claude is still running the tool, before the `tool_result` arrives. The open-call
+     * trackers (runPi's stall warning, the dashboard flag) only see a call while it is open, so
+     * this is what lets them judge a claude call by its duration instead of its silence. */
+    const startToolCall = (block) => JSON.stringify({
+        type: "tool_execution_start",
+        toolCallId: block.id,
+        toolName: block.name,
+        args: block.arguments,
+    });
+    const record = (kind) => {
+        if (seen.has(kind))
+            return;
+        seen.add(kind);
+        warnings.add(kind);
+    };
+    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 = str(event.type);
+        switch (type) {
+            case "system": {
+                const subtype = str(event.subtype);
+                if (subtype === "init") {
+                    const out = [];
+                    const cwd = str(event.cwd);
+                    const id = str(event.session_id);
+                    out.push(JSON.stringify({ type: "session", ...(cwd !== undefined ? { cwd } : {}), ...(id !== undefined ? { id } : {}) }));
+                    out.push(JSON.stringify({ type: "agent_start" }));
+                    const billing = billingOf(str(event.apiKeySource), opts.thirdPartyProvider === true);
+                    if (billing)
+                        out.push(JSON.stringify({ type: "billing", billing }));
+                    return out;
+                }
+                if (subtype === "api_retry") {
+                    const attempt = nonNegativeNumber(event.attempt, undefined);
+                    const maxAttempts = nonNegativeNumber(event.max_retries, undefined);
+                    const status = nonNegativeNumber(event.error_status, undefined);
+                    const error = str(event.error) ?? "";
+                    const errorMessage = [status !== undefined ? `status ${status}` : "", error].filter(Boolean).join(": ");
+                    return [
+                        JSON.stringify({
+                            type: "auto_retry_start",
+                            ...(attempt !== undefined ? { attempt } : {}),
+                            ...(maxAttempts !== undefined ? { maxAttempts } : {}),
+                            errorMessage: errorMessage || "api retry",
+                        }),
+                    ];
+                }
+                if (subtype === "compact_boundary")
+                    return [JSON.stringify({ type: "compaction_start" })];
+                // A thinking-token estimate during extended thinking: known, carries nothing canonical.
+                if (subtype === "thinking_tokens")
+                    return [];
+                record(`system:${subtype ?? "unknown"}`);
+                return [];
+            }
+            case "assistant": {
+                sawActivity = true;
+                const message = objectOrEmpty(event.message);
+                const id = str(message.id) ?? `anon-${anonymous++}`;
+                // A new id flushes the open message; a continuing one flushes nothing. Either way the
+                // fresh or open pending then folds this event's content, usage, and stop reason the
+                // same way — that shared fold is why both branches live on one path.
+                let out = [];
+                if (pending?.id !== id) {
+                    out = flush();
+                    pending = { id, content: [], usage: canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined) };
+                }
+                const blocks = Array.isArray(message.content) ? message.content : [];
+                for (const raw of blocks) {
+                    if (!isJsonObject(raw))
+                        continue;
+                    const block = canonicalBlock(raw);
+                    if (!block)
+                        continue;
+                    pending.content.push(block);
+                    if (block.type === "toolCall")
+                        out.push(startToolCall(block));
+                }
+                // Usage repeats on every event of the same message; the last read wins and is counted
+                // once because the fold emits one message_end per id.
+                pending.usage = canonicalUsage(isJsonObject(message.usage) ? message.usage : undefined);
+                const stopReason = str(message.stop_reason);
+                if (stopReason !== undefined)
+                    pending.stopReason = stopReason;
+                return out;
+            }
+            case "user": {
+                const out = flush();
+                const message = objectOrEmpty(event.message);
+                const blocks = Array.isArray(message.content) ? message.content : [];
+                for (const raw of blocks) {
+                    if (!isJsonObject(raw) || raw.type !== "tool_result")
+                        continue;
+                    out.push(JSON.stringify({
+                        type: "tool_execution_end",
+                        toolCallId: str(raw.tool_use_id) ?? "",
+                        isError: raw.is_error === true,
+                    }));
+                }
+                return out;
+            }
+            case "rate_limit_event": {
+                const info = objectOrEmpty(event.rate_limit_info);
+                const rateLimitType = str(info.rateLimitType);
+                const status = str(info.status);
+                // claude 2.1.295 reports every window's utilization and reset under `unifiedWindows`,
+                // keyed by window type, and only the binding window's status at the top level.
+                const windows = [];
+                for (const [type, raw] of Object.entries(objectOrEmpty(info.unifiedWindows))) {
+                    if (type === rateLimitType || !isJsonObject(raw))
+                        continue;
+                    const reading = { type: "rate_limit", rateLimitType: type };
+                    const windowResets = nonNegativeNumber(raw.resetsAt, undefined);
+                    if (windowResets !== undefined)
+                        reading.resetsAt = windowResets;
+                    const windowUtil = nonNegativeNumber(raw.utilization, undefined);
+                    if (windowUtil !== undefined)
+                        reading.utilization = windowUtil;
+                    windows.push(JSON.stringify(reading));
+                }
+                const own = rateLimitType === undefined ? undefined : objectOrEmpty(objectOrEmpty(info.unifiedWindows)[rateLimitType]);
+                const resetsAt = nonNegativeNumber(info.resetsAt, undefined) ?? nonNegativeNumber(own?.resetsAt, undefined);
+                const out = { type: "rate_limit" };
+                if (rateLimitType !== undefined)
+                    out.rateLimitType = rateLimitType;
+                if (status !== undefined)
+                    out.status = status;
+                if (resetsAt !== undefined)
+                    out.resetsAt = resetsAt;
+                const utilization = nonNegativeNumber(info.utilization, undefined) ?? nonNegativeNumber(own?.utilization, undefined);
+                if (utilization !== undefined)
+                    out.utilization = utilization;
+                const overageStatus = str(info.overageStatus);
+                if (overageStatus !== undefined)
+                    out.overageStatus = overageStatus;
+                if (info.isUsingOverage === true)
+                    out.isUsingOverage = true;
+                if (status === "rejected" && resetsAt !== undefined) {
+                    // resetsAt is a unix-seconds stamp; retryAfterSeconds is the wait the loop honors.
+                    out.retryAfterSeconds = Math.max(0, Math.round(resetsAt - Date.now() / 1000));
+                }
+                return [JSON.stringify(out), ...windows];
+            }
+            case "result": {
+                sawActivity = true;
+                const out = flush();
+                // The assistant events' usage is the message-start snapshot, so the result's total
+                // is the run's real output-token count (thinking included).
+                const outputTokens = nonNegativeNumber(objectOrEmpty(event.usage).output_tokens, undefined);
+                if (outputTokens !== undefined)
+                    out.push(JSON.stringify({ type: "run_usage", outputTokens }));
+                const total = nonNegativeNumber(event.total_cost_usd, undefined);
+                if (total !== undefined) {
+                    sawRunCost = true;
+                    out.push(JSON.stringify({ type: "run_cost", total }));
+                }
+                else {
+                    warnings.add("cost_unknown");
+                }
+                if (event.is_error === true) {
+                    const { kind, backendKind } = classifyResult(event);
+                    const message = {
+                        role: "assistant",
+                        content: [],
+                        stopReason: "error",
+                    };
+                    const errorMessage = str(event.result) ?? str(event.error);
+                    if (errorMessage !== undefined)
+                        message.errorMessage = errorMessage;
+                    // tumwaterKind/backendKind ride the canonical EVENT (not its message): the parser
+                    // reads event.tumwaterKind and trusts it before its text regexes.
+                    out.push(JSON.stringify({
+                        type: "message_end",
+                        message,
+                        ...(kind !== undefined ? { tumwaterKind: kind } : {}),
+                        ...(backendKind !== undefined ? { backendKind } : {}),
+                    }));
+                }
+                return out;
+            }
+            case "tool_progress":
+                // A 30 s heartbeat of a running tool call: known, and the open call already tracks liveness.
+                return [];
+            default:
+                record(type ?? "unknown");
+                return [];
+        }
+    };
+    return {
+        translate,
+        finalize() {
+            // The stream ended (a completed run's result already flushed, a killed one did not):
+            // emit whatever assistant message is still pending so the last turn is not lost.
+            return flush();
+        },
+        warnings() {
+            // A claude run's authoritative cost is the result's total_cost_usd; a stream that did
+            // real work yet never produced that total has no trustworthy cost. Recorded lazily so a
+            // killed run's translator still reports it.
+            if (!sawRunCost && sawActivity)
+                warnings.add("cost_unknown");
+            return [...warnings];
+        },
+    };
+}
+/** The run's billing, from `system/init.apiKeySource`: claude.ai OAuth reports `"none"`, an
+ * environment key reports `ANTHROPIC_API_KEY`, a helper reports `apiKeyHelper`. A
+ * third-party provider overrides both — it is API billing even when the init omitted a
+ * source. Undefined when the init named no source and no third-party flag applied. */
+function billingOf(apiKeySource, thirdPartyProvider) {
+    if (thirdPartyProvider)
+        return "api";
+    if (apiKeySource === undefined || apiKeySource === "")
+        return undefined;
+    return apiKeySource === "none" ? "subscription" : "api";
+}