faberun 0.3.0

package/src/harnesses/dsh/closed-packet.patch.yml

@@ -0,0 +1,42 @@
+# The closed-packet profile: what a worker or a judge that may inspect only the
+# paths its packet names actually needs.
+#
+# Measured on one closed packet (fix a function, verify with an exit code),
+# same model, against the unpatched profile: 60,994 prompt tokens across 6
+# model calls, versus 11,959 across 4 with every row below disabled. The
+# preamble is re-sent on each call, so the saving multiplies by the number of
+# steps a node takes, not by the number of nodes.
+#
+# Rows are disabled by loader id, never removed: the services behind them still
+# mount, so nothing that waits on them fails to activate.
+- id: tool-jobs
+  disabled: true
+- id: tool-skill
+  disabled: true
+- id: tool-subagent
+  disabled: true
+- id: tool-subagent-fork
+  disabled: true
+- id: tool-subagent-control
+  disabled: true
+- id: tool-subagent-list-agents
+  disabled: true
+- id: tool-workflow
+  disabled: true
+- id: tool-todo
+  disabled: true
+- id: tool-goal
+  disabled: true
+- id: tool-ralph
+  disabled: true
+- id: tool-web
+  disabled: true
+- id: tool-pwsh
+  disabled: true
+- id: plan-mode
+  disabled: true
+# The packet is the instruction set: inheriting the repository's AGENTS.md
+# would hand a closed-packet worker rules nobody asked it to follow. In this
+# repository that file alone is ~2,500 prompt tokens per session.
+- id: agent-instructions
+  disabled: true

package/src/harnesses/dsh/index.mjs

