tumwater 0.1.3 → 0.3.0

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

@@ -0,0 +1,181 @@
+/** The Codex run's reserved flags and config keys plus the effort mapping — the pure,
+ * build-agnostic half of the codex invocation (plans/codex-backend.md "Config and routing" §2
+ * and "The invocation" §3). Part 4/9 owns these constants so config validation and the traits
+ * layer can screen a `backends.codex.args` passthrough before the adapter registered; part 5/9
+ * adds the `codexArgs` argv builder beside them, and 6/9 the stream translator. Pure — imports
+ * no runtime registry, config or subprocess — so config-validation.ts can import it without
+ * dragging the adapter in.
+ *
+ * Everything here is proved against Codex 0.163.0: every flag exists on that build, and every
+ * `-c` key passes the `--strict-config` device (design finding 20). */
+/** Flags the harness invocation sets itself (§3): the output and model flags, the sandbox and
+ * approval switches, the isolation switches, and the where-and-what-it-runs switches. A
+ * passthrough arg equal to one of these is appended AFTER the harness's own copy and Codex's
+ * parser is last-wins, so it would silently override the model, the isolation or the run
+ * location the harness resolved. Each is rejected with the offending arg named. This is the
+ * design's reserved set (§2 "Reserved passthrough flags"); config validation
+ * (config-validation-agents.ts) mirrors it for `backends.codex.args`, so a value that passes
+ * validation is never accepted there and then thrown in the builder.
+ *
+ * Operators keep `-c`, `--enable` and `--disable` for their own settings — those keys are
+ * screened separately (HARNESS_CODEX_CONFIG_KEYS). */
+import { appendPassthroughArgs } from "../agent-args.js";
+export const HARNESS_CODEX_FLAGS = new Set([
+    // Output and model: tumwater forces JSON output, the resolved model, and a normal color for
+    // the transcript log.
+    "--json",
+    "-m",
+    "--model",
+    "-o",
+    "--output-last-message",
+    "--output-schema",
+    "--color",
+    // Sandbox and approvals: tumwater runs every job with bypass approval and no sandbox
+    // (decision 2), so an operator cannot re-arm an approval prompt or a sandbox mid-run.
+    "-s",
+    "--sandbox",
+    "--dangerously-bypass-approvals-and-sandbox",
+    "--approve-for-me",
+    "--dangerously-bypass-hook-trust",
+    // Isolation: tumwater ignores the user's config, rules and persistent state so one team run
+    // cannot read a personal hook, skill or trust entry.
+    "--ignore-user-config",
+    "--ignore-rules",
+    "--ephemeral",
+    // Where and what it runs: tumwater pins the cwd and the worktree and refuses `--oss` /
+    // `--local-provider` so a run can never target something other than the resolved backend.
+    "-C",
+    "--cd",
+    "--worktree",
+    "--add-dir",
+    "--skip-git-repo-check",
+    "-p",
+    "--profile",
+    "--oss",
+    "--local-provider",
+]);
+/** The keys tumwater sets on every run via `-c <key>=…` (§3), so an operator's `-c` passthrough
+ * whose key is one of these would silently override the model, the effort, the sandbox mode, or
+ * the telemetry/state settings the harness already passed. A `-c` or `--config` passthrough whose
+ * key names one of these is refused; any other key is the operator's own and passes. */
+export const HARNESS_CODEX_CONFIG_KEYS = new Set([
+    "model",
+    "model_reasoning_effort",
+    "sandbox_mode",
+    "project_doc_fallback_filenames",
+    "web_search",
+    "agents.enabled",
+    "check_for_update_on_startup",
+    "analytics.enabled",
+    "feedback.enabled",
+    "history.persistence",
+]);
+/** Config-key prefixes an operator's `-c`/`--config` passthrough may not set: the write guard's
+ * own `hooks.*` keys (part 3/9). Codex is last-wins, so a `-c hooks.PreToolUse=…` or
+ * `-c hooks.state=…` passthrough would otherwise replace the guard or its trust after the
+ * harness's. Written beside HARNESS_CODEX_CONFIG_KEYS so both it and config validation screen
+ * against one predicate. */
+const HARNESS_CODEX_CONFIG_KEY_PREFIXES = ["hooks"];
+/** Whether `key` is a config key tumwater sets or reserves, so an operator's `-c`/`--config`
+ * passthrough naming it would silently override the harness. True for every
+ * HARNESS_CODEX_CONFIG_KEYS key and for the `hooks` key or any `hooks.<…>` subkey, which the
+ * write guard owns. */
+export function isHarnessCodexConfigKey(key) {
+    if (HARNESS_CODEX_CONFIG_KEYS.has(key))
+        return true;
+    return HARNESS_CODEX_CONFIG_KEY_PREFIXES.some((p) => key === p || key.startsWith(`${p}.`));
+}
+/** Thinking → `model_reasoning_effort`. `off` and `minimal` clamp to `low` (Codex has no lower
+ * setting; doctor notes the clamp), `low` through `max` map 1:1. `ultra` is not a value Codex
+ * can receive — tumwater never sends it (it delegates to sub-agents). This is claude's
+ * EFFORT_BY_THINKING rule moved to codex, where the level the model's catalog lists also gates
+ * the result (part 5/9's `codexEffort`). */
+export const EFFORT_BY_THINKING = {
+    off: "low",
+    minimal: "low",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+    max: "max",
+};
+/** The effort values tumwater will ever send as `model_reasoning_effort`: the set
+ * EFFORT_BY_THINKING can produce. `ultra` (which some models add for sub-agent delegation) is
+ * deliberately not here —
+ * tumwater never sends it, so `codexArgs` rejects it rather than let a whole agent hierarchy
+ * spawn on a model that lists it. */
+const KNOWN_EFFORTS = new Set(Object.values(EFFORT_BY_THINKING));
+/** Map a thinking level to the Codex `model_reasoning_effort` it means, gated by the model's own
+ * catalog. `levels` is the model's `supported_reasoning_levels` (design finding 14), which a
+ * stream-minted catalog (part 8/9) supplies; until then the caller passes `undefined`, and the
+ * result is returned unclamped. An unknown thinking level returns `undefined` (no effort flag) —
+ * the level simply has no Codex effort, unlike a thinking level that maps but the model does not
+ * support, which is also `undefined`. */
+export function codexEffort(thinking, levels) {
+    if (!Object.hasOwn(EFFORT_BY_THINKING, thinking))
+        return undefined;
+    const result = EFFORT_BY_THINKING[thinking];
+    if (levels !== undefined && !levels.includes(result))
+        return undefined;
+    return result;
+}
+/** Build one run's codex argv and stdin. The prompt is never an argv element (codex reads `-`
+ * input from stdin). Throws on an unknown effort, or a passthrough arg that repeats a harness
+ * flag, since each would otherwise silently change what the harness asked for. */
+export function codexArgs(opts) {
+    if (opts.effort !== undefined && !KNOWN_EFFORTS.has(opts.effort)) {
+        throw new Error(`codexArgs: unknown effort ${JSON.stringify(opts.effort)} (known: ${[...KNOWN_EFFORTS].join(", ")})`);
+    }
+    // Isolation flags, then the `--disable` list (design finding 7), then the `-c` keys (finding
+    // 20), then the model and effort, then the operator's passthrough, then the closing `-`.
+    const head = [
+        "--json",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--ignore-user-config",
+        "--ignore-rules",
+        "--disable",
+        "plugins",
+        "--disable",
+        "apps",
+        "--disable",
+        "goals",
+        "--disable",
+        "image_generation",
+        "--disable",
+        "browser_use",
+        "--disable",
+        "computer_use",
+        "--disable",
+        "tool_suggest",
+        "--disable",
+        "skill_search",
+        "-c",
+        "agents.enabled=false",
+        "-c",
+        'web_search="disabled"',
+        "-c",
+        "check_for_update_on_startup=false",
+        "-c",
+        "analytics.enabled=false",
+        "-c",
+        "feedback.enabled=false",
+        "-c",
+        'history.persistence="none"',
+        "-c",
+        'project_doc_fallback_filenames=["CLAUDE.md"]',
+        // The write guard's hook and trust ride the same `-c` layer, after the harness's own
+        // keys and before `-m` (plans/codex-write-guard.md "Runs (part 6)"); an untrusted hook
+        // would be skipped silently, so a backend with no trust passes nothing here.
+        ...(opts.guardArgs ?? []),
+        "-m",
+        opts.model,
+    ];
+    if (opts.effort !== undefined)
+        head.push("-c", `model_reasoning_effort=${opts.effort}`);
+    const args = opts.resumeId === undefined
+        ? ["exec", ...head]
+        : ["exec", "resume", opts.resumeId, ...head];
+    appendPassthroughArgs(args, opts.args, HARNESS_CODEX_FLAGS, "codexArgs");
+    args.push("-");
+    return { args, stdin: opts.prompt };
+}

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

