cookbook-bridge 0.1.0

package/robot-runner.mjs

@@ -0,0 +1,55 @@
+/**
+ * Robot runner — the Bridge's embodied-agent socket (Coordination v2, sim-first).
+ *
+ * Unlike the LLM runners (which get a PROMPT and reason), a robot agent gets the
+ * task STRUCTURED — env vars, not prose — because its "brain" is a skill program
+ * (today a kinematic sim; later a LeRobot policy), not a language model. The
+ * contract mirrors every other runner: the Bridge pre-claims, the agent process
+ * does the work THROUGH Cookbook MCP tools (upload_file for the camera-proof
+ * receipt, remember for the writeback, complete_task to finish), and the Bridge
+ * verifies completion via getTask like any other run.
+ *
+ * Safety posture for embodied agents: this runner NEVER auto-approves anything;
+ * the standard delegation policy applies upstream, and for REAL hardware the
+ * owner's policy should be 'ask' — a physical action deserves a human yes.
+ * (v0 is a simulation; the posture is set now so hardware inherits it.)
+ *
+ * Config example:
+ *   { "name": "Robo", "match": ["robo", "robot", "arm"], "runner": "robot",
+ *     "command": ["python3", "robots/sim-arm/agent.py"], "token": "cbk_mcp_..." }
+ */
+import { spawn } from "node:child_process";
+
+export function runRobotTask(agent, ws, task, timeoutSeconds, token, cookbookUrl, baseEnv) {
+  return new Promise((resolve) => {
+    const [cmd, ...args] = agent.command;
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...(baseEnv ?? process.env),
+        COOKBOOK_URL: cookbookUrl,
+        COOKBOOK_TOKEN: token,
+        WORKSPACE_ID: ws.id,
+        TASK_ID: task.id,
+        TASK_TITLE: task.title ?? "",
+        TASK_INSTRUCTIONS: task.instructions ?? "",
+      },
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    const killTimer = setTimeout(() => {
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 5000);
+    }, timeoutSeconds * 1000);
+    child.on("error", (e) => {
+      clearTimeout(killTimer);
+      resolve({ code: -1, out, err: `could not launch robot agent \`${cmd}\`: ${e.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(killTimer);
+      resolve({ code, out, err });
+    });
+  });
+}

package/thread-runner.mjs

@@ -0,0 +1,221 @@
+/**
+ * Persistent per-thread agent processes (the terminal-feel unlock, Diego 2026-08-20).
+ *
+ * A terminal feels instant because the process is already alive: you pay CLI boot +
+ * MCP handshake once per SESSION, not once per message. This module gives Composer
+ * threads the same physics: one `claude -p --input-format stream-json` process per
+ * active thread, held open; each follow-up message is written to stdin and the turn
+ * ends at the CLI's `result` line. Reply latency collapses to model time.
+ *
+ * Design walls:
+ *  - claude-only (the one CLI with a streaming stdin protocol here); callers fall
+ *    back to the one-shot spawn path for anything else, and on ANY runner error —
+ *    the runner is an accelerator, never a dependency.
+ *  - one in-flight send per runner (`busy`); concurrent sends are the caller's cue
+ *    to use the one-shot path (claim serialization makes this rare).
+ *  - idle runners are reaped (default 10 min) and every runner dies with the Bridge.
+ *  - stream-parsing helpers are INJECTED (bridge.mjs dispatches on import, so this
+ *    module must not import it back).
+ */
+import { spawn } from "node:child_process";
+
+const IDLE_MS = 10 * 60_000;
+const runners = new Map(); // threadRootId -> Runner
+
+/** Build the persistent variant of a one-shot claude command: same binary and
+ *  allowlist flags, minus the inline prompt, plus the streaming stdin protocol.
+ *  Returns null when the command isn't claude-shaped (caller falls back). */
+export function persistentCommand(command, resumeSessionId) {
+  if (!Array.isArray(command) || command[0] !== "claude") return null;
+  const args = ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose"];
+  if (resumeSessionId) args.push("--resume", resumeSessionId);
+  // Carry over safety-relevant flags from the configured command (allowlist etc.),
+  // dropping prompt/format flags this protocol replaces.
+  const skip = new Set(["-p", "--print", "{prompt}", "--output-format", "--input-format", "--verbose", "--include-partial-messages", "--resume"]);
+  for (let i = 1; i < command.length; i++) {
+    const a = command[i];
+    if (a === "--output-format" || a === "--input-format" || a === "--resume") { i++; continue; }
+    if (skip.has(a)) continue;
+    args.push(a);
+  }
+  return ["claude", ...args];
+}
+
+class Runner {
+  constructor({ threadId, agent, env, resumeSessionId, helpers, log }) {
+    this.threadId = threadId;
+    this.agent = agent;
+    this.helpers = helpers; // { fold, textFrom, sessionFrom }
+    this.log = log;
+    this.busy = false;
+    this.lastUsedAt = Date.now();
+    this.sessionId = resumeSessionId ?? null;
+    this.dead = false;
+    this.sends = 0; // 0 = still adoptable (a pre-warmed process with no history)
+    const command = persistentCommand(agent.command, resumeSessionId);
+    if (!command) throw new Error("not a claude-shaped command");
+    const [cmd, ...args] = command;
+    // Local-access agents carry a cwd (the workspace's mapped folder).
+    this.child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"], env, ...(agent.cwd ? { cwd: agent.cwd } : {}) });
+    this.lineBuf = "";
+    this.err = "";
+    this.turn = null; // in-flight send state
+    this.child.stdout.on("data", (d) => this.#onData(String(d)));
+    this.child.stderr.on("data", (d) => { this.err = (this.err + String(d)).slice(-4000); });
+    this.child.on("close", (code) => {
+      this.dead = true;
+      const t = this.turn;
+      this.turn = null;
+      if (t) t.reject(Object.assign(new Error(`thread runner exited (${code}): ${this.err.slice(-300)}`), { sessionId: this.sessionId }));
+    });
+    this.child.on("error", (e) => {
+      this.dead = true;
+      const t = this.turn;
+      this.turn = null;
+      if (t) t.reject(new Error(`thread runner failed to launch: ${e.message}`));
+    });
+  }
+
+  #onData(chunk) {
+    this.lineBuf += chunk;
+    let nl;
+    while ((nl = this.lineBuf.indexOf("\n")) >= 0) {
+      const line = this.lineBuf.slice(0, nl).trim();
+      this.lineBuf = this.lineBuf.slice(nl + 1);
+      if (!line || !this.turn) continue;
+      const t = this.turn;
+      t.lastActivityAt = Date.now();
+      if (!this.sessionId) this.sessionId = this.helpers.sessionFrom(line);
+      const spoke = this.helpers.textFrom(line);
+      if (spoke) {
+        if (spoke.kind === "delta") t.partialText += spoke.text;
+        else { t.turnsText += (t.turnsText && spoke.text ? "\n\n" : "") + spoke.text; t.partialText = ""; }
+      }
+      const r = this.helpers.fold(line, t.acc);
+      t.acc = r.acc;
+      if (r.resultLine) {
+        clearInterval(t.watchdog);
+        this.turn = null;
+        this.busy = false;
+        this.lastUsedAt = Date.now();
+        t.resolve({ code: 0, out: r.resultLine, err: "", sessionId: this.sessionId });
+      } else {
+        t.emit();
+      }
+    }
+  }
+
+  /** Send one user message; resolves with a one-shot-shaped result envelope. */
+  send(text, { onProgress, timeoutMs, livenessMs }) {
+    if (this.dead) return Promise.reject(new Error("thread runner is dead"));
+    if (this.busy) return Promise.reject(new Error("thread runner busy"));
+    this.busy = true;
+    this.sends++;
+    this.lastUsedAt = Date.now();
+    return new Promise((resolve, reject) => {
+      const startedAt = Date.now();
+      const t = {
+        resolve, reject,
+        acc: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, num_turns: 0 },
+        turnsText: "", partialText: "",
+        lastEmit: 0, lastActivityAt: startedAt,
+        emit: () => {
+          if (!onProgress || Date.now() - t.lastEmit < 1200) return;
+          t.lastEmit = Date.now();
+          const full = t.partialText ? `${t.turnsText}${t.turnsText ? "\n\n" : ""}${t.partialText}` : t.turnsText;
+          const live_text = full.length > 1800 ? "…" + full.slice(-1800) : full;
+          if (t.acc.input_tokens === 0 && t.acc.output_tokens === 0 && !live_text) return;
+          try {
+            onProgress({ ...t.acc, runner: this.agent.name, ...(live_text ? { live_text } : {}), ...(this.sessionId ? { session_ref: this.sessionId } : {}) });
+          } catch { /* best-effort */ }
+        },
+        watchdog: setInterval(() => {
+          const now = Date.now();
+          const stalled = livenessMs > 0 && now - t.lastActivityAt >= livenessMs;
+          const over = now - startedAt >= timeoutMs;
+          if (!stalled && !over) return;
+          clearInterval(t.watchdog);
+          this.kill();
+          const e = new Error(stalled ? `thread runner silent for ${Math.round(livenessMs / 1000)}s` : `thread runner hit the ${Math.round(timeoutMs / 1000)}s ceiling`);
+          e.partialUsage = t.acc.input_tokens || t.acc.output_tokens ? { ...t.acc } : null;
+          e.elapsedMs = now - startedAt;
+          e.sessionId = this.sessionId;
+          this.turn = null;
+          reject(e);
+        }, 5000),
+      };
+      this.turn = t;
+      const msg = JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+      this.child.stdin.write(msg + "\n", (err) => {
+        if (err) { clearInterval(t.watchdog); this.turn = null; this.busy = false; reject(new Error(`stdin write failed: ${err.message}`)); }
+      });
+    });
+  }
+
+  kill() {
+    this.dead = true;
+    try { this.child.kill("SIGTERM"); } catch { /* already gone */ }
+    setTimeout(() => { try { this.child.kill("SIGKILL"); } catch { /* gone */ } }, 5000);
+  }
+}
+
+/** The live runner for a thread, or null — never creates. */
+export function hasRunner(threadId) {
+  const r = runners.get(threadId);
+  return r && !r.dead ? r : null;
+}
+
+/** PRE-WARM (0065): boot an idle runner under a pool key before any task exists.
+ *  No-op if one is already there or the pool is full. */
+export function warmUp({ poolKey, agent, env, helpers, log, cap = 4 }) {
+  if (hasRunner(poolKey)) return;
+  if (runners.size >= cap) return;
+  try {
+    const r = new Runner({ threadId: poolKey, agent, env, resumeSessionId: null, helpers, log });
+    runners.set(poolKey, r);
+    log(`  ↳ pre-warming ${agent.name} (${poolKey.slice(0, 24)}…)`);
+  } catch { /* not claude-shaped — nothing to warm */ }
+}
+
+/** Adopt a pre-warmed, never-used runner into a real thread key. Returns the runner
+ *  or null (dead, busy, or already carrying a conversation — adoption would leak
+ *  one thread's context into another). */
+export function adoptRunner(fromKey, toKey) {
+  const r = runners.get(fromKey);
+  if (!r || r.dead || r.busy || r.sends > 0) return null;
+  runners.delete(fromKey);
+  runners.set(toKey, r);
+  r.threadId = toKey;
+  return r;
+}
+
+/** Get the live runner for a thread, or create one (resuming a prior session when
+ *  given). Throws when the agent isn't claude-shaped; callers fall back. */
+export function runnerFor({ threadId, agent, env, resumeSessionId, helpers, log }) {
+  const existing = runners.get(threadId);
+  if (existing && !existing.dead) return existing;
+  if (existing) runners.delete(threadId);
+  const r = new Runner({ threadId, agent, env, resumeSessionId, helpers, log });
+  runners.set(threadId, r);
+  log(`  ↳ thread runner started for ${threadId.slice(0, 8)}${resumeSessionId ? " (resuming session)" : ""}`);
+  return r;
+}
+
+export function reapIdleRunners(log, idleMs = IDLE_MS) {
+  const now = Date.now();
+  for (const [id, r] of runners) {
+    if (r.dead || (now - r.lastUsedAt > idleMs && !r.busy)) {
+      if (!r.dead) { r.kill(); log(`  ↳ thread runner for ${id.slice(0, 8)} reaped (idle)`); }
+      runners.delete(id);
+    }
+  }
+}
+
+export function killAllRunners() {
+  for (const [, r] of runners) r.kill();
+  runners.clear();
+}
+
+export function runnerStats() {
+  return { count: runners.size, busy: [...runners.values()].filter((r) => r.busy).length };
+}

package/update.mjs

@@ -0,0 +1,151 @@
+/**
+ * Bridge self-updater — "when the app updates, so does the Bridge."
+ *
+ * The app deploy is the version source of truth: /api/bridge/manifest publishes a sha256
+ * per runtime file (computed from what the deploy is actually serving) + a combined
+ * version hash. This module hashes the LOCAL files, compares, and applies updates by
+ * downloading the same tar every user installs from — verifying every extracted file
+ * against the manifest before a single byte on disk changes. The user's config.json
+ * (and its token) is NEVER touched.
+ *
+ * Trust posture (see /security): same-origin as the install itself, hash-verified,
+ * old files kept in bridge.backup/, plain readable JS, and `"autoUpdate": false` pins
+ * the version entirely. Auto-updates re-exec the running Bridge so fleets track deploys
+ * within one check interval.
+ *
+ * Pure helpers (hashing, comparison, tar parsing) are exported for
+ * scripts/test-bridge-update.ts; I/O lives in checkForUpdate/applyUpdate.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+
+/** Files the updater manages — must mirror the server's BRIDGE_RUNTIME_FILES. The list
+ *  itself comes from the MANIFEST at update time (server-driven), so a future deploy can
+ *  add files without this constant; this is only the local-hash candidate set. */
+export const LOCAL_FILES_GLOB = /\.(mjs|md)$/i;
+
+export function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+/** Hash the local runtime files that exist (missing files = trivially outdated). */
+export function localManifest(dir, names) {
+  const files = {};
+  for (const name of names) {
+    const p = path.join(dir, name);
+    if (fs.existsSync(p)) files[name] = sha256(fs.readFileSync(p));
+  }
+  return files;
+}
+
+/** Compare local hashes to the remote manifest → the files that need replacing. */
+export function diffManifest(remoteFiles, localFiles) {
+  return Object.keys(remoteFiles).filter((name) => localFiles[name] !== remoteFiles[name]);
+}
+
+/** Minimal ustar reader (mirror of the server's zero-dep writer): {name → Buffer}. */
+export function untar(buf) {
+  const out = {};
+  let off = 0;
+  while (off + 512 <= buf.length) {
+    const header = buf.subarray(off, off + 512);
+    if (header.every((b) => b === 0)) break; // terminator blocks
+    const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
+    const size = parseInt(header.subarray(124, 136).toString("ascii").replace(/\0.*$/, "").trim(), 8) || 0;
+    const body = buf.subarray(off + 512, off + 512 + size);
+    if (name) out[name] = Buffer.from(body);
+    off += 512 + Math.ceil(size / 512) * 512;
+  }
+  return out;
+}
+
+/**
+ * Check the deploy's manifest against local files. Returns
+ * { version, changed: [names] } — changed.length === 0 means up to date.
+ * Throws on network/shape errors (callers treat check failures as non-fatal).
+ */
+export async function checkForUpdate(cfg, dir) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/manifest`, { headers: { "Cache-Control": "no-store" } });
+  if (!res.ok) throw new Error(`manifest HTTP ${res.status}`);
+  const manifest = await res.json();
+  if (!manifest || typeof manifest.files !== "object") throw new Error("malformed manifest");
+  const local = localManifest(dir, Object.keys(manifest.files));
+  return { version: manifest.version, files: manifest.files, changed: diffManifest(manifest.files, local) };
+}
+
+/** A filesystem-safe backup subdir name for a manifest version (falls back to a
+ *  monotonic-ish label when no version is given). Exported for the test. */
+export function backupDirName(version) {
+  const v = String(version || "").replace(/[^A-Za-z0-9._-]/g, "").slice(0, 40);
+  return v || "prev";
+}
+
+/**
+ * Apply an update: download the tar, VERIFY every runtime file against the manifest
+ * hashes (any mismatch aborts before any write), back up current files to a
+ * PER-VERSION bridge.backup/<version>/ dir, then replace ATOMICALLY (write each to a
+ * .tmp and rename; roll back from the backup if any rename fails mid-way). Never writes
+ * config.json. Returns the replaced names.
+ *
+ * Two audit-2026-07-03 fixes vs the old flat overwrite: (#14a) a bad-but-hash-valid
+ * update N+1 can no longer clobber update N's last-good backup — each version keeps its
+ * own; (#14b) a mid-loop write failure (disk full, EACCES) no longer leaves a mixed
+ * old/new install that crashes lazy module loading on next start — it's rename-based and
+ * rolls back.
+ */
+export async function applyUpdate(cfg, dir, manifest) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/download`);
+  if (!res.ok) throw new Error(`download HTTP ${res.status}`);
+  const tar = untar(gunzipSync(Buffer.from(await res.arrayBuffer())));
+
+  // Verify EVERYTHING the manifest names, before touching disk.
+  const verified = {};
+  for (const [name, wantHash] of Object.entries(manifest.files)) {
+    const data = tar[`bridge/${name}`];
+    if (!data) throw new Error(`update aborted: ${name} missing from archive`);
+    const got = sha256(data);
+    if (got !== wantHash) throw new Error(`update aborted: ${name} hash mismatch (archive ${got.slice(0, 12)}… ≠ manifest ${String(wantHash).slice(0, 12)}…)`);
+    verified[name] = data;
+  }
+
+  // Per-version backup dir — never overwrites a prior version's last-good copies.
+  const backupDir = path.join(dir, "bridge.backup", backupDirName(manifest.version));
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  // 1. Write every new file to a sibling .tmp and back up the current one. No live
+  //    file is replaced yet, so a failure here leaves the install fully intact.
+  const staged = []; // { name, target, tmp, backup|null }
+  try {
+    for (const [name, data] of Object.entries(verified)) {
+      const target = path.join(dir, name);
+      const tmp = target + ".tmp";
+      let backup = null;
+      if (fs.existsSync(target)) {
+        backup = path.join(backupDir, name);
+        fs.copyFileSync(target, backup);
+      }
+      fs.writeFileSync(tmp, data, { mode: name.endsWith(".mjs") ? 0o755 : 0o644 });
+      staged.push({ name, target, tmp, backup });
+    }
+  } catch (e) {
+    for (const s of staged) { try { fs.rmSync(s.tmp, { force: true }); } catch { /* ignore */ } }
+    throw new Error(`update aborted before any live file changed: ${e.message}`);
+  }
+
+  // 2. Rename each staged .tmp over its target. If one fails, roll the already-renamed
+  //    ones back from their backups so we never leave a half-old/half-new install.
+  const done = [];
+  try {
+    for (const s of staged) {
+      fs.renameSync(s.tmp, s.target);
+      done.push(s);
+    }
+  } catch (e) {
+    for (const s of done) { if (s.backup) { try { fs.copyFileSync(s.backup, s.target); } catch { /* best-effort */ } } }
+    for (const s of staged) { try { fs.rmSync(s.tmp, { force: true }); } catch { /* ignore */ } }
+    throw new Error(`update rolled back (rename failed on ${e.message}) — still on the previous version`);
+  }
+  return done.map((s) => s.name);
+}

package/usage.mjs

@@ -0,0 +1,147 @@
+/**
+ * Run-cost extraction — "what did this task cost the runner's quota?"
+ *
+ * Side-effect-free on purpose (bridge.mjs dispatches on import; testable helpers live
+ * in modules like this — see scripts/test-bridge-usage.ts). After a verified-done run,
+ * the Bridge normalizes whatever the CLI reported and posts it to Cookbook via
+ * report_task_usage, so the ASSIGNER sees the cost of the delegation and the RUNNER
+ * sees what their quota paid for. Everything here is best-effort: a CLI that reports
+ * nothing simply yields duration-only usage — never an error.
+ *
+ * Known shapes handled:
+ *  - Claude Code `claude -p --output-format json` (verified against a real run):
+ *      { result, usage: { input_tokens, output_tokens, cache_read_input_tokens,
+ *        cache_creation_input_tokens, ... }, total_cost_usd, duration_ms, num_turns,
+ *        modelUsage: { "<model>": {...} } }
+ *  - Codex app-server token events (captured by codex-runner.mjs):
+ *      { input_tokens | inputTokens, cached_input_tokens | cachedInputTokens,
+ *        output_tokens | outputTokens, ... } — camel/snake both seen in the wild.
+ *  - Gemini CLI JSON output (best-effort): { stats: { models: { "<model>":
+ *      { tokens: { prompt, candidates, cached, total } } } } } or a flat usage object.
+ */
+
+const num = (v) => (Number.isFinite(Number(v)) && Number(v) >= 0 ? Number(v) : undefined);
+
+/** Drop undefined fields; return null when nothing of substance remains. */
+function compact(u) {
+  const out = {};
+  for (const [k, v] of Object.entries(u)) if (v !== undefined && v !== null && v !== "") out[k] = v;
+  const hasSubstance =
+    out.input_tokens !== undefined || out.output_tokens !== undefined ||
+    out.cost_usd !== undefined || out.duration_ms !== undefined;
+  return hasSubstance ? out : null;
+}
+
+/** Claude Code / generic flat shape: { usage: {...}, total_cost_usd, duration_ms, ... } */
+function fromClaudeJson(j) {
+  const u = j.usage;
+  if (!u || typeof u !== "object") return null;
+  return compact({
+    input_tokens: num(u.input_tokens),
+    output_tokens: num(u.output_tokens),
+    cache_read_input_tokens: num(u.cache_read_input_tokens),
+    cache_creation_input_tokens: num(u.cache_creation_input_tokens),
+    cost_usd: num(j.total_cost_usd),
+    duration_ms: num(j.duration_ms),
+    num_turns: num(j.num_turns),
+    model: j.modelUsage && typeof j.modelUsage === "object" ? Object.keys(j.modelUsage)[0] : undefined,
+  });
+}
+
+/** Gemini CLI stats shape: { stats: { models: { "<model>": { tokens: {...} } } } } */
+function fromGeminiStats(j) {
+  const models = j?.stats?.models;
+  if (!models || typeof models !== "object") return null;
+  let input = 0, output = 0, cached = 0, any = false;
+  for (const m of Object.values(models)) {
+    const t = m?.tokens;
+    if (!t) continue;
+    any = true;
+    input += Number(t.prompt) || 0;
+    output += Number(t.candidates) || 0;
+    cached += Number(t.cached) || 0;
+  }
+  if (!any) return null;
+  return compact({
+    input_tokens: input || undefined,
+    output_tokens: output || undefined,
+    cache_read_input_tokens: cached || undefined,
+    model: Object.keys(models)[0],
+  });
+}
+
+/** Codex app-server token_usage (camel or snake): captured by codex-runner. */
+export function fromCodexUsage(u) {
+  if (!u || typeof u !== "object") return null;
+  // Some payloads nest { total_token_usage: {...} } / { last_token_usage: {...} }.
+  const t = u.total_token_usage ?? u.totalTokenUsage ?? u;
+  return compact({
+    input_tokens: num(t.input_tokens ?? t.inputTokens),
+    output_tokens: num(t.output_tokens ?? t.outputTokens),
+    cache_read_input_tokens: num(t.cached_input_tokens ?? t.cachedInputTokens),
+  });
+}
+
+/**
+ * Extract normalized usage from a finished run.
+ *  - result: { out, err?, code? } for one-shot CLIs, or { out, usage? } from codex-runner.
+ *  - wallMs: the Bridge's own wall-clock measurement — the duration fallback, so every
+ *    report has at least duration even when the CLI says nothing.
+ * Returns the report_task_usage argument object, or null if there's nothing to say.
+ */
+export function extractUsage(result, agentName, wallMs) {
+  let usage = null;
+
+  // Persistent-runner path: codex-runner captured token events directly.
+  if (result && result.usage) usage = fromCodexUsage(result.usage);
+
+  // One-shot path: stdout may be a JSON document (claude/gemini json output modes).
+  if (!usage && result && typeof result.out === "string") {
+    const text = result.out.trim();
+    // Parse from the first "{"/"[" — CLIs print warnings BEFORE the envelope (the
+    // same prefix noise that broke displayText, audit 2026-07-03 #8: fixing one
+    // sibling and not the other silently dropped token receipts).
+    const start = Math.min(...["{", "["].map((c) => {
+      const i = text.indexOf(c);
+      return i < 0 ? Infinity : i;
+    }));
+    if (start !== Infinity) {
+      try {
+        const j = JSON.parse(text.slice(start));
+        usage = fromClaudeJson(j) ?? fromGeminiStats(j);
+      } catch {
+        /* not JSON — no usage in text mode */
+      }
+    }
+  }
+
+  const merged = compact({
+    ...(usage ?? {}),
+    duration_ms: usage?.duration_ms ?? num(wallMs),
+    runner: agentName,
+  });
+  return merged;
+}
+
+/**
+ * The agent's human-readable answer, for logs/hints: with `--output-format json` the
+ * text lives in `.result` (claude) / `.response` (gemini); in text mode it IS stdout.
+ */
+export function displayText(out) {
+  const text = String(out ?? "").trim();
+  // CLIs can print warnings BEFORE the JSON envelope (e.g. claude's workspace-trust
+  // notice), so parse from the first "{" rather than requiring the text to start
+  // with it. Verified live 2026-07-03: the prefix noise made a volunteer decision
+  // read as PASS.
+  const brace = text.indexOf("{");
+  if (brace >= 0) {
+    try {
+      const j = JSON.parse(text.slice(brace));
+      if (typeof j.result === "string") return j.result;
+      if (typeof j.response === "string") return j.response;
+    } catch {
+      /* fall through */
+    }
+  }
+  return text;
+}