@gleapai/kai-bridge 0.2.0

package/runner/lib/contract.mjs

@@ -0,0 +1,1122 @@
+// Shared runner contract for the in-sandbox agent drivers.
+//
+// Every runner (`opencode-runner.mjs`, `claude-runner.mjs`,
+// `codex-runner.mjs`) parses the SAME argv flag set, emits the SAME
+// ParsedAgentOutput JSONL on stdout (one JSON object per line), and
+// uses the SAME stderr trace/heartbeat conventions. This module is
+// the single source of truth for those mechanics so the engines stay
+// interchangeable behind `AgentRunner` on the host.
+//
+// Hard rules every runner must follow:
+//   - stdout carries ONLY contract JSONL. The host pipeline's idle
+//     watchdog resets exclusively on stdout data; during long silent
+//     model stretches a runner MUST keep stdout alive (see
+//     `startIdleKeepalive` / throttled `{type:"keepalive"}` emits).
+//   - stderr is diagnostics only (`[<prefix>-trace]` lines). It never
+//     resets the watchdog.
+//   - The final event of a successful turn is `{type:"result", ...}`
+//     carrying sessionId + usage; the process then exits 0.
+//
+// Zero npm dependencies — Node stdlib only.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync, writeSync } from "node:fs";
+import { basename, join } from "node:path";
+
+// ── Argv parsing (no minimist; keep zero deps inside the sandbox) ─────
+export function parseArgv(rawArgs) {
+  const out = {};
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const a = rawArgs[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const next = rawArgs[i + 1];
+    if (next == null || next.startsWith("--")) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+export function decodeB64(value) {
+  if (value == null || value === true) return "";
+  return Buffer.from(String(value), "base64").toString("utf8");
+}
+
+export function decodeB64Json(value, fallback) {
+  if (value == null || value === true) return fallback;
+  try {
+    return JSON.parse(decodeB64(value));
+  } catch {
+    return fallback;
+  }
+}
+
+// ── Kai agent names ───────────────────────────────────────────────────
+// Plan mode runs `kai-planner` (read-only strategic planner); build
+// mode runs `kai` (orchestrator / coder). Legacy short aliases
+// (`plan` / `build` / `prometheus` / `sisyphus` / `kai-builder` / the
+// old long descriptive names) resolve forward so a session paused on
+// an older template resumes cleanly on a newer one.
+export const KAI_PLANNER_AGENT_NAME = "kai-planner";
+export const KAI_BUILDER_AGENT_NAME = "kai";
+export const KAI_RESOLUTION_ANALYST_AGENT_NAME = "kai-resolution-analyst";
+
+export function normalizeAgentName(raw) {
+  const value = typeof raw === "string" ? raw : "";
+  const normalised = value.toLowerCase();
+  if (
+    normalised === "plan" ||
+    normalised === "kai-planner" ||
+    normalised === "prometheus" ||
+    normalised === "prometheus - plan builder"
+  )
+    return KAI_PLANNER_AGENT_NAME;
+  if (
+    normalised === "build" ||
+    normalised === "kai" ||
+    normalised === "kai-builder" ||
+    normalised === "sisyphus" ||
+    normalised === "sisyphus - ultraworker"
+  )
+    return KAI_BUILDER_AGENT_NAME;
+  return value || KAI_BUILDER_AGENT_NAME;
+}
+
+export function isPlanModeAgent(agentName) {
+  // The resolution analyst used to run here (native plan mode = read-only).
+  // It now has FULL tool access (it may act, not just recommend), so it
+  // runs as an artifact writer (dontAsk) instead — see
+  // ARTIFACT_WRITER_AGENT_NAMES below. Plan mode would route every
+  // write/mutation tool to a canUseTool approver that doesn't exist in a
+  // headless run, so under plan mode it could never call mutation tools.
+  return agentName === KAI_PLANNER_AGENT_NAME;
+}
+
+// Artifact-writer agents produce ONLY `.kai/` outputs at the
+// workspace root (findings dossiers, answer.md, research.md) — never
+// repository edits, never a PR. Each engine scopes their writes as
+// tightly as it can natively (claude: dontAsk + `Write(.kai/**)`
+// allow rules; codex: workspaceWrite can't subtract cwd, so prompt
+// discipline); `revertRepoMutations` below is the engine-agnostic
+// backstop that guarantees the repo clones stay pristine either way.
+export const ARTIFACT_WRITER_AGENT_NAMES = [
+  "kai-documentarian",
+  "kai-asker",
+  "kai-researcher",
+  // Full tool access (incl. non-destructive mutations) + writes its
+  // report to `.kai/resolution-analysis.md`. dontAsk hard-denies the
+  // destructive verbs (server-side guard) and anything not allow-listed,
+  // with no permission prompt to hang the headless run.
+  KAI_RESOLUTION_ANALYST_AGENT_NAME,
+];
+
+export function isArtifactWriterAgent(agentName) {
+  return ARTIFACT_WRITER_AGENT_NAMES.includes(agentName);
+}
+
+function findWorkspaceRepos(workDir) {
+  const repos = [];
+  if (existsSync(join(workDir, ".git"))) {
+    repos.push({ name: basename(workDir) || workDir, path: workDir });
+    return repos;
+  }
+
+  let entries = [];
+  try {
+    entries = readdirSync(workDir);
+  } catch {
+    return repos;
+  }
+  for (const entry of entries) {
+    const repoDir = join(workDir, entry);
+    try {
+      if (!statSync(repoDir).isDirectory()) continue;
+      if (!existsSync(join(repoDir, ".git"))) continue;
+    } catch {
+      continue;
+    }
+    repos.push({ name: entry, path: repoDir });
+  }
+  return repos;
+}
+
+function parseIgnoredPaths(output) {
+  return String(output || "")
+    .split("\0")
+    .filter((entry) => entry.startsWith("!! "))
+    .map((entry) => entry.slice(3))
+    .filter(Boolean);
+}
+
+function readIgnoredPaths(repoDir) {
+  const result = spawnSync(
+    "git",
+    [
+      "-C",
+      repoDir,
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--ignored=matching",
+      "--untracked-files=normal",
+    ],
+    { encoding: "utf8", timeout: 30_000 },
+  );
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message || result.stderr?.trim() || `exit ${result.status}`;
+    throw new Error(`git status --ignored failed for ${repoDir}: ${detail}`);
+  }
+  return parseIgnoredPaths(result.stdout);
+}
+
+function runGitOrThrow(repoDir, args, timeout = 60_000) {
+  const result = spawnSync("git", ["-C", repoDir, ...args], {
+    encoding: "utf8",
+    timeout,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message || result.stderr?.trim() || `exit ${result.status}`;
+    throw new Error(`git ${args.join(" ")} failed for ${repoDir}: ${detail}`);
+  }
+  return result.stdout || "";
+}
+
+const PRESERVED_ARTIFACT_PATHS = [".kai", ".codex-kai", ".opencode"];
+
+function isPreservedArtifactPath(path) {
+  const normalized = String(path || "").replace(/\/$/, "");
+  return PRESERVED_ARTIFACT_PATHS.some(
+    (prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`),
+  );
+}
+
+/**
+ * Snapshot repository HEADs before an artifact writer starts. A plain
+ * `git status` cleanup cannot see an agent-created commit, so without this
+ * baseline a `git add && git commit` shell command could make a mutation
+ * look clean and survive the safety net.
+ */
+export function captureRepoBaselines(workDir) {
+  return findWorkspaceRepos(workDir).flatMap((repo) => {
+    const head = spawnSync("git", ["-C", repo.path, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    if (head.status !== 0 || !head.stdout?.trim()) return [];
+    const branch = spawnSync(
+      "git",
+      ["-C", repo.path, "symbolic-ref", "--quiet", "--short", "HEAD"],
+      { encoding: "utf8", timeout: 30_000 },
+    );
+    return [
+      {
+        ...repo,
+        head: head.stdout.trim(),
+        branch: branch.status === 0 ? branch.stdout.trim() || null : null,
+        // Record ignored roots too. `git clean -fd` intentionally skips them,
+        // so without a baseline an artifact writer could leave a newly created
+        // node_modules/ or build cache behind while status looks clean. Git's
+        // `--ignored=matching` reports the top-level matching entry; contents
+        // of an already-present ignored directory are preserved as local cache
+        // state and are not content-diffed or copied/restored here.
+        ignoredPaths: readIgnoredPaths(repo.path),
+      },
+    ];
+  });
+}
+
+/**
+ * Revert any mutation inside the git repositories under `workDir`
+ * (tracked changes restored, untracked files removed — `.kai/`
+ * subtrees excepted). The artifact agents read the repos and write
+ * `.kai/` at the WORKSPACE root, which sits outside every repo clone,
+ * so a clean revert of the clones never touches their output.
+ *
+ * Why this exists even with engine-side permission scoping: claude's
+ * read-only Bash allowlist is prefix-matched, so an allowed verb with
+ * a shell redirection (`cat x > y`) can still write; codex's
+ * workspace-write sandbox always keeps the whole cwd writable
+ * (writableRoots is additive-only — verified against codex-rs
+ * source). This backstop makes stray writes non-durable regardless of
+ * which engine ran the turn. Mirrors the opencode runner's plan-mode
+ * safety net.
+ *
+ * Returns the list of repos that had to be reverted (empty = clean).
+ */
+export function revertRepoMutations(workDir, baselines = null) {
+  const reverted = [];
+  // The coder pipeline keeps artifact writers at the workspace root, with
+  // repository clones as children. Still handle a repository passed as
+  // workDir directly: older warm sandboxes and standalone runner invocations
+  // may use that layout. Prefer the pre-turn baseline when supplied so a
+  // committed mutation (which has a clean status) is still discoverable.
+  const repos = Array.isArray(baselines) && baselines.length > 0
+    ? baselines
+    : findWorkspaceRepos(workDir);
+
+  for (const repo of repos) {
+    const repoDir = repo.path;
+    const dirty = runGitOrThrow(repoDir, ["status", "--porcelain"], 30_000).trim();
+    const currentHead = spawnSync(
+      "git",
+      ["-C", repoDir, "rev-parse", "HEAD"],
+      { encoding: "utf8", timeout: 30_000 },
+    );
+    if (typeof repo.head === "string" && (currentHead.error || currentHead.status !== 0)) {
+      const detail =
+        currentHead.error?.message || currentHead.stderr?.trim() || `exit ${currentHead.status}`;
+      throw new Error(`git rev-parse HEAD failed for ${repoDir}: ${detail}`);
+    }
+    const headChanged =
+      typeof repo.head === "string" &&
+      currentHead.status === 0 &&
+      currentHead.stdout.trim() !== repo.head;
+    const ignoredBaseline = Array.isArray(repo.ignoredPaths)
+      ? new Set(repo.ignoredPaths)
+      : null;
+    const newIgnoredPaths = ignoredBaseline
+      ? readIgnoredPaths(repoDir).filter(
+          (path) => !ignoredBaseline.has(path) && !isPreservedArtifactPath(path),
+        )
+      : [];
+    if (!dirty && !headChanged && newIgnoredPaths.length === 0) continue;
+    traceLog("repo.revert", {
+      repo: repo.name,
+      files: [
+        ...dirty.split("\n").filter(Boolean),
+        ...newIgnoredPaths.map((path) => `!! ${path}`),
+      ].slice(0, 10),
+      headChanged,
+    });
+    if (typeof repo.head === "string") {
+      // Restore the original checkout as well as its commit. This covers an
+      // agent switching/renaming branches before committing. The fallback
+      // recreates a deleted original branch at the captured commit.
+      if (repo.branch) {
+        try {
+          runGitOrThrow(repoDir, ["checkout", "-f", repo.branch]);
+        } catch {
+          runGitOrThrow(repoDir, ["checkout", "-B", repo.branch, repo.head]);
+        }
+      } else {
+        runGitOrThrow(repoDir, ["checkout", "--detach", "-f", repo.head]);
+      }
+      runGitOrThrow(repoDir, ["reset", "--hard", repo.head]);
+    }
+    // Restore tracked files, then sweep untracked ones — keeping any
+    // repo-nested `.kai/` content a persona may legitimately have
+    // produced.
+    runGitOrThrow(repoDir, ["checkout", "--", "."]);
+    runGitOrThrow(repoDir, ["clean", "-fd", "-e", ".kai"]);
+    for (const path of newIgnoredPaths) {
+      runGitOrThrow(repoDir, ["clean", "-fdX", "--", path]);
+    }
+
+    if (ignoredBaseline) {
+      const residualIgnored = readIgnoredPaths(repoDir).filter(
+        (path) => !ignoredBaseline.has(path) && !isPreservedArtifactPath(path),
+      );
+      if (residualIgnored.length > 0) {
+        throw new Error(
+          `artifact cleanup left ignored paths in ${repoDir}: ${residualIgnored.join(", ")}`,
+        );
+      }
+    }
+    reverted.push(repo.name);
+  }
+  return reverted;
+}
+
+// Multi-modal attachments — only image/* and application/pdf survive;
+// anything else is dropped so prompt bodies stay valid on every engine.
+const SUPPORTED_FILE_PART_MIME_PREFIXES = ["image/"];
+const SUPPORTED_FILE_PART_MIMES = new Set(["application/pdf"]);
+
+// LEGACY: steps are no longer enforced as a turn limit — budget
+// (--max-budget-usd) is the sole cap (budget-only decision, 2026-06-18).
+// Retained only so `--max-steps` parsing stays backward-compatible
+// (Runner Contract v1); runners parse the value but ignore it for
+// enforcement. Safe to remove once no caller passes --max-steps.
+export const DEFAULT_STEP_CAP = 50;
+
+/**
+ * Decode the full runner argv contract into one options object. All
+ * flags are optional except `--task-b64`; callers fail fast on an
+ * empty `task` themselves (the error message differs per runner).
+ *
+ *   --agent <name>                       kai | kai-planner | kai-documentarian | …
+ *   --model <provider/modelID>           canonical registry id
+ *   --engine-model <slug>                engine-native model slug (claude/codex wire form)
+ *   --subagent-model <provider/modelID>  cheaper sibling for explorer subagents
+ *   --effort <tier>                      low|medium|high|extra_high|max
+ *   --session-id <id>                    resume an existing engine session/thread
+ *   --max-budget-usd <number>            abort when accumulated cost exceeds
+ *   --max-steps <number>                 LEGACY/no-op — steps no longer abort a
+ *                                        turn; budget (--max-budget-usd) is the
+ *                                        sole limit. Still parsed for compat.
+ *   --task-b64 <base64>                  REQUIRED — the user prompt
+ *   --feedback-b64 <base64>              wrapped follow-up prompt for resumes
+ *   --answers-b64 <base64-json>          string[][] question replies
+ *   --attachments-b64 <base64-json>      [{ name, url, type }]
+ *   --system-prompt-b64 <base64>         project-level system-prompt addendum
+ *   --mcp-config-b64 <base64-json>       [{ id, name, transport, command?, args?, env?, url?, headers?, disabledTools? }]
+ *   --model-pricing-b64 <base64-json>    { "<canonical model id>": { input, cachedInput, cacheWriteInput, output } }
+ *                                        USD per 1M tokens — lets runners price
+ *                                        usage for budget enforcement + costUsd
+ *                                        when the engine reports tokens only.
+ *   --provider-orders-b64 <base64-json>  { "<engine slug>": ["provider-slug", …] }
+ *                                        OpenRouter provider pins — the runner
+ *                                        injects provider.order into the body.
+ *   --work-dir <path>                    working directory for the agent
+ */
+export function parseRunnerArgs(rawArgs) {
+  const argv = parseArgv(rawArgs);
+
+  const agent = normalizeAgentName(argv.agent);
+
+  const maxSteps = (() => {
+    const raw = argv["max-steps"];
+    if (raw == null || raw === true) return DEFAULT_STEP_CAP;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_STEP_CAP;
+  })();
+
+  const maxBudgetUsd =
+    argv["max-budget-usd"] != null && argv["max-budget-usd"] !== true
+      ? Number(argv["max-budget-usd"])
+      : undefined;
+
+  const questionAnswers = (() => {
+    const parsed = decodeB64Json(argv["answers-b64"], null);
+    if (!Array.isArray(parsed)) return null;
+    return parsed.map((row) => (Array.isArray(row) ? row.map(String) : []));
+  })();
+
+  const attachments = (() => {
+    const parsed = decodeB64Json(argv["attachments-b64"], []);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((a) => {
+      if (!a || typeof a !== "object") return false;
+      const url = typeof a.url === "string" ? a.url : "";
+      const type = typeof a.type === "string" ? a.type : "";
+      if (!url || !type) return false;
+      if (SUPPORTED_FILE_PART_MIMES.has(type)) return true;
+      return SUPPORTED_FILE_PART_MIME_PREFIXES.some((p) => type.startsWith(p));
+    });
+  })();
+
+  const mcpServers = (() => {
+    const parsed = decodeB64Json(argv["mcp-config-b64"], []);
+    return Array.isArray(parsed) ? parsed : [];
+  })();
+
+  const modelPricing = (() => {
+    const parsed = decodeB64Json(argv["model-pricing-b64"], null);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return {};
+    const out = {};
+    for (const [model, rates] of Object.entries(parsed)) {
+      if (!rates || typeof rates !== "object") continue;
+      const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+      out[model] = {
+        input: num(rates.input),
+        output: num(rates.output),
+        // Cache rates stay undefined when the registry doesn't define
+        // them — the tracker then falls back to the input rate. An
+        // EXPLICIT 0 means "free" and must survive the round-trip.
+        ...(rates.cachedInput != null ? { cachedInput: num(rates.cachedInput) } : {}),
+        ...(rates.cacheWriteInput != null
+          ? { cacheWriteInput: num(rates.cacheWriteInput) }
+          : {}),
+        // Long-context dual-tier fields — drive per-step tier pricing
+        // and the tier-split modelBreakdown in createUsageTracker.
+        ...(rates.longContextThreshold != null
+          ? { longContextThreshold: num(rates.longContextThreshold) }
+          : {}),
+        ...(rates.longInputMultiplier != null
+          ? { longInputMultiplier: num(rates.longInputMultiplier) }
+          : {}),
+        ...(rates.longOutputMultiplier != null
+          ? { longOutputMultiplier: num(rates.longOutputMultiplier) }
+          : {}),
+      };
+    }
+    return out;
+  })();
+
+  // Per-model OpenRouter provider pins, keyed by ENGINE slug. The runner
+  // injects `provider:{order,allow_fallbacks:true}` into the request body for
+  // models present here; absent models keep OpenRouter's default routing.
+  const providerOrders = (() => {
+    const parsed = decodeB64Json(argv["provider-orders-b64"], null);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out = {};
+    for (const [model, order] of Object.entries(parsed)) {
+      if (!Array.isArray(order)) continue;
+      const slugs = order.filter((p) => typeof p === "string" && p.length > 0);
+      if (slugs.length > 0) out[model] = slugs;
+    }
+    return out;
+  })();
+
+  // Positive-integer token ceilings. Claude Code recognises models by ID
+  // PATTERN; a gateway slug like `z-ai/glm-5.3` matches nothing, so it falls
+  // back to a 200K assumed context window (it compacts there) and a 32K
+  // output cap. The Server sends the registry's real numbers so a 1M-context
+  // model stops behaving like a 200K one.
+  const positiveInt = (raw) => {
+    if (raw == null || raw === true) return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+  };
+
+  return {
+    argv,
+    agent,
+    isPlanMode: isPlanModeAgent(agent),
+    model: argv.model ? String(argv.model) : undefined,
+    engineModel: argv["engine-model"] ? String(argv["engine-model"]) : undefined,
+    subagentModel: argv["subagent-model"]
+      ? String(argv["subagent-model"])
+      : undefined,
+    effort: argv.effort ? String(argv.effort) : undefined,
+    sessionId: argv["session-id"] ? String(argv["session-id"]) : undefined,
+    maxBudgetUsd,
+    maxSteps,
+    task: decodeB64(argv["task-b64"]),
+    feedback: decodeB64(argv["feedback-b64"]),
+    questionAnswers,
+    attachments,
+    customSystemPrompt: decodeB64(argv["system-prompt-b64"]),
+    mcpServers,
+    modelPricing,
+    providerOrders,
+    maxContextTokens: positiveInt(argv["max-context-tokens"]),
+    maxOutputTokens: positiveInt(argv["max-output-tokens"]),
+    backgroundModel: argv["background-model"]
+      ? String(argv["background-model"])
+      : undefined,
+    workDir: argv["work-dir"] ? String(argv["work-dir"]) : process.cwd(),
+  };
+}
+
+// ── Stdout emission ───────────────────────────────────────────────────
+// `process.stdout.write` is async on pipes — Node buffers writes and
+// flushes opportunistically, so a long-running agent can produce
+// stdout the e2b parent only sees in big bursts. `writeSync` to fd=1
+// bypasses the stream's buffer and pushes each JSONL line straight to
+// the OS, so events reach the pipeline as the agent produces them.
+let lastEmitAt = Date.now();
+
+export function emit(obj) {
+  try {
+    writeSync(1, JSON.stringify(obj) + "\n");
+    lastEmitAt = Date.now();
+  } catch {
+    // Parent pipe closed — nothing useful to do.
+    process.exit(1);
+  }
+}
+
+// Same path as `emit`, but never exits — for fail-fast call sites that
+// are already on their way out and must not recurse into exit logic.
+export function emitSync(obj) {
+  try {
+    writeSync(1, JSON.stringify(obj) + "\n");
+    lastEmitAt = Date.now();
+  } catch {
+    /* parent pipe closed; ignore */
+  }
+}
+
+export function getLastEmitAt() {
+  return lastEmitAt;
+}
+
+// ── Liveness keepalive (host idle-watchdog) ───────────────────────────
+// The host's idle-kill watchdog (pipeline.ts) only resets on stdout
+// data and kills after 5 min of silence. A long reasoning step
+// produces no stdout and looks identical to a hang. Runners that
+// stream engine events through a child process should call
+// `startIdleKeepalive()` once: every `intervalMs` with no other emit,
+// it writes a tiny `{type:"keepalive"}` line (the host parser drops
+// it — it never reaches the UI). Runners that can hook token deltas
+// directly (OpenCode) keep their own delta-throttled variant instead
+// so a genuinely hung engine still trips the watchdog.
+export const KEEPALIVE_THROTTLE_MS = 20_000;
+
+export function startIdleKeepalive(intervalMs = KEEPALIVE_THROTTLE_MS) {
+  const timer = setInterval(() => {
+    if (Date.now() - lastEmitAt < intervalMs) return;
+    emitSync({ type: "keepalive" });
+  }, Math.max(1000, Math.floor(intervalMs / 2)));
+  timer.unref();
+  return () => clearInterval(timer);
+}
+
+// ── Stderr diagnostics ────────────────────────────────────────────────
+// `traceLog` is the always-on event trace: every line lands in the
+// analyzer host's stderr (forwarded to the dev terminal verbatim).
+// `debugLog` is gated on KAI_RUNNER_DEBUG / OPENCODE_RUNNER_DEBUG for
+// verbose payload dumps. Keep trace entries to one short line; the
+// payload is clamped hard so an oversized message never floods the
+// parent terminal.
+let tracePrefix = "runner";
+let lastTraceAt = Date.now();
+
+export function setTracePrefix(prefix) {
+  tracePrefix = String(prefix || "runner");
+}
+
+export function debugLog(prefix, obj) {
+  if (!process.env.KAI_RUNNER_DEBUG && !process.env.OPENCODE_RUNNER_DEBUG)
+    return;
+  try {
+    process.stderr.write(
+      `[${tracePrefix}-runner] ${prefix} ${JSON.stringify(obj).slice(0, 800)}\n`,
+    );
+  } catch {
+    /* ignore */
+  }
+}
+
+export function traceLog(prefix, obj) {
+  try {
+    const ts = new Date().toISOString();
+    const body = obj == null ? "" : ` ${JSON.stringify(obj).slice(0, 280)}`;
+    process.stderr.write(`[${tracePrefix}-trace] ${ts} ${prefix}${body}\n`);
+    lastTraceAt = Date.now();
+  } catch {
+    /* ignore */
+  }
+}
+
+export function getLastTraceAt() {
+  return lastTraceAt;
+}
+
+// Heartbeat — every 30s, if no event has been traced in the last 15s,
+// dump a short status line so a wedged turn is obvious in the log
+// instead of looking like a frozen tab. `getInFlight` returns labels
+// for tools still running so the operator can see WHICH call the
+// agent is waiting on.
+export const HEARTBEAT_MS = 30_000;
+export const HEARTBEAT_QUIET_THRESHOLD_MS = 15_000;
+
+export function startHeartbeat(getInFlight) {
+  const timer = setInterval(() => {
+    const idleMs = Date.now() - lastTraceAt;
+    if (idleMs < HEARTBEAT_QUIET_THRESHOLD_MS) return;
+    let inFlight = [];
+    try {
+      inFlight = getInFlight ? getInFlight() : [];
+    } catch {
+      /* state may not be initialised yet */
+    }
+    try {
+      process.stderr.write(
+        `[${tracePrefix}-trace] ${new Date().toISOString()} heartbeat idle=${Math.round(idleMs / 1000)}s in-flight=[${inFlight.join(", ")}]\n`,
+      );
+    } catch {
+      /* ignore */
+    }
+  }, HEARTBEAT_MS);
+  timer.unref();
+  return () => clearInterval(timer);
+}
+
+// ── Provider/model parsing ────────────────────────────────────────────
+// Accepts the `provider/modelID` slug form coming from the analyzer.
+// Multi-segment modelIDs (e.g. `vendor/model-name` for OpenRouter)
+// join everything after the first `/` back into the modelID.
+export function parseModelSlug(slug) {
+  const parts = String(slug).split("/");
+  if (parts.length < 2) {
+    return { providerID: "anthropic", modelID: slug };
+  }
+  return { providerID: parts[0], modelID: parts.slice(1).join("/") };
+}
+
+// ── Tool input → one-line summary ─────────────────────────────────────
+export const TOOL_SUMMARY_KEY = {
+  read: ["filePath", "file_path", "path"],
+  write: ["filePath", "file_path", "path"],
+  edit: ["filePath", "file_path", "path"],
+  multiedit: ["filePath", "file_path", "path"],
+  bash: ["command"],
+  glob: ["pattern"],
+  grep: ["pattern"],
+  search: ["pattern", "query"],
+  webfetch: ["url"],
+  fetch: ["url"],
+  websearch: ["query"],
+  task: ["description", "prompt"],
+  agent: ["description", "prompt"],
+};
+
+export function describeBashCommand(command) {
+  const cmd = String(command || "")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (!cmd) return "";
+  const lower = cmd.toLowerCase();
+  const first = cmd.split(/\s+/)[0] || "";
+  if (lower === "git status" || lower.startsWith("git status "))
+    return "Show working tree status";
+  if (lower === "git diff" || lower.startsWith("git diff "))
+    return "Show code differences";
+  if (lower === "git log" || lower.startsWith("git log "))
+    return "Show recent commits";
+  if (lower === "git show" || lower.startsWith("git show "))
+    return "Show git object details";
+  if (lower === "git branch --show-current") return "Show current branch";
+  if (lower.startsWith("git add ")) return "Stage selected files";
+  if (lower.startsWith("git commit ")) return "Create git commit";
+  if (lower.startsWith("git push ")) return "Push git branch";
+  if (lower === "npm install" || lower.startsWith("npm install "))
+    return "Install package dependencies";
+  if (lower === "npm test" || lower.startsWith("npm test "))
+    return "Run package tests";
+  if (lower === "npm run build" || lower.startsWith("npm run build "))
+    return "Build the project";
+  const npmRun = cmd.match(/^npm run ([^\s]+)/i);
+  if (npmRun) return `Run npm script ${npmRun[1]}`;
+  if (lower === "pnpm install" || lower.startsWith("pnpm install "))
+    return "Install package dependencies";
+  if (lower === "pnpm test" || lower.startsWith("pnpm test "))
+    return "Run package tests";
+  const pnpmRun = cmd.match(/^pnpm (?:run )?([^\s]+)/i);
+  if (
+    pnpmRun &&
+    !["install", "add", "remove"].includes(pnpmRun[1].toLowerCase())
+  ) {
+    return `Run pnpm script ${pnpmRun[1]}`;
+  }
+  if (lower === "yarn install" || lower.startsWith("yarn install "))
+    return "Install package dependencies";
+  const yarnRun = cmd.match(/^yarn (?:run )?([^\s]+)/i);
+  if (
+    yarnRun &&
+    !["install", "add", "remove"].includes(yarnRun[1].toLowerCase())
+  ) {
+    return `Run yarn script ${yarnRun[1]}`;
+  }
+  if (lower.startsWith("node --check ")) return "Check JavaScript syntax";
+  if (lower === "tsc" || lower.startsWith("tsc "))
+    return "Run TypeScript compiler";
+  if (lower.startsWith("npx tsc") || lower.startsWith("pnpm tsc"))
+    return "Run TypeScript compiler";
+  if (first === "rg") return "Search files with ripgrep";
+  if (first === "grep") return "Search file contents";
+  if (first === "find") return "Find files";
+  if (first === "ls") return "List files";
+  if (first === "cat") return "Read file contents";
+  if (first === "head") return "Read file beginning";
+  if (first === "tail") return "Read file ending";
+  if (first === "curl") return "Fetch URL";
+  if (first === "gh") return "Run GitHub CLI command";
+  const truncated = cmd.length > 96 ? cmd.slice(0, 93).trimEnd() + "…" : cmd;
+  return `Run shell command: ${truncated}`;
+}
+
+export function summarizeTool(name, input) {
+  if (!input || typeof input !== "object") return "";
+  if (
+    String(name || "").toLowerCase() === "bash" &&
+    typeof input.command === "string"
+  ) {
+    return describeBashCommand(input.command);
+  }
+  const keys = TOOL_SUMMARY_KEY[String(name || "").toLowerCase()] || [];
+  for (const k of keys) {
+    const v = input[k];
+    if (typeof v === "string" && v.length > 0) {
+      return v.length > 160 ? v.slice(0, 157) + "…" : v;
+    }
+  }
+  return "";
+}
+
+// Normalise raw tool names so engine variations (`_grep`,
+// `webfetch_v2`, `filesystem.read`, `apply_patch`, etc.) still map to
+// the canonical title-cased name the frontend's TOOL_VERBS /
+// beautifyToolName tables expect. Project MCP tools
+// (`mcp__server__tool`) are passed through untouched — the frontend
+// has its own beautifier for those.
+export function canonicalToolName(name) {
+  const raw = String(name || "");
+  if (/exit[_-]?plan[_-]?mode$/i.test(raw)) return "ExitPlanMode";
+  // The runner-injected `kai_todos` bridge (todo-mcp.mjs) IS TodoWrite:
+  // fold every harness's spelling (mcp__kai_todos__todo_write, Codex's
+  // server-scoped variant, …) onto the canonical name so the mapper's
+  // TodoWrite branch turns the calls into dashboard `todos` events.
+  if (/(^|__|\.)todo_write$/.test(raw)) return "TodoWrite";
+  if (raw.startsWith("mcp__")) return raw;
+  let lower = raw.toLowerCase().replace(/^_+/, "");
+  lower = lower.replace(/_v\d+$/, "");
+  if (lower.startsWith("filesystem."))
+    lower = lower.slice("filesystem.".length);
+  const aliases = {
+    read: "Read",
+    write: "Write",
+    edit: "Edit",
+    multiedit: "MultiEdit",
+    bash: "Bash",
+    glob: "Glob",
+    grep: "Grep",
+    search: "Grep",
+    list: "Glob",
+    ls: "Glob",
+    webfetch: "WebFetch",
+    fetch: "WebFetch",
+    websearch: "WebSearch",
+    task: "Task",
+    agent: "Task",
+    todowrite: "TodoWrite",
+    todos: "TodoWrite",
+    exitplanmode: "ExitPlanMode",
+    patch: "Edit",
+    apply_patch: "Edit",
+    askuserquestion: "Question",
+    question: "Question",
+  };
+  if (aliases[lower]) return aliases[lower];
+  debugLog("canonical.miss", { raw, lower });
+  return raw;
+}
+
+// Map raw engine tool status strings to a small canonical set
+// (`running | completed | error | pending`). Different engines use
+// different verbs; collapse them so emit logic doesn't have to.
+export function normalizeToolStatus(raw) {
+  const s = String(raw || "").toLowerCase();
+  if (s === "completed" || s === "complete" || s === "done") return "completed";
+  if (s === "error" || s === "failed") return "error";
+  if (s === "running" || s === "in_progress" || s === "inprogress")
+    return "running";
+  return "pending";
+}
+
+export function truncateString(value, max) {
+  if (typeof value !== "string") return value;
+  return value.length > max ? value.slice(0, max - 1).trimEnd() + "…" : value;
+}
+
+export function sanitizeToolValue(value, maxStringLength = 4000) {
+  if (typeof value === "string") return truncateString(value, maxStringLength);
+  if (Array.isArray(value))
+    return value
+      .slice(0, 50)
+      .map((item) => sanitizeToolValue(item, maxStringLength));
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, nested] of Object.entries(value)) {
+    out[key] = sanitizeToolValue(nested, maxStringLength);
+  }
+  return out;
+}
+
+// ── Tool-schema compatibility (provider quirks) ───────────────────────
+// Some gateways validate the JSON Schema of EVERY tool in a request and
+// reject the whole request when one uses a regex construct their engine
+// lacks. xAI is the known case: probed against grok-4.6 on 2026-08-14,
+// its own error strings name exactly three unsupported constructs —
+//     Unicode property escapes   \p{...}   \P{...}
+//     backreferences             \1        \k<name>
+//     word boundaries            \b        \B
+// while lookaround, named groups, non-capturing groups and POSIX
+// classes are all accepted. So this is a narrow list, not a blanket
+// "no regex".
+//
+// These are legal ECMA-262 patterns that Anthropic accepts, so they
+// reach the wire untouched from third-party MCP servers we don't
+// control. Deliberately loose matching: a false positive costs one
+// dropped refinement, a miss costs the whole session.
+export const UNSUPPORTED_SCHEMA_PATTERN = /\\[pP]\{|\\k<|\\[1-9]|\\[bB]/;
+
+function stripUnsupportedPatterns(node, dropped) {
+  if (Array.isArray(node)) {
+    for (const child of node) stripUnsupportedPatterns(child, dropped);
+    return;
+  }
+  if (!node || typeof node !== "object") return;
+  // Only a string `pattern` is the JSON-Schema keyword; a property
+  // legitimately NAMED "pattern" holds a schema object and is skipped
+  // here, then visited by the recursion below.
+  if (
+    typeof node.pattern === "string" &&
+    UNSUPPORTED_SCHEMA_PATTERN.test(node.pattern)
+  ) {
+    dropped.push(node.pattern);
+    delete node.pattern;
+  }
+  for (const key of Object.keys(node)) {
+    stripUnsupportedPatterns(node[key], dropped);
+  }
+}
+
+/**
+ * Removes `pattern` keywords a provider's schema validator rejects from
+ * every tool in an Anthropic-shaped request body, MUTATING it in place.
+ * Walks nested `properties` / `items` / `$defs` / `anyOf` / `oneOf` /
+ * `allOf` alike. Returns the dropped patterns, or null when the body
+ * needed no change (so callers can skip re-serializing).
+ *
+ * Dropping is the correct repair, not rewriting: `pattern` is a
+ * validation refinement, so removing it only WIDENS what the schema
+ * accepts and can never turn a call the model would have made into an
+ * invalid one. Rewriting `\p{L}` → `[A-Za-z]` was rejected — it
+ * silently stops accepting the non-ASCII input the author allowed.
+ */
+export function stripUnsupportedToolPatterns(body) {
+  if (!Array.isArray(body?.tools)) return null;
+  const dropped = [];
+  for (const tool of body.tools) {
+    stripUnsupportedPatterns(tool?.input_schema, dropped);
+    stripUnsupportedPatterns(tool?.custom?.input_schema, dropped);
+  }
+  return dropped.length > 0 ? dropped : null;
+}
+
+// ── Usage accumulation + pricing ──────────────────────────────────────
+// Shared by the claude / codex runners (OpenCode keeps its own
+// accumulator — its cost events arrive pre-priced from the SDK).
+// Tracks per-model token usage, prices it from the host-forwarded
+// `modelPricing` map (USD per 1M tokens, registry rates), and builds
+// the `result` fields the host billing layer consumes. Model keys
+// MUST be canonical registry ids — callers normalize engine-reported
+// ids before recording.
+export function createUsageTracker(modelPricing = {}) {
+  // Buckets are keyed by (model, long-context tier) — one model can hold
+  // two buckets when the pricing carries a `longContextThreshold`, so the
+  // reported breakdown preserves per-tier attribution. Entries store the
+  // PLAIN model string; the composite key is internal only.
+  const perModel = new Map();
+  let providerCostUsd = 0;
+  // Running USD priced per RECORDED step (not recomputed from bucket
+  // sums): the long-context surcharge is per-request, so pricing summed
+  // buckets would tier-flip once the sum crosses the threshold even
+  // though no single request did.
+  let pricedUsd = 0;
+  // Last model request's context occupancy — a SNAPSHOT (overwritten on
+  // each note, last one wins), never a sum. Kept separate from record():
+  // seedFromBreakdown() and aggregate residuals also flow through
+  // record() and must not move the snapshot.
+  let lastContext = null;
+
+  const num = (v) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0);
+
+  const bucket = (model, longContext) => {
+    const name = String(model || "unknown");
+    const key = longContext ? `${name}long` : name;
+    let entry = perModel.get(key);
+    if (!entry) {
+      entry = {
+        model: name,
+        longContext,
+        inputTokens: 0,
+        cachedInputTokens: 0,
+        cacheWriteInputTokens: 0,
+        outputTokens: 0,
+        turns: 0,
+      };
+      perModel.set(key, entry);
+    }
+    return entry;
+  };
+
+  return {
+    /**
+     * Record one model step's usage. `cachedInputTokens` /
+     * `cacheWriteInputTokens` are subsets of the total input side —
+     * callers pass whatever the engine reports; `inputTokens` here is
+     * the NON-cached fresh input count (pass the engine's
+     * `input_tokens` for Anthropic, which already excludes cache
+     * reads/writes).
+     *
+     * `aggregate: true` marks a recording that is a TOTAL over many
+     * requests (CLI terminal envelopes, turn summaries) — the
+     * long-context tier is a per-request surcharge and cannot be
+     * inferred from a sum, so aggregates always land in (and price at)
+     * the base tier. Never over-charge from an aggregate.
+     *
+     * `longContext` (boolean) overrides the inference entirely — used
+     * when re-seeding buckets whose tier was already decided per step.
+     */
+    record(model, usage, { countTurn = true, aggregate = false, longContext: forcedTier } = {}) {
+      const fresh = num(usage.inputTokens);
+      const cached = num(usage.cachedInputTokens);
+      const cacheWrite = num(usage.cacheWriteInputTokens);
+      const output = num(usage.outputTokens);
+
+      const rates = modelPricing[String(model || "unknown")];
+      // Tier check uses the step's TOTAL input (fresh + cache buckets) —
+      // matches the Server's convention where `input` includes cache.
+      const totalInput = fresh + cached + cacheWrite;
+      const longContext =
+        forcedTier != null
+          ? Boolean(forcedTier)
+          : !aggregate &&
+            rates?.longContextThreshold != null &&
+            totalInput > rates.longContextThreshold;
+
+      if (rates) {
+        const inputMult = longContext ? (rates.longInputMultiplier ?? 1) : 1;
+        const outputMult = longContext ? (rates.longOutputMultiplier ?? 1) : 1;
+        pricedUsd +=
+          (fresh / 1_000_000) * rates.input * inputMult +
+          (cached / 1_000_000) * (rates.cachedInput ?? rates.input) * inputMult +
+          (cacheWrite / 1_000_000) * (rates.cacheWriteInput ?? rates.input) * inputMult +
+          (output / 1_000_000) * rates.output * outputMult;
+      }
+
+      const entry = bucket(model, longContext);
+      entry.inputTokens += fresh;
+      entry.cachedInputTokens += cached;
+      entry.cacheWriteInputTokens += cacheWrite;
+      entry.outputTokens += output;
+      if (countTurn) entry.turns += 1;
+    },
+    /**
+     * Re-seed from another tracker's `modelBreakdown()` rows, preserving
+     * each row's per-step tier attribution and turn counts. Used by the
+     * claude runner's terminal merge: live per-step buckets seed the
+     * final tracker, then only the envelope residual is recorded as an
+     * aggregate.
+     */
+    seedFromBreakdown(rows = []) {
+      for (const row of Array.isArray(rows) ? rows : []) {
+        if (!row || typeof row !== "object" || !row.model) continue;
+        const cached = num(row.cachedInputTokens);
+        const cacheWrite = num(row.cacheWriteInputTokens);
+        this.record(
+          row.model,
+          {
+            // Breakdown rows carry COMBINED input; record() wants fresh-only.
+            inputTokens: Math.max(0, num(row.inputTokens) - cached - cacheWrite),
+            cachedInputTokens: cached,
+            cacheWriteInputTokens: cacheWrite,
+            outputTokens: num(row.outputTokens),
+          },
+          { countTurn: false, longContext: row.longContext === true }
+        );
+        bucket(row.model, row.longContext === true).turns += num(row.turns);
+      }
+    },
+    /**
+     * Note the context occupancy of ONE model request: its full
+     * prompt-side token count (fresh input + cache reads + cache
+     * writes). Callers invoke this per request; the last call wins and
+     * feeds the dashboard's context-window fill indicator.
+     * `windowTokens` is the engine-reported context-window size when
+     * the engine exposes one (codex does; claude/opencode don't).
+     */
+    noteContextSnapshot(model, tokens, windowTokens) {
+      const value = num(tokens);
+      if (value <= 0) return;
+      const window = num(windowTokens);
+      lastContext = {
+        model: String(model || "unknown"),
+        tokens: value,
+        ...(window > 0 ? { windowTokens: window } : {}),
+      };
+    },
+    /** Last noted context snapshot ({model, tokens, windowTokens?}) or null. */
+    contextSnapshot() {
+      return lastContext;
+    },
+    /** Provider-reported authoritative USD (native Anthropic only). */
+    setProviderCostUsd(value) {
+      providerCostUsd = num(value);
+    },
+    /** USD priced per recorded step from the forwarded registry rates (per 1M tokens). */
+    pricedCostUsd() {
+      return pricedUsd;
+    },
+    /** Best-available USD for budget enforcement. */
+    effectiveCostUsd() {
+      const priced = this.pricedCostUsd();
+      return Math.max(providerCostUsd, priced);
+    },
+    totals() {
+      let inputTokens = 0;
+      let cachedInputTokens = 0;
+      let cacheWriteInputTokens = 0;
+      let outputTokens = 0;
+      for (const u of perModel.values()) {
+        inputTokens += u.inputTokens + u.cachedInputTokens + u.cacheWriteInputTokens;
+        cachedInputTokens += u.cachedInputTokens;
+        cacheWriteInputTokens += u.cacheWriteInputTokens;
+        outputTokens += u.outputTokens;
+      }
+      return { inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens };
+    },
+    modelBreakdown() {
+      const out = [];
+      for (const u of perModel.values()) {
+        out.push({
+          // Plain model id from the entry — the map key is composite for
+          // tier-split buckets and must never leak (the Server resolves
+          // rows via getModelCost(row.model)).
+          model: u.model,
+          inputTokens: u.inputTokens + u.cachedInputTokens + u.cacheWriteInputTokens,
+          ...(u.cachedInputTokens > 0
+            ? { cachedInputTokens: u.cachedInputTokens }
+            : {}),
+          ...(u.cacheWriteInputTokens > 0
+            ? { cacheWriteInputTokens: u.cacheWriteInputTokens }
+            : {}),
+          outputTokens: u.outputTokens,
+          turns: u.turns,
+          // Explicit tier attribution — BOTH values, always. The host
+          // treats a MISSING flag as "infer the tier from this row's
+          // token totals", and these rows are per-model TOTALS across a
+          // whole turn: a base-tier bucket that merely sums past the
+          // threshold would be re-inferred long and billed the 2×/1.5×
+          // surcharge (bit 90% of terra engine turns, 2026-07). The
+          // explicit false is what disarms that inference.
+          longContext: !!u.longContext,
+        });
+      }
+      return out;
+    },
+    /**
+     * Build the terminal `result` event. `costUsd` is the provider-
+     * reported USD when available, otherwise the priced total (omitted
+     * entirely when neither yields a positive number — the Server then
+     * bills from the token fields).
+     */
+    buildResultEvent({ message = "", sessionId } = {}) {
+      const totals = this.totals();
+      const breakdown = this.modelBreakdown();
+      const cost = this.effectiveCostUsd();
+      return {
+        type: "result",
+        message,
+        sessionId,
+        costUsd: cost > 0 ? cost : undefined,
+        inputTokens: totals.inputTokens || undefined,
+        cachedInputTokens: totals.cachedInputTokens || undefined,
+        cacheWriteInputTokens: totals.cacheWriteInputTokens || undefined,
+        outputTokens: totals.outputTokens || undefined,
+        ...(breakdown.length > 0 ? { modelBreakdown: breakdown } : {}),
+        // Last request's context occupancy — a snapshot, unlike the
+        // cumulative token fields above. Drives the context-window fill
+        // indicator; absent when no request was noted.
+        ...(lastContext
+          ? {
+              contextTokens: lastContext.tokens,
+              contextModelId: lastContext.model,
+              ...(lastContext.windowTokens
+                ? { contextWindowTokens: lastContext.windowTokens }
+                : {}),
+            }
+          : {}),
+      };
+    },
+  };
+}