@@ -0,0 +1,279 @@
+/** 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-agent.ts owns the spawn 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.
+ *
+ * Sessions resume by id, out of the team's `CODEX_HOME`. A continue takes the ledger's newest
+ * record of this run's kind and resumes only when it is codex's, has this cwd, carries a UUID
+ * id, and `findRollout` finds its rollout under the run's home — anything else mints a fresh
+ * 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
+ * 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. */
+import fs from "node:fs";
+import { loadConfigSafe } from "../../config/config.js";
+import { resolvedBackendConfig } from "../../config/config-views.js";
+import { backendBaseEnv, withNotesPath } from "../../process/run-marker.js";
+import { resolveBinForBackend } from "../../pi/pi-bin.js";
+import { teamRootOf, nearestTumwaterRoot } from "../../paths.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../../events/events.js";
+import { errorMessage } from "../../text/text.js";
+import { codexHome, readCodexCatalog } from "./codex-catalog.js";
+import { resumableSession } from "../session-ledger.js";
+import { codexArgs, codexEffort } from "./codex-args.js";
+import { codexEnv } from "./codex-env.js";
+import { codexHookTrust } from "./codex-hook-trust.js";
+import { codexHookArg, codexHookTrustArg, codexWriteGuardDefinition } from "./codex-write-guard.js";
+import { findRollout, rolloutLines } from "./codex-rollout.js";
+import { codexTranslator } from "./codex-stream.js";
+/** A codex thread id (a UUID format, e.g. `01a15c9d-6762-7931-814e-a3e6e64c1b51`). The
+ * stream mints it in `thread.started`; the pre-spawn ledger record carries the session name
+ * instead, so this regex is what tells a resume that a record holds a real, stream-minted id
+ * worth resuming (design §4). */
+const THREAD_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The oldest codex CLI the team targets, the sibling of `OPENCODE_MIN_VERSION`
+ * (src/agent/opencode/opencode-backend.ts) and `CLAUDE_MIN_VERSION`
+ * (src/agent/claude/claude-backend.ts): doctor's `codex version` row fails an installed CLI
+ * below this floor (plans/codex-backend.md "Hand steps", H1). */
+export const CODEX_MIN_VERSION = "0.163.0";
+/** The wall-clock bound `prepare` gives each trust lookup, mirroring lookupCodexHookTrust's
+ * own 15 s default (plans/codex-write-guard.md "Trust (parts 4–5)"). Settable so a test can
+ * shorten the bound (to 500 ms) without waiting out the real 15 s; a hand run keeps the
+ * default. */
+let codexTrustLookupTimeoutMs = 15_000;
+/** The test seam for the trust lookup bound: a test sets it to 500 ms and returns it to the
+ * 15 s default in a finally, so a hanging app-server case stays fast without a config knob. */
+export function setCodexTrustLookupTimeoutMs(ms) {
+    codexTrustLookupTimeoutMs = ms;
+}
+/** The write-guard trust `prepare` has resolved, keyed by home and hook definition, so one
+ * process looks each up at most once and a run's invocation never spawns `app-server` again. */
+const writeGuardTrust = new Map();
+/** One in-flight resolution per (home, definition) key, so concurrent runs share a single
+ * `app-server` instead of starting one each (plans/codex-write-guard.md "Trust (parts 4–5)"). */
+const writeGuardInFlight = new Map();
+/** The (home, definition) keys whose `off` warning has already been logged, so a failed lookup
+ * warns once per process instead of once per run. */
+const writeGuardWarned = new Set();
+/** Warn once per process per (home, definition) that the write guard is off. The warning rides
+ * the best-effort event feed on the run's root, skipped when there is no root (a hand run's
+ * prepared look-up must not mint a `.tumwater`). A `trust` result logs nothing. */
+function warnGuardOffOnce(key, root, state) {
+    if (state.kind !== "off")
+        return;
+    if (writeGuardWarned.has(key))
+        return;
+    writeGuardWarned.add(key);
+    if (root !== undefined) {
+        warnEventBestEffort(root, TUMWATER_SOURCE, `codex write guard off: ${state.reason}`);
+    }
+}
+/** The (home, definition) cache key shared by the single-flight and the resolved-trust map. */
+function writeGuardKey(home, definition) {
+    return `${home ?? ""}|${JSON.stringify(definition)}`;
+}
+/** The session this run uses: for a continue, the ledger's newest record of this kind when it
+ * is codex's, has this cwd, carries a UUID thread id, and `findRollout` finds its rollout
+ * under the run's home; otherwise the run is fresh (no pre-minted id — the stream names it).
+ * Returns the id and whether this is a resume, so `invocation` can name it and build `exec
+ * resume`. */
+function resolveCodexSession(run, home) {
+    if (run.continueSession && home !== undefined) {
+        const record = resumableSession(run.sessionDir, {
+            kind: run.kind,
+            agent: "codex",
+            cwd: run.cwd,
+        });
+        if (record !== null && THREAD_ID_RE.test(record.id) && findRollout(home, record.id) !== null) {
+            return { sessionId: record.id, resumed: true };
+        }
+    }
+    return { resumed: false };
+}
+/** Classify codex's stderr: the seam's stderr half for a CLI that died before emitting a
+ * `turn.failed` (the stream's own failures are classified by the translator). A run the
+ * harness killed has its own cause and is never classified here (design finding 12). The
+ * codex CLI surfaces login/model/usage failures as stream JSON, so a bare nonzero exit with
+ * no stream carries no signal this part has a verdict for — it stays unclassified and the
+ * parser's own event-derived flags stand. */
+function classifyCodexExit(info) {
+    if (info.killed)
+        return {};
+    return {};
+}
+/** The agent-backend seam's codex adapter. */
+export const codexBackend = {
+    id: "codex",
+    label: "Codex",
+    defaultBin: "codex",
+    binEnv: "TUMWATER_CODEX_BIN",
+    resolveBin(config) {
+        return resolveBinForBackend(config, this);
+    },
+    invocation(run) {
+        // The notes path rides beside the run marker, as the pi and claude adapters' envs do
+        // (withNotesPath); from part 2/4 the run saves its note through the `tumwater-notes`
+        // command on PATH, so codex configures no MCP server for notes.
+        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        // A team home of its own (`CODEX_HOME`) keeps team sessions and trust entries out of the
+        // operator's `~/.codex` (design §4, finding 10); unset leaves the operator's home.
+        const home = codexHome(resolvedBackendConfig(run.config, "codex"));
+        const env = codexEnv(base, { home });
+        const { sessionId, resumed } = resolveCodexSession(run, home);
+        const thinking = run.config.thinking;
+        // The effort (parts 5/9 and 8/9): ride the thinking level through the decoder, then gate
+        // it on the model's cataloged effort levels — a level the model does not list is never
+        // sent (codexEffort's `levels` half). No home (no catalog) leaves the value unclamped, as
+        // before part 8/9.
+        const catalog = home === undefined ? new Map() : readCodexCatalog(home);
+        const effort = thinking === undefined ? undefined : codexEffort(thinking, catalog.get(run.config.model ?? "")?.levels);
+        // The write guard's trust (part 6/9): `prepare` resolved it under this run's env and
+        // home and stored it keyed by (home, definition), so `invocation` reads it synchronously.
+        // With trust it rides the hook and its trust entry as two `-c` values (after the
+        // harness's own keys, before `-m`); with `off` or no state it passes neither, since an
+        // untrusted hook would be skipped silently anyway. tumwater never passes
+        // `--dangerously-bypass-hook-trust` (findings 1 and 4).
+        const definition = codexWriteGuardDefinition();
+        const trust = writeGuardTrust.get(writeGuardKey(home, definition));
+        const guardArgs = trust?.kind === "trust"
+            ? ["-c", codexHookArg(definition), "-c", codexHookTrustArg(trust.trust)]
+            : undefined;
+        const { args, stdin } = codexArgs({
+            model: run.config.model ?? "",
+            ...(effort !== undefined ? { effort } : {}),
+            ...(resumed && sessionId !== undefined ? { resumeId: sessionId } : {}),
+            ...(guardArgs !== undefined ? { guardArgs } : {}),
+            args: resolvedBackendConfig(run.config, "codex").args,
+            prompt: run.prompt,
+        });
+        // A resumed run returns its id so the runner's pre-spawn ledger record carries it; a fresh
+        // run has none until the stream names it (the runner's stream-mint pass appends it).
+        return { args, stdin, env, ...(resumed && sessionId !== undefined ? { sessionId } : {}) };
+    },
+    async prepare(run) {
+        // Resolve the write guard's trust under the same env and home invocation will use (the
+        // run's CODEX_HOME, plans/codex-write-guard.md "Trust (parts 4–5)"), so the trust an
+        // invocation later reads was looked up under the run's own config. It never throws a run
+        // away: a failed lookup records `off` (and warns once) and the run continues without the
+        // guard's trust.
+        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const home = codexHome(resolvedBackendConfig(run.config, "codex"));
+        const env = codexEnv(base, { home });
+        const root = nearestTumwaterRoot(run.sessionDir);
+        const definition = codexWriteGuardDefinition();
+        const key = writeGuardKey(home, definition);
+        // Single-flight per (home, definition): a run whose key is being resolved (or already
+        // resolved) shares the one in-flight lookup, so concurrent runs start one `app-server`.
+        const settled = writeGuardTrust.get(key);
+        if (settled !== undefined) {
+            warnGuardOffOnce(key, root, settled);
+            return;
+        }
+        const inFlight = writeGuardInFlight.get(key);
+        if (inFlight !== undefined) {
+            await inFlight;
+            const after = writeGuardTrust.get(key);
+            if (after !== undefined)
+                warnGuardOffOnce(key, root, after);
+            return;
+        }
+        const promise = (async () => {
+            try {
+                const trust = await codexHookTrust(root, {
+                    bin: run.agentBin,
+                    env,
+                    cwd: run.cwd,
+                    definition,
+                    timeoutMs: codexTrustLookupTimeoutMs,
+                });
+                writeGuardTrust.set(key, { kind: "trust", trust });
+            }
+            catch (error) {
+                writeGuardTrust.set(key, { kind: "off", reason: errorMessage(error) });
+            }
+        })();
+        writeGuardInFlight.set(key, promise);
+        await promise;
+        writeGuardInFlight.delete(key);
+        const state = writeGuardTrust.get(key);
+        if (state !== undefined)
+            warnGuardOffOnce(key, root, state);
+    },
+    translator() {
+        return codexTranslator();
+    },
+    imageInput(model) {
+        // Answer from the model catalog (part 8/9): a model reads images when its catalog entry's
+        // `input_modalities` say so; a model missing from the catalog — or a run with no home to
+        // read — answers false, the safe direction, so a blind image read is never silently
+        // assumed readable. The home is the team's `backends.codex.configDir`, found by walking
+        // up from the process's working directory to its `.tumwater` root and loading the config
+        // there, the same root the runs' home and account live under (like opencode's cache).
+        if (model === undefined)
+            return false;
+        const root = teamRootOf(process.cwd());
+        const { config } = loadConfigSafe(root);
+        const home = codexHome(resolvedBackendConfig(config ?? {}, "codex"));
+        if (home === undefined)
+            return false;
+        return readCodexCatalog(home).get(model)?.images === true;
+    },
+    resumable(dir, opts) {
+        const record = resumableSession(dir, { kind: opts.kind, agent: "codex", cwd: opts.cwd });
+        if (record === null || !THREAD_ID_RE.test(record.id))
+            return false;
+        const root = teamRootOf(dir);
+        const { config } = loadConfigSafe(root);
+        const home = codexHome(resolvedBackendConfig(config ?? {}, "codex"));
+        if (home === undefined)
+            return false;
+        return findRollout(home, record.id) !== null;
+    },
+    afterRun(run, invocation, translator) {
+        const ct = translator;
+        const home = codexHome(resolvedBackendConfig(run.config, "codex"));
+        const id = invocation.sessionId ?? ct.sessionId?.();
+        const fresh = invocation.sessionId === undefined;
+        // The rollout is authoritative, so its loss is worth one warning: a fresh run keeps the
+        // stream's own usage as a fallback, a resumed run records none (design §5, finding 4).
+        const fallback = () => {
+            ct.flagUsagePartial();
+            if (!fresh)
+                return [];
+            const usage = ct.turnCompletedUsage();
+            return usage !== undefined ? [JSON.stringify({ type: "run_usage", ...usage })] : [];
+        };
+        if (home === undefined || id === undefined)
+            return fallback();
+        const rollout = findRollout(home, id);
+        if (rollout === null)
+            return fallback();
+        let text;
+        try {
+            text = fs.readFileSync(rollout, "utf8");
+        }
+        catch {
+            return fallback();
+        }
+        // The stream never exposes the turn id — only the thread id that names the rollout file
+        // (real captures' `task_started.turn_id` is a different UUID), so the reader selects the
+        // last block, this run's, from the file the thread id located.
+        const { lines, switchedTo } = rolloutLines(text, {
+            requestedModel: run.config.model ?? "",
+        });
+        if (lines.length === 0)
+            return fallback();
+        // Codex can switch models on a usage limit by itself (finding 24): warn once and record
+        // the model that actually ran in the rollout's reading.
+        if (switchedTo !== undefined)
+            ct.flagModelSwitched(run.config.model ?? "", switchedTo);
+        return lines;
+    },
+    classifyExit: classifyCodexExit,
+};

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

@@ -0,0 +1,97 @@
+/** The Codex model catalog (plans/codex-backend.md design finding 14 — "Spend, free-ness,
+ * window, images" part 8/9): tumwater reads a Codex model's effort levels, default effort,
+ * context window and image input from `$CODEX_HOME/models_cache.json`, the file the CLI itself
+ * refreshes and `codex debug models` prints. Before part 8/9 the adapter assumed every Codex
+ * model had every effort and read every image; the catalog refines both, and seats the context
+ * window `seamContextWindow` reports for a codex seam. There are no prices in the catalog — the
+ * whole file knows nothing of cost — so free-ness never reads here; the codex account
+ * (codex-account.ts) owns billing.
+ *
+ * A missing, unreadable or malformed file reads as an empty catalog, the same "no data" policy
+ * pi's models.json reader uses: the adapter then answers blind (no effort gating, no images,
+ * no window), which is the safe direction for the window and image checks. The parse itself is
+ * pure and build-agnostic — no registry, config or subprocess — so the adapter, pi's
+ * seamContextWindow and the doctor can read one answer without dragging a runtime in. */
+import os from "node:os";
+import path from "node:path";
+import { cachedByStat } from "../../files/stat-cache.js";
+import { finiteNumber, isJsonObject } from "../../files/json-object.js";
+import { readJsonFile } from "../../files/json-files.js";
+import { expandHomeTilde } from "../../files/files.js";
+/** The team's Codex home for a run: `backends.codex.configDir`, a leading `~` expanded, else
+ * the CLI's default `~/.codex` — a run with no configured home keeps the operator's
+ * `CODEX_HOME`, which is exactly Codex's own default home, so the catalog and the sessions
+ * live there too and a known home always exists. Pure. Shared by the adapter, pi's
+ * seamContextWindow and the codex-account seed, so all three read one home. */
+export function codexHome(config) {
+    const dir = config.configDir;
+    if (dir === undefined)
+        return path.join(os.homedir(), ".codex");
+    return expandHomeTilde(dir, os.homedir());
+}
+/** Where a home's model catalog lives: `$CODEX_HOME/models_cache.json`. */
+export function codexModelsPath(home) {
+    return path.join(home, "models_cache.json");
+}
+/** Per-catalog cache of the parsed entries, keyed by the models_cache path: the status
+ * surfaces read the window every poll while the file changes only when the CLI refreshes it —
+ * and it grows with the model catalog — so an unchanged file costs one stat per poll instead
+ * of a re-read plus a JSON.parse of the whole file. Any write invalidates via
+ * dev/ino/mtime/size (stat-cache.cachedByStat, the same freshness check pi's providers use). */
+const catalogCache = new Map();
+/** The parsed model catalog from `$CODEX_HOME/models_cache.json`, keyed by model slug, or an
+ * empty map when the file is missing, unreadable, malformed or not shaped like what the CLI
+ * writes. A model's entry is kept only when it names a usable slug and context_window; a
+ * missing `effective_context_window_percent` reads as no window (the model is dropped), since
+ * the window is the whole point of the entry. The returned map is a copy — callers may treat
+ * their result as their own. */
+export function readCodexCatalog(home) {
+    const modelsPath = codexModelsPath(home);
+    return (cachedByStat(catalogCache, modelsPath, modelsPath, () => {
+        const out = new Map();
+        // readJsonFile is the shared "missing or torn reads as no data" policy for a JSON
+        // object file; the nested `models` array gets the same isJsonObject/Array guards.
+        const doc = readJsonFile(modelsPath);
+        if (doc === null)
+            return out;
+        const models = doc.models;
+        if (!Array.isArray(models))
+            return out;
+        for (const model of models) {
+            const entry = parseModelEntry(model);
+            if (entry !== undefined)
+                out.set(entry.slug, entry.entry);
+        }
+        return out;
+    }, (models) => new Map([...models].map(([slug, entry]) => [slug, { ...entry, levels: [...entry.levels] }]))) ?? new Map());
+}
+/** One catalog model entry as the map needs it: the slug to key by plus the parsed entry. The
+ * entry is kept only when the slug and context window are usable; any other missing field
+ * (levels, modalities, default level) just reads as absent on the entry. */
+function parseModelEntry(model) {
+    if (!isJsonObject(model) || typeof model.slug !== "string")
+        return undefined;
+    const context = finiteNumber(model.context_window, Number.NaN);
+    const percent = finiteNumber(model.effective_context_window_percent, Number.NaN);
+    if (!Number.isFinite(context) || !Number.isFinite(percent))
+        return undefined;
+    const levels = [];
+    if (Array.isArray(model.supported_reasoning_levels)) {
+        for (const level of model.supported_reasoning_levels) {
+            if (isJsonObject(level) && typeof level.effort === "string")
+                levels.push(level.effort);
+        }
+    }
+    const modalities = model.input_modalities;
+    return {
+        slug: model.slug,
+        entry: {
+            levels,
+            ...(typeof model.default_reasoning_level === "string"
+                ? { defaultLevel: model.default_reasoning_level }
+                : {}),
+            contextWindow: Math.round((context * percent) / 100),
+            images: Array.isArray(modalities) && modalities.includes("image"),
+        },
+    };
+}

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

@@ -0,0 +1,18 @@
+/** 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;
+}