@gr8ful/spf 0.14.0 → 0.16.0

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.");
         }
@@ -412,14 +441,22 @@ export async function runInterview(asker, ctx) {
             });
             const projectKey = await asker.text("Jira project key", { validate: (val) => (val.trim() ? null : "required") });
             watch.jira = { base_url: baseUrl.replace(/\/+$/, ""), project_key: projectKey.toUpperCase() };
+            asker.note("Jira workflow status (the board's Status column) stays untouched by default — labels alone drive spf watch. " +
+                "Opt in with watch.jira.status_map (per-state -> Jira status name) to also sync it, then run `spf watch init` to validate.");
         }
         const needsGithub = issueProvider === "github" || codeHost === "github";
         if (needsGithub) {
-            asker.note('classic PAT, "repo" scope (private) or "public_repo" (public-only) — never "project".');
+            asker.note(issueProvider === "github"
+                ? 'classic PAT, "repo" scope (private) or "public_repo" (public-only) — add "project" too if you plan to use watch.github.status_map (native Projects v2 board sync).'
+                : 'classic PAT, "repo" scope (private) or "public_repo" (public-only).');
             const token = await asker.secret("GITHUB_TOKEN", { current: ctx.existingEnv.get("GITHUB_TOKEN") });
             if (token)
                 env["GITHUB_TOKEN"] = token;
             envExampleKeys.push("GITHUB_TOKEN");
+            if (issueProvider === "github") {
+                asker.note("GitHub Projects v2 board status (the board's Status column) stays untouched by default — labels alone drive spf watch. " +
+                    "Opt in with watch.github.project_number + watch.github.status_map (per-state -> Status option name) to also sync it, then run `spf watch init` to validate.");
+            }
         }
         if (issueProvider === "jira") {
             const email = await asker.text("JIRA_EMAIL", { default: ctx.gitEmail ?? "" });
@@ -497,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>;