@tangle-network/agent-runtime 0.89.0 → 0.90.0

package/dist/{chunk-VNOOH22O.js → chunk-XMOU4WEY.js}

@@ -4,6 +4,11 @@ import {
 
 // src/improvement/agentic-generator.ts
 import { spawnSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var RAW_TRACE_ANALYST_ID = "raw-trace-distiller";
+var RAW_TRACE_AREA = "raw-trace-context";
+var RAW_TRACE_DIAGNOSIS_PATH = ".improve/raw-trace-diagnosis.md";
 function agenticGenerator(opts = {}) {
   const harness = opts.harness ?? "claude";
   const buildPrompt = opts.buildPrompt ?? defaultBuildPrompt;
@@ -14,6 +19,7 @@ function agenticGenerator(opts = {}) {
     kind: `agentic:${harness}`,
     async generate({ worktreePath, report, findings, maxShots, signal }) {
       const basePrompt = buildPrompt({ report, findings });
+      const needsRawTraceEvidence = requiresRawTraceEvidence(findings);
       const shots = Math.max(1, maxShots);
       let attemptNote = "";
       for (let shot = 0; shot < shots; shot++) {
@@ -31,6 +37,13 @@ ${attemptNote}` : basePrompt,
           attemptNote = EMPTY_TREE_NOTE;
           continue;
         }
+        if (needsRawTraceEvidence) {
+          const problem = rawTraceEvidenceProblem(worktreePath, findings);
+          if (problem) {
+            attemptNote = problem;
+            continue;
+          }
+        }
         if (!verify) {
           return { applied: true, summary: summarize(findings) };
         }
@@ -57,6 +70,16 @@ function defaultBuildPrompt(args) {
     lines.push(`- (${f.severity})${where} ${f.claim}`);
     if (f.recommended_action) lines.push(`    \u2192 ${f.recommended_action}`);
   }
+  if (requiresRawTraceEvidence(args.findings)) {
+    lines.push(
+      "",
+      "Raw trace evidence requirement:",
+      `- Inspect at least one raw trace path named above before editing.`,
+      `- Write ${RAW_TRACE_DIAGNOSIS_PATH} in this worktree.`,
+      "- Include the exact trace path(s) inspected, the failure mechanism, and the code change made.",
+      "- A candidate without this file, or with only this file changed, is discarded."
+    );
+  }
   return lines.join("\n");
 }
 var EMPTY_TREE_NOTE = "NOTE: your previous attempt left the working tree unchanged. Make the concrete file edits now.";
@@ -69,6 +92,51 @@ function failureNote(feedback) {
 ${truncate(detail, 4e3)}` : "No verifier detail was captured."
   ].join("\n");
 }
+function rawTraceEvidenceProblem(worktreePath, findings) {
+  const changedPaths = worktreeChangedPaths(worktreePath);
+  const substantive = changedPaths.filter((path) => path !== RAW_TRACE_DIAGNOSIS_PATH);
+  if (substantive.length === 0) {
+    return [
+      `NOTE: raw-trace mode requires a real code/config edit in addition to ${RAW_TRACE_DIAGNOSIS_PATH}.`,
+      "Your previous attempt only changed the diagnosis artifact. Inspect the cited traces and make the causal code change."
+    ].join("\n");
+  }
+  const diagnosisPath = join(worktreePath, RAW_TRACE_DIAGNOSIS_PATH);
+  if (!existsSync(diagnosisPath)) {
+    return [
+      `NOTE: raw-trace mode requires ${RAW_TRACE_DIAGNOSIS_PATH}.`,
+      "Before retrying, inspect at least one cited spans.jsonl/cached-result.json/artifact path, then write the diagnosis file with the exact path, failure mechanism, and code change."
+    ].join("\n");
+  }
+  const body = readFileSync(diagnosisPath, "utf8");
+  const evidencePaths = traceEvidencePaths(findings);
+  if (evidencePaths.length > 0 && !evidencePaths.some((path) => body.includes(path))) {
+    return [
+      `${RAW_TRACE_DIAGNOSIS_PATH} exists, but it does not cite any exact raw trace path from the findings.`,
+      `Cite at least one of these inspected paths exactly: ${evidencePaths.slice(0, 5).join(", ")}`
+    ].join("\n");
+  }
+  return null;
+}
+function requiresRawTraceEvidence(findings) {
+  return findings.some((finding) => {
+    const f = finding;
+    return f.analyst_id === RAW_TRACE_ANALYST_ID || f.area === RAW_TRACE_AREA;
+  });
+}
+function traceEvidencePaths(findings) {
+  const out = [];
+  for (const finding of findings) {
+    const refs = finding.evidence_refs;
+    if (!Array.isArray(refs)) continue;
+    for (const ref of refs) {
+      if (!ref || typeof ref !== "object") continue;
+      const uri = ref.uri;
+      if (typeof uri === "string" && uri.length > 0) out.push(uri);
+    }
+  }
+  return [...new Set(out)];
+}
 function commandVerifier(command, args = [], timeoutMs = 3e5) {
   return (worktreePath) => {
     const result = spawnSync(command, args, {
@@ -105,7 +173,10 @@ function truncate(s, n) {
   return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
 }
 function worktreeDirty(worktreePath) {
-  const result = spawnSync("git", ["status", "--porcelain"], {
+  return worktreeChangedPaths(worktreePath).length > 0;
+}
+function worktreeChangedPaths(worktreePath) {
+  const result = spawnSync("git", ["status", "--porcelain", "--untracked-files=all"], {
     cwd: worktreePath,
     encoding: "utf-8"
   });
@@ -119,7 +190,7 @@ function worktreeDirty(worktreePath) {
       `agenticGenerator: git status exited ${result.status} in ${worktreePath}: ${result.stderr.trim()}`
     );
   }
-  return result.stdout.trim().length > 0;
+  return result.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => line.slice(3).trim());
 }
 
 // src/improvement/build-prompts.ts
@@ -263,4 +334,4 @@ export {
   mcpBuildPrompt,
   mcpServeVerifier
 };
-//# sourceMappingURL=chunk-VNOOH22O.js.map
+//# sourceMappingURL=chunk-XMOU4WEY.js.map

package/dist/chunk-XMOU4WEY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/improvement/agentic-generator.ts","../src/improvement/build-prompts.ts","../src/improvement/mcp-serve-verifier.ts"],"sourcesContent":["/**\n *\n * `agenticGenerator` — the full-agentic `CandidateGenerator`: the\n * `shots=N, sandbox=on` setting of the one `improvementDriver`. It runs a real\n * coding harness (claude / codex / opencode) inside the candidate worktree the\n * driver already created, letting the agent read the codebase + the research\n * report and make the change in place. The driver then commits the worktree\n * into a `CodeSurface`.\n *\n * Mechanism: identical to the proven Phase-2.8 in-process executor — spawn the\n * harness as a subprocess with `cwd` = the worktree, on the same filesystem,\n * so edits land in place (no sandbox-mount round-trip). `runLocalHarness` is\n * the verified primitive. The OUTER sandbox is the improvement loop's own\n * execution context; the generator does not nest a second sandbox per\n * candidate (which would reintroduce a host↔sandbox worktree-transport\n * problem that does not need solving here).\n *\n * `maxShots` is the DEPTH dial — a multi-shot verify-in-session loop, NOT the\n * kernel `runLoop`. Each shot runs one full harness session in the (persistent)\n * worktree; between shots the loop refines based on what the last shot produced:\n *   - empty tree   → \"you changed nothing, make the edits\" → retry\n *   - dirty + `verify` fails → feed the verifier's failure into the next shot\n *       (the worktree persists, so the harness RESUMES atop its own failing\n *       edits with the error in hand — no `--resume` session plumbing needed,\n *       and harness-agnostic across claude/codex/opencode)\n *   - dirty + `verify` ok (or no verifier configured) → return the candidate\n * A candidate that never verifies within `maxShots` is discarded (`applied:\n * false`), never shipped — if you configured a verifier, a non-passing tree is\n * not a candidate. With no verifier the legacy behavior holds: first dirty shot\n * is the candidate.\n *\n * @experimental\n */\n\nimport { spawnSync } from 'node:child_process'\nimport { existsSync, readFileSync } from 'node:fs'\nimport { join } from 'node:path'\nimport type { AnalystFinding } from '@tangle-network/agent-eval'\nimport { type LocalHarness, runLocalHarness } from '../mcp/local-harness'\nimport type { CandidateGenerator } from './improvement-driver'\n\nconst RAW_TRACE_ANALYST_ID = 'raw-trace-distiller'\nconst RAW_TRACE_AREA = 'raw-trace-context'\nconst RAW_TRACE_DIAGNOSIS_PATH = '.improve/raw-trace-diagnosis.md'\n\n/** Outcome of verifying a candidate worktree. `feedback` (compiler errors,\n *  failing test output) is fed into the next shot when `ok` is false. */\nexport interface VerifyResult {\n  ok: boolean\n  feedback?: string\n}\n\n/** Verifies the edited worktree. Sync or async; throws only on a setup fault\n *  (a candidate that fails verification returns `{ok:false}`, it does not\n *  throw). */\nexport type Verifier = (worktreePath: string) => Promise<VerifyResult> | VerifyResult\n\nexport interface AgenticGeneratorOptions {\n  /** Local coding harness to run in the worktree. Default `claude`. */\n  harness?: LocalHarness\n  /** Per-shot wall-clock timeout (ms). Default = `runLocalHarness` default (5m). */\n  timeoutMs?: number\n  /** Build the harness task prompt from the report + findings. Override for\n   *  domain phrasing; the default turns findings into a concrete coder task. */\n  buildPrompt?: (args: { report: unknown; findings: AnalystFinding[] }) => string\n  /** Verify the worktree after each dirtying shot. When set, a candidate that\n   *  fails verification is NOT returned — the failure feeds the next shot\n   *  (verify-in-session), up to `maxShots`; a candidate that never verifies is\n   *  discarded (`applied:false`), never shipped. Omitted ⇒ legacy behavior:\n   *  the first dirty shot is the candidate. See `commandVerifier`. */\n  verify?: Verifier\n  /** Test seam — inject the harness runner (defaults to `runLocalHarness`). */\n  runHarness?: typeof runLocalHarness\n  /** Test seam — inject the worktree-dirty check (defaults to `git status`). */\n  isDirty?: (worktreePath: string) => boolean\n}\n\n/** Full-agentic `CandidateGenerator` (the `shots=N, sandbox=on` setting): run a real coding harness inside the candidate worktree so the agent makes the change in place. */\nexport function agenticGenerator(opts: AgenticGeneratorOptions = {}): CandidateGenerator {\n  const harness = opts.harness ?? 'claude'\n  const buildPrompt = opts.buildPrompt ?? defaultBuildPrompt\n  const run = opts.runHarness ?? runLocalHarness\n  const dirty = opts.isDirty ?? worktreeDirty\n  const verify = opts.verify\n\n  return {\n    kind: `agentic:${harness}`,\n    async generate({ worktreePath, report, findings, maxShots, signal }) {\n      const basePrompt = buildPrompt({ report, findings })\n      const needsRawTraceEvidence = requiresRawTraceEvidence(findings)\n      const shots = Math.max(1, maxShots)\n      // Feedback appended to the base prompt for the NEXT shot — empty on shot 0.\n      let attemptNote = ''\n\n      for (let shot = 0; shot < shots; shot++) {\n        if (signal.aborted) break\n        await run({\n          harness,\n          cwd: worktreePath,\n          taskPrompt: attemptNote ? `${basePrompt}\\n\\n${attemptNote}` : basePrompt,\n          timeoutMs: opts.timeoutMs,\n          signal,\n        })\n\n        // The worktree IS the signal: no edits ⇒ tell the next shot to act.\n        if (!dirty(worktreePath)) {\n          attemptNote = EMPTY_TREE_NOTE\n          continue\n        }\n\n        if (needsRawTraceEvidence) {\n          const problem = rawTraceEvidenceProblem(worktreePath, findings)\n          if (problem) {\n            attemptNote = problem\n            continue\n          }\n        }\n\n        // Dirty: with no verifier the diff IS the candidate (we trust the diff,\n        // not the harness's stdout). With a verifier the candidate must pass it.\n        if (!verify) {\n          return { applied: true, summary: summarize(findings) }\n        }\n        const result = await verify(worktreePath)\n        if (result.ok) {\n          return { applied: true, summary: summarize(findings) }\n        }\n        // Dirty but failing — resume next shot atop these edits with the error.\n        attemptNote = failureNote(result.feedback)\n      }\n\n      // Shots exhausted: no verified candidate (or, sans verifier, no edits).\n      return { applied: false, summary: '' }\n    },\n  }\n}\n\n/** Turn the analyst's findings (+ optional report) into a concrete coder task. */\nfunction defaultBuildPrompt(args: { report: unknown; findings: AnalystFinding[] }): string {\n  const lines: string[] = [\n    'You are improving this codebase based on an evaluation analysis.',\n    'Make the smallest set of edits that addresses the findings below, then stop.',\n    'Do not change unrelated code. Do not commit — leave changes in the working tree.',\n    '',\n    'Findings:',\n  ]\n  for (const f of args.findings) {\n    const where = f.subject ? ` [${f.subject}]` : ''\n    lines.push(`- (${f.severity})${where} ${f.claim}`)\n    if (f.recommended_action) lines.push(`    → ${f.recommended_action}`)\n  }\n  if (requiresRawTraceEvidence(args.findings)) {\n    lines.push(\n      '',\n      'Raw trace evidence requirement:',\n      `- Inspect at least one raw trace path named above before editing.`,\n      `- Write ${RAW_TRACE_DIAGNOSIS_PATH} in this worktree.`,\n      '- Include the exact trace path(s) inspected, the failure mechanism, and the code change made.',\n      '- A candidate without this file, or with only this file changed, is discarded.',\n    )\n  }\n  return lines.join('\\n')\n}\n\nconst EMPTY_TREE_NOTE =\n  'NOTE: your previous attempt left the working tree unchanged. Make the concrete file edits now.'\n\n/** Next-shot feedback when the worktree is dirty but failed verification. The\n *  edits persist on disk, so the harness resumes atop them — tell it to fix in\n *  place, not start over. Verifier detail is truncated to keep the prompt bounded. */\nfunction failureNote(feedback?: string): string {\n  const detail = feedback?.trim()\n  return [\n    'NOTE: your edits are in the working tree but verification FAILED.',\n    'Fix the problem in place — build on your existing edits, do not revert them.',\n    detail ? `Verifier output:\\n${truncate(detail, 4000)}` : 'No verifier detail was captured.',\n  ].join('\\n')\n}\n\nfunction rawTraceEvidenceProblem(worktreePath: string, findings: AnalystFinding[]): string | null {\n  const changedPaths = worktreeChangedPaths(worktreePath)\n  const substantive = changedPaths.filter((path) => path !== RAW_TRACE_DIAGNOSIS_PATH)\n  if (substantive.length === 0) {\n    return [\n      `NOTE: raw-trace mode requires a real code/config edit in addition to ${RAW_TRACE_DIAGNOSIS_PATH}.`,\n      'Your previous attempt only changed the diagnosis artifact. Inspect the cited traces and make the causal code change.',\n    ].join('\\n')\n  }\n\n  const diagnosisPath = join(worktreePath, RAW_TRACE_DIAGNOSIS_PATH)\n  if (!existsSync(diagnosisPath)) {\n    return [\n      `NOTE: raw-trace mode requires ${RAW_TRACE_DIAGNOSIS_PATH}.`,\n      'Before retrying, inspect at least one cited spans.jsonl/cached-result.json/artifact path, then write the diagnosis file with the exact path, failure mechanism, and code change.',\n    ].join('\\n')\n  }\n\n  const body = readFileSync(diagnosisPath, 'utf8')\n  const evidencePaths = traceEvidencePaths(findings)\n  if (evidencePaths.length > 0 && !evidencePaths.some((path) => body.includes(path))) {\n    return [\n      `${RAW_TRACE_DIAGNOSIS_PATH} exists, but it does not cite any exact raw trace path from the findings.`,\n      `Cite at least one of these inspected paths exactly: ${evidencePaths.slice(0, 5).join(', ')}`,\n    ].join('\\n')\n  }\n\n  return null\n}\n\nfunction requiresRawTraceEvidence(findings: AnalystFinding[]): boolean {\n  return findings.some((finding) => {\n    const f = finding as unknown as Record<string, unknown>\n    return f.analyst_id === RAW_TRACE_ANALYST_ID || f.area === RAW_TRACE_AREA\n  })\n}\n\nfunction traceEvidencePaths(findings: AnalystFinding[]): string[] {\n  const out: string[] = []\n  for (const finding of findings) {\n    const refs = (finding as unknown as { evidence_refs?: unknown }).evidence_refs\n    if (!Array.isArray(refs)) continue\n    for (const ref of refs) {\n      if (!ref || typeof ref !== 'object') continue\n      const uri = (ref as { uri?: unknown }).uri\n      if (typeof uri === 'string' && uri.length > 0) out.push(uri)\n    }\n  }\n  return [...new Set(out)]\n}\n\n/** A `Verifier` that runs a command in the worktree: exit 0 ⇒ ok, any other\n *  exit ⇒ failed with stdout+stderr as feedback. The common case — verify by\n *  `tsc --noEmit`, `pnpm build`, or a test command. A timeout is treated as a\n *  FAILED candidate (a change that hangs the build is a bad change); a missing\n *  binary or spawn fault throws (a setup bug, not a failed candidate — no\n *  silent fallback). */\nexport function commandVerifier(\n  command: string,\n  args: string[] = [],\n  timeoutMs = 300_000,\n): Verifier {\n  return (worktreePath: string): VerifyResult => {\n    const result = spawnSync(command, args, {\n      cwd: worktreePath,\n      encoding: 'utf-8',\n      timeout: timeoutMs,\n    })\n    if (result.signal) {\n      return {\n        ok: false,\n        feedback: `verifier '${command}' killed by ${result.signal} (likely timeout after ${timeoutMs}ms)`,\n      }\n    }\n    if (result.error) {\n      const code = (result.error as NodeJS.ErrnoException).code\n      if (code === 'ENOENT') {\n        throw new Error(\n          `commandVerifier: '${command}' not found in PATH (setup bug, not a failed candidate)`,\n        )\n      }\n      throw new Error(`commandVerifier: '${command}' failed to spawn: ${result.error.message}`)\n    }\n    if (result.status === 0) return { ok: true }\n    const out = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()\n    return { ok: false, feedback: out.length > 0 ? out : `exit ${result.status}` }\n  }\n}\n\n/** A one-line summary for the commit message, derived from the findings. */\nfunction summarize(findings: AnalystFinding[]): string {\n  if (findings.length === 0) return 'agentic improvement'\n  if (findings.length === 1) return `agentic: ${truncate(findings[0]!.claim, 64)}`\n  return `agentic: ${findings.length} findings addressed`\n}\n\nfunction truncate(s: string, n: number): string {\n  return s.length <= n ? s : `${s.slice(0, n - 1)}…`\n}\n\n/** Non-empty `git status --porcelain` ⇒ the harness changed the worktree.\n *  Fails loud: the worktree is a fresh checkout, so a git error here means\n *  something is genuinely broken (git missing, corrupt index, killed mid-run).\n *  Folding that into `false` would silently discard a candidate and mask the\n *  real failure — forbidden by the no-silent-fallbacks doctrine. */\nfunction worktreeDirty(worktreePath: string): boolean {\n  return worktreeChangedPaths(worktreePath).length > 0\n}\n\nfunction worktreeChangedPaths(worktreePath: string): string[] {\n  const result = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], {\n    cwd: worktreePath,\n    encoding: 'utf-8',\n  })\n  if (result.error) {\n    throw new Error(\n      `agenticGenerator: git status failed to spawn in ${worktreePath}: ${result.error.message}`,\n    )\n  }\n  if (result.status !== 0) {\n    throw new Error(\n      `agenticGenerator: git status exited ${result.status} in ${worktreePath}: ${result.stderr.trim()}`,\n    )\n  }\n  return result.stdout\n    .split('\\n')\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0)\n    .map((line) => line.slice(3).trim())\n}\n","/**\n * Build-prompt starting points for the two buildable artifact types. There is\n * NO `toolGenerator`/`mcpGenerator` wrapper — the factory is `agenticGenerator`\n * + a verifier (docs/artifact-lifecycle-frontier.md), so a tool or an MCP\n * server is built by composing the pieces directly:\n *\n *   // a tool:\n *   agenticGenerator({ buildPrompt: toolBuildPrompt, verify: commandVerifier('pnpm', ['test']) })\n *   // an MCP server:\n *   agenticGenerator({ buildPrompt: mcpBuildPrompt, verify: mcpServeVerifier({ command: 'node', args: ['server.mjs'] }) })\n *\n * These are the only type-specific bit (the phrasing that points the agent at a\n * tool vs. an MCP); the worktree, resume-on-failure loop, and improvement-loop\n * wrapper are shared. MCP is the load-bearing target — it is how a harness\n * acquires tools; raw tools matter where we control the loader.\n */\n\nimport type { AnalystFinding } from '@tangle-network/agent-eval'\n\ntype FindingsArg = { report: unknown; findings: AnalystFinding[] }\n\nfunction findingLines(findings: AnalystFinding[]): string[] {\n  return findings.map((f) => {\n    const where = f.subject ? ` [${f.subject}]` : ''\n    const action = f.recommended_action ? ` → ${f.recommended_action}` : ''\n    return `- (${f.severity})${where} ${f.claim}${action}`\n  })\n}\n\n/** Build the starting instruction for a coder agent tasked with implementing a new tool. */\nexport function toolBuildPrompt(args: FindingsArg): string {\n  return [\n    'You are building a new TOOL for this codebase to address the gaps below.',\n    'Write the tool as a small, self-contained module PLUS tests that exercise it.',\n    'The tool must compile and its tests must pass — they will be run automatically;',\n    'if verification fails you will get the error and another attempt. Do not commit;',\n    'leave the changes in the working tree.',\n    '',\n    'Gaps the tool should close:',\n    ...findingLines(args.findings),\n  ].join('\\n')\n}\n\n/** Build the starting instruction for a coder agent tasked with implementing a new MCP server. */\nexport function mcpBuildPrompt(args: FindingsArg): string {\n  return [\n    'You are building a new MCP SERVER (Model Context Protocol) that exposes',\n    'tool(s) addressing the gaps below, so any harness can mount it.',\n    'Requirements that WILL be checked by booting the server:',\n    '- it starts over stdio and answers the MCP `initialize` handshake,',\n    '- `tools/list` returns at least one tool with a valid input schema.',\n    'Newline-delimited JSON-RPC 2.0, protocol version 2024-11-05. Include a start',\n    'command (e.g. a package.json `start` script or a clear entrypoint). If the',\n    'boot-and-probe fails you will get the error and another attempt. Do not',\n    'commit; leave the changes in the working tree.',\n    '',\n    'Capabilities the server should provide:',\n    ...findingLines(args.findings),\n  ].join('\\n')\n}\n","/**\n * `mcpServeVerifier` — the intrinsic verifier for a built MCP server: the\n * boot-and-probe checker named in docs/artifact-lifecycle-frontier.md. A\n * generated MCP server is only a candidate if it actually *serves* — so this\n * boots it over stdio (the default local MCP transport) and runs the real\n * handshake: `initialize` → `notifications/initialized` → `tools/list`, and\n * asserts the server answers with at least `minTools` tools.\n *\n * Outcomes follow the `Verifier` contract: a server that fails to start, exits\n * early, errors the handshake, times out, or exposes no tools is a FAILED\n * candidate (`{ok:false}`, fed back into the next generation shot); a missing\n * start binary or spawn fault THROWS (a setup bug, never a silent fallback).\n *\n * Protocol matches the runtime's own stdio MCP server (src/mcp/server.ts):\n * newline-delimited JSON-RPC 2.0, protocol version 2024-11-05.\n */\n\nimport { spawn } from 'node:child_process'\nimport { createInterface } from 'node:readline'\nimport type { Verifier, VerifyResult } from './agentic-generator'\n\nconst PROTOCOL_VERSION = '2024-11-05'\n\nexport interface McpServeSpec {\n  /** Command that starts the built MCP server in the worktree (stdio transport). */\n  command: string\n  args?: string[]\n  /** Extra env for the server process (merged over `process.env`). */\n  env?: Record<string, string>\n  /** Handshake timeout (ms). Default 30s. */\n  timeoutMs?: number\n  /** Minimum tools the server must expose to pass. Default 1. */\n  minTools?: number\n}\n\ninterface JsonRpcResponse {\n  jsonrpc?: string\n  id?: number | string | null\n  result?: unknown\n  error?: { code: number; message: string }\n}\n\n/** Build a `Verifier` that boots a generated MCP server over stdio and checks it exposes tools. */\nexport function mcpServeVerifier(spec: McpServeSpec): Verifier {\n  const timeoutMs = spec.timeoutMs ?? 30_000\n  const minTools = spec.minTools ?? 1\n\n  return (worktreePath: string): Promise<VerifyResult> =>\n    new Promise<VerifyResult>((resolve, reject) => {\n      const child = spawn(spec.command, spec.args ?? [], {\n        cwd: worktreePath,\n        stdio: ['pipe', 'pipe', 'pipe'],\n        env: { ...process.env, ...spec.env },\n      })\n\n      const stderr: string[] = []\n      let settled = false\n      let nextId = 1\n      const initId = nextId++\n      let listId = -1\n\n      const settle = (fn: () => void) => {\n        if (settled) return\n        settled = true\n        clearTimeout(timer)\n        rl.close()\n        child.kill('SIGKILL')\n        fn()\n      }\n      const withStderr = (msg: string) =>\n        stderr.length > 0 ? `${msg}\\nstderr:\\n${stderr.join('').slice(-2000)}` : msg\n      const pass = () => settle(() => resolve({ ok: true }))\n      const failCandidate = (msg: string) =>\n        settle(() => resolve({ ok: false, feedback: withStderr(msg) }))\n      const setupFault = (err: Error) => settle(() => reject(err))\n\n      const send = (msg: Record<string, unknown>): boolean => {\n        try {\n          child.stdin.write(`${JSON.stringify(msg)}\\n`)\n          return true\n        } catch (err) {\n          // EPIPE: the server died mid-handshake — a failed candidate, not a fault.\n          failCandidate(`writing to MCP server stdin failed: ${(err as Error).message}`)\n          return false\n        }\n      }\n\n      child.on('error', (err) => {\n        const code = (err as NodeJS.ErrnoException).code\n        setupFault(\n          code === 'ENOENT'\n            ? new Error(\n                `mcpServeVerifier: '${spec.command}' not found in PATH (setup bug, not a failed candidate)`,\n              )\n            : new Error(`mcpServeVerifier: '${spec.command}' failed to spawn: ${err.message}`),\n        )\n      })\n      child.on('exit', (code, signal) => {\n        // An exit before the handshake completes is a failed candidate (the\n        // server crashed on boot); after we settle, our own SIGKILL fires here.\n        failCandidate(`MCP server exited (code ${code}, signal ${signal}) before serving`)\n      })\n      child.stderr.on('data', (d) => stderr.push(String(d)))\n\n      const rl = createInterface({ input: child.stdout })\n      rl.on('line', (line) => {\n        let msg: JsonRpcResponse | undefined\n        try {\n          msg = JSON.parse(line) as JsonRpcResponse\n        } catch {\n          return // servers log to stdout too; skip non-JSON lines\n        }\n        if (!msg || typeof msg !== 'object') return\n\n        if (msg.id === initId) {\n          if (msg.error) return failCandidate(`initialize errored: ${JSON.stringify(msg.error)}`)\n          if (!send({ jsonrpc: '2.0', method: 'notifications/initialized' })) return\n          listId = nextId++\n          send({ jsonrpc: '2.0', id: listId, method: 'tools/list' })\n          return\n        }\n        if (msg.id === listId) {\n          if (msg.error) return failCandidate(`tools/list errored: ${JSON.stringify(msg.error)}`)\n          const tools = (msg.result as { tools?: unknown[] } | undefined)?.tools\n          if (!Array.isArray(tools)) return failCandidate('tools/list result has no tools array')\n          if (tools.length < minTools) {\n            return failCandidate(`tools/list returned ${tools.length} tool(s), need >= ${minTools}`)\n          }\n          return pass()\n        }\n      })\n\n      const timer = setTimeout(\n        () => failCandidate(`MCP server did not complete the handshake within ${timeoutMs}ms`),\n        timeoutMs,\n      )\n\n      send({\n        jsonrpc: '2.0',\n        id: initId,\n        method: 'initialize',\n        params: {\n          protocolVersion: PROTOCOL_VERSION,\n          capabilities: {},\n          clientInfo: { name: 'agent-runtime-mcp-verify', version: '0' },\n        },\n      })\n    })\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-5AVV7KAH.js → chunk-XQEISTK2.js}

@@ -8,7 +8,7 @@ import {
   DELEGATION_STATUS_DESCRIPTION,
   DELEGATION_STATUS_INPUT_SCHEMA,
   DELEGATION_STATUS_TOOL_NAME
-} from "./chunk-N7EJV7N3.js";
+} from "./chunk-QSNSMJSZ.js";
 
 // src/mcp/openai-tools.ts
 function buildTool(name, description, parameters) {
@@ -45,4 +45,4 @@ export {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
 };
-//# sourceMappingURL=chunk-5AVV7KAH.js.map
+//# sourceMappingURL=chunk-XQEISTK2.js.map

package/dist/{worktree-harness-CX_McRLp.d.ts → completion-gate-BDaBP8dd.d.ts}

@@ -1,48 +1,5 @@
-import { a as Executor } from './types-Driepl87.js';
 import { L as LocalHarness } from './local-harness-sI0S_XNA.js';
-
-/**
- *
- * The completion-oracle: **settled ⟺ DELIVERED.**
- *
- * Foreman's one hard lesson (0/18 self-improvement deliverables) — "done" must mean a check
- * PASSED, not the agent's say-so. `gateOnDeliverable` wraps an `Executor` so its settlement
- * is `valid` ONLY when the deliverable check passes. The child still RUNS and settles (its
- * spend is conserved into the pool either way), but a child that ran WITHOUT delivering
- * settles `valid:false` — so a keep-best driver never counts it as done, and a gate never
- * inflates with self-judged wins.
- *
- * Dual-purpose by construction:
- *  - product: the agent fleet only advances on real, checked deliverables.
- *  - proof: the gate's `valid` is the honest settle — equal-k comparisons can't be gamed by an
- *    arm that "ran" without producing the artifact.
- *
- * The check is a DEPLOYABLE oracle — a test command, a state verifier, the commit0 judge —
- * read off the child's output, never the model judging itself. A throwing check is
- * fail-closed (not delivered), never a crash.
- *
- * @experimental
- */
-
-/**
- * The deployable completion oracle passed to {@link gateOnDeliverable}: a `check` that
- * decides DELIVERED (settles `valid` ⟺ it resolves true) plus an optional `describe` of
- * what the spawn was supposed to produce. The check reads the child's output — never the
- * model judging itself.
- */
-interface DeliverableSpec<Out = unknown> {
-    /** The deployable check that decides DELIVERED. `settled.valid ⟺ this resolves true`. */
-    check: (out: Out) => boolean | Promise<boolean>;
-    /** What the spawn was supposed to produce — surfaced in traces/reports. */
-    describe?: string;
-}
-/**
- * Wrap an `Executor` so its settlement `valid` reflects the deliverable check, not the
- * inner verdict. Handles both `execute` shapes (one-shot `Promise<ExecutorResult>` and
- * streaming `AsyncIterable<UsageEvent>` + `resultArtifact()`); the check runs once the inner
- * executor has produced its output. The inner `score` is preserved; only `valid` is gated.
- */
-declare function gateOnDeliverable<Out>(inner: Executor<Out>, deliverable: DeliverableSpec<Out>): Executor<Out>;
+import { c as Executor } from './types-DAJQRIUD.js';
 
 /**
  *
@@ -197,4 +154,47 @@ type WorktreeCheckRunner = (opts: {
     output: string;
 }>;
 
+/**
+ *
+ * The completion-oracle: **settled ⟺ DELIVERED.**
+ *
+ * Foreman's one hard lesson (0/18 self-improvement deliverables) — "done" must mean a check
+ * PASSED, not the agent's say-so. `gateOnDeliverable` wraps an `Executor` so its settlement
+ * is `valid` ONLY when the deliverable check passes. The child still RUNS and settles (its
+ * spend is conserved into the pool either way), but a child that ran WITHOUT delivering
+ * settles `valid:false` — so a keep-best driver never counts it as done, and a gate never
+ * inflates with self-judged wins.
+ *
+ * Dual-purpose by construction:
+ *  - product: the agent fleet only advances on real, checked deliverables.
+ *  - proof: the gate's `valid` is the honest settle — equal-k comparisons can't be gamed by an
+ *    arm that "ran" without producing the artifact.
+ *
+ * The check is a DEPLOYABLE oracle — a test command, a state verifier, the commit0 judge —
+ * read off the child's output, never the model judging itself. A throwing check is
+ * fail-closed (not delivered), never a crash.
+ *
+ * @experimental
+ */
+
+/**
+ * The deployable completion oracle passed to {@link gateOnDeliverable}: a `check` that
+ * decides DELIVERED (settles `valid` ⟺ it resolves true) plus an optional `describe` of
+ * what the spawn was supposed to produce. The check reads the child's output — never the
+ * model judging itself.
+ */
+interface DeliverableSpec<Out = unknown> {
+    /** The deployable check that decides DELIVERED. `settled.valid ⟺ this resolves true`. */
+    check: (out: Out) => boolean | Promise<boolean>;
+    /** What the spawn was supposed to produce — surfaced in traces/reports. */
+    describe?: string;
+}
+/**
+ * Wrap an `Executor` so its settlement `valid` reflects the deliverable check, not the
+ * inner verdict. Handles both `execute` shapes (one-shot `Promise<ExecutorResult>` and
+ * streaming `AsyncIterable<UsageEvent>` + `resultArtifact()`); the check runs once the inner
+ * executor has produced its output. The inner `score` is preserved; only `valid` is gated.
+ */
+declare function gateOnDeliverable<Out>(inner: Executor<Out>, deliverable: DeliverableSpec<Out>): Executor<Out>;
+
 export { type CreateWorktreeOptions as C, type DeliverableSpec as D, type GitRunner as G, type RemoveWorktreeOptions as R, type WorktreeHarnessResult as W, type WorktreeCheckRunner as a, type DiffOptions as b, type DiffResult as c, type WorktreeHandle as d, captureWorktreeDiff as e, createWorktree as f, type WorktreeCommandResult as g, gateOnDeliverable as h, removeWorktree as r };