tumwater 0.4.0 → 0.4.1

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

@@ -10,12 +10,13 @@
  * 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
+ * `warnings()` — src/agent/run-stream.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";
+import { SERVER_TRANSIENT_STATUS } from "../backend-traits.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;
@@ -25,9 +26,6 @@ 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. */
@@ -96,7 +94,7 @@ function classifyTurnFailed(parsed) {
         kind.kind = "configError";
         return kind;
     }
-    if (status !== undefined && SERVER_STATUS.has(status)) {
+    if (status !== undefined && SERVER_TRANSIENT_STATUS.has(status)) {
         kind.kind = "transientBackend";
         kind.backendKind = "server";
         return kind;
@@ -185,187 +183,210 @@ export function codexTranslator(opts = {}) {
         }
         return out;
     };
+    /** The `thread.started` arm: announces the session and the agent start, or records the
+     * unmapped event once when the thread id is missing. */
+    const handleThreadStarted = (event) => {
+        const id = typeof event.thread_id === "string" ? event.thread_id : undefined;
+        if (id === undefined) {
+            recordEvent("thread.started");
+            return [];
+        }
+        sessionIdValue = id;
+        const out = [];
+        out.push(JSON.stringify({
+            type: "session",
+            id,
+            ...(cwd !== undefined ? { cwd } : {}),
+        }));
+        out.push(JSON.stringify({ type: "agent_start" }));
+        return out;
+    };
+    /** The `turn.completed` arm: folds the usage block and abandons the open calls. */
+    const handleTurnCompleted = (event) => {
+        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();
+    };
+    /** The `turn.failed` arm: classifies the inner-JSON error and closes the turn. */
+    const handleTurnFailed = (event) => {
+        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)];
+    };
+    /** The top-level `error` arm: a reconnect text emits an `auto_retry_start`; any other
+     * message is held as the next `turn.failed`'s fallback text. */
+    const handleErrorLine = (event) => {
+        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 [];
+    };
+    /** The `item.started`/`item.completed` arm: reads the item and delegates by type to the
+     * item handlers, dropping the silent types and warning once on the unknown tail. */
+    const handleItem = (event, started) => {
+        const item = objectOrEmpty(event.item);
+        const itemType = typeof item.type === "string" ? item.type : "unknown";
+        if (itemType === "command_execution")
+            return handleCommandItem(item, started);
+        if (itemType === "file_change")
+            return handleFileChangeItem(item, started);
+        if (itemType === "error")
+            return handleErrorItem(item);
+        if (itemType === "agent_message")
+            return handleAgentMessageItem(item);
+        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 [];
+    };
+    /** The `command_execution` item arm: opens or closes the bash call, capping the result. */
+    const handleCommandItem = (item, started) => {
+        const command = typeof item.command === "string" ? item.command : "";
+        const out = [];
+        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;
+    };
+    /** The `file_change` item arm: mirrors each change as an `edit` tool call. */
+    const handleFileChangeItem = (item, started) => {
+        const changes = Array.isArray(item.changes) ? item.changes.filter((c) => typeof c === "object" && c !== null) : [];
+        const id = typeof item.id === "string" ? item.id : "";
+        const out = [];
+        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;
+    };
+    /** The `item.type === "error"` arm: a non-fatal notice warned once per distinct message. */
+    const handleErrorItem = (item) => {
+        const message = typeof item.message === "string" ? item.message : undefined;
+        if (message !== undefined)
+            recordErrorItem(message);
+        return [];
+    };
+    /** The `agent_message` arm: the model's reply as one canonical `message_end`. */
+    const handleAgentMessageItem = (item) => {
+        const text = typeof item.text === "string" ? item.text : "";
+        return [
+            JSON.stringify({
+                type: "message_end",
+                message: { role: "assistant", content: [{ type: "text", text }] },
+            }),
+        ];
+    };
     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 "thread.started": return handleThreadStarted(event);
+            case "turn.started": return [];
+            case "turn.completed": return handleTurnCompleted(event);
+            case "turn.failed": return handleTurnFailed(event);
+            case "error": return handleErrorLine(event);
             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 [];
-            }
+            case "item.completed": return handleItem(event, type === "item.started");
             default:
                 recordEvent(type);
                 return [];

package/dist/src/agent/codex/{write-guard-hook.js → codex-write-guard-hook.js}

