@mono-agent/agent-runtime 0.1.0

package/src/agent/transcript.js

@@ -0,0 +1,227 @@
+// Snapshot/render helpers for preserving partial agent progress across
+// continuations. The worker writes a bounded "transcript tail" when a run
+// terminates with usable progress but no structured result, and the coordinator
+// passes it through `diagnosticsSeed.resume_snapshot` so the next worker can
+// prepend it to the system prompt.
+
+import { readRuntimeBrand } from "./tools/shared/runtime-context.js";
+
+// intelligence-ramp Phase 5.3: keep more turns but reserve verbatim slots for
+// the most recent few. Older turns ride along as one-paragraph summaries so
+// the SDK-mode agent can reason about the whole arc without paying the full
+// payload cost (CLI agents get true session resume; this is the SDK fallback).
+const DEFAULT_MAX_TURNS = 12;
+const DEFAULT_VERBATIM_TURNS = 3;
+const DEFAULT_MAX_CHARS = 24_000;
+const DEFAULT_TOOL_RESULT_CHARS = 2_400;
+const DEFAULT_ASSISTANT_TEXT_CHARS = 4_000;
+const DEFAULT_TURN_SUMMARY_CHARS = 320;
+
+function truncate(text, limit, suffix = "…") {
+  const value = String(text ?? "");
+  if (!Number.isFinite(limit) || limit <= 0 || value.length <= limit) return value;
+  return `${value.slice(0, Math.max(0, limit - suffix.length))}${suffix}`;
+}
+
+function flattenContent(content) {
+  if (!Array.isArray(content)) {
+    if (typeof content === "string") return content;
+    return "";
+  }
+  return content
+    .map((block) => {
+      if (!block || typeof block !== "object") return "";
+      if (block.type === "text" && typeof block.text === "string") return block.text;
+      if (block.type === "thinking" && typeof block.text === "string") return block.text;
+      if (block.type === "tool_result") {
+        if (typeof block.content === "string") return block.content;
+        if (Array.isArray(block.content)) return flattenContent(block.content);
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("");
+}
+
+function describeToolUse(block) {
+  if (!block || block.type !== "tool_use") return null;
+  return {
+    id: block.id || null,
+    name: block.name || "",
+    input_summary: truncate(JSON.stringify(block.input || {}), DEFAULT_TOOL_RESULT_CHARS),
+  };
+}
+
+function describeToolResult(block, { toolResultChars }) {
+  if (!block || block.type !== "tool_result") return null;
+  return {
+    tool_use_id: block.tool_use_id || null,
+    is_error: !!block.is_error,
+    content: truncate(flattenContent(block.content), toolResultChars || DEFAULT_TOOL_RESULT_CHARS),
+  };
+}
+
+// Compress one turn into a single short paragraph: tool names + an excerpt
+// of the assistant text. Used for older turns that we keep around for
+// continuity but can't afford verbatim.
+function summarizeTurn(turn, { maxChars = DEFAULT_TURN_SUMMARY_CHARS } = {}) {
+  const parts = [];
+  if (turn.assistant_text) {
+    const firstLine = turn.assistant_text.split(/\r?\n/).find((line) => line.trim());
+    if (firstLine) parts.push(truncate(firstLine.trim(), Math.floor(maxChars * 0.6)));
+  }
+  const toolUseNames = (turn.tool_uses || []).map((u) => u.name).filter(Boolean);
+  if (toolUseNames.length) {
+    parts.push(`tools: ${toolUseNames.slice(0, 5).join(", ")}${toolUseNames.length > 5 ? "…" : ""}`);
+  }
+  const errorCount = (turn.tool_results || []).filter((r) => r.is_error).length;
+  if (errorCount > 0) parts.push(`${errorCount} tool error${errorCount === 1 ? "" : "s"}`);
+  return truncate(parts.join("; ") || "no narrative", maxChars);
+}
+
+// Walk the captured event log backwards and collect the most recent N turns
+// worth of (assistant text, tool calls, tool results). Returns null when there
+// is nothing usable to resume from. Older turns beyond `verbatimTurns` are
+// summarized into a one-paragraph snippet; only the trailing `verbatimTurns`
+// keep their full assistant text + tool detail.
+export function buildTranscriptTailSnapshot(events, {
+  maxTurns = DEFAULT_MAX_TURNS,
+  verbatimTurns = DEFAULT_VERBATIM_TURNS,
+  maxChars = DEFAULT_MAX_CHARS,
+  toolResultChars = DEFAULT_TOOL_RESULT_CHARS,
+  assistantTextChars = DEFAULT_ASSISTANT_TEXT_CHARS,
+  turnSummaryChars = DEFAULT_TURN_SUMMARY_CHARS,
+} = {}) {
+  if (!Array.isArray(events) || events.length === 0) return null;
+  const turns = [];
+  let currentAssistantText = "";
+  let currentThinking = "";
+  let currentToolUses = [];
+  let currentToolResults = [];
+
+  function flushTurn() {
+    if (!currentAssistantText && !currentThinking && currentToolUses.length === 0 && currentToolResults.length === 0) {
+      return;
+    }
+    turns.push({
+      assistant_text: truncate(currentAssistantText.trim(), assistantTextChars) || null,
+      thinking: truncate(currentThinking.trim(), assistantTextChars) || null,
+      tool_uses: currentToolUses,
+      tool_results: currentToolResults,
+    });
+    currentAssistantText = "";
+    currentThinking = "";
+    currentToolUses = [];
+    currentToolResults = [];
+  }
+
+  for (const event of events) {
+    if (!event || typeof event !== "object") continue;
+    if (event.type === "assistant" && Array.isArray(event.message?.content)) {
+      for (const block of event.message.content) {
+        if (block?.type === "text" && typeof block.text === "string") {
+          currentAssistantText += block.text;
+        } else if (block?.type === "thinking" && typeof block.text === "string") {
+          currentThinking += block.text;
+        } else if (block?.type === "tool_use") {
+          const summary = describeToolUse(block);
+          if (summary) currentToolUses.push(summary);
+        }
+      }
+    } else if (event.type === "user" && Array.isArray(event.message?.content)) {
+      for (const block of event.message.content) {
+        if (block?.type === "tool_result") {
+          const summary = describeToolResult(block, { toolResultChars });
+          if (summary) currentToolResults.push(summary);
+        }
+      }
+      if (currentToolResults.length > 0) flushTurn();
+    } else if (event.type === "final" || event.type === "error" || event.type === "cancelled") {
+      flushTurn();
+    }
+  }
+  flushTurn();
+
+  if (turns.length === 0) return null;
+  const totalCap = Math.max(1, Number(maxTurns) || DEFAULT_MAX_TURNS);
+  const verbatimCap = Math.max(1, Number(verbatimTurns) || DEFAULT_VERBATIM_TURNS);
+  const tailWindow = turns.slice(-totalCap);
+  const verbatimSlice = tailWindow.slice(-Math.min(verbatimCap, tailWindow.length));
+  const summarizedSlice = tailWindow.slice(0, Math.max(0, tailWindow.length - verbatimSlice.length));
+  // Each summarized entry retains its turn index (so renderResumeSnapshot
+  // labels them correctly) and a one-paragraph description.
+  const earlierTurnSummaries = summarizedSlice.map((turn, idx) => ({
+    turn_index: turns.length - tailWindow.length + idx + 1,
+    summary: summarizeTurn(turn, { maxChars: turnSummaryChars }),
+  }));
+  const brand = readRuntimeBrand();
+  const snapshot = {
+    schema: `${brand.schemaPrefix}.transcript-tail.v1`,
+    captured_at: Date.now(),
+    turn_count: turns.length,
+    earlier_turn_summaries: earlierTurnSummaries,
+    turns: verbatimSlice,
+  };
+  const json = JSON.stringify(snapshot);
+  if (json.length <= maxChars) return snapshot;
+  // Fall back to fewer verbatim turns if the JSON exceeds maxChars; the
+  // summaries are tiny and stay.
+  let trimmedTurns = verbatimSlice.slice();
+  while (trimmedTurns.length > 1 && JSON.stringify({ ...snapshot, turns: trimmedTurns }).length > maxChars) {
+    trimmedTurns = trimmedTurns.slice(1);
+  }
+  return { ...snapshot, turns: trimmedTurns, truncated: true };
+}
+
+export function renderResumeSnapshot(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.turns) || snapshot.turns.length === 0) return "";
+  const lines = [];
+  lines.push("<resume_context>");
+  lines.push(`A previous attempt at this task ran ${snapshot.turn_count || snapshot.turns.length} turn(s) before the provider connection dropped.`);
+  lines.push("Below is the trail of recent work so you can continue from where it left off rather than starting over. Tool results are abbreviated; re-read files as needed if you require the full content.");
+  lines.push("");
+  // Phase 5.3: earlier turns are present as one-paragraph summaries; only the
+  // most recent few are verbatim. Render summaries first so the agent gets
+  // the full arc, then the recent verbatim turns for fine-grained context.
+  if (Array.isArray(snapshot.earlier_turn_summaries) && snapshot.earlier_turn_summaries.length > 0) {
+    lines.push("### Earlier turns (summarized)");
+    for (const entry of snapshot.earlier_turn_summaries) {
+      lines.push(`- Turn ${entry.turn_index}: ${entry.summary}`);
+    }
+    lines.push("");
+  }
+  const verbatimStartIndex = (snapshot.turn_count || snapshot.turns.length) - snapshot.turns.length + 1;
+  snapshot.turns.forEach((turn, index) => {
+    const label = `Turn ${verbatimStartIndex + index}`;
+    lines.push(`### ${label}`);
+    if (turn.thinking) {
+      lines.push(`Thinking: ${turn.thinking}`);
+    }
+    if (turn.assistant_text) {
+      lines.push(`Assistant: ${turn.assistant_text}`);
+    }
+    if (Array.isArray(turn.tool_uses) && turn.tool_uses.length > 0) {
+      for (const use of turn.tool_uses) {
+        lines.push(`Tool call: ${use.name}(${use.input_summary || ""})`);
+      }
+    }
+    if (Array.isArray(turn.tool_results) && turn.tool_results.length > 0) {
+      for (const result of turn.tool_results) {
+        const prefix = result.is_error ? "Tool result (error)" : "Tool result";
+        lines.push(`${prefix}: ${result.content || ""}`);
+      }
+    }
+    lines.push("");
+  });
+  lines.push("</resume_context>");
+  return lines.join("\n");
+}
+
+export const RESUME_SNAPSHOT_DEFAULTS = {
+  maxTurns: DEFAULT_MAX_TURNS,
+  verbatimTurns: DEFAULT_VERBATIM_TURNS,
+  maxChars: DEFAULT_MAX_CHARS,
+  toolResultChars: DEFAULT_TOOL_RESULT_CHARS,
+  assistantTextChars: DEFAULT_ASSISTANT_TEXT_CHARS,
+  turnSummaryChars: DEFAULT_TURN_SUMMARY_CHARS,
+};

package/src/ai/backend.js

@@ -0,0 +1,17 @@
+import { RUNTIME_CAPABILITIES, runtimeCapabilities } from "./runtime/capabilities.js";
+
+// Back-compat export name for callers that still ask for backend capabilities.
+// The canonical source is the runtime bridge registry.
+export const BACKEND_CAPABILITIES = RUNTIME_CAPABILITIES;
+
+export function backendCapabilities(sdkOrModel) {
+  return runtimeCapabilities(sdkOrModel);
+}
+
+export function backendUsesExecenvConfig(sdk) {
+  return !!RUNTIME_CAPABILITIES[sdk]?.native_runtime_config;
+}
+
+export function backendSupportsSessionResume(sdk) {
+  return !!RUNTIME_CAPABILITIES[sdk]?.supports_session_resume;
+}

package/src/ai/cost.js

@@ -0,0 +1,164 @@
+import { getModel as getPiModel } from "@earendil-works/pi-ai";
+
+const CLAUDE_PRICING = {
+  "claude-haiku-4-5-20251001": { input: 1.0, cacheRead: 0.1, cacheWrite: 1.25, output: 5.0 },
+  "claude-haiku-4-5": { input: 1.0, cacheRead: 0.1, cacheWrite: 1.25, output: 5.0 },
+  "claude-sonnet-4-6": { input: 3.0, cacheRead: 0.3, cacheWrite: 3.75, output: 15.0 },
+  "claude-sonnet-4-5": { input: 3.0, cacheRead: 0.3, cacheWrite: 3.75, output: 15.0 },
+  "claude-sonnet-4": { input: 3.0, cacheRead: 0.3, cacheWrite: 3.75, output: 15.0 },
+  "claude-opus-4-7": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
+  "claude-opus-4-6": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
+  "claude-opus-4-5": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
+};
+
+function finiteOrNull(value) {
+  if (value == null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+function rate(value, fallback = 0) {
+  const n = finiteOrNull(value);
+  return n == null ? fallback : n;
+}
+
+function normalizePricing(pricing, { source, priced = true, missing = 0 } = {}) {
+  if (!pricing || typeof pricing !== "object") return null;
+  const input = rate(pricing.input ?? pricing.input_per_million, missing);
+  const cacheRead = rate(
+    pricing.cacheRead
+      ?? pricing.cachedInput
+      ?? pricing.cached_input_per_million,
+    input,
+  );
+  const cacheWrite = rate(
+    pricing.cacheWrite
+      ?? pricing.cache_write_per_million
+      ?? pricing.cache_creation_per_million,
+    missing,
+  );
+  const output = rate(pricing.output ?? pricing.output_per_million, missing);
+  return { input, cacheRead, cacheWrite, output, source, priced };
+}
+
+function zeroPricing(source) {
+  return { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, source, priced: true };
+}
+
+function unknownPricing() {
+  return { input: null, cacheRead: null, cacheWrite: null, output: null, source: "unknown", priced: false };
+}
+
+function parseReference(reference) {
+  if (typeof reference !== "string" || !reference.trim()) return null;
+  if (reference.startsWith("vercel:")) {
+    const rest = reference.slice("vercel:".length);
+    const i = rest.indexOf(":");
+    return i > 0 ? { sdk: "pi", provider: rest.slice(0, i), model: rest.slice(i + 1) } : null;
+  }
+  if (reference.startsWith("codex:")) {
+    return { sdk: "pi", provider: "openai-codex", model: reference.slice("codex:".length) };
+  }
+  if (reference.startsWith("openai:")) {
+    return { sdk: "pi", provider: "openai", model: reference.slice("openai:".length) };
+  }
+  if (reference.startsWith("pi:")) {
+    const rest = reference.slice("pi:".length);
+    const i = rest.indexOf(":");
+    return i > 0 ? { sdk: "pi", provider: rest.slice(0, i), model: rest.slice(i + 1) } : null;
+  }
+  const i = reference.indexOf(":");
+  if (i <= 0) return { sdk: null, model: reference };
+  return { sdk: reference.slice(0, i), model: reference.slice(i + 1) };
+}
+
+function isPrivateHost(baseUrl) {
+  try {
+    const host = new URL(baseUrl).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    return host === "localhost"
+      || host === "host.docker.internal"
+      || host === "::1"
+      || host.startsWith("127.")
+      || host.startsWith("10.")
+      || host.startsWith("192.168.")
+      || /^172\.(1[6-9]|2\d|3[01])\./.test(host)
+      || /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host);
+  } catch {
+    return false;
+  }
+}
+
+function pricingHasRates(pricing = {}) {
+  return [
+    pricing.input_per_million,
+    pricing.cached_input_per_million,
+    pricing.cache_write_per_million,
+    pricing.output_per_million,
+  ].some((value) => finiteOrNull(value) != null);
+}
+
+function piCatalogPricing(parsed) {
+  if (parsed?.sdk !== "pi" || !parsed.provider || !parsed.model) return null;
+  try {
+    const model = getPiModel(parsed.provider, parsed.model);
+    return model?.cost ? normalizePricing(model.cost, { source: "pi-catalog" }) : null;
+  } catch {
+    return null;
+  }
+}
+
+function claudePricing(parsed) {
+  if (parsed?.sdk !== "claude") return null;
+  return normalizePricing(CLAUDE_PRICING[parsed.model], { source: "claude-table" });
+}
+
+// `resolveCustomPricing(parsed) -> NormalizedPricing | null` lets a host plug
+// in user-defined pricing tables. Hosts query custom model/provider stores
+// in src/core/custom-pricing.js and passes the closure in via `generateResponse`.
+// The pricing helpers below (`normalizePricing`, `zeroPricing`, `unknownPricing`,
+// `pricingHasRates`, `isPrivateHost`, `parseReference`) are exported so hosts
+// can build their own resolvers without re-implementing the row-shape conversion.
+export function resolvePricing({ resolveCustomPricing, model } = {}) {
+  const parsed = parseReference(model);
+  if (!parsed) return unknownPricing();
+  const custom = typeof resolveCustomPricing === "function"
+    ? resolveCustomPricing(parsed)
+    : null;
+  return custom
+    || piCatalogPricing(parsed)
+    || claudePricing(parsed)
+    || unknownPricing();
+}
+
+export { normalizePricing, zeroPricing, unknownPricing, pricingHasRates, isPrivateHost, parseReference };
+
+export function estimateCost({
+  resolveCustomPricing,
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+  cachedTokens = 0,
+  cacheWriteTokens = 0,
+  cacheCreationTokens = 0,
+} = {}) {
+  const pricing = resolvePricing({ resolveCustomPricing, model });
+  if (!pricing?.priced) return null;
+  const cacheRead = Math.max(0, Number(cachedTokens) || 0);
+  const cacheWrite = Math.max(0, Number(cacheWriteTokens ?? cacheCreationTokens) || 0);
+  const input = Math.max(0, Number(inputTokens) || 0);
+  const output = Math.max(0, Number(outputTokens) || 0);
+  const parts = [
+    [input, pricing.input],
+    [cacheRead, pricing.cacheRead],
+    [cacheWrite, pricing.cacheWrite],
+    [output, pricing.output],
+  ];
+  let total = 0;
+  for (const [tokens, price] of parts) {
+    if (tokens <= 0) continue;
+    const priceNumber = finiteOrNull(price);
+    if (priceNumber == null) return null;
+    total += (tokens / 1_000_000) * priceNumber;
+  }
+  return total;
+}

package/src/ai/failure.js

@@ -0,0 +1,165 @@
+export const FAILURE_KINDS = [
+  "spawn",
+  "timeout",
+  "stall",
+  "usage_limit",
+  "invalid_result",
+  "invalid_delegation",
+  "tool_failure",
+  "provider_unavailable",
+  "provider_unavailable_exhausted",
+  "child_failed",
+  "budget_exceeded",
+  "cancelled",
+  "cancelled_user",
+  "cancelled_stale",
+  "cancelled_shutdown",
+  "cancelled_signal",
+  "abandoned",
+  // v33: planner delegated to an agent outside the effective team's roster
+  // (lead + members). Replaces the retired delegation_agent_not_allowed kind.
+  "delegation_agent_not_in_team",
+  "delegation_team_roster_empty",
+  // Provider session resume: the host asked to resume a provider session that
+  // is no longer live (expired, evicted, or process died) or that is still
+  // executing another turn. Both are non-retryable at the router level; the
+  // host retries once without the session (replaying history) instead.
+  "session_not_found",
+  "session_busy",
+];
+
+const USAGE_LIMIT_RE = /(rate limit|usage limit|max tokens|max turns|context length|too many tokens)/i;
+const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|service unavailable|503|502|gateway|fetch failed|network|websocket)/i;
+const TOOL_FAILURE_RE = /(tool .* failed|mcp tool|permission denied|EACCES|read-only file system)/i;
+const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|invalid api key|incorrect api key|authentication|authorization|not authorized|forbidden|billing|insufficient[_ ]quota|quota exceeded|model[_ ]not[_ ]found|unsupported model|permission denied|bad request|401|403|404)/i;
+const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error)/i;
+export const PROVIDER_ABORT_RE = /\b(?:terminated|aborted before final output|aborted before final|stream aborted|stream was aborted|stream disconnected|websocket (?:error|disconnected|closed)|socket hang up|und_err_socket|econnreset|premature close)\b/i;
+
+function requestIdFromText(text) {
+  const match = /\b(?:request[_ -]?id|req[_ -]?id)\s*[:#]?\s*([A-Za-z0-9._:-]{8,})/i.exec(text || "");
+  return match?.[1]?.replace(/[.,;:]+$/, "") || null;
+}
+
+function retryableProviderSubkind(text) {
+  if (/overloaded/i.test(text)) return "overloaded";
+  if (/429|too many requests|rate limit/i.test(text)) return "rate_limited";
+  if (/timed? ?out|etimedout/i.test(text)) return "timeout";
+  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network/i.test(text)) return "network";
+  if (/500|502|503|504|service unavailable|gateway|internal server error/i.test(text)) return "server_error";
+  if (/retry your request|try again later|request id|processing your request/i.test(text)) return "retryable_request";
+  return null;
+}
+
+export function retryableProviderFailureInfo({
+  errorText = "",
+  stderrTail = "",
+  failureKind = null,
+} = {}) {
+  if (failureKind && failureKind !== "provider_unavailable") {
+    return { retryable: false, subkind: null, requestId: null };
+  }
+  const haystack = `${errorText || ""}\n${stderrTail || ""}`.trim();
+  if (!haystack) return { retryable: false, subkind: null, requestId: null };
+  const requestId = requestIdFromText(haystack);
+  if (NON_RETRYABLE_PROVIDER_RE.test(haystack)) {
+    return { retryable: false, subkind: "non_retryable", requestId };
+  }
+  const subkind = (failureKind === "provider_unavailable" && PROVIDER_ABORT_RE.test(haystack))
+    ? "terminated"
+    : retryableProviderSubkind(haystack);
+  return {
+    retryable: !!subkind || RETRYABLE_PROVIDER_RE.test(haystack),
+    subkind: subkind || (RETRYABLE_PROVIDER_RE.test(haystack) ? "retryable_request" : null),
+    requestId,
+  };
+}
+
+// classifyFailure is the single source of truth for mapping the disparate
+// inputs the coordinator sees on a worker exit (process code, signal, error
+// text, stderr tail, timeout flag, cancellation flag, mcp init result, parse
+// errors) into one of FAILURE_KINDS. Every adapter / spawn-worker / watcher
+// path should funnel through this so the values in `task_runs.failure_kind`
+// stay coherent.
+export function classifyFailure({
+  exitCode = null,
+  signal = null,
+  errorText = "",
+  stderrTail = "",
+  timedOut = false,
+  cancelRequested = false,
+  cancelInitiator = null,
+  resultParseError = false,
+  mcpInitFailed = false,
+  budgetExceeded = false,
+  childFailed = false,
+  hint = null,
+} = {}) {
+  if (budgetExceeded) return "budget_exceeded";
+  if (childFailed) return "child_failed";
+  if (resultParseError) return "invalid_result";
+  if (timedOut) return "timeout";
+  if (cancelRequested) {
+    // R5: distinguish a clean coordinator shutdown from a stale-run reconcile.
+    // Both the audit and the operator care which one: a coordinator_shutdown
+    // means "we asked you to stop", and the work is reconciliation-eligible
+    // on the next boot. A stale_reconcile means the run was already orphaned
+    // (no live coordinator to ask). Mapping both to cancelled_stale hid the
+    // difference and confused the audit-period reports.
+    if (cancelInitiator === "coordinator_shutdown") return "cancelled_shutdown";
+    if (cancelInitiator === "stale_reconcile") return "cancelled_stale";
+    if (cancelInitiator === "worker_signal") return "cancelled_signal";
+    if (cancelInitiator === "user" || cancelInitiator === "api_cancel") return "cancelled_user";
+    // An in-flight run cancelled by the settings-backed turn guardrail reuses
+    // budget_exceeded so dashboards / reports don't have to learn a new label.
+    if (cancelInitiator === "budget") return "budget_exceeded";
+    return "cancelled";
+  }
+  if (exitCode === 130 || signal === "SIGTERM" || signal === "SIGINT") return "cancelled_signal";
+  if (signal === "SIGKILL" && !exitCode) return "abandoned";
+
+  if (hint && FAILURE_KINDS.includes(hint)) return hint;
+
+  const haystack = `${errorText || ""}\n${stderrTail || ""}`;
+  if (USAGE_LIMIT_RE.test(haystack)) return "usage_limit";
+  if (TOOL_FAILURE_RE.test(haystack)) return "tool_failure";
+  if (PROVIDER_UNAVAILABLE_RE.test(haystack)) return "provider_unavailable";
+  if (mcpInitFailed && haystack.toLowerCase().includes("mcp")) return "tool_failure";
+
+  if (exitCode === 0 && !errorText) return null;
+  return "spawn";
+}
+
+// Bounded ring buffer for stderr tails. CLI providers can produce 100s of MB
+// of stderr; we only want the last few KB for diagnostics. Returns a string
+// guaranteed to be ≤ `limit` bytes, with a `[truncated …]` marker if anything
+// was dropped.
+export function createStderrTail({ limit = 8 * 1024 } = {}) {
+  let buffer = "";
+  let dropped = 0;
+  return {
+    push(chunk) {
+      const text = typeof chunk === "string" ? chunk : chunk?.toString?.() || "";
+      if (!text) return;
+      if (text.length >= limit) {
+        dropped += buffer.length + (text.length - limit);
+        buffer = text.slice(text.length - limit);
+        return;
+      }
+      const combined = buffer + text;
+      if (combined.length <= limit) {
+        buffer = combined;
+        return;
+      }
+      const overflow = combined.length - limit;
+      dropped += Math.min(buffer.length, overflow);
+      buffer = combined.slice(overflow);
+    },
+    toString() {
+      if (!dropped) return buffer;
+      return `[truncated ${dropped} earlier bytes]\n${buffer}`;
+    },
+    get bytesDropped() {
+      return dropped;
+    },
+  };
+}