faberun 0.26.2 → 0.27.0

package/src/harnesses/runner-transcript.mjs

@@ -0,0 +1,127 @@
+/**
+ * The adapter half of Faberun's own harness clients. `dsh` and `fx` are
+ * driven by a runner this repository ships (a JSON-RPC client per harness),
+ * and both runners write the same transcript: `<prefix>.started`,
+ * `<prefix>.tool`, `<prefix>.message`, then exactly one `<prefix>.completed`
+ * or `<prefix>.failed` carrying the session usage. Folding that transcript
+ * into an envelope is one job whatever harness sits behind the runner, so it
+ * lives here instead of in either adapter.
+ */
+
+import { canonicalUsage, extractJson, failed, isQuotaText, isVerdictCandidate, parseJsonLines } from "./protocol.mjs";
+
+/**
+ * @param {string} prefix the runner's event namespace, `dsh` or `fx`
+ * @param {string} stdout
+ * @param {number|null} exitCode
+ * @param {string|null} signal
+ * @param {import("./index.mjs").NormalizeOptions} [options]
+ * @returns {import("./index.mjs").ProviderEnvelope}
+ */
+export function normalizeRunnerTranscript(prefix, stdout, exitCode, signal, options = {}) {
+  if (signal) return failed("canceled", `provider ended after ${signal}`, "canceled");
+  let events;
+  try {
+    events = parseJsonLines(stdout, prefix);
+  } catch (error) {
+    return failed("invalid_protocol", error instanceof Error ? error.message : String(error));
+  }
+  const terminal = events.findLast((event) => event.type === `${prefix}.completed` || event.type === `${prefix}.failed`);
+  if (!terminal) {
+    const detail = options.stderr?.trim();
+    return failed(
+      "incomplete_stream",
+      `${prefix} emitted no terminal event${detail ? `: ${detail.slice(-512)}` : ""}${exitCode === null ? "" : ` (exit ${exitCode})`}`,
+    );
+  }
+  const usage = canonicalUsage(terminal.usage);
+  if (terminal.type === `${prefix}.completed`) {
+    const text = typeof terminal.result === "string" ? terminal.result : null;
+    const result = options.preferStructured ? extractJson(text) ?? text : text;
+    const verdicts = options.preferStructured
+      ? events.filter((event) => event.type === `${prefix}.message` && isVerdictCandidate(event.text)).length
+      : null;
+    return {
+      status: result?.trim() ? "done" : "no-op",
+      result,
+      continuationId: null,
+      usage,
+      costUsd: null,
+      error: null,
+      ...(verdicts === null ? {} : { judgeCandidates: verdicts }),
+    };
+  }
+  const error = terminal.error && typeof terminal.error === "object" ? /** @type {Record<string, unknown>} */ (terminal.error) : {};
+  const kind = typeof terminal.kind === "string" ? terminal.kind : "error";
+  const code = typeof error.code === "string" && error.code ? error.code : kind;
+  const message = typeof error.message === "string" && error.message ? error.message : code;
+  const resetAt = resetTimestamp(error.retryAfterMs);
+  return {
+    status: statusFor(kind, `${code} ${message}`),
+    result: null,
+    continuationId: null,
+    usage,
+    costUsd: null,
+    error: { code, message, ...(resetAt ? { resetAt } : {}) },
+    ...(resetAt ? { exhaustedUntil: resetAt } : {}),
+  };
+}
+
+/**
+ * Append the output schema the judge prompt refers to. Codex and Claude receive
+ * it through a native flag; neither runner-driven harness has one, so it
+ * travels in the prompt.
+ *
+ * @param {string} prompt
+ * @param {object|undefined} schema
+ * @returns {string}
+ */
+export function withSchema(prompt, schema) {
+  if (!schema) return prompt;
+  return `${prompt}\n\nOutput schema (the JSON object must validate against it):\n${JSON.stringify(schema)}`;
+}
+
+/**
+ * The environment overlay every runner turn spawns with. The Claude Code shell
+ * exports `GIT_CONFIG_COUNT` with the VALUE half of each `GIT_CONFIG_{KEY,VALUE}_<n>`
+ * pair but not the key half, so `git init` inside the worker fails with status
+ * 128; the overlay removes the whole family. `GIT_TERMINAL_PROMPT=0` takes over
+ * the prompting that family was for. A null value removes the ambient variable
+ * when the gate merges the overlay over the runner environment.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Record<string, string|null>}
+ */
+export function runnerEnvironmentOverlay(env) {
+  /** @type {Record<string, string|null>} */
+  const overlay = { GIT_TERMINAL_PROMPT: "0" };
+  for (const key of Object.keys(env)) {
+    if (key === "GIT_CONFIG_COUNT" || /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/u.test(key)) overlay[key] = null;
+  }
+  return overlay;
+}
+
+/**
+ * @param {string} kind
+ * @param {string} text
+ * @returns {"done"|"no-op"|"blocked"|"failed"|"exhausted"|"stalled"|"canceled"}
+ */
+function statusFor(kind, text) {
+  if (kind === "aborted") return "canceled";
+  if (kind === "blocked") return "blocked";
+  if (isQuotaText(text) || /insufficient balance/iu.test(text)) return "exhausted";
+  if (/permission|approval|sandbox/iu.test(text)) return "blocked";
+  return "failed";
+}
+
+/**
+ * Turn the harness's relative retry hint into the absolute instant the
+ * controller needs; without one it takes the failover edge instead of waiting.
+ *
+ * @param {unknown} retryAfterMs
+ * @returns {string|null}
+ */
+function resetTimestamp(retryAfterMs) {
+  if (typeof retryAfterMs !== "number" || !Number.isFinite(retryAfterMs) || retryAfterMs <= 0) return null;
+  return new Date(Date.now() + retryAfterMs).toISOString();
+}