@@ -0,0 +1,210 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalUsage, extractJson, failed, isQuotaText, isVerdictCandidate, parseJsonLines, parseVersion } from "../protocol.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The harness has no one-shot surface that reports what a turn cost, so the
+ * adapter's real provider is this client: it speaks the `sdk` JSON-RPC profile
+ * and folds the session firehose into the envelope. The `dsh` binary named by
+ * `executable()` is the harness the client drives, and probing it is what
+ * preflight means by "the provider binary exists".
+ */
+const RUNNER = join(HERE, "runner.mjs");
+
+/**
+ * Every runtime gets the closed-packet profile: the shipped harness advertises
+ * twenty-five tools and describes goals, subagents, and skills it was never
+ * asked to use. Measured on the same closed packet, that preamble costs
+ * 60,994 prompt tokens against 11,959 with this patch — the overhead is
+ * re-sent on every step, so it is paid once per model call, not once per node.
+ * `agent-instructions` is off for the same reason the packet is closed: the
+ * worker's instructions come from its packet, not from whatever `AGENTS.md`
+ * sits above the worktree.
+ */
+const CLOSED_PACKET_PATCH = join(HERE, "closed-packet.patch.yml");
+
+/**
+ * @type {import("../index.mjs").HarnessAdapter}
+ */
+export const dshHarness = {
+  capabilities: {
+    // The schema rides in the prompt and the verdict is extracted from the
+    // final message, exactly as `agy` does; nothing in the wire enforces it.
+    structuredOutput: true,
+    promptTransport: "stdin",
+    // `runtime.sandbox` maps onto DSH_PERMISSION_MODE, which is the harness's
+    // own file-effect boundary and its approval policy in one value.
+    sandbox: true,
+    permissions: false,
+    // `sdk` and `headless` are create-only: `session/resume` exists on the ACP
+    // profile alone, and reusing a persisted session id is refused outright.
+    continuation: false,
+    tokenBudget: false,
+    costBudget: false,
+    usage: true,
+    cost: false,
+    toolPolicy: false,
+    // Measured 2026-09-10: runner.mjs writeSync's each dsh.message as the
+    // session emits it, not just at the end. A three-tool-call turn against
+    // deepseek-official/deepseek-flash grew the redirected stdout file from
+    // 67 to 1,380 to 1,441 to 2,084 bytes across a 14s turn.
+    streamsOutput: true,
+  },
+
+  // sandbox maps to DSH_PERMISSION_MODE, which is the harness's file-effect
+  // boundary and its approval policy in one value. Both modes execute, so both
+  // are declared: measured 2026-09-11, a worker left at the harness default
+  // `workspace-write` ran `printf ... > exec-probe.txt` through the shell (the
+  // packet forbade the write tool) and the file reached the integrated commit.
+  // What that default cannot do is reach outside the worktree -- something a
+  // detached run cannot answer an approval prompt for, and the reason
+  // `danger-full-access` is the mode for a packet with effects beyond it.
+  permissionExecution: { field: "sandbox", executingModes: ["workspace-write", "danger-full-access"], defaultMode: "workspace-write" },
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @returns {string} */
+  executable(runtime) {
+    return process.env.FABERUN_DSH_BIN ?? runtime.executable ?? "dsh";
+  },
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @returns {string[]} */
+  versionArgs(runtime) {
+    return runtime.versionArgs ?? ["--version"];
+  },
+
+  parseVersion,
+
+  /**
+   * @param {import("../index.mjs").HarnessRuntime} runtime
+   * @param {string} prompt
+   * @param {import("../index.mjs").CommandOptions} options
+   * @returns {import("../index.mjs").HarnessCommand}
+   */
+  command(runtime, prompt, options = {}) {
+    const args = [
+      RUNNER,
+      "--dsh", this.executable(runtime),
+      "--provider", /** @type {string} */ (runtime.config?.provider),
+      "--model", runtime.model,
+    ];
+    if (runtime.reasoning) args.push("--reasoning", runtime.reasoning);
+    if (runtime.sandbox) args.push("--sandbox", runtime.sandbox);
+    args.push("--patch", CLOSED_PACKET_PATCH);
+    const extraPatch = runtime.config?.patch;
+    if (typeof extraPatch === "string" && extraPatch.length) args.push("--patch", extraPatch);
+    return {
+      executable: process.execPath,
+      args,
+      promptTransport: "stdin",
+      input: withSchema(prompt, options.schema),
+    };
+  },
+
+  /**
+   * @param {string} stdout
+   * @param {number|null} exitCode
+   * @param {string|null} signal
+   * @param {import("../index.mjs").NormalizeOptions} [options]
+   * @returns {import("../index.mjs").ProviderEnvelope}
+   */
+  normalize(stdout, exitCode, signal, options = {}) {
+    if (signal) return failed("canceled", `provider ended after ${signal}`, "canceled");
+    let events;
+    try {
+      events = parseJsonLines(stdout, "dsh");
+    } catch (error) {
+      return failed("invalid_protocol", error instanceof Error ? error.message : String(error));
+    }
+    const terminal = events.findLast((event) => event.type === "dsh.completed" || event.type === "dsh.failed");
+    if (!terminal) {
+      const detail = options.stderr?.trim();
+      return failed(
+        "incomplete_stream",
+        `dsh emitted no terminal event${detail ? `: ${detail.slice(-512)}` : ""}${exitCode === null ? "" : ` (exit ${exitCode})`}`,
+      );
+    }
+    const usage = canonicalUsage(terminal.usage);
+    if (terminal.type === "dsh.completed") {
+      const text = typeof terminal.result === "string" ? terminal.result : null;
+      const result = options.preferStructured ? extractJson(text) ?? text : text;
+      const verdicts = options.preferStructured ? countVerdicts(events) : 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; this harness has none, so it travels in the prompt.
+ *
+ * @param {string} prompt
+ * @param {object|undefined} schema
+ * @returns {string}
+ */
+function withSchema(prompt, schema) {
+  if (!schema) return prompt;
+  return `${prompt}\n\nOutput schema (the JSON object must validate against it):\n${JSON.stringify(schema)}`;
+}
+
+/**
+ * Count the verdict-shaped final messages, the way the codex adapter does: two
+ * verdicts in one turn must be visible at the provider boundary, because the
+ * last one alone is indistinguishable from a single clean answer.
+ *
+ * @param {Record<string, unknown>[]} events
+ * @returns {number}
+ */
+function countVerdicts(events) {
+  return events.filter((event) => event.type === "dsh.message" && isVerdictCandidate(event.text)).length;
+}
+
+/**
+ * @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();
+}
+
+export const harness = dshHarness;
+export default dshHarness;

package/src/harnesses/dsh/runner.mjs

@@ -0,0 +1,259 @@
+/**
+ * Faberun's DeepSeek Harness client: one prompt on stdin, one JSONL
+ * transcript on stdout, no interactive surface. The adapter runs this file
+ * under `process.execPath`, so spawning it never depends on a shebang, an
+ * executable bit, or `node` being on the provider's PATH.
+ *
+ * Why JSON-RPC instead of `dsh --profile headless`: headless discards every
+ * usage chunk it receives and prints the answer alone, so the tokens the
+ * controller records would be invented. `--profile sdk` streams every session
+ * event, including `assistant/message.data.usage`, and closes the turn with a
+ * structured reason whose `error.code` carries the provider's own QUOTA or
+ * RATE_LIMIT verdict — the fact the declared failover edge depends on.
+ *
+ * Transcript, the only thing this process writes to stdout:
+ *   {"type":"dsh.started","sessionId":string}
+ *   {"type":"dsh.message","text":string}          one per non-empty assistant message
+ *   {"type":"dsh.completed","sessionId":string,"result":string,"usage":Usage}
+ *   {"type":"dsh.failed","sessionId":string,"kind":string,"error":{...},"usage":Usage}
+ * where Usage is `{inputTokens, outputTokens, cacheReadInputTokens}` with
+ * `inputTokens` excluding the cached prefix, matching `canonicalUsage`.
+ */
+
+import { spawn } from "node:child_process";
+import { writeSync } from "node:fs";
+
+const HANDSHAKE_ID = 1;
+const PROMPT_ID = 2;
+
+/** Effective provider name for a failed harness start with no protocol output. */
+const HARNESS_EXIT_CODE = "harness_exit";
+
+/** @typedef {{dsh: string, provider: string|null, model: string|null, reasoning: string|null, sandbox: string|null, patches: string[]}} RunnerOptions */
+
+/**
+ * @param {string[]} argv
+ * @returns {RunnerOptions}
+ */
+function parseArgs(argv) {
+  /** @type {RunnerOptions} */
+  const options = {
+    dsh: "dsh",
+    provider: null,
+    model: null,
+    reasoning: null,
+    sandbox: null,
+    patches: [],
+  };
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (typeof value !== "string") throw new Error(`${flag} needs a value`);
+    if (flag === "--dsh") options.dsh = value;
+    else if (flag === "--provider") options.provider = value;
+    else if (flag === "--model") options.model = value;
+    else if (flag === "--reasoning") options.reasoning = value;
+    else if (flag === "--sandbox") options.sandbox = value;
+    else if (flag === "--patch") options.patches.push(value);
+    else throw new Error(`unknown argument: ${flag}`);
+  }
+  if (!options.provider) throw new Error("--provider is required");
+  if (!options.model) throw new Error("--model is required");
+  return options;
+}
+
+/**
+ * Whole-line writes to fd 1: `process.exit` cannot lose an unfinished write.
+ *
+ * @param {Record<string, unknown>} event
+ */
+function emit(event) {
+  const line = Buffer.from(`${JSON.stringify(event)}\n`, "utf8");
+  for (let written = 0; written < line.length; ) written += writeSync(1, line, written);
+}
+
+async function readPrompt() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * @param {{inputTokens: number, outputTokens: number, cacheReadInputTokens: number}} totals
+ * @param {unknown} usage
+ * @returns {boolean} whether any counter was observed
+ */
+function addUsage(totals, usage) {
+  if (!usage || typeof usage !== "object") return false;
+  const record = /** @type {Record<string, unknown>} */ (usage);
+  let observed = false;
+  /** @type {[string, keyof typeof totals][]} */
+  const counters = [["inputTokens", "inputTokens"], ["outputTokens", "outputTokens"], ["cacheReadTokens", "cacheReadInputTokens"]];
+  for (const [source, target] of counters) {
+    const value = record[source];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      totals[target] += value;
+      observed = true;
+    }
+  }
+  return observed;
+}
+
+/** @param {unknown} reason @returns {{kind: string, error: {code: string, message: string, retryAfterMs?: number} | null}} */
+function describeReason(reason) {
+  const record = reason && typeof reason === "object" ? /** @type {Record<string, unknown>} */ (reason) : {};
+  const kind = typeof record.kind === "string" ? record.kind : "unknown";
+  const failure = record.error && typeof record.error === "object" ? /** @type {Record<string, unknown>} */ (record.error) : null;
+  if (!failure) return { kind, error: null };
+  const code = typeof failure.code === "string" ? failure.code : kind;
+  const message = typeof failure.message === "string" ? failure.message : `${code}`;
+  const retryAfterMs = failure.providerRetryAfterMs;
+  const retryAfter = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) ? { retryAfterMs } : {};
+  return { kind, error: { code, message, ...retryAfter } };
+}
+
+const options = parseArgs(process.argv.slice(2));
+const prompt = await readPrompt();
+const sessionId = `faberun-${process.pid}-${Date.now().toString(36)}`;
+const env = { ...process.env };
+// The harness owns the boundary: `sandbox` names the file-effect mode the
+// contract asked for, and DSH derives its approval policy from the same value.
+if (options.sandbox) env.DSH_PERMISSION_MODE = options.sandbox;
+
+const args = ["--profile", "sdk"];
+for (const patch of options.patches) args.push("--patch", patch);
+const child = spawn(options.dsh, args, { cwd: process.cwd(), env, stdio: ["pipe", "pipe", "pipe"] });
+
+const usage = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 };
+let sawUsage = false;
+/** @type {string[]} */
+const texts = [];
+let stderrTail = "";
+let buffered = "";
+let prompted = false;
+let settled = false;
+
+/** @param {Record<string, unknown>} event @param {number} exitCode */
+function settle(event, exitCode) {
+  if (settled) return;
+  settled = true;
+  emit({ ...event, usage: sawUsage ? usage : null });
+  child.kill("SIGTERM");
+  process.exit(exitCode);
+}
+
+/** @param {string} kind @param {{code: string, message: string, retryAfterMs?: number}} error @param {number} [exitCode] */
+function fail(kind, error, exitCode = 1) {
+  settle({ type: "dsh.failed", sessionId, kind, error }, exitCode);
+}
+
+/** @param {Record<string, any>} event */
+function fold(event) {
+  if (event.type === "assistant/message") {
+    const data = event.data && typeof event.data === "object" ? /** @type {Record<string, unknown>} */ (event.data) : {};
+    sawUsage = addUsage(usage, data.usage) || sawUsage;
+    const message = data.message && typeof data.message === "object" ? /** @type {Record<string, unknown>} */ (data.message) : {};
+    const blocks = Array.isArray(message.content) ? message.content : [];
+    const text = blocks.map((block) => (block && typeof block === "object" && typeof block.text === "string" ? block.text : "")).join("");
+    if (text.trim()) {
+      texts.push(text);
+      // Every message, not only the last: a judge that returns two verdicts
+      // must be visible as two, and the adapter counts them here.
+      emit({ type: "dsh.message", text });
+    }
+    return;
+  }
+  if (event.type !== "turn/end") return;
+  const data = event.data && typeof event.data === "object" ? /** @type {Record<string, unknown>} */ (event.data) : {};
+  const { kind, error } = describeReason(data.reason);
+  if (kind === "completed") {
+    settle({ type: "dsh.completed", sessionId, result: texts.at(-1) ?? "" }, 0);
+    return;
+  }
+  fail(kind, error ?? { code: kind, message: `the turn ended: ${kind}` });
+}
+
+child.stdout.setEncoding("utf8");
+child.stdout.on("data", (chunk) => {
+  buffered += chunk;
+  const lines = buffered.split("\n");
+  buffered = lines.pop() ?? "";
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      // stdout carries the JSON-RPC transport only; a non-JSON line is a
+      // harness defect, not provider prose, and must not be silently dropped.
+      fail("invalid_protocol", { code: "invalid_protocol", message: `the harness wrote a non-JSON line: ${line.slice(0, 200)}` });
+      return;
+    }
+    if (message.id === HANDSHAKE_ID) {
+      if (message.error) {
+        fail("initialize_failed", { code: "initialize_failed", message: JSON.stringify(message.error).slice(0, 512) });
+        return;
+      }
+      if (prompted) continue;
+      prompted = true;
+      emit({ type: "dsh.started", sessionId });
+      child.stdin.write(`${JSON.stringify({
+        jsonrpc: "2.0",
+        id: PROMPT_ID,
+        method: "session/prompt",
+        params: { sessionId, contentBlocks: [{ type: "text", text: prompt }] },
+      })}\n`);
+      continue;
+    }
+    if (message.id === PROMPT_ID && message.error) {
+      fail("prompt_rejected", { code: "prompt_rejected", message: JSON.stringify(message.error).slice(0, 512) });
+      return;
+    }
+    if (message.method === "session.event" && message.params?.sessionId === sessionId && message.params.event) {
+      fold(message.params.event);
+    }
+  }
+});
+
+child.stderr.setEncoding("utf8");
+child.stderr.on("data", (chunk) => {
+  stderrTail = `${stderrTail}${chunk}`.slice(-4096);
+  process.stderr.write(chunk);
+});
+
+child.on("error", (error) => {
+  fail(HARNESS_EXIT_CODE, { code: HARNESS_EXIT_CODE, message: `cannot start ${options.dsh}: ${error.message}` });
+});
+
+child.on("close", (code) => {
+  const detail = stderrTail.trim() ? `: ${stderrTail.trim().slice(-512)}` : "";
+  fail(HARNESS_EXIT_CODE, {
+    code: HARNESS_EXIT_CODE,
+    message: `the harness exited with code ${code ?? 1} before the turn ended${detail}`,
+  });
+});
+
+for (const signal of ["SIGTERM", "SIGINT"]) {
+  process.on(signal, () => {
+    child.kill(/** @type {NodeJS.Signals} */ (signal));
+    process.exit(1);
+  });
+}
+
+child.stdin.write(`${JSON.stringify({
+  jsonrpc: "2.0",
+  id: HANDSHAKE_ID,
+  method: "initialize",
+  params: {
+    cwd: process.cwd(),
+    provider: options.provider,
+    model: options.model,
+    ...(options.reasoning ? { reasoningEffort: options.reasoning } : {}),
+  },
+})}\n`);
+
+process.on("exit", () => {
+  // `settle` already asked the harness to stop; only an exit that never
+  // reached it leaves a harness that must not outlive this process.
+  if (!settled) child.kill("SIGKILL");
+});