@tangle-network/agent-runtime 0.104.0 → 0.106.0

package/dist/index.js

@@ -1,2053 +1,2215 @@
-import {
-  DELEGATED_LOOP_MODES,
-  auditLoopRunner,
-  isDelegatedLoopMode,
-  parseLoopRunnerArgv,
-  researchLoopRunner,
-  runDelegatedLoop,
-  runLoopRunnerCli,
-  selfImproveLoopRunner,
-  worktreeLoopRunner
-} from "./chunk-3PPVCS75.js";
-import {
-  FileAgentCandidateExecutionClaimStore,
-  buildAgentCandidateBundle,
-  disposePreparedAgentCandidateExecution,
-  recoverExpiredAgentCandidateExecution
-} from "./chunk-SNSMRT6H.js";
-import {
-  mcpToolsForRuntimeMcp,
-  mcpToolsForRuntimeMcpSubset
-} from "./chunk-2QJSNOGK.js";
-import "./chunk-SGKPNBXE.js";
-import {
-  DEFAULT_ROUTER_BASE_URL,
-  cleanModelId,
-  getModels,
-  resolveChatModel,
-  resolveRouterBaseUrl,
-  validateChatModelId
-} from "./chunk-NURIQBJQ.js";
-import {
-  CircuitBreakerState,
-  CircuitOpenError,
-  DEFAULT_MAX_DEPTH,
-  DeadlineExceededError,
-  FORWARD_HEADERS,
-  FileConversationJournal,
-  InMemoryConversationJournal,
-  SqlConversationJournal,
-  buildForwardHeaders,
-  computeBackoff,
-  createConversationBackend,
-  d1ToSqlAdapter,
-  defaultIsRetryable,
-  defineConversation,
-  isDepthExceeded,
-  makePerAttemptSignal,
-  readDepth,
-  runConversation,
-  runConversationStream,
-  runPersonaConversation,
-  runPersonaDispatch,
-  sleep,
-  slugifySpeaker,
-  turnId
-} from "./chunk-2KGAN2HM.js";
-import {
-  createProtectedAgentCandidateModelPort,
-  exactProcessProviderAsCandidateExecutor
-} from "./chunk-ZXICDSAK.js";
-import {
-  McpSpawnFault,
-  connectStdioMcp
-} from "./chunk-ATDFUJYI.js";
-import {
-  InMemoryRuntimeSessionStore,
-  createIterableBackend,
-  createOpenAICompatibleBackend,
-  createSandboxPromptBackend,
-  normalizeBackendStreamEvent,
-  nowIso,
-  startOrResumeRuntimeSession,
-  touchSession
-} from "./chunk-Q2JSAVQ3.js";
-import {
-  RESEARCH_SUPERVISOR_SYSTEM_PROMPT,
-  buildKnowledgeImprovementExperimentBundles,
-  createAgentKnowledgeReadinessCheck,
-  createKnowledgeImprovementActivationExecutor,
-  createSupervisedKnowledgeUpdater,
-  formatSupervisedKnowledgeTask,
-  knowledgeReadinessDeliverable,
-  runKnowledgeImprovementJob,
-  runSupervisedKnowledgeUpdate
-} from "./chunk-2UABGGUB.js";
-import "./chunk-5QOB7H74.js";
-import {
-  captureAgentCandidateWorkspace,
-  captureAgentCandidateWorkspaceFiles,
-  createAgentCandidateWorkspacePort,
-  sealAgentCandidateBundle
-} from "./chunk-B7K7V22Y.js";
-import "./chunk-HAO4CXHP.js";
-import {
-  AGENTIC_PROFILE_RESOURCE_ROOT,
-  LIFTED_FINDING_ANALYST_ID,
-  ROLLOUT_POLICY_BOUNDS,
-  ROLLOUT_POLICY_EXTENSION,
-  agenticGenerator,
-  applyRolloutPolicyToProfile,
-  commandVerifier,
-  defaultBuildPrompt,
-  enumerateNeighborPolicies,
-  improve,
-  improvementDriver,
-  isAnalystFinding,
-  normalizeRolloutPolicy,
-  parseRolloutPolicy,
-  rawTraceDistiller,
-  rawTraceEvidenceProblem,
-  requiresRawTraceEvidence,
-  rolloutPolicyProposer,
-  serializeRolloutPolicy,
-  structuralRolloutPolicyFromProfile,
-  summarizeFindings,
-  toAnalystFindings,
-  worktreeChangedPaths
-} from "./chunk-FJI3EXU3.js";
-import {
-  AGENT_CANDIDATE_EXECUTION_SUPPORT,
-  CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV,
-  CANDIDATE_KNOWLEDGE_ROOT_ENV,
-  CANDIDATE_TRACE_ENV,
-  CANDIDATE_TRACE_TAGS,
-  InMemoryAgentCandidateExecutionClaimStore,
-  applyExactAgentProfileDiff,
-  assertCandidateProfileBinding,
-  candidateExecutionClaim,
-  candidateKnowledgeExecutionPaths,
-  canonicalCandidateDigest,
-  executePreparedAgentCandidate,
-  parseExactAgentProfile,
-  parseExactAgentProfileDiff,
-  persistCandidateOutputArtifact,
-  prepareAgentCandidateExecution,
-  verifyAgentCandidateBundle
-} from "./chunk-SBTWKPVR.js";
-import "./chunk-5HNDYWUT.js";
-import "./chunk-DPEUKJRO.js";
-import {
-  buildDriverSystem,
-  optimizerMethod,
-  researchDriverNote,
-  strategyAuthorMethod
-} from "./chunk-STJEHM5F.js";
-import "./chunk-UPWGXKXB.js";
-import {
-  INTELLIGENCE_WIRE_VERSION,
-  buildLoopOtelSpans,
-  buildLoopSpanNodes,
-  buildRuntimeEventOtelSpans,
-  createOtelExporter,
-  createRuntimeEventCollector,
-  createRuntimeStreamEventCollector,
-  exportEvalRuns,
-  loopEventToOtelSpan,
-  sanitizeAgentRuntimeEvent,
-  sanitizeKnowledgeReadinessReport,
-  sanitizeRuntimeStreamEvent
-} from "./chunk-2VZYRB55.js";
-import {
-  composeRuntimeHooks,
-  defineRuntimeHooks,
-  notifyRuntimeDecisionPoint,
-  notifyRuntimeHookEvent,
-  runBrainLoop,
-  runLocalHarness
-} from "./chunk-2X65HYMI.js";
-import "./chunk-ISPWRSEC.js";
-import "./chunk-KRBFHMV6.js";
-import "./chunk-3MDZX7YU.js";
-import "./chunk-FD2MBMOH.js";
-import "./chunk-M22PL4GH.js";
-import {
-  AgentEvalError,
-  BackendTransportError,
-  ConfigError,
-  JudgeError,
-  NotFoundError,
-  PlannerError,
-  RuntimeRunStateError,
-  ValidationError
-} from "./chunk-YEJR7IXO.js";
-
-// src/durable/chat-engine.ts
-var encoder = new TextEncoder();
+import { a as JudgeError, c as RuntimeRunStateError, i as ConfigError, o as NotFoundError, r as BackendTransportError, s as PlannerError, t as AgentEvalError, u as ValidationError } from "./errors-DEAvWQPy.js";
+import { a as InMemoryRuntimeSessionStore, c as startOrResumeRuntimeSession, i as normalizeBackendStreamEvent, l as touchSession, n as createOpenAICompatibleBackend, r as createSandboxPromptBackend, s as nowIso, t as createIterableBackend } from "./backends-Dy8NujB4.js";
+import { $ as parseExactAgentProfile, K as applyExactAgentProfileDiff, S as CANDIDATE_TRACE_TAGS, _ as candidateExecutionClaim, a as persistCandidateOutputArtifact, c as CANDIDATE_KNOWLEDGE_ROOT_ENV, et as parseExactAgentProfileDiff, f as verifyAgentCandidateBundle, h as InMemoryAgentCandidateExecutionClaimStore, l as candidateKnowledgeExecutionPaths, n as executePreparedAgentCandidate, q as assertCandidateProfileBinding, rt as canonicalCandidateDigest, s as CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV, t as prepareAgentCandidateExecution, u as AGENT_CANDIDATE_EXECUTION_SUPPORT, x as CANDIDATE_TRACE_ENV } from "./prepare-B53sPV7M.js";
+import { i as sealAgentCandidateBundle, n as captureAgentCandidateWorkspaceFiles, r as createAgentCandidateWorkspacePort, t as captureAgentCandidateWorkspace } from "./workspace-archive-BosQiotA.js";
+import { i as buildAgentCandidateBundle, n as disposePreparedAgentCandidateExecution, r as FileAgentCandidateExecutionClaimStore, t as recoverExpiredAgentCandidateExecution } from "./candidate-execution-DqMbv1rU.js";
+import { n as exactProcessProviderAsCandidateExecutor, t as createProtectedAgentCandidateModelPort } from "./protected-model-port-BLPH5VVv.js";
+import { C as makePerAttemptSignal, S as defaultIsRetryable, _ as readDepth, a as FileConversationJournal, b as DeadlineExceededError, c as createConversationBackend, d as slugifySpeaker, f as turnId, g as isDepthExceeded, h as buildForwardHeaders, i as d1ToSqlAdapter, l as runConversation, m as FORWARD_HEADERS, n as runPersonaDispatch, o as InMemoryConversationJournal, p as DEFAULT_MAX_DEPTH, r as SqlConversationJournal, s as defineConversation, t as runPersonaConversation, u as runConversationStream, v as CircuitBreakerState, w as sleep, x as computeBackoff, y as CircuitOpenError } from "./conversation-XucG_K3l.js";
+import { N as runLocalHarness, _ as defineRuntimeHooks, g as composeRuntimeHooks, v as notifyRuntimeDecisionPoint, w as runBrainLoop, y as notifyRuntimeHookEvent } from "./supervisor-DTKhF-RV.js";
+import { D as researchDriverNote, E as optimizerMethod, O as strategyAuthorMethod, T as buildDriverSystem } from "./structural-rollout-IXUEplky.js";
+import { A as applyRolloutPolicyToProfile, B as commandVerifier, D as withMethodRuntimeControls, E as improve, F as LIFTED_FINDING_ANALYST_ID, G as worktreeChangedPaths, H as rawTraceEvidenceProblem, I as isAnalystFinding, L as toAnalystFindings, M as parseRolloutPolicy, N as serializeRolloutPolicy, O as rawTraceDistiller, P as structuralRolloutPolicyFromProfile, R as AGENTIC_PROFILE_RESOURCE_ROOT, U as requiresRawTraceEvidence, V as defaultBuildPrompt, W as summarizeFindings, j as normalizeRolloutPolicy, k as ROLLOUT_POLICY_EXTENSION, z as agenticGenerator } from "./improvement-cycle-C095kS_g.js";
+import { bt as connectStdioMcp, yt as McpSpawnFault } from "./runtime-BG0BziaP.js";
+import { n as defaultRedactorIdentityMaterial, r as resolveRedactor, t as defaultRedactor } from "./redact-D-u-rrcn.js";
+import { a as createSupervisedKnowledgeUpdater, c as runSupervisedKnowledgeUpdate, i as RESEARCH_SUPERVISOR_SYSTEM_PROMPT, l as createKnowledgeImprovementActivationExecutor, n as createAgentKnowledgeReadinessCheck, o as formatSupervisedKnowledgeTask, r as runKnowledgeImprovementJob, s as knowledgeReadinessDeliverable, t as buildKnowledgeImprovementExperimentBundles } from "./knowledge-Ku-mPP4f.js";
+import { a as createOtelExporter, c as loopEventToOtelSpan, d as sanitizeAgentRuntimeEvent, f as sanitizeKnowledgeReadinessReport, i as buildRuntimeEventOtelSpans, l as createRuntimeEventCollector, n as buildLoopOtelSpans, o as exportEvalRuns, p as sanitizeRuntimeStreamEvent, r as buildLoopSpanNodes, t as INTELLIGENCE_WIRE_VERSION, u as createRuntimeStreamEventCollector } from "./otel-export-D34IQW1C.js";
+import { a as isDelegatedLoopMode, c as worktreeLoopRunner, i as auditLoopRunner, n as runLoopRunnerCli, o as researchLoopRunner, r as DELEGATED_LOOP_MODES, s as runDelegatedLoop, t as parseLoopRunnerArgv } from "./loop-runner-bin-BwjQ1NfH.js";
+import { n as mcpToolsForRuntimeMcpSubset, t as mcpToolsForRuntimeMcp } from "./openai-tools-CKLy1C7M.js";
+import { a as resolveRouterBaseUrl, i as resolveChatModel, n as cleanModelId, o as validateChatModelId, r as getModels, t as DEFAULT_ROUTER_BASE_URL } from "./model-resolution-Btd9iIKV.js";
+import { FAILURE_CLASSES, acquisitionPlansForKnowledgeGaps, blockingKnowledgeEval, canonicalJson, runAgentControlLoop, scoreKnowledgeReadiness, userQuestionsForKnowledgeGaps } from "@tangle-network/agent-eval";
+import { gepaOptimizationMethod, skillOptOptimizationMethod } from "@tangle-network/agent-eval/campaign";
+import { readFileSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+//#region src/durable/chat-engine.ts
+const encoder = new TextEncoder();
 function encodeLine(event) {
-  return encoder.encode(`${JSON.stringify(event)}
-`);
+	return encoder.encode(`${JSON.stringify(event)}\n`);
 }
 function defaultLog(message, meta) {
-  if (meta) console.error(message, meta);
-  else console.error(message);
-}
+	if (meta) console.error(message, meta);
+	else console.error(message);
+}
+/**
+* Run one chat turn. Returns immediately with a `ReadableStream` body;
+* the turn executes as the body is pulled. Never rejects — backend
+* failures surface as `error` + `session.run.failed` events.
+*/
 function handleChatTurn(input) {
-  const log = input.log ?? defaultLog;
-  const { identity, hooks } = input;
-  const body = new ReadableStream({
-    start: async (controller) => {
-      const emit2 = async (event) => {
-        controller.enqueue(encodeLine(event));
-        if (hooks.onEvent) {
-          try {
-            await hooks.onEvent(event);
-          } catch (err) {
-            log("[chat-engine] onEvent hook threw", {
-              error: err instanceof Error ? err.message : String(err)
-            });
-          }
-        }
-      };
-      try {
-        await emit2({
-          type: "session.run.started",
-          data: {
-            sessionId: identity.sessionId,
-            tenantId: identity.tenantId,
-            turnIndex: identity.turnIndex
-          }
-        });
-        const producer = hooks.produce();
-        for await (const event of producer.stream) {
-          await emit2(event);
-        }
-        const rawFinal = producer.finalText();
-        const finalText = hooks.transformFinalText ? await hooks.transformFinalText(rawFinal) : rawFinal;
-        await hooks.persistAssistantMessage({ identity, finalText });
-        if (hooks.onTurnComplete) {
-          try {
-            await hooks.onTurnComplete({ identity, finalText });
-          } catch (err) {
-            log("[chat-engine] onTurnComplete threw", {
-              error: err instanceof Error ? err.message : String(err)
-            });
-          }
-        }
-        await emit2({
-          type: "session.run.completed",
-          data: { sessionId: identity.sessionId }
-        });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        log("[chat-engine] turn failed", { error: message });
-        await emit2({ type: "error", data: { message } });
-        await emit2({
-          type: "session.run.failed",
-          data: { sessionId: identity.sessionId, message }
-        });
-      } finally {
-        if (hooks.traceFlush) {
-          const flush = hooks.traceFlush().catch(
-            (err) => log("[chat-engine] traceFlush threw", {
-              error: err instanceof Error ? err.message : String(err)
-            })
-          );
-          if (input.waitUntil) input.waitUntil(flush);
-          else await flush;
-        }
-        controller.close();
-      }
-    }
-  });
-  return { body, contentType: "application/x-ndjson" };
-}
-
-// src/durable/execution-handle.ts
+	const log = input.log ?? defaultLog;
+	const { identity, hooks } = input;
+	return {
+		body: new ReadableStream({ start: async (controller) => {
+			const emit = async (event) => {
+				controller.enqueue(encodeLine(event));
+				if (hooks.onEvent) try {
+					await hooks.onEvent(event);
+				} catch (err) {
+					log("[chat-engine] onEvent hook threw", { error: err instanceof Error ? err.message : String(err) });
+				}
+			};
+			try {
+				await emit({
+					type: "session.run.started",
+					data: {
+						sessionId: identity.sessionId,
+						tenantId: identity.tenantId,
+						turnIndex: identity.turnIndex
+					}
+				});
+				const producer = hooks.produce();
+				for await (const event of producer.stream) await emit(event);
+				const rawFinal = producer.finalText();
+				const finalText = hooks.transformFinalText ? await hooks.transformFinalText(rawFinal) : rawFinal;
+				await hooks.persistAssistantMessage({
+					identity,
+					finalText
+				});
+				if (hooks.onTurnComplete) try {
+					await hooks.onTurnComplete({
+						identity,
+						finalText
+					});
+				} catch (err) {
+					log("[chat-engine] onTurnComplete threw", { error: err instanceof Error ? err.message : String(err) });
+				}
+				await emit({
+					type: "session.run.completed",
+					data: { sessionId: identity.sessionId }
+				});
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				log("[chat-engine] turn failed", { error: message });
+				await emit({
+					type: "error",
+					data: { message }
+				});
+				await emit({
+					type: "session.run.failed",
+					data: {
+						sessionId: identity.sessionId,
+						message
+					}
+				});
+			} finally {
+				if (hooks.traceFlush) {
+					const flush = hooks.traceFlush().catch((err) => log("[chat-engine] traceFlush threw", { error: err instanceof Error ? err.message : String(err) }));
+					if (input.waitUntil) input.waitUntil(flush);
+					else await flush;
+				}
+				controller.close();
+			}
+		} }),
+		contentType: "application/x-ndjson"
+	};
+}
+//#endregion
+//#region src/durable/execution-handle.ts
+/**
+* Derive a stable executionId from the run identity. The same
+* `(projectId, sessionId, turnIndex)` tuple yields the same id — so a
+* client retry of the same turn lands on the same substrate execution
+* and the orchestrator's buffer replays instead of starting a second
+* prompt.
+*
+* Format is readable, not hashed: operators grepping orchestrator logs
+* for `gtm-agent:thread-abc:3` find the run without translating an
+* opaque id. Substrate executionIds are not a secrecy boundary.
+*
+* Wire integration:
+*   - Sandbox PromptOptions accepts `executionId` and `lastEventId`.
+*     Products pass this id to make cross-process reconnect land on the
+*     same substrate execution instead of spawning a duplicate run.
+*/
 function deriveExecutionId(input) {
-  return `${input.projectId}:${input.sessionId}:${input.turnIndex}`;
+	return `${input.projectId}:${input.sessionId}:${input.turnIndex}`;
 }
