@tangle-network/agent-runtime 0.126.0 → 0.131.0

package/dist/index.js

@@ -1,24 +1,21 @@
 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-CiOCyRHb.js";
-import { $ as parseExactAgentProfile, G as agentCandidateProfileAsAgentProfile, K as applyExactAgentProfileDiff, S as CANDIDATE_TRACE_TAGS, X as freezeGenericAgentCandidateProfile, Z as omitUndefinedObjectFields, _ 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, tt as parseExactCandidateProfile, u as AGENT_CANDIDATE_EXECUTION_SUPPORT, x as CANDIDATE_TRACE_ENV } from "./prepare--8EvLqCr.js";
-import { i as sealAgentCandidateBundle, n as captureAgentCandidateWorkspaceFiles, r as createAgentCandidateWorkspacePort, t as captureAgentCandidateWorkspace } from "./workspace-archive-BQxvkypI.js";
-import { i as buildAgentCandidateBundle, n as disposePreparedAgentCandidateExecution, r as FileAgentCandidateExecutionClaimStore, t as recoverExpiredAgentCandidateExecution } from "./candidate-execution-BFpq-Xi6.js";
-import { n as exactProcessProviderAsCandidateExecutor, t as createProtectedAgentCandidateModelPort } from "./protected-model-port-CXVfOUu_.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-BpLQZGPH.js";
-import { B as sanitizeRuntimeStreamEvent, C as INTELLIGENCE_WIRE_VERSION, D as createOpenInferenceFileExporter, E as buildRuntimeEventOtelSpans, F as toOtelAttributes, I as createRuntimeEventCollector, Jt as runLocalHarness, L as createRuntimeStreamEventCollector, M as loopEventToOtelSpan, N as padSpanId, O as createOtelExporter, P as padTraceId, R as sanitizeAgentRuntimeEvent, T as buildLoopSpanNodes, bt as runBrainLoop, j as generateSpanId, k as exportEvalRuns, w as buildLoopOtelSpans, z as sanitizeKnowledgeReadinessReport } from "./supervisor-DpjO0Gmy.js";
-import { D as researchDriverNote, E as optimizerMethod, O as strategyAuthorMethod, T as buildDriverSystem } from "./structural-rollout-zY0oqQzO.js";
-import { A as improve, B as agenticGenerator, F as normalizeRolloutPolicy, G as summarizeFindings, H as defaultBuildPrompt, I as parseRolloutPolicy, K as worktreeChangedPaths, L as serializeRolloutPolicy, M as rawTraceDistiller, N as ROLLOUT_POLICY_EXTENSION, P as applyRolloutPolicyToProfile, R as structuralRolloutPolicyFromProfile, U as rawTraceEvidenceProblem, V as commandVerifier, W as requiresRawTraceEvidence, j as withMethodRuntimeControls, z as AGENTIC_PROFILE_RESOURCE_ROOT } from "./improvement-cycle-IJgCbKWQ.js";
+import { a as normalizeBackendStreamEvent, c as nowIso, i as createSandboxPromptBackend, l as startOrResumeRuntimeSession, o as InMemoryRuntimeSessionStore, r as createIterableBackend, u as touchSession } from "./stream-agent-turn-rYgaOLO0.js";
+import { $ as parseExactAgentProfile, G as agentCandidateProfileAsAgentProfile, K as applyExactAgentProfileDiff, S as CANDIDATE_TRACE_TAGS, Y as freezeGenericAgentCandidateProfile, Z as omitUndefinedObjectFields, _ 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, tt as parseExactCandidateProfile, u as AGENT_CANDIDATE_EXECUTION_SUPPORT, x as CANDIDATE_TRACE_ENV } from "./prepare-DYWjVcPx.js";
+import { i as sealAgentCandidateBundle, n as captureAgentCandidateWorkspaceFiles, r as createAgentCandidateWorkspacePort, t as captureAgentCandidateWorkspace } from "./workspace-archive-aOfJ47ms.js";
+import { i as buildAgentCandidateBundle, n as disposePreparedAgentCandidateExecution, r as FileAgentCandidateExecutionClaimStore, t as recoverExpiredAgentCandidateExecution } from "./candidate-execution-BNxKr-Bu.js";
+import { n as exactProcessProviderAsCandidateExecutor, t as createProtectedAgentCandidateModelPort } from "./protected-model-port-48ALLGxT.js";
+import { C as makePerAttemptSignal, S as defaultIsRetryable, T as createProfileExecutionBackend, _ 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-DNtxaJ1Z.js";
+import { Ct as sanitizeAgentRuntimeEvent, St as createRuntimeStreamEventCollector, Tt as sanitizeRuntimeStreamEvent, _t as loopEventToOtelSpan, bt as toOtelAttributes, ct as INTELLIGENCE_WIRE_VERSION, dt as buildRuntimeEventOtelSpans, ft as createOpenInferenceFileExporter, gt as generateSpanId, lt as buildLoopOtelSpans, mt as exportEvalRuns, pt as createOtelExporter, ut as buildLoopSpanNodes, vt as padSpanId, wt as sanitizeKnowledgeReadinessReport, xt as createRuntimeEventCollector, yt as padTraceId } from "./supervisor-CV6Jh28D.js";
 import { i as notifyRuntimeHookEvent, n as defineRuntimeHooks, r as notifyRuntimeDecisionPoint, t as composeRuntimeHooks } from "./runtime-hooks-C7iJOWm3.js";
-import { Ot as McpSpawnFault, kt as connectStdioMcp } from "./runtime-BzXz7OjS.js";
+import { D as optimizerMethod, O as strategyAuthorMethod } from "./structural-rollout-3uxVGcg2.js";
+import { A as improve, B as commandVerifier, F as normalizeRolloutPolicy, I as parseRolloutPolicy, L as serializeRolloutPolicy, M as rawTraceDistiller, N as ROLLOUT_POLICY_EXTENSION, P as applyRolloutPolicyToProfile, R as structuralRolloutPolicyFromProfile, V as defaultBuildPrompt, j as withMethodRuntimeControls, z as agenticGenerator } from "./improvement-cycle-Csp38cWg.js";
+import { Dt as McpSpawnFault, Ot as connectStdioMcp } from "./runtime-hiAABiTk.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-EnuEqm_Y.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-qwT_4F5I.js";
-import { n as mcpToolsForRuntimeMcpSubset, t as mcpToolsForRuntimeMcp } from "./openai-tools-Bp1KSkP6.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 { 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-ce0_uKCl.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-DSbuDDqM.js";
+import { n as mcpToolsForRuntimeMcpSubset, t as mcpToolsForRuntimeMcp } from "./openai-tools-ru75mLjq.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/improvement/build-prompts.ts
@@ -89,277 +86,6 @@ function mcpBuildPrompt(args) {
 	].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-code";
-	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, findings, maxShots, signal }) {
-			signal.throwIfAborted();
-			const briefing = buildPrompt({ 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: {}
-			}
-		}
-	}
-];
-/** 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;
-}
-/** 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 = 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 : `…${trimmed.slice(-n)}`;
-}
-function truncate(s, n) {
-	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
@@ -414,7 +140,7 @@ function mcpServeVerifier(spec) {
 //#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 bridgeInstall = "`python -m pip install \"agent-eval-rpc==0.144.6\"`";
 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"\``;
@@ -687,7 +413,7 @@ function isMissingDependency(optimizer, cause) {
 * This is the `shots=1, sandbox=off` code-candidate setting.
 * `agenticGenerator` supplies the multi-shot verify-in-session setting.
 *
-* @experimental
+* @stable
 */
 /** 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) {
@@ -727,6 +453,101 @@ function applyPatch(patch, cwd) {
 	}).status === 0;
 }
 //#endregion
+//#region src/model-resolution.ts
+/** Default Tangle Router base URL used when no env override is set. */
+const DEFAULT_ROUTER_BASE_URL = "https://router.tangle.tools";
+/** Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. */
+function resolveRouterBaseUrl(env = {}) {
+	return (env.TANGLE_ROUTER_URL ?? env.TANGLE_ROUTER_BASE_URL ?? "https://router.tangle.tools").replace(/\/v1\/?$/, "").replace(/\/$/, "");
+}
+/**
+* Fetch the model catalog from the router's `/v1/models`. Throws on a non-2xx
+* response — callers decide whether to fail open (empty catalog) or closed.
+*/
+async function getModels(routerBaseUrl = DEFAULT_ROUTER_BASE_URL) {
+	const res = await fetch(`${routerBaseUrl}/v1/models`, { headers: { Accept: "application/json" } });
+	if (!res.ok) throw new Error(`router /v1/models ${res.status}`);
+	const body = await res.json();
+	return Array.isArray(body.data) ? body.data : [];
+}
+/** Trim a candidate model id; `undefined` for non-strings and blanks. */
+function cleanModelId(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+/**
+* Resolve a chat model by precedence: the first candidate carrying a
+* non-blank model wins, else `fallback`. The caller owns the precedence
+* order, so each product keeps its own policy (request → workspace → env,
+* etc.) while the first-non-blank logic and the telemetry shape stay shared.
+*/
+function resolveChatModel(candidates, fallback) {
+	for (const candidate of candidates) {
+		const model = cleanModelId(candidate.model);
+		if (model) return {
+			source: candidate.source,
+			model
+		};
+	}
+	return fallback;
+}
+const WELL_FORMED_MODEL_ID = /^[A-Za-z0-9._/@:-]+$/;
+function isWellFormedModelId(modelId) {
+	return modelId.length <= 200 && WELL_FORMED_MODEL_ID.test(modelId);
+}
+/**
+* Every id a catalog entry can be addressed by — its bare id, plus a
+* `provider/id` form when the router exposes a separate provider slug.
+*/
+function catalogIdsForModel(model) {
+	const ids = /* @__PURE__ */ new Set();
+	const id = cleanModelId(model.id);
+	if (id) ids.add(id);
+	const provider = cleanModelId(model._provider) ?? cleanModelId(model.provider);
+	if (provider && id && !id.includes("/")) ids.add(`${provider}/${id}`);
+	return [...ids];
+}
+/**
+* Validate a caller-supplied chat-model id. Rejects non-strings, malformed
+* ids, and ids absent from both the caller's `allowlist` and the live router
+* catalog. Fails closed: when the catalog cannot be fetched, an unverifiable
+* id is rejected rather than admitted — a bad model never reaches the agent.
+*/
+async function validateChatModelId(modelId, options = {}) {
+	const { allowlist = [], routerBaseUrl = DEFAULT_ROUTER_BASE_URL, loadModels = getModels } = options;
+	const cleaned = cleanModelId(modelId);
+	if (!cleaned) return {
+		succeeded: false,
+		error: "Model id must be a non-empty string."
+	};
+	if (!isWellFormedModelId(cleaned)) return {
+		succeeded: false,
+		error: `Model id is malformed: ${cleaned}`
+	};
+	if (allowlist.some((id) => cleanModelId(id) === cleaned)) return {
+		succeeded: true,
+		value: cleaned
+	};
+	let catalog;
+	try {
+		catalog = await loadModels(routerBaseUrl);
+	} catch (err) {
+		return {
+			succeeded: false,
+			error: `Could not validate model catalog: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	if (!new Set(catalog.flatMap(catalogIdsForModel)).has(cleaned)) return {
+		succeeded: false,
+		error: `Model is not available: ${cleaned}`
+	};
+	return {
+		succeeded: true,
+		value: cleaned
+	};
+}
+//#endregion
 //#region src/readiness.ts
 const DEFAULT_MINIMUM_READINESS_SCORE = .7;
 /**
@@ -771,70 +592,6 @@ function decideKnowledgeReadiness(report, options = {}) {
 	};
 }
 //#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();
-	}
-}
-//#endregion
 //#region src/run.ts
 /**
 *
@@ -1478,6 +1235,6 @@ function stripNewlines(value) {
 	return value.replace(/[\r\n]/g, " ");
 }
 //#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, NotFoundError, OfficialOptimizerUnavailableError, PlannerError, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, ROLLOUT_POLICY_EXTENSION, RuntimeRunStateError, SqlConversationJournal, ValidationError, agentCandidateProfileAsAgentProfile, 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, createOpenInferenceFileExporter, createOtelExporter, createProtectedAgentCandidateModelPort, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createSupervisedKnowledgeUpdater, d1ToSqlAdapter, decideKnowledgeReadiness, defaultBuildPrompt, defaultIsRetryable, defineConversation, defineRuntimeHooks, disposePreparedAgentCandidateExecution, driverLoopGenerator, exactProcessProviderAsCandidateExecutor, executePreparedAgentCandidate, exportEvalRuns, findingLines, formatSupervisedKnowledgeTask, freezeGenericAgentCandidateProfile, generateSpanId, getModels, improve, isDelegatedLoopMode, isDepthExceeded, knowledgeReadinessDeliverable, loopEventToOtelSpan, makePerAttemptSignal, mcpBuildPrompt, mcpServeVerifier, mcpToolsForRuntimeMcp, mcpToolsForRuntimeMcpSubset, normalizeRolloutPolicy, notifyRuntimeDecisionPoint, notifyRuntimeHookEvent, officialGepa, officialSkillOpt, omitUndefinedObjectFields, optimizerMethod, padSpanId, padTraceId, parseExactAgentProfile, parseExactAgentProfileDiff, parseExactCandidateProfile, parseLoopRunnerArgv, parseRolloutPolicy, persistCandidateOutputArtifact, prepareAgentCandidateExecution, rawTraceDistiller, readDepth, readinessServerSentEvent, recoverExpiredAgentCandidateExecution, reflectiveGenerator, researchDriverNote, researchLoopRunner, resolveAgentBackend, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runDelegatedLoop, runKnowledgeImprovementJob, runLoopRunnerCli, runPersonaConversation, runPersonaDispatch, runSupervisedKnowledgeUpdate, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sealAgentCandidateBundle, serializeRolloutPolicy, sleep, slugifySpeaker, startRuntimeRun, strategyAuthorMethod, structuralRolloutPolicyFromProfile, toOtelAttributes, toolBuildPrompt, turnId, validateChatModelId, verifyAgentCandidateBundle, worktreeLoopRunner };
+export { 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, NotFoundError, OfficialOptimizerUnavailableError, PlannerError, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, ROLLOUT_POLICY_EXTENSION, RuntimeRunStateError, SqlConversationJournal, ValidationError, agentCandidateProfileAsAgentProfile, agenticGenerator, applyExactAgentProfileDiff, applyRolloutPolicyToProfile, applyRunRecordDefaults, assertCandidateProfileBinding, auditLoopRunner, buildAgentCandidateBundle, buildForwardHeaders, buildKnowledgeImprovementExperimentBundles, buildLoopOtelSpans, buildLoopSpanNodes, buildRuntimeEventOtelSpans, candidateExecutionClaim, candidateKnowledgeExecutionPaths, captureAgentCandidateWorkspace, captureAgentCandidateWorkspaceFiles, cleanModelId, commandVerifier, composeRuntimeHooks, computeBackoff, createAgentCandidateWorkspacePort, createAgentKnowledgeReadinessCheck, createConversationBackend, createIterableBackend, createKnowledgeImprovementActivationExecutor, createOpenInferenceFileExporter, createOtelExporter, createProfileExecutionBackend, createProtectedAgentCandidateModelPort, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createSupervisedKnowledgeUpdater, d1ToSqlAdapter, decideKnowledgeReadiness, defaultBuildPrompt, defaultIsRetryable, defineConversation, defineRuntimeHooks, disposePreparedAgentCandidateExecution, exactProcessProviderAsCandidateExecutor, executePreparedAgentCandidate, exportEvalRuns, findingLines, formatSupervisedKnowledgeTask, freezeGenericAgentCandidateProfile, generateSpanId, getModels, improve, isDelegatedLoopMode, isDepthExceeded, knowledgeReadinessDeliverable, loopEventToOtelSpan, makePerAttemptSignal, mcpBuildPrompt, mcpServeVerifier, mcpToolsForRuntimeMcp, mcpToolsForRuntimeMcpSubset, normalizeRolloutPolicy, notifyRuntimeDecisionPoint, notifyRuntimeHookEvent, officialGepa, officialSkillOpt, omitUndefinedObjectFields, optimizerMethod, padSpanId, padTraceId, parseExactAgentProfile, parseExactAgentProfileDiff, parseExactCandidateProfile, parseLoopRunnerArgv, parseRolloutPolicy, persistCandidateOutputArtifact, prepareAgentCandidateExecution, rawTraceDistiller, readDepth, readinessServerSentEvent, recoverExpiredAgentCandidateExecution, reflectiveGenerator, researchLoopRunner, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runDelegatedLoop, runKnowledgeImprovementJob, runLoopRunnerCli, runPersonaConversation, runPersonaDispatch, runSupervisedKnowledgeUpdate, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sealAgentCandidateBundle, serializeRolloutPolicy, sleep, slugifySpeaker, startRuntimeRun, strategyAuthorMethod, structuralRolloutPolicyFromProfile, toOtelAttributes, toolBuildPrompt, turnId, validateChatModelId, verifyAgentCandidateBundle, worktreeLoopRunner };
 
 //# sourceMappingURL=index.js.map