@tangle-network/agent-runtime 0.89.0 → 0.90.1

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset
-} from "./chunk-5AVV7KAH.js";
+} from "./chunk-QK4DV5PR.js";
 import {
   DEFAULT_ROUTER_BASE_URL,
   cleanModelId,
@@ -20,25 +20,45 @@ import {
   runLoopRunnerCli,
   selfImproveLoopRunner,
   worktreeLoopRunner
-} from "./chunk-BQPFZE2C.js";
+} from "./chunk-WRUSWK4F.js";
 import "./chunk-SGKPNBXE.js";
 import {
   InMemoryRuntimeSessionStore,
   createIterableBackend,
   createOpenAICompatibleBackend,
   createSandboxPromptBackend,
+  defaultStructuralRolloutPolicy,
   newRuntimeSession,
   normalizeBackendStreamEvent,
   nowIso,
   touchSession
-} from "./chunk-PIPPLSOF.js";
+} from "./chunk-ZV4LXYCJ.js";
+import "./chunk-ZQZX77MM.js";
+import {
+  agenticGenerator,
+  commandVerifier,
+  mcpBuildPrompt,
+  mcpServeVerifier,
+  toolBuildPrompt
+} from "./chunk-OOL3675H.js";
+import {
+  RESEARCH_SUPERVISOR_SYSTEM_PROMPT,
+  createAgentKnowledgeReadinessCheck,
+  createSupervisedKnowledgeUpdater,
+  formatSupervisedKnowledgeTask,
+  knowledgeReadinessDeliverable,
+  runKnowledgeImprovementJob,
+  runSupervisedKnowledgeUpdate
+} from "./chunk-R2VAJGR3.js";
+import "./chunk-5QOB7H74.js";
 import {
   assertModelAllowed,
   composeRuntimeHooks,
   defineRuntimeHooks,
   notifyRuntimeDecisionPoint,
   notifyRuntimeHookEvent
-} from "./chunk-N7EJV7N3.js";
+} from "./chunk-RYBVU4M3.js";
+import "./chunk-DPEUKJRO.js";
 import {
   INTELLIGENCE_WIRE_VERSION,
   buildLoopOtelSpans,
@@ -46,18 +66,10 @@ import {
   createOtelExporter,
   exportEvalRuns,
   loopEventToOtelSpan
-} from "./chunk-UD4BHQMI.js";
+} from "./chunk-IVGYLCFH.js";
 import "./chunk-BZF3KQ6G.js";
-import "./chunk-ZQZX77MM.js";
 import "./chunk-FVJ7M3DA.js";