-
-// src/improvement/build-prompts.ts
+//#endregion
+//#region src/improvement/build-prompts.ts
+/** Render findings as the ranked-evidence block every build prompt ends with. */
 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}`;
-  });
+	return findings.map((f) => {
+		const where = f.subject ? ` [${f.subject}]` : "";
+		const action = f.recommended_action ? ` → ${f.recommended_action}` : "";
+		return `- (${f.severity})${where} ${f.claim}${action}`;
+	});
 }
+/** Build the starting instruction for a coder agent tasked with implementing a new tool. */
 function toolBuildPrompt(args) {
-  return [
-    "You are building a new TOOL for this codebase \u2014 a capability the agent measurably lacks,",
-    "evidenced by the failure findings at the bottom. The tool is an experiment: after it is",
-    "built and verified, its marginal lift is measured on held-out tasks, and only a real lift",
-    "promotes it.",
-    "",
-    optimizerMethod,
-    "",
-    "THE SURFACE \u2014 what a deliverable tool looks like here:",
-    "- ONE small, self-contained module PLUS tests that exercise its contract (what callers rely",
-    "  on), not its internals. The tests are the experiment for sub-goal correctness \u2014 write the",
-    "  test that would fail if your hypothesis about the gap were wrong.",
-    "- It must compile and its tests must pass \u2014 they run automatically; on failure you get the",
-    "  verifier output and another attempt, resuming on top of your own edits (fix in place, do",
-    "  not start over).",
-    "- Match the codebase grain: reuse its existing helpers, style, and test framework; a tool",
-    "  that fights the codebase is the wrong tool even if it passes.",
-    "- Do not commit; leave the changes in the working tree.",
-    "",
-    "FINDINGS \u2014 ranked evidence from real failed runs (the gaps the tool must close):",
-    ...findingLines(args.findings)
-  ].join("\n");
-}
+	return [
+		"You are building a new TOOL for this codebase — a capability the agent measurably lacks,",
+		"evidenced by the failure findings at the bottom. The tool is an experiment: after it is",
+		"built and verified, its marginal lift is measured on held-out tasks, and only a real lift",
+		"promotes it.",
+		"",
+		optimizerMethod,
+		"",
+		"THE SURFACE — what a deliverable tool looks like here:",
+		"- ONE small, self-contained module PLUS tests that exercise its contract (what callers rely",
+		"  on), not its internals. The tests are the experiment for sub-goal correctness — write the",
+		"  test that would fail if your hypothesis about the gap were wrong.",
+		"- It must compile and its tests must pass — they run automatically; on failure you get the",
+		"  verifier output and another attempt, resuming on top of your own edits (fix in place, do",
+		"  not start over).",
+		"- Match the codebase grain: reuse its existing helpers, style, and test framework; a tool",
+		"  that fights the codebase is the wrong tool even if it passes.",
+		"- Do not commit; leave the changes in the working tree.",
+		"",
+		"FINDINGS — ranked evidence from real failed runs (the gaps the tool must close):",
+		...findingLines(args.findings)
+	].join("\n");
+}
+/** Build the starting instruction for a coder agent tasked with implementing a new MCP server. */
 function mcpBuildPrompt(args) {
-  return [
-    "You are building a new MCP SERVER (Model Context Protocol) exposing tool(s) that close the",
-    "capability gaps evidenced by the failure findings at the bottom, so any harness can mount",
-    "them. The server is an experiment: after it is built and boot-verified, its marginal lift is",
-    "measured on held-out tasks, and only a real lift promotes it.",
-    "",
-    optimizerMethod,
-    "",
-    "RESEARCH FIRST \u2014 ADOPT BEFORE BUILD: you may discover and ADOPT an existing external MCP",
-    "server if it fits the gaps better than building one. Registries and vendor docs list",
-    "maintained servers for most common capabilities (web search, fetch, GitHub, filesystems,",
-    "databases). To adopt, deliver a short adoption note instead of an implementation: the",
-    "server's launch command or HTTP endpoint, and the API key it needs BY NAME (e.g.",
-    "EXA_API_KEY) \u2014 never a key value; provisioning injects the value at materialize time. If",
-    "your environment has no web access, decide from what you already know and say so.",
-    "",
-    "THE SURFACE \u2014 what a deliverable MCP server looks like here (checked by BOOTING it):",
-    "- 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,",
-    "- a clear start command (a package.json `start` script or an obvious entrypoint).",
-    "Design the tool surface for the FINDINGS, not for generality: each exposed tool should map to",
-    "a named failure mechanism, with a description that tells the agent when to reach for it (a",
-    "tool the agent never calls measures zero). If the boot-and-probe fails you get the error and",
-    "another attempt, resuming on top of your own edits. Do not commit; leave the changes in the",
-    "working tree.",
-    "",
-    "FINDINGS \u2014 ranked evidence from real failed runs (the capabilities the server must provide):",
-    ...findingLines(args.findings)
-  ].join("\n");
-}
-
-// src/improvement/campaign-otlp.ts
-import { readdirSync, readFileSync } from "fs";
-import { basename, dirname, join, resolve } from "path";
-import { OPENINFERENCE_SPAN_KIND } from "@tangle-network/agent-eval/traces";
-var MAX_WALK_DEPTH = 4;
-function campaignCellSpansToOtlp(content, cell, opts = {}) {
-  const records = parseCampaignSpans(content, cell.cellId);
-  if (records.length === 0) return [];
-  const serviceName = opts.serviceName ?? "campaign";
-  const key = cell.cellKey ?? cell.cellId;
-  const traceId = foldTo32Hex(key);
-  const rootSpanId = foldTo16Hex(`${key}::root`);
-  const startMs = Math.min(...records.map((r) => r.startMs));
-  const endMs = Math.max(...records.map((r) => r.startMs + (r.durationMs ?? 0)));
-  const anyError = records.some((r) => r.error !== void 0);
-  const resource = {
-    attributes: {
-      "service.name": serviceName,
-      "campaign.cell_id": cell.cellId,
-      ...cell.cellKey ? { "campaign.cell_dir": cell.cellKey } : {}
-    }
-  };
-  const lines = [
-    JSON.stringify({
-      trace_id: traceId,
-      span_id: rootSpanId,
-      parent_span_id: "",
-      name: `cell.${cell.cellId}`,
-      start_time: msToIso(startMs),
-      end_time: msToIso(endMs),
-      status: anyError ? { code: "STATUS_CODE_ERROR", message: "one or more spans errored" } : { code: "STATUS_CODE_OK", message: "" },
-      resource,
-      attributes: {
-        [OPENINFERENCE_SPAN_KIND]: "AGENT",
-        "agent.name": cell.cellId
-      }
-    })
-  ];
-  for (let i = 0; i < records.length; i++) {
-    const r = records[i];
-    lines.push(
-      JSON.stringify({
-        trace_id: traceId,
-        span_id: foldTo16Hex(`${key}::${i}`),
-        parent_span_id: rootSpanId,
-        name: r.name,
-        start_time: msToIso(r.startMs),
-        end_time: msToIso(r.startMs + (r.durationMs ?? 0)),
-        status: r.error === void 0 ? { code: "STATUS_CODE_OK", message: "" } : { code: "STATUS_CODE_ERROR", message: r.error },
-        resource,
-        attributes: r.attributes
-      })
-    );
-  }
-  return lines;
-}
-function convertCampaignDirToOtlp(dir, opts = {}) {
-  const root = resolve(dir);
-  const files = findSpansFiles(root, MAX_WALK_DEPTH);
-  const lines = [];
-  for (const file of files) {
-    let content;
-    try {
-      content = readFileSync(file, "utf8");
-    } catch {
-      continue;
-    }
-    const cellDir = dirname(file);
-    lines.push(
-      ...campaignCellSpansToOtlp(content, { cellId: basename(cellDir), cellKey: cellDir }, opts)
-    );
-  }
-  return lines.length > 0 ? `${lines.join("\n")}
-` : "";
-}
-function campaignTraceResolver(opts) {
-  return (ctx) => {
-    const priorDir = ctx.generation <= 0 ? join(opts.runDir, "baseline") : join(opts.runDir, `gen-${ctx.generation - 1}`);
-    const prior = convertCampaignDirToOtlp(priorDir, opts);
-    if (prior) return prior;
-    return convertCampaignDirToOtlp(opts.runDir, opts);
-  };
-}
-function parseCampaignSpans(content, cellId) {
-  const out = [];
-  for (const line of content.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let raw;
-    try {
-      raw = JSON.parse(trimmed);
-    } catch {
-      continue;
-    }
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
-    const o = raw;
-    if (typeof o.name !== "string" || typeof o.startMs !== "number") continue;
-    const attributes = { "campaign.cell_id": cellId };
-    for (const [k, v] of Object.entries(o)) {
-      if (k === "name" || k === "cellId" || k === "startMs" || k === "durationMs") continue;
-      attributes[k] = v;
-    }
-    out.push({
-      name: o.name,
-      cellId,
-      startMs: o.startMs,
-      ...typeof o.durationMs === "number" ? { durationMs: o.durationMs } : {},
-      attributes,
-      ...typeof o.error === "string" ? { error: o.error } : {}
-    });
-  }
-  return out;
-}
-function findSpansFiles(dir, depth) {
-  const out = [];
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return out;
-  }
-  for (const entry of entries) {
-    const full = join(dir, entry.name);
-    if (entry.isFile() && entry.name === "spans.jsonl") {
-      out.push(full);
-    } else if (depth > 0 && entry.isDirectory() && !entry.isSymbolicLink()) {
-      out.push(...findSpansFiles(full, depth - 1));
-    }
-  }
-  return out.sort();
-}
-function msToIso(ms) {
-  return Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : (/* @__PURE__ */ new Date(0)).toISOString();
-}
-function foldTo16Hex(s) {
-  const a = fnv1a(s);
-  const b = fnv1a(`${s}::salt`);
-  return a + b;
-}
-function foldTo32Hex(s) {
-  return foldTo16Hex(s) + foldTo16Hex(`${s}::trace`);
-}
-function fnv1a(s) {
-  let h = 2166136261;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 16777619) >>> 0;
-  }
-  return h.toString(16).padStart(8, "0");
-}
-
-// src/improvement/driver-loop-generator.ts
-import { spawnSync } from "child_process";
-import { readFileSync as readFileSync2, statSync } from "fs";
-import { resolve as resolve2, sep } from "path";
-var workerOutputTailChars = 2e3;
-var diffMaxChars = 6e3;
-var readFileDefaultBytes = 8192;
-var researchResultMaxChars = 8e3;
+	return [
+		"You are building a new MCP SERVER (Model Context Protocol) exposing tool(s) that close the",
+		"capability gaps evidenced by the failure findings at the bottom, so any harness can mount",
+		"them. The server is an experiment: after it is built and boot-verified, its marginal lift is",
+		"measured on held-out tasks, and only a real lift promotes it.",
+		"",
+		optimizerMethod,
+		"",
+		"RESEARCH FIRST — ADOPT BEFORE BUILD: you may discover and ADOPT an existing external MCP",
+		"server if it fits the gaps better than building one. Registries and vendor docs list",
+		"maintained servers for most common capabilities (web search, fetch, GitHub, filesystems,",
+		"databases). To adopt, deliver a short adoption note instead of an implementation: the",
+		"server's launch command or HTTP endpoint, and the API key it needs BY NAME (e.g.",
+		"EXA_API_KEY) — never a key value; provisioning injects the value at materialize time. If",
+		"your environment has no web access, decide from what you already know and say so.",
+		"",
+		"THE SURFACE — what a deliverable MCP server looks like here (checked by BOOTING it):",
+		"- 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,",
+		"- a clear start command (a package.json `start` script or an obvious entrypoint).",
+		"Design the tool surface for the FINDINGS, not for generality: each exposed tool should map to",
+		"a named failure mechanism, with a description that tells the agent when to reach for it (a",
+		"tool the agent never calls measures zero). If the boot-and-probe fails you get the error and",
+		"another attempt, resuming on top of your own edits. Do not commit; leave the changes in the",
+		"working tree.",
+		"",
+		"FINDINGS — ranked evidence from real failed runs (the capabilities the server must provide):",
+		...findingLines(args.findings)
+	].join("\n");
+}
+//#endregion
+//#region src/improvement/driver-loop-generator.ts
+/**
+* `driverLoopGenerator` — the driver→worker `CandidateGenerator`: the build
+* loop run by the ATOM instead of the canned respawn.
+*
+* `agenticGenerator` steers with three hardcoded conditions picking a canned
+* note (`EMPTY_TREE_NOTE` / `failureNote`) and respawns. This generator swaps
+* that respawn brain for a real driver: an LLM on the canonical tool-loop seam
+* (`runBrainLoop` + `ToolLoopChat` — the exact loop `driverAgent` runs its
+* brain on) that AUTHORS each worker instruction, OBSERVES what the session
+* actually produced (diff, files, verifier output), RATES it, and DECIDES
+* refine / re-scope / decompose — prompted with the senior scientific-method
+* doctrine (`buildDriverSystem`).
+*
+* The worker stays the proven primitive: `runLocalHarness` in the candidate
+* worktree, same as `agenticGenerator` — only the brain between sessions
+* changes. The worktree machinery (`worktreeBuildCandidate`) and verifiers
+* (`commandVerifier` / `mcpServeVerifier`) are reused verbatim.
+*
+* Completion-oracle invariant (the supervisor doctrine, kept): the driver's
+* prose NEVER decides the outcome. After the loop, code re-checks ground
+* truth — tree dirty, raw-trace evidence present, verifier green — and only
+* that decides `applied`. A driver that claims success over a failing verifier
+* produces a discarded candidate, not a shipped one.
+*
+* @experimental
+*/
+const workerOutputTailChars = 2e3;
+const diffMaxChars = 6e3;
+const readFileDefaultBytes = 8192;
+const researchResultMaxChars = 8e3;
+/** Driver→worker `CandidateGenerator`: an LLM driver on the canonical tool-loop authors, observes, rates, and steers coding-harness sessions in the worktree until the verifier passes or the session budget is spent. */
 function driverLoopGenerator(opts) {
-  const harness = opts.harness ?? "claude";
-  const buildPrompt = opts.buildPrompt ?? defaultBuildPrompt;
-  const run = opts.runHarness ?? runLocalHarness;
-  const changed = opts.changedPaths ?? worktreeChangedPaths;
-  const readDiff = opts.readDiff ?? worktreeDiff;
-  const verify = opts.verify;
-  return {
-    kind: `driver-loop:${harness}`,
-    async generate({ worktreePath, report, findings, maxShots, signal }) {
-      signal.throwIfAborted();
-      const briefing = buildPrompt({ report, findings });
-      const needsRawTraceEvidence = requiresRawTraceEvidence(findings);
-      const sessionCap = Math.max(1, maxShots);
-      let sessionsUsed = 0;
-      const groundVerify = async () => {
-        signal.throwIfAborted();
-        if (changed(worktreePath).length === 0) {
-          return { ok: false, feedback: "the working tree has no changes \u2014 nothing to verify" };
-        }
-        if (needsRawTraceEvidence) {
-          const problem = rawTraceEvidenceProblem(worktreePath, findings);
-          if (problem) return { ok: false, feedback: problem };
-        }
-        if (!verify) {
-          return { ok: true, feedback: "no verifier configured: a dirty tree is the candidate" };
-        }
-        const result = await verify(worktreePath, signal);
-        signal.throwIfAborted();
-        return result;
-      };
-      const execute = async (name, args) => {
-        signal.throwIfAborted();
-        switch (name) {
-          case "run_worker": {
-            const instruction = typeof args.instruction === "string" ? args.instruction.trim() : "";
-            if (instruction.length === 0) {
-              return "error: run_worker requires a non-empty `instruction`";
-            }
-            if (sessionsUsed >= sessionCap) {
-              return `error: worker-session budget exhausted (${sessionsUsed}/${sessionCap} used). Inspect and verify what exists, then stop with your final assessment.`;
-            }
-            sessionsUsed += 1;
-            const result = await run({
-              harness,
-              cwd: worktreePath,
-              taskPrompt: instruction,
-              ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
-              signal
-            });
-            signal.throwIfAborted();
-            if (result.aborted) {
-              throw new Error("driverLoopGenerator: worker session was cancelled by the caller");
-            }
-            return JSON.stringify({
-              session: `${sessionsUsed}/${sessionCap}`,
-              exitCode: result.exitCode,
-              timedOut: result.timedOut,
-              aborted: result.aborted ?? false,
-              killedBySignal: result.killedBySignal,
-              durationMs: result.durationMs,
-              changedPaths: changed(worktreePath),
-              stdoutTail: tail(result.stdout, workerOutputTailChars),
-              stderrTail: tail(result.stderr, workerOutputTailChars)
-            });
-          }
-          case "inspect_worktree": {
-            const paths = changed(worktreePath);
-            const diff = truncate(readDiff(worktreePath), diffMaxChars);
-            return JSON.stringify({
-              changedPaths: paths,
-              diff: diff.length > 0 ? diff : "(no tracked-file diff \u2014 new files are untracked; read_file them)"
-            });
-          }
-          case "read_file":
-            return readWorktreeFile(worktreePath, args);
-          case "research": {
-            if (!opts.research) return "error: research tool is not provisioned in this run";
-            const query = typeof args.query === "string" ? args.query.trim() : "";
-            if (query.length === 0) return "error: research requires a non-empty `query`";
-            const result = await opts.research(query);
-            signal.throwIfAborted();
-            return truncate(result, researchResultMaxChars);
-          }
-          case "run_verifier": {
-            const result = await groundVerify();
-            return JSON.stringify({
-              ok: result.ok,
-              feedback: truncate(result.feedback ?? "", 4e3)
-            });
-          }
-          default:
-            return `error: unknown tool: ${name}`;
-        }
-      };
-      await runBrainLoop({
-        chat: opts.brain,
-        tools: opts.research ? [...driverToolSpecs, researchToolSpec] : driverToolSpecs,
-        execute,
-        initialMessages: [
-          {
-            role: "system",
-            content: opts.research ? `${buildDriverSystem}
-
-${researchDriverNote}` : buildDriverSystem
-          },
-          {
-            role: "user",
-            content: [
-              `THE BUILD BRIEF (the contract your workers must satisfy \u2014 fold what each needs into its instruction; workers never see this brief):`,
-              "",
-              briefing,
-              "",
-              `Worker-session budget: ${sessionCap}. The worktree is a fresh checkout at ${worktreePath}.`
-            ].join("\n")
-          }
-        ],
-        maxTurns: opts.maxTurns ?? Math.max(8, 2 + sessionCap * 3),
-        hooks: { stopBefore: () => signal.aborted }
-      });
-      signal.throwIfAborted();
-      const verdict = await groundVerify();
-      signal.throwIfAborted();
-      if (!verdict.ok) return { applied: false, summary: "" };
-      return { applied: true, summary: summarizeFindings(findings) };
-    }
-  };
-}
-var driverToolSpecs = [
-  {
-    type: "function",
-    function: {
-      name: "run_worker",
-      description: "Run ONE coding-harness session in the worktree with your instruction as its entire goal. The worktree persists between sessions. Sessions are capped \u2014 author each instruction richly (outcome, context, placement, the check it is held to).",
-      parameters: {
-        type: "object",
-        properties: {
-          instruction: {
-            type: "string",
-            description: "The complete, self-contained goal for this worker session."
-          }
-        },
-        required: ["instruction"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "inspect_worktree",
-      description: "Current git state of the worktree: changed paths + the tracked-file diff (truncated). New untracked files show in changedPaths only \u2014 read_file them.",
-      parameters: { type: "object", properties: {} }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "read_file",
-      description: "Read one file from the worktree (paths are worktree-relative).",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "Worktree-relative file path." },
-          maxBytes: { type: "number", description: "Byte cap (default 8192)." }
-        },
-        required: ["path"]
-      }
-    }
-  },
-  {
-    type: "function",
-    function: {
-      name: "run_verifier",
-      description: "Run the intrinsic check of the surface (compile+tests / boot-and-probe). Its result \u2014 not your judgment \u2014 decides whether the candidate is kept.",
-      parameters: { type: "object", properties: {} }
-    }
-  }
+	const harness = opts.harness ?? "claude";
+	const buildPrompt = opts.buildPrompt ?? defaultBuildPrompt;
+	const run = opts.runHarness ?? runLocalHarness;
+	const changed = opts.changedPaths ?? worktreeChangedPaths;
+	const readDiff = opts.readDiff ?? worktreeDiff;
+	const verify = opts.verify;
+	return {
+		kind: `driver-loop:${harness}`,
+		async generate({ worktreePath, report, findings, maxShots, signal }) {
+			signal.throwIfAborted();
+			const briefing = buildPrompt({
+				report,
+				findings
+			});
+			const needsRawTraceEvidence = requiresRawTraceEvidence(findings);
+			const sessionCap = Math.max(1, maxShots);
+			let sessionsUsed = 0;
+			const groundVerify = async () => {
+				signal.throwIfAborted();
+				if (changed(worktreePath).length === 0) return {
+					ok: false,
+					feedback: "the working tree has no changes — nothing to verify"
+				};
+				if (needsRawTraceEvidence) {
+					const problem = rawTraceEvidenceProblem(worktreePath, findings);
+					if (problem) return {
+						ok: false,
+						feedback: problem
+					};
+				}
+				if (!verify) return {
+					ok: true,
+					feedback: "no verifier configured: a dirty tree is the candidate"
+				};
+				const result = await verify(worktreePath, signal);
+				signal.throwIfAborted();
+				return result;
+			};
+			const execute = async (name, args) => {
+				signal.throwIfAborted();
+				switch (name) {
+					case "run_worker": {
+						const instruction = typeof args.instruction === "string" ? args.instruction.trim() : "";
+						if (instruction.length === 0) return "error: run_worker requires a non-empty `instruction`";
+						if (sessionsUsed >= sessionCap) return `error: worker-session budget exhausted (${sessionsUsed}/${sessionCap} used). Inspect and verify what exists, then stop with your final assessment.`;
+						sessionsUsed += 1;
+						const result = await run({
+							harness,
+							cwd: worktreePath,
+							taskPrompt: instruction,
+							...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+							signal
+						});
+						signal.throwIfAborted();
+						if (result.aborted) throw new Error("driverLoopGenerator: worker session was cancelled by the caller");
+						return JSON.stringify({
+							session: `${sessionsUsed}/${sessionCap}`,
+							exitCode: result.exitCode,
+							timedOut: result.timedOut,
+							aborted: result.aborted ?? false,
+							killedBySignal: result.killedBySignal,
+							durationMs: result.durationMs,
+							changedPaths: changed(worktreePath),
+							stdoutTail: tail(result.stdout, workerOutputTailChars),
+							stderrTail: tail(result.stderr, workerOutputTailChars)
+						});
+					}
+					case "inspect_worktree": {
+						const paths = changed(worktreePath);
+						const diff = truncate(readDiff(worktreePath), diffMaxChars);
+						return JSON.stringify({
+							changedPaths: paths,
+							diff: diff.length > 0 ? diff : "(no tracked-file diff — new files are untracked; read_file them)"
+						});
+					}
+					case "read_file": return readWorktreeFile(worktreePath, args);
+					case "research": {
+						if (!opts.research) return "error: research tool is not provisioned in this run";
+						const query = typeof args.query === "string" ? args.query.trim() : "";
+						if (query.length === 0) return "error: research requires a non-empty `query`";
+						const result = await opts.research(query);
+						signal.throwIfAborted();
+						return truncate(result, researchResultMaxChars);
+					}
+					case "run_verifier": {
+						const result = await groundVerify();
+						return JSON.stringify({
+							ok: result.ok,
+							feedback: truncate(result.feedback ?? "", 4e3)
+						});
+					}
+					default: return `error: unknown tool: ${name}`;
+				}
+			};
+			await runBrainLoop({
+				chat: opts.brain,
+				tools: opts.research ? [...driverToolSpecs, researchToolSpec] : driverToolSpecs,
+				execute,
+				initialMessages: [{
+					role: "system",
+					content: opts.research ? `${buildDriverSystem}\n\n${researchDriverNote}` : buildDriverSystem
+				}, {
+					role: "user",
+					content: [
+						`THE BUILD BRIEF (the contract your workers must satisfy — fold what each needs into its instruction; workers never see this brief):`,
+						"",
+						briefing,
+						"",
+						`Worker-session budget: ${sessionCap}. The worktree is a fresh checkout at ${worktreePath}.`
+					].join("\n")
+				}],
+				maxTurns: opts.maxTurns ?? Math.max(8, 2 + sessionCap * 3),
+				hooks: { stopBefore: () => signal.aborted }
+			});
+			signal.throwIfAborted();
+			const verdict = await groundVerify();
+			signal.throwIfAborted();
+			if (!verdict.ok) return {
+				applied: false,
+				summary: ""
+			};
+			return {
+				applied: true,
+				summary: summarizeFindings(findings)
+			};
+		}
+	};
+}
+const driverToolSpecs = [
+	{
+		type: "function",
+		function: {
+			name: "run_worker",
+			description: "Run ONE coding-harness session in the worktree with your instruction as its entire goal. The worktree persists between sessions. Sessions are capped — author each instruction richly (outcome, context, placement, the check it is held to).",
+			parameters: {
+				type: "object",
+				properties: { instruction: {
+					type: "string",
+					description: "The complete, self-contained goal for this worker session."
+				} },
+				required: ["instruction"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "inspect_worktree",
+			description: "Current git state of the worktree: changed paths + the tracked-file diff (truncated). New untracked files show in changedPaths only — read_file them.",
+			parameters: {
+				type: "object",
+				properties: {}
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "read_file",
+			description: "Read one file from the worktree (paths are worktree-relative).",
+			parameters: {
+				type: "object",
+				properties: {
+					path: {
+						type: "string",
+						description: "Worktree-relative file path."
+					},
+					maxBytes: {
+						type: "number",
+						description: "Byte cap (default 8192)."
+					}
+				},
+				required: ["path"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "run_verifier",
+			description: "Run the intrinsic check of the surface (compile+tests / boot-and-probe). Its result — not your judgment — decides whether the candidate is kept.",
+			parameters: {
+				type: "object",
+				properties: {}
+			}
+		}
+	}
 ];
-var researchToolSpec = {
-  type: "function",
-  function: {
-    name: "research",
-    description: "Search external sources (MCP registries, vendor docs) for an EXISTING server that closes the capability gap \u2014 the adopt-not-build check. Returns text findings.",
-    parameters: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "What capability / server to search for." }
-      },
-      required: ["query"]
-    }
-  }
+/** Only offered when `opts.research` is wired — a tool the driver cannot call
+*  must never appear in its tool list. */
+const researchToolSpec = {
+	type: "function",
+	function: {
+		name: "research",
+		description: "Search external sources (MCP registries, vendor docs) for an EXISTING server that closes the capability gap — the adopt-not-build check. Returns text findings.",
+		parameters: {
+			type: "object",
+			properties: { query: {
+				type: "string",
+				description: "What capability / server to search for."
+			} },
+			required: ["query"]
+		}
+	}
 };
+/** `git diff` over the worktree (tracked files). Fails loud like `worktreeChangedPaths` — a git
+*  fault on a fresh checkout is a broken setup, not an empty diff. */
 function worktreeDiff(worktreePath) {
-  const result = spawnSync("git", ["diff"], { cwd: worktreePath, encoding: "utf-8" });
-  if (result.error) {
-    throw new Error(
-      `driverLoopGenerator: git diff failed to spawn in ${worktreePath}: ${result.error.message}`
-    );
-  }
-  if (result.status !== 0) {
-    throw new Error(
-      `driverLoopGenerator: git diff exited ${result.status} in ${worktreePath}: ${result.stderr.trim()}`
-    );
-  }
-  return result.stdout;
-}
+	const result = spawnSync("git", ["diff"], {
+		cwd: worktreePath,
+		encoding: "utf-8"
+	});
+	if (result.error) throw new Error(`driverLoopGenerator: git diff failed to spawn in ${worktreePath}: ${result.error.message}`);
+	if (result.status !== 0) throw new Error(`driverLoopGenerator: git diff exited ${result.status} in ${worktreePath}: ${result.stderr.trim()}`);
+	return result.stdout;
+}
+/** Bounded, worktree-jailed file read for the driver's `read_file`. A path escaping the worktree
+*  is refused (the driver only rates work in the candidate tree; it has no business elsewhere). */
 function readWorktreeFile(worktreePath, args) {
-  const rel = typeof args.path === "string" ? args.path : "";
-  if (rel.length === 0) return "error: read_file requires `path`";
-  const root = resolve2(worktreePath);
-  const target = resolve2(root, rel);
-  if (target !== root && !target.startsWith(root + sep)) {
-    return `error: path escapes the worktree: ${rel}`;
-  }
-  const maxBytes = typeof args.maxBytes === "number" && args.maxBytes > 0 ? Math.min(args.maxBytes, 65536) : readFileDefaultBytes;
-  try {
-    const size = statSync(target).size;
-    const body = readFileSync2(target, "utf-8").slice(0, maxBytes);
-    return size > maxBytes ? `${body}
-\u2026 (${size - maxBytes} bytes truncated)` : body;
-  } catch (e) {
-    return `error: ${e instanceof Error ? e.message : String(e)}`;
-  }
+	const rel = typeof args.path === "string" ? args.path : "";
+	if (rel.length === 0) return "error: read_file requires `path`";
+	const root = resolve(worktreePath);
+	const target = resolve(root, rel);
+	if (target !== root && !target.startsWith(root + sep)) return `error: path escapes the worktree: ${rel}`;
+	const maxBytes = typeof args.maxBytes === "number" && args.maxBytes > 0 ? Math.min(args.maxBytes, 65536) : readFileDefaultBytes;
+	try {
+		const size = statSync(target).size;
+		const body = readFileSync(target, "utf-8").slice(0, maxBytes);
+		return size > maxBytes ? `${body}\n… (${size - maxBytes} bytes truncated)` : body;
+	} catch (e) {
+		return `error: ${e instanceof Error ? e.message : String(e)}`;
+	}
 }
 function tail(s, n) {
-  const trimmed = s.trim();
-  return trimmed.length <= n ? trimmed : `\u2026${trimmed.slice(-n)}`;
+	const trimmed = s.trim();
+	return trimmed.length <= n ? trimmed : `…${trimmed.slice(-n)}`;
 }
 function truncate(s, n) {
-  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
-}
-
-// src/improvement/mcp-serve-verifier.ts
+	return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
+}
+//#endregion
+//#region src/improvement/mcp-serve-verifier.ts
+/**
+* `mcpServeVerifier` — the intrinsic verifier for a built MCP server: the
+* boot-and-probe checker named in docs/artifact-lifecycle-frontier.md. A
+* generated MCP server is only a candidate if it actually *serves* — so this
+* boots it over stdio (the default local MCP transport) and runs the real
+* handshake: `initialize` → `notifications/initialized` → `tools/list`, and
+* asserts the server answers with at least `minTools` tools.
+*
+* The spawn + handshake is the SHARED same-host stdio connection
+* (`connectStdioMcp`) — the same code path that later serves the built server
+* LIVE to a scored run (`materializeLocalMcp`), so "verified it serves" and
+* "served while scored" can never drift apart.
+*
+* Outcomes follow the `Verifier` contract: a server that fails to start, exits
+* early, errors the handshake, times out, or exposes no tools is a FAILED
+* candidate (`{ok:false}`, fed back into the next generation shot); a missing
+* start binary or spawn fault THROWS (a setup bug, never a silent fallback).
+*/
+/** Build a `Verifier` that boots a generated MCP server over stdio and checks it exposes tools. */
 function mcpServeVerifier(spec) {
-  const minTools = spec.minTools ?? 1;
-  return async (worktreePath) => {
-    let conn;
-    try {
-      conn = await connectStdioMcp({
-        command: spec.command,
-        ...spec.args ? { args: spec.args } : {},
-        cwd: worktreePath,
-        ...spec.env ? { env: spec.env } : {},
-        ...spec.timeoutMs !== void 0 ? { timeoutMs: spec.timeoutMs } : {}
-      });
-    } catch (err) {
-      if (err instanceof McpSpawnFault) {
-        throw new Error(`mcpServeVerifier: ${err.message}`);
-      }
-      return { ok: false, feedback: err instanceof Error ? err.message : String(err) };
-    }
-    try {
-      if (conn.tools.length < minTools) {
-        return {
-          ok: false,
-          feedback: `tools/list returned ${conn.tools.length} tool(s), need >= ${minTools}`
-        };
-      }
-      return { ok: true };
-    } finally {
-      await conn.close();
-    }
-  };
-}
-
-// src/improvement/profile-diff-proposer.ts
-import { canonicalJson } from "@tangle-network/agent-eval";
-import {
-  changedAgentProfileAxes
-} from "@tangle-network/agent-interface";
-function profileDiffProposer(options) {
-  return {
-    kind: "agent-profile-diff",
-    async propose(ctx) {
-      if (typeof ctx.currentSurface !== "string") {
-        throw new Error("profileDiffProposer requires a serialized AgentProfile surface");
-      }
-      const profile = parseSerializedProfile(ctx.currentSurface);
-      const proposals = await options.proposeDiffs({
-        ...ctx,
-        profile
-      });
-      const candidates = [];
-      const normalizedBaseline = applyExactAgentProfileDiff(
-        profile,
-        { kind: "agent-profile-diff" },
-        "profile diff baseline"
-      );
-      const seen = /* @__PURE__ */ new Set([canonicalJson(normalizedBaseline)]);
-      for (const [index, proposal] of proposals.entries()) {
-        if (candidates.length >= ctx.populationSize || ctx.signal.aborted) break;
-        const diff = parseExactAgentProfileDiff(proposal, `profile diff proposal ${index}`);
-        const axes = changedAgentProfileAxes(diff);
-        if (axes.length === 0) continue;
-        const candidate = applyExactAgentProfileDiff(
-          profile,
-          diff,
-          `profile diff candidate ${index}`
-        );
-        const surface = canonicalJson(candidate);
-        if (seen.has(surface)) continue;
-        seen.add(surface);
-        candidates.push({
-          surface,
-          label: diff.title ?? diff.id ?? `Change ${axes.join(", ")}`,
-          rationale: candidateRationale(diff, axes)
-        });
-      }
-      return candidates;
-    }
-  };
-}
-function candidateRationale(diff, axes) {
-  const reason = diff.rationale ?? `Changes profile axes: ${axes.join(", ")}.`;
-  const source = diff.source ? [diff.source.kind, ...diff.source.artifacts ?? []].join(" \xB7 ") : "source unspecified";
-  return `${reason} Source: ${source}. Diff: ${canonicalCandidateDigest(diff)}.`;
-}
-function parseSerializedProfile(surface) {
-  let raw;
-  try {
-    raw = JSON.parse(surface);
-  } catch (cause) {
-    throw new Error("profileDiffProposer current surface is not valid AgentProfile JSON", {
-      cause
-    });
-  }
-  return parseExactAgentProfile(raw, "profileDiffProposer current profile");
-}
-
-// src/improvement/reflective-generator.ts
-import { spawnSync as spawnSync2 } from "child_process";
+	const minTools = spec.minTools ?? 1;
+	return async (worktreePath) => {
+		let conn;
+		try {
+			conn = await connectStdioMcp({
+				command: spec.command,
+				...spec.args ? { args: spec.args } : {},
+				cwd: worktreePath,
+				...spec.env ? { env: spec.env } : {},
+				...spec.timeoutMs !== void 0 ? { timeoutMs: spec.timeoutMs } : {}
+			});
+		} catch (err) {
+			if (err instanceof McpSpawnFault) throw new Error(`mcpServeVerifier: ${err.message}`);
+			return {
+				ok: false,
+				feedback: err instanceof Error ? err.message : String(err)
+			};
+		}
+		try {
+			if (conn.tools.length < minTools) return {
+				ok: false,
+				feedback: `tools/list returned ${conn.tools.length} tool(s), need >= ${minTools}`
+			};
+			return { ok: true };
+		} finally {
+			await conn.close();
+		}
+	};
+}
+//#endregion
+//#region src/improvement/official-optimizers.ts
+const defaultMaxFindingsChars = 5e4;
+const pythonClientDocs = "https://github.com/tangle-network/agent-eval/tree/main/clients/python";
+const bridgeInstall = "`python -m pip install \"agent-eval-rpc==0.131.0\"`";
+const gepaWheelInstall = "`python -m pip install \"gepa[full]==0.1.4\"`";
+const gepaSourceInstall = "`python -m pip install \"gepa[full] @ git+https://github.com/gepa-ai/gepa.git@f919db0a622e2e9f9204779b81fe00cc1b2d808f\"`";
+const skillOptInstall = `${bridgeInstall}, then \`python -m pip install "skillopt @ git+https://github.com/microsoft/SkillOpt.git@61735e3922efc2b90c6d6cab561e62e98452ca90"\``;
+/** Missing optional Python dependencies for an official optimizer. */
+var OfficialOptimizerUnavailableError = class extends ConfigError {
+	optimizer;
+	constructor(optimizer, cause) {
+		const detail = cause instanceof Error ? cause.message : String(cause);
+		const install = optimizer === "gepa" ? [
+			`Install the Python bridge: ${bridgeInstall}.`,
+			`The direct GEPA engine uses the published wheel: ${gepaWheelInstall}.`,
+			`Composed recipes and source-only engines use the tested source revision: ${gepaSourceInstall}.`
+		].join(" ") : `Install Microsoft SkillOpt: ${skillOptInstall}.`;
+		super([
+			`Official ${optimizer === "gepa" ? "GEPA" : "SkillOpt"} could not start.`,
+			"Runtime did not use a local fallback.",
+			install,
+			`Setup: ${pythonClientDocs}.`,
+			`Cause: ${detail}`
+		].join(" "), { cause });
+		this.optimizer = optimizer;
+	}
+};
+/**
+* Build a complete method backed by GEPA's official Optimize Anything API.
+*
+* The recipe is passed through unchanged. Use `engine`, `sequential`,
+* `adaptive-sequential`, `best-of`, `vote`, or `omni` explicitly.
+*/
+function officialGepa(options) {
+	const { background, includeFindings = true, maxFindingsChars, describeScenario, describeArtifact, redact, authorizeSensitiveCandidate, ...config } = options;
+	const redactor = resolveRedactor(redact);
+	const redactionPolicyRef = optimizerRedactionPolicyRef(redact);
+	assertMaxFindingsChars("officialGepa", maxFindingsChars);
+	const objective = redactOptimizerText("officialGepa", "objective", config.objective, redactor);
+	return (context) => {
+		const externalEvaluationRef = optimizerEvidencePolicyRef({
+			runtimeEvaluationRef: context.evaluationRef,
+			redactionPolicyRef,
+			describeScenario,
+			describeArtifact,
+			authorizeSensitiveCandidate
+		});
+		return withMethodRuntimeControls(withDependencyHelp("gepa", externalEvaluationRef, redactor, redactionPolicyRef, gepaOptimizationMethod({
+			...config,
+			objective,
+			evaluationId: externalEvaluationRef,
+			background: methodBackground({
+				context,
+				background,
+				includeFindings,
+				maxFindingsChars,
+				label: "officialGepa",
+				redactor
+			}),
+			...describeScenario ? { describeScenario: (scenario) => redactOptimizerEvidence("officialGepa", "scenario descriptor", describeScenario(scenario), redactor) } : {},
+			...describeArtifact ? { describeArtifact: (artifact, scenario) => redactOptimizerEvidence("officialGepa", "artifact descriptor", describeArtifact(artifact, scenario), redactor) } : {}
+		})), {
+			costAttribution: "optimizer-run",
+			validateCandidate: (input) => assertSafeOptimizerCandidate("officialGepa", input, authorizeSensitiveCandidate)
+		});
+	};
+}
+/** Build a complete method backed by Microsoft's official SkillOpt trainer. */
+function officialSkillOpt(options) {
+	const { background, includeFindings = true, maxFindingsChars, describeScenario, describeArtifact, redact, authorizeSensitiveCandidate, ...config } = options;
+	const redactor = resolveRedactor(redact);
+	const redactionPolicyRef = optimizerRedactionPolicyRef(redact);
+	assertMaxFindingsChars("officialSkillOpt", maxFindingsChars);
+	const objective = redactOptimizerText("officialSkillOpt", "objective", config.objective, redactor);
+	return (context) => {
+		const externalEvaluationRef = optimizerEvidencePolicyRef({
+			runtimeEvaluationRef: context.evaluationRef,
+			redactionPolicyRef,
+			describeScenario,
+			describeArtifact,
+			authorizeSensitiveCandidate
+		});
+		return withMethodRuntimeControls(withDependencyHelp("skillopt", externalEvaluationRef, redactor, redactionPolicyRef, skillOptOptimizationMethod({
+			...config,
+			objective,
+			evaluationId: externalEvaluationRef,
+			background: methodBackground({
+				context,
+				background,
+				includeFindings,
+				maxFindingsChars,
+				label: "officialSkillOpt",
+				redactor
+			}),
+			...describeScenario ? { describeScenario: (scenario) => redactOptimizerEvidence("officialSkillOpt", "scenario descriptor", describeScenario(scenario), redactor) } : {},
+			...describeArtifact ? { describeArtifact: (artifact, scenario) => redactOptimizerEvidence("officialSkillOpt", "artifact descriptor", describeArtifact(artifact, scenario), redactor) } : {}
+		})), {
+			costAttribution: "optimizer-run",
+			validateCandidate: (input) => assertSafeOptimizerCandidate("officialSkillOpt", input, authorizeSensitiveCandidate)
+		});
+	};
+}
+function assertMaxFindingsChars(label, value) {
+	if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) throw new ConfigError(`${label}: maxFindingsChars must be a positive safe integer`);
+}
+function methodBackground(options) {
+	const { context, background, includeFindings, maxFindingsChars = defaultMaxFindingsChars, label, redactor } = options;
+	const safeBackground = background === void 0 ? void 0 : redactOptimizerText(label, "background", background, redactor);
+	const safeProfileName = context.profile.name === void 0 ? void 0 : redactOptimizerText(label, "profile name", context.profile.name, redactor);
+	const sections = [safeBackground?.trim(), safeProfileName ? `Agent profile: ${safeProfileName}. Surface: ${context.surface}.` : `Agent surface: ${context.surface}.`].filter((value) => Boolean(value));
+	if (includeFindings && context.findings.length > 0) {
+		let serialized;
+		try {
+			serialized = canonicalJson(redactOptimizerEvidence(label, "findings", context.findings, redactor));
+		} catch (cause) {
+			throw new ConfigError(`${label}: findings must be JSON-serializable`, { cause });
+		}
+		if (serialized.length > maxFindingsChars) throw new ConfigError(`${label}: serialized findings exceed maxFindingsChars (${serialized.length} > ${maxFindingsChars})`);
+		sections.push(`Observed failures:\n${serialized}`);
+	}
+	return sections.join("\n\n");
+}
+function assertSafeOptimizerCandidate(label, input, authorizeSensitiveCandidate) {
+	const redactedValue = defaultRedactor(input.value);
+	const redactedSurface = defaultRedactor(input.candidateSurface);
+	if (!isDeepStrictEqual(input.value, redactedValue) || !isDeepStrictEqual(input.candidateSurface, redactedSurface)) throw new ConfigError(`${label}: the selected profile surface contains a common credential or private value. Store live credentials as provider references, or remove private data before starting an external optimizer.`);
+	const sensitivePaths = sensitiveProfileSurfacePaths(input);
+	if (sensitivePaths.length === 0) return;
+	let authorized = false;
+	if (authorizeSensitiveCandidate) try {
+		authorized = authorizeSensitiveCandidate(Object.freeze({
+			...input,
+			sensitivePaths: Object.freeze([...sensitivePaths])
+		})) === true;
+	} catch (cause) {
+		throw new ConfigError(`${label}: sensitive candidate authorization failed`, { cause });
+	}
+	if (!authorized) throw new ConfigError(`${label}: the selected profile surface contains fields that may carry private values: ${sensitivePaths.slice(0, 8).join(", ")}. Remove them, replace values with safe references, or authorize the exact profile with authorizeSensitiveCandidate.`);
+}
+function sensitiveProfileSurfacePaths(input) {
+	const paths = /* @__PURE__ */ new Set();
+	if (input.surface === "tools" || input.surface === "mcp" || input.surface === "hooks" || input.surface === "subagents" || input.surface === "agent-profile") paths.add("$");
+	const seen = /* @__PURE__ */ new WeakSet();
+	const visit = (current, path) => {
+		if (current === null || typeof current !== "object") return;
+		if (seen.has(current)) return;
+		seen.add(current);
+		if (Array.isArray(current)) {
+			current.forEach((child, index) => {
+				visit(child, `${path}[${index}]`);
+			});
+			return;
+		}
+		for (const [key, child] of Object.entries(current)) {
+			const childPath = `${path}.${key}`;
+			if ([
+				"env",
+				"headers",
+				"url",
+				"metadata",
+				"extensions"
+			].includes(key.toLowerCase())) {
+				paths.add(childPath);
+				continue;
+			}
+			visit(child, childPath);
+		}
+	};
+	visit(input.value, "$");
+	return [...paths];
+}
+function redactOptimizerEvidence(label, field, value, redactor) {
+	try {
+		return redactor(value);
+	} catch (cause) {
+		throw new ConfigError(`${label}: ${field} redaction failed`, { cause });
+	}
+}
+function redactOptimizerText(label, field, value, redactor) {
+	const redacted = redactOptimizerEvidence(label, field, value, redactor);
+	if (typeof redacted !== "string" || !redacted.trim()) throw new ConfigError(`${label}: ${field} redaction must return a non-empty string`);
+	return redacted;
+}
+function redactJudgeScore(score, redactor) {
+	const notes = redactOptimizerEvidence("official optimizer", "judge notes", score.notes, redactor);
+	return {
+		...score,
+		notes: typeof notes === "string" ? notes : "[redacted]"
+	};
+}
+function optimizerRedactionPolicyRef(redact, builtInIdentity = defaultRedactorIdentityMaterial()) {
+	if (redact === false) return "caller-approved-raw";
+	return canonicalCandidateDigest({
+		kind: redact === void 0 ? "default-redactor" : "caller-redactor-with-default",
+		builtIn: builtInIdentity,
+		...redact === void 0 ? {} : {
+			callerSource: Function.prototype.toString.call(redact),
+			composition: Function.prototype.toString.call(resolveRedactor)
+		}
+	});
+}
+function optimizerEvidencePolicyRef(input) {
+	return canonicalCandidateDigest({
+		runtimeEvaluationRef: input.runtimeEvaluationRef,
+		redactionPolicyRef: input.redactionPolicyRef,
+		describeScenario: callbackSource(input.describeScenario),
+		describeArtifact: callbackSource(input.describeArtifact),
+		authorizeSensitiveCandidate: callbackSource(input.authorizeSensitiveCandidate)
+	});
+}
+function callbackSource(callback) {
+	return typeof callback === "function" ? Function.prototype.toString.call(callback) : null;
+}
+function withDependencyHelp(optimizer, evaluationRef, redactor, redactionPolicyRef, method) {
+	return {
+		...method,
+		async optimize(input) {
+			try {
+				const judges = input.judges.map((judge) => Object.freeze({
+					...judge,
+					judgeVersion: canonicalCandidateDigest({
+						evaluationRef,
+						name: judge.name,
+						dimensions: judge.dimensions,
+						judgeVersion: judge.judgeVersion ?? null,
+						outwardEvidence: redactionPolicyRef
+					}),
+					async score(scoreInput) {
+						return redactJudgeScore(await judge.score(scoreInput), redactor);
+					}
+				}));
+				return await method.optimize({
+					...input,
+					judges: Object.freeze(judges)
+				});
+			} catch (cause) {
+				if (isMissingDependency(optimizer, cause)) throw new OfficialOptimizerUnavailableError(optimizer, cause);
+				throw cause;
+			}
+		}
+	};
+}
+function isMissingDependency(optimizer, cause) {
+	const message = cause instanceof Error ? cause.message : String(cause);
+	const common = [
+		`${optimizer === "gepa" ? "GEPA" : "SkillOpt"} bridge could not start`,
+		"source inspection could not start",
+		"No module named 'agent_eval_rpc'",
+		`No module named 'agent_eval_rpc.${optimizer === "gepa" ? "gepa_bridge" : "skillopt_bridge"}'`
+	];
+	const specific = optimizer === "gepa" ? [
+		"requires GEPA",
+		"requires GEPA's Optimize Anything",
+		"No module named 'gepa'",
+		"gepa is importable but its package metadata is unavailable"
+	] : [
+		"requires skillopt",
+		"requires SkillOpt",
+		"No module named 'skillopt'",
+		"skillopt is importable but its package metadata is unavailable"
+	];
+	return [...common, ...specific].some((fragment) => message.includes(fragment));
+}
+//#endregion
+//#region src/improvement/reflective-generator.ts
+/**
+*
+* `reflectiveGenerator` — the cheap, no-sandbox `CandidateGenerator`. It drafts
+* surface edits via the existing improvement proposer (`proposeFromFindings`,
+* one LLM patch per finding) and applies them as ONE coherent improvement into
+* the candidate worktree. `maxShots` is ignored — reflection is single-shot by
+* construction (the patches are already drafted).
+*
+* This is the `shots=1, sandbox=off` code-candidate setting.
+* `agenticGenerator` supplies the multi-shot verify-in-session setting.
+*
+* @experimental
+*/
+/** Cheap no-sandbox `CandidateGenerator` (the `shots=1` setting): draft surface edits via the improvement adapter and apply them as one coherent candidate. */
 function reflectiveGenerator(opts) {
-  return {
-    kind: "reflective",
-    async generate({ worktreePath, findings }) {
-      const batch = await opts.improvementProposalSource.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 };
-    }
-  };
-}
+	return {
+		kind: "reflective",
+		async generate({ worktreePath, findings }) {
+			const batch = await opts.improvementProposalSource.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: ""
+			};
+			return {
+				applied: true,
+				summary: batch.edits.length === 1 ? batch.edits[0].summary : `analyst: ${applied} surface edit${applied === 1 ? "" : "s"}`
+			};
+		}
+	};
+}
+/** Apply a proposed patch inside the isolated candidate worktree.
+*  candidate worktree (a fresh checkout of baseRef, so `-p0` paths match). */
 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;
+	return spawnSync("git", [
+		"apply",
+		"--whitespace=fix",
+		"-p0",
+		"-"
+	], {
+		cwd,
+		input: patch,
+		encoding: "utf-8"
+	}).status === 0;
+}
+//#endregion
+//#region src/readiness.ts
+const DEFAULT_MINIMUM_READINESS_SCORE = .7;
+/**
+* Map a `KnowledgeReadinessReport` to a three-state branch (`ready` / `blocked` / `caveat`) the runtime, route handlers, and UI shells all switch on.
+*
+* @stable
+*/
 function decideKnowledgeReadiness(report, options = {}) {
-  const minimumScore = options.minimumScore ?? DEFAULT_MINIMUM_READINESS_SCORE;
-  if (!Number.isFinite(minimumScore) || minimumScore < 0 || minimumScore > 1) {
-    throw new ValidationError(
-      `minimumScore must be a finite number in [0, 1]; received ${String(minimumScore)}`
-    );
-  }
-  const blockingGapIds = report.blockingMissingRequirements.map((requirement) => requirement.id);
-  const nonBlockingGapIds = report.nonBlockingGaps.map((requirement) => requirement.id);
-  if (blockingGapIds.length > 0) {
-    return {
-      passed: false,
-      status: "blocked",
-      reason: report.reason,
-      readinessScore: report.readinessScore,
-      recommendedAction: report.recommendedAction,
-      severity: report.severity,
-      blockingGapIds,
-      nonBlockingGapIds
-    };
-  }
-  if (report.readinessScore < minimumScore) {
-    return {
-      passed: false,
-      status: "caveat",
-      reason: `Knowledge readiness score ${report.readinessScore.toFixed(3)} is below minimum ${minimumScore.toFixed(3)}.`,
-      readinessScore: report.readinessScore,
-      recommendedAction: report.recommendedAction,
-      severity: report.severity,
-      blockingGapIds,
-      nonBlockingGapIds
-    };
-  }
-  return {
-    passed: true,
-    status: "ready",
-    reason: report.reason,
-    readinessScore: report.readinessScore,
-    recommendedAction: report.recommendedAction,
-    severity: report.severity,
-    blockingGapIds,
-    nonBlockingGapIds
-  };
-}
-
-// src/resolve-agent-backend.ts
+	const minimumScore = options.minimumScore ?? DEFAULT_MINIMUM_READINESS_SCORE;
+	if (!Number.isFinite(minimumScore) || minimumScore < 0 || minimumScore > 1) throw new ValidationError(`minimumScore must be a finite number in [0, 1]; received ${String(minimumScore)}`);
+	const blockingGapIds = report.blockingMissingRequirements.map((requirement) => requirement.id);
+	const nonBlockingGapIds = report.nonBlockingGaps.map((requirement) => requirement.id);
+	if (blockingGapIds.length > 0) return {
+		passed: false,
+		status: "blocked",
+		reason: report.reason,
+		readinessScore: report.readinessScore,
+		recommendedAction: report.recommendedAction,
+		severity: report.severity,
+		blockingGapIds,
+		nonBlockingGapIds
+	};
+	if (report.readinessScore < minimumScore) return {
+		passed: false,
+		status: "caveat",
+		reason: `Knowledge readiness score ${report.readinessScore.toFixed(3)} is below minimum ${minimumScore.toFixed(3)}.`,
+		readinessScore: report.readinessScore,
+		recommendedAction: report.recommendedAction,
+		severity: report.severity,
+		blockingGapIds,
+		nonBlockingGapIds
+	};
+	return {
+		passed: true,
+		status: "ready",
+		reason: report.reason,
+		readinessScore: report.readinessScore,
+		recommendedAction: report.recommendedAction,
+		severity: report.severity,
+		blockingGapIds,
+		nonBlockingGapIds
+	};
+}
+//#endregion
+//#region src/resolve-agent-backend.ts
+/**
+* The product-facing backend selector for `runChatThroughRuntime` /
+* `runAgentTaskStream`: one call turns a `--backend {router,tcloud,cli-bridge,
+* sandbox}` choice into the `AgentExecutionBackend` the chat leg runs on.
+*
+* It is the `AgentExecutionBackend` sibling of `resolveSandboxClient` (which
+* resolves the `SandboxClient` a `runAgentRounds` drives). Both exist for the same
+* reason: every in-process eval product hand-rolled the identical
+* "`backend-name` → `createOpenAICompatibleBackend`" branch, and the copies
+* drift. This is the single generic resolver they share.
+*
+*   - `router` / `tcloud` / `cli-bridge` → OpenAI-compatible chat completions.
+*     All three speak `POST {baseUrl}/chat/completions` in OpenAI's SSE shape —
+*     the router (a.k.a. tcloud) IS that endpoint, and cli-bridge fronts a
+*     harness CLI behind the same protocol at its own `/v1`. They differ only
+*     in `baseUrl` / `apiKey` and the `kind` label a product wants on its
+*     traces. cli-bridge REQUIRES `model` in the request body, so it MUST route
+*     through `createOpenAICompatibleBackend` (which sends it), never a
+*     transport that drops the field.
+*   - `sandbox` → the caller's own domain backend. The sandbox variant carries
+*     product specifics (system prompt, workspace id, in-box D1 executor) that
+*     do NOT belong in the substrate, so the product passes a `sandboxBackend()`
+*     seam that this resolver simply invokes.
+*
+* This resolver is PURE backend selection. Product concerns — credit hard-cuts,
+* fetch-capture shims, D1 platform wiring — stay as product-side WRAPPERS
+* around the returned backend. The OpenAI-compat passthrough fields (`tools`,
+* `toolChoice`, `responseFormat`, `temperature`, `maxTokens`, `fetchImpl`,
+* `retry`) are forwarded verbatim so a product can advertise its app tools,
+* preserve generation settings, or install a capturing fetch without
+* re-opening the branch this consolidation closes.
+*/
+/**
+* Resolve the `AgentExecutionBackend` for the chosen `kind`. Reuse this instead
+* of hand-rolling the `createOpenAICompatibleBackend` branch in each product.
+*/
 function resolveAgentBackend(opts) {
-  switch (opts.kind) {
-    case "router":
-    case "tcloud":
-    case "cli-bridge": {
-      const passthrough = {};
-      if (opts.tools !== void 0) passthrough.tools = opts.tools;
-      if (opts.toolChoice !== void 0) passthrough.toolChoice = opts.toolChoice;
-      if (opts.responseFormat !== void 0) passthrough.responseFormat = opts.responseFormat;
-      if (opts.temperature !== void 0) passthrough.temperature = opts.temperature;
-      if (opts.maxTokens !== void 0) passthrough.maxTokens = opts.maxTokens;
-      if (opts.fetchImpl !== void 0) passthrough.fetchImpl = opts.fetchImpl;
-      if (opts.retry !== void 0) passthrough.retry = opts.retry;
-      return createOpenAICompatibleBackend({
-        apiKey: opts.apiKey,
-        baseUrl: opts.baseUrl,
-        model: opts.model,
-        kind: opts.label ?? opts.kind,
-        ...passthrough
-      });
-    }
-    case "sandbox": {
-      if (!opts.sandboxBackend) {
-        throw new Error("resolveAgentBackend: kind 'sandbox' requires opts.sandboxBackend");
-      }
-      return opts.sandboxBackend();
-    }
-  }
-}
-
-// src/run.ts
-import {
-  acquisitionPlansForKnowledgeGaps,
-  blockingKnowledgeEval,
-  FAILURE_CLASSES,
-  runAgentControlLoop,
-  scoreKnowledgeReadiness,
-  userQuestionsForKnowledgeGaps
-} from "@tangle-network/agent-eval";
-var FAILURE_CLASS_SET = new Set(FAILURE_CLASSES);
+	switch (opts.kind) {
+		case "router":
+		case "tcloud":
+		case "cli-bridge": {
+			const passthrough = {};
+			if (opts.tools !== void 0) passthrough.tools = opts.tools;
+			if (opts.toolChoice !== void 0) passthrough.toolChoice = opts.toolChoice;
+			if (opts.responseFormat !== void 0) passthrough.responseFormat = opts.responseFormat;
+			if (opts.temperature !== void 0) passthrough.temperature = opts.temperature;
+			if (opts.maxTokens !== void 0) passthrough.maxTokens = opts.maxTokens;
+			if (opts.fetchImpl !== void 0) passthrough.fetchImpl = opts.fetchImpl;
+			if (opts.retry !== void 0) passthrough.retry = opts.retry;
+			return createOpenAICompatibleBackend({
+				apiKey: opts.apiKey,
+				baseUrl: opts.baseUrl,
+				model: opts.model,
+				kind: opts.label ?? opts.kind,
+				...passthrough
+			});
+		}
+		case "sandbox":
+			if (!opts.sandboxBackend) throw new Error("resolveAgentBackend: kind 'sandbox' requires opts.sandboxBackend");
+			return opts.sandboxBackend();
+	}
+}
+//#endregion
+//#region src/run.ts
+/**
+*
+* The two top-level entry points:
+*
+*  - `runAgentTask` — single-shot lifecycle for adapter-driven tasks.
+*  - `runAgentTaskStream` — streaming lifecycle that delegates execution to an
+*    `AgentExecutionBackend` (model API, sandbox, or custom iterable).
+*
+* Both gate the run on `KnowledgeReadinessReport` from `agent-eval`, emit the
+* same lifecycle event vocabulary (under different shapes — see `types.ts`),
+* and route session lifecycle through a pluggable `RuntimeSessionStore`.
+*
+* @stable
+*/
+const FAILURE_CLASS_SET = new Set(FAILURE_CLASSES);
+/** True when a free-form control failure string is a canonical taxonomy
+*  class — so only real taxonomy tags are promoted to the cross-agent
+*  `RunRecord.failureClass` key; novel strings stay as `failureMode` detail. */
 function asFailureClass(value) {
-  return value && FAILURE_CLASS_SET.has(value) ? value : void 0;
-}
+	return value && FAILURE_CLASS_SET.has(value) ? value : void 0;
+}
+/** Stamp cross-cutting defaults onto adapter-projected RunRecords without
+*  overriding anything the adapter set explicitly:
+*   - `scenarioId` — the run's scenario, when the record omits one.
+*   - `failureClass` — the control layer's failure classification promoted
+*     onto the canonical cross-agent key, but ONLY when it's a real taxonomy
+*     class. This is what lets the substrate aggregate failures across every
+*     agent in one vocabulary instead of per-agent ad-hoc strings. */
 function applyRunRecordDefaults(records, scenarioId, controlFailureClass) {
-  const fc = asFailureClass(controlFailureClass);
-  return records.map((record) => {
-    let r = record;
-    if (r.scenarioId === void 0) r = { ...r, scenarioId };
-    if (r.failureClass === void 0 && fc) r = { ...r, failureClass: fc };
-    return r;
-  });
-}
+	const fc = asFailureClass(controlFailureClass);
+	return records.map((record) => {
+		let r = record;
+		if (r.scenarioId === void 0) r = {
+			...r,
+			scenarioId
+		};
+		if (r.failureClass === void 0 && fc) r = {
+			...r,
+			failureClass: fc
+		};
+		return r;
+	});
+}
+/**
+* Single-shot task lifecycle for adapter-driven tasks: readiness-gated, emits the runtime lifecycle event vocabulary, session-store pluggable.
+*
+* @stable
+*/
 async function runAgentTask(options) {
-  const task = options.task;
-  await emit(options.onEvent, { type: "task_start", task });
-  await emit(options.onEvent, { type: "readiness_start", task });
-  let knowledge = await buildReadiness(task, options.knowledge);
-  await emit(options.onEvent, { type: "readiness_end", task, knowledge });
-  const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements);
-  const acquisitionPlans = acquisitionPlansForKnowledgeGaps([
-    ...knowledge.blockingMissingRequirements,
-    ...knowledge.nonBlockingGaps
-  ]);
-  const preflight = await runKnowledgePreflight(
-    task,
-    questions,
-    acquisitionPlans,
-    options.knowledge,
-    options.onEvent
-  );
-  if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
-    await emit(options.onEvent, { type: "readiness_start", task });
-    knowledge = await options.knowledge.refreshReadiness({
-      task,
-      previous: knowledge,
-      userAnswers: preflight.userAnswers,
-      acquiredEvidenceIds: preflight.acquiredEvidenceIds
-    });
-    await emit(options.onEvent, { type: "readiness_end", task, knowledge });
-  }
-  await emit(options.onEvent, { type: "control_start", task, knowledge });
-  const scenarioId = options.scenarioId ?? task.id;
-  const control = await runAgentControlLoop({
-    intent: task.intent,
-    budget: task.budget,
-    signal: options.signal,
-    store: options.store,
-    scenarioId,
-    projectId: options.projectId,
-    variantId: options.variantId,
-    observe: ({ history, abortSignal }) => options.adapter.observe({ task, knowledge, history, abortSignal }),
-    validate: async ({ state, history, abortSignal }) => {
-      const readinessEval = blockingKnowledgeEval(knowledge, {
-        minimumScore: options.minimumReadinessScore
-      });
-      const evals = await options.adapter.validate({
-        task,
-        knowledge,
-        state,
-        history,
-        abortSignal
-      });
-      return [readinessEval, ...evals];
-    },
-    decide: (ctx) => {
-      if (isKnowledgeBlocked(ctx.evals)) {
-        return options.adapter.onKnowledgeBlocked?.({
-          task,
-          knowledge,
-          questions,
-          acquisitionPlans
-        }) ?? {
-          type: "stop",
-          pass: false,
-          score: knowledge.readinessScore,
-          reason: `knowledge readiness blocked: ${knowledge.reason}`
-        };
-      }
-      return options.adapter.decide(toAgentContext(task, knowledge, ctx));
-    },
-    act: (action, ctx) => options.adapter.act(action, toAgentContext(task, knowledge, ctx)),
-    shouldStop: options.adapter.shouldStop ? (ctx) => options.adapter.shouldStop(toAgentContext(task, knowledge, ctx)) : void 0,
-    getActionCostUsd: options.adapter.getActionCostUsd ? ({ action, result, state, evals, history }) => options.adapter.getActionCostUsd({ action, result, task, state, evals, history }) : void 0,
-    onStep: (step) => emit(options.onEvent, { type: "control_step", task, step })
-  });
-  await emit(options.onEvent, { type: "control_end", task, control });
-  const status = statusFromControl(control);
-  await emit(options.onEvent, { type: "task_end", task, status, reason: control.reason });
-  return {
-    task,
-    status,
-    knowledge,
-    questions,
-    acquisitionPlans,
-    userAnswers: preflight.userAnswers,
-    acquiredEvidenceIds: preflight.acquiredEvidenceIds,
-    control,
-    runRecords: applyRunRecordDefaults(
-      options.adapter.projectRunRecords?.(control, task) ?? [],
-      scenarioId,
-      control.failureClass
-    )
-  };
-}
+	const task = options.task;
+	await emit(options.onEvent, {
+		type: "task_start",
+		task
+	});
+	await emit(options.onEvent, {
+		type: "readiness_start",
+		task
+	});
+	let knowledge = await buildReadiness(task, options.knowledge);
+	await emit(options.onEvent, {
+		type: "readiness_end",
+		task,
+		knowledge
+	});
+	const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements);
+	const acquisitionPlans = acquisitionPlansForKnowledgeGaps([...knowledge.blockingMissingRequirements, ...knowledge.nonBlockingGaps]);
+	const preflight = await runKnowledgePreflight(task, questions, acquisitionPlans, options.knowledge, options.onEvent);
+	if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
+		await emit(options.onEvent, {
+			type: "readiness_start",
+			task
+		});
+		knowledge = await options.knowledge.refreshReadiness({
+			task,
+			previous: knowledge,
+			userAnswers: preflight.userAnswers,
+			acquiredEvidenceIds: preflight.acquiredEvidenceIds
+		});
+		await emit(options.onEvent, {
+			type: "readiness_end",
+			task,
+			knowledge
+		});
+	}
+	await emit(options.onEvent, {
+		type: "control_start",
+		task,
+		knowledge
+	});
+	const scenarioId = options.scenarioId ?? task.id;
+	const control = await runAgentControlLoop({
+		intent: task.intent,
+		budget: task.budget,
+		signal: options.signal,
+		store: options.store,
+		scenarioId,
+		projectId: options.projectId,
+		variantId: options.variantId,
+		observe: ({ history, abortSignal }) => options.adapter.observe({
+			task,
+			knowledge,
+			history,
+			abortSignal
+		}),
+		validate: async ({ state, history, abortSignal }) => {
+			return [blockingKnowledgeEval(knowledge, { minimumScore: options.minimumReadinessScore }), ...await options.adapter.validate({
+				task,
+				knowledge,
+				state,
+				history,
+				abortSignal
+			})];
+		},
+		decide: (ctx) => {
+			if (isKnowledgeBlocked(ctx.evals)) return options.adapter.onKnowledgeBlocked?.({
+				task,
+				knowledge,
+				questions,
+				acquisitionPlans
+			}) ?? {
+				type: "stop",
+				pass: false,
+				score: knowledge.readinessScore,
+				reason: `knowledge readiness blocked: ${knowledge.reason}`
+			};
+			return options.adapter.decide(toAgentContext(task, knowledge, ctx));
+		},
+		act: (action, ctx) => options.adapter.act(action, toAgentContext(task, knowledge, ctx)),
+		shouldStop: options.adapter.shouldStop ? (ctx) => options.adapter.shouldStop(toAgentContext(task, knowledge, ctx)) : void 0,
+		getActionCostUsd: options.adapter.getActionCostUsd ? ({ action, result, state, evals, history }) => options.adapter.getActionCostUsd({
+			action,
+			result,
+			task,
+			state,
+			evals,
+			history
+		}) : void 0,
+		onStep: (step) => emit(options.onEvent, {
+			type: "control_step",
+			task,
+			step
+		})
+	});
+	await emit(options.onEvent, {
+		type: "control_end",
+		task,
+		control
+	});
+	const status = statusFromControl(control);
+	await emit(options.onEvent, {
+		type: "task_end",
+		task,
+		status,
+		reason: control.reason
+	});
+	return {
+		task,
+		status,
+		knowledge,
+		questions,
+		acquisitionPlans,
+		userAnswers: preflight.userAnswers,
+		acquiredEvidenceIds: preflight.acquiredEvidenceIds,
+		control,
+		runRecords: applyRunRecordDefaults(options.adapter.projectRunRecords?.(control, task) ?? [], scenarioId, control.failureClass)
+	};
+}
+/**
+* Streaming task lifecycle: delegates execution to an `AgentExecutionBackend` (model API, sandbox, or custom iterable) and yields lifecycle events as they happen.
+*
+* @stable
+*/
 async function* runAgentTaskStream(options) {
-  const task = options.task;
-  const input = { task, ...options.input ?? {} };
-  yield streamEvent({ type: "task_start", task });
-  yield streamEvent({ type: "readiness_start", task });
-  let knowledge = await buildReadiness(task, options.knowledge);
-  const questions = userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements);
-  const acquisitionPlans = acquisitionPlansForKnowledgeGaps([
-    ...knowledge.blockingMissingRequirements,
-    ...knowledge.nonBlockingGaps
-  ]);
-  const preflight = await runKnowledgePreflightStream(
-    task,
-    questions,
-    acquisitionPlans,
-    options.knowledge
-  );
-  for (const event of preflight.events) yield event;
-  if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
-    yield streamEvent({ type: "readiness_start", task });
-    knowledge = await options.knowledge.refreshReadiness({
-      task,
-      previous: knowledge,
-      userAnswers: preflight.userAnswers,
-      acquiredEvidenceIds: preflight.acquiredEvidenceIds
-    });
-  }
-  const decision = decideKnowledgeReadiness(knowledge, {
-    minimumScore: options.minimumReadinessScore
-  });
-  yield streamEvent({ type: "readiness_end", task, knowledge, decision });
-  if (!decision.passed && decision.status === "blocked") {
-    const reason = `knowledge readiness blocked: ${decision.reason}`;
-    yield streamEvent({ type: "task_end", task, status: "blocked", reason });
-    yield streamEvent({ type: "final", task, status: "blocked", reason });
-    return;
-  }
-  const store = options.sessionStore;
-  const opened = await startOrResumeRuntimeSession({
-    backend: options.backend,
-    input,
-    context: { task, knowledge, signal: options.signal },
-    store,
-    sessionId: options.sessionId,
-    resume: options.resume
-  });
-  let session = opened.session;
-  const shouldResume = opened.resumed;
-  const sessionEvent = streamEvent({
-    type: shouldResume ? "session_resumed" : "session_created",
-    task,
-    session
-  });
-  await store?.appendEvent?.(session.id, sessionEvent);
-  yield sessionEvent;
-  const backendStart = streamEvent({
-    type: "backend_start",
-    task,
-    session,
-    backend: options.backend.kind
-  });
-  await store?.appendEvent?.(session.id, backendStart);
-  yield backendStart;
-  let finalText = "";
-  try {
-    for await (const rawEvent of options.backend.stream(opened.input, {
-      task,
-      knowledge,
-      session,
-      signal: options.signal
-    })) {
-      const event = normalizeBackendStreamEvent(rawEvent, task, session);
-      if (event.type === "text_delta") finalText += event.text;
-      await store?.appendEvent?.(session.id, event);
-      yield event;
-    }
-    const completedStatus = "completed";
-    session = touchSession({ ...session, status: completedStatus });
-    await store?.put(session);
-    const backendEnd = streamEvent({
-      type: "backend_end",
-      task,
-      session,
-      backend: options.backend.kind
-    });
-    await store?.appendEvent?.(session.id, backendEnd);
-    yield backendEnd;
-    const reason = "backend completed";
-    const taskEnd = streamEvent({ type: "task_end", task, status: completedStatus, reason });
-    await store?.appendEvent?.(session.id, taskEnd);
-    yield taskEnd;
-    const final = streamEvent({
-      type: "final",
-      task,
-      session,
-      status: completedStatus,
-      reason,
-      text: finalText || void 0
-    });
-    await store?.appendEvent?.(session.id, final);
-    yield final;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    session = touchSession({ ...session, status: options.signal?.aborted ? "aborted" : "failed" });
-    await store?.put(session);
-    let stopErrorMessage;
-    try {
-      await options.backend.stop?.(session, message);
-    } catch (stopErr) {
-      stopErrorMessage = stopErr instanceof Error ? stopErr.message : String(stopErr);
-    }
-    const combinedMessage = stopErrorMessage ? `${message}; backend stop failed: ${stopErrorMessage}` : message;
-    const errorDetail = err instanceof BackendTransportError ? {
-      kind: "transport",
-      message: combinedMessage,
-      status: err.status,
-      body: err.body
-    } : { kind: "backend", message: combinedMessage };
-    const backendError = streamEvent({
-      type: "backend_error",
-      task,
-      session,
-      backend: options.backend.kind,
-      message: combinedMessage,
-      recoverable: !options.signal?.aborted,
-      error: errorDetail
-    });
-    await store?.appendEvent?.(session.id, backendError);
-    yield backendError;
-    const status = options.signal?.aborted ? "aborted" : "failed";
-    const taskEnd = streamEvent({ type: "task_end", task, status, reason: message });
-    await store?.appendEvent?.(session.id, taskEnd);
-    yield taskEnd;
-    const final = streamEvent({
-      type: "final",
-      task,
-      session,
-      status,
-      reason: message,
-      text: finalText || void 0,
-      error: errorDetail
-    });
-    await store?.appendEvent?.(session.id, final);
-    yield final;
-  }
+	const task = options.task;
+	const input = {
+		task,
+		...options.input ?? {}
+	};
+	yield streamEvent({
+		type: "task_start",
+		task
+	});
+	yield streamEvent({
+		type: "readiness_start",
+		task
+	});
+	let knowledge = await buildReadiness(task, options.knowledge);
+	const preflight = await runKnowledgePreflightStream(task, userQuestionsForKnowledgeGaps(knowledge.blockingMissingRequirements), acquisitionPlansForKnowledgeGaps([...knowledge.blockingMissingRequirements, ...knowledge.nonBlockingGaps]), options.knowledge);
+	for (const event of preflight.events) yield event;
+	if (options.knowledge?.refreshReadiness && (Object.keys(preflight.userAnswers).length > 0 || preflight.acquiredEvidenceIds.length > 0)) {
+		yield streamEvent({
+			type: "readiness_start",
+			task
+		});
+		knowledge = await options.knowledge.refreshReadiness({
+			task,
+			previous: knowledge,
+			userAnswers: preflight.userAnswers,
+			acquiredEvidenceIds: preflight.acquiredEvidenceIds
+		});
+	}
+	const decision = decideKnowledgeReadiness(knowledge, { minimumScore: options.minimumReadinessScore });
+	yield streamEvent({
+		type: "readiness_end",
+		task,
+		knowledge,
+		decision
+	});
+	if (!decision.passed && decision.status === "blocked") {
+		const reason = `knowledge readiness blocked: ${decision.reason}`;
+		yield streamEvent({
+			type: "task_end",
+			task,
+			status: "blocked",
+			reason
+		});
+		yield streamEvent({
+			type: "final",
+			task,
+			status: "blocked",
+			reason
+		});
+		return;
+	}
+	const store = options.sessionStore;
+	const opened = await startOrResumeRuntimeSession({
+		backend: options.backend,
+		input,
+		context: {
+			task,
+			knowledge,
+			signal: options.signal
+		},
+		store,
+		sessionId: options.sessionId,
+		resume: options.resume
+	});
+	let session = opened.session;
+	const shouldResume = opened.resumed;
+	const sessionEvent = streamEvent({
+		type: shouldResume ? "session_resumed" : "session_created",
+		task,
+		session
+	});
+	await store?.appendEvent?.(session.id, sessionEvent);
+	yield sessionEvent;
+	const backendStart = streamEvent({
+		type: "backend_start",
+		task,
+		session,
+		backend: options.backend.kind
+	});
+	await store?.appendEvent?.(session.id, backendStart);
+	yield backendStart;
+	let finalText = "";
+	try {
+		for await (const rawEvent of options.backend.stream(opened.input, {
+			task,
+			knowledge,
+			session,
+			signal: options.signal
+		})) {
+			const event = normalizeBackendStreamEvent(rawEvent, task, session);
+			if (event.type === "text_delta") finalText += event.text;
+			await store?.appendEvent?.(session.id, event);
+			yield event;
+		}
+		const completedStatus = "completed";
+		session = touchSession({
+			...session,
+			status: completedStatus
+		});
+		await store?.put(session);
+		const backendEnd = streamEvent({
+			type: "backend_end",
+			task,
+			session,
+			backend: options.backend.kind
+		});
+		await store?.appendEvent?.(session.id, backendEnd);
+		yield backendEnd;
+		const reason = "backend completed";
+		const taskEnd = streamEvent({
+			type: "task_end",
+			task,
+			status: completedStatus,
+			reason
+		});
+		await store?.appendEvent?.(session.id, taskEnd);
+		yield taskEnd;
+		const final = streamEvent({
+			type: "final",
+			task,
+			session,
+			status: completedStatus,
+			reason,
+			text: finalText || void 0
+		});
+		await store?.appendEvent?.(session.id, final);
+		yield final;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		session = touchSession({
+			...session,
+			status: options.signal?.aborted ? "aborted" : "failed"
+		});
+		await store?.put(session);
+		let stopErrorMessage;
+		try {
+			await options.backend.stop?.(session, message);
+		} catch (stopErr) {
+			stopErrorMessage = stopErr instanceof Error ? stopErr.message : String(stopErr);
+		}
+		const combinedMessage = stopErrorMessage ? `${message}; backend stop failed: ${stopErrorMessage}` : message;
+		const errorDetail = err instanceof BackendTransportError ? {
+			kind: "transport",
+			message: combinedMessage,
+			status: err.status,
+			body: err.body
+		} : {
+			kind: "backend",
+			message: combinedMessage
+		};
+		const backendError = streamEvent({
+			type: "backend_error",
+			task,
+			session,
+			backend: options.backend.kind,
+			message: combinedMessage,
+			recoverable: !options.signal?.aborted,
+			error: errorDetail
+		});
+		await store?.appendEvent?.(session.id, backendError);
+		yield backendError;
+		const status = options.signal?.aborted ? "aborted" : "failed";
+		const taskEnd = streamEvent({
+			type: "task_end",
+			task,
+			status,
+			reason: message
+		});
+		await store?.appendEvent?.(session.id, taskEnd);
+		yield taskEnd;
+		const final = streamEvent({
+			type: "final",
+			task,
+			session,
+			status,
+			reason: message,
+			text: finalText || void 0,
+			error: errorDetail
+		});
+		await store?.appendEvent?.(session.id, final);
+		yield final;
+	}
 }
 async function runKnowledgePreflight(task, questions, acquisitionPlans, provider, onEvent) {
-  let userAnswers = {};
-  let acquiredEvidenceIds = [];
-  if (questions.length > 0 && provider?.answerQuestions) {
-    await emit(onEvent, { type: "questions_start", task, questions });
-    userAnswers = await provider.answerQuestions(questions, task);
-    await emit(onEvent, { type: "questions_end", task, questions, userAnswers });
-  }
-  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
-    await emit(onEvent, { type: "acquisition_start", task, acquisitionPlans });
-    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
-    await emit(onEvent, {
-      type: "acquisition_end",
-      task,
-      acquisitionPlans,
-      acquiredEvidenceIds
-    });
-  }
-  return { userAnswers, acquiredEvidenceIds };
+	let userAnswers = {};
+	let acquiredEvidenceIds = [];
+	if (questions.length > 0 && provider?.answerQuestions) {
+		await emit(onEvent, {
+			type: "questions_start",
+			task,
+			questions
+		});
+		userAnswers = await provider.answerQuestions(questions, task);
+		await emit(onEvent, {
+			type: "questions_end",
+			task,
+			questions,
+			userAnswers
+		});
+	}
+	if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
+		await emit(onEvent, {
+			type: "acquisition_start",
+			task,
+			acquisitionPlans
+		});
+		acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
+		await emit(onEvent, {
+			type: "acquisition_end",
+			task,
+			acquisitionPlans,
+			acquiredEvidenceIds
+		});
+	}
+	return {
+		userAnswers,
+		acquiredEvidenceIds
+	};
 }
 async function runKnowledgePreflightStream(task, questions, acquisitionPlans, provider) {
-  const events = [];
-  let userAnswers = {};
-  let acquiredEvidenceIds = [];
-  if (questions.length > 0 && provider?.answerQuestions) {
-    events.push(streamEvent({ type: "questions_start", task, questions }));
-    userAnswers = await provider.answerQuestions(questions, task);
-    events.push(streamEvent({ type: "questions_end", task, questions, userAnswers }));
-  }
-  if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
-    events.push(streamEvent({ type: "acquisition_start", task, acquisitionPlans }));
-    acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
-    events.push(
-      streamEvent({ type: "acquisition_end", task, acquisitionPlans, acquiredEvidenceIds })
-    );
-  }
-  return { userAnswers, acquiredEvidenceIds, events };
+	const events = [];
+	let userAnswers = {};
+	let acquiredEvidenceIds = [];
+	if (questions.length > 0 && provider?.answerQuestions) {
+		events.push(streamEvent({
+			type: "questions_start",
+			task,
+			questions
+		}));
+		userAnswers = await provider.answerQuestions(questions, task);
+		events.push(streamEvent({
+			type: "questions_end",
+			task,
+			questions,
+			userAnswers
+		}));
+	}
+	if (acquisitionPlans.length > 0 && provider?.executeAcquisitionPlans) {
+		events.push(streamEvent({
+			type: "acquisition_start",
+			task,
+			acquisitionPlans
+		}));
+		acquiredEvidenceIds = await provider.executeAcquisitionPlans(acquisitionPlans, task);
+		events.push(streamEvent({
+			type: "acquisition_end",
+			task,
+			acquisitionPlans,
+			acquiredEvidenceIds
+		}));
+	}
+	return {
+		userAnswers,
+		acquiredEvidenceIds,
+		events
+	};
 }
 function streamEvent(event) {
-  return { ...event, timestamp: nowIso() };
+	return {
+		...event,
+		timestamp: nowIso()
+	};
 }
 function buildReadiness(task, provider) {
-  if (provider?.buildReadiness) return provider.buildReadiness(task);
-  return scoreKnowledgeReadiness({
-    taskId: task.id,
-    requirements: task.requiredKnowledge ?? [],
-    metadata: { domain: task.domain, ...task.metadata }
-  });
+	if (provider?.buildReadiness) return provider.buildReadiness(task);
+	return scoreKnowledgeReadiness({
+		taskId: task.id,
+		requirements: task.requiredKnowledge ?? [],
+		metadata: {
+			domain: task.domain,
+			...task.metadata
+		}
+	});
 }
 function isKnowledgeBlocked(evals) {
-  return evals.some((evalResult) => evalResult.id === "knowledge-ready" && !evalResult.passed);
+	return evals.some((evalResult) => evalResult.id === "knowledge-ready" && !evalResult.passed);
 }
 function statusFromControl(control) {
-  if (control.stoppedBy === "abort") return "aborted";
-  if (control.reason.includes("knowledge readiness blocked")) return "blocked";
-  if (control.pass) return "completed";
-  return "failed";
+	if (control.stoppedBy === "abort") return "aborted";
+	if (control.reason.includes("knowledge readiness blocked")) return "blocked";
+	if (control.pass) return "completed";
+	return "failed";
 }
 async function emit(sink, event) {
-  await sink?.(event);
+	await sink?.(event);
 }
 function toAgentContext(task, knowledge, ctx) {
-  return {
-    task,
-    knowledge,
-    state: ctx.state,
-    evals: ctx.evals,
-    history: ctx.history,
-    budget: ctx.budget,
-    stepIndex: ctx.stepIndex,
-    wallMs: ctx.wallMs,
-    spentCostUsd: ctx.spentCostUsd,
-    remainingCostUsd: ctx.remainingCostUsd,
-    abortSignal: ctx.abortSignal
-  };
-}
-
-// src/runtime-run.ts
+	return {
+		task,
+		knowledge,
+		state: ctx.state,
+		evals: ctx.evals,
+		history: ctx.history,
+		budget: ctx.budget,
+		stepIndex: ctx.stepIndex,
+		wallMs: ctx.wallMs,
+		spentCostUsd: ctx.spentCostUsd,
+		remainingCostUsd: ctx.remainingCostUsd,
+		abortSignal: ctx.abortSignal
+	};
+}
+//#endregion
+//#region src/runtime-run.ts
+/**
+*
+* Production-run lifecycle: record what the agent did on behalf of a customer,
+* what it cost, and how it ended.
+*
+* Three concerns live in this module:
+*
+*  1. **Lifecycle state machine** — `running` -> `completed | failed | cancelled`,
+*     enforced by `RuntimeRunStateError`. Completion is idempotent for the same
+*     status (a second `complete()` call is a no-op so retries / cleanup paths
+*     don't double-fire side effects). A different terminal status is a state
+*     error.
+*
+*  2. **Cost ledger** — every `llm_call` event the handle observes contributes
+*     `tokensIn`, `tokensOut`, `costUsd`, and bumps `llmCalls`. Wall time is
+*     measured from `startRuntimeRun()` to `complete()`. Surface via
+*     `handle.cost()` for cost-per-task dashboards.
+*
+*  3. **Persistence adapter** — `RuntimeRunPersistenceAdapter` is the seam
+*     consumers plug in to write a `RuntimeRunRow` to their D1 / postgres /
+*     KV store. The adapter receives a sanitized row shape; no telemetry
+*     payload bytes flow through it unless the consumer opts in via
+*     `RuntimeRunOptions.telemetryEvents`.
+*
+* @stable
+*/
+/**
+*
+* Construct a runtime-run handle. The returned handle is mutable across its
+* lifetime; consumers should not share it across requests.
+*
+* @stable
+*/
 function startRuntimeRun(options) {
-  if (!options.workspaceId) {
-    throw new ValidationError("startRuntimeRun: workspaceId is required");
-  }
-  if (!options.taskSpec?.id) {
-    throw new ValidationError("startRuntimeRun: taskSpec.id is required");
-  }
-  const now = options.now ?? Date.now;
-  const startedAtMs = now();
-  const startedAt = new Date(startedAtMs).toISOString();
-  const id = options.id ?? `${options.taskSpec.id}:${randomSuffix()}`;
-  let status = "running";
-  let completedAtMs;
-  let resultSummary;
-  let error;
-  let completionMetadata;
-  const ledger = {
-    tokensIn: 0,
-    tokensOut: 0,
-    costUsd: 0,
-    wallMs: 0,
-    llmCalls: 0
-  };
-  const snapshotCost = () => ({
-    tokensIn: ledger.tokensIn,
-    tokensOut: ledger.tokensOut,
-    costUsd: ledger.costUsd,
-    wallMs: (completedAtMs ?? now()) - startedAtMs,
-    llmCalls: ledger.llmCalls
-  });
-  const buildRow = (extraMetadata) => ({
-    id,
-    workspaceId: options.workspaceId,
-    sessionId: options.sessionId,
-    agentId: options.agentId,
-    domain: options.taskSpec.domain,
-    taskId: options.taskSpec.id,
-    scenarioId: options.scenarioId,
-    status,
-    resultSummary,
-    error,
-    cost: snapshotCost(),
-    startedAt,
-    completedAt: completedAtMs !== void 0 ? new Date(completedAtMs).toISOString() : void 0,
-    metadata: mergeMetadata(completionMetadata, extraMetadata)
-  });
-  return {
-    id,
-    workspaceId: options.workspaceId,
-    sessionId: options.sessionId,
-    taskSpec: options.taskSpec,
-    get status() {
-      return status;
-    },
-    observe(event) {
-      if (event.type !== "llm_call") return;
-      ledger.llmCalls += 1;
-      if (typeof event.tokensIn === "number" && Number.isFinite(event.tokensIn)) {
-        ledger.tokensIn += event.tokensIn;
-      }
-      if (typeof event.tokensOut === "number" && Number.isFinite(event.tokensOut)) {
-        ledger.tokensOut += event.tokensOut;
-      }
-      if (typeof event.costUsd === "number" && Number.isFinite(event.costUsd)) {
-        ledger.costUsd += event.costUsd;
-      }
-    },
-    cost: snapshotCost,
-    complete(input) {
-      if (input.status === "running") {
-        throw new ValidationError('complete() requires a terminal status, got "running"');
-      }
-      if (status !== "running") {
-        if (status === input.status) return;
-        throw new RuntimeRunStateError(
-          `Cannot transition runtime run from "${status}" to "${input.status}"`
-        );
-      }
-      status = input.status;
-      completedAtMs = now();
-      resultSummary = input.resultSummary;
-      error = input.error;
-      completionMetadata = input.metadata;
-      if (input.cost) {
-        if (typeof input.cost.tokensIn === "number" && Number.isFinite(input.cost.tokensIn)) {
-          ledger.tokensIn = input.cost.tokensIn;
-        }
-        if (typeof input.cost.tokensOut === "number" && Number.isFinite(input.cost.tokensOut)) {
-          ledger.tokensOut = input.cost.tokensOut;
-        }
-        if (typeof input.cost.costUsd === "number" && Number.isFinite(input.cost.costUsd)) {
-          ledger.costUsd = input.cost.costUsd;
-        }
-        if (typeof input.cost.llmCalls === "number" && Number.isFinite(input.cost.llmCalls)) {
-          ledger.llmCalls = input.cost.llmCalls;
-        }
-      }
-    },
-    toRow(metadata) {
-      return buildRow(metadata);
-    },
-    async persist(metadata) {
-      if (status === "running") {
-        throw new RuntimeRunStateError("Cannot persist a runtime run before complete() is called");
-      }
-      if (!options.adapter) return;
-      await options.adapter.upsert(buildRow(metadata));
-    }
-  };
+	if (!options.workspaceId) throw new ValidationError("startRuntimeRun: workspaceId is required");
+	if (!options.taskSpec?.id) throw new ValidationError("startRuntimeRun: taskSpec.id is required");
+	const now = options.now ?? Date.now;
+	const startedAtMs = now();
+	const startedAt = new Date(startedAtMs).toISOString();
+	const id = options.id ?? `${options.taskSpec.id}:${randomSuffix$1()}`;
+	let status = "running";
+	let completedAtMs;
+	let resultSummary;
+	let error;
+	let completionMetadata;
+	const ledger = {
+		tokensIn: 0,
+		tokensOut: 0,
+		costUsd: 0,
+		wallMs: 0,
+		llmCalls: 0
+	};
+	const snapshotCost = () => ({
+		tokensIn: ledger.tokensIn,
+		tokensOut: ledger.tokensOut,
+		costUsd: ledger.costUsd,
+		wallMs: (completedAtMs ?? now()) - startedAtMs,
+		llmCalls: ledger.llmCalls
+	});
+	const buildRow = (extraMetadata) => ({
+		id,
+		workspaceId: options.workspaceId,
+		sessionId: options.sessionId,
+		agentId: options.agentId,
+		domain: options.taskSpec.domain,
+		taskId: options.taskSpec.id,
+		scenarioId: options.scenarioId,
+		status,
+		resultSummary,
+		error,
+		cost: snapshotCost(),
+		startedAt,
+		completedAt: completedAtMs !== void 0 ? new Date(completedAtMs).toISOString() : void 0,
+		metadata: mergeMetadata(completionMetadata, extraMetadata)
+	});
+	return {
+		id,
+		workspaceId: options.workspaceId,
+		sessionId: options.sessionId,
+		taskSpec: options.taskSpec,
+		get status() {
+			return status;
+		},
+		observe(event) {
+			if (event.type !== "llm_call") return;
+			ledger.llmCalls += 1;
+			if (typeof event.tokensIn === "number" && Number.isFinite(event.tokensIn)) ledger.tokensIn += event.tokensIn;
+			if (typeof event.tokensOut === "number" && Number.isFinite(event.tokensOut)) ledger.tokensOut += event.tokensOut;
+			if (typeof event.costUsd === "number" && Number.isFinite(event.costUsd)) ledger.costUsd += event.costUsd;
+		},
+		cost: snapshotCost,
+		complete(input) {
+			if (input.status === "running") throw new ValidationError("complete() requires a terminal status, got \"running\"");
+			if (status !== "running") {
+				if (status === input.status) return;
+				throw new RuntimeRunStateError(`Cannot transition runtime run from "${status}" to "${input.status}"`);
+			}
+			status = input.status;
+			completedAtMs = now();
+			resultSummary = input.resultSummary;
+			error = input.error;
+			completionMetadata = input.metadata;
+			if (input.cost) {
+				if (typeof input.cost.tokensIn === "number" && Number.isFinite(input.cost.tokensIn)) ledger.tokensIn = input.cost.tokensIn;
+				if (typeof input.cost.tokensOut === "number" && Number.isFinite(input.cost.tokensOut)) ledger.tokensOut = input.cost.tokensOut;
+				if (typeof input.cost.costUsd === "number" && Number.isFinite(input.cost.costUsd)) ledger.costUsd = input.cost.costUsd;
+				if (typeof input.cost.llmCalls === "number" && Number.isFinite(input.cost.llmCalls)) ledger.llmCalls = input.cost.llmCalls;
+			}
+		},
+		toRow(metadata) {
+			return buildRow(metadata);
+		},
+		async persist(metadata) {
+			if (status === "running") throw new RuntimeRunStateError("Cannot persist a runtime run before complete() is called");
+			if (!options.adapter) return;
+			await options.adapter.upsert(buildRow(metadata));
+		}
+	};
 }
 function mergeMetadata(base, extra) {
-  if (!base && !extra) return void 0;
-  return { ...base ?? {}, ...extra ?? {} };
-}
-function randomSuffix() {
-  return Math.random().toString(36).slice(2, 10);
-}
-
-// src/sse.ts
+	if (!base && !extra) return void 0;
+	return {
+		...base ?? {},
+		...extra ?? {}
+	};
+}
+function randomSuffix$1() {
+	return Math.random().toString(36).slice(2, 10);
+}
+//#endregion
+//#region src/sse.ts
+/** @stable */
 function encodeServerSentEvent(data, options = {}) {
-  const lines = [];
-  if (options.id) lines.push(`id: ${stripNewlines(options.id)}`);
-  if (options.event) lines.push(`event: ${stripNewlines(options.event)}`);
-  if (typeof options.retry === "number" && Number.isFinite(options.retry) && options.retry >= 0) {
-    lines.push(`retry: ${Math.floor(options.retry)}`);
-  }
-  const payload = typeof data === "string" ? data : JSON.stringify(data);
-  for (const line of payload.split(/\r?\n/)) {
-    lines.push(`data: ${line}`);
-  }
-  return `${lines.join("\n")}
-
-`;
-}
+	const lines = [];
+	if (options.id) lines.push(`id: ${stripNewlines(options.id)}`);
+	if (options.event) lines.push(`event: ${stripNewlines(options.event)}`);
+	if (typeof options.retry === "number" && Number.isFinite(options.retry) && options.retry >= 0) lines.push(`retry: ${Math.floor(options.retry)}`);
+	const payload = typeof data === "string" ? data : JSON.stringify(data);
+	for (const line of payload.split(/\r?\n/)) lines.push(`data: ${line}`);
+	return `${lines.join("\n")}\n\n`;
+}
+/** Serialize a `KnowledgeReadinessReport` as a Server-Sent Event string. @stable */
 function readinessServerSentEvent(report, options = {}) {
-  const { event, id, retry, ...telemetryOptions } = options;
-  return encodeServerSentEvent(
-    {
-      type: "readiness",
-      readiness: sanitizeKnowledgeReadinessReport(report, telemetryOptions)
-    },
-    { event, id, retry }
-  );
-}
+	const { event, id, retry, ...telemetryOptions } = options;
+	return encodeServerSentEvent({
+		type: "readiness",
+		readiness: sanitizeKnowledgeReadinessReport(report, telemetryOptions)
+	}, {
+		event,
+		id,
+		retry
+	});
+}
+/** Serialize a `RuntimeStreamEvent` as a Server-Sent Event string. @stable */
 function runtimeStreamServerSentEvent(event, options = {}) {
-  const { event: sseEvent, id, retry, ...telemetryOptions } = options;
-  return encodeServerSentEvent(sanitizeRuntimeStreamEvent(event, telemetryOptions), {
-    event: sseEvent,
-    id,
-    retry
-  });
+	const { event: sseEvent, id, retry, ...telemetryOptions } = options;
+	return encodeServerSentEvent(sanitizeRuntimeStreamEvent(event, telemetryOptions), {
+		event: sseEvent,
+		id,
+		retry
+	});
 }
 function stripNewlines(value) {
-  return value.replace(/[\r\n]/g, " ");
-}
-
-// src/tool-loop.ts
-var RUNAWAY_BACKSTOP_TURNS = 200;
-var DEFAULT_DECISION_CONTEXT_CHARS = 12e3;
-var FAILURE_RECOVERY_ACTIONS = ["retry", "verify", "continue", "stop"];
-var STUCK_LOOP_THRESHOLD = 3;
+	return value.replace(/[\r\n]/g, " ");
+}
+//#endregion
+//#region src/tool-loop.ts
+/** Runaway-backstop: stops an infinite tool loop where cost is unmetered. Set
+*  far above any legitimate workflow — this is a watchdog, not a policy cap.
+*  Legitimate per-call budgets come from `maxCostUsd` + `costOf`. */
+const RUNAWAY_BACKSTOP_TURNS = 200;
+const DEFAULT_DECISION_CONTEXT_CHARS = 12e3;
+const FAILURE_RECOVERY_ACTIONS = [
+	"retry",
+	"verify",
+	"continue",
+	"stop"
+];
+/** Consecutive identical calls (same tool + canonical-JSON args) that trigger
+*  stuck-loop detection. The window resets on any different call. */
+const STUCK_LOOP_THRESHOLD = 3;
+/** A tool-call id is required to key a `role: 'tool'` result back to its call.
+*  When the model omitted one, derive a stable id from the tool name so the
+*  assistant `tool_calls` entry and its `tool` result still match. */
 function toolCallId(call) {
-  return call.toolCallId ?? `call_${call.toolName}`;
+	return call.toolCallId ?? `call_${call.toolName}`;
 }
+/** The assistant turn that emitted `pending`, in OpenAI shape: text content
+*  (null when the turn was tool-only) plus its `tool_calls` array. */
 function assistantToolCallMessage(turnText, pending) {
-  return {
-    role: "assistant",
-    content: turnText.trim() || null,
-    tool_calls: pending.map((call) => ({
-      id: toolCallId(call),
-      type: "function",
-      function: { name: call.toolName, arguments: JSON.stringify(call.args) }
-    }))
-  };
-}
+	return {
+		role: "assistant",
+		content: turnText.trim() || null,
+		tool_calls: pending.map((call) => ({
+			id: toolCallId(call),
+			type: "function",
+			function: {
+				name: call.toolName,
+				arguments: JSON.stringify(call.args)
+			}
+		}))
+	};
+}
+/** One `role: 'tool'` result message keyed to its call by `tool_call_id`. */
 function toolResultMessage(call, content) {
-  return { role: "tool", tool_call_id: toolCallId(call), content };
+	return {
+		role: "tool",
+		tool_call_id: toolCallId(call),
+		content
+	};
 }
 function defaultRender(label, outcome) {
-  if (outcome.ok) return `- ${label} \u2192 ok: ${JSON.stringify(outcome.result)}`;
-  return `- ${label} \u2192 failed (${outcome.code}): ${outcome.message}`;
+	if (outcome.ok) return `- ${label} → ok: ${JSON.stringify(outcome.result)}`;
+	return `- ${label} → failed (${outcome.code}): ${outcome.message}`;
 }
+/** Run the bounded tool loop and return the final text + every executed tool
+*  outcome. Awaitable — callers needing to stream events to a UI use
+*  {@link streamToolLoop}. */
 async function runToolLoop(opts) {
-  const backstop = opts.maxToolTurns ?? RUNAWAY_BACKSTOP_TURNS;
-  const render = opts.renderResult ?? defaultRender;
-  const labelFor = opts.labelFor ?? ((c) => c.toolName);
-  const runId = opts.runId ?? `agent-run-${randomSuffix2()}`;
-  const messages = [
-    { role: "system", content: opts.systemPrompt },
-    ...opts.priorMessages ?? [],
-    { role: "user", content: opts.userMessage }
-  ];
-  const observer = createToolLoopObserver(opts.hooks, runId, opts.scenarioId);
-  const toolResults = [];
-  let finalText = "";
-  let turns = 0;
-  let accumulatedCostUsd = 0;
-  let lastCallHash = null;
-  let consecutiveCount = 0;
-  observer.loopBefore(backstop, messages.length);
-  for (let toolTurn = 0; ; toolTurn++) {
-    turns++;
-    if (opts.deadlineMs !== void 0 && Date.now() >= opts.deadlineMs) {
-      observer.loopAfter({ turns, toolResults: toolResults.length, stopReason: "deadline" });
-      return { finalText, toolResults, turns, stopReason: "deadline", cappedOut: true };
-    }
-    let turnText = "";
-    const pending = [];
-    const turnEventId = observer.turnBefore(toolTurn, messages.length);
-    for await (const ev of opts.streamTurn([...messages])) {
-      if (ev.type === "text") {
-        turnText += ev.text;
-        finalText += ev.text;
-      } else if (ev.type === "tool_call" && opts.isExecutableTool(ev.call.toolName)) {
-        pending.push(ev.call);
-      }
-    }
-    if (pending.length === 0) {
-      observer.turnAfter(toolTurn, turnEventId, {
-        pendingToolCalls: 0,
-        finalTextChars: finalText.length
-      });
-      break;
-    }
-    if (toolTurn >= backstop) {
-      observer.turnAfter(toolTurn, turnEventId, {
-        pendingToolCalls: pending.length,
-        stopReason: "backstop"
-      });
-      observer.loopAfter({ turns, toolResults: toolResults.length, stopReason: "backstop" });
-      return { finalText, toolResults, turns, stopReason: "backstop", cappedOut: true };
-    }
-    messages.push(assistantToolCallMessage(turnText, pending));
-    const outcomes = [];
-    for (const [callIndex, call] of pending.entries()) {
-      const callHash = canonicalCallHash(call);
-      if (callHash === lastCallHash) {
-        consecutiveCount++;
-      } else {
-        lastCallHash = callHash;
-        consecutiveCount = 1;
-      }
-      if (consecutiveCount >= STUCK_LOOP_THRESHOLD) {
-        observer.turnAfter(toolTurn, turnEventId, {
-          pendingToolCalls: pending.length,
-          stopReason: "stuck-loop"
-        });
-        observer.loopAfter({ turns, toolResults: toolResults.length, stopReason: "stuck-loop" });
-        return { finalText, toolResults, turns, stopReason: "stuck-loop", cappedOut: true };
-      }
-      const callEventId = observer.toolCallBefore(toolTurn, turnEventId, callIndex, call);
-      let outcome;
-      try {
-        outcome = await opts.executeToolCall(call);
-      } catch (err) {
-        outcome = {
-          ok: false,
-          code: "executor_error",
-          message: err instanceof Error ? err.message : String(err)
-        };
-      }
-      if (opts.maxCostUsd !== void 0 && opts.costOf !== void 0) {
-        accumulatedCostUsd += opts.costOf(call, outcome);
-        if (accumulatedCostUsd >= opts.maxCostUsd) {
-          const label2 = labelFor(call);
-          toolResults.push({ call, label: label2, outcome });
-          messages.push(toolResultMessage(call, render(label2, outcome)));
-          observer.toolCallAfter(toolTurn, callEventId, call, outcome);
-          observer.turnAfter(toolTurn, turnEventId, {
-            pendingToolCalls: pending.length,
-            stopReason: "budget"
-          });
-          observer.loopAfter({ turns, toolResults: toolResults.length, stopReason: "budget" });
-          return { finalText, toolResults, turns, stopReason: "budget", cappedOut: true };
-        }
-      }
-      const label = labelFor(call);
-      const rendered = render(label, outcome);
-      toolResults.push({ call, label, outcome });
-      outcomes.push({ call, label, outcome, rendered });
-      messages.push(toolResultMessage(call, rendered));
-      observer.toolCallAfter(toolTurn, callEventId, call, outcome);
-    }
-    observer.failureRecovery({
-      toolTurn,
-      messages,
-      turnText,
-      outcomes
-    });
-    observer.turnAfter(toolTurn, turnEventId, {
-      pendingToolCalls: pending.length,
-      toolResults: outcomes.map((item) => ({
-        toolName: item.call.toolName,
-        toolCallId: item.call.toolCallId,
-        ok: item.outcome.ok
-      })),
-      failedToolCalls: outcomes.filter((item) => !item.outcome.ok).length
-    });
-  }
-  observer.loopAfter({ turns, toolResults: toolResults.length, stopReason: "completed" });
-  return { finalText, toolResults, turns, stopReason: "completed", cappedOut: false };
-}
+	const backstop = opts.maxToolTurns ?? RUNAWAY_BACKSTOP_TURNS;
+	const render = opts.renderResult ?? defaultRender;
+	const labelFor = opts.labelFor ?? ((c) => c.toolName);
+	const runId = opts.runId ?? `agent-run-${randomSuffix()}`;
+	const messages = [
+		{
+			role: "system",
+			content: opts.systemPrompt
+		},
+		...opts.priorMessages ?? [],
+		{
+			role: "user",
+			content: opts.userMessage
+		}
+	];
+	const observer = createToolLoopObserver(opts.hooks, runId, opts.scenarioId);
+	const toolResults = [];
+	let finalText = "";
+	let turns = 0;
+	let accumulatedCostUsd = 0;
+	let lastCallHash = null;
+	let consecutiveCount = 0;
+	observer.loopBefore(backstop, messages.length);
+	for (let toolTurn = 0;; toolTurn++) {
+		turns++;
+		if (opts.deadlineMs !== void 0 && Date.now() >= opts.deadlineMs) {
+			observer.loopAfter({
+				turns,
+				toolResults: toolResults.length,
+				stopReason: "deadline"
+			});
+			return {
+				finalText,
+				toolResults,
+				turns,
+				stopReason: "deadline",
+				cappedOut: true
+			};
+		}
+		let turnText = "";
+		const pending = [];
+		const turnEventId = observer.turnBefore(toolTurn, messages.length);
+		for await (const ev of opts.streamTurn([...messages])) if (ev.type === "text") {
+			turnText += ev.text;
+			finalText += ev.text;
+		} else if (ev.type === "tool_call" && opts.isExecutableTool(ev.call.toolName)) pending.push(ev.call);
+		if (pending.length === 0) {
+			observer.turnAfter(toolTurn, turnEventId, {
+				pendingToolCalls: 0,
+				finalTextChars: finalText.length
+			});
+			break;
+		}
+		if (toolTurn >= backstop) {
+			observer.turnAfter(toolTurn, turnEventId, {
+				pendingToolCalls: pending.length,
+				stopReason: "backstop"
+			});
+			observer.loopAfter({
+				turns,
+				toolResults: toolResults.length,
+				stopReason: "backstop"
+			});
+			return {
+				finalText,
+				toolResults,
+				turns,
+				stopReason: "backstop",
+				cappedOut: true
+			};
+		}
+		messages.push(assistantToolCallMessage(turnText, pending));
+		const outcomes = [];
+		for (const [callIndex, call] of pending.entries()) {
+			const callHash = canonicalCallHash(call);
+			if (callHash === lastCallHash) consecutiveCount++;
+			else {
+				lastCallHash = callHash;
+				consecutiveCount = 1;
+			}
+			if (consecutiveCount >= STUCK_LOOP_THRESHOLD) {
+				observer.turnAfter(toolTurn, turnEventId, {
+					pendingToolCalls: pending.length,
+					stopReason: "stuck-loop"
+				});
+				observer.loopAfter({
+					turns,
+					toolResults: toolResults.length,
+					stopReason: "stuck-loop"
+				});
+				return {
+					finalText,
+					toolResults,
+					turns,
+					stopReason: "stuck-loop",
+					cappedOut: true
+				};
+			}
+			const callEventId = observer.toolCallBefore(toolTurn, turnEventId, callIndex, call);
+			let outcome;
+			try {
+				outcome = await opts.executeToolCall(call);
+			} catch (err) {
+				outcome = {
+					ok: false,
+					code: "executor_error",
+					message: err instanceof Error ? err.message : String(err)
+				};
+			}
+			if (opts.maxCostUsd !== void 0 && opts.costOf !== void 0) {
+				accumulatedCostUsd += opts.costOf(call, outcome);
+				if (accumulatedCostUsd >= opts.maxCostUsd) {
+					const label = labelFor(call);
+					toolResults.push({
+						call,
+						label,
+						outcome
+					});
+					messages.push(toolResultMessage(call, render(label, outcome)));
+					observer.toolCallAfter(toolTurn, callEventId, call, outcome);
+					observer.turnAfter(toolTurn, turnEventId, {
+						pendingToolCalls: pending.length,
+						stopReason: "budget"
+					});
+					observer.loopAfter({
+						turns,
+						toolResults: toolResults.length,
+						stopReason: "budget"
+					});
+					return {
+						finalText,
+						toolResults,
+						turns,
+						stopReason: "budget",
+						cappedOut: true
+					};
+				}
+			}
+			const label = labelFor(call);
+			const rendered = render(label, outcome);
+			toolResults.push({
+				call,
+				label,
+				outcome
+			});
+			outcomes.push({
+				call,
+				label,
+				outcome,
+				rendered
+			});
+			messages.push(toolResultMessage(call, rendered));
+			observer.toolCallAfter(toolTurn, callEventId, call, outcome);
+		}
+		observer.failureRecovery({
+			toolTurn,
+			messages,
+			turnText,
+			outcomes
+		});
+		observer.turnAfter(toolTurn, turnEventId, {
+			pendingToolCalls: pending.length,
+			toolResults: outcomes.map((item) => ({
+				toolName: item.call.toolName,
+				toolCallId: item.call.toolCallId,
+				ok: item.outcome.ok
+			})),
+			failedToolCalls: outcomes.filter((item) => !item.outcome.ok).length
+		});
+	}
+	observer.loopAfter({
+		turns,
+		toolResults: toolResults.length,
+		stopReason: "completed"
+	});
+	return {
+		finalText,
+		toolResults,
+		turns,
+		stopReason: "completed",
+		cappedOut: false
+	};
+}
+/** Streaming bounded tool loop: yields each raw turn event (the caller maps +
+*  telemetries + re-emits it) and each executed `tool_result`; emits one
+*  `capped` if it stops for any non-completed reason with calls still pending. */
 async function* streamToolLoop(opts) {
-  const backstop = opts.maxToolTurns ?? RUNAWAY_BACKSTOP_TURNS;
-  const render = opts.renderResult ?? defaultRender;
-  const labelFor = opts.labelFor ?? ((c) => c.toolName);
-  const runId = opts.runId ?? `agent-run-${randomSuffix2()}`;
-  const messages = [
-    { role: "system", content: opts.systemPrompt },
-    ...opts.priorMessages ?? [],
-    { role: "user", content: opts.userMessage }
-  ];
-  const observer = createToolLoopObserver(opts.hooks, runId, opts.scenarioId);
-  let accumulatedCostUsd = 0;
-  let lastCallHash = null;
-  let consecutiveCount = 0;
-  observer.loopBefore(backstop, messages.length);
-  for (let toolTurn = 0; ; toolTurn++) {
-    if (opts.deadlineMs !== void 0 && Date.now() >= opts.deadlineMs) {
-      observer.loopAfter({ turns: toolTurn + 1, stopReason: "deadline" });
-      yield { kind: "capped", pending: 0, stopReason: "deadline" };
-      return;
-    }
-    let turnText = "";
-    const pending = [];
-    const turnEventId = observer.turnBefore(toolTurn, messages.length);
-    for await (const event of opts.streamTurn([...messages])) {
-      yield { kind: "event", event };
-      turnText += opts.extractText(event);
-      const call = opts.extractToolCall(event);
-      if (call && opts.isExecutableTool(call.toolName)) pending.push(call);
-    }
-    if (pending.length === 0) {
-      observer.turnAfter(toolTurn, turnEventId, { pendingToolCalls: 0 });
-      observer.loopAfter({ turns: toolTurn + 1, stopReason: "completed" });
-      return;
-    }
-    if (toolTurn >= backstop) {
-      observer.turnAfter(toolTurn, turnEventId, {
-        pendingToolCalls: pending.length,
-        stopReason: "backstop"
-      });
-      observer.loopAfter({ turns: toolTurn + 1, stopReason: "backstop" });
-      yield { kind: "capped", pending: pending.length, stopReason: "backstop" };
-      return;
-    }
-    messages.push(assistantToolCallMessage(turnText, pending));
-    const outcomes = [];
-    for (const [callIndex, call] of pending.entries()) {
-      const callHash = canonicalCallHash(call);
-      if (callHash === lastCallHash) {
-        consecutiveCount++;
-      } else {
-        lastCallHash = callHash;
-        consecutiveCount = 1;
-      }
-      if (consecutiveCount >= STUCK_LOOP_THRESHOLD) {
-        observer.turnAfter(toolTurn, turnEventId, {
-          pendingToolCalls: pending.length,
-          stopReason: "stuck-loop"
-        });
-        observer.loopAfter({ turns: toolTurn + 1, stopReason: "stuck-loop" });
-        yield { kind: "capped", pending: pending.length, stopReason: "stuck-loop" };
-        return;
-      }
-      const callEventId = observer.toolCallBefore(toolTurn, turnEventId, callIndex, call);
-      let outcome;
-      try {
-        outcome = await opts.executeToolCall(call);
-      } catch (err) {
-        outcome = {
-          ok: false,
-          code: "executor_error",
-          message: err instanceof Error ? err.message : String(err)
-        };
-      }
-      if (opts.maxCostUsd !== void 0 && opts.costOf !== void 0) {
-        accumulatedCostUsd += opts.costOf(call, outcome);
-        if (accumulatedCostUsd >= opts.maxCostUsd) {
-          const label2 = labelFor(call);
-          yield {
-            kind: "tool_result",
-            toolName: call.toolName,
-            toolCallId: call.toolCallId,
-            label: label2,
-            outcome
-          };
-          messages.push(toolResultMessage(call, render(label2, outcome)));
-          observer.toolCallAfter(toolTurn, callEventId, call, outcome);
-          observer.turnAfter(toolTurn, turnEventId, {
-            pendingToolCalls: pending.length,
-            stopReason: "budget"
-          });
-          observer.loopAfter({ turns: toolTurn + 1, stopReason: "budget" });
-          yield { kind: "capped", pending: pending.length, stopReason: "budget" };
-          return;
-        }
-      }
-      const label = labelFor(call);
-      yield {
-        kind: "tool_result",
-        toolName: call.toolName,
-        toolCallId: call.toolCallId,
-        label,
-        outcome
-      };
-      const rendered = render(label, outcome);
-      outcomes.push({ call, label, outcome, rendered });
-      messages.push(toolResultMessage(call, rendered));
-      observer.toolCallAfter(toolTurn, callEventId, call, outcome);
-    }
-    observer.failureRecovery({
-      toolTurn,
-      messages,
-      turnText,
-      outcomes
-    });
-    observer.turnAfter(toolTurn, turnEventId, {
-      pendingToolCalls: pending.length,
-      toolResults: outcomes.map((item) => ({
-        toolName: item.call.toolName,
-        toolCallId: item.call.toolCallId,
-        ok: item.outcome.ok
-      })),
-      failedToolCalls: outcomes.filter((item) => !item.outcome.ok).length
-    });
-  }
+	const backstop = opts.maxToolTurns ?? RUNAWAY_BACKSTOP_TURNS;
+	const render = opts.renderResult ?? defaultRender;
+	const labelFor = opts.labelFor ?? ((c) => c.toolName);
+	const runId = opts.runId ?? `agent-run-${randomSuffix()}`;
+	const messages = [
+		{
+			role: "system",
+			content: opts.systemPrompt
+		},
+		...opts.priorMessages ?? [],
+		{
+			role: "user",
+			content: opts.userMessage
+		}
+	];
+	const observer = createToolLoopObserver(opts.hooks, runId, opts.scenarioId);
+	let accumulatedCostUsd = 0;
+	let lastCallHash = null;
+	let consecutiveCount = 0;
+	observer.loopBefore(backstop, messages.length);
+	for (let toolTurn = 0;; toolTurn++) {
+		if (opts.deadlineMs !== void 0 && Date.now() >= opts.deadlineMs) {
+			observer.loopAfter({
+				turns: toolTurn + 1,
+				stopReason: "deadline"
+			});
+			yield {
+				kind: "capped",
+				pending: 0,
+				stopReason: "deadline"
+			};
+			return;
+		}
+		let turnText = "";
+		const pending = [];
+		const turnEventId = observer.turnBefore(toolTurn, messages.length);
+		for await (const event of opts.streamTurn([...messages])) {
+			yield {
+				kind: "event",
+				event
+			};
+			turnText += opts.extractText(event);
+			const call = opts.extractToolCall(event);
+			if (call && opts.isExecutableTool(call.toolName)) pending.push(call);
+		}
+		if (pending.length === 0) {
+			observer.turnAfter(toolTurn, turnEventId, { pendingToolCalls: 0 });
+			observer.loopAfter({
+				turns: toolTurn + 1,
+				stopReason: "completed"
+			});
+			return;
+		}
+		if (toolTurn >= backstop) {
+			observer.turnAfter(toolTurn, turnEventId, {
+				pendingToolCalls: pending.length,
+				stopReason: "backstop"
+			});
+			observer.loopAfter({
+				turns: toolTurn + 1,
+				stopReason: "backstop"
+			});
+			yield {
+				kind: "capped",
+				pending: pending.length,
+				stopReason: "backstop"
+			};
+			return;
+		}
+		messages.push(assistantToolCallMessage(turnText, pending));
+		const outcomes = [];
+		for (const [callIndex, call] of pending.entries()) {
+			const callHash = canonicalCallHash(call);
+			if (callHash === lastCallHash) consecutiveCount++;
+			else {
+				lastCallHash = callHash;
+				consecutiveCount = 1;
+			}
+			if (consecutiveCount >= STUCK_LOOP_THRESHOLD) {
+				observer.turnAfter(toolTurn, turnEventId, {
+					pendingToolCalls: pending.length,
+					stopReason: "stuck-loop"
+				});
+				observer.loopAfter({
+					turns: toolTurn + 1,
+					stopReason: "stuck-loop"
+				});
+				yield {
+					kind: "capped",
+					pending: pending.length,
+					stopReason: "stuck-loop"
+				};
+				return;
+			}
+			const callEventId = observer.toolCallBefore(toolTurn, turnEventId, callIndex, call);
+			let outcome;
+			try {
+				outcome = await opts.executeToolCall(call);
+			} catch (err) {
+				outcome = {
+					ok: false,
+					code: "executor_error",
+					message: err instanceof Error ? err.message : String(err)
+				};
+			}
+			if (opts.maxCostUsd !== void 0 && opts.costOf !== void 0) {
+				accumulatedCostUsd += opts.costOf(call, outcome);
+				if (accumulatedCostUsd >= opts.maxCostUsd) {
+					const label = labelFor(call);
+					yield {
+						kind: "tool_result",
+						toolName: call.toolName,
+						toolCallId: call.toolCallId,
+						label,
+						outcome
+					};
+					messages.push(toolResultMessage(call, render(label, outcome)));
+					observer.toolCallAfter(toolTurn, callEventId, call, outcome);
+					observer.turnAfter(toolTurn, turnEventId, {
+						pendingToolCalls: pending.length,
+						stopReason: "budget"
+					});
+					observer.loopAfter({
+						turns: toolTurn + 1,
+						stopReason: "budget"
+					});
+					yield {
+						kind: "capped",
+						pending: pending.length,
+						stopReason: "budget"
+					};
+					return;
+				}
+			}
+			const label = labelFor(call);
+			yield {
+				kind: "tool_result",
+				toolName: call.toolName,
+				toolCallId: call.toolCallId,
+				label,
+				outcome
+			};
+			const rendered = render(label, outcome);
+			outcomes.push({
+				call,
+				label,
+				outcome,
+				rendered
+			});
+			messages.push(toolResultMessage(call, rendered));
+			observer.toolCallAfter(toolTurn, callEventId, call, outcome);
+		}
+		observer.failureRecovery({
+			toolTurn,
+			messages,
+			turnText,
+			outcomes
+		});
+		observer.turnAfter(toolTurn, turnEventId, {
+			pendingToolCalls: pending.length,
+			toolResults: outcomes.map((item) => ({
+				toolName: item.call.toolName,
+				toolCallId: item.call.toolCallId,
+				ok: item.outcome.ok
+			})),
+			failedToolCalls: outcomes.filter((item) => !item.outcome.ok).length
+		});
+	}
 }
 function createToolLoopObserver(hooks, runId, scenarioId) {
-  const loopEventId = `${runId}:agent.run`;
-  return {
-    loopBefore: (maxToolTurns, messageCount) => {
-      notifyToolLoopEvent({
-        hooks,
-        runId,
-        scenarioId,
-        target: "agent.run",
-        phase: "before",
-        id: `${loopEventId}:before`,
-        payload: { maxToolTurns, messageCount }
-      });
-    },
-    loopAfter: (payload) => {
-      notifyToolLoopEvent({
-        hooks,
-        runId,
-        scenarioId,
-        target: "agent.run",
-        phase: "after",
-        id: `${loopEventId}:after`,
-        payload
-      });
-    },
-    turnBefore: (toolTurn, messageCount) => {
-      const turnEventId = `${loopEventId}:${toolTurn}`;
-      notifyToolLoopEvent({
-        hooks,
-        runId,
-        scenarioId,
-        target: "agent.turn",
-        phase: "before",
-        id: turnEventId,
-        stepIndex: toolTurn,
-        parentId: loopEventId,
-        payload: { messageCount }
-      });
-      return turnEventId;
-    },
-    turnAfter: (toolTurn, turnEventId, payload) => {
-      notifyToolLoopEvent({
-        hooks,
-        runId,
-        scenarioId,
-        target: "agent.turn",
-        phase: "after",
-        id: `${turnEventId}:after`,
-        stepIndex: toolTurn,
-        parentId: turnEventId,
-        payload
-      });
-    },
-    toolCallBefore: (toolTurn, turnEventId, callIndex, call) => {
-      const callEventId = `${turnEventId}:tool-call:${callIndex}`;
-      notifyToolLoopEvent({
-        hooks,
-        runId,
-        scenarioId,
-        target: "agent.tool_call",
-        phase: "before",
-        id: callEventId,
-        stepIndex: toolTurn,
-        parentId: turnEventId,
-        payload: toolCallPayload(call)
-      });
-      return callEventId;
-    },
-    toolCallAfter: (toolTurn, callEventId, call, outcome) => {
-      notifyToolLoopEvent({
-        hooks,
-        runId,
-        scenarioId,
-        target: "agent.tool_call",
-        phase: "after",
-        id: `${callEventId}:after`,
-        stepIndex: toolTurn,
-        parentId: callEventId,
-        payload: { ...toolCallPayload(call), outcome: outcomePayload(outcome) }
-      });
-    },
-    failureRecovery: (options) => {
-      notifyToolFailureRecovery({
-        hooks,
-        runId,
-        scenarioId,
-        stepIndex: options.toolTurn,
-        messages: options.messages,
-        turnText: options.turnText,
-        outcomes: options.outcomes
-      });
-    }
-  };
+	const loopEventId = `${runId}:agent.run`;
+	return {
+		loopBefore: (maxToolTurns, messageCount) => {
+			notifyToolLoopEvent({
+				hooks,
+				runId,
+				scenarioId,
+				target: "agent.run",
+				phase: "before",
+				id: `${loopEventId}:before`,
+				payload: {
+					maxToolTurns,
+					messageCount
+				}
+			});
+		},
+		loopAfter: (payload) => {
+			notifyToolLoopEvent({
+				hooks,
+				runId,
+				scenarioId,
+				target: "agent.run",
+				phase: "after",
+				id: `${loopEventId}:after`,
+				payload
+			});
+		},
+		turnBefore: (toolTurn, messageCount) => {
+			const turnEventId = `${loopEventId}:${toolTurn}`;
+			notifyToolLoopEvent({
+				hooks,
+				runId,
+				scenarioId,
+				target: "agent.turn",
+				phase: "before",
+				id: turnEventId,
+				stepIndex: toolTurn,
+				parentId: loopEventId,
+				payload: { messageCount }
+			});
+			return turnEventId;
+		},
+		turnAfter: (toolTurn, turnEventId, payload) => {
+			notifyToolLoopEvent({
+				hooks,
+				runId,
+				scenarioId,
+				target: "agent.turn",
+				phase: "after",
+				id: `${turnEventId}:after`,
+				stepIndex: toolTurn,
+				parentId: turnEventId,
+				payload
+			});
+		},
+		toolCallBefore: (toolTurn, turnEventId, callIndex, call) => {
+			const callEventId = `${turnEventId}:tool-call:${callIndex}`;
+			notifyToolLoopEvent({
+				hooks,
+				runId,
+				scenarioId,
+				target: "agent.tool_call",
+				phase: "before",
+				id: callEventId,
+				stepIndex: toolTurn,
+				parentId: turnEventId,
+				payload: toolCallPayload(call)
+			});
+			return callEventId;
+		},
+		toolCallAfter: (toolTurn, callEventId, call, outcome) => {
+			notifyToolLoopEvent({
+				hooks,
+				runId,
+				scenarioId,
+				target: "agent.tool_call",
+				phase: "after",
+				id: `${callEventId}:after`,
+				stepIndex: toolTurn,
+				parentId: callEventId,
+				payload: {
+					...toolCallPayload(call),
+					outcome: outcomePayload(outcome)
+				}
+			});
+		},
+		failureRecovery: (options) => {
+			notifyToolFailureRecovery({
+				hooks,
+				runId,
+				scenarioId,
+				stepIndex: options.toolTurn,
+				messages: options.messages,
+				turnText: options.turnText,
+				outcomes: options.outcomes
+			});
+		}
+	};
 }
 function notifyToolLoopEvent(options) {
-  notifyRuntimeHookEvent(options.hooks, {
-    id: options.id ?? `${options.runId}:${options.target}:${options.phase}`,
-    runId: options.runId,
-    scenarioId: options.scenarioId,
-    target: options.target,
-    phase: options.phase,
-    timestamp: Date.now(),
-    stepIndex: options.stepIndex,
-    parentId: options.parentId,
-    payload: options.payload,
-    metadata: { producer: "tool-loop", ...options.metadata }
-  });
+	notifyRuntimeHookEvent(options.hooks, {
+		id: options.id ?? `${options.runId}:${options.target}:${options.phase}`,
+		runId: options.runId,
+		scenarioId: options.scenarioId,
+		target: options.target,
+		phase: options.phase,
+		timestamp: Date.now(),
+		stepIndex: options.stepIndex,
+		parentId: options.parentId,
+		payload: options.payload,
+		metadata: {
+			producer: "tool-loop",
+			...options.metadata
+		}
+	});
 }
 function notifyToolFailureRecovery(options) {
-  const failed = options.outcomes.filter((item) => !item.outcome.ok);
-  if (failed.length === 0) return;
-  const evidence = [];
-  for (const item of failed) {
-    const id = item.call.toolCallId ?? `${options.stepIndex}:${item.label}`;
-    evidence.push({
-      source: "tool_call",
-      id,
-      detail: `${item.call.toolName} ${stringifySafe(item.call.args, 2e3)}`,
-      metadata: { toolName: item.call.toolName, label: item.label }
-    });
-    evidence.push({
-      source: "tool_result",
-      id: `${id}:result`,
-      detail: item.rendered,
-      metadata: failureMetadata(item.outcome)
-    });
-  }
-  notifyRuntimeDecisionPoint(options.hooks, {
-    id: `${options.runId}:agent.turn:${options.stepIndex}:failure-recovery`,
-    runId: options.runId,
-    scenarioId: options.scenarioId,
-    stepIndex: options.stepIndex,
-    kind: "retry",
-    candidateActions: [...FAILURE_RECOVERY_ACTIONS],
-    context: renderDecisionContext(options.messages, options.turnText, options.outcomes),
-    evidence,
-    metadata: {
-      target: "failure-recovery",
-      source: "agent.turn",
-      failedToolCount: failed.length,
-      toolNames: failed.map((item) => item.call.toolName)
-    }
-  });
+	const failed = options.outcomes.filter((item) => !item.outcome.ok);
+	if (failed.length === 0) return;
+	const evidence = [];
+	for (const item of failed) {
+		const id = item.call.toolCallId ?? `${options.stepIndex}:${item.label}`;
+		evidence.push({
+			source: "tool_call",
+			id,
+			detail: `${item.call.toolName} ${stringifySafe(item.call.args, 2e3)}`,
+			metadata: {
+				toolName: item.call.toolName,
+				label: item.label
+			}
+		});
+		evidence.push({
+			source: "tool_result",
+			id: `${id}:result`,
+			detail: item.rendered,
+			metadata: failureMetadata(item.outcome)
+		});
+	}
+	notifyRuntimeDecisionPoint(options.hooks, {
+		id: `${options.runId}:agent.turn:${options.stepIndex}:failure-recovery`,
+		runId: options.runId,
+		scenarioId: options.scenarioId,
+		stepIndex: options.stepIndex,
+		kind: "retry",
+		candidateActions: [...FAILURE_RECOVERY_ACTIONS],
+		context: renderDecisionContext(options.messages, options.turnText, options.outcomes),
+		evidence,
+		metadata: {
+			target: "failure-recovery",
+			source: "agent.turn",
+			failedToolCount: failed.length,
+			toolNames: failed.map((item) => item.call.toolName)
+		}
+	});
 }
 function toolCallPayload(call) {
-  return {
-    toolName: call.toolName,
-    toolCallId: call.toolCallId,
-    argsPreview: stringifySafe(call.args, 2e3)
-  };
+	return {
+		toolName: call.toolName,
+		toolCallId: call.toolCallId,
+		argsPreview: stringifySafe(call.args, 2e3)
+	};
 }
 function outcomePayload(outcome) {
-  if (!outcome.ok) {
-    return {
-      ok: false,
-      code: outcome.code,
-      message: trimText(outcome.message, 2e3),
-      status: outcome.status
-    };
-  }
-  return {
-    ok: true,
-    resultPreview: stringifySafe(outcome.result, 2e3)
-  };
+	if (!outcome.ok) return {
+		ok: false,
+		code: outcome.code,
+		message: trimText(outcome.message, 2e3),
+		status: outcome.status
+	};
+	return {
+		ok: true,
+		resultPreview: stringifySafe(outcome.result, 2e3)
+	};
 }
 function failureMetadata(outcome) {
-  if (outcome.ok) return void 0;
-  return {
-    code: outcome.code,
-    message: outcome.message,
-    status: outcome.status
-  };
+	if (outcome.ok) return void 0;
+	return {
+		code: outcome.code,
+		message: outcome.message,
+		status: outcome.status
+	};
 }
 function renderDecisionContext(messages, turnText, outcomes) {
-  const recent = messages.slice(-6).map((message) => `[${message.role}]
-${message.content ?? ""}`);
-  const assistant = turnText.trim() ? [`[assistant]
-${turnText}`] : [];
-  const toolResults = [`[tool results]
-${outcomes.map((item) => item.rendered).join("\n")}`];
-  return trimText(
-    [...recent, ...assistant, ...toolResults].join("\n\n"),
-    DEFAULT_DECISION_CONTEXT_CHARS
-  );
-}
+	const recent = messages.slice(-6).map((message) => `[${message.role}]\n${message.content ?? ""}`);
+	const assistant = turnText.trim() ? [`[assistant]\n${turnText}`] : [];
+	const toolResults = [`[tool results]\n${outcomes.map((item) => item.rendered).join("\n")}`];
+	return trimText([
+		...recent,
+		...assistant,
+		...toolResults
+	].join("\n\n"), DEFAULT_DECISION_CONTEXT_CHARS);
+}
+/** Canonical identifier for a tool call used by stuck-loop detection.
+*  Keys are sorted so `{b:1,a:2}` and `{a:2,b:1}` produce the same hash. */
 function canonicalCallHash(call) {
-  const sortedArgs = Object.fromEntries(
-    Object.entries(call.args).sort(([a], [b]) => a.localeCompare(b))
-  );
-  return `${call.toolName}:${JSON.stringify(sortedArgs)}`;
+	const sortedArgs = Object.fromEntries(Object.entries(call.args).sort(([a], [b]) => a.localeCompare(b)));
+	return `${call.toolName}:${JSON.stringify(sortedArgs)}`;
 }
 function stringifySafe(value, max) {
-  let text;
-  try {
-    text = JSON.stringify(value) ?? String(value);
-  } catch {
-    text = String(value);
-  }
-  return trimText(text, max);
+	let text;
+	try {
+		text = JSON.stringify(value) ?? String(value);
+	} catch {
+		text = String(value);
+	}
+	return trimText(text, max);
 }
 function trimText(text, max) {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max)}\u2026`;
-}
-function randomSuffix2(len = 8) {
-  return Math.random().toString(36).slice(2, 2 + len);
-}
-export {
-  AGENTIC_PROFILE_RESOURCE_ROOT,
-  AGENT_CANDIDATE_EXECUTION_SUPPORT,
-  AgentEvalError,
-  BackendTransportError,
-  CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV,
-  CANDIDATE_KNOWLEDGE_ROOT_ENV,
-  CANDIDATE_TRACE_ENV,
-  CANDIDATE_TRACE_TAGS,
-  CircuitBreakerState,
-  CircuitOpenError,
-  ConfigError,
-  DEFAULT_MAX_DEPTH,
-  DEFAULT_ROUTER_BASE_URL,
-  DELEGATED_LOOP_MODES,
-  DeadlineExceededError,
-  FORWARD_HEADERS,
-  FileAgentCandidateExecutionClaimStore,
-  FileConversationJournal,
-  INTELLIGENCE_WIRE_VERSION,
-  InMemoryAgentCandidateExecutionClaimStore,
-  InMemoryConversationJournal,
-  InMemoryRuntimeSessionStore,
-  JudgeError,
-  LIFTED_FINDING_ANALYST_ID,
-  NotFoundError,
-  PlannerError,
-  RESEARCH_SUPERVISOR_SYSTEM_PROMPT,
-  ROLLOUT_POLICY_BOUNDS,
-  ROLLOUT_POLICY_EXTENSION,
-  RuntimeRunStateError,
-  SqlConversationJournal,
-  ValidationError,
-  agenticGenerator,
-  applyExactAgentProfileDiff,
-  applyRolloutPolicyToProfile,
-  applyRunRecordDefaults,
-  assertCandidateProfileBinding,
-  auditLoopRunner,
-  buildAgentCandidateBundle,
-  buildDriverSystem,
-  buildForwardHeaders,
-  buildKnowledgeImprovementExperimentBundles,
-  buildLoopOtelSpans,
-  buildLoopSpanNodes,
-  buildRuntimeEventOtelSpans,
-  campaignCellSpansToOtlp,
-  campaignTraceResolver,
-  candidateExecutionClaim,
-  candidateKnowledgeExecutionPaths,
-  captureAgentCandidateWorkspace,
-  captureAgentCandidateWorkspaceFiles,
-  cleanModelId,
-  commandVerifier,
-  composeRuntimeHooks,
-  computeBackoff,
-  convertCampaignDirToOtlp,
-  createAgentCandidateWorkspacePort,
-  createAgentKnowledgeReadinessCheck,
-  createConversationBackend,
-  createIterableBackend,
-  createKnowledgeImprovementActivationExecutor,
-  createOpenAICompatibleBackend,
-  createOtelExporter,
-  createProtectedAgentCandidateModelPort,
-  createRuntimeEventCollector,
-  createRuntimeStreamEventCollector,
-  createSandboxPromptBackend,
-  createSupervisedKnowledgeUpdater,
-  d1ToSqlAdapter,
-  decideKnowledgeReadiness,
-  defaultBuildPrompt,
-  defaultIsRetryable,
-  defineConversation,
-  defineRuntimeHooks,
-  deriveExecutionId,
-  disposePreparedAgentCandidateExecution,
-  driverLoopGenerator,
-  enumerateNeighborPolicies,
-  exactProcessProviderAsCandidateExecutor,
-  executePreparedAgentCandidate,
-  exportEvalRuns,
-  findingLines,
-  formatSupervisedKnowledgeTask,
-  getModels,
-  handleChatTurn,
-  improve,
-  improvementDriver,
-  isAnalystFinding,
-  isDelegatedLoopMode,
-  isDepthExceeded,
-  knowledgeReadinessDeliverable,
-  loopEventToOtelSpan,
-  makePerAttemptSignal,
-  mcpBuildPrompt,
-  mcpServeVerifier,
-  mcpToolsForRuntimeMcp,
-  mcpToolsForRuntimeMcpSubset,
-  normalizeRolloutPolicy,
-  notifyRuntimeDecisionPoint,
-  notifyRuntimeHookEvent,
-  optimizerMethod,
-  parseExactAgentProfile,
-  parseExactAgentProfileDiff,
-  parseLoopRunnerArgv,
-  parseRolloutPolicy,
-  persistCandidateOutputArtifact,
-  prepareAgentCandidateExecution,
-  profileDiffProposer,
-  rawTraceDistiller,
-  readDepth,
-  readinessServerSentEvent,
-  recoverExpiredAgentCandidateExecution,
-  reflectiveGenerator,
-  researchDriverNote,
-  researchLoopRunner,
-  resolveAgentBackend,
-  resolveChatModel,
-  resolveRouterBaseUrl,
-  rolloutPolicyProposer,
-  runAgentTask,
-  runAgentTaskStream,
-  runConversation,
-  runConversationStream,
-  runDelegatedLoop,
-  runKnowledgeImprovementJob,
-  runLoopRunnerCli,
-  runPersonaConversation,
-  runPersonaDispatch,
-  runSupervisedKnowledgeUpdate,
-  runToolLoop,
-  runtimeStreamServerSentEvent,
-  sanitizeAgentRuntimeEvent,
-  sanitizeKnowledgeReadinessReport,
-  sanitizeRuntimeStreamEvent,
-  sealAgentCandidateBundle,
-  selfImproveLoopRunner,
-  serializeRolloutPolicy,
-  sleep,
-  slugifySpeaker,
-  startRuntimeRun,
-  strategyAuthorMethod,
-  streamToolLoop,
-  structuralRolloutPolicyFromProfile,
-  toAnalystFindings,
-  toolBuildPrompt,
-  turnId,
-  validateChatModelId,
-  verifyAgentCandidateBundle,
-  worktreeLoopRunner
-};
+	if (text.length <= max) return text;
+	return `${text.slice(0, max)}…`;
+}
+function randomSuffix(len = 8) {
+	return Math.random().toString(36).slice(2, 2 + len);
+}
+//#endregion
+export { AGENTIC_PROFILE_RESOURCE_ROOT, AGENT_CANDIDATE_EXECUTION_SUPPORT, AgentEvalError, BackendTransportError, CANDIDATE_KNOWLEDGE_RETRIEVAL_CONFIG_ENV, CANDIDATE_KNOWLEDGE_ROOT_ENV, CANDIDATE_TRACE_ENV, CANDIDATE_TRACE_TAGS, CircuitBreakerState, CircuitOpenError, ConfigError, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DELEGATED_LOOP_MODES, DeadlineExceededError, FORWARD_HEADERS, FileAgentCandidateExecutionClaimStore, FileConversationJournal, INTELLIGENCE_WIRE_VERSION, InMemoryAgentCandidateExecutionClaimStore, InMemoryConversationJournal, InMemoryRuntimeSessionStore, JudgeError, LIFTED_FINDING_ANALYST_ID, NotFoundError, OfficialOptimizerUnavailableError, PlannerError, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, ROLLOUT_POLICY_EXTENSION, RuntimeRunStateError, SqlConversationJournal, ValidationError, agenticGenerator, applyExactAgentProfileDiff, applyRolloutPolicyToProfile, applyRunRecordDefaults, assertCandidateProfileBinding, auditLoopRunner, buildAgentCandidateBundle, buildDriverSystem, buildForwardHeaders, buildKnowledgeImprovementExperimentBundles, buildLoopOtelSpans, buildLoopSpanNodes, buildRuntimeEventOtelSpans, candidateExecutionClaim, candidateKnowledgeExecutionPaths, captureAgentCandidateWorkspace, captureAgentCandidateWorkspaceFiles, cleanModelId, commandVerifier, composeRuntimeHooks, computeBackoff, createAgentCandidateWorkspacePort, createAgentKnowledgeReadinessCheck, createConversationBackend, createIterableBackend, createKnowledgeImprovementActivationExecutor, createOpenAICompatibleBackend, createOtelExporter, createProtectedAgentCandidateModelPort, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createSupervisedKnowledgeUpdater, d1ToSqlAdapter, decideKnowledgeReadiness, defaultBuildPrompt, defaultIsRetryable, defineConversation, defineRuntimeHooks, deriveExecutionId, disposePreparedAgentCandidateExecution, driverLoopGenerator, exactProcessProviderAsCandidateExecutor, executePreparedAgentCandidate, exportEvalRuns, findingLines, formatSupervisedKnowledgeTask, getModels, handleChatTurn, improve, isAnalystFinding, isDelegatedLoopMode, isDepthExceeded, knowledgeReadinessDeliverable, loopEventToOtelSpan, makePerAttemptSignal, mcpBuildPrompt, mcpServeVerifier, mcpToolsForRuntimeMcp, mcpToolsForRuntimeMcpSubset, normalizeRolloutPolicy, notifyRuntimeDecisionPoint, notifyRuntimeHookEvent, officialGepa, officialSkillOpt, optimizerMethod, parseExactAgentProfile, parseExactAgentProfileDiff, parseLoopRunnerArgv, parseRolloutPolicy, persistCandidateOutputArtifact, prepareAgentCandidateExecution, rawTraceDistiller, readDepth, readinessServerSentEvent, recoverExpiredAgentCandidateExecution, reflectiveGenerator, researchDriverNote, researchLoopRunner, resolveAgentBackend, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runDelegatedLoop, runKnowledgeImprovementJob, runLoopRunnerCli, runPersonaConversation, runPersonaDispatch, runSupervisedKnowledgeUpdate, runToolLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sealAgentCandidateBundle, serializeRolloutPolicy, sleep, slugifySpeaker, startRuntimeRun, strategyAuthorMethod, streamToolLoop, structuralRolloutPolicyFromProfile, toAnalystFindings, toolBuildPrompt, turnId, validateChatModelId, verifyAgentCandidateBundle, worktreeLoopRunner };
+
 //# sourceMappingURL=index.js.map