@@ -1,5 +1,6 @@
 /** The PreToolUse hook codex runs before each `apply_patch` in a team run (part 6/9 installs it
- * through `-c`): `node write-guard-hook.js` with codex's hook payload on stdin. To block the patch
+ * through `-c`): `node codex-write-guard-hook.js` with codex's hook payload on stdin. To block
+ * the patch
  * it prints a `deny` decision with the refusal as its reason, in the shape finding 5 showed codex
  * accepts: the model reads only the reason, so a denial by exit code would not carry it. It prints
  * nothing to let the patch run, and exits 0 either way. Any failure of its own (bad JSON, a throw)

package/dist/src/agent/codex/codex-write-guard.js

@@ -1,6 +1,6 @@
 /** codex's half of the write guard (src/agent/write-guard.ts holds the rule): a PreToolUse hook on
  * `apply_patch`, installed by part 6/9, refuses an `apply_patch` that writes under the team root
- * but outside the run's worktree. The entry point is write-guard-hook.ts beside this file.
+ * but outside the run's worktree. The entry point is codex-write-guard-hook.ts beside this file.
  *
  * Codex's hook takes no argument naming the worktree, unlike claude's: codex trusts a hook by a
  * hash of its whole definition, so a command constant per build needs one trust lookup, while a
@@ -63,11 +63,11 @@ export function tomlString(s) {
     return out + '"';
 }
 /** The codex write guard's definition: the PreToolUse hook on `apply_patch` that runs the
- * compiled write-guard-hook.js with this process's node, falling back to `node` on PATH when
+ * compiled codex-write-guard-hook.js with this process's node, falling back to `node` on PATH when
  * that binary has moved (as claude's and the notes shim do). The hook path resolves from this
  * module, so a staged build (.tumwater/build/<sha>) runs its own copy and gets its own hash. */
 export function codexWriteGuardDefinition(nodeBin = process.execPath) {
-    const hook = fileURLToPath(new URL("./write-guard-hook.js", import.meta.url));
+    const hook = fileURLToPath(new URL("./codex-write-guard-hook.js", import.meta.url));
     const command = `n=${shellQuote(nodeBin)}; [ -x "$n" ] || n=node; exec "$n" ${shellQuote(hook)}`;
     return { matcher: HOOK_MATCHER, command, timeout: HOOK_TIMEOUT_SECONDS };
 }

package/dist/src/agent/notes-shim.js

@@ -1,5 +1,5 @@
 /** Installing the per-team `tumwater-notes` shim every backend's run finds on its PATH
- * (plans/notes-command.md "Reaching it from a run"): run-agent calls `ensureNotesShim(root)`
+ * (plans/notes-command.md "Reaching it from a run"): run-spawn calls `ensureNotesShim(root)`
  * before building each invocation, and the backend prepends the returned dir to the run's
  * PATH (backendBaseEnv's `binDir`, src/process/run-marker.ts). The shim is a two-line `sh`
  * script that execs the compiled notes CLI, so a model's shell — pi's, Claude Code's or
@@ -20,7 +20,7 @@ export const NOTES_SHIM_NAME = "tumwater-notes";
 /** Install the `tumwater-notes` shim under `<root>/.tumwater/bin` and return that directory.
  * The shim is written atomically with mode 0755, only when its content differs from what is
  * already there (a redeploy that changes `<dist>` rewrites it). Never throws: a failure to
- * write is the caller's to absorb — run-agent logs one warning and runs without the shim. */
+ * write is the caller's to absorb — run-spawn logs one warning and runs without the shim. */
 export function ensureNotesShim(root, execPath = process.execPath) {
     const dir = notesShimDir(root);
     const target = path.join(dir, NOTES_SHIM_NAME);

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

@@ -1,8 +1,8 @@
 /** The opencode adapter for the agent seam (plans/opencode-backend.md "The invocation",
  * "Sessions", §6). It shapes one run's argv/stdin/env, translates opencode's `run --format
  * json` into the canonical stream, runs the authoritative session export after the process
- * exits, 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; opencode mints its own session id
+ * exits, and classifies the exit's stderr — everything backend-specific. src/agent/run-spawn.ts
+ * spawns the run and records this run in the session ledger; opencode mints its own session id
  * (a `ses_…` id, or the resumed record's id), which `invocation` returns so the ledger can
  * carry it.
  *

package/dist/src/agent/opencode/opencode-config.js

@@ -18,7 +18,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { readTextOrNull } from "../../files/files.js";
+import { readTextOrNull, xdgConfigHomeDir } from "../../files/files.js";
 import { isJsonObject } from "../../files/json-object.js";
 /** The operator's global opencode config lives in `$XDG_CONFIG_HOME/opencode/` (or
  * `~/.config/opencode/`), in `config.json`, `opencode.json` or `opencode.jsonc`. */
@@ -123,7 +123,7 @@ function stripJsonc(src) {
  * parse; doctor reports a broken one in part 7/7. `homeDir` is the operator's home directory;
  * the process's own `XDG_CONFIG_HOME` env, when set, wins over `~/.config` (the XDG default). */
 export function operatorMcpNames(env, homeDir) {
-    const configHome = env.XDG_CONFIG_HOME ?? path.join(homeDir, ".config");
+    const configHome = xdgConfigHomeDir(env, homeDir);
     const dir = path.join(configHome, "opencode");
     for (const file of OPERATOR_CONFIG_FILES) {
         const text = readTextOrNull(path.join(dir, file));