@tangle-network/agent-runtime 0.82.0 → 0.83.0

package/dist/index.d.ts

@@ -1,27 +1,26 @@
 import { AgentProfile, AgentEvalError, AnalystFinding, KnowledgeReadinessReport, RunRecord, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
 export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
-import { f as AgentBackendInput, g as AgentExecutionBackend, O as OpenAIChatTool, h as OpenAIChatToolChoice, i as OpenAIChatResponseFormat, j as AgentBackendContext, a as RuntimeStreamEvent, K as KnowledgeReadinessDecision, k as RunAgentTaskOptions, l as AgentTaskRunResult, m as RunAgentTaskStreamOptions, n as AgentRuntimeEvent, o as AgentTaskStatus, p as RuntimeSessionStore, q as RuntimeSession, R as RuntimeHooks } from './types-BF-MEsQB.js';
-export { r as AgentAdapter, s as AgentKnowledgeProvider, t as AgentRuntimeEventSink, u as AgentTaskContext, v as AgentTaskSpec, B as BackendErrorDetail, w as RuntimeDecisionEvidenceRef, x as RuntimeDecisionKind, y as RuntimeDecisionPoint, z as RuntimeHookContext, C as RuntimeHookErrorContext, D as RuntimeHookEvent, F as RuntimeHookPhase, G as RuntimeHookTarget, H as RuntimeRunHandle, J as RuntimeRunPersistenceAdapter, M as RuntimeRunRow, N as composeRuntimeHooks, P as defineRuntimeHooks, Q as notifyRuntimeDecisionPoint, T as notifyRuntimeHookEvent, U as startRuntimeRun } from './types-BF-MEsQB.js';
+import { f as AgentBackendInput, O as OpenAIChatTool, g as OpenAIChatToolChoice, h as OpenAIChatResponseFormat, i as AgentExecutionBackend, j as AgentBackendContext, a as RuntimeStreamEvent, K as KnowledgeReadinessDecision, k as RunAgentTaskOptions, l as AgentTaskRunResult, m as RunAgentTaskStreamOptions, n as AgentRuntimeEvent, o as AgentTaskStatus, p as RuntimeSessionStore, q as RuntimeSession, R as RuntimeHooks } from './types-ESeMOj94.js';
+export { r as AgentAdapter, s as AgentKnowledgeProvider, t as AgentRuntimeEventSink, u as AgentTaskContext, v as AgentTaskSpec, B as BackendErrorDetail, w as RuntimeDecisionEvidenceRef, x as RuntimeDecisionKind, y as RuntimeDecisionPoint, z as RuntimeHookContext, C as RuntimeHookErrorContext, D as RuntimeHookEvent, F as RuntimeHookPhase, G as RuntimeHookTarget, H as RuntimeRunHandle, J as RuntimeRunPersistenceAdapter, M as RuntimeRunRow, N as composeRuntimeHooks, P as defineRuntimeHooks, Q as notifyRuntimeDecisionPoint, T as notifyRuntimeHookEvent, U as startRuntimeRun } from './types-ESeMOj94.js';
 import { Scenario, ProfileDispatchFn } from '@tangle-network/agent-eval/campaign';
-import { C as CandidateGenerator } from './mcp-serve-verifier-BvMAV_8U.js';
-export { A as AgenticGeneratorOptions, I as ImprovementDriverOptions, M as McpServeSpec, V as Verifier, a as VerifyResult, b as agenticGenerator, c as commandVerifier, i as improvementDriver, m as mcpServeVerifier } from './mcp-serve-verifier-BvMAV_8U.js';
+import { C as CandidateGenerator } from './mcp-serve-verifier-FL7-ZEb_.js';
+export { A as AgenticGeneratorOptions, I as ImprovementDriverOptions, M as McpServeSpec, V as Verifier, a as VerifyResult, b as agenticGenerator, c as commandVerifier, i as improvementDriver, m as mcpServeVerifier } from './mcp-serve-verifier-FL7-ZEb_.js';
 import { Scenario as Scenario$1, SurfaceProposer, JudgeConfig, MutableSurface, DispatchContext, SelfImproveBudget, SelfImproveLlm, SelfImproveResult } from '@tangle-network/agent-eval/contract';
 import { AgentProfile as AgentProfile$1 } from '@tangle-network/agent-interface';
-import { S as SurfaceImprovementEdit } from './improvement-adapter-CioiEE2z.js';
+import { S as SurfaceImprovementEdit } from './improvement-adapter-CDR8QNVM.js';
 import { I as ImprovementAdapter } from './types-BC3bZpH0.js';
-export { D as DELEGATED_LOOP_MODES, a as DelegatedLoopMode, b as DelegatedLoopRegistry, c as DelegatedLoopResult, d as DelegatedLoopRunner, L as LoopRunnerCliArgs, e as LoopRunnerCliResult, R as ResearchLoopResult, f as ResearchLoopRunnerOptions, g as RunDelegatedLoopOptions, V as VetoedFact, W as WorktreeLoopRunnerOptions, h as auditLoopRunner, i as isDelegatedLoopMode, p as parseLoopRunnerArgv, r as researchLoopRunner, j as runDelegatedLoop, k as runLoopRunnerCli, s as selfImproveLoopRunner, w as worktreeLoopRunner } from './loop-runner-bin-CBkLsyFg.js';
-export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './openai-tools-B-3v06BE.js';
+export { D as DELEGATED_LOOP_MODES, a as DelegatedLoopMode, b as DelegatedLoopRegistry, c as DelegatedLoopResult, d as DelegatedLoopRunner, L as LoopRunnerCliArgs, e as LoopRunnerCliResult, R as ResearchLoopResult, f as ResearchLoopRunnerOptions, g as RunDelegatedLoopOptions, V as VetoedFact, W as WorktreeLoopRunnerOptions, h as auditLoopRunner, i as isDelegatedLoopMode, p as parseLoopRunnerArgv, r as researchLoopRunner, j as runDelegatedLoop, k as runLoopRunnerCli, s as selfImproveLoopRunner, w as worktreeLoopRunner } from './loop-runner-bin-hQDUL8Ld.js';
+export { m as mcpToolsForRuntimeMcp, a as mcpToolsForRuntimeMcpSubset } from './openai-tools-BnrOmGjN.js';
 export { E as EvalRunEvent, a as EvalRunGeneration, b as EvalRunsExportConfig, c as EvalRunsExportResult, I as INTELLIGENCE_WIRE_VERSION, L as LoopSpanNode, d as OtelAttribute, e as OtelExportConfig, O as OtelExporter, f as OtelSpan, g as buildLoopOtelSpans, h as buildLoopSpanNodes, i as createOtelExporter, j as exportEvalRuns, l as loopEventToOtelSpan } from './otel-export-BKmNwiCb.js';
 import '@tangle-network/sandbox';
-import './local-harness-DU7yV6mG.js';
+import './local-harness-sI0S_XNA.js';
 import 'node:child_process';
-import './kb-gate-CuzMYGYM.js';
-import './types-By9LXllv.js';
-import './worktree-fanout-D9Z2dMS9.js';
-import './worktree-harness-Dx8XULW3.js';
+import './kb-gate-CwHO0vz6.js';
+import './types-Driepl87.js';
+import './worktree-fanout-D6xR2CIA.js';
+import './worktree-harness-CX_McRLp.js';
 
 /**
- * @stable
  *
  * Backend factories for `runAgentTaskStream`. Three shapes ship in core:
  *
@@ -32,9 +31,11 @@ import './worktree-harness-Dx8XULW3.js';
  * Adapters stay thin: domain repos own auth, model selection, and the concrete
  * tool surface. The factories handle session creation, stream normalization,
  * and graceful end-of-stream signalling.
+ *
+ * @stable
  */
 
-/** @stable */
+/** Wrap any custom async-iterable stream into a typed `AgentExecutionBackend`. @stable */
 declare function createIterableBackend<TInput extends AgentBackendInput>(options: {
     kind: string;
     start?: AgentExecutionBackend<TInput>['start'];
@@ -42,7 +43,7 @@ declare function createIterableBackend<TInput extends AgentBackendInput>(options
     stream: AgentExecutionBackend<TInput>['stream'];
     stop?: AgentExecutionBackend<TInput>['stop'];
 }): AgentExecutionBackend<TInput>;
-/** @stable */
+/** Build an `AgentExecutionBackend` backed by a sandbox/sidecar `streamPrompt` call. @stable */
 declare function createSandboxPromptBackend<TBox, TInput extends AgentBackendInput = AgentBackendInput>(options: {
     kind?: string;
     getBox(input: TInput, context: Omit<AgentBackendContext, 'session'>): Promise<TBox> | TBox;
@@ -85,7 +86,6 @@ interface BackendRetryPolicy {
     requestTimeoutMs?: number;
 }
 /**
- * @stable
  *
  * OpenAI-compat streaming backend. Routes `runAgentTaskStream` through any
  * `POST /chat/completions` endpoint that speaks OpenAI's SSE protocol —
@@ -117,6 +117,8 @@ interface BackendRetryPolicy {
  * `final.error` onto their `RunRecord.error` — silently treating an empty
  * `finalText` as "agent produced nothing" hides credit exhaustion, auth
  * failure, and upstream outages.
+ *
+ * @stable
  */
 declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput = AgentBackendInput>(options: {
     apiKey: string;
@@ -146,7 +148,6 @@ declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput
 }): AgentExecutionBackend<TInput>;
 
 /**
- * @stable
  *
  * Per-call resilience policy for participant backends: deadline, retry with
  * backoff, and a circuit breaker. Each policy is applied *around* a single
@@ -158,6 +159,8 @@ declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput
  * leaking sockets. Retries replay the same logical turn (same `turnId`) so
  * any caching gateway can dedupe. Circuit breakers are *per participant*: A's
  * failures don't open B's breaker.
+ *
+ * @stable
  */
 /** Pure judgment of whether an error is worth retrying. Defaults: TimeoutError, AbortError, fetch-level network errors. */
 type RetryableErrorPredicate = (err: unknown) => boolean;
@@ -180,9 +183,11 @@ interface BackendCallPolicy {
     /** Circuit breaker that opens after N consecutive failures per participant. */
     circuitBreaker?: CircuitBreakerConfig;
 }
+/** Thrown when the circuit breaker is open for a participant and no retry is allowed yet. */
 declare class CircuitOpenError extends Error {
     constructor(participant: string, retryAfterMs: number);
 }
+/** Thrown when a backend call exceeds its per-attempt deadline. */
 declare class DeadlineExceededError extends Error {
     constructor(deadlineMs: number);
 }
@@ -222,10 +227,10 @@ declare function makePerAttemptSignal(parentSignal: AbortSignal | undefined, dea
 };
 /** Compute the delay before the next attempt. Default: 250ms exponential with jitter. */
 declare function computeBackoff(spec: RetryBackoff | undefined, attempt: number): number;
+/** Resolve after `ms` milliseconds — used for retry backoff in conversation call policy. */
 declare function sleep(ms: number): Promise<void>;
 
 /**
- * @stable
  *
  * Cross-gateway forwarding headers — the wire-level contract that makes
  * agent-to-agent communication composable across organizational boundaries.
@@ -239,6 +244,8 @@ declare function sleep(ms: number): Promise<void>;
  * rules so both sides agree.
  *
  * Full protocol: `docs/agent-bus-protocol.md`.
+ *
+ * @stable
  */
 /** Standard names — lowercased so Headers maps interop on every runtime. */
 declare const FORWARD_HEADERS: {
@@ -293,7 +300,6 @@ declare function buildForwardHeaders(input: {
 type PropagatedHeaders = Readonly<Record<string, string>>;
 
 /**
- * @stable
  *
  * Durable conversation transcript — survives a driver process crash mid-run.
  * The runner journals every committed turn before yielding `turn_end`, so a
@@ -306,6 +312,8 @@ type PropagatedHeaders = Readonly<Record<string, string>>;
  * is ~30 lines. The in-memory adapter is the default for tests and scratch.
  * The file adapter (JSONL on disk) is the default-durable choice when no
  * upstream store is wired.
+ *
+ * @stable
  */
 
 interface ConversationJournalEntry {
@@ -342,6 +350,7 @@ interface ConversationJournal {
      */
     recordHalt(runId: string, halt: HaltReason, endedAt: string): Promise<void>;
 }
+/** In-memory `ConversationJournal` — suitable for testing and single-process runs. */
 declare class InMemoryConversationJournal implements ConversationJournal {
     private readonly entries;
     loadRun(runId: string): Promise<ConversationJournalEntry | undefined>;
@@ -370,7 +379,6 @@ declare class FileConversationJournal implements ConversationJournal {
 }
 
 /**
- * @stable
  *
  * Public types for multi-agent conversations. A `Conversation` is two-or-more
  * participants taking turns through their own `AgentExecutionBackend`s, driven
@@ -380,6 +388,8 @@ declare class FileConversationJournal implements ConversationJournal {
  * in-process iterable, local cli-bridge, sandbox, router, or a remote
  * agent-gateway — so the same `runConversation` call drives same-machine,
  * same-cloud, and cross-cloud orchestration without code change.
+ *
+ * @stable
  */
 
 /** @stable */
@@ -642,7 +652,6 @@ type ConversationStreamEvent = {
 };
 
 /**
- * @stable
  *
  * Wrap a `Conversation` so it satisfies `AgentExecutionBackend`. The result is
  * an addressable "single agent" whose internal behavior is an N-party
@@ -654,6 +663,8 @@ type ConversationStreamEvent = {
  * callers see one `text_delta` per inner turn (the turn's full text), tagged
  * with `[speaker] ` prefix so the outer transcript stays attributable. The
  * conversation's `conversation_end` halt reason rides on a `final` event.
+ *
+ * @stable
  */
 
 declare function createConversationBackend(options: {
@@ -663,12 +674,13 @@ declare function createConversationBackend(options: {
 }): AgentExecutionBackend;
 
 /**
- * @stable
  *
  * Declarative constructor for a multi-agent `Conversation`. Validates inputs
  * fail-loud at definition time (duplicate participant names, alternate order
  * with ≠2 participants, non-positive `maxTurns`) so misconfiguration is caught
  * before `runConversation` is called and not buried inside a streaming run.
+ *
+ * @stable
  */
 
 declare function defineConversation(input: {
@@ -677,7 +689,6 @@ declare function defineConversation(input: {
 }): Conversation;
 
 /**
- * @stable
  *
  * Durable conversation journal backed by any SQL store. Adapter-agnostic by
  * design: callers wire a `SqlAdapter` against their driver of choice (D1,
@@ -711,6 +722,8 @@ declare function defineConversation(input: {
  *   }
  *   const journal = new SqlConversationJournal(pg)
  *   await journal.migrate()
+ *
+ * @stable
  */
 
 /**
@@ -777,7 +790,6 @@ declare class SqlConversationJournal implements ConversationJournal {
 }
 
 /**
- * @stable
  *
  * Conversation orchestrator. Drives N participants in turn through their own
  * `AgentExecutionBackend`s, aggregating per-turn text + usage, enforcing
@@ -805,9 +817,12 @@ declare class SqlConversationJournal implements ConversationJournal {
  * Credit cap is enforced *between turns*, not mid-stream: a turn that
  * overshoots the cap completes, the cap then halts the conversation before
  * the next turn.
+ *
+ * @stable
  */
 
 declare function runConversation(conversation: Conversation, options: RunConversationOptions): Promise<ConversationResult>;
+/** Streaming conversation orchestrator: drives N participants in turn through their own backends, enforcing `maxTurns` / `maxCreditsCents` / `haltOn`, yielding per-event stream markers. */
 declare function runConversationStream(conversation: Conversation, options: RunConversationOptions): AsyncIterable<ConversationStreamEvent>;
 
 /**
@@ -896,7 +911,6 @@ interface RunPersonaConfig<TScenario extends Scenario, TArtifact> {
 declare function runPersonaDispatch<TScenario extends Scenario, TArtifact>(config: RunPersonaConfig<TScenario, TArtifact>): ProfileDispatchFn<TScenario, TArtifact>;
 
 /**
- * @stable
  *
  * Deterministic turn identifier. Stable across retries of the same logical
  * turn so backends (and any caching gateway in between) can dedupe on it.
@@ -906,6 +920,8 @@ declare function runPersonaDispatch<TScenario extends Scenario, TArtifact>(confi
  * Shape: `${runId}.t${index}.${speakerSlug}` — readable in logs, sortable by
  * turn index, attributable to a speaker. Slugify keeps the speaker portion
  * URL-safe so it can ride in HTTP headers without escaping.
+ *
+ * @stable
  */
 declare function turnId(runId: string, index: number, speaker: string): string;
 /**
@@ -1038,7 +1054,6 @@ declare function deriveExecutionId(input: {
 }): string;
 
 /**
- * @stable
  *
  * Error taxonomy for `@tangle-network/agent-runtime`.
  *
@@ -1057,15 +1072,18 @@ declare function deriveExecutionId(input: {
  * backend, backend transport errors) get fresh subclasses that still carry an
  * `AgentEvalErrorCode` so cross-package handlers can pattern-match without
  * importing the runtime.
+ *
+ * @stable
  */
 
 /**
- * @stable
  *
  * A backend transport call (HTTP, gRPC, sidecar IPC) failed with a non-success
  * status. Distinct from `JudgeError` (which is structural / unrecoverable)
  * because backend failures are sometimes retryable and consumers may want to
  * branch on the upstream status code.
+ *
+ * @stable
  */
 declare class BackendTransportError extends AgentEvalError {
     readonly backend: string;
@@ -1084,10 +1102,11 @@ declare class BackendTransportError extends AgentEvalError {
     });
 }
 /**
- * @stable
  *
  * A runtime-run lifecycle method was called in an order the state machine does
  * not allow: `persist()` before `complete()`, `complete()` twice, etc.
+ *
+ * @stable
  */
 declare class RuntimeRunStateError extends AgentEvalError {
     constructor(message: string, options?: {
@@ -1095,7 +1114,6 @@ declare class RuntimeRunStateError extends AgentEvalError {
     });
 }
 /**
- * @stable
  *
  * The dynamic-loop planner returned an unusable topology move — the LLM emitted
  * no parseable envelope, an unknown `kind`, or a structurally-invalid move
@@ -1104,6 +1122,8 @@ declare class RuntimeRunStateError extends AgentEvalError {
  * cannot drive the kernel. Carries `validation` so cross-package handlers can
  * pattern-match without importing the runtime. Fail loud — never substitute a
  * default move, or the loop silently runs a topology nobody chose.
+ *
+ * @stable
  */
 declare class PlannerError extends AgentEvalError {
     constructor(message: string, options?: {
@@ -1132,11 +1152,12 @@ type FindingsArg = {
     report: unknown;
     findings: AnalystFinding[];
 };
+/** Build the starting instruction for a coder agent tasked with implementing a new tool. */
 declare function toolBuildPrompt(args: FindingsArg): string;
+/** Build the starting instruction for a coder agent tasked with implementing a new MCP server. */
 declare function mcpBuildPrompt(args: FindingsArg): string;
 
 /**
- * @experimental
  *
  * `improve` — the ONE public, surface-pluggable RSI verb.
  *
@@ -1159,6 +1180,8 @@ declare function mcpBuildPrompt(args: FindingsArg): string;
  *
  * Everything else (`scenarios`, `judge`, `agent`, `budget`, `llm`) passes
  * straight through to `selfImprove`.
+ *
+ * @experimental
  */
 
 /** The agent-profile lever `improve` optimizes. Mirrors the AgentProfile-law
@@ -1221,7 +1244,6 @@ interface ImproveResult<TScenario extends Scenario$1, TArtifact> {
 declare function improve<TScenario extends Scenario$1, TArtifact>(profile: AgentProfile$1, findings: unknown[], opts: ImproveOptions<TScenario, TArtifact>): Promise<ImproveResult<TScenario, TArtifact>>;
 
 /**
- * @experimental
  *
  * `reflectiveGenerator` — the cheap, no-sandbox `CandidateGenerator`. It drafts
  * surface edits via the existing improvement adapter (`proposeFromFindings`,
@@ -1232,15 +1254,17 @@ declare function improve<TScenario extends Scenario$1, TArtifact>(profile: Agent
  * This is the `shots=1, sandbox=off` setting of the one improvement driver.
  * The `agenticGenerator` (a multi-shot verify-in-session loop) is the
  * `shots=N` setting — both plug into the same `improvementDriver`.
+ *
+ * @experimental
  */
 
 interface ReflectiveGeneratorOptions {
     improvementAdapter: ImprovementAdapter<SurfaceImprovementEdit>;
 }
+/** Cheap no-sandbox `CandidateGenerator` (the `shots=1` setting): draft surface edits via the improvement adapter and apply them as one coherent candidate. */
 declare function reflectiveGenerator(opts: ReflectiveGeneratorOptions): CandidateGenerator;
 
 /**
- * @stable
  *
  * Chat-model resolution + catalog validation — the shared primitive every
  * product chat handler needs and was, until now, hand-rolling. Lifts the
@@ -1253,6 +1277,8 @@ declare function reflectiveGenerator(opts: ReflectiveGeneratorOptions): Candidat
  * sharing the catalog fetch, the malformed-id guard, and the fail-closed
  * admission rule. No React, no `process.env` assumption — `env` is an
  * explicit narrow record so this runs unchanged in Node and in Workers.
+ *
+ * @stable
  */
 /**
  * A model entry as returned by the Tangle Router `/v1/models` endpoint.
@@ -1276,6 +1302,7 @@ interface RouterEnv {
     TANGLE_ROUTER_URL?: string;
     TANGLE_ROUTER_BASE_URL?: string;
 }
+/** Default Tangle Router base URL used when no env override is set. */
 declare const DEFAULT_ROUTER_BASE_URL = "https://router.tangle.tools";
 /** Resolve the router base URL from env, normalised — no trailing `/v1` or `/`. */
 declare function resolveRouterBaseUrl(env?: RouterEnv): string;
@@ -1327,7 +1354,6 @@ declare function validateChatModelId(modelId: unknown, options?: {
 }): Promise<ChatModelValidation>;
 
 /**
- * @stable
  *
  * Pure readiness-decision helper. Maps a `KnowledgeReadinessReport` from
  * `@tangle-network/agent-eval` to a three-state branch (`ready` / `blocked` /
@@ -1337,15 +1363,89 @@ declare function validateChatModelId(modelId: unknown, options?: {
  * agent-eval; callers tightening or loosening this should keep it consistent
  * across all entry points for the same product so the UI / metrics agree on
  * what "caveat" means.
+ *
+ * @stable
  */
 
-/** @stable */
+/**
+ * Map a `KnowledgeReadinessReport` to a three-state branch (`ready` / `blocked` / `caveat`) the runtime, route handlers, and UI shells all switch on.
+ *
+ * @stable
+ */
 declare function decideKnowledgeReadiness(report: KnowledgeReadinessReport, options?: {
     minimumScore?: number;
 }): KnowledgeReadinessDecision;
 
 /**
- * @stable
+ * 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 `runLoop` 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`, `fetchImpl`, `retry`) are forwarded verbatim
+ * so a product can advertise its app tools or install a capturing fetch without
+ * re-opening the branch this consolidation closes.
+ */
+
+/** The transport a chat backend runs on. */
+type AgentBackendKind = 'router' | 'tcloud' | 'cli-bridge' | 'sandbox';
+/**
+ * OpenAI-compat passthrough forwarded to `createOpenAICompatibleBackend` for
+ * the `router` / `tcloud` / `cli-bridge` kinds. Mirrors that factory's optional
+ * inputs so a product keeps its tool advertising / capture-fetch without
+ * re-implementing the backend branch.
+ */
+type OpenAICompatPassthrough = Pick<Parameters<typeof createOpenAICompatibleBackend>[0], 'tools' | 'toolChoice' | 'responseFormat' | 'fetchImpl' | 'retry'>;
+interface ResolveAgentBackendOptions<TInput extends AgentBackendInput = AgentBackendInput> extends OpenAICompatPassthrough {
+    /** The chat transport to resolve. */
+    kind: AgentBackendKind;
+    /**
+     * Bearer credential for the OpenAI-compat kinds. Empty string is valid for a
+     * loopback-anonymous cli-bridge; a `router`/`tcloud` route with an empty key
+     * is a caller bug the product surfaces before calling in.
+     */
+    apiKey: string;
+    /** Base URL for the OpenAI-compat kinds. cli-bridge's is its `/v1`. */
+    baseUrl: string;
+    /** Model id sent on every request. cli-bridge rejects a request without it. */
+    model: string;
+    /** `kind` label stamped on the resolved backend + its traces. Defaults to `kind`. */
+    label?: string;
+    /**
+     * `sandbox` kind: the product's own domain backend. Required for that kind —
+     * the substrate owns no product sandbox shape, so a `sandbox` resolution with
+     * no seam is a caller bug, not a silent fallback.
+     */
+    sandboxBackend?: () => AgentExecutionBackend<TInput>;
+}
+/**
+ * Resolve the `AgentExecutionBackend` for the chosen `kind`. Reuse this instead
+ * of hand-rolling the `createOpenAICompatibleBackend` branch in each product.
+ */
+declare function resolveAgentBackend<TInput extends AgentBackendInput = AgentBackendInput>(opts: ResolveAgentBackendOptions<TInput>): AgentExecutionBackend<TInput>;
+
+/**
  *
  * The two top-level entry points:
  *
@@ -1356,6 +1456,8 @@ declare function decideKnowledgeReadiness(report: KnowledgeReadinessReport, opti
  * 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
  */
 
 /** Stamp cross-cutting defaults onto adapter-projected RunRecords without
@@ -1367,18 +1469,27 @@ declare function decideKnowledgeReadiness(report: KnowledgeReadinessReport, opti
  *     agent in one vocabulary instead of per-agent ad-hoc strings. */
 declare function applyRunRecordDefaults(records: RunRecord[], scenarioId: string, controlFailureClass: string | undefined): RunRecord[];
 
-/** @stable */
+/**
+ * Single-shot task lifecycle for adapter-driven tasks: readiness-gated, emits the runtime lifecycle event vocabulary, session-store pluggable.
+ *
+ * @stable
+ */
 declare function runAgentTask<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(options: RunAgentTaskOptions<TState, TAction, TActionResult, TEval>): Promise<AgentTaskRunResult<TState, TAction, TActionResult, TEval>>;
-/** @stable */
+/**
+ * Streaming task lifecycle: delegates execution to an `AgentExecutionBackend` (model API, sandbox, or custom iterable) and yields lifecycle events as they happen.
+ *
+ * @stable
+ */
 declare function runAgentTaskStream<TInput extends AgentBackendInput = AgentBackendInput>(options: RunAgentTaskStreamOptions<TInput>): AsyncIterable<RuntimeStreamEvent>;
 
 /**
- * @stable
  *
  * Sanitization for runtime telemetry. The rule: nothing user-controlled leaks
  * unless the caller opts in with a `RuntimeTelemetryOptions` flag. This is the
  * envelope that ends up in `agent_run.metadata.runtimeEvents` on every
  * consumer, so the default must be safe.
+ *
+ * @stable
  */
 
 /** @stable */
@@ -1430,11 +1541,11 @@ interface SanitizedKnowledgeReadinessReport {
     evidenceIds?: string[];
     missingRequirementIds: string[];
 }
-/** @stable */
+/** Strip PII and large blobs from a `KnowledgeReadinessReport` for safe telemetry emission. @stable */
 declare function sanitizeKnowledgeReadinessReport(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions): SanitizedKnowledgeReadinessReport;
-/** @stable */
+/** Reduce an `AgentRuntimeEvent` to a PII-safe, serializable plain object for telemetry. @stable */
 declare function sanitizeAgentRuntimeEvent<TState, TAction, TActionResult, TEval extends ControlEvalResult>(event: AgentRuntimeEvent<TState, TAction, TActionResult, TEval>, options?: RuntimeTelemetryOptions): Record<string, unknown>;
-/** @stable */
+/** Reduce a `RuntimeStreamEvent` to a PII-safe, serializable plain object for telemetry. @stable */
 declare function sanitizeRuntimeStreamEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions): Record<string, unknown>;
 /** @stable */
 interface RuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult> {
@@ -1465,10 +1576,9 @@ interface RuntimeStreamEventCollector {
     /** Snapshot of a small streaming-flavored summary derived from collected events. */
     summary(): RuntimeStreamEventSummary;
 }
-/** @stable */
+/** Build an in-memory collector that sanitizes and accumulates `AgentRuntimeEvent`s for inspection. @stable */
 declare function createRuntimeEventCollector<TState = unknown, TAction = unknown, TActionResult = unknown, TEval extends ControlEvalResult = ControlEvalResult>(options?: RuntimeTelemetryOptions): RuntimeEventCollector<TState, TAction, TActionResult, TEval>;
 /**
- * @stable
  *
  * Streaming-event counterpart of `createRuntimeEventCollector`. Pass each
  * event yielded by `runAgentTaskStream` through `onEvent` and read the
@@ -1476,19 +1586,22 @@ declare function createRuntimeEventCollector<TState = unknown, TAction = unknown
  * flags apply. Kept distinct from `createRuntimeEventCollector` because the
  * stream and non-stream event shapes overlap on `type` literals — dispatching
  * on `type` alone would misroute events.
+ *
+ * @stable
  */
 declare function createRuntimeStreamEventCollector(options?: RuntimeTelemetryOptions): RuntimeStreamEventCollector;
 
 /**
- * @stable
  *
  * Session helpers + an in-memory `RuntimeSessionStore` implementation suitable
  * for tests, scratch processes, and per-request scratch storage in serverless
  * runtimes. Durable stores (D1, postgres, Durable Objects) implement the same
  * interface from `./types`.
+ *
+ * @stable
  */
 
-/** @stable */
+/** In-memory `RuntimeSessionStore` for single-process use and tests. @stable */
 declare class InMemoryRuntimeSessionStore implements RuntimeSessionStore {
     private readonly sessions;
     private readonly events;
@@ -1499,7 +1612,6 @@ declare class InMemoryRuntimeSessionStore implements RuntimeSessionStore {
 }
 
 /**
- * @stable
  *
  * Server-Sent Events serialization for runtime telemetry streams.
  *
@@ -1507,6 +1619,8 @@ declare class InMemoryRuntimeSessionStore implements RuntimeSessionStore {
  * a space (browsers terminate fields on newline), and multi-line `data`
  * payloads are split into one `data:` line per source line so JSON.stringify
  * output transports cleanly.
+ *
+ * @stable
  */
 
 /** @stable */
@@ -1515,9 +1629,9 @@ interface ServerSentEventOptions {
     id?: string;
     retry?: number;
 }
-/** @stable */
+/** Serialize a `KnowledgeReadinessReport` as a Server-Sent Event string. @stable */
 declare function readinessServerSentEvent(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
-/** @stable */
+/** Serialize a `RuntimeStreamEvent` as a Server-Sent Event string. @stable */
 declare function runtimeStreamServerSentEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
 
 /**
@@ -1683,4 +1797,4 @@ interface StreamToolLoopOptions<Raw> {
  *  `capped` if it stops for any non-completed reason with calls still pending. */
 declare function streamToolLoop<Raw>(opts: StreamToolLoopOptions<Raw>): AsyncGenerator<StreamToolLoopYield<Raw>, void, unknown>;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, CandidateGenerator, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, type ImproveOptions, type ImproveResult, type ImproveSurface, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatResponseFormat, OpenAIChatTool, OpenAIChatToolChoice, type PersonaConversationResult, type PersonaDriver, PlannerError, type PropagatedHeaders, type ReflectiveGeneratorOptions, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type RunToolLoopOptions, type RuntimeEventCollector, RuntimeHooks, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type StreamToolLoopOptions, type StreamToolLoopYield, type ToolCallOutcome, type ToolLoopAssistantToolCall, type ToolLoopCall, type ToolLoopEvent, type ToolLoopMessage, type ToolLoopResult, type ToolLoopStopReason, type TurnOrder, applyRunRecordDefaults, buildForwardHeaders, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, getModels, handleChatTurn, improve, isDepthExceeded, makePerAttemptSignal, mcpBuildPrompt, readDepth, readinessServerSentEvent, reflectiveGenerator, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, runToolLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sleep, slugifySpeaker, streamToolLoop, toolBuildPrompt, turnId, validateChatModelId };
+export { AgentBackendContext, AgentBackendInput, type AgentBackendKind, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskStatus, type AuthSource, type BackendCallPolicy, BackendTransportError, CandidateGenerator, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type CircuitBreakerConfig, CircuitBreakerState, CircuitOpenError, type Conversation, type ConversationDriveState, type ConversationJournal, type ConversationJournalEntry, type ConversationParticipant, type ConversationPolicy, type ConversationResult, type ConversationStreamEvent, type ConversationTurn, type D1DatabaseLike, type D1StmtLike, DEFAULT_MAX_DEPTH, DEFAULT_ROUTER_BASE_URL, DeadlineExceededError, FORWARD_HEADERS, FileConversationJournal, type ForwardHeaderName, type HaltContext, type HaltPredicate, type HaltReason, type HaltSignal, type ImproveOptions, type ImproveResult, type ImproveSurface, InMemoryConversationJournal, InMemoryRuntimeSessionStore, type ModelInfo, OpenAIChatResponseFormat, OpenAIChatTool, OpenAIChatToolChoice, type PersonaConversationResult, type PersonaDriver, PlannerError, type PropagatedHeaders, type ReflectiveGeneratorOptions, type ResolveAgentBackendOptions, type ResolvedChatModel, type RetryBackoff, type RetryableErrorPredicate, type RouterEnv, type RunChatTurnInput, type RunConversationOptions, type RunPersonaConfig, type RunPersonaConversationOptions, type RunToolLoopOptions, type RuntimeEventCollector, RuntimeHooks, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SqlAdapter, SqlConversationJournal, type StreamToolLoopOptions, type StreamToolLoopYield, type ToolCallOutcome, type ToolLoopAssistantToolCall, type ToolLoopCall, type ToolLoopEvent, type ToolLoopMessage, type ToolLoopResult, type ToolLoopStopReason, type TurnOrder, applyRunRecordDefaults, buildForwardHeaders, cleanModelId, computeBackoff, createConversationBackend, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, d1ToSqlAdapter, decideKnowledgeReadiness, defaultIsRetryable, defineConversation, deriveExecutionId, getModels, handleChatTurn, improve, isDepthExceeded, makePerAttemptSignal, mcpBuildPrompt, readDepth, readinessServerSentEvent, reflectiveGenerator, resolveAgentBackend, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runConversation, runConversationStream, runPersonaConversation, runPersonaDispatch, runToolLoop, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, sleep, slugifySpeaker, streamToolLoop, toolBuildPrompt, turnId, validateChatModelId };