@tangle-network/agent-runtime 0.68.0 → 0.70.0

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "./chunk-OYU5LR4T.js";
+} from "./chunk-EDCVUZZC.js";
 import {
   DEFAULT_ROUTER_BASE_URL,
   cleanModelId,
@@ -21,18 +21,9 @@ import {
   runLoopRunnerCli,
   selfImproveLoopRunner,
   worktreeLoopRunner
-} from "./chunk-FCIPUALH.js";
+} from "./chunk-BYZCXQHF.js";
 import "./chunk-FNMGYYSS.js";
-import "./chunk-QNUEFNU7.js";
-import "./chunk-DVQGYDN5.js";
-import "./chunk-P5OKDSLB.js";
-import {
-  composeRuntimeHooks,
-  defineRuntimeHooks,
-  notifyRuntimeDecisionPoint,
-  notifyRuntimeHookEvent
-} from "./chunk-VKUHUFX7.js";
-import "./chunk-WIR4HOOJ.js";
+import "./chunk-L5ZFBVT6.js";
 import {
   AgentEvalError,
   BackendTransportError,
@@ -42,9 +33,14 @@ import {
   PlannerError,
   RuntimeRunStateError,
   SessionMismatchError,
-  ValidationError
-} from "./chunk-VLF5RHEQ.js";
-import "./chunk-O2UPHN7X.js";
+  ValidationError,
+  assertModelAllowed,
+  composeRuntimeHooks,
+  defineRuntimeHooks,
+  notifyRuntimeDecisionPoint,
+  notifyRuntimeHookEvent,
+  runLocalHarness
+} from "./chunk-QXWGSDAQ.js";
 import {
   INTELLIGENCE_WIRE_VERSION,
   buildLoopOtelSpans,
@@ -53,6 +49,8 @@ import {
   exportEvalRuns,
   loopEventToOtelSpan
 } from "./chunk-G3RGMA7C.js";
+import "./chunk-DVQGYDN5.js";
+import "./chunk-WIR4HOOJ.js";
 import "./chunk-DGUM43GV.js";
 
 // src/sessions.ts
@@ -1420,6 +1418,146 @@ function normalizePolicy(policy, participantCount) {
   return { ...policy, turnOrder };
 }
 
+// src/conversation/run-persona.ts
+function withProfilePrompt(inner, systemPrompt, counter) {
+  return {
+    kind: inner.kind,
+    start: inner.start ? (input, ctx) => inner.start(input, ctx) : void 0,
+    resume: inner.resume ? (session, input, ctx) => inner.resume(session, input, ctx) : void 0,
+    stop: inner.stop ? (session, reason) => inner.stop(session, reason) : void 0,
+    async *stream(input, context) {
+      const base = input.messages ?? (input.message ? [{ role: "user", content: input.message }] : []);
+      const messages = base[0]?.role === "system" ? base : [{ role: "system", content: systemPrompt }, ...base];
+      for await (const event of inner.stream({ ...input, messages }, context)) {
+        if (counter && event.type === "llm_call") {
+          counter.tokensIn += event.tokensIn ?? 0;
+          counter.tokensOut += event.tokensOut ?? 0;
+          counter.costUsd += event.costUsd ?? 0;
+        }
+        yield event;
+      }
+    }
+  };
+}
+function scriptedPersonaBackend(turns) {
+  let idx = 0;
+  return createIterableBackend({
+    kind: "persona-user",
+    async *stream(_input, context) {
+      const text = turns[idx];
+      if (text === void 0) {
+        throw new Error(
+          `persona-user: ran out of scripted turns at index ${idx} (had ${turns.length})`
+        );
+      }
+      idx += 1;
+      yield {
+        type: "text_delta",
+        task: context.task,
+        session: context.session,
+        text,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+  });
+}
+async function runPersonaConversation(opts) {
+  const counter = { tokensIn: 0, tokensOut: 0, costUsd: 0 };
+  const workerName = opts.workerName ?? "agent";
+  const worker = withProfilePrompt(
+    opts.backendFor(opts.worker, "worker"),
+    opts.systemPromptOf(opts.worker),
+    counter
+  );
+  let persona;
+  let maxTurns;
+  if (opts.persona.kind === "scripted") {
+    if (opts.persona.turns.length === 0) {
+      throw new Error("runPersonaConversation: scripted persona has no turns");
+    }
+    persona = scriptedPersonaBackend(opts.persona.turns);
+    maxTurns = opts.maxTurns ?? 2 * opts.persona.turns.length;
+  } else {
+    persona = withProfilePrompt(
+      opts.backendFor(opts.persona.profile, "persona"),
+      opts.systemPromptOf(opts.persona.profile)
+    );
+    if (opts.maxTurns === void 0) {
+      throw new Error("runPersonaConversation: maxTurns is required for a profile-driven persona");
+    }
+    maxTurns = opts.maxTurns;
+  }
+  const conversation = defineConversation({
+    // Persona leads (participant 0): the seed routes to it, it produces the
+    // user turn, the worker answers, alternate.
+    participants: [
+      { name: "user", backend: persona },
+      { name: workerName, backend: worker }
+    ],
+    policy: { maxTurns, turnOrder: "alternate", ...opts.haltOn ? { haltOn: opts.haltOn } : {} }
+  });
+  const result = await runConversation(conversation, {
+    seed: opts.seed ?? "Begin.",
+    signal: opts.signal
+  });
+  const costUsd = counter.costUsd > 0 ? counter.costUsd : opts.persona.kind === "scripted" ? result.spentCreditsCents / 100 : 0;
+  return {
+    transcript: result.transcript,
+    turns: result.turns,
+    halted: result.halted,
+    costUsd,
+    tokensIn: counter.tokensIn,
+    tokensOut: counter.tokensOut
+  };
+}
+function runPersonaDispatch(config) {
+  return async (worker, scenario, ctx) => {
+    const result = await runPersonaConversation({
+      worker,
+      persona: config.personaOf(scenario),
+      backendFor: config.backendFor,
+      systemPromptOf: config.systemPromptOf,
+      maxTurns: config.maxTurns?.(scenario),
+      seed: config.seed?.(scenario),
+      signal: ctx.signal,
+      workerName: config.workerName
+    });
+    ctx.cost.observe(result.costUsd, "persona-conversation");
+    ctx.cost.observeTokens({ input: result.tokensIn, output: result.tokensOut });
+    return config.artifactOf(result.transcript, scenario);
+  };
+}
+
+// src/conversation/eval-persona.ts
+function evalPersona(worker, persona, opts = {}) {
+  const defaultBackendFor = () => {
+    if (!opts.apiKey || !opts.baseUrl || !opts.model) {
+      throw new Error(
+        "evalPersona: provide opts.{apiKey,baseUrl,model} for the default backend, or opts.backendFor"
+      );
+    }
+    const { apiKey, baseUrl, model } = opts;
+    return () => createOpenAICompatibleBackend({ apiKey, baseUrl, model });
+  };
+  const backendFor = opts.backendFor ?? defaultBackendFor();
+  const systemPromptOf = opts.systemPromptOf ?? ((p) => p.prompt?.systemPrompt ?? "");
+  return runPersonaConversation({
+    // runPersonaConversation types its profile as the benchmark-cell AgentProfile; here it is the
+    // authored AgentProfile (the carrier of prompt.systemPrompt). The runner never inspects the
+    // profile itself — only backendFor/systemPromptOf do, and both are typed for THIS profile — so
+    // the cast at this single boundary is sound.
+    worker,
+    persona,
+    backendFor,
+    systemPromptOf,
+    ...opts.maxTurns !== void 0 ? { maxTurns: opts.maxTurns } : {},
+    ...opts.haltOn ? { haltOn: opts.haltOn } : {},
+    ...opts.seed !== void 0 ? { seed: opts.seed } : {},
+    ...opts.signal ? { signal: opts.signal } : {},
+    ...opts.workerName !== void 0 ? { workerName: opts.workerName } : {}
+  });
+}
+
 // src/conversation/journal.ts
 var InMemoryConversationJournal = class {
   entries = /* @__PURE__ */ new Map();
@@ -1673,116 +1811,6 @@ var SqlConversationJournal = class {
   }
 };
 
-// src/conversation/run-persona.ts
-function withProfilePrompt(inner, systemPrompt, counter) {
-  return {
-    kind: inner.kind,
-    start: inner.start ? (input, ctx) => inner.start(input, ctx) : void 0,
-    resume: inner.resume ? (session, input, ctx) => inner.resume(session, input, ctx) : void 0,
-    stop: inner.stop ? (session, reason) => inner.stop(session, reason) : void 0,
-    async *stream(input, context) {
-      const base = input.messages ?? (input.message ? [{ role: "user", content: input.message }] : []);
-      const messages = base[0]?.role === "system" ? base : [{ role: "system", content: systemPrompt }, ...base];
-      for await (const event of inner.stream({ ...input, messages }, context)) {
-        if (counter && event.type === "llm_call") {
-          counter.tokensIn += event.tokensIn ?? 0;
-          counter.tokensOut += event.tokensOut ?? 0;
-          counter.costUsd += event.costUsd ?? 0;
-        }
-        yield event;
-      }
-    }
-  };
-}
-function scriptedPersonaBackend(turns) {
-  let idx = 0;
-  return createIterableBackend({
-    kind: "persona-user",
-    async *stream(_input, context) {
-      const text = turns[idx];
-      if (text === void 0) {
-        throw new Error(
-          `persona-user: ran out of scripted turns at index ${idx} (had ${turns.length})`
-        );
-      }
-      idx += 1;
-      yield {
-        type: "text_delta",
-        task: context.task,
-        session: context.session,
-        text,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      };
-    }
-  });
-}
-async function runPersonaConversation(opts) {
-  const counter = { tokensIn: 0, tokensOut: 0, costUsd: 0 };
-  const workerName = opts.workerName ?? "agent";
-  const worker = withProfilePrompt(
-    opts.backendFor(opts.worker, "worker"),
-    opts.systemPromptOf(opts.worker),
-    counter
-  );
-  let persona;
-  let maxTurns;
-  if (opts.persona.kind === "scripted") {
-    if (opts.persona.turns.length === 0) {
-      throw new Error("runPersonaConversation: scripted persona has no turns");
-    }
-    persona = scriptedPersonaBackend(opts.persona.turns);
-    maxTurns = opts.maxTurns ?? 2 * opts.persona.turns.length;
-  } else {
-    persona = withProfilePrompt(
-      opts.backendFor(opts.persona.profile, "persona"),
-      opts.systemPromptOf(opts.persona.profile)
-    );
-    if (opts.maxTurns === void 0) {
-      throw new Error("runPersonaConversation: maxTurns is required for a profile-driven persona");
-    }
-    maxTurns = opts.maxTurns;
-  }
-  const conversation = defineConversation({
-    // Persona leads (participant 0): the seed routes to it, it produces the
-    // user turn, the worker answers, alternate.
-    participants: [
-      { name: "user", backend: persona },
-      { name: workerName, backend: worker }
-    ],
-    policy: { maxTurns, turnOrder: "alternate" }
-  });
-  const result = await runConversation(conversation, {
-    seed: opts.seed ?? "Begin.",
-    signal: opts.signal
-  });
-  const costUsd = counter.costUsd > 0 ? counter.costUsd : opts.persona.kind === "scripted" ? result.spentCreditsCents / 100 : 0;
-  return {
-    transcript: result.transcript,
-    turns: result.turns,
-    halted: result.halted,
-    costUsd,
-    tokensIn: counter.tokensIn,
-    tokensOut: counter.tokensOut
-  };
-}
-function runPersonaDispatch(config) {
-  return async (worker, scenario, ctx) => {
-    const result = await runPersonaConversation({
-      worker,
-      persona: config.personaOf(scenario),
-      backendFor: config.backendFor,
-      systemPromptOf: config.systemPromptOf,
-      maxTurns: config.maxTurns?.(scenario),
-      seed: config.seed?.(scenario),
-      signal: ctx.signal,
-      workerName: config.workerName
-    });
-    ctx.cost.observe(result.costUsd, "persona-conversation");
-    ctx.cost.observeTokens({ input: result.tokensIn, output: result.tokensOut });
-    return config.artifactOf(result.transcript, scenario);
-  };
-}
-
 // src/durable/chat-engine.ts
 var encoder = new TextEncoder();
 function encodeLine(event) {
@@ -1869,6 +1897,427 @@ function deriveExecutionId(input) {
   return `${input.projectId}:${input.sessionId}:${input.turnIndex}`;
 }
 
+// src/improvement/agentic-generator.ts
+import { spawnSync } from "child_process";
+function agenticGenerator(opts = {}) {
+  const harness = opts.harness ?? "claude";
+  const buildPrompt = opts.buildPrompt ?? defaultBuildPrompt;
+  const run = opts.runHarness ?? runLocalHarness;
+  const dirty = opts.isDirty ?? worktreeDirty;
+  const verify = opts.verify;
+  return {
+    kind: `agentic:${harness}`,
+    async generate({ worktreePath, report, findings, maxShots, signal }) {
+      const basePrompt = buildPrompt({ report, findings });
+      const shots = Math.max(1, maxShots);
+      let attemptNote = "";
+      for (let shot = 0; shot < shots; shot++) {
+        if (signal.aborted) break;
+        await run({
+          harness,
+          cwd: worktreePath,
+          taskPrompt: attemptNote ? `${basePrompt}
+
+${attemptNote}` : basePrompt,
+          timeoutMs: opts.timeoutMs,
+          signal
+        });
+        if (!dirty(worktreePath)) {
+          attemptNote = EMPTY_TREE_NOTE;
+          continue;
+        }
+        if (!verify) {
+          return { applied: true, summary: summarize(findings) };
+        }
+        const result = await verify(worktreePath);
+        if (result.ok) {
+          return { applied: true, summary: summarize(findings) };
+        }
+        attemptNote = failureNote(result.feedback);
+      }
+      return { applied: false, summary: "" };
+    }
+  };
+}
+function defaultBuildPrompt(args) {
+  const lines = [
+    "You are improving this codebase based on an evaluation analysis.",
+    "Make the smallest set of edits that addresses the findings below, then stop.",
+    "Do not change unrelated code. Do not commit \u2014 leave changes in the working tree.",
+    "",
+    "Findings:"
+  ];
+  for (const f of args.findings) {
+    const where = f.subject ? ` [${f.subject}]` : "";
+    lines.push(`- (${f.severity})${where} ${f.claim}`);
+    if (f.recommended_action) lines.push(`    \u2192 ${f.recommended_action}`);
+  }
+  return lines.join("\n");
+}
+var EMPTY_TREE_NOTE = "NOTE: your previous attempt left the working tree unchanged. Make the concrete file edits now.";
+function failureNote(feedback) {
+  const detail = feedback?.trim();
+  return [
+    "NOTE: your edits are in the working tree but verification FAILED.",
+    "Fix the problem in place \u2014 build on your existing edits, do not revert them.",
+    detail ? `Verifier output:
+${truncate(detail, 4e3)}` : "No verifier detail was captured."
+  ].join("\n");
+}
+function commandVerifier(command, args = [], timeoutMs = 3e5) {
+  return (worktreePath) => {
+    const result = spawnSync(command, args, {
+      cwd: worktreePath,
+      encoding: "utf-8",
+      timeout: timeoutMs
+    });
+    if (result.signal) {
+      return {
+        ok: false,
+        feedback: `verifier '${command}' killed by ${result.signal} (likely timeout after ${timeoutMs}ms)`
+      };
+    }
+    if (result.error) {
+      const code = result.error.code;
+      if (code === "ENOENT") {
+        throw new Error(
+          `commandVerifier: '${command}' not found in PATH (setup bug, not a failed candidate)`
+        );
+      }
+      throw new Error(`commandVerifier: '${command}' failed to spawn: ${result.error.message}`);
+    }
+    if (result.status === 0) return { ok: true };
+    const out = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    return { ok: false, feedback: out.length > 0 ? out : `exit ${result.status}` };
+  };
+}
+function summarize(findings) {
+  if (findings.length === 0) return "agentic improvement";
+  if (findings.length === 1) return `agentic: ${truncate(findings[0].claim, 64)}`;
+  return `agentic: ${findings.length} findings addressed`;
+}
+function truncate(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
+}
+function worktreeDirty(worktreePath) {
+  const result = spawnSync("git", ["status", "--porcelain"], {
+    cwd: worktreePath,
+    encoding: "utf-8"
+  });
+  if (result.error) {
+    throw new Error(
+      `agenticGenerator: git status failed to spawn in ${worktreePath}: ${result.error.message}`
+    );
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `agenticGenerator: git status exited ${result.status} in ${worktreePath}: ${result.stderr.trim()}`
+    );
+  }
+  return result.stdout.trim().length > 0;
+}
+
+// src/improvement/build-prompts.ts
+function findingLines(findings) {
+  return findings.map((f) => {
+    const where = f.subject ? ` [${f.subject}]` : "";
+    const action = f.recommended_action ? ` \u2192 ${f.recommended_action}` : "";
+    return `- (${f.severity})${where} ${f.claim}${action}`;
+  });
+}
+function toolBuildPrompt(args) {
+  return [
+    "You are building a new TOOL for this codebase to address the gaps below.",
+    "Write the tool as a small, self-contained module PLUS tests that exercise it.",
+    "The tool must compile and its tests must pass \u2014 they will be run automatically;",
+    "if verification fails you will get the error and another attempt. Do not commit;",
+    "leave the changes in the working tree.",
+    "",
+    "Gaps the tool should close:",
+    ...findingLines(args.findings)
+  ].join("\n");
+}
+function mcpBuildPrompt(args) {
+  return [
+    "You are building a new MCP SERVER (Model Context Protocol) that exposes",
+    "tool(s) addressing the gaps below, so any harness can mount it.",
+    "Requirements that WILL be checked by booting the server:",
+    "- it starts over stdio and answers the MCP `initialize` handshake,",
+    "- `tools/list` returns at least one tool with a valid input schema.",
+    "Newline-delimited JSON-RPC 2.0, protocol version 2024-11-05. Include a start",
+    "command (e.g. a package.json `start` script or a clear entrypoint). If the",
+    "boot-and-probe fails you will get the error and another attempt. Do not",
+    "commit; leave the changes in the working tree.",
+    "",
+    "Capabilities the server should provide:",
+    ...findingLines(args.findings)
+  ].join("\n");
+}
+
+// src/improvement/improve.ts
+import { skillOptProposer } from "@tangle-network/agent-eval/campaign";
+import {
+  gepaProposer,
+  selfImprove
+} from "@tangle-network/agent-eval/contract";
+var defaultReflectionModel = "deepseek-v4-flash";
+function llmClientOptions(llm) {
+  return { baseUrl: llm?.baseUrl, apiKey: llm?.apiKey };
+}
+function defaultGeneratorFor(surface, llm) {
+  const model = llm?.model ?? defaultReflectionModel;
+  switch (surface) {
+    case "prompt":
+      return gepaProposer({ llm: llmClientOptions(llm), model, target: "agent system prompt" });
+    case "skills":
+      return skillOptProposer({ llm: llmClientOptions(llm), model, target: "agent skill document" });
+    default:
+      return void 0;
+  }
+}
+function baselineSurfaceFor(profile, surface) {
+  switch (surface) {
+    case "prompt":
+      return profile.prompt?.systemPrompt ?? "";
+    case "skills":
+      return JSON.stringify(profile.resources?.skills ?? []);
+    case "tools":
+      return JSON.stringify(profile.tools ?? {});
+    case "mcp":
+      return JSON.stringify(profile.mcp ?? {});
+    case "hooks":
+      return JSON.stringify(profile.hooks ?? {});
+    case "code":
+      return "";
+  }
+}
+function parseWinnerJson(winner, surface) {
+  try {
+    return JSON.parse(winner);
+  } catch (cause) {
+    throw new ConfigError(
+      `improve(): the shipped '${surface}' winner is not valid JSON, so it cannot be applied back to the profile: ${cause.message}`
+    );
+  }
+}
+function applyWinnerToProfile(profile, surface, winner) {
+  if (typeof winner !== "string") return profile;
+  switch (surface) {
+    case "prompt":
+      return { ...profile, prompt: { ...profile.prompt, systemPrompt: winner } };
+    case "skills":
+      return {
+        ...profile,
+        resources: { ...profile.resources, skills: parseWinnerJson(winner, surface) }
+      };
+    case "tools":
+      return { ...profile, tools: parseWinnerJson(winner, surface) };
+    case "mcp":
+      return { ...profile, mcp: parseWinnerJson(winner, surface) };
+    case "hooks":
+      return { ...profile, hooks: parseWinnerJson(winner, surface) };
+    case "code":
+      return profile;
+  }
+}
+async function improve(profile, findings, opts) {
+  const surface = opts.surface ?? "prompt";
+  const gate = opts.gate ?? "holdout";
+  assertModelAllowed(opts.llm?.model ?? defaultReflectionModel, opts.allowedModels);
+  const proposer = opts.generator ?? defaultGeneratorFor(surface, opts.llm);
+  if (!proposer) {
+    throw new ConfigError(
+      `improve(): surface '${surface}' has no default generator \u2014 pass opts.generator (a SurfaceProposer) explicitly`
+    );
+  }
+  const budget = gate === "none" ? { ...opts.budget, generations: 0 } : { ...opts.budget };
+  const raw = await selfImprove({
+    agent: opts.agent,
+    scenarios: opts.scenarios,
+    judge: opts.judge,
+    baselineSurface: baselineSurfaceFor(profile, surface),
+    proposer,
+    budget,
+    llm: opts.llm,
+    findings
+  });
+  const shipped = raw.gateDecision === "ship";
+  const nextProfile = shipped ? applyWinnerToProfile(profile, surface, raw.winner.surface) : profile;
+  return { profile: nextProfile, shipped, lift: raw.lift, gateDecision: raw.gateDecision, raw };
+}
+
+// src/improvement/improvement-driver.ts
+function improvementDriver(opts) {
+  const baseRef = opts.baseRef ?? "main";
+  return {
+    kind: `improvement:${opts.generator.kind}`,
+    async propose(ctx) {
+      const findings = resolveFindings(ctx);
+      if (findings.length === 0 && ctx.report === void 0) return [];
+      const surfaces = [];
+      for (let i = 0; i < ctx.populationSize; i++) {
+        if (ctx.signal.aborted) break;
+        const wt = await opts.worktree.create({
+          baseRef,
+          label: `${opts.generator.kind}-gen${ctx.generation}-cand${i}`
+        });
+        try {
+          const { applied, summary } = await opts.generator.generate({
+            worktreePath: wt.path,
+            report: ctx.report,
+            findings,
+            dataset: ctx.dataset,
+            maxShots: ctx.maxImprovementShots ?? 1,
+            signal: ctx.signal
+          });
+          if (!applied) {
+            await opts.worktree.discard(wt);
+            continue;
+          }
+          surfaces.push(await opts.worktree.finalize(wt, summary));
+        } catch (err) {
+          await opts.worktree.discard(wt).catch(() => {
+          });
+          throw err;
+        }
+      }
+      return surfaces;
+    }
+  };
+}
+function resolveFindings(ctx) {
+  const report = ctx.report;
+  if (report && typeof report === "object" && "findings" in report) {
+    const f = report.findings;
+    if (Array.isArray(f) && f.length > 0) return f;
+  }
+  return ctx.findings;
+}
+
+// src/improvement/mcp-serve-verifier.ts
+import { spawn } from "child_process";
+import { createInterface } from "readline";
+var PROTOCOL_VERSION = "2024-11-05";
+function mcpServeVerifier(spec) {
+  const timeoutMs = spec.timeoutMs ?? 3e4;
+  const minTools = spec.minTools ?? 1;
+  return (worktreePath) => new Promise((resolve, reject) => {
+    const child = spawn(spec.command, spec.args ?? [], {
+      cwd: worktreePath,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...spec.env }
+    });
+    const stderr = [];
+    let settled = false;
+    let nextId = 1;
+    const initId = nextId++;
+    let listId = -1;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rl.close();
+      child.kill("SIGKILL");
+      fn();
+    };
+    const withStderr = (msg) => stderr.length > 0 ? `${msg}
+stderr:
+${stderr.join("").slice(-2e3)}` : msg;
+    const pass = () => settle(() => resolve({ ok: true }));
+    const failCandidate = (msg) => settle(() => resolve({ ok: false, feedback: withStderr(msg) }));
+    const setupFault = (err) => settle(() => reject(err));
+    const send = (msg) => {
+      try {
+        child.stdin.write(`${JSON.stringify(msg)}
+`);
+        return true;
+      } catch (err) {
+        failCandidate(`writing to MCP server stdin failed: ${err.message}`);
+        return false;
+      }
+    };
+    child.on("error", (err) => {
+      const code = err.code;
+      setupFault(
+        code === "ENOENT" ? new Error(
+          `mcpServeVerifier: '${spec.command}' not found in PATH (setup bug, not a failed candidate)`
+        ) : new Error(`mcpServeVerifier: '${spec.command}' failed to spawn: ${err.message}`)
+      );
+    });
+    child.on("exit", (code, signal) => {
+      failCandidate(`MCP server exited (code ${code}, signal ${signal}) before serving`);
+    });
+    child.stderr.on("data", (d) => stderr.push(String(d)));
+    const rl = createInterface({ input: child.stdout });
+    rl.on("line", (line) => {
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg !== "object") return;
+      if (msg.id === initId) {
+        if (msg.error) return failCandidate(`initialize errored: ${JSON.stringify(msg.error)}`);
+        if (!send({ jsonrpc: "2.0", method: "notifications/initialized" })) return;
+        listId = nextId++;
+        send({ jsonrpc: "2.0", id: listId, method: "tools/list" });
+        return;
+      }
+      if (msg.id === listId) {
+        if (msg.error) return failCandidate(`tools/list errored: ${JSON.stringify(msg.error)}`);
+        const tools = msg.result?.tools;
+        if (!Array.isArray(tools)) return failCandidate("tools/list result has no tools array");
+        if (tools.length < minTools) {
+          return failCandidate(`tools/list returned ${tools.length} tool(s), need >= ${minTools}`);
+        }
+        return pass();
+      }
+    });
+    const timer = setTimeout(
+      () => failCandidate(`MCP server did not complete the handshake within ${timeoutMs}ms`),
+      timeoutMs
+    );
+    send({
+      jsonrpc: "2.0",
+      id: initId,
+      method: "initialize",
+      params: {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "agent-runtime-mcp-verify", version: "0" }
+      }
+    });
+  });
+}
+
+// src/improvement/reflective-generator.ts
+import { spawnSync as spawnSync2 } from "child_process";
+function reflectiveGenerator(opts) {
+  return {
+    kind: "reflective",
+    async generate({ worktreePath, findings }) {
+      const batch = await opts.improvementAdapter.proposeFromFindings(findings);
+      if (batch.edits.length === 0) return { applied: false, summary: "" };
+      let applied = 0;
+      for (const edit of batch.edits) {
+        if (applyPatch(edit.patch, worktreePath)) applied++;
+      }
+      if (applied === 0) return { applied: false, summary: "" };
+      const summary = batch.edits.length === 1 ? batch.edits[0].summary : `analyst: ${applied} surface edit${applied === 1 ? "" : "s"}`;
+      return { applied: true, summary };
+    }
+  };
+}
+function applyPatch(patch, cwd) {
+  const result = spawnSync2("git", ["apply", "--whitespace=fix", "-p0", "-"], {
+    cwd,
+    input: patch,
+    encoding: "utf-8"
+  });
+  return result.status === 0;
+}
+
 // src/readiness.ts
 var DEFAULT_MINIMUM_READINESS_SCORE = 0.7;
 function decideKnowledgeReadiness(report, options = {}) {
@@ -3292,6 +3741,7 @@ export {
   RuntimeRunStateError,
   SqlConversationJournal,
   ValidationError,
+  agenticGenerator,
   applyRunRecordDefaults,
   auditLoopRunner,
   buildForwardHeaders,
@@ -3299,6 +3749,7 @@ export {
   buildLoopSpanNodes,
   cleanModelId,
   coderLoopRunner,
+  commandVerifier,
   composeRuntimeHooks,
   computeBackoff,
   createConversationBackend,
@@ -3314,13 +3765,18 @@ export {
   defineConversation,
   defineRuntimeHooks,
   deriveExecutionId,
+  evalPersona,
   exportEvalRuns,
   getModels,
   handleChatTurn,
+  improve,
+  improvementDriver,
   isDelegatedLoopMode,
   isDepthExceeded,
   loopEventToOtelSpan,
   makePerAttemptSignal,
+  mcpBuildPrompt,
+  mcpServeVerifier,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset,
   notifyRuntimeDecisionPoint,
@@ -3328,6 +3784,7 @@ export {
   parseLoopRunnerArgv,
   readDepth,
   readinessServerSentEvent,
+  reflectiveGenerator,
   researchLoopRunner,
   resolveChatModel,
   resolveRouterBaseUrl,
@@ -3349,6 +3806,7 @@ export {
   slugifySpeaker,
   startRuntimeRun,
   streamToolLoop,
+  toolBuildPrompt,
   turnId,
   validateChatModelId,
   worktreeLoopRunner