package/src/harnesses/session-metrics.mjs

@@ -26,7 +26,29 @@ import { finite } from "../util.mjs";
  */
 
 /** The harnesses whose streams carry usage per provider request; the others meter turns and tool calls only. */
-const PER_REQUEST_USAGE = new Set(["claude", "dsh", "agy", "exec-jsonl", "replay"]);
+const PER_REQUEST_USAGE = new Set(["claude", "dsh", "fx", "agy", "exec-jsonl", "replay"]);
+
+/**
+ * The transcripts Faberun's own harness clients write (`runner-transcript.mjs`).
+ * `usage` names the event that carries one provider request's usage: dsh
+ * attaches it to each assistant message, while fx's relay reports it per HTTP
+ * request, apart from the message text.
+ */
+const RUNNER_TRANSCRIPTS = Object.freeze({
+  dsh: Object.freeze({ usage: "dsh.message", tool: "dsh.tool", completed: "dsh.completed", failed: "dsh.failed" }),
+  fx: Object.freeze({ usage: "fx.request", tool: "fx.tool", completed: "fx.completed", failed: "fx.failed" }),
+});
+
+/** @param {string} harness */
+function runnerTranscript(harness) {
+  return Object.hasOwn(RUNNER_TRANSCRIPTS, harness) ? RUNNER_TRANSCRIPTS[/** @type {"dsh"|"fx"} */ (harness)] : null;
+}
+
+/** @param {string} harness @param {unknown} type */
+function isRunnerTerminal(harness, type) {
+  const transcript = runnerTranscript(harness);
+  return transcript !== null && (type === transcript.completed || type === transcript.failed);
+}
 
 /**
  * Best-effort input-token meter over a still-growing transcript. The
@@ -90,15 +112,16 @@ export function liveUsage(harness, stdout) {
       cacheReadInputTokens: null,
     };
   }
-  if (harness === "dsh") {
-    // The terminal event carries the harness's own session total; before it
-    // lands, sum the per-message usage the runner forwards.
-    const terminal = events.findLast((event) => event?.type === "dsh.completed" || event?.type === "dsh.failed");
+  const transcript = runnerTranscript(harness);
+  if (transcript) {
+    // The terminal event carries the session total; before it lands, sum the
+    // per-request usage the runner forwards.
+    const terminal = events.findLast((event) => event?.type === transcript.completed || event?.type === transcript.failed);
     const terminalUsage = terminal ? canonicalUsage(terminal.usage) : null;
     if (terminalUsage && terminalUsage.inputTokens !== null) {
       return { inputTokens: terminalUsage.inputTokens, cacheReadInputTokens: terminalUsage.cacheReadInputTokens };
     }
-    return sumRequestUsage(events.filter((event) => event?.type === "dsh.message").map((event) => event.usage));
+    return sumRequestUsage(events.filter((event) => event?.type === transcript.usage).map((event) => event.usage));
   }
   if (harness === "agy") {
     const resultRecord = events.map((event) => agyResult(event)).findLast((result) => result !== null);
@@ -394,7 +417,7 @@ export class SessionMetricsParser {
       }
     } else if (this.harness === "claude" && record.type === "result") {
       totals.completed = true;
-    } else if (this.harness === "dsh" && (record.type === "dsh.completed" || record.type === "dsh.failed")) {
+    } else if (isRunnerTerminal(this.harness, record.type)) {
       totals.completed = true;
     } else if (this.harness === "agy" && record.event === "result") {
       totals.completed = true;
@@ -453,20 +476,22 @@ function foldRecord(harness, totals, record) {
     }
     return;
   }
-  if (harness === "dsh") {
-    // The runner folds the sdk firehose to one `dsh.message` per assistant
-    // message (with that message's usage) and one `dsh.tool` per tool call.
+  const transcript = runnerTranscript(harness);
+  if (transcript) {
+    // The dsh runner folds the sdk firehose to one `dsh.message` per assistant
+    // message (with that message's usage) and one `dsh.tool` per tool call;
+    // the fx runner reports usage per relayed request as `fx.request`.
     // measured 2026-09-20: before this branch a dsh turn metered zero events,
     // so once progress became event-only (668f6c1) the stall detector cut
     // every dsh worker at the contract's stallTimeoutSec regardless of
     // activity -- three kills on 2026-09-16 at 903s against a 900s limit.
-    if (record.type === "dsh.message") {
+    if (record.type === transcript.usage) {
       totals.turns += 1;
       totals.cacheReadInputTokens += canonicalUsage(record.usage).cacheReadInputTokens ?? 0;
       foldRequestUsage(totals, canonicalUsage(record.usage));
-    } else if (record.type === "dsh.tool") {
+    } else if (record.type === transcript.tool) {
       totals.toolCalls += 1;
-    } else if (record.type === "dsh.completed" || record.type === "dsh.failed") {
+    } else if (record.type === transcript.completed || record.type === transcript.failed) {
       const sessionTotal = canonicalUsage(record.usage).cacheReadInputTokens;
       if (sessionTotal !== null) totals.cacheReadInputTokens = sessionTotal;
     }

package/src/host/preflight.mjs

@@ -344,6 +344,7 @@ const SIDE_EFFECT_ENV_KEYS = [
   "FABERUN_CLAUDE_BIN", // same, for the claude harness
   "FABERUN_AGY_BIN", // same, for the agy harness
   "FABERUN_DSH_BIN", // same, for the dsh harness
+  "FABERUN_FX_BIN", // same, for the fx harness
   "FABERUN_ZCODE_BIN", // same, for the zcode harness
   "FABERUN_EXEC_JSONL_BIN", // same, for the exec-jsonl harness
 ];
@@ -672,7 +673,7 @@ export async function doctorCommand(contractPath, values) {
   // already validated whatever the runtime actually resolves to. `zcode` is
   // absent on purpose — its binary is a shim the harness writes on first use, so
   // a PATH miss here is the normal state of a fresh machine, not a missing
-  // dependency; `dsh` runs through its own SDK client, not a PATH binary.
+  // dependency; `dsh` and `fx` run through Faberun's own clients, not a PATH binary.
   for (const binary of ["codex", "claude", "agy", "exec-jsonl"]) {
     const overrideName = /** @type {Record<string, string>} */ (HARNESS_BIN_OVERRIDES)[binary];
     const overridden = overriddenHarnesses.has(binary) || Boolean(process.env[overrideName]);

package/src/plan/template.mjs

@@ -236,6 +236,25 @@ function readFilesForKind(kind, inputs) {
   return [/** @type {string} */ (inputs.specPath)];
 }
 
+/**
+ * The wall clock one planning stage gets, from the reasoning effort of the
+ * runtime that runs it. A stage is a single long turn over the whole plan, so
+ * the contract default (2400 s) fits a draft at ordinary effort but not a
+ * revise at high effort. Measured 2026-09-27: Opus 5.5 at `xhigh` revising
+ * a 20-node plan against 13 findings was still reasoning when the 2400 s wall
+ * clock ended the stage, and the pipeline, which cannot resume a stage, lost
+ * the draft and review it had already paid for.
+ *
+ * @param {Record<string, unknown>|undefined} runtime
+ * @returns {number}
+ */
+export function planningStageTimeoutSec(runtime) {
+  const reasoning = runtime?.reasoning;
+  if (reasoning === "xhigh" || reasoning === "max") return 7200;
+  if (reasoning === "high") return 3600;
+  return 2400;
+}
+
 /**
  * Build one of the planning pipeline's one-node discovery contracts. Pure:
  * no file is read or written, and no model is invoked. The returned object is
@@ -273,10 +292,13 @@ export function buildPlanningContract(kind, inputs) {
     verification: [],
   };
 
+  const stageRuntime = runtimeId === undefined ? undefined : /** @type {Record<string, unknown>|undefined} */ (inputs.runtimes[runtimeId]);
+
   return {
     schemaVersion: PROTOCOL_SCHEMA_VERSION,
     contractVersion: CONTRACT_VERSION,
     id: `${inputs.campaignId}-plan-${inputs.phase}-${kind}-${inputs.n}`,
+    timeoutSec: planningStageTimeoutSec(stageRuntime),
     campaignId: inputs.campaignId,
     goal: inputs.goal ?? `Plan ${kind} for phase ${inputs.phase}`,
     cwd: inputs.cwd ?? ".",