@gr8ful/spf 0.15.0 → 0.17.0

package/dist/cli/commands/ui.js

@@ -6,23 +6,33 @@ import { runUi } from "../../ui/server/serve.js";
 export async function uiCommand(argv) {
     const { options, flags } = parseCli(argv, ["cwd", "config", "db", "port"], ["no-open"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
-    let dbPath;
+    let db;
+    let sessionsDir;
+    let label;
     if (options["db"]) {
-        dbPath = path.resolve(anchor.cwd, options["db"]);
+        // `--db <path>` always names a local sqlite file — there is no D1
+        // equivalent of "point at this one file" from the CLI yet.
+        const dbPath = path.resolve(anchor.cwd, options["db"]);
+        db = { kind: "sqlite", path: dbPath };
+        label = dbPath;
     }
     else {
         const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
-        dbPath = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db).db_path;
+        const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
+        db = dataPaths.db;
+        sessionsDir = dataPaths.sessions_dir;
+        label = db.kind === "sqlite" ? db.path : `d1:${db.database_id}`;
     }
     try {
         const handle = await runUi({
-            dbPath,
+            db,
+            sessionsDir,
             webDir: paths.WEB_DIR,
             port: options["port"] ? Number.parseInt(options["port"], 10) : undefined,
             open: !flags["no-open"],
         });
         console.log(`[spf] ui        ${handle.url}`);
-        console.log(`[spf] db        ${dbPath}`);
+        console.log(`[spf] db        ${label}`);
         // runUi() already registers SIGINT/SIGTERM handlers that exit the
         // process; just keep this call from returning until then.
         await new Promise(() => { });

package/dist/cli/commands/watch.js

@@ -217,14 +217,14 @@ export async function watchInitCommand(argv) {
     return 0;
 }
 /** Shared by `runChain`/`runRefine`/the fan-out lane's dispatch: best-effort enrichment of a generic "didn't succeed" message with the first phase that actually failed, read back from the worktree's own (symlinked) trace db. Top-level (not a `watchCommand` local) so `makeWatchFanoutDispatch` below can share it — see that factory's own doc comment for why. */
-function detailFromFailedPhase(cfg, cwd, adwId, prefix) {
+async function detailFromFailedPhase(cfg, cwd, adwId, prefix) {
     let detail = prefix;
     let db;
     try {
         const wtAnchor = paths.resolveAnchor(cwd);
         const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-        db = new SfDb(wtDataPaths.db_path);
-        const failed = db.phases(adwId).find((p) => p.status === "fail");
+        db = await SfDb.open(wtDataPaths.db, wtDataPaths.sessions_dir);
+        const failed = (await db.phases(adwId)).find((p) => p.status === "fail");
         if (failed)
             detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
     }
@@ -232,7 +232,7 @@ function detailFromFailedPhase(cfg, cwd, adwId, prefix) {
         // best-effort — the generic message above still points at where to look
     }
     finally {
-        db?.close();
+        await db?.close();
     }
     return detail;
 }
@@ -245,14 +245,13 @@ function detailFromFailedPhase(cfg, cwd, adwId, prefix) {
  * is a nice-to-have, not something that gets to block the PR-open flow
  * it's decorating. Top-level for the same reason as `detailFromFailedPhase`.
  */
-function reviewSummaryFor(cfg, cwd, adwId) {
+async function reviewSummaryFor(cfg, cwd, adwId) {
     let db;
     try {
         const wtAnchor = paths.resolveAnchor(cwd);
         const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-        db = new SfDb(wtDataPaths.db_path);
-        const envelope = db
-            .envelopes(adwId)
+        db = await SfDb.open(wtDataPaths.db, wtDataPaths.sessions_dir);
+        const envelope = (await db.envelopes(adwId))
             .filter((e) => e.output_type === ReviewOutput.name)
             .at(-1); // the LATEST verdict — a revise loop can produce several
         if (!envelope?.payload_json)
@@ -264,7 +263,7 @@ function reviewSummaryFor(cfg, cwd, adwId) {
         return undefined; // best-effort — see the doc comment above
     }
     finally {
-        db?.close();
+        await db?.close();
     }
 }
 /**
@@ -309,14 +308,14 @@ export function makeWatchFanoutDispatch(cfg, configPaths, dataPaths, chainDef) {
      * a shared handle in — the same per-call shape `detailFromFailedPhase`/
      * `reviewSummaryFor` above already use against the same WAL db.
      */
-    const readMetrics = (adwId) => {
-        if (!existsSync(dataPaths.db_path))
-            return { gate_passes: 0, gate_failures: 0, cost: 0, tokens: 0 };
+    const readMetrics = async (adwId) => {
         let db;
         try {
-            db = new SfDb(dataPaths.db_path);
-            const gates = db.gates(adwId);
-            const session = db.session(adwId);
+            if (!(await SfDb.exists(dataPaths)))
+                return { gate_passes: 0, gate_failures: 0, cost: 0, tokens: 0 };
+            db = await SfDb.open(dataPaths.db, dataPaths.sessions_dir);
+            const gates = await db.gates(adwId);
+            const session = await db.session(adwId);
             // `passed` is a SQLite integer boolean that CAN be NULL on a row an
             // older tracer wrote. Counted explicitly in both directions, never as
             // `!g.passed`: a NULL is unknown, and letting it read as a failure
@@ -332,7 +331,7 @@ export function makeWatchFanoutDispatch(cfg, configPaths, dataPaths, chainDef) {
             return { gate_passes: 0, gate_failures: 0, cost: 0, tokens: 0 };
         }
         finally {
-            db?.close();
+            await db?.close();
         }
     };
     /**
@@ -341,24 +340,25 @@ export function makeWatchFanoutDispatch(cfg, configPaths, dataPaths, chainDef) {
      * candidate id. Safe direction is FALSE (see `WatchFanoutDeps.adwIdsFree`'s
      * own doc comment): an unreadable db reports "taken" rather than "free".
      */
-    const adwIdsFree = (adwIds) => {
-        if (!existsSync(dataPaths.db_path))
-            return true; // no db yet — nothing to collide with
+    const adwIdsFree = async (adwIds) => {
         let db;
         try {
-            db = new SfDb(dataPaths.db_path);
-            return adwIds.every((id) => db.session(id) === null);
+            if (!(await SfDb.exists(dataPaths)))
+                return true; // no db yet — nothing to collide with
+            db = await SfDb.open(dataPaths.db, dataPaths.sessions_dir);
+            const results = await Promise.all(adwIds.map((id) => db.session(id)));
+            return results.every((session) => session === null);
         }
         catch {
             return false;
         }
         finally {
-            db?.close();
+            await db?.close();
         }
     };
-    const reviewFor = (opts) => ({
+    const reviewFor = async (opts) => ({
         reviewRequired: resolveRequiredAgents(chainDef, opts.chainOptions).includes("reviewer"),
-        reviewSummary: reviewSummaryFor(cfg, opts.cwd, opts.adwId),
+        reviewSummary: await reviewSummaryFor(cfg, opts.cwd, opts.adwId),
     });
     return { runAttempt, readMetrics, adwIdsFree, reviewFor };
 }
@@ -586,9 +586,9 @@ export async function watchCommand(argv) {
         // is reflected here too, not just each chain's static/YAML default.
         const reviewRequired = resolveRequiredAgents(chainDef, opts.chainOptions).includes("reviewer");
         if (code === 0) {
-            return { accepted: true, adwId: opts.adwId, detail: "", reviewRequired, reviewSummary: reviewSummaryFor(cfg, opts.cwd, opts.adwId) };
+            return { accepted: true, adwId: opts.adwId, detail: "", reviewRequired, reviewSummary: await reviewSummaryFor(cfg, opts.cwd, opts.adwId) };
         }
-        const detail = detailFromFailedPhase(cfg, opts.cwd, opts.adwId, `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
+        const detail = await detailFromFailedPhase(cfg, opts.cwd, opts.adwId, `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
         return { accepted: false, adwId: opts.adwId, detail, reviewRequired };
     };
     /**
@@ -620,7 +620,7 @@ export async function watchCommand(argv) {
         // comment for the KNOWN LIMITATION this fixes.
         const code = await withRunScope(opts.adwId, () => runChainDef(chainDef, ctx, opts.chainOptions));
         if (code !== 0) {
-            const detail = detailFromFailedPhase(cfg, opts.cwd, opts.adwId, `Refine chain "${cfg.watch.refine.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
+            const detail = await detailFromFailedPhase(cfg, opts.cwd, opts.adwId, `Refine chain "${cfg.watch.refine.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
             return { accepted: false, adwId: opts.adwId, detail, created: [], questions: [], split: [] };
         }
         const wtAnchor = paths.resolveAnchor(opts.cwd);

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import path from "node:path";
 import * as agents from "../core/agents.js";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
+import * as agentOpencode from "../core/agent_opencode.js";
 import * as notify from "../core/notify/notifier.js";
 import * as otel from "../core/otel.js";
 import * as paths from "../core/paths.js";
@@ -212,7 +213,7 @@ export async function main() {
                 process.exitCode = await eventsCommand(rest);
                 return;
             case "abort":
-                process.exitCode = abortCommand(rest);
+                process.exitCode = await abortCommand(rest);
                 return;
             default: {
                 const chain = findChain(cmd);
@@ -243,6 +244,7 @@ export async function main() {
         // agent_cc.ts's shutdown() just kills any still-running claude children.
         await agentFlue.shutdown();
         await agentCc.shutdown();
+        await agentOpencode.shutdown();
         // Belt-and-braces alongside the per-run `sandbox.withRunScope` wraps in
         // dispatchChain/watch/fanout: catches any sandboxed run's lease this
         // process still holds when the CLI exits (a per-run wrap that itself

package/dist/cli/interview.d.ts

@@ -6,6 +6,7 @@ export interface DetectedContext {
     gitName?: string;
     scripts: Record<string, string>;
     claudeOnPath: boolean;
+    opencodeOnPath: boolean;
     /** Whatever's already in `.env` — shown masked so a re-run can offer "keep current" instead of asking blind. */
     existingEnv: Map<string, string>;
     /** The packaged roster's agent names (planner, builder, scout, reviewer, documenter today) — read from the built-in config so a 6th agent added there needs no interview change. */

package/dist/cli/interview.js

@@ -62,6 +62,7 @@ export function gatherContext(repoRoot, existingEnv = new Map()) {
         gitName: gitConfigValue(repoRoot, "user.name"),
         scripts: readScripts(repoRoot),
         claudeOnPath: binaryOnPath("claude"),
+        opencodeOnPath: binaryOnPath("opencode"),
         existingEnv,
         rosterNames: readRosterNames(),
     };
@@ -90,10 +91,38 @@ export async function runInterview(asker, ctx) {
     asker.heading("Coding agent");
     const codingAgent = await asker.select("Which backend runs each agent?", [
         { value: "claude_code", label: "claude_code — shells out to the `claude` CLI you already use", hint: "cc" },
+        { value: "opencode", label: "opencode — shells out to the `opencode` CLI, provider/model-id (anthropic, ollama, ...)", hint: "oc" },
         { value: "flue", label: "flue — in-process, provider/model-id (openai, anthropic, openrouter, ...)" },
     ], "claude_code");
     defaults.coding_agent = codingAgent;
-    if (codingAgent === "claude_code") {
+    if (codingAgent === "opencode") {
+        if (!ctx.opencodeOnPath) {
+            asker.note("warning: `opencode` was not found on PATH — install it (npm install -g opencode-ai), or pick a launch command below, before running spf.");
+        }
+        const launchCommand = await asker.text("Launch command for the `opencode` CLI", { default: "opencode" });
+        if (launchCommand !== "opencode")
+            configEnv["SPF_OPENCODE_CMD"] = launchCommand;
+        // opencode's own model vocabulary is "provider/model-id" — same shape
+        // Flue speaks (see agent_opencode.ts's module doc comment) — so this
+        // asks the same way the flue branch below does, minus Flue's own
+        // resolveModel() validation (that function belongs to agent_flue.ts,
+        // not opencode).
+        const model = await asker.text('Model ("provider/model-id", opencode\'s own vocabulary)', {
+            default: "anthropic/claude-sonnet-4-6",
+            validate: (val) => (val.trim() ? null : "required"),
+        });
+        defaults.model = model;
+        asker.note("opencode manages its own authentication (`opencode auth login`, or a provider's own env var like ANTHROPIC_API_KEY) — spf does not drive that login flow. `spf doctor` checks for ~/.local/share/opencode/auth.json (informational only).");
+        // Same pinned-roster fix the claude_code/ollama/cloudflare branches below
+        // already apply: the packaged roster pins planner/reviewer/documenter to
+        // their own Flue-style provider/model-id strings, which always win over
+        // defaults.model — override all three to the model chosen above.
+        for (const name of ["planner", "reviewer", "documenter"]) {
+            agentOverrides.push({ name, model: defaults.model });
+        }
+        notes.push("planner/reviewer/documenter pin their own model in the packaged roster and always win over defaults.model — overriding all three to match, since they're already valid provider/model-id strings for opencode too, but not necessarily ones you've configured auth for.");
+    }
+    else if (codingAgent === "claude_code") {
         if (!ctx.claudeOnPath) {
             asker.note("warning: `claude` was not found on PATH — install it (or pick a launch command below) before running spf.");
         }
@@ -505,10 +534,63 @@ export async function runInterview(asker, ctx) {
         const protectedList = protectedFiles.split(",").map((s) => s.trim()).filter(Boolean);
         if (protectedList.join(",") !== ".spf/,spf.config.yaml")
             defaults.protected_files = protectedList;
-        const dbPath = await asker.text("observability.db", { default: ".spf/data/spf.db" });
+        // Local sqlite (today's default, unchanged) or a remote Cloudflare D1
+        // database (SPF #66, PR 3) — `resolveObservabilityDb`/`resolveDataPaths`
+        // (data_types.ts/paths.ts, PR 1+2) already accept either shape; this is
+        // just wiring the interview up to the option. `spf init --yes` never
+        // reaches this "advanced" gate at all, so it stays zero-prompt and
+        // defaults to local exactly as before.
+        asker.note("Data egress: choosing remote (D1) sends the complete trace — your raw request text, tool arguments and results, envelope payloads, and gate violation details, not just spans or metadata — to Cloudflare on every run. Stick with local sqlite if that data should never leave this machine.");
+        const dbBackend = await asker.select("Store trace data locally or remotely (Cloudflare D1)?", [
+            { value: "local", label: "local sqlite (default)" },
+            { value: "d1", label: "remote — Cloudflare D1 (sends full trace off-box, see note above)" },
+        ], "local");
+        let dbValue;
+        if (dbBackend === "d1") {
+            const databaseId = await asker.text("Cloudflare D1 database_id", {
+                validate: (v) => (v.trim() ? null : "required"),
+            });
+            // `account_id_env`/`api_token_env` both default (schema-side, see
+            // data_types.ts's D1DbConfigSchema) to the SAME env vars the Cloudflare
+            // Workers AI provider branch above already reads — leaving both out
+            // here keeps the generated config terse (the object below just says
+            // `{kind:"d1", database_id}`) while still resolving to the exact same
+            // normalized descriptor `resolveObservabilityDb` would produce with
+            // them spelled out.
+            dbValue = { kind: "d1", database_id: databaseId };
+            // Reuse CLOUDFLARE_ACCOUNT_ID/CLOUDFLARE_API_TOKEN if the coding-agent
+            // section above already collected them (this run is ALSO routed
+            // through Cloudflare Workers AI) — `envExampleKeys` is the definitive
+            // record of "already asked this run", true whether or not the answer
+            // itself ended up blank (e.g. an existing .env value was kept as-is).
+            // Otherwise collect them now, same validation/env-bucket convention as
+            // that branch: both are secrets, so they go into `env` (written to
+            // `.env`), never `configEnv`.
+            if (!envExampleKeys.includes("CLOUDFLARE_ACCOUNT_ID")) {
+                const accountId = await asker.text("CLOUDFLARE_ACCOUNT_ID", {
+                    validate: (v) => (v.trim() ? null : "required — find it in the Cloudflare dashboard (right sidebar)"),
+                });
+                env["CLOUDFLARE_ACCOUNT_ID"] = accountId;
+                envExampleKeys.push("CLOUDFLARE_ACCOUNT_ID");
+            }
+            if (!envExampleKeys.includes("CLOUDFLARE_API_TOKEN")) {
+                const apiToken = await asker.secret("CLOUDFLARE_API_TOKEN", { current: ctx.existingEnv.get("CLOUDFLARE_API_TOKEN") });
+                if (apiToken)
+                    env["CLOUDFLARE_API_TOKEN"] = apiToken;
+                envExampleKeys.push("CLOUDFLARE_API_TOKEN");
+            }
+            // D1's own consistency model, not local WAL sqlite's — see
+            // trace_db.ts's D1TraceDb class doc comment (SPF #66) for the full
+            // spike-verified explanation this paraphrases.
+            asker.note("D1 is not local WAL sqlite: spf ui and a running chain each talk to it over independent HTTP calls, not one shared file, so (per Cloudflare's own read-replication docs) a live trace view can briefly show a slightly-stale read while a chain is actively writing — D1's own consistency model, not a bug. No phase/gate/run outcome depends on that live read.");
+            asker.note("spf doctor probes the resolved D1 endpoint (informational, never a hard failure).");
+        }
+        else {
+            dbValue = await asker.text("observability.db", { default: ".spf/data/spf.db" });
+        }
         const pollMs = await asker.text("observability.poll_ms", { default: "500" });
-        if (dbPath !== ".spf/data/spf.db" || pollMs !== "500") {
-            defaults["__observability__"] = { ...(dbPath !== ".spf/data/spf.db" ? { db: dbPath } : {}), ...(pollMs !== "500" ? { poll_ms: Number(pollMs) } : {}) };
+        if (dbValue !== ".spf/data/spf.db" || pollMs !== "500") {
+            defaults["__observability__"] = { ...(dbValue !== ".spf/data/spf.db" ? { db: dbValue } : {}), ...(pollMs !== "500" ? { poll_ms: Number(pollMs) } : {}) };
         }
         if (watch) {
             const watchPollMs = await asker.text("watch.poll_ms", { default: "60000" });

package/dist/core/agent_opencode.d.ts

@@ -0,0 +1,247 @@
+/**
+ * OpenCode coding agent interface — a third backend alongside `agent_flue.ts`
+ * (`coding_agent: flue`) and `agent_cc.ts` (`coding_agent: claude_code`), for
+ * running agents on the `opencode` CLI. Subprocess-based, for the same
+ * reason `agent_cc.ts` is: shelling out costs SPF zero new dependencies, and
+ * anyone using this backend needs the `opencode` CLI installed anyway.
+ *
+ * The `opencode` command is resolved from `PATH` by default. To route it
+ * through a wrapper, proxy, or launcher, set `SPF_OPENCODE_CMD` — same
+ * mechanism, same rationale, and same `{model}` token substitution as
+ * `agent_cc.ts`'s `SPF_CLAUDE_CMD` (see that module's doc comment for the
+ * `ollama launch`-style motivating example). Unlike `SPF_CLAUDE_CMD`, no
+ * `ollama launch`-shaped wrapper is special-cased here: that fix was for a
+ * specific cobra flag-parsing quirk in `claude`'s own launcher story, and
+ * there is no equivalent evidence for `opencode` — inventing one would be
+ * guessing at a bug that may not exist.
+ *
+ * This module's understanding of the real `opencode` CLI started from a docs
+ * research spike, then was checked against real `opencode run --format json`
+ * invocations (via `npx opencode-ai@1.18.26`, a free `opencode/*` model) —
+ * a plain text reply, a bash tool call, a slow bash tool call (to look for
+ * multi-line status transitions), a `--session <id>` resume, and an invalid
+ * `--model` string. Every fact below is tagged:
+ *
+ *   [OFFICIAL]  — stated in opencode's own published docs.
+ *   [VERIFIED]  — confirmed against a real `opencode run --format json`
+ *                 invocation, per the spike above. One real run is
+ *                 corroboration, not a version-pinned contract — still
+ *                 parsed defensively.
+ *   [SOURCE]    — inferred from opencode's repo/issue tracker, NOT written
+ *                 down anywhere in prose, and NOT independently exercised by
+ *                 the spike above (e.g. a multi-line tool_use transition
+ *                 never actually appeared in any run tried). High confidence
+ *                 on field NAMES, but not a contractual guarantee — parsed
+ *                 defensively throughout this module for exactly that
+ *                 reason.
+ *
+ * COMMAND SHAPE [OFFICIAL]: `opencode run [message..]` — the prompt is a
+ * POSITIONAL argument, not a flag (contrast `claude -p <prompt>`, also
+ * positional-ish but behind `-p`). Confirmed flags this module uses:
+ * `--model`/`-m` (`provider/model` string, free-form — same vocabulary
+ * shape as Flue's own `provider/model-id`, e.g. `anthropic/claude-sonnet-4-
+ * 20250514`, `ollama/qwen3-coder:30b`), `--format json` (structured NDJSON
+ * output — opencode's analog of `claude`'s `--output-format stream-json`),
+ * `--dir` (working directory), `--session <id>` (resume a specific
+ * session), `--auto` (auto-approve permissions not explicitly denied —
+ * opencode's rough analog of `claude`'s `--dangerously-skip-permissions`),
+ * `--variant` (provider-specific reasoning effort — opencode's analog of
+ * `claude`'s `--effort`).
+ *
+ * NO SYSTEM-PROMPT FLAG [OFFICIAL]: opencode has nothing like `claude`'s
+ * `--system-prompt`. `request.system_prompt` is prepended to the message
+ * text instead (see `run()` below) — a REAL LIMITATION, not a workaround
+ * that fully replicates a separate channel: from opencode's own point of
+ * view, the system prompt is just the first paragraph of the user's
+ * message, not a distinct role in the transcript it sees.
+ *
+ * NO PER-CALL TOOL-ALLOWLIST FLAG [OFFICIAL]: tool restriction is
+ * CONFIG-ONLY, via a `permission` map in an `opencode.json` file (values
+ * `"allow"`/`"ask"`/`"deny"` per tool name) pointed at by the `OPENCODE_CONFIG`
+ * env var — see `writeTempPermissionConfig()` below. `--auto` only
+ * suppresses `"ask"`; it never overrides an explicit `"deny"`.
+ *
+ * KNOWN LIMITATION — CONFIG PRECEDENCE: per opencode's own config-merge
+ * docs, a target repo's OWN project-level `opencode.json` (if one exists)
+ * merges at HIGHER precedence than the file `OPENCODE_CONFIG` points at.
+ * That means a repo carrying its own `opencode.json` can silently override
+ * (widen or narrow) the restriction this module writes — a real, documented
+ * gap in this backend's tool-restriction guarantee, not a bug this module
+ * can paper over from the outside.
+ *
+ * `write`/`apply_patch` ARE GATED THROUGH `edit` [OFFICIAL]: opencode's own
+ * docs say these two are not independent permission keys — both ride the
+ * `edit` key. This module never writes `write`/`apply_patch` keys of their
+ * own for exactly that reason.
+ *
+ * NDJSON EVENT SHAPE [VERIFIED]: one JSON object per line,
+ * `{ type, timestamp, sessionID, part, ... }`. Types this module reacts to:
+ * `step_start` (carries the REAL `sessionID` — captured from the first one
+ * seen and returned as `AgentResult.session_id`), `tool_use` (carries
+ * `part.tool`/`part.callID`/`part.state.status`/`part.state.input`/
+ * `part.state.output`/`part.state.time.{start,end}` — every observed call,
+ * even a deliberately slow one, arrived as exactly ONE already-terminal
+ * line, `status: "completed"`, never a separate pending/running line first),
+ * `text` (carries the response text at `part.text`), `step_finish` (carries
+ * `part.reason`: `"stop"` = done, `"tool-calls"` = more coming; and
+ * `part.tokens.{input,output,reasoning,cache.{read,write}}` +
+ * `part.cost` as a plain number — ALL VERIFIED field names/shapes), `error`
+ * (carries `error.name`/`error.data.message` — verified via an invalid
+ * `--model` string, which this build surfaced as `error.name:
+ * "UnknownError"` with exit code 1, NOT the exit-0-on-error upstream bug
+ * described below; that bug may be real for other error classes/versions,
+ * so the defense against it stays).
+ *
+ * NDJSON EVENT SHAPE, UNVERIFIED PORTION [SOURCE]: whether `tool_use` can
+ * ever arrive as MULTIPLE lines for the same call (a pending/running status
+ * before the terminal one) was not observed in the spike above — every call
+ * tried was a fast bash command that appeared already-`completed` on its
+ * first (and only) line. `OcToolCallTracker` still defensively folds a
+ * multi-line sequence if one occurs (see its own doc comment), but that path
+ * is unexercised, not confirmed absent.
+ *
+ * SESSION IDS ARE NOT CLIENT-CHOOSABLE [OFFICIAL + VERIFIED]: opencode's
+ * server assigns a ULID-based id (`ses_<26 chars>`, exact shape confirmed —
+ * e.g. `ses_f9bf9448cffe9LnZCxoR5m2uyf`) on session creation. The spike
+ * above also confirmed the RESUME half: capturing a `sessionID` from one
+ * call and passing it back via `--session <id>` on a second, unrelated
+ * `run()` genuinely continued the first call's conversation (the model
+ * correctly recalled content from the first turn). So a first-contact call
+ * passes NO `--session`/`--continue` at all, and the real id is captured
+ * from the first `step_start` event. See
+ * `pendingSessionLabel()` for the placeholder this module hands back before
+ * that capture happens, and `agents.ts`'s `agentSessionId()`/`send()` for how
+ * the placeholder gets replaced with the real id for the REST of a phase's
+ * retries — this is the "session-id lifecycle" change described in that
+ * module.
+ *
+ * DEVIATION FROM A LITERAL "only pass --session when request.resume" RULE:
+ * within one phase, `agents.ts`'s `send()` re-assigns its local `sessionId`
+ * to whatever THIS module's last call returned, but `AgentRequest.resume`
+ * itself is computed once per phase and does NOT flip to `true` for a
+ * same-phase JSON-repair retry or gate-correction (`agents.ts` only ever
+ * threads `!isNewSession` through, unchanged, on every `send()` in a phase).
+ * Passed literally, that would mean: brand-new phase, first call succeeds
+ * and captures a real `ses_...` id — the very next correction in that same
+ * phase would see `request.resume === false` and `request.session_id` ===
+ * a REAL id, and a literal "only pass --session when resume" rule would
+ * drop `--session` entirely, causing opencode to silently open a SECOND,
+ * unrelated session and lose the conversation the correction is supposed to
+ * continue. `run()` instead keys off whether `request.session_id` is this
+ * module's OWN placeholder shape (see `isPendingSessionLabel()`): a
+ * placeholder means genuinely first contact (no `--session`, let opencode
+ * mint one); anything else — a same-phase corrected id OR a real id carried
+ * over from `agent_map.json` on `resume: true` — gets `--session <id>`.
+ * This is a deliberate judgment call flagged for review: it stays
+ * functionally equivalent to "pass --session whenever there's a real id to
+ * resume," which is what the source instructions' own mechanism (the
+ * mid-phase `sessionId` correction) requires to actually work.
+ *
+ * KNOWN UPSTREAM BUGS [SOURCE, filed against opencode's own repo]: exit code
+ * can be 0 even on a session error or an invalid-model error — this module
+ * never trusts exit code 0 alone; it also requires either a `step_finish`
+ * with `reason: "stop"` or an explicit `error` event, and treats "the
+ * stream ended with neither" as a hard failure too (same spirit as
+ * `agent_cc.ts`'s "no result message" check). Some invocations reportedly
+ * hang indefinitely on upstream API errors with no exit code ever — this
+ * module does NOT attempt a watchdog/timeout for that (out of scope, the
+ * same choice `agent_cc.ts` makes: timeouts are the caller's job); it only
+ * guarantees that a missing final event, once the process DOES exit, throws
+ * a clear error instead of something worse.
+ *
+ * STDIN [OFFICIAL]: opencode reads stdin when it is not a TTY, merging it
+ * with the positional message. `child.stdin.end()` runs immediately after
+ * spawn — not for `agent_cc.ts`'s reason (a ~3s "waiting to see if anything
+ * is piped" stall), but to avoid ANY unintended stdin-content merge into the
+ * prompt, since the full prompt (system + user) already travels as the
+ * positional `message` argument.
+ *
+ * AUTH [OFFICIAL]: `~/.local/share/opencode/auth.json` is the credential
+ * store; `opencode auth list` is the documented non-interactive
+ * is-it-configured check. This module does not drive `opencode auth login`
+ * — see `cli/commands/doctor.ts`'s opencode checks, which treat auth the
+ * same way `claude login` is treated for `claude_code`: already the
+ * operator's job, informational only.
+ *
+ * KNOWN RISK — SINGLE-ARGV PROMPT SIZE: `system_prompt` + `prompt` travel as
+ * ONE positional argv element (see `run()`'s `message`), unlike
+ * `agent_cc.ts`'s two separate flags plus a separate `--json-schema` blob.
+ * On Linux, `execve` enforces a ~128KB ceiling PER ARGUMENT
+ * (`MAX_ARG_STRLEN`), independent of the much larger total `ARG_MAX` — a
+ * large combined system+user prompt (e.g. a big `previous_envelope` JSON
+ * blob folded into the user prompt, see `agents.ts`) could approach that
+ * ceiling and fail with a bare `E2BIG` via `child.on("error")`, for a
+ * prompt pair that would run fine under `claude_code`. STDIN is
+ * deliberately closed above, foreclosing the natural workaround (opencode
+ * DOES read and merge non-TTY stdin). Not fixed here: no measurement of
+ * real envelope sizes against this ceiling has been done, and the fix
+ * (piping the prompt some other way) needs opencode-side confirmation of
+ * what it actually supports — disclosed as a real, unverified risk rather
+ * than guessed at.
+ */
+import type { AgentRequest, AgentResult } from "./data_types.ts";
+/** One line of `opencode run --format json` output, loosely typed — see the module doc comment for what's actually verified vs. inferred. */
+export type OcStreamMessage = Record<string, any>;
+/**
+ * Folds `tool_use` events into the SAME record shape `agent_flue`'s
+ * `ToolCallTracker` and `agent_cc`'s `CcToolCallTracker` produce, so
+ * `agents.ts`'s `eventForwarder` needs no backend-specific branching beyond
+ * picking which tracker class to instantiate.
+ *
+ * Unlike CC's assistant/tool_use + user/tool_result PAIR (two distinct
+ * messages, linked by `tool_use_id`), opencode's NDJSON carries ONE
+ * `tool_use` event per call [VERIFIED for the common case: every call
+ * observed in the module's spike, including a deliberately slow one,
+ * arrived as a single already-`"completed"` line]. Whether `part.state.status`
+ * can ALSO transition across multiple lines for one call (e.g. `pending` ->
+ * `running` -> `completed`/`error`) before that terminal line remains
+ * [SOURCE]-only — not observed, not confirmed absent — so this folds on
+ * "looks terminal" rather than a hardcoded status enum, in case it does:
+ * `state.output` being present is treated as the authoritative terminal
+ * signal (an explicit `"error"`/`"completed"`/`"done"` status also counts).
+ */
+export declare class OcToolCallTracker {
+    private open;
+    private closed;
+    observe(message: OcStreamMessage): Record<string, any> | null;
+}
+export declare function isKnownToolName(name: string): boolean;
+/**
+ * Resolve `SPF_OPENCODE_CMD` for THIS call, substituting a literal `{model}`
+ * token with `model` — same mechanism and rationale as `agent_cc.ts`'s
+ * `resolveClaudeCmdSpec`. Exported as its own pure function for the same
+ * reason: unit-testable without spawning a real subprocess.
+ */
+export declare function resolveOpencodeCmdSpec(model: string): string;
+/**
+ * NOT a real session id, and NOT interchangeable with `agent_cc.ts`'s
+ * `newSessionId()` — opencode's server assigns its own `ses_<ULID>` id on
+ * first contact; nothing this module mints is ever valid to pass to
+ * `--session`. This exists purely as a COSMETIC placeholder for
+ * `agents.ts`'s pre-call logging (the `agent_start` trace event, the
+ * console line) before the real id is captured from the first response —
+ * see `run()`'s session-id handling and this module's doc comment for the
+ * full lifecycle.
+ */
+export declare function pendingSessionLabel(): string;
+/**
+ * The `--session` decision — see the module doc comment's "DEVIATION FROM A
+ * LITERAL only-pass-when-resume RULE" note for why this keys off the id's
+ * SHAPE (a placeholder means genuinely first contact) rather than
+ * `request.resume`. Extracted as its own pure function specifically so this
+ * judgment call is unit-testable without spawning a real subprocess.
+ */
+export declare function sessionArgs(sessionId: string): string[];
+/** Kill any still-running `opencode` children — call once, at process exit. Safe if none are running. */
+export declare function shutdown(): Promise<void>;
+/**
+ * Run one `opencode run` turn. See the module doc comment for the full
+ * session-id lifecycle, the system-prompt-via-prepend limitation, and the
+ * tool-restriction-via-temp-config mechanism.
+ *
+ * `onEvent` receives each parsed NDJSON line UNFOLDED, exactly as
+ * `agent_cc.run()`/`agent_flue.run()` forward their own raw events — folding
+ * into one record per tool call is `eventForwarder`'s job (`agents.ts`), via
+ * this module's `OcToolCallTracker`.
+ */
+export declare function run(request: AgentRequest, onEvent?: (message: OcStreamMessage) => void, onSpawn?: (pid: number) => void, onExit?: (pid: number) => void): Promise<AgentResult>;