tumwater 0.1.3 → 0.3.0

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

@@ -0,0 +1,246 @@
+/** How tumwater learns the write guard's trust from codex itself (plans/codex-write-guard.md
+ * "Trust (parts 4–5)", findings 2–3): codex runs a session-flag PreToolUse hook only when its
+ * `trusted_hash` matches the hash codex computed for the hook's definition, and that hash is
+ * opaque — no simple digest of any command or JSON spelling matched (finding 3). So this module
+ * asks codex's own `hooks/list` RPC for the hook's `key` and `currentHash`, and caches the
+ * answer per build and codex version so a run's argv never spawns `app-server` again. The
+ * answer is never hardcoded: the key (`/<session-flags>/config.toml:pre_tool_use:0:0` on
+ * 0.163.0) and the hash both come from this lookup.
+ *
+ * The lookup spawns `app-server` in its own process group under the run's env and a bounded
+ * deadline, kills the group whether it succeeds, times out, or fails, and makes no model
+ * request and needs no login (an empty `CODEX_HOME` is enough — finding 3). Part 5/9 wires it
+ * into a run before the codex adapter's synchronous invocation. */
+import { spawn } from "node:child_process";
+import { codexHookArg } from "./codex-write-guard.js";
+import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
+import { releaseChildHandles, signalTree } from "../../process/process.js";
+import { codexHookTrustPath } from "../../paths.js";
+import { PACKAGE_JSON, packageVersion } from "../../version.js";
+/** The JSON-RPC request/notification sequence one lookup sends over `app-server`'s stdio: the
+ * `initialize` handshake (carrying tumwater's own version), the `initialized` notification,
+ * then `hooks/list` for the one cwd. The reply to `id: 2` carries the hooks. */
+function hookListMessages(cwd) {
+    const version = packageVersion(PACKAGE_JSON).version;
+    return [
+        {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: { clientInfo: { name: "tumwater", version: version ?? "unknown" } },
+        },
+        { jsonrpc: "2.0", method: "initialized" },
+        { jsonrpc: "2.0", id: 2, method: "hooks/list", params: { cwds: [cwd] } },
+    ];
+}
+/** The first hook in `hooks/list`'s `result.data[*].hooks` with `source: "sessionFlags"`,
+ * `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) {
+    if (typeof result !== "object" || result === null)
+        return null;
+    const data = result.data;
+    if (!Array.isArray(data))
+        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 };
+            }
+        }
+    }
+    return null;
+}
+/** A short name for a JSON-RPC `error` value, for the rejection message. */
+function describeError(error) {
+    if (typeof error === "string")
+        return error;
+    if (typeof error === "object" && error !== null) {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    return JSON.stringify(error);
+}
+/** Ask codex for the guard hook's trust. Spawns `<bin> -c <codexHookArg(definition)>
+ * app-server` in `cwd` under `env`, in its own process group, sends the JSON-RPC sequence
+ * above over stdio, and resolves with the trust from the first matching `hooks/list` hook.
+ *
+ * It rejects on a timeout (`timeoutMs`), on the child exiting before the reply, on a JSON-RPC
+ * `error`, and on codex listing no session-flag PreToolUse hook with this command. The child's
+ * process group is SIGKILLed whether the lookup settles by success, failure, or timeout, so no
+ * `app-server` outlives the call. */
+export function lookupCodexHookTrust(opts) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    return new Promise((resolve, reject) => {
+        const child = spawn(opts.bin, ["-c", codexHookArg(opts.definition), "app-server"], {
+            cwd: opts.cwd,
+            env: opts.env,
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let settled = false;
+        let buffer = "";
+        const finish = (err, trust) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signalTree(child, "SIGKILL");
+            releaseChildHandles(child);
+            if (err !== null)
+                reject(err);
+            else
+                resolve(trust);
+        };
+        const timer = setTimeout(() => {
+            finish(new Error(`codex hook trust lookup timed out after ${timeoutMs} ms`));
+        }, timeoutMs);
+        timer.unref?.();
+        const onLine = (line) => {
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return; // A non-JSON-RPC line (a notice, a prompt) is not our reply.
+            }
+            if (typeof msg !== "object" || msg === null)
+                return;
+            const m = msg;
+            if (m.error !== undefined) {
+                finish(new Error(`codex hooks/list errored: ${describeError(m.error)}`));
+                return;
+            }
+            if (m.id !== 2)
+                return;
+            const trust = findTrust(m.result, opts.definition);
+            if (trust !== null)
+                finish(null, trust);
+            else
+                finish(new Error("codex listed no session-flag PreToolUse hook with this command"));
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            buffer += chunk;
+            let nl = buffer.indexOf("\n");
+            while (nl >= 0) {
+                const line = buffer.slice(0, nl);
+                buffer = buffer.slice(nl + 1);
+                if (line.trim() !== "")
+                    onLine(line);
+                nl = buffer.indexOf("\n");
+            }
+        });
+        child.on("error", (err) => finish(err instanceof Error ? err : new Error(String(err))));
+        child.on("close", (code) => {
+            if (!settled) {
+                finish(new Error(`codex app-server exited (code ${code ?? "signal"}) before answering hooks/list`));
+            }
+        });
+        for (const message of hookListMessages(opts.cwd)) {
+            try {
+                child.stdin?.write(JSON.stringify(message) + "\n");
+            }
+            catch {
+                // The pipe is gone (a failed spawn); the error handler settles the lookup.
+            }
+        }
+    });
+}
+/** The trimmed output of `<bin> --version`, or "" when the probe fails or prints nothing. It
+ * keys the trust cache, so a codex upgrade re-looks-up the guard's trust for the new build.
+ * Async (spawn, not spawnSync): a hung binary's probe must not block the event loop — every
+ * run's `prepare` awaits this, and a blocking probe would freeze the whole agent while waiting
+ * out its deadline. The child's group is killed whether it succeeds or times out. */
+function codexVersion(bin, env, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(bin, ["--version"], {
+            env,
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let out = "";
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            signalTree(child, "SIGKILL");
+            releaseChildHandles(child);
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(""), timeoutMs);
+        timer.unref?.();
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            out += chunk;
+        });
+        child.on("error", () => finish(""));
+        child.on("close", () => finish(out.trim()));
+    });
+}
+/** Whether a cached value is a usable `{key, hash}` entry. */
+function isTrust(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.key === "string" &&
+        typeof value.hash === "string");
+}
+/** Resolve the guard hook's trust, cached per codex version and hook definition in
+ * `.tumwater/state/codex-hook-trust.json` so a run's argv never spawns `app-server` again.
+ * Returns the trust, rejecting on a failed lookup.
+ *
+ * The cache key is the trimmed `<bin> --version` output plus `JSON.stringify(definition)`, so
+ * a changed codex version, a changed hook command, or a changed `timeout` (which changes the
+ * hash, finding 3) each re-look-up; each entry is `{key, hash, checkedAt}`. A hit resolves
+ * without spawning `app-server`; a miss looks up and writes the entry atomically.
+ *
+ * `root` undefined (a hand run with no `.tumwater` root) looks up and caches nothing and never
+ * creates a `.tumwater` directory — a hand run once minted a phantom `$TMPDIR/.tumwater` and
+ * reddened every suite on the host (plans/codex-write-guard.md "Visibility"). */
+export async function codexHookTrust(root, opts) {
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    if (root === undefined)
+        return lookupCodexHookTrust(opts);
+    const file = codexHookTrustPath(root);
+    // The version probe and the app-server lookup share one deadline (timeoutMs): a failed
+    // lookup — a hung binary, an app-server that never answers — never delays a run past the
+    // bound, and the probe never blocks the event loop (it is async, not spawnSync). The probe
+    // is a quick identity read, so its own slice is capped at a third of the deadline — a slow
+    // probe never starves the app-server lookup of its budget, and the sum of the two always
+    // stays within the one deadline.
+    const deadline = Date.now() + timeoutMs;
+    const version = await codexVersion(opts.bin, opts.env, opts.cwd, Math.floor(timeoutMs / 3));
+    const cacheKey = `${version}${JSON.stringify(opts.definition)}`;
+    const cache = readJsonFile(file);
+    const hit = cache?.[cacheKey];
+    if (isTrust(hit))
+        return { key: hit.key, hash: hit.hash };
+    const trust = await lookupCodexHookTrust({
+        ...opts,
+        timeoutMs: Math.max(1, deadline - Date.now()),
+    });
+    const next = { ...(cache ?? {}) };
+    next[cacheKey] = { key: trust.key, hash: trust.hash, checkedAt: Date.now() };
+    try {
+        writeJsonAtomic(file, next);
+    }
+    catch {
+        // A cache write failure must never fail the lookup whose result it is only persisting.
+    }
+    return trust;
+}

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;
+}