tumwater 0.4.1 → 0.4.3

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

@@ -11,13 +11,13 @@
  * 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-stream.ts forwards each as an
+ * on the seam's optional `warnings()` — src/agent/agent-stream.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 { joinParts } from "../../text/text.js";
-import { secondsUntil } from "../../text/datetime.js";
-import { canonicalUsageBlock, isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
-import { SERVER_TRANSIENT_STATUS } from "../backend-traits.js";
+import { secondsUntilUnixStamp } from "../../text/datetime.js";
+import { canonicalUsageBlock, isJsonObject, nonNegativeNumber, objectOrEmpty, optionalString, parseJsonObject } from "../../files/json-object.js";
+import { SERVER_TRANSIENT_STATUS, transientProseKind } from "../backend-traits.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`. */
@@ -32,9 +32,6 @@ const TOOL_NAMES = {
 };
 /** 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). The
@@ -49,15 +46,15 @@ function canonicalUsage(usage) {
 function canonicalBlock(block) {
     switch (block.type) {
         case "text":
-            return { type: "text", text: str(block.text) ?? "" };
+            return { type: "text", text: optionalString(block.text) ?? "" };
         case "thinking":
-            return { type: "thinking", thinking: str(block.thinking) ?? str(block.text) ?? "" };
+            return { type: "thinking", thinking: optionalString(block.thinking) ?? optionalString(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) ?? "";
+            const name = optionalString(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
@@ -65,7 +62,7 @@ function canonicalBlock(block) {
             // applies to EFFORT_BY_THINKING.
             return {
                 type: "toolCall",
-                id: str(block.id) ?? "",
+                id: optionalString(block.id) ?? "",
                 name: Object.hasOwn(TOOL_NAMES, name) ? (TOOL_NAMES[name]) : name.toLowerCase(),
                 arguments: args,
             };
@@ -74,48 +71,80 @@ function canonicalBlock(block) {
             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);
+/** `terminal === "aborted_tools"` is deliberate: the harness killed the run, so no provider
+ * classification applies — the chain stops there. `error_max_budget_usd`, as a terminal
+ * reason or in the text, caps the budget. */
+function terminalAndBudgetClassification(terminal, text) {
     if (terminal === "aborted_tools")
         return {};
     if (terminal === "error_max_budget_usd")
         return { kind: "budgetCapped" };
-    const text = joinParts([str(result.result), str(result.error)], " ");
     if (/error_max_budget_usd/i.test(text))
         return { kind: "budgetCapped" };
-    const status = nonNegativeNumber(result.api_error_status, undefined);
+    return undefined;
+}
+function statusClassification(status) {
     if (status === 429)
         return { kind: "transientRateLimit" };
     if (status !== undefined && SERVER_TRANSIENT_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.
+    return undefined;
+}
+/** 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. */
+function contextOverflowClassification(text) {
     if (/prompt is too long/i.test(text))
         return { kind: "contextExceeded" };
+    return undefined;
+}
+function configStatusClassification(status) {
     if (status !== undefined && CONFIG_STATUS.has(status))
         return { kind: "configError" };
-    // Text fallbacks, for the statuses claude leaves null or omits.
+    return undefined;
+}
+function resumeMissingClassification(text) {
     if (/No conversation found with session ID/i.test(text))
         return { kind: "resumeMissing" };
+    return undefined;
+}
+function configTextClassification(text) {
     if (/Not logged in|issue with the selected model|does not support this model/i.test(text))
         return { kind: "configError" };
+    return undefined;
+}
+function transientTextClassification(text) {
     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" };
+    const prose = transientProseKind(text);
+    return prose;
+}
+/** Text fallbacks, for the statuses claude leaves null or omits. */
+function httpStatusTextClassification(text) {
     if (/\b(400|401|403|404)\b/i.test(text))
         return { kind: "configError" };
-    return {};
+    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 = optionalString(result.terminal_reason);
+    const text = joinParts([optionalString(result.result), optionalString(result.error)], " ");
+    const status = nonNegativeNumber(result.api_error_status, undefined);
+    return (terminalAndBudgetClassification(terminal, text) ??
+        statusClassification(status) ??
+        contextOverflowClassification(text) ??
+        configStatusClassification(status) ??
+        resumeMissingClassification(text) ??
+        configTextClassification(text) ??
+        transientTextClassification(text) ??
+        httpStatusTextClassification(text) ??
+        {});
 }
 /** Build a fresh per-run claude translator. */
 export function claudeTranslator(opts = {}) {
@@ -169,14 +198,14 @@ export function claudeTranslator(opts = {}) {
         warnings.add(kind);
     };
     const handleSystem = (event) => {
-        const subtype = str(event.subtype);
+        const subtype = optionalString(event.subtype);
         if (subtype === "init") {
             const out = [];
-            const cwd = str(event.cwd);
-            const id = str(event.session_id);
+            const cwd = optionalString(event.cwd);
+            const id = optionalString(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);
+            const billing = billingOf(optionalString(event.apiKeySource), opts.thirdPartyProvider === true);
             if (billing)
                 out.push(JSON.stringify({ type: "billing", billing }));
             return out;
@@ -185,7 +214,7 @@ export function claudeTranslator(opts = {}) {
             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 error = optionalString(event.error) ?? "";
             const errorMessage = joinParts([status !== undefined ? `status ${status}` : "", error], ": ");
             return [
                 JSON.stringify({
@@ -207,7 +236,7 @@ export function claudeTranslator(opts = {}) {
     const handleAssistant = (event) => {
         sawActivity = true;
         const message = objectOrEmpty(event.message);
-        const id = str(message.id) ?? `anon-${anonymous++}`;
+        const id = optionalString(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.
@@ -230,7 +259,7 @@ export function claudeTranslator(opts = {}) {
         // 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);
+        const stopReason = optionalString(message.stop_reason);
         if (stopReason !== undefined)
             pending.stopReason = stopReason;
         return out;
@@ -244,7 +273,7 @@ export function claudeTranslator(opts = {}) {
                 continue;
             out.push(JSON.stringify({
                 type: "tool_execution_end",
-                toolCallId: str(raw.tool_use_id) ?? "",
+                toolCallId: optionalString(raw.tool_use_id) ?? "",
                 isError: raw.is_error === true,
             }));
         }
@@ -252,45 +281,12 @@ export function claudeTranslator(opts = {}) {
     };
     const handleRateLimitEvent = (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; secondsUntil folds it (×1000) to whole seconds.
-            out.retryAfterSeconds = secondsUntil(resetsAt * 1000, Date.now());
-        }
-        return [JSON.stringify(out), ...windows];
+        const rateLimitType = optionalString(info.rateLimitType);
+        const status = optionalString(info.status);
+        return [
+            JSON.stringify(claudeRateLimitReading(info, rateLimitType, status)),
+            ...claudeRateLimitWindowReadings(info, rateLimitType),
+        ];
     };
     const handleResult = (event) => {
         sawActivity = true;
@@ -315,7 +311,7 @@ export function claudeTranslator(opts = {}) {
                 content: [],
                 stopReason: "error",
             };
-            const errorMessage = str(event.result) ?? str(event.error);
+            const errorMessage = optionalString(event.result) ?? optionalString(event.error);
             if (errorMessage !== undefined)
                 message.errorMessage = errorMessage;
             // tumwaterKind/backendKind ride the canonical EVENT (not its message): the parser
@@ -334,7 +330,7 @@ export function claudeTranslator(opts = {}) {
         if (!parsed)
             return []; // Non-JSON noise on stdout; ignore, as pi's parser does.
         const event = parsed;
-        const type = str(event.type);
+        const type = optionalString(event.type);
         switch (type) {
             case "system": return handleSystem(event);
             case "assistant": return handleAssistant(event);
@@ -367,6 +363,63 @@ export function claudeTranslator(opts = {}) {
         },
     };
 }
+/** One reading per sibling `unifiedWindows` window other than the binding window. */
+function claudeRateLimitWindowReadings(info, rateLimitType) {
+    // 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));
+    }
+    return windows;
+}
+/** The binding window's own `unifiedWindows` record, if a rate-limit type was named. */
+function claudeRateLimitOwnWindow(info, rateLimitType) {
+    return rateLimitType === undefined ? undefined : objectOrEmpty(objectOrEmpty(info.unifiedWindows)[rateLimitType]);
+}
+/** The binding window's reset time: the top-level `resetsAt` falling back to its own record. */
+function claudeRateLimitResetsAt(info, own) {
+    return nonNegativeNumber(info.resetsAt, undefined) ?? nonNegativeNumber(own?.resetsAt, undefined);
+}
+/** The binding window's utilization: the top-level `utilization` falling back to its own record. */
+function claudeRateLimitUtilization(info, own) {
+    return nonNegativeNumber(info.utilization, undefined) ?? nonNegativeNumber(own?.utilization, undefined);
+}
+/** The binding window's canonical reading: its optional fields, plus a rejected window's
+ * retry-after. */
+function claudeRateLimitReading(info, rateLimitType, status) {
+    const own = claudeRateLimitOwnWindow(info, rateLimitType);
+    const resetsAt = claudeRateLimitResetsAt(info, own);
+    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 = claudeRateLimitUtilization(info, own);
+    if (utilization !== undefined)
+        out.utilization = utilization;
+    const overageStatus = optionalString(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; secondsUntilUnixStamp folds it to whole seconds.
+        out.retryAfterSeconds = secondsUntilUnixStamp(resetsAt, Date.now());
+    }
+    return out;
+}
 /** 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

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

@@ -84,6 +84,15 @@ export function parseCodexLoginStatus(stdout) {
         return "api";
     return null;
 }
+/** The refusal message when a codex seam is API-key logged in (decision 5): Codex reports no
+ * cost, so per-token billing would spend money the budget cap cannot see. The one home of the
+ * remedy text the startup gate, the live config editor, and the doctor all print, so the remedy
+ * command and its wording cannot drift between them. `home` is the codex home named in the
+ * remedy: the literal `<home>` placeholder where the call site does not resolve the home, else
+ * the resolved `CODEX_HOME` path. */
+export function codexApiKeyRefusalMessage(home) {
+    return `Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run \`CODEX_HOME=${home} codex login --device-auth\``;
+}
 /** The billing the login probe names, or null when it cannot be decided. */
 function seedBilling(config) {
     const status = probeLoginStatus(config);

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

@@ -1,7 +1,7 @@
 /** The codex adapter for the agent seam (plans/codex-backend.md §4, §5, §6): it shapes one
  * run's argv/stdin/env, translates codex's `exec --json` stream, reads the authoritative
  * rollout after the process 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
+ * backend-specific. src/agent/agent-spawn.ts spawns the run and records this run in the session
  * ledger; codex mints its own session id (a thread id, or the resumed record's id) in the
  * stream's `thread.started`, which the runner's stream-mint pass appends to the ledger and
  * `invocation` returns so a later `exec resume` can reach it.
@@ -12,7 +12,7 @@
  * thread and the existing `handoff` path takes over (design §4). Together with the `resumable`
  * hook, that is every resume point's one rule.
  *
- * Registration lives in src/agent/run-agent.ts beside the pi, claude and opencode adapters; a
+ * Registration lives in src/agent/agent-run.ts beside the pi, claude and opencode adapters; a
  * test selects codex by setting `config.agent = "codex"` on a run. A run carrying a note gets
  * the notes path in its environment (the `tumwater-notes` command on PATH reads it), as the
  * pi and claude adapters do. */

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

@@ -1,18 +1,31 @@
+/** Building the environment for one codex run (plans/codex-backend.md "The invocation" §3,
+ * findings 10, 13) — pure scrub-and-set over a base environment, with no subprocess. The caller
+ * layers the run-marker, the macOS LaunchServices preload and the notes shim on first, then hands
+ * the result here.
+ *
+ * Inherited state from a host Codex or Claude Code session breaks the team run: a Codex child
+ * keeps every `CODEX_*` it was given (finding 13), and `--ignore-user-config` still reads a host
+ * home whose `config.toml` a run writes into (finding 10). So every `CODEX_*`, the host Claude
+ * session's `CLAUDECODE` / `CLAUDE_CODE_*`, and both API keys an operator might carry
+ * (`OPENAI_API_KEY`, `CODEX_API_KEY`) are scrubbed — pi's OpenAI key must never switch Codex to
+ * per-token billing behind tumwater's back (decision 5). Everything else survives, including the
+ * run marker and the PATH that carries the notes shim.
+ *
+ * The set half points Codex at a home of the team's own (`CODEX_HOME`) when one is configured, so
+ * team sessions and trust entries stay out of the operator's `~/.codex` (finding 10). Unset, runs
+ * keep the operator's home. */
+import { scrubEnv } from "../env-scrub.js";
 /** Build the codex process environment from `base`. Never mutates `base`. */
 export function codexEnv(base, opts = {}) {
-    const env = {};
-    for (const [key, value] of Object.entries(base)) {
-        if (key === "CLAUDECODE")
-            continue;
-        if (key.startsWith("CODEX_"))
-            continue;
-        if (key.startsWith("CLAUDE_CODE_"))
-            continue;
-        if (key === "OPENAI_API_KEY" || key === "CODEX_API_KEY")
-            continue;
-        env[key] = value;
-    }
-    if (opts.home)
-        env.CODEX_HOME = opts.home;
-    return env;
+    return scrubEnv(base, {
+        keep: (key) => key !== "CLAUDECODE" &&
+            !key.startsWith("CODEX_") &&
+            !key.startsWith("CLAUDE_CODE_") &&
+            key !== "OPENAI_API_KEY" &&
+            key !== "CODEX_API_KEY",
+        then: (env) => {
+            if (opts.home)
+                env.CODEX_HOME = opts.home;
+        },
+    });
 }

package/dist/src/agent/codex/codex-hook-trust.js

@@ -37,29 +37,48 @@ function hookListMessages(cwd) {
  * `eventName: "preToolUse"` and `command` exactly the guard definition's (finding 3), or null
  * when none matches. The key and hash are returned as codex reports them. */
 function findTrust(result, definition) {
+    for (const group of hookGroups(result)) {
+        for (const hook of groupHooks(group)) {
+            const trust = matchHookTrust(hook, definition);
+            if (trust !== null)
+                return trust;
+        }
+    }
+    return null;
+}
+/** The top-level group list from `hooks/list`'s `result.data`, or `[]` when the result is not
+ * an object or has no array `data`. */
+function hookGroups(result) {
     if (typeof result !== "object" || result === null)
-        return null;
+        return [];
     const data = result.data;
-    if (!Array.isArray(data))
+    if (Array.isArray(data))
+        return data;
+    return [];
+}
+/** One group's hook list from its `hooks` field, or `[]` when the group is not an object or
+ * has no array `hooks`. */
+function groupHooks(group) {
+    if (typeof group !== "object" || group === null)
+        return [];
+    const hooks = group.hooks;
+    if (Array.isArray(hooks))
+        return hooks;
+    return [];
+}
+/** The trust of one hook when it is the guard's — `source` `sessionFlags`, `eventName`
+ * `preToolUse`, `command` exactly the definition's, with string `key` and `currentHash` — or
+ * null. */
+function matchHookTrust(hook, definition) {
+    if (typeof hook !== "object" || hook === null)
         return null;
-    for (const group of data) {
-        if (typeof group !== "object" || group === null)
-            continue;
-        const hooks = group.hooks;
-        if (!Array.isArray(hooks))
-            continue;
-        for (const hook of hooks) {
-            if (typeof hook !== "object" || hook === null)
-                continue;
-            const h = hook;
-            if (h.source !== "sessionFlags" || h.eventName !== "preToolUse")
-                continue;
-            if (h.command !== definition.command)
-                continue;
-            if (typeof h.key === "string" && typeof h.currentHash === "string") {
-                return { key: h.key, hash: h.currentHash };
-            }
-        }
+    const h = hook;
+    if (h.source !== "sessionFlags" || h.eventName !== "preToolUse")
+        return null;
+    if (h.command !== definition.command)
+        return null;
+    if (typeof h.key === "string" && typeof h.currentHash === "string") {
+        return { key: h.key, hash: h.currentHash };
     }
     return null;
 }