-import {
-  agenticGenerator,
-  commandVerifier,
-  mcpBuildPrompt,
-  mcpServeVerifier,
-  toolBuildPrompt
-} from "./chunk-VNOOH22O.js";
-import "./chunk-7LO5GMAO.js";
+import "./chunk-CMYMTRGA.js";
 import {
   AgentEvalError,
   BackendTransportError,
@@ -69,7 +81,6 @@ import {
   SessionMismatchError,
   ValidationError
 } from "./chunk-YEJR7IXO.js";
-import "./chunk-DPEUKJRO.js";
 import "./chunk-DGUM43GV.js";
 
 // src/conversation/call-policy.ts
@@ -171,7 +182,7 @@ function computeBackoff(spec, attempt) {
   return Math.max(0, spec);
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 
 // src/conversation/headers.ts
@@ -1272,10 +1283,353 @@ function deriveExecutionId(input) {
 }
 
 // src/improvement/improve.ts
-import { gepaProposer, skillOptProposer } from "@tangle-network/agent-eval/campaign";
+import {
+  gepaProposer,
+  gitWorktreeAdapter,
+  skillOptProposer
+} from "@tangle-network/agent-eval/campaign";
 import {
   selfImprove
 } from "@tangle-network/agent-eval/contract";
+
+// 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 && !opts.generator.proposesWithoutFindings) {
+        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/raw-trace-distiller.ts
+import { existsSync, readdirSync } from "fs";
+import { basename, join, resolve } from "path";
+import { makeFinding } from "@tangle-network/agent-eval";
+var ANALYST_ID = "raw-trace-distiller";
+var PASS_THRESHOLD = 0.999;
+function rawTraceDistiller(options = {}) {
+  const maxCandidates = options.maxCandidates ?? 12;
+  const maxCellsPerCandidate = options.maxCellsPerCandidate ?? 8;
+  const maxFilesPerCell = options.maxFilesPerCell ?? 24;
+  return async (input) => {
+    const genRoot = absoluteRunDir(options.runDir ?? input.runDir);
+    const durable = isDurable(genRoot);
+    const ranked = [...input.candidates].map((c) => ({
+      surfaceHash: c.surfaceHash,
+      composite: c.composite,
+      campaignDir: absoluteRunDir(c.campaign.runDir),
+      cells: failingCells(c.campaign, maxCellsPerCandidate, maxFilesPerCell)
+    })).sort((a, b) => a.composite - b.composite).slice(0, maxCandidates);
+    const totalFailingCells = ranked.reduce((n, c) => n + c.cells.length, 0);
+    if (totalFailingCells === 0) {
+      if (options.fallbackFindings && options.fallbackFindings.length > 0) {
+        return options.fallbackFindings;
+      }
+      return [
+        makeFinding({
+          analyst_id: ANALYST_ID,
+          severity: "info",
+          area: "raw-trace-context",
+          confidence: 1,
+          claim: `Generation ${input.generation} had no failing cells. The full raw run traces are on disk under ${genRoot}.`,
+          recommended_action: `To keep improving, grep/cat the raw traces under ${genRoot} (per-cell spans.jsonl + cached-result.json) to find the weakest passing runs, then make a targeted harness-code edit.`,
+          evidence_refs: [{ kind: "artifact", uri: genRoot }],
+          metadata: { generation: input.generation, runDir: genRoot, failingCells: 0 }
+        })
+      ];
+    }
+    const findings = [];
+    findings.push(
+      makeFinding({
+        analyst_id: ANALYST_ID,
+        severity: "high",
+        area: "raw-trace-context",
+        confidence: 1,
+        claim: `Generation ${input.generation} produced ${totalFailingCells} failing/low-scoring cell(s) across ${ranked.length} candidate(s). Their FULL RAW run traces are on disk under ${genRoot} \u2014 the actual event logs (spans.jsonl), scores (cached-result.json), and artifacts, not a summary.${durable ? "" : " (WARNING: this run root does not exist on disk \u2014 it looks like an in-memory run; pass a real runDir to improve() to get raw-trace context.)"}`,
+        recommended_action: `Do NOT rely on a pre-summarized finding. Before editing, DIAGNOSE from the raw traces: run \`grep\`/\`cat\`/\`ls\` over the trace files and directories named in the following findings to see exactly what each failing run did and why it scored low, then make the smallest harness-code edit that fixes the dominant failure. Start with \`grep -rIn "error" ${genRoot}\` then \`cat\` the spans.jsonl of the worst cell.`,
+        evidence_refs: [{ kind: "artifact", uri: genRoot }],
+        metadata: {
+          generation: input.generation,
+          runDir: genRoot,
+          failingCells: totalFailingCells,
+          candidates: ranked.length
+        }
+      })
+    );
+    for (const cand of ranked) {
+      if (cand.cells.length === 0) continue;
+      const scenarioList = cand.cells.map((c) => c.scenarioId).join(", ");
+      const fileLines = cand.cells.map((c) => {
+        const header = `  cell ${c.scenarioId} (composite ${c.composite.toFixed(3)}${c.error ? `, error: ${truncate(c.error, 160)}` : ""}) \u2014 dir ${c.cellDir}`;
+        const files = c.files.map((f) => `    - ${f}`).join("\n");
+        const more = c.truncatedFiles ? `
+    - \u2026(ls ${c.cellDir} for the rest)` : "";
+        return c.files.length > 0 ? `${header}
+${files}${more}` : header;
+      }).join("\n");
+      findings.push(
+        makeFinding({
+          analyst_id: ANALYST_ID,
+          severity: cand.composite < 0.5 ? "critical" : "high",
+          area: "raw-trace-context",
+          confidence: 1,
+          subject: cand.surfaceHash,
+          claim: `Candidate ${cand.surfaceHash} scored composite ${cand.composite.toFixed(3)} with ${cand.cells.length} failing cell(s) [${scenarioList}]. Its raw traces are under ${cand.campaignDir}.`,
+          recommended_action: `grep/cat these raw trace files to diagnose WHY this candidate failed before editing:
+${fileLines}
+Or scan the whole candidate at once: \`grep -rIn . ${cand.campaignDir}\` and \`ls -R ${cand.campaignDir}\`.`,
+          evidence_refs: [
+            { kind: "artifact", uri: cand.campaignDir },
+            ...cand.cells.flatMap(
+              (c) => c.files.map((f) => ({ kind: "artifact", uri: f }))
+            )
+          ],
+          metadata: {
+            surfaceHash: cand.surfaceHash,
+            composite: cand.composite,
+            campaignDir: cand.campaignDir,
+            cells: cand.cells.map((c) => ({
+              scenarioId: c.scenarioId,
+              composite: c.composite,
+              cellDir: c.cellDir,
+              files: c.files,
+              ...c.error ? { error: c.error } : {}
+            }))
+          }
+        })
+      );
+    }
+    return findings;
+  };
+}
+function failingCells(campaign, maxCells, maxFiles) {
+  const campaignDir = absoluteRunDir(campaign.runDir);
+  const durable = isDurable(campaignDir);
+  const out = [];
+  for (const cell of campaign.cells) {
+    const scores = Object.values(cell.judgeScores ?? {});
+    const composite = scores.length === 0 ? 0 : scores.reduce((sum, s) => sum + (s.composite ?? 0), 0) / scores.length;
+    if (!cell.error && composite >= PASS_THRESHOLD) continue;
+    const cellDir = join(campaignDir, sanitizeCellId(cell.cellId));
+    const artifactPaths = artifactPathsForCell(campaign.artifactsByPath, cell.cellId);
+    const discovered = durable ? listTraceFiles(cellDir) : [];
+    const canonical = [join(cellDir, "spans.jsonl"), join(cellDir, "cached-result.json")];
+    const files = dedupeSorted([...discovered, ...artifactPaths, ...canonical]);
+    out.push({
+      scenarioId: cell.scenarioId,
+      composite: Number(composite.toFixed(3)),
+      ...cell.error ? { error: cell.error } : {},
+      cellDir,
+      files: files.slice(0, maxFiles),
+      truncatedFiles: files.length > maxFiles
+    });
+    if (out.length >= maxCells) break;
+  }
+  return out;
+}
+function artifactPathsForCell(artifactsByPath, cellId) {
+  if (!artifactsByPath) return [];
+  const prefix = `${cellId}/`;
+  return Object.entries(artifactsByPath).filter(([key]) => key.startsWith(prefix)).map(([, absPath]) => resolve(absPath));
+}
+function listTraceFiles(dir) {
+  const out = [];
+  for (const entry of safeReadDir(dir)) {
+    const full = join(dir, entry.name);
+    if (entry.isFile()) {
+      out.push(full);
+    } else if (!entry.isSymbolicLink() && entry.isDirectory()) {
+      for (const sub of safeReadDir(full)) {
+        if (sub.isFile()) out.push(join(full, sub.name));
+      }
+    }
+  }
+  return out;
+}
+function safeReadDir(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+function sanitizeCellId(cellId) {
+  return cellId.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function isDurable(runDir) {
+  return !runDir.startsWith("mem://") && existsSync(runDir);
+}
+function absoluteRunDir(runDir) {
+  return runDir.startsWith("mem://") ? runDir : resolve(runDir);
+}
+function dedupeSorted(paths) {
+  return [...new Set(paths)].sort((a, b) => {
+    const da = a.slice(0, a.length - basename(a).length);
+    const db = b.slice(0, b.length - basename(b).length);
+    return da === db ? basename(a).localeCompare(basename(b)) : da.localeCompare(db);
+  });
+}
+function truncate(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
+}
+
+// src/improvement/rollout-policy.ts
+var ROLLOUT_POLICY_EXTENSION = "structural-rollout";
+var ROLLOUT_POLICY_BOUNDS = {
+  k: { min: 1, max: 10, step: 2 },
+  repairRounds: { min: 0, max: 3, step: 1 },
+  testgen: { min: 0, max: 10, step: 3 }
+};
+var MAX_CANDIDATES_PER_GENERATION = 4;
+var clamp = (v, min, max) => Math.min(max, Math.max(min, v));
+var isBoundedInt = (v, min) => typeof v === "number" && Number.isInteger(v) && v >= min;
+function parseRolloutPolicy(surface) {
+  if (typeof surface !== "string" || surface.trim().length === 0) return void 0;
+  let raw;
+  try {
+    raw = JSON.parse(surface);
+  } catch {
+    return void 0;
+  }
+  return normalizeRolloutPolicy(raw);
+}
+function normalizeRolloutPolicy(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return void 0;
+  const bag = raw;
+  const k = bag.k ?? defaultStructuralRolloutPolicy.k;
+  const repairRounds = bag.repairRounds ?? defaultStructuralRolloutPolicy.repairRounds;
+  const testgen = bag.testgen ?? defaultStructuralRolloutPolicy.testgen;
+  if (!isBoundedInt(k, 1) || !isBoundedInt(repairRounds, 0) || !isBoundedInt(testgen, 0)) {
+    return void 0;
+  }
+  return {
+    k,
+    repairRounds,
+    testgen,
+    ...typeof bag.diverse === "boolean" ? { diverse: bag.diverse } : {},
+    ...typeof bag.temperature === "number" ? { temperature: bag.temperature } : {}
+  };
+}
+function serializeRolloutPolicy(policy) {
+  return JSON.stringify({
+    k: policy.k,
+    repairRounds: policy.repairRounds,
+    testgen: policy.testgen,
+    ...policy.diverse !== void 0 ? { diverse: policy.diverse } : {},
+    ...policy.temperature !== void 0 ? { temperature: policy.temperature } : {}
+  });
+}
+function structuralRolloutPolicyFromProfile(profile) {
+  const bag = profile.extensions?.[ROLLOUT_POLICY_EXTENSION];
+  if (bag === void 0) return void 0;
+  return normalizeRolloutPolicy(bag);
+}
+function applyRolloutPolicyToProfile(profile, policy) {
+  const bag = {
+    k: policy.k,
+    repairRounds: policy.repairRounds,
+    testgen: policy.testgen,
+    ...policy.diverse !== void 0 ? { diverse: policy.diverse } : {},
+    ...policy.temperature !== void 0 ? { temperature: policy.temperature } : {}
+  };
+  return {
+    ...profile,
+    extensions: { ...profile.extensions, [ROLLOUT_POLICY_EXTENSION]: bag }
+  };
+}
+function enumerateNeighborPolicies(policy) {
+  const moves = [
+    { dial: "k", delta: 1 },
+    { dial: "k", delta: -1 },
+    { dial: "repairRounds", delta: 1 },
+    { dial: "repairRounds", delta: -1 },
+    { dial: "testgen", delta: 1 },
+    { dial: "testgen", delta: -1 }
+  ];
+  const seen = /* @__PURE__ */ new Set([serializeRolloutPolicy(policy)]);
+  const neighbors = [];
+  for (const move of moves) {
+    const bounds = ROLLOUT_POLICY_BOUNDS[move.dial];
+    const next = clamp(policy[move.dial] + move.delta * bounds.step, bounds.min, bounds.max);
+    const candidate = { ...policy, [move.dial]: next };
+    const key = serializeRolloutPolicy(candidate);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    neighbors.push(candidate);
+  }
+  return neighbors;
+}
+function candidateLabel(base, next) {
+  for (const dial of ["k", "repairRounds", "testgen"]) {
+    if (next[dial] !== base[dial]) return `${dial} ${base[dial]}\u2192${next[dial]}`;
+  }
+  return "unchanged";
+}
+function rolloutPolicyProposer() {
+  return {
+    kind: "rollout-policy",
+    async propose(ctx) {
+      const policy = parseRolloutPolicy(ctx.currentSurface);
+      if (!policy) return [];
+      const neighbors = enumerateNeighborPolicies(policy);
+      if (neighbors.length === 0) return [];
+      const cap = Math.max(1, Math.min(ctx.populationSize, MAX_CANDIDATES_PER_GENERATION));
+      const start = ctx.generation * cap % neighbors.length;
+      const window = [];
+      for (let i = 0; i < Math.min(cap, neighbors.length); i += 1) {
+        window.push(neighbors[(start + i) % neighbors.length]);
+      }
+      return window.map((candidate) => ({
+        surface: serializeRolloutPolicy(candidate),
+        label: candidateLabel(policy, candidate),
+        rationale: "bounded single-dial neighbor of the current structuralRollout policy; the held-out gate decides (deterministic enumeration \u2014 the dial space is tiny and prompt-style reflective proposals are a measured zero here)"
+      }));
+    }
+  };
+}
+
+// src/improvement/improve.ts
 var defaultReflectionModel = "deepseek-v4-flash";
 function llmClientOptions(llm) {
   return { baseUrl: llm?.baseUrl, apiKey: llm?.apiKey };
@@ -1287,26 +1641,76 @@ function defaultGeneratorFor(surface, llm) {
       return gepaProposer({ llm: llmClientOptions(llm), model, target: "agent system prompt" });
     case "skills":
       return skillOptProposer({ llm: llmClientOptions(llm), model, target: "agent skill document" });
+    case "rollout-policy":
+      return rolloutPolicyProposer();
     default:
       return void 0;
   }
 }
-function baselineSurfaceFor(profile, surface) {
+function baselineSurfaceFor(profile, surface, skills) {
   switch (surface) {
     case "prompt":
       return profile.prompt?.systemPrompt ?? "";
     case "skills":
-      return JSON.stringify(profile.resources?.skills ?? []);
+      return skills?.document ?? 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 "rollout-policy": {
+      const policy = structuralRolloutPolicyFromProfile(profile);
+      return policy ? serializeRolloutPolicy(policy) : "";
+    }
     case "code":
       return "";
   }
 }
+function generationFailureDistiller(staticFindings) {
+  const CAP = 12;
+  return async (input) => {
+    const failures = [];
+    for (const candidate of input.candidates) {
+      for (const rawCell of candidate.campaign.cells) {
+        const cell = rawCell;
+        const scenario = String(cell.scenarioId ?? "unknown");
+        const error = typeof cell.error === "string" ? cell.error : void 0;
+        const judgeScores = cell.judgeScores && typeof cell.judgeScores === "object" ? Object.values(
+          cell.judgeScores
+        ) : [];
+        const composite = judgeScores.length === 0 ? 0 : judgeScores.reduce((sum, j) => sum + (j.composite ?? 0), 0) / judgeScores.length;
+        if (!error && composite >= 0.999) continue;
+        const notes = judgeScores.map((j) => j.notes).filter((n) => typeof n === "string" && n.length > 0).join("; ").slice(0, 400);
+        failures.push({
+          scenario,
+          composite: Number(composite.toFixed(3)),
+          notes,
+          ...error ? { error: error.slice(0, 200) } : {}
+        });
+      }
+    }
+    if (failures.length === 0) return staticFindings;
+    failures.sort((a, b) => a.composite - b.composite);
+    return failures.slice(0, CAP);
+  };
+}
+function codeProposerFor(surface, code) {
+  if (surface !== "code" || !code) return void 0;
+  const generator = code.generator ?? agenticGenerator({
+    ...code.harness ? { harness: code.harness } : {},
+    ...code.verify ? { verify: code.verify } : {},
+    ...code.timeoutMs ? { timeoutMs: code.timeoutMs } : {}
+  });
+  return improvementDriver({
+    worktree: gitWorktreeAdapter({
+      repoRoot: code.repoRoot,
+      ...code.worktreeDir ? { worktreeDir: code.worktreeDir } : {}
+    }),
+    generator,
+    ...code.baseRef ? { baseRef: code.baseRef } : {}
+  });
+}
 function parseWinnerJson(winner, surface) {
   try {
     return JSON.parse(winner);
@@ -1332,6 +1736,15 @@ function applyWinnerToProfile(profile, surface, winner) {
       return { ...profile, mcp: parseWinnerJson(winner, surface) };
     case "hooks":
       return { ...profile, hooks: parseWinnerJson(winner, surface) };
+    case "rollout-policy": {
+      const policy = normalizeRolloutPolicy(parseWinnerJson(winner, surface));
+      if (!policy) {
+        throw new ConfigError(
+          `improve(): the shipped 'rollout-policy' winner is not a valid StructuralRolloutPolicy (integer k >= 1, repairRounds >= 0, testgen >= 0), so it cannot be applied: ${winner}`
+        );
+      }
+      return applyRolloutPolicyToProfile(profile, policy);
+    }
     case "code":
       return profile;
   }
@@ -1340,10 +1753,10 @@ 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);
+  const proposer = opts.generator ?? defaultGeneratorFor(surface, opts.llm) ?? codeProposerFor(surface, opts.code);
   if (!proposer) {
     throw new ConfigError(
-      `improve(): surface '${surface}' has no default generator \u2014 pass opts.generator (a SurfaceProposer) explicitly`
+      surface === "code" ? `improve(): surface 'code' needs either opts.generator or opts.code ({ repoRoot, ... }) \u2014 there is no safe zero-config repo to invent` : `improve(): surface '${surface}' has no default generator \u2014 pass opts.generator (a SurfaceProposer) explicitly`
     );
   }
   const budget = gate === "none" ? { ...opts.budget, generations: 0 } : { ...opts.budget };
@@ -1351,63 +1764,24 @@ async function improve(profile, findings, opts) {
     agent: opts.agent,
     scenarios: opts.scenarios,
     judge: opts.judge,
-    baselineSurface: baselineSurfaceFor(profile, surface),
+    baselineSurface: baselineSurfaceFor(profile, surface, opts.skills),
     proposer,
     budget,
     llm: opts.llm,
-    findings
+    findings,
+    ...opts.runDir !== void 0 ? { runDir: opts.runDir } : {},
+    ...opts.storage !== void 0 ? { storage: opts.storage } : {},
+    ...opts.analyzeGeneration === null ? {} : {
+      analyzeGeneration: opts.analyzeGeneration ?? (opts.rawTraceContext ? rawTraceDistiller({ fallbackFindings: findings }) : generationFailureDistiller(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;
+  const usedSkillDocument = surface === "skills" && opts.skills !== void 0;
+  if (shipped && usedSkillDocument && typeof raw.winner.surface === "string") {
+    opts.skills?.writeBack?.(raw.winner.surface);
   }
-  return ctx.findings;
+  const nextProfile = shipped && !usedSkillDocument ? applyWinnerToProfile(profile, surface, raw.winner.surface) : profile;
+  return { profile: nextProfile, shipped, lift: raw.lift, gateDecision: raw.gateDecision, raw };
 }
 
 // src/improvement/reflective-generator.ts
@@ -2888,10 +3262,14 @@ export {
   JudgeError,
   NotFoundError,
   PlannerError,
+  RESEARCH_SUPERVISOR_SYSTEM_PROMPT,
+  ROLLOUT_POLICY_BOUNDS,
+  ROLLOUT_POLICY_EXTENSION,
   RuntimeRunStateError,
   SqlConversationJournal,
   ValidationError,
   agenticGenerator,
+  applyRolloutPolicyToProfile,
   applyRunRecordDefaults,
   auditLoopRunner,
   buildForwardHeaders,
@@ -2901,6 +3279,7 @@ export {
   commandVerifier,
   composeRuntimeHooks,
   computeBackoff,
+  createAgentKnowledgeReadinessCheck,
   createConversationBackend,
   createIterableBackend,
   createOpenAICompatibleBackend,
@@ -2908,28 +3287,35 @@ export {
   createRuntimeEventCollector,
   createRuntimeStreamEventCollector,
   createSandboxPromptBackend,
+  createSupervisedKnowledgeUpdater,
   d1ToSqlAdapter,
   decideKnowledgeReadiness,
   defaultIsRetryable,
   defineConversation,
   defineRuntimeHooks,
   deriveExecutionId,
+  enumerateNeighborPolicies,
   exportEvalRuns,
+  formatSupervisedKnowledgeTask,
   getModels,
   handleChatTurn,
   improve,
   improvementDriver,
   isDelegatedLoopMode,
   isDepthExceeded,
+  knowledgeReadinessDeliverable,
   loopEventToOtelSpan,
   makePerAttemptSignal,
   mcpBuildPrompt,
   mcpServeVerifier,
   mcpToolsForRuntimeMcp,
   mcpToolsForRuntimeMcpSubset,
+  normalizeRolloutPolicy,
   notifyRuntimeDecisionPoint,
   notifyRuntimeHookEvent,
   parseLoopRunnerArgv,
+  parseRolloutPolicy,
+  rawTraceDistiller,
   readDepth,
   readinessServerSentEvent,
   reflectiveGenerator,
@@ -2937,24 +3323,29 @@ export {
   resolveAgentBackend,
   resolveChatModel,
   resolveRouterBaseUrl,
+  rolloutPolicyProposer,
   runAgentTask,
   runAgentTaskStream,
   runConversation,
   runConversationStream,
   runDelegatedLoop,
+  runKnowledgeImprovementJob,
   runLoopRunnerCli,
   runPersonaConversation,
   runPersonaDispatch,
+  runSupervisedKnowledgeUpdate,
   runToolLoop,
   runtimeStreamServerSentEvent,
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
   sanitizeRuntimeStreamEvent,
   selfImproveLoopRunner,
+  serializeRolloutPolicy,
   sleep,
   slugifySpeaker,
   startRuntimeRun,
   streamToolLoop,
+  structuralRolloutPolicyFromProfile,
   toolBuildPrompt,
   turnId,
   validateChatModelId,