@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/mcp/results.mjs

@@ -0,0 +1,133 @@
+/**
+ * lib/engine/mcp/results.mjs — MCP results → engine tool results (pure).
+ *
+ * Each MCP content block becomes text:
+ *
+ *   text           → its text
+ *   image          → with `attachImages`, a one-line note and the image itself
+ *                    in `images` (base64 + media type) for the wire to send as
+ *                    an image block — within the caps below; otherwise, or
+ *                    over a cap, a note with the MIME type and size
+ *   audio          → a note (no gateway wire carries audio input)
+ *   resource       → the embedded resource's text, or a note for a blob
+ *                    (an image blob is attached like an image)
+ *   resource_link  → a note naming the URI
+ *   anything else  → a note naming the block type
+ *
+ * `isError: true` makes an error result carrying the same text. A result with
+ * no content but `structuredContent` returns that JSON.
+ *
+ * @module lib/engine/mcp/results
+ */
+
+/** Image types every image-capable wire accepts. */
+export const IMAGE_MEDIA_TYPES = Object.freeze(new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]));
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+export const MAX_IMAGES_PER_RESULT = 8;
+export const MAX_IMAGE_BYTES_PER_RESULT = 20 * 1024 * 1024;
+
+/**
+ * @typedef {{mediaType:string, data:string}} ImageAttachment
+ * @typedef {{ok:true, content:string, images?:ImageAttachment[]} | {ok:false, error:string}} MappedResult
+ */
+
+/**
+ * Attach an image if it fits; the note to put in the text either way.
+ * @param {string|undefined} mimeType @param {unknown} data
+ * @param {{attachImages:boolean, images:ImageAttachment[], bytes:number}} state
+ */
+function imageNote(mimeType, data, state) {
+  const type = String(mimeType || "unknown type").toLowerCase();
+  const size = approxBytes(data);
+  if (!state.attachImages) return `[image content: ${type}, ${size} bytes — not shown]`;
+  let why = null;
+  if (typeof data !== "string" || data === "") why = "no data";
+  else if (!IMAGE_MEDIA_TYPES.has(type)) why = `${type} is not a supported image type`;
+  else if (size > MAX_IMAGE_BYTES) why = `larger than ${MAX_IMAGE_BYTES} bytes`;
+  else if (state.images.length >= MAX_IMAGES_PER_RESULT) why = `more than ${MAX_IMAGES_PER_RESULT} images in one result`;
+  else if (state.bytes + size > MAX_IMAGE_BYTES_PER_RESULT) why = `images in one result over ${MAX_IMAGE_BYTES_PER_RESULT} bytes`;
+  if (why) return `[image content: ${type}, ${size} bytes — not shown: ${why}]`;
+  state.images.push({ mediaType: type, data: /** @type string */ (data) });
+  state.bytes += size;
+  return `[image content: ${type}, ${size} bytes]`;
+}
+
+/**
+ * @param {unknown} result  the JSON-RPC `result` of tools/call
+ * @param {{attachImages?:boolean}} [o]
+ * @returns {MappedResult}
+ */
+export function mapCallToolResult(result, { attachImages = false } = {}) {
+  if (!result || typeof result !== "object") {
+    return { ok: false, error: "The MCP server returned a malformed tool result." };
+  }
+  const r = /** @type {any} */ (result);
+  const state = { attachImages, images: /** @type {ImageAttachment[]} */ ([]), bytes: 0 };
+  const parts = Array.isArray(r.content) ? r.content.map((b) => blockText(b, state)).filter((t) => t !== "") : [];
+  if (parts.length === 0 && r.structuredContent !== undefined) parts.push(safeJson(r.structuredContent));
+  const text = parts.join("\n\n");
+  if (r.isError === true) return { ok: false, error: text === "" ? "The MCP tool reported an error with no details." : text };
+  const out = /** @type {{ok:true, content:string, images?:ImageAttachment[]}} */ ({ ok: true, content: text === "" ? "(no output)" : text });
+  if (state.images.length > 0) out.images = state.images;
+  return out;
+}
+
+/**
+ * `resources/read` result → tool result.
+ * @param {unknown} result @param {{attachImages?:boolean}} [o]
+ * @returns {MappedResult}
+ */
+export function mapReadResourceResult(result, { attachImages = false } = {}) {
+  const contents = result && typeof result === "object" && Array.isArray(/** @type any */ (result).contents) ? /** @type any */ (result).contents : null;
+  if (!contents) return { ok: false, error: "The MCP server returned a malformed resource." };
+  const state = { attachImages, images: /** @type {ImageAttachment[]} */ ([]), bytes: 0 };
+  const parts = contents.map((/** @type any */ c) => {
+    if (!c || typeof c !== "object") return "";
+    if (typeof c.text === "string") return `[resource ${c.uri ?? "(no uri)"}${c.mimeType ? `, ${c.mimeType}` : ""}]\n${c.text}`;
+    if (typeof c.mimeType === "string" && c.mimeType.toLowerCase().startsWith("image/")) return `[resource ${c.uri ?? "(no uri)"}] ${imageNote(c.mimeType, c.blob, state)}`;
+    return `[resource ${c.uri ?? "(no uri)"}: ${c.mimeType || "binary"}, ${approxBytes(c.blob)} bytes — not shown]`;
+  });
+  const text = parts.filter((t) => t !== "").join("\n\n");
+  const out = /** @type {{ok:true, content:string, images?:ImageAttachment[]}} */ ({ ok: true, content: text === "" ? "(empty resource)" : text });
+  if (state.images.length > 0) out.images = state.images;
+  return out;
+}
+
+/** @param {any} b @param {{attachImages:boolean, images:ImageAttachment[], bytes:number}} state */
+function blockText(b, state) {
+  if (!b || typeof b !== "object") return "";
+  switch (b.type) {
+    case "text":
+      return typeof b.text === "string" ? b.text : "";
+    case "image":
+      return imageNote(b.mimeType, b.data, state);
+    case "audio":
+      return `[audio content: ${b.mimeType || "unknown type"}, ${approxBytes(b.data)} bytes — not shown]`;
+    case "resource": {
+      const res = b.resource || {};
+      if (typeof res.text === "string") return res.uri ? `[resource ${res.uri}]\n${res.text}` : res.text;
+      if (state.attachImages && typeof res.mimeType === "string" && res.mimeType.toLowerCase().startsWith("image/")) return `[resource ${res.uri || "(no uri)"}] ${imageNote(res.mimeType, res.blob, state)}`;
+      return `[resource ${res.uri || "(no uri)"}: ${res.mimeType || "binary"}, ${approxBytes(res.blob)} bytes — not shown]`;
+    }
+    case "resource_link":
+      return `[resource link: ${b.uri || "(no uri)"}${b.name ? ` (${b.name})` : ""}]`;
+    default:
+      return `[unsupported MCP content block "${String(b.type)}"]`;
+  }
+}
+
+/** @param {unknown} base64 */
+export function approxBytes(base64) {
+  if (typeof base64 !== "string") return 0;
+  const pad = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor((base64.length * 3) / 4) - pad);
+}
+
+/** @param {unknown} v */
+function safeJson(v) {
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}

package/lib/engine/mcp/stdio.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/engine/mcp/stdio.mjs — the MCP stdio transport.
+ *
+ * Per the MCP specification: the client launches the server as a subprocess;
+ * messages are JSON-RPC objects, one per line (UTF-8, newline-delimited, no
+ * embedded newlines) on the child's stdin/stdout; the child's stderr is log
+ * output and is never parsed. Shutdown closes the child's stdin, then sends
+ * SIGTERM, then SIGKILL, each after a grace period.
+ *
+ * The child's stderr is kept as a short tail so a crash can be reported with
+ * the server's own last words.
+ *
+ * @module lib/engine/mcp/stdio
+ */
+
+import { spawn } from "node:child_process";
+
+export const STDERR_TAIL_CHARS = 2_000;
+export const SHUTDOWN_GRACE_MS = 1_500;
+
+/**
+ * @param {object} p
+ * @param {string} p.command
+ * @param {string[]} [p.args]
+ * @param {Record<string,string|undefined>} [p.env]  the full child environment
+ * @param {string} [p.cwd]
+ * @param {typeof spawn} [p.spawnImpl]
+ */
+export function createStdioTransport({ command, args = [], env, cwd, spawnImpl = spawn }) {
+  /** @type {import('node:child_process').ChildProcessWithoutNullStreams|null} */
+  let child = null;
+  let stderrTail = "";
+  /** @type {string|null} */
+  let exitReason = null;
+  /** @type {Promise<void>|null} */
+  let exited = null;
+
+  return {
+    /**
+     * @param {(msg:unknown) => void} onMessage
+     * @param {(reason:string) => void} onClose
+     * @returns {{ok:true}|{ok:false, error:string}}
+     */
+    start(onMessage, onClose) {
+      try {
+        child = /** @type any */ (spawnImpl(command, args, { cwd, env, stdio: ["pipe", "pipe", "pipe"] }));
+      } catch (e) {
+        return { ok: false, error: `could not start "${command}": ${e instanceof Error ? e.message : e}` };
+      }
+      const c = /** @type {import('node:child_process').ChildProcessWithoutNullStreams} */ (child);
+      let buffer = "";
+      c.stdout.setEncoding("utf8");
+      c.stdout.on("data", (chunk) => {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, nl).trim();
+          buffer = buffer.slice(nl + 1);
+          if (line === "") continue;
+          let msg;
+          try {
+            msg = JSON.parse(line);
+          } catch {
+            continue; // a server that logs to stdout: not a frame, not fatal
+          }
+          onMessage(msg);
+        }
+      });
+      c.stderr.setEncoding("utf8");
+      c.stderr.on("data", (chunk) => {
+        stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+      });
+      c.stdin.on("error", () => {
+        /* EPIPE after the child died; the exit handler reports it */
+      });
+      exited = new Promise((resolve) => {
+        const done = (/** @type string */ reason) => {
+          if (exitReason !== null) return;
+          exitReason = reason;
+          onClose(reason);
+          resolve();
+        };
+        c.on("error", (e) => done(`could not start "${command}": ${e.message}`));
+        c.on("exit", (code, signal) => done(code !== null ? `exited with code ${code}` : `killed by ${signal}`));
+      });
+      return { ok: true };
+    },
+
+    /** @param {object} msg */
+    send(msg) {
+      if (!child || exitReason !== null) return { ok: false, error: `server process is not running (${exitReason ?? "not started"})` };
+      try {
+        child.stdin.write(`${JSON.stringify(msg)}\n`);
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, error: `write to server failed: ${e instanceof Error ? e.message : e}` };
+      }
+    },
+
+    stderrTail: () => stderrTail.trim(),
+
+    /** Close stdin, then SIGTERM, then SIGKILL. Resolves once the child is gone. */
+    async close() {
+      if (!child || exitReason !== null || !exited) return;
+      const c = child;
+      const wait = (/** @type number */ ms) => {
+        /** @type {ReturnType<typeof setTimeout>|undefined} */
+        let timer;
+        const grace = new Promise((r) => {
+          timer = setTimeout(r, ms);
+        });
+        return Promise.race([exited, grace]).then(() => {
+          clearTimeout(timer);
+          return exitReason !== null;
+        });
+      };
+      try {
+        c.stdin.end();
+      } catch {
+        /* already closed */
+      }
+      if (await wait(SHUTDOWN_GRACE_MS)) return;
+      try {
+        c.kill("SIGTERM");
+      } catch {
+        /* already gone */
+      }
+      if (await wait(SHUTDOWN_GRACE_MS)) return;
+      try {
+        c.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+      await wait(SHUTDOWN_GRACE_MS);
+    },
+  };
+}

package/lib/engine/mcp/supervisor.mjs

@@ -0,0 +1,116 @@
+/**
+ * lib/engine/mcp/supervisor.mjs — a crashed stdio server gets one restart per run.
+ *
+ * A stdio MCP server that dies (a crash, an out-of-memory kill) takes its
+ * tools with it. The supervisor wraps a connection with the same interface;
+ * on the NEXT call after the server stopped, it starts the server again —
+ * once per run, per server — and makes the call on the new connection. The
+ * result says the server was restarted. A second death is reported like any
+ * crash, with a note that the restart was already used. HTTP servers are not
+ * restarted (their process is not ours; each request already reconnects).
+ *
+ * If the restarted server lists different tools, `toolsChanged` is set so the
+ * run re-lists them at its next turn boundary.
+ *
+ * @module lib/engine/mcp/supervisor
+ */
+
+import { connectMcpServer } from "./client.mjs";
+
+export const MAX_RESTARTS_PER_RUN = 1;
+
+/**
+ * @param {import('./config.mjs').McpServerConfig} config
+ * @param {Parameters<typeof connectMcpServer>[1]} deps
+ * @param {import('./client.mjs').McpConnection} first
+ * @param {{connect?:typeof connectMcpServer, maxRestarts?:number}} [o]
+ */
+export function superviseConnection(config, deps, first, { connect = connectMcpServer, maxRestarts = MAX_RESTARTS_PER_RUN } = {}) {
+  let current = first;
+  let restarts = 0;
+  let closed = false;
+  let pendingRefresh = false;
+  /** @type {Promise<{ok:true, restarted:boolean, exhausted:boolean}|{ok:false, error:string}>|null} */
+  let restarting = null;
+  const toolNames = (/** @type any */ c) => JSON.stringify(c.tools.map((/** @type any */ t) => t.name));
+
+  /** @returns {Promise<{ok:true, restarted:boolean, exhausted:boolean}|{ok:false, error:string}>} */
+  const ensure = async () => {
+    if (closed || current.isAlive() || config.transport !== "stdio") return { ok: true, restarted: false, exhausted: false };
+    if (restarts >= maxRestarts) return { ok: true, restarted: false, exhausted: true };
+    if (!restarting) {
+      restarting = (async () => {
+        restarts++;
+        const before = toolNames(current);
+        const r = await connect(config, deps);
+        if (!r.ok) return { ok: /** @type {false} */ (false), error: `MCP server "${config.name}" had stopped, and restarting it failed: ${r.error}` };
+        await current.close().catch(() => {});
+        current = r.connection;
+        if (toolNames(current) !== before) pendingRefresh = true;
+        return { ok: /** @type {true} */ (true), restarted: true, exhausted: false };
+      })().finally(() => {
+        restarting = null;
+      });
+    }
+    return restarting;
+  };
+
+  const note = `(The MCP server "${config.name}" had stopped; it was restarted for this call.)`;
+  const exhaustedNote = ` It was already restarted once in this run and is not restarted again.`;
+
+  /**
+   * @template {{ok:boolean, content?:string, error?:string}} R
+   * @param {() => Promise<R>} op
+   * @returns {Promise<R|{ok:false, error:string}>}
+   */
+  const withRestart = async (op) => {
+    const e = await ensure();
+    if (!e.ok) return { ok: false, error: e.error };
+    const r = await op();
+    if (e.restarted) return r.ok ? { ...r, content: `${r.content}\n\n${note}` } : { ...r, error: `${r.error}\n\n${note}` };
+    if (e.exhausted && !r.ok) return { ...r, error: `${r.error}${exhaustedNote}` };
+    return r;
+  };
+
+  return {
+    get name() {
+      return current.name;
+    },
+    get protocolVersion() {
+      return current.protocolVersion;
+    },
+    get serverInfo() {
+      return current.serverInfo;
+    },
+    get instructions() {
+      return current.instructions;
+    },
+    get capabilities() {
+      return current.capabilities;
+    },
+    get tools() {
+      return current.tools;
+    },
+    get toolsChanged() {
+      return pendingRefresh || current.toolsChanged;
+    },
+    get restarts() {
+      return restarts;
+    },
+    isAlive: () => current.isAlive(),
+    async refreshTools() {
+      pendingRefresh = false;
+      return current.refreshTools();
+    },
+    /** @param {string} tool @param {object} args @param {{signal?:AbortSignal, timeoutMs?:number}} [o] */
+    callTool: (tool, args, o) => withRestart(() => current.callTool(tool, args, o)),
+    /** @param {{signal?:AbortSignal}} [o] */
+    listResources: (o) => withRestart(() => current.listResources(o)),
+    /** @param {string} uri @param {{signal?:AbortSignal}} [o] */
+    readResource: (uri, o) => withRestart(() => current.readResource(uri, o)),
+    async close() {
+      closed = true;
+      await current.close();
+    },
+  };
+}

package/lib/engine/messages.mjs

@@ -0,0 +1,104 @@
+/**
+ * lib/engine/messages.mjs — the engine's canonical conversation shape (pure).
+ *
+ * The loop, the session store and both wires speak ONE message shape, so a
+ * transcript written while talking OpenAI Chat can be resumed on Anthropic
+ * Messages and vice versa. It is deliberately block-structured (the richer of
+ * the two wire formats); the OpenAI wire flattens it on the way out.
+ *
+ *   { role: 'user',      content: Array<TextBlock | ToolResultBlock> }
+ *   { role: 'assistant', content: Array<TextBlock | ToolUseBlock | ThinkingBlock> }
+ *
+ *   TextBlock       { type:'text', text }
+ *   ToolUseBlock    { type:'tool_use', id, name, input, inputError?, rawInput? }
+ *   ToolResultBlock { type:'tool_result', tool_use_id, content: string, is_error? }
+ *   ThinkingBlock   { type:'thinking', thinking, signature? }
+ *
+ * `inputError` / `rawInput` mark a tool call whose argument JSON did not parse;
+ * the loop attempts a repair and the wires never send those two fields.
+ *
+ * @module lib/engine/messages
+ */
+
+/** @param {string} text */
+export function userText(text) {
+  return { role: "user", content: [{ type: "text", text: String(text) }] };
+}
+
+/**
+ * Concatenate the text blocks of a message.
+ * @param {{content: any[]}|null|undefined} message
+ */
+export function messageText(message) {
+  if (!message || !Array.isArray(message.content)) return "";
+  return message.content
+    .filter((b) => b && b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("");
+}
+
+/** @param {{content:any[]}} message */
+export function toolUses(message) {
+  return Array.isArray(message?.content) ? message.content.filter((b) => b && b.type === "tool_use") : [];
+}
+
+/**
+ * Make a history safe to send:
+ *   · consecutive same-role messages are merged (a resumed session whose last
+ *     record is a user turn, followed by the new prompt, is one user turn);
+ *   · an assistant `tool_use` with no matching `tool_result` in the next user
+ *     turn (a run killed mid-tool) gets a synthetic error result, because both
+ *     wires reject an unanswered tool call;
+ *   · empty messages are dropped.
+ * Returns a new array; the input is not mutated.
+ *
+ * @param {Array<{role:string, content:any[]}>} messages
+ */
+export function normaliseHistory(messages) {
+  /** @type {Array<{role:string, content:any[]}>} */
+  const merged = [];
+  for (const m of messages || []) {
+    if (!m || (m.role !== "user" && m.role !== "assistant") || !Array.isArray(m.content)) continue;
+    if (m.content.length === 0) continue;
+    const last = merged[merged.length - 1];
+    if (last && last.role === m.role) last.content = [...last.content, ...m.content];
+    else merged.push({ role: m.role, content: [...m.content] });
+  }
+  for (let i = 0; i < merged.length; i++) {
+    const m = merged[i];
+    if (m.role !== "assistant") continue;
+    const uses = toolUses(m);
+    if (uses.length === 0) continue;
+    let next = merged[i + 1];
+    if (!next || next.role !== "user") {
+      next = { role: "user", content: [] };
+      merged.splice(i + 1, 0, next);
+    }
+    const answered = new Set(next.content.filter((b) => b.type === "tool_result").map((b) => b.tool_use_id));
+    const missing = uses
+      .filter((u) => !answered.has(u.id))
+      .map((u) => ({
+        type: "tool_result",
+        tool_use_id: u.id,
+        content: "The run was interrupted before this tool finished; no result was recorded.",
+        is_error: true,
+      }));
+    // Tool results lead the user turn: the OpenAI wire requires tool messages
+    // to follow the assistant message directly.
+    if (missing.length > 0) next.content = [...missing, ...next.content];
+  }
+  return merged;
+}
+
+/**
+ * Deterministic JSON (sorted keys) — used for loop-detection signatures, where
+ * `{a,b}` and `{b,a}` are the same call.
+ * @param {unknown} v
+ * @returns {string}
+ */
+export function stableStringify(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(v).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(/** @type any */ (v)[k])}`).join(",")}}`;
+}

package/lib/engine/output/json.mjs

@@ -0,0 +1,164 @@
+/**
+ * lib/engine/output/json.mjs — the headless result object (pure).
+ *
+ * maestro's dispatcher, responder and cost ledger already parse the JSON the
+ * `claude --print --output-format json` lane emits. The engine's result is a
+ * SUPERSET of that shape, so those readers work unchanged:
+ *
+ *   type:'result', subtype, is_error, result, session_id, num_turns,
+ *   duration_ms, duration_api_ms, total_cost_usd,
+ *   usage{ input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens },
+ *   permission_denials
+ *
+ * plus a `cohort` block with what only the gateway knows: request ids, the
+ * tier that served, integer micro-USD cost, quota state, the normalised usage
+ * record (design §4.5), and why the run stopped.
+ *
+ * `total_cost_usd` comes from the gateway's `x-cohort-cost-micros` and nothing
+ * else. If ANY request in the run lacked the header the figure is `null` —
+ * a partial sum would under-report, and a local price guess is exactly the
+ * pricer bug the design removes (C7). `cohort.costMicros` keeps the exact
+ * integer as a string; the float exists only at this display boundary.
+ *
+ * @module lib/engine/output/json
+ */
+
+import { toResultUsage, emptyUsage } from "../wire/usage.mjs";
+import { refusalFromWireError } from "../wire/errors.mjs";
+
+/**
+ * @param {import('../loop.mjs').LoopStop} stop
+ * @returns {{ subtype: 'success'|'error_max_turns'|'error_max_budget_usd'|'error_during_execution', isError: boolean, message: string|null }}
+ */
+export function classifyStop(stop) {
+  switch (stop.kind) {
+    case "completed":
+      return { subtype: "success", isError: false, message: null };
+    case "max_turns":
+      return { subtype: "error_max_turns", isError: true, message: `Reached the maximum number of turns (${stop.maxTurns}).` };
+    case "wall_clock":
+      return { subtype: "error_during_execution", isError: true, message: `Stopped after the ${stop.wallClockMs} ms time limit.` };
+    case "aborted":
+      return { subtype: "error_during_execution", isError: true, message: "The run was aborted." };
+    case "wire_error":
+      return {
+        subtype: "error_during_execution",
+        isError: true,
+        message: `Model request failed (${stop.error?.code ?? "unknown"}): ${stop.error?.message ?? ""}`.trim(),
+      };
+    case "loop_detected":
+      return {
+        subtype: "error_during_execution",
+        isError: true,
+        message: `Stopped: ${stop.tool} was called with identical input ${stop.repeats} turns in a row.`,
+      };
+    case "hook_stopped":
+      return { subtype: "error_during_execution", isError: true, message: `Stopped by a hook: ${stop.reason}` };
+    case "max_budget":
+      // W4-E1 (row 24): --max-budget-usd reached; no further model call was made.
+      return {
+        subtype: "error_max_budget_usd",
+        isError: true,
+        message: `Reached the maximum budget ($${stop.maxBudgetUsd}); spent $${Number(BigInt(stop.spentMicros)) / 1e6}.`,
+      };
+    default:
+      throw new Error(`classifyStop: unhandled stop kind ${JSON.stringify(/** @type any */ (stop).kind)}`);
+  }
+}
+
+/** @param {string|null} micros */
+export function microsToUsd(micros) {
+  if (micros == null) return null;
+  return Number(BigInt(micros)) / 1e6;
+}
+
+/**
+ * @param {object} p
+ * @param {Awaited<ReturnType<typeof import('../loop.mjs').runLoop>>} p.outcome
+ * @param {string} p.sessionId
+ * @param {number} p.durationMs
+ * @param {string} p.wire
+ * @param {{ path:string, writeFailures:number, skipped:number }|null} [p.session]
+ */
+export function buildResult({ outcome, sessionId, durationMs, wire, session = null }) {
+  const c = classifyStop(outcome.stop);
+  return {
+    type: "result",
+    subtype: c.subtype,
+    is_error: c.isError,
+    result: c.isError ? c.message : outcome.resultText,
+    session_id: sessionId,
+    num_turns: outcome.numTurns,
+    duration_ms: durationMs,
+    duration_api_ms: outcome.apiMs,
+    total_cost_usd: microsToUsd(outcome.costMicros),
+    usage: toResultUsage(outcome.usage),
+    permission_denials: [],
+    cohort: {
+      wire,
+      model: outcome.model,
+      modelTier: outcome.modelTier,
+      requestIds: outcome.requestIds,
+      costMicros: outcome.costMicros,
+      quota: outcome.quota,
+      usage: outcome.usage,
+      // CF-158: the gateway's own view of the same turns, off the terminal
+      // cohort frame — a DISTINCT key from `usage` above, which is the engine's
+      // accumulated count from the wire. The two are near-equal but not the
+      // same number, and naming one after the other is exactly the silent
+      // divergence CF-158 exists to stop. null when no frame reported usage.
+      //
+      // SCOPE, which differs from `usage` above: this is the PARENT loop's own
+      // requests. cli.mjs replaces `usage` with the parent+children aggregate
+      // when a run has subagents (aggregateUsage), and child frame usage is not
+      // threaded through that record — it is counted run-wide only by the
+      // shared budget meter, as `cohort.budget.observedTokens`. Two adjacent
+      // keys with different scopes is worth one comment; silently differing
+      // scopes is the same trap as silently differing numbers.
+      gatewayUsage: outcome.gatewayUsage ?? null,
+      stop: outcome.stop.kind === "wire_error" ? { kind: "wire_error" } : outcome.stop,
+      error: outcome.stop.kind === "wire_error" ? outcome.stop.error : null,
+      // A run that ended on a gateway refusal carries it in the §4.8 shape;
+      // maestro's rate-guard classifyCohortRefusal reads exactly this.
+      refusal: outcome.stop.kind === "wire_error" ? refusalFromWireError(outcome.stop.error) : null,
+      lastText: c.isError ? outcome.resultText : undefined,
+      session,
+    },
+  };
+}
+
+/**
+ * A result for a run that failed before the loop started (bad flags, no token,
+ * unknown session). Same shape, so a caller never special-cases it.
+ * @param {{ sessionId:string|null, code:string, message:string, durationMs:number, wire?:string|null }} p
+ */
+export function buildSetupErrorResult({ sessionId, code, message, durationMs, wire = null }) {
+  return {
+    type: "result",
+    subtype: "error_during_execution",
+    is_error: true,
+    result: message,
+    session_id: sessionId,
+    num_turns: 0,
+    duration_ms: durationMs,
+    duration_api_ms: 0,
+    total_cost_usd: null,
+    usage: toResultUsage(emptyUsage()),
+    permission_denials: [],
+    cohort: {
+      wire,
+      model: null,
+      modelTier: null,
+      requestIds: [],
+      costMicros: null,
+      quota: null,
+      usage: emptyUsage("estimated"),
+      // No request was made, so the gateway reported nothing (CF-158).
+      gatewayUsage: null,
+      stop: { kind: "setup_error" },
+      error: { kind: "setup", code, message },
+      refusal: null,
+      session: null,
+    },
+  };
+}