tumwater 0.1.3 → 0.2.0

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

@@ -0,0 +1,184 @@
+// vocabulary: plain
+/** The data half of OpenCode free-ness (plans/opencode-backend.md §7; part 6a/7): a bounded
+ * fetch of models.dev's `api.json` — the catalog OpenCode itself caches (finding 10) — a parse
+ * that keeps only the providers the config routes through OpenCode, a cache at
+ * `.tumwater/state/opencode-models.json` that survives a failed fetch, and
+ * `opencodeModelFree` as the one predicate part 6b/7's seam reads. No seam is wired here: that
+ * is part 6b/7 (the budget gate), part 6c/7 (a billedAt demotion on an observed cost) and
+ * part 7/7 (a startup-cache seed and doctor), so this module's only callers today are its own
+ * tests. */
+import { spawnSync } from "node:child_process";
+import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";
+import { opencodeModelsPath } from "../../paths.js";
+import { logEventBestEffort } from "../../events/events.js";
+import { opencodeQualifiedModel } from "./opencode-args.js";
+/** models.dev's catalog, the data OpenCode caches in its database `kv` table (finding 10). */
+const CATALOG_URL = "https://models.dev/api.json";
+/** The fetch bound (finding 10; the plan's 30 s): OpenCode prices from the same endpoint at
+ * most once a day, so a slow or wedged network must not hold the team up. */
+const CATALOG_FETCH_TIMEOUT_MS = 30_000;
+/** How long a fetched cache is trusted before it is refreshed. */
+const CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const defaultFetch = async (url, timeoutMs) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`models.dev catalog ${res.status} ${res.statusText}`);
+    return res.json();
+};
+/** GET models.dev's catalog, bounded at 30 s. Returns the parsed JSON body, or the injected
+ * (or default) fetch throws on a failure. So a spare `opencode` binary is never needed just to
+ * cable this up; the version check that forces a refresh lives in refreshOpencodeCatalog. */
+export async function fetchOpencodeCatalog(fetchFn = defaultFetch) {
+    return fetchFn(CATALOG_URL, CATALOG_FETCH_TIMEOUT_MS);
+}
+/** Parse models.dev's `api.json` into the models the config routes through OpenCode: always the
+ * `opencode` provider, plus every provider named in `providers` (the config's
+ * `opencode/<provider>/…` routes — `opencode-go` and so on). The live `GET /api.json` returns
+ * the provider map at the top level; OpenCode's cached copy wraps that same map under a `body`
+ * key (the 2.0.32 capture in test/fixtures), so both shapes are accepted. Each kept model is
+ * keyed `<provider>/<model>`. A model never present yields no entry, so an unknown model is
+ * automatically "not free" to opencodeModelFree. */
+export function parseOpencodeCatalog(body, providers) {
+    const out = {};
+    const root = body;
+    // models.dev's api.json IS the provider map; OpenCode's cached copy wraps that map under `body`.
+    const wrapped = root?.body;
+    const catalog = typeof wrapped === "object" && wrapped !== null && !Array.isArray(wrapped)
+        ? wrapped
+        : (body ?? {});
+    for (const [provider, providerRaw] of Object.entries(catalog)) {
+        if (provider !== "opencode" && !providers.includes(provider))
+            continue;
+        const providerInfo = providerRaw;
+        if (providerInfo?.models === undefined)
+            continue;
+        for (const [id, raw] of Object.entries(providerInfo.models)) {
+            const m = raw;
+            // Only a present cost block marks a model free: a missing cost block is unknown price data,
+            // and treating it as $0 is the unsafe direction for a budget gate.
+            const cost = m?.cost;
+            const input = cost?.input ?? 0;
+            const output = cost?.output ?? 0;
+            const model = { free: cost !== undefined && input === 0 && output === 0 };
+            if (cost !== undefined) {
+                model.inputPerM = input;
+                model.outputPerM = output;
+            }
+            if (m?.limit?.context !== undefined)
+                model.context = m.limit.context;
+            if (m?.modalities?.input !== undefined)
+                model.images = m.modalities.input.includes("image");
+            const efforts = m?.reasoning_options
+                ?.filter((r) => r.type === "effort")
+                .flatMap((r) => r.values ?? []);
+            if (efforts !== undefined && efforts.length > 0)
+                model.efforts = efforts;
+            out[`${provider}/${id}`] = model;
+        }
+    }
+    return out;
+}
+/** True when the catalog says the model is free and no run has marked it billed (part 6c/7).
+ * A model missing from the cache, a priced one, and a free one with `billedAt` set are all not
+ * free — the safe direction for a budget gate. */
+export function opencodeModelFree(cache, model) {
+    const entry = cache.models[model];
+    return entry !== undefined && entry.free && entry.billedAt === undefined;
+}
+/** The catalog cache key for an opencode run's resolved selector: the `<provider>/<model>`
+ * form part 6a/7 keys the cache by. Delegates the bare-gateway-prefix rule to
+ * opencode-args.ts's opencodeQualifiedModel (the single home), so the key a run is priced by
+ * always matches the id a run is invoked by. */
+export function opencodeModelKey(selector) {
+    return opencodeQualifiedModel(selector);
+}
+/** Demote a catalog-free model the moment a run bills it (part 6c/7): when a run reports a
+ * nonzero cost on a model the cache calls free, mark that entry priced (`billedAt`) in the
+ * cache and log `opencode_free_model_billed` {model, costUsd} once. A subsequent priced run on
+ * the same model sees `billedAt` already set and stays silent, and the next
+ * `opencodeModelFree` answer for it is false. A run reporting $0, a priced model, or an
+ * unknown model leaves the cache untouched — a $0 run never demotes (missing and priced
+ * models are already "not free" to opencodeModelFree). Best-effort like observeClaudeAccount:
+ * the caller wraps the write/log in try/catch so an unwritable cache or feed never fails the
+ * run that observed it. Returns the cache after the observation, or null when nothing changed. */
+export function observeOpencodeRun(root, run, opts) {
+    const cache = readOpencodeCache(root);
+    const entry = cache.models[run.model];
+    if (entry === undefined || !entry.free || entry.billedAt !== undefined || run.costUsd <= 0) {
+        return null;
+    }
+    entry.billedAt = opts.now !== undefined ? opts.now() : Date.now();
+    writeOpencodeCache(root, cache);
+    const log = opts.log !== undefined ? opts.log : (e) => logEventBestEffort(root, e);
+    log({ source: opts.source, type: "opencode_free_model_billed", model: run.model, costUsd: run.costUsd });
+    return cache;
+}
+/** Read the cached catalog, or an empty one (fetchedAt 0, no models) when the file is missing
+ * or malformed — the harness's no-data policy, so a torn write reads as "needs a refresh".
+ * Exported so the opencode backend's adapter (part 6d/7) and doctor can read the same cache
+ * without triggering a network fetch. The synchronous read the sync poll surfaces
+ * (pollBudgetGate, collectBudget) use to thread the catalog-cache into their free-ness reads
+ * (part 6b/7); the async refresh (which runs once per process at the startup gate) is what
+ * fills the file in. */
+export function readOpencodeCache(root) {
+    const existing = readJsonFile(opencodeModelsPath(root));
+    if (existing !== null && typeof existing.fetchedAt === "number" && existing.models !== undefined && typeof existing.models === "object" && !Array.isArray(existing.models)) {
+        return {
+            fetchedAt: existing.fetchedAt,
+            cliVersion: typeof existing.cliVersion === "string" ? existing.cliVersion : undefined,
+            models: existing.models,
+        };
+    }
+    return { fetchedAt: 0, models: {} };
+}
+/** Persist the catalog cache atomically under `.tumwater/state/`. */
+export function writeOpencodeCache(root, cache) {
+    writeJsonAtomic(opencodeModelsPath(root), cache);
+}
+/** Read the installed opencode CLI's version, undefined when it cannot be read (no binary, a
+ * timeout, or a spawn failure). A changed version forces a catalog refresh: OpenCode serves from
+ * the same models.dev data, so a new CLI may route to providers the old cache does not know.
+ * `bin` is the configured opencode binary (default `opencode` on PATH), so the seed probes the
+ * same binary the runs spawn. */
+function readCliVersion(bin = "opencode") {
+    try {
+        const res = spawnSync(bin, ["--version"], { stdio: "pipe", encoding: "utf8", timeout: 5_000 });
+        const version = res.stdout?.trim();
+        return version === undefined || version === "" ? undefined : version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Return a cache fresh enough to price by, fetching and persisting when the current one is
+ * missing, stale (older than 24 h) or fetched by a different `opencode --version`. A failed
+ * fetch keeps the old cache (logging one warning) so the team still prices by the last good
+ * data; `billedAt` from the old cache survives a successful refresh (part 6c/7). */
+export async function refreshOpencodeCatalog(root, opts) {
+    const now = opts.now !== undefined ? opts.now() : Date.now();
+    const version = opts.cliVersion !== undefined ? opts.cliVersion : readCliVersion(opts.cliBin);
+    const current = readOpencodeCache(root);
+    const fresh = current.fetchedAt !== 0 &&
+        now - current.fetchedAt < CATALOG_CACHE_TTL_MS &&
+        (version === undefined || current.cliVersion === version);
+    if (fresh)
+        return current;
+    let body;
+    try {
+        body = await fetchOpencodeCatalog(opts.fetch);
+    }
+    catch {
+        opts.warn?.(`open code model catalog fetch failed; keeping the cached copy`);
+        return current.fetchedAt === 0 ? { fetchedAt: 0, cliVersion: version, models: {} } : current;
+    }
+    const parsed = parseOpencodeCatalog(body, opts.providers);
+    for (const key of Object.keys(parsed)) {
+        const fresh = parsed[key];
+        const old = current.models[key];
+        if (fresh !== undefined && old?.billedAt !== undefined)
+            fresh.billedAt = old.billedAt;
+    }
+    const cache = { fetchedAt: now, cliVersion: version, models: parsed };
+    writeOpencodeCache(root, cache);
+    return cache;
+}

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

@@ -0,0 +1,188 @@
+// vocabulary: plain
+/** Building one OpenCode run's injected config (`OPENCODE_CONFIG_CONTENT`) (plans/opencode-
+ * backend.md "The invocation") — pure JSON construction, with no subprocess. The config
+ * applies after the operator's global and project files, so only managed config wins over it:
+ * the gate-safe isolation switches (snapshots off, updates off, six denials), `enabled →
+ * disabled: true` for every operator MCP server (config merges, so disabling is the only way
+ * to remove one), and an `instructions` entry mirroring claude's AGENTS.md handling. No
+ * tool is disabled beyond the six gate-safe denials — denying `read` trips the free-tier gate
+ * (finding 11). Part 5/7 wires this string into the run's environment.
+ *
+ * From part 3/4 tumwater no longer adds an MCP server of its own: run notes ride the
+ * `tumwater-notes` command on PATH, so every operator MCP server is disabled alike — an
+ * operator server named `tumwater` is disabled like any other (a later config replaces a
+ * server object whole, design decision 8 and plans/opencode-backend.md "The invocation"). No
+ * XDG/config files are read here except the operator's global opencode config, and that only
+ * to enumerate its MCP server names (operatorMcpNames): a broken or missing file yields `[]`
+ * here, and doctor reports it in part 7/7. */
+import fs from "node:fs";
+import path from "node:path";
+/** The operator's global opencode config lives in `$XDG_CONFIG_HOME/opencode/` (or
+ * `~/.config/opencode/`), in `config.json`, `opencode.json` or `opencode.jsonc`. */
+const OPERATOR_CONFIG_FILES = ["config.json", "opencode.json", "opencode.jsonc"];
+/** The six gate-safe denials (plans/opencode-backend.md "The invocation", findings 11–12).
+ * `read` is never denied — it trips the free-tier gate. `shell`, `glob`, `grep`, `edit` and
+ * `write` stay allowed for parity with pi. */
+const DENIED_PERMISSIONS = [
+    { action: "execute", resource: "*", effect: "deny" },
+    { action: "subagent", resource: "*", effect: "deny" },
+    { action: "webfetch", resource: "*", effect: "deny" },
+    { action: "websearch", resource: "*", effect: "deny" },
+    { action: "question", resource: "*", effect: "deny" },
+    { action: "skill", resource: "*", effect: "deny" },
+];
+/** True at `i` when a `//` line comment or a `/*`-style block comment starts there. */
+function isCommentStart(src, i) {
+    return src[i] === "/" && (src[i + 1] === "/" || src[i + 1] === "*");
+}
+/** Advance `j` past any whitespace and comments, for a position that is never inside a string.
+ * Returns the index of the next significant (non-comment, non-whitespace) character, or
+ * `src.length` when the input ends in comments/whitespace. */
+function skipWhitespaceAndComments(src, j) {
+    while (j < src.length) {
+        const c = src[j];
+        if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+            j += 1;
+            continue;
+        }
+        if (c === "/" && src[j + 1] === "/") {
+            while (j < src.length && src[j] !== "\n")
+                j += 1;
+            continue;
+        }
+        if (c === "/" && src[j + 1] === "*") {
+            j += 2;
+            while (j < src.length && !(src[j] === "*" && src[j + 1] === "/"))
+                j += 1;
+            j += 2;
+            continue;
+        }
+        break;
+    }
+    return j;
+}
+/** Strip comments and trailing commas from a JSONC string so a strict JSON parse succeeds.
+ * Walks the string so a `//` or a block-comment opener, and `,}` / `,]`, inside a normal
+ * double-quoted string value survive (escape sequences included); comments and trailing
+ * commas are removed only outside strings, where they are legal JSONC but not JSON. A
+ * trailing comma is dropped when the next significant character — past any whitespace AND
+ * any comment — is a closing brace or bracket, so a comma then a comment then `}` strips
+ * correctly. */
+function stripJsonc(src) {
+    let out = "";
+    let inString = false;
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        const next = src[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\" && next !== undefined) {
+                out += next;
+                i += 2;
+            }
+            else {
+                if (c === '"')
+                    inString = false;
+                i += 1;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            i += 1;
+            continue;
+        }
+        if (isCommentStart(src, i)) {
+            i = skipWhitespaceAndComments(src, i);
+            continue;
+        }
+        if (c === ",") {
+            // A trailing comma may be followed by whitespace and comments before the closing
+            // brace/bracket (`,\n  // c\n }`); look past all of it to decide, without touching a
+            // comma inside a string value.
+            const j = skipWhitespaceAndComments(src, i + 1);
+            if (src[j] === "}" || src[j] === "]") {
+                i += 1;
+                continue;
+            }
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+/** Read the MCP server names in the operator's global opencode config. Each name is a server
+ * the managed config must explicitly disable (config merges, so it cannot be removed). Reads
+ * both config shapes: the keys of V2's `mcp.servers` plus V1-shaped `mcp.<name>` keys other
+ * than `servers`. Returns `[]` for a missing file, an unreadable file, or one that does not
+ * 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 dir = path.join(configHome, "opencode");
+    for (const file of OPERATOR_CONFIG_FILES) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(file.endsWith(".jsonc") ? stripJsonc(text) : text);
+        }
+        catch {
+            return [];
+        }
+        const mcp = parsed?.mcp;
+        if (mcp === undefined || mcp === null)
+            return [];
+        if (typeof mcp !== "object" || Array.isArray(mcp))
+            return [];
+        const names = new Set();
+        const servers = mcp.servers;
+        if (typeof servers === "object" && servers !== null && !Array.isArray(servers)) {
+            for (const key of Object.keys(servers))
+                names.add(key);
+        }
+        // V1-shaped `mcp.<name>` keys, other than the V2 `servers` grouping.
+        for (const key of Object.keys(mcp)) {
+            if (key !== "servers")
+                names.add(key);
+        }
+        return [...names];
+    }
+    return [];
+}
+/** True when the worktree has a `CLAUDE.md` and no `AGENTS.md`: OpenCode reads `AGENTS.md`
+ * only, so the managed config injects `CLAUDE.md` — but only when the repo has no `AGENTS.md`,
+ * exactly the mirror of claude's `shouldAppendAgents`. */
+function shouldInjectClaudeMd(cwd) {
+    return fs.existsSync(path.join(cwd, "CLAUDE.md")) && !fs.existsSync(path.join(cwd, "AGENTS.md"));
+}
+/** Build the injected opencode config JSON string. Never reads the worktree beyond the
+ * CLAUDE.md/AGENTS.md probe. */
+export function opencodeConfigContent(opts) {
+    const config = {
+        snapshots: false,
+        update: "disable",
+        permissions: DENIED_PERMISSIONS,
+    };
+    if (opts.toolOutput !== undefined) {
+        config.tool_output = { max_lines: opts.toolOutput.maxLines, max_bytes: opts.toolOutput.maxBytes };
+    }
+    const servers = {};
+    for (const name of opts.operatorMcpNames) {
+        // Every operator server is disabled alike: an operator server named `tumwater` gets no
+        // special treatment now that tumwater ships no MCP server of its own (part 3/4).
+        servers[name] = { disabled: true };
+    }
+    if (Object.keys(servers).length > 0)
+        config.mcp = { servers };
+    if (shouldInjectClaudeMd(opts.cwd))
+        config.instructions = ["CLAUDE.md"];
+    return JSON.stringify(config);
+}

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

@@ -0,0 +1,36 @@
+// vocabulary: plain
+/** Building the environment for one opencode run (plans/opencode-backend.md "The invocation")
+ * — pure scrub-and-set over a base environment, with no subprocess. The caller layers the
+ * run-marker and the macOS preload on first (claude's adapter shows the pie pattern), then
+ * hands the result here alongside the injected config and the session database path.
+ *
+ * Inherited OpenCode session variables are scrubbed (every `OPENCODE_*` except the operator's
+ * `OPENCODE_API_KEY`, plus the bare `OPENCODE` and `AI_AGENT`): a run spawned from inside an
+ * OpenCode session must not attach to that session's server, config or database, and `AI_AGENT`
+ * must not leak so the shell tool sets its own (finding 16). The set half disables Claude Code
+ * interop and its skills, auto-update and the file watcher, and isolates the run to its own
+ * database and injected config.
+ *
+ * No shell-timeout variable exists in 2.0.32 (finding 16), so none is set; the dialect tells
+ * the model to pass `timeout` for the check (§5). `XDG_CONFIG_HOME` and its siblings are NOT
+ * set: OpenCode's shell-tool children inherit the environment, and pointing XDG at a private
+ * dir would stop `git` reading `~/.config/git/config`, losing commits' author identity (§3). */
+/** Build the opencode process environment from `base`. Never mutates `base`. */
+export function opencodeEnv(base, opts) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        // Everything an inherited OpenCode session set is scrubbed — server, config, database,
+        // client and session id — except the operator's API key, which is operator intent and must
+        // survive. `AI_AGENT` goes too, so the shell tool sets its own (finding 16).
+        if (key === "OPENCODE" || (key.startsWith("OPENCODE_") && key !== "OPENCODE_API_KEY") || key === "AI_AGENT")
+            continue;
+        env[key] = value;
+    }
+    env.OPENCODE_DISABLE_CLAUDE_CODE = "1";
+    env.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = "1";
+    env.OPENCODE_DISABLE_AUTOUPDATE = "1";
+    env.OPENCODE_DISABLE_FILEWATCHER = "1";
+    env.OPENCODE_DB = opts.dbPath;
+    env.OPENCODE_CONFIG_CONTENT = opts.configContent;
+    return env;
+}

package/dist/src/agent/opencode/opencode-session-id.js

@@ -0,0 +1,37 @@
+// vocabulary: plain
+/** Minting an OpenCode session id (plans/opencode-backend.md "Sessions", finding 3) — a pure
+ * reproduction of OpenCode's `Identifier.descending()` (packages/schema/src/identifier.ts), so
+ * a fresh run's `--session` id is accepted by the free-tier gate. A `ses_…` id in any other
+ * shape is refused with a 403 (finding 3), so this must match OpenCode exactly.
+ *
+ * The id is `ses_` + 12 hex digits + 14 base-62 characters. The hex is the low 48 bits of the
+ * bitwise NOT of (Unix milliseconds × 4096 + a per-millisecond counter), big-endian; the 14
+ * characters are drawn from `0-9A-Za-z` one random byte each. */
+import crypto from "node:crypto";
+/** The 62-character alphabet OpenCode draws a session id's trailing characters from. */
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+/** Per-process minting state, mirroring OpenCode's per-millisecond counter: the counter
+ * restarts at 1 for each new millisecond, and increments within the same millisecond so two
+ * ids minted in one tick still differ in their hex. */
+let lastMintMs = -1;
+let counter = 0;
+/** Mint an OpenCode session id. `now` is a Unix-millisecond epoch (injected for tests);
+ * `randomBytes` supplies the 14 base-62 characters (defaults to `crypto.randomBytes`, so the
+ * trailing part is random, never guessed from the visible prefix). */
+export function mintOpencodeSessionId(now = Date.now(), randomBytes = (n) => crypto.randomBytes(n)) {
+    if (now === lastMintMs)
+        counter += 1;
+    else {
+        lastMintMs = now;
+        counter = 1;
+    }
+    // `Identifier.descending()`: current = now × 4096 + counter, then the low 48 bits of ~current.
+    const current = BigInt(now) * 0x1000n + BigInt(counter);
+    const hex = ((~current) & 0xffffffffffffn).toString(16).padStart(12, "0");
+    const bytes = randomBytes(14);
+    let suffix = "";
+    for (let i = 0; i < 14; i += 1) {
+        suffix += ALPHABET[bytes[i] % 62];
+    }
+    return `ses_${hex}${suffix}`;
+}