@tangle-network/agent-runtime 0.15.0 → 0.16.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { AgentEvalError, KnowledgeReadinessReport, ControlEvalResult, KnowledgeRequirement, TraceEvent } from '@tangle-network/agent-eval';
 export { AgentEvalError, AgentEvalErrorCode, CaptureIntegrityError, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, ReplayError, RunRecord, UserQuestion, ValidationError, VerificationError } from '@tangle-network/agent-eval';
-import { A as AgentBackendInput, a as AgentExecutionBackend, b as AgentBackendContext, R as RuntimeStreamEvent, c as AgentTaskSpec, K as KnowledgeReadinessDecision, d as RunAgentTaskOptions, e as AgentTaskRunResult, f as RunAgentTaskStreamOptions, g as AgentTaskRunSummary, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-CYxfw14J.js';
-export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext } from './types-CYxfw14J.js';
+import { A as AgentBackendInput, a as AgentExecutionBackend, b as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, c as RunAgentTaskOptions, d as AgentTaskRunResult, e as RunAgentTaskStreamOptions, f as AgentTaskRunSummary, g as AgentTaskSpec, h as AgentRuntimeEvent, i as AgentTaskStatus, j as RuntimeSessionStore, k as RuntimeSession } from './types-DmhXdAhu.js';
+export { l as AgentAdapter, m as AgentKnowledgeProvider, n as AgentRuntimeEventSink, o as AgentTaskContext } from './types-DmhXdAhu.js';
 import { AgentProfilePrompt, AgentProfileResources, AgentSubagentProfile, AgentProfile, SandboxInstance } from '@tangle-network/sandbox';
 
 /**
@@ -177,338 +177,55 @@ declare function sandboxAsChatTurnTarget(instance: SandboxInstance, opts?: {
 }): ChatTurnSandbox;
 
 /**
- * Durable-run substrate: the typed contract for checkpointed agent runs that
- * survive worker crashes, deploy rolls, OOM, and transient transport errors.
+ * 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.
  *
- * The model — directly inspired by Absurd (Postgres-backed) and Cloudflare
- * Workflows — splits a run into ordered, idempotent **steps**. Each step's
- * result is persisted before the next step runs. On resume, the runner reads
- * the prior steps from a `DurableRunStore` and fast-replays them (returning
- * cached values) until it reaches the first unfinished step, where execution
- * actually resumes.
+ * 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.
  *
- * Three boundary disciplines:
- *
- *   1. Step results MUST be JSON-serializable. No closures, no class
- *      instances, no live streams. The store treats results as opaque JSON.
- *
- *   2. Step intents MUST be stable across replays. The runner derives a
- *      stable step id from (runId, stepIndex, intent). Mismatched intent at
- *      the same index = `DurableRunDivergenceError`.
- *
- *   3. Non-determinism (now / uuid / random) MUST flow through the
- *      `DurableContext` helpers — `ctx.now()`, `ctx.uuid()` — so the values
- *      are checkpointed and identical on replay. Bare `Date.now()` /
- *      `crypto.randomUUID()` inside a task fn breaks replay equality.
+ * Wire integration:
+ *   - `@tangle-network/sandbox@0.1.x` PromptOptions does not yet expose
+ *     `executionId`. The SDK auto-reconnects in-call by extracting it
+ *     from the response `execution.started` event; products do nothing.
+ *   - For cross-process reconnect today, bypass the SDK and POST to the
+ *     orchestrator's `/agents/run/stream` directly with this id in the
+ *     `X-Execution-ID` header (see tax-agent's `sessions.ts`).
  */
-
-/** Caller-facing kinds. The runner uses these for telemetry + querying. */
-type StepKind = 
-/** Logical step that ran user code (the default for ctx.step). */
-'logic'
-/** A wrapped LLM call. */
- | 'llm'
-/** A wrapped tool call. */
- | 'tool'
-/** A wrapped readiness probe. */
- | 'readiness'
-/** A deterministic clock or uuid read. */
- | 'deterministic'
-/** A suspend-for-event boundary. */
- | 'event';
-type StepStatus = 'pending' | 'running' | 'completed' | 'failed';
-interface StepError {
-    message: string;
-    code?: string;
-    /** Optional stack — stored for diagnostics, NEVER replayed as an exception. */
-    stack?: string;
-}
-interface StepRecord<T = unknown> {
-    runId: string;
-    /** Monotonic 0-based index. Position is the load-bearing identifier — the
-     *  same intent string at different positions is a different step. */
-    stepIndex: number;
-    /** Caller-supplied label; intended for human reading + log correlation. */
-    intent: string;
-    kind: StepKind;
-    /** sha256 of the canonical input fingerprint at begin-time. Used to detect
-     *  divergence (caller changed inputs across replays). Empty for steps where
-     *  the input cannot be canonicalized (e.g. ctx.now()). */
-    inputHash: string;
-    status: StepStatus;
-    /** Re-entry count. Increments each time the step begins. */
-    attempts: number;
-    /** JSON-serializable result. Present when status === 'completed'. */
-    result?: T;
-    error?: StepError;
-    startedAt?: string;
-    completedAt?: string;
-}
-interface EventRecord {
-    runId: string;
-    key: string;
-    payload: unknown;
-    emittedAt: string;
-}
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'suspended';
-interface RunOutcome {
-    pass?: boolean;
-    score?: number;
-    notes?: string;
-    /** Free-form bag of run-level metrics — surfaced in OTLP / TraceStore. */
-    metadata?: Record<string, unknown>;
-}
-interface DurableRunManifest {
-    /** Stable per-product id (e.g. 'legal-agent', 'creative-agent'). */
+declare function deriveExecutionId(input: {
     projectId: string;
-    /** Optional scenario / persona / session id — surfaced in telemetry. */
-    scenarioId?: string;
-    task: AgentTaskSpec;
-    /** Input payload. Hashed into the run identity so two runs with the same
-     *  runId but different inputs raise DurableRunInputMismatchError. */
-    input: Record<string, unknown>;
-    /** Free-form tags surfaced into RunRecord / OTLP. */
-    tags?: Record<string, string>;
-}
-interface RunRecord {
-    runId: string;
-    manifestHash: string;
-    projectId: string;
-    scenarioId?: string;
-    status: RunStatus;
-    createdAt: string;
-    updatedAt: string;
-    completedAt?: string;
-    /** Stable per-worker id holding the lease. */
-    leaseHolderId?: string;
-    leaseExpiresAt?: string;
-    outcome?: RunOutcome;
-    stepCount: number;
-}
-/**
- * The durable-run substrate. Implementations: in-memory (dev), file-system
- * (eval harness), D1 (Cloudflare prod). All stores share this exact contract
- * — swap by changing one factory call.
- *
- * Concurrency model: at most one worker holds a run's lease at a time. Lease
- * renewal happens on a heartbeat; on lease expiry, another worker can
- * `startOrResume` and pick up. Steps committed by the prior worker survive.
- */
-interface DurableRunStore {
-    /**
-     * Begin or resume a run. Returns the canonical RunRecord, all previously
-     * completed steps (in order), and the lease deadline.
-     *
-     * If the run did not exist, creates it with status='running'. If it existed
-     * with a different manifest hash, throws DurableRunInputMismatchError.
-     * If it existed with a live lease held by a different worker, throws
-     * DurableRunLeaseHeldError (caller can retry or back off).
-     */
-    startOrResume(input: {
-        runId: string;
-        manifest: DurableRunManifest;
-        workerId: string;
-        leaseMs?: number;
-    }): Promise<{
-        run: RunRecord;
-        completedSteps: ReadonlyArray<StepRecord>;
-        leaseExpiresAt: string;
-    }>;
-    /** Renew the lease. Returns false if another worker now holds it. */
-    renewLease(input: {
-        runId: string;
-        workerId: string;
-        leaseMs?: number;
-    }): Promise<{
-        ok: boolean;
-        leaseExpiresAt?: string;
-    }>;
-    /** Load a step by position. Returns undefined if not yet begun. */
-    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
-    /** Record step start (intent + input hash + kind). Bumps attempt count. */
-    beginStep(input: {
-        runId: string;
-        stepIndex: number;
-        intent: string;
-        kind: StepKind;
-        inputHash: string;
-    }): Promise<StepRecord>;
-    /** Mark step completed with a JSON-serializable result. */
-    completeStep(input: {
-        runId: string;
-        stepIndex: number;
-        result: unknown;
-    }): Promise<StepRecord>;
-    /** Mark step failed with a captured error. */
-    failStep(input: {
-        runId: string;
-        stepIndex: number;
-        error: StepError;
-    }): Promise<StepRecord>;
-    /** End the run; releases lease. */
-    endRun(input: {
-        runId: string;
-        workerId: string;
-        status: 'completed' | 'failed';
-        outcome?: RunOutcome;
-    }): Promise<RunRecord>;
-    /**
-     * Emit an event. First emit wins; subsequent emits return the existing
-     * record under `existing` and accepted=false. Caller can treat that as
-     * idempotency-by-design — never double-fire a downstream side effect.
-     */
-    emitEvent(input: {
-        runId: string;
-        key: string;
-        payload: unknown;
-    }): Promise<{
-        accepted: boolean;
-        record: EventRecord;
-    }>;
-    /** Load the cached event payload if it has been emitted. */
-    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
-    /** Cleanup hook for in-memory / fs stores; no-op for D1. Idempotent. */
-    close(): Promise<void>;
-}
-/** Base class for durable-run errors. */
-declare class DurableRunError extends Error {
-    readonly code: 'lease_held' | 'manifest_mismatch' | 'step_divergence' | 'step_input_mismatch' | 'await_event_timeout' | 'event_emit_race';
-    constructor(message: string, code: 'lease_held' | 'manifest_mismatch' | 'step_divergence' | 'step_input_mismatch' | 'await_event_timeout' | 'event_emit_race');
-}
-/** Thrown when another worker holds the lease for this runId. */
-declare class DurableRunLeaseHeldError extends DurableRunError {
-    constructor(message: string);
-}
-/** Thrown when the manifest hash differs from a prior run with the same id. */
-declare class DurableRunInputMismatchError extends DurableRunError {
-    constructor(message: string);
-}
-/** Thrown when the same stepIndex re-runs with a different intent string. */
-declare class DurableRunDivergenceError extends DurableRunError {
-    constructor(message: string);
-}
-/** Thrown when `awaitEvent` times out. */
-declare class DurableAwaitEventTimeoutError extends DurableRunError {
-    constructor(message: string);
-}
-
-/**
- * `runDurableTurn` — a streaming, backend-agnostic, checkpoint+replay durable
- * turn. The single reusable primitive every product's chat handler routes
- * through, so per-product durability code drops to zero.
- *
- * A **turn** is one request→response unit: a producer yields a stream of
- * events and, once drained, exposes the turn's final text. `runDurableTurn`
- * wraps that with a `DurableRunStore`:
- *
- *   - **Fresh run** — no completed step for this `(runId)`. The producer
- *     runs; its events forward live to the caller (streaming preserved)
- *     while final text accumulates; on drain the text is checkpointed.
- *
- *   - **Replay** — a completed step already exists (the worker died after
- *     the turn finished but before the response reached the client, and the
- *     client retried the same turn). The cached text is emitted as a single
- *     synthetic event; the producer is never constructed — no LLM call, no
- *     double-billing.
- *
- *   - **Mid-stream crash** — a turn that died *while streaming* leaves step 0
- *     in `running`/`failed`. There is no partial-stream checkpoint (the
- *     substrate checkpoints JSON values at step granularity), so the turn
- *     re-runs from the top. This is the honest durability ceiling: a
- *     *completed* turn is free to replay; an *interrupted* turn re-runs.
- *
- * Generic over the event type `TEvent` so a product can stream its own NDJSON
- * shape or the runtime's `RuntimeStreamEvent` — `runDurableTurn` never
- * inspects events, it only forwards them and reads `finalText()` after drain.
- *
- * Lease: a turn is a single step, fast enough that the heartbeat in
- * `runDurable` is unnecessary — `runDurableTurn` claims the lease once via
- * `startOrResume` and releases it on `endRun`. Concurrent workers on the same
- * `runId` are rejected with `DurableRunLeaseHeldError` (the client retried
- * before the first attempt finished); callers surface that as "turn already
- * in flight."
- */
-
-/** The live side of a turn — what a fresh run produces. */
-interface DurableTurnProducer<TEvent> {
-    /** The turn's event stream. Forwarded verbatim to the caller. */
-    stream: AsyncGenerator<TEvent, void, unknown>;
-    /** The turn's final assistant text. Read once, after `stream` drains. */
-    finalText(): string;
-}
-interface RunDurableTurnOptions<TEvent> {
-    store: DurableRunStore;
-    /** Stable per-turn run id. Convention: `chat:<threadId>:<turnIndex>`. The
-     *  same id on a retry is what enables replay. */
-    runId: string;
-    manifest: DurableRunManifest;
-    /** Stable per-isolate worker id. Defaults to a fresh `deriveWorkerId()`
-     *  per call when omitted — fine for single-attempt turns. */
-    workerId: string;
-    /** Lease window in ms. Default 60_000 — a turn rarely runs longer. */
-    leaseMs?: number;
-    /** Human-readable step label. Default `turn`. */
-    intent?: string;
-    /** Builds the live producer. Called exactly once, on a fresh run; never
-     *  called on the replay path. */
-    produce: () => DurableTurnProducer<TEvent>;
-    /** Synthesizes the single event emitted on the replay path from the
-     *  cached final text (e.g. a product's `{ type: 'result', data: {...} }`). */
-    replayEvent: (finalText: string) => TEvent;
-    /** Optional live accumulator. When the producer's `finalText()` is only
-     *  valid after drain, this lets `runDurableTurn` also observe each event
-     *  to build the text — return the running text or `undefined` to ignore
-     *  an event. When omitted, `producer.finalText()` is the sole source. */
-    accumulate?: (event: TEvent, current: string) => string | undefined;
-}
-interface DurableTurnHandle<TEvent> {
-    /** Drop-in stream. Fresh runs forward producer events live; replays emit
-     *  exactly one `replayEvent(cachedText)`. */
-    stream: AsyncGenerator<TEvent, void, unknown>;
-    /** The turn's final text. Valid after `stream` drains. */
-    finalText(): string;
-    /** True iff this turn replayed a cached result (no producer ran). Valid
-     *  after `stream` drains. */
-    replayed(): boolean;
-    /** The durable `RunRecord` for this turn. Valid after `stream` drains. */
-    record(): RunRecord | undefined;
-}
-declare function runDurableTurn<TEvent>(options: RunDurableTurnOptions<TEvent>): DurableTurnHandle<TEvent>;
+    sessionId: string;
+    turnIndex: number;
+}): string;
 
 /**
- * `DurableChatTurnEngine` — the framework-neutral chat-turn orchestrator every
- * product chat handler routes through. It owns the parts that were copy-pasted
- * across legal / gtm / creative / tax: durable checkpointing, the NDJSON
- * `StreamEvent` line protocol, the `session.run.*` lifecycle vocabulary, the
- * runtime-run cost ledger, and trace flush. Everything genuinely
- * product-specific is a hook the product supplies.
+ * `handleChatTurn` — framework-neutral chat-turn HTTP orchestrator.
+ * Owns the NDJSON `ChatStreamEvent` line protocol, the `session.run.*`
+ * lifecycle vocabulary, and the persist / post-process / trace-flush
+ * hook order. Returns a `ReadableStream` body the product hands to its
+ * platform `Response`.
  *
- * What the engine owns:
- *   - durable turn (`runDurableTurn`): completed turns replay free, no re-bill
- *   - the `session.run.started` / `session.run.completed` / `session.run.failed`
- *     event envelope around the producer's events
- *   - NDJSON encoding into a `ReadableStream<Uint8Array>` (the body every
- *     product returns, React Router or Hono alike)
- *   - calling the product's persist / post-process hooks in the right order,
- *     after the stream drains, with the assembled final text
- *   - never throwing into the HTTP layer — a producer failure becomes an
- *     `error` + `session.run.failed` event pair, the stream still closes
+ * Execution durability is the substrate's concern: `box.streamPrompt`
+ * auto-reconnects in-call; cross-process reconnect via `X-Execution-ID`
+ * is the product's job. The producer this engine wraps already speaks
+ * that protocol — the engine just frames the events.
  *
- * What the product supplies (`ChatTurnHooks`):
- *   - `produce`     — build the backend stream for this turn (sandbox / router
- *                     / tcloud / runtime — the engine does not care which)
- *   - `persistAssistantMessage` — write the assistant turn to the product DB
- *   - `onTurnComplete` (optional) — post-process (proposals, citations, …)
- *   - `onEvent` (optional)        — per-event side-channel (e.g. DO broadcast)
- *   - `transformFinalText` (optional) — pre-persist transform (e.g. PII redact)
+ * Hooks (`ChatTurnHooks`):
+ *   - `produce`                  — build the backend event stream
+ *   - `persistAssistantMessage`  — write the assistant turn to the product DB
+ *   - `onTurnComplete?`          — post-process (proposals, citations, …)
+ *   - `onEvent?`                 — per-event side channel (e.g. DO broadcast)
+ *   - `transformFinalText?`      — pre-persist transform (e.g. PII redact)
+ *   - `traceFlush?`              — handed to waitUntil so OTLP export lands
  *
- * Framework neutrality: the engine takes already-resolved values
- * (`userId`, identity tuple, parsed message, a `DurableRunStore`, a
- * `waitUntil`), never a `Request` or a `Context`. The product's thin route
- * adapter does auth + parse + access-control, then calls `engine.runTurn(...)`
- * and returns `result.body` as its platform `Response`.
+ * Framework neutrality: takes already-resolved values (`identity` tuple,
+ * a `waitUntil`), never a `Request` or a `Context`. The product's thin
+ * route adapter does auth + parse + access-control, then calls
+ * `handleChatTurn(...)` and returns `result.body` as its platform `Response`.
  */
-
 /** The NDJSON line protocol every product chat client already speaks. */
 interface ChatStreamEvent {
     type: string;
@@ -518,76 +235,56 @@ interface ChatStreamEvent {
  *  scoped products and the user id for session-scoped products. */
 interface ChatTurnIdentity {
     tenantId: string;
-    /** Thread / session id — the durable run is keyed on this + `turnIndex`. */
+    /** Thread / session id. */
     sessionId: string;
     userId: string;
     /** Monotonic 0-based turn index within the session. */
     turnIndex: number;
 }
+/** The live side of a turn — what the product's `produce` hook returns. */
+interface ChatTurnProducer<TEvent extends ChatStreamEvent = ChatStreamEvent> {
+    /** The turn's event stream. Forwarded verbatim to the caller. */
+    stream: AsyncGenerator<TEvent, void, unknown>;
+    /** The turn's final assistant text. Read once, after `stream` drains. */
+    finalText(): string;
+}
 interface ChatTurnHooks {
-    /**
-     * Build the backend stream for this turn. The engine never inspects which
-     * backend this is — sandbox container, tcloud router, direct runtime, a
-     * test double — it only forwards the events and reads `finalText()`.
-     */
-    produce(): DurableTurnProducer<ChatStreamEvent>;
-    /**
-     * Persist the completed assistant message to the product's own store.
-     * Called once, after the stream drains, on a fresh (non-replay) run.
-     * Receives the assembled (and `transformFinalText`-transformed) text.
-     */
+    /** Build the backend stream. The engine forwards events verbatim and
+     *  reads `finalText()` once the stream drains. */
+    produce(): ChatTurnProducer;
+    /** Persist the assistant message to the product's own store. Called
+     *  once, after drain, with the assembled (transform-applied) text. */
     persistAssistantMessage(input: {
         identity: ChatTurnIdentity;
         finalText: string;
-        record: RunRecord | undefined;
     }): Promise<void>;
-    /**
-     * Optional post-processing after persistence — proposal extraction,
-     * citation validation, credit metering, etc. Product policy; the engine
-     * has no shared logic here. Errors are swallowed + logged (post-process
-     * must never fail the turn that already streamed successfully).
-     */
+    /** Optional post-processing (proposals, citations, credit metering …).
+     *  Errors are swallowed + logged — post-process must never fail a turn
+     *  that already streamed successfully. */
     onTurnComplete?(input: {
         identity: ChatTurnIdentity;
         finalText: string;
     }): Promise<void>;
-    /**
-     * Optional per-event side channel (e.g. Durable Object broadcast). Runs
-     * for every event the engine emits, lifecycle envelope included. Errors
-     * are swallowed — a broadcast failure must not break the chat stream.
-     */
+    /** Optional per-event side channel (e.g. DO broadcast). Runs for every
+     *  emitted event, lifecycle envelope included. Errors swallowed — a
+     *  broadcast failure must not break the chat stream. */
     onEvent?(event: ChatStreamEvent): void | Promise<void>;
-    /**
-     * Optional pre-persist transform of the final text (e.g. PII redaction).
-     * Affects only what is persisted; the live stream is never altered.
-     */
+    /** Optional pre-persist transform of the final text (e.g. PII
+     *  redaction). Affects only what is persisted; the live stream is
+     *  never altered. */
     transformFinalText?(text: string): string | Promise<string>;
-    /**
-     * Optional trace flush — resolves when OTLP export completes. The engine
-     * hands it to `waitUntil` so the worker isolate stays alive for the POST.
-     */
+    /** Optional trace flush — resolves when OTLP export completes. Handed
+     *  to `waitUntil` so the worker isolate stays alive for the POST. */
     traceFlush?(): Promise<void>;
 }
 interface RunChatTurnInput {
     identity: ChatTurnIdentity;
-    /** The user's message for this turn. Hashed into the durable run identity. */
-    userMessage: string;
-    /** Product id for telemetry / the durable manifest (`legal-agent`, …). */
-    projectId: string;
-    /** Domain tag for the task spec (`legal`, `gtm`, …). */
-    domain: string;
-    /** Model id, when known — recorded on the manifest. */
-    model?: string;
-    store: DurableRunStore;
     hooks: ChatTurnHooks;
-    /** Worker liveness hook (`ctx.waitUntil` / `executionCtx.waitUntil`). When
-     *  omitted, trace flush is awaited inline before the stream closes. */
+    /** Worker liveness hook. When omitted, trace flush is awaited inline
+     *  before the stream closes. */
     waitUntil?: (p: Promise<unknown>) => void;
-    /** Stable per-isolate worker id. Defaults to a fresh `deriveWorkerId()`. */
-    workerId?: string;
-    /** Lease window in ms. Default 60_000. */
-    leaseMs?: number;
-    /** Optional structured logger for swallowed hook errors. */
+    /** Structured logger for swallowed hook errors. Defaults to
+     *  `console.error` so failures surface without product wiring. */
     log?: (message: string, meta?: Record<string, unknown>) => void;
 }
 interface ChatTurnResult {
@@ -597,496 +294,11 @@ interface ChatTurnResult {
     contentType: 'application/x-ndjson';
 }
 /**
- * The engine. One instance is stateless and reusable across requests — all
- * per-turn state lives in `runTurn`'s closure.
- */
-declare class DurableChatTurnEngine {
-    /**
-     * Run one durable 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.
-     */
-    runTurn(input: RunChatTurnInput): ChatTurnResult;
-}
-/** Convenience singleton — the engine is stateless, one instance is enough. */
-declare const durableChatTurnEngine: DurableChatTurnEngine;
-
-/**
- * D1DurableRunStore — the production path for Cloudflare Workers. Backed by
- * a D1 (SQLite-compatible) database via the binding the worker already holds.
- *
- * Apply `./schema.sql` once before use; the store itself does not run DDL.
- * Migration version is recorded in `durable_schema_info`; consumers can
- * inspect `getSchemaVersion()` if they ship a migration tool.
- *
- * Why structural typing: agent-runtime stays Cloudflare-free at the dep
- * level. Consumers pass their `D1Database` binding — TypeScript matches the
- * minimal `D1DatabaseLike` surface below. Tests use the same interface with
- * a fake.
- */
-
-/**
- * Minimal D1 surface this store uses. Compatible with Cloudflare's
- * `D1Database` from `@cloudflare/workers-types`. Defined locally so
- * agent-runtime does not depend on workers-types at the package level.
- */
-interface D1DatabaseLike {
-    prepare(query: string): D1PreparedStatementLike;
-    batch(statements: D1PreparedStatementLike[]): Promise<unknown[]>;
-}
-interface D1PreparedStatementLike {
-    bind(...values: unknown[]): D1PreparedStatementLike;
-    first<T = unknown>(): Promise<T | null>;
-    all<T = unknown>(): Promise<{
-        results: T[];
-    }>;
-    run(): Promise<{
-        success: boolean;
-        meta?: {
-            changes?: number;
-        };
-    }>;
-}
-declare class D1DurableRunStore implements DurableRunStore {
-    private readonly db;
-    constructor(db: D1DatabaseLike);
-    /** Override for tests — defaults to Date.now(). */
-    now: () => number;
-    startOrResume(input: {
-        runId: string;
-        manifest: DurableRunManifest;
-        workerId: string;
-        leaseMs?: number;
-    }): ReturnType<DurableRunStore['startOrResume']>;
-    renewLease(input: {
-        runId: string;
-        workerId: string;
-        leaseMs?: number;
-    }): Promise<{
-        ok: boolean;
-        leaseExpiresAt?: string;
-    }>;
-    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
-    beginStep(input: {
-        runId: string;
-        stepIndex: number;
-        intent: string;
-        kind: StepKind;
-        inputHash: string;
-    }): Promise<StepRecord>;
-    completeStep(input: {
-        runId: string;
-        stepIndex: number;
-        result: unknown;
-    }): Promise<StepRecord>;
-    failStep(input: {
-        runId: string;
-        stepIndex: number;
-        error: StepError;
-    }): Promise<StepRecord>;
-    endRun(input: {
-        runId: string;
-        workerId: string;
-        status: 'completed' | 'failed';
-        outcome?: RunOutcome;
-    }): Promise<RunRecord>;
-    emitEvent(input: {
-        runId: string;
-        key: string;
-        payload: unknown;
-    }): ReturnType<DurableRunStore['emitEvent']>;
-    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
-    close(): Promise<void>;
-    /** Inspect the currently-applied schema version. */
-    getSchemaVersion(): Promise<number | undefined>;
-    private readSteps;
-    private bumpUpdated;
-}
-
-/**
- * FileSystemDurableRunStore — durable-run substrate backed by a directory
- * tree under a single root. One subdir per run:
- *
- *   <root>/<runId>/
- *     run.json         — RunRecord (rewritten on every mutation; the only
- *                        scalar fields are status/lease, so this stays small)
- *     steps.jsonl      — append-only StepRecord stream; one JSON per line
- *     events.jsonl     — append-only EventRecord stream
- *     lease.json       — current leaseholder + deadline (separate from
- *                        run.json so renewLease writes one tiny file
- *                        instead of round-tripping the whole run record)
- *
- * Concurrency: the eval harness is single-process — we rely on Node's
- * append-mode semantics for atomicity of step / event writes (single-line
- * writes < PIPE_BUF are atomic on POSIX). For run.json / lease.json we write
- * to a `<file>.tmp` then `rename` to make replacement atomic. This is
- * sufficient for the single-process eval harness use case. Multi-process
- * concurrency on the SAME filesystem requires a flock-based extension;
- * for that path use D1DurableRunStore.
- */
-
-declare class FileSystemDurableRunStore implements DurableRunStore {
-    private readonly root;
-    constructor(root: string);
-    /** Override for tests — defaults to Date.now(). */
-    now: () => number;
-    startOrResume(input: {
-        runId: string;
-        manifest: DurableRunManifest;
-        workerId: string;
-        leaseMs?: number;
-    }): ReturnType<DurableRunStore['startOrResume']>;
-    renewLease(input: {
-        runId: string;
-        workerId: string;
-        leaseMs?: number;
-    }): Promise<{
-        ok: boolean;
-        leaseExpiresAt?: string;
-    }>;
-    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
-    beginStep(input: {
-        runId: string;
-        stepIndex: number;
-        intent: string;
-        kind: StepKind;
-        inputHash: string;
-    }): Promise<StepRecord>;
-    completeStep(input: {
-        runId: string;
-        stepIndex: number;
-        result: unknown;
-    }): Promise<StepRecord>;
-    failStep(input: {
-        runId: string;
-        stepIndex: number;
-        error: StepError;
-    }): Promise<StepRecord>;
-    endRun(input: {
-        runId: string;
-        workerId: string;
-        status: 'completed' | 'failed';
-        outcome?: RunOutcome;
-    }): Promise<RunRecord>;
-    emitEvent(input: {
-        runId: string;
-        key: string;
-        payload: unknown;
-    }): ReturnType<DurableRunStore['emitEvent']>;
-    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
-    close(): Promise<void>;
-    /** @internal — used by tests to list runs in the store. */
-    _listRunIds(): Promise<string[]>;
-    private runDir;
-    private readRun;
-    private writeRun;
-    private readLeaseSafe;
-    private writeLease;
-    private readSteps;
-    private appendStep;
-    private bumpRunUpdated;
-}
-
-/**
- * Identity + canonical-hash helpers for the durable-runs substrate.
- *
- * Two boundary disciplines:
- *
- *   1. **Manifest hash** — sha256 over a sorted-key JSON of (projectId,
- *      scenarioId, task.id, task.intent, task.domain, input). Same hash =
- *      same run identity. Used to detect "same runId, different inputs."
- *
- *   2. **Step input hash** — sha256 over a sorted-key JSON of the step's
- *      input fingerprint. Used to detect drift across replays.
- *
- * Sorted-key JSON makes hashes deterministic regardless of object insertion
- * order. NaN / Infinity / undefined / functions / symbols / class instances
- * are rejected — pure JSON only at the boundary, so the hash matches whatever
- * the store round-trips.
+ * 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.
  */
-
-/** sha256-hex over a JSON-canonicalized value. */
-declare function canonicalHash(value: unknown): string;
-/** Canonical JSON: object keys sorted lexicographically; arrays preserved. */
-declare function canonicalJson(value: unknown): string;
-/** Hash a DurableRunManifest into the run identity component. */
-declare function manifestHash(manifest: DurableRunManifest): string;
-/** Stable per-step identifier — hash of (runId, position, intent). */
-declare function stepId(runId: string, stepIndex: number, intent: string): string;
-/**
- * Stable worker id for a single process. Format: `host:pid:rand`. Random
- * suffix prevents collisions when the host/pid pair is short-lived (e.g.,
- * Cloudflare isolates that recycle fast).
- */
-declare function deriveWorkerId(): string;
-
-/**
- * In-memory DurableRunStore for dev + tests. Single-process. All state lives
- * in maps. Lease enforcement is real (Date.now() vs lease deadline) so the
- * crash-recovery + multi-worker race tests run identically against this and
- * the file-system / D1 stores.
- */
-
-declare class InMemoryDurableRunStore implements DurableRunStore {
-    private readonly runs;
-    /** Override for tests — defaults to Date.now(). */
-    now: () => number;
-    startOrResume(input: {
-        runId: string;
-        manifest: DurableRunManifest;
-        workerId: string;
-        leaseMs?: number;
-    }): ReturnType<DurableRunStore['startOrResume']>;
-    renewLease(input: {
-        runId: string;
-        workerId: string;
-        leaseMs?: number;
-    }): Promise<{
-        ok: boolean;
-        leaseExpiresAt?: string;
-    }>;
-    loadStep(runId: string, stepIndex: number): Promise<StepRecord | undefined>;
-    beginStep(input: {
-        runId: string;
-        stepIndex: number;
-        intent: string;
-        kind: StepKind;
-        inputHash: string;
-    }): Promise<StepRecord>;
-    completeStep(input: {
-        runId: string;
-        stepIndex: number;
-        result: unknown;
-    }): Promise<StepRecord>;
-    failStep(input: {
-        runId: string;
-        stepIndex: number;
-        error: StepError;
-    }): Promise<StepRecord>;
-    endRun(input: {
-        runId: string;
-        workerId: string;
-        status: 'completed' | 'failed';
-        outcome?: RunOutcome;
-    }): Promise<RunRecord>;
-    emitEvent(input: {
-        runId: string;
-        key: string;
-        payload: unknown;
-    }): ReturnType<DurableRunStore['emitEvent']>;
-    loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
-    close(): Promise<void>;
-    /** @internal — used by tests to inspect lease metadata. */
-    _inspect(runId: string): RunRecord | undefined;
-    /** @internal — used by tests to simulate lease expiry. */
-    _expireLease(runId: string): void;
-    private requireRun;
-}
-
-/**
- * Durable runner — wraps a user-supplied async function in checkpoint /
- * resume / lease semantics. The user writes plain async code, awaiting
- * `ctx.step(intent, fn)` boundaries. On worker crash, the next caller with
- * the same `runId` skips completed steps and resumes from the first unfinished
- * one.
- *
- * Invariants:
- *
- *   - Step positions are derived from a monotonic counter on the ctx. The
- *     same intent at position N is the same step across replays. If the user
- *     reorders steps, position N changes intent and we raise
- *     DurableRunDivergenceError fail-loud.
- *
- *   - `ctx.now()` and `ctx.uuid()` are checkpointed as zero-input logic steps
- *     with kind='deterministic'. On replay they return the recorded value.
- *
- *   - `awaitEvent` writes a 'event' step that records the event payload on
- *     first awaited completion. On replay, the cached payload returns
- *     synchronously. If the event has not been emitted and the runner is in
- *     a fresh execution, it polls the store until timeout.
- *
- *   - Lease renewal happens on a wall-clock interval (every leaseMs/3). If
- *     the store reports a lost lease, the runner aborts the current step
- *     execution and throws — letting whichever worker holds the lease pick
- *     up. Committed steps survive.
- */
-
-interface DurableContext {
-    readonly runId: string;
-    readonly projectId: string;
-    readonly scenarioId?: string;
-    /**
-     * Execute a checkpointed step. The step is identified by its **position**
-     * (monotonic counter on this ctx); `intent` is a human-readable label that
-     * must stay stable across replays.
-     *
-     * On first execution: runs `fn`, records the result, returns it.
-     * On replay: returns the recorded result WITHOUT calling `fn`.
-     *
-     * The `inputFingerprint` (optional) lets the runner detect "same intent,
-     * different inputs" — it gets hashed and compared. If you don't supply
-     * one, drift is allowed (input not checked).
-     */
-    step<T>(intent: string, fn: () => Promise<T>, opts?: {
-        kind?: StepKind;
-        inputFingerprint?: unknown;
-    }): Promise<T>;
-    /** Race-free first-emit-wins event wait. */
-    awaitEvent<T = unknown>(key: string, opts?: {
-        timeoutMs?: number;
-        pollMs?: number;
-    }): Promise<T>;
-    /** Emit an event. First emit wins. Subsequent emits no-op. */
-    emitEvent(key: string, payload: unknown): Promise<{
-        accepted: boolean;
-    }>;
-    /** Deterministic clock — checkpointed once per call. */
-    now(): Promise<Date>;
-    /** Deterministic uuid — checkpointed once per call. */
-    uuid(): Promise<string>;
-}
-interface RunDurableInput<TResult> {
-    runId: string;
-    manifest: DurableRunManifest;
-    store: DurableRunStore;
-    workerId?: string;
-    leaseMs?: number;
-    /** Total time budget for the run. Used for awaitEvent timeouts; runner
-     *  itself doesn't kill long-running steps (the step fn must respect
-     *  AbortSignal if it cares). */
-    signal?: AbortSignal;
-    taskFn: (ctx: DurableContext) => Promise<TResult>;
-    /** Default outcome on successful completion. */
-    defaultOutcome?: RunOutcome;
-}
-interface RunDurableResult<TResult> {
-    result: TResult;
-    record: RunRecord;
-    /** All steps captured this run (replayed + freshly executed). */
-    steps: ReadonlyArray<StepRecord>;
-}
-declare function runDurable<TResult>(input: RunDurableInput<TResult>): Promise<RunDurableResult<TResult>>;
-
-/**
- * The durable-runs SQL schema as a string constant. Inlined so consumers
- * (Cloudflare Workers via D1) can apply it without bundling a `.sql` file:
- *
- *   import { DURABLE_SCHEMA_SQL } from '@tangle-network/agent-runtime'
- *   await env.DB.exec(DURABLE_SCHEMA_SQL)
- *
- * The canonical source is `src/durable/schema.sql` — this string MUST stay
- * byte-identical to it. The build does not copy `.sql` files into `dist/`,
- * so the constant is the only path consumers have. A unit test asserts the
- * two stay in sync (`durable-schema.test.ts`).
- *
- * `DURABLE_SCHEMA_VERSION` reflects the latest migration version applied by
- * this string. Bump it on every backwards-incompatible change AND add a new
- * migration entry to durable_schema_info instead of mutating prior rows.
- */
-declare const DURABLE_SCHEMA_VERSION = 1;
-declare const DURABLE_SCHEMA_SQL = "-- Durable-run substrate \u2014 versioned schema for D1 / SQLite.\n--\n-- Apply once per database. Subsequent migrations append; never rewrite a\n-- prior version. See `durable_schema_info` for the migration trail.\n--\n-- Concurrency notes for D1:\n--   - SQLite supports UNIQUE constraints for first-emit-wins (`durable_events`\n--     PK is (run_id, key) \u2014 duplicate insert raises, caller treats as \"already\n--     emitted\").\n--   - Lease takeover happens via a conditional UPDATE: we only claim the lease\n--     if (lease_holder_id IS NULL OR lease_expires_at < :now) \u2014 atomic under\n--     SQLite's row-level locking.\n--   - All timestamps stored as ISO-8601 TEXT for cross-platform consistency.\n--   - `result_json` / `error_json` / `outcome_json` / `payload_json` are\n--     JSON-encoded TEXT; the application enforces canonical-JSON discipline at\n--     the boundary so the store stays type-agnostic.\n\nCREATE TABLE IF NOT EXISTS durable_schema_info (\n  version    INTEGER PRIMARY KEY,\n  applied_at TEXT    NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS durable_runs (\n  run_id           TEXT    PRIMARY KEY,\n  manifest_hash    TEXT    NOT NULL,\n  project_id       TEXT    NOT NULL,\n  scenario_id      TEXT,\n  status           TEXT    NOT NULL CHECK (status IN ('pending','running','completed','failed','suspended')),\n  created_at       TEXT    NOT NULL,\n  updated_at       TEXT    NOT NULL,\n  completed_at     TEXT,\n  lease_holder_id  TEXT,\n  lease_expires_at TEXT,\n  outcome_json     TEXT,\n  step_count       INTEGER NOT NULL DEFAULT 0\n);\n\nCREATE INDEX IF NOT EXISTS idx_durable_runs_project_status ON durable_runs(project_id, status);\nCREATE INDEX IF NOT EXISTS idx_durable_runs_lease_expires ON durable_runs(lease_expires_at);\n\nCREATE TABLE IF NOT EXISTS durable_steps (\n  run_id       TEXT    NOT NULL,\n  step_index   INTEGER NOT NULL,\n  intent       TEXT    NOT NULL,\n  kind         TEXT    NOT NULL,\n  input_hash   TEXT    NOT NULL DEFAULT '',\n  status       TEXT    NOT NULL CHECK (status IN ('pending','running','completed','failed')),\n  attempts     INTEGER NOT NULL DEFAULT 0,\n  result_json  TEXT,\n  error_json   TEXT,\n  started_at   TEXT,\n  completed_at TEXT,\n  PRIMARY KEY (run_id, step_index)\n);\n\nCREATE INDEX IF NOT EXISTS idx_durable_steps_status ON durable_steps(run_id, status);\n\nCREATE TABLE IF NOT EXISTS durable_events (\n  run_id     TEXT NOT NULL,\n  key        TEXT NOT NULL,\n  payload_json TEXT,\n  emitted_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, key)\n);\n\nINSERT OR IGNORE INTO durable_schema_info (version, applied_at)\nVALUES (1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));\n";
-
-/**
- * Cloudflare Workflows integration for the durable-run substrate.
- *
- * Two valid deployment patterns on Cloudflare:
- *
- *   A. **Plain Worker + D1DurableRunStore.** Each request invokes
- *      `runDurable(...)` directly against a D1 binding. Survives worker
- *      isolate restarts; lease takeover happens via D1 row-level
- *      conditional UPDATE. The default path; no Workflows binding needed.
- *
- *   B. **Cloudflare Workflows entrypoint.** Wrap an entire `runDurable(...)`
- *      call inside a single Workflow `step.do(...)`. Workflows gives you
- *      retry-on-throw with platform-managed exponential backoff and
- *      survives full Workers deploy rolls. Use it when the task can take
- *      minutes to hours, or when you want the Workflows dashboard for
- *      observability. Inside the step, `runDurable` still uses D1 for
- *      step-level checkpoints — so a half-completed run resumes from
- *      its last checkpoint on retry rather than restarting from scratch.
- *
- * This module provides the surface for pattern B: a thin helper that
- * converts a Workflows `WorkflowStep` into a `DurableContext`. We do not
- * take a runtime dep on `cloudflare:workers` — the integration is purely
- * structural typing.
- *
- * Example (pattern B):
- *
- *   import { WorkflowEntrypoint } from 'cloudflare:workers'
- *   import { runOnWorkflowStep } from '@tangle-network/agent-runtime'
- *
- *   export class LegalChatWorkflow extends WorkflowEntrypoint<Env, ChatParams> {
- *     async run(event, step) {
- *       return runOnWorkflowStep(step, {
- *         workflowName: 'legal-chat',
- *         taskFn: async (ctx) => {
- *           const ready  = await ctx.step('readiness',   () => probeKnowledge(...))
- *           const answer = await ctx.step('llm:turn-1',  () => callLlm(...))
- *           const shipped = await ctx.awaitEvent('shipped', { timeoutMs: 5 * 60_000 })
- *           return { answer, shipped }
- *         },
- *       })
- *     }
- *   }
- *
- * Step ordering, replay semantics, and divergence detection inside the
- * `taskFn` are inherited from Cloudflare's Workflows engine — we
- * intentionally do NOT layer a second durable store inside this path.
- * Pick pattern A or pattern B per agent; do not mix.
- */
-
-/**
- * Structural subset of Cloudflare's `WorkflowStep`. Mirrors the public surface
- * documented at https://developers.cloudflare.com/workflows/build/. Defined
- * here so this module imposes zero `cloudflare:workers` runtime dependency.
- */
-interface WorkflowStepLike {
-    do<T>(name: string, opts: WorkflowStepConfig, fn: () => Promise<T>): Promise<T>;
-    do<T>(name: string, fn: () => Promise<T>): Promise<T>;
-    sleep(name: string, duration: string | number): Promise<void>;
-    waitForEvent<T = unknown>(name: string, opts: {
-        type: string;
-        timeout?: string;
-    }): Promise<{
-        payload: T;
-        timestamp: number;
-        type: string;
-    }>;
-}
-interface WorkflowStepConfig {
-    retries?: {
-        limit: number;
-        delay: string | number;
-        backoff?: 'constant' | 'linear' | 'exponential';
-    };
-    timeout?: string | number;
-}
-interface RunOnWorkflowStepInput<TResult> {
-    /** Logical workflow name; used as a prefix on step ids for filtering. */
-    workflowName: string;
-    /** User task — same shape as runDurable's taskFn. */
-    taskFn: (ctx: DurableContext) => Promise<TResult>;
-    /** Optional per-step retry / timeout policy applied to ctx.step calls. */
-    stepConfig?: WorkflowStepConfig;
-    /** Optional clock — defaults to Date.now. */
-    now?: () => number;
-}
-/**
- * Adapt a Cloudflare `WorkflowStep` into a `DurableContext` and run a task.
- *
- * Every `ctx.step(intent, fn)` becomes `step.do(<name>, fn)` with stable
- * names — Workflows checkpoints + replays based on step name + position,
- * matching our model.
- *
- * `ctx.awaitEvent(key)` becomes `step.waitForEvent(key, { type: key })`.
- * Caller is responsible for emitting from the platform side (e.g. via the
- * Workflows REST API or a sibling worker that publishes events).
- *
- * `ctx.now()` and `ctx.uuid()` go through `step.do` so the values are
- * captured in the platform's checkpoint state and remain stable across
- * replay — same invariant as our own stores.
- */
-declare function runOnWorkflowStep<TResult>(workflowStep: WorkflowStepLike, input: RunOnWorkflowStepInput<TResult>): Promise<TResult>;
+declare function handleChatTurn(input: RunChatTurnInput): ChatTurnResult;
 
 /**
  * @stable
@@ -1206,6 +418,99 @@ interface ClassifyIntentOptions {
  */
 declare function classifyIntent(profile: AgentProfile, message: string, opts?: ClassifyIntentOptions): ClassifyIntentResult;
 
+/**
+ * @stable
+ *
+ * Chat-model resolution + catalog validation — the shared primitive every
+ * product chat handler needs and was, until now, hand-rolling. Lifts the
+ * router `/v1/models` fetch, the fail-closed id validation, and the
+ * precedence resolver out of four near-identical per-repo copies.
+ *
+ * Policy-free by design: callers pass their own precedence order
+ * (`resolveChatModel`) and their own known-good `allowlist`
+ * (`validateChatModelId`), so each product keeps its resolution policy while
+ * 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.
+ */
+/**
+ * A model entry as returned by the Tangle Router `/v1/models` endpoint.
+ * Intentionally minimal — only the fields resolution + validation read.
+ */
+interface ModelInfo {
+    id: string;
+    name?: string;
+    description?: string;
+    /** Provider slug, when the router exposes it (`provider` or `_provider`). */
+    provider?: string;
+    _provider?: string;
+    architecture?: {
+        modality?: string;
+        input_modalities?: string[];
+        output_modalities?: string[];
+    };
+}
+/** Env keys the router base URL is resolved from. */
+interface RouterEnv {
+    TANGLE_ROUTER_URL?: string;
+    TANGLE_ROUTER_BASE_URL?: string;
+}
+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;
+/**
+ * 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.
+ */
+declare function getModels(routerBaseUrl?: string): Promise<ModelInfo[]>;
+/**
+ * Prepend synthetic catalog entries for ids the environment pins but the
+ * router may not list (e.g. a private or self-hosted chat model). Ids already
+ * present in `models` are not duplicated.
+ */
+declare function withConfiguredModels(models: ModelInfo[], extraIds: string[]): ModelInfo[];
+/** Trim a candidate model id; `undefined` for non-strings and blanks. */
+declare function cleanModelId(value: unknown): string | undefined;
+interface ChatModelCandidate {
+    /** Stable label for telemetry — e.g. `request`, `workspace`, `env`. */
+    source: string;
+    model: string | undefined;
+}
+interface ResolvedChatModel {
+    source: string;
+    model: string;
+}
+/**
+ * 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.
+ */
+declare function resolveChatModel(candidates: ChatModelCandidate[], fallback: ResolvedChatModel): ResolvedChatModel;
+type ChatModelValidation = {
+    succeeded: true;
+    value: string;
+} | {
+    succeeded: false;
+    error: string;
+};
+/**
+ * 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.
+ */
+declare function validateChatModelId(modelId: unknown, options?: {
+    /**
+     * Known-good ids that skip the catalog round trip — e.g. the product's
+     * default model plus any env-configured ids.
+     */
+    allowlist?: string[];
+    routerBaseUrl?: string;
+    /** Injectable catalog loader — overridden in tests. */
+    loadModels?: (routerBaseUrl: string) => Promise<ModelInfo[]>;
+}): Promise<ChatModelValidation>;
+
 /**
  * Validate an AgentProfile against canonical conformance rules: tool keys
  * must map to an MCP server entry (not be shell capabilities masquerading
@@ -1651,4 +956,4 @@ declare function createTraceBridge(options: TraceBridgeOptions): TraceBridge;
  */
 declare function toAgentEvalTrace(event: RuntimeStreamEvent, options: TraceBridgeOptions): TraceEvent | undefined;
 
-export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskRunSummary, AgentTaskSpec, AgentTaskStatus, type BackendRetryPolicy, BackendTransportError, type ChatStreamEvent, ChatTurnError, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnMessage, type ChatTurnOverlay, type ChatTurnResult, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, type D1DatabaseLike, D1DurableRunStore, type D1PreparedStatementLike, DURABLE_SCHEMA_SQL, DURABLE_SCHEMA_VERSION, DurableAwaitEventTimeoutError, DurableChatTurnEngine, type DurableContext, DurableRunDivergenceError, DurableRunError, DurableRunInputMismatchError, DurableRunLeaseHeldError, type DurableRunManifest, type DurableRunStore, type DurableTurnHandle, type DurableTurnProducer, type EventRecord, FileSystemDurableRunStore, InMemoryDurableRunStore, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnInput, type RunChatTurnOptions, type RunDurableInput, type RunDurableResult, type RunDurableTurnOptions, type RunOnWorkflowStepInput, type RunOutcome, type RunStatus, type RuntimeEventCollector, type RuntimeRunCompleteInput, type RuntimeRunCost, type RuntimeRunHandle, type RuntimeRunOptions, type RuntimeRunPersistenceAdapter, type RuntimeRunRow, RuntimeRunStateError, type RuntimeRunStatus, RuntimeSession, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeStreamEventSink, type RuntimeStreamEventSummary, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, SessionMismatchError, type StepError, type StepKind, type StepRecord, type StepStatus, type SubagentMatcher, type TraceBridge, type TraceBridgeOptions, type WorkflowStepConfig, type WorkflowStepLike, assertProfileConformance, canonicalHash, canonicalJson, classifyIntent, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createTraceBridge, decideKnowledgeReadiness, deriveWorkerId, durableChatTurnEngine, encodeServerSentEvent, manifestHash, readinessServerSentEvent, runAgentTask, runAgentTaskStream, runChatTurn, runDurable, runDurableTurn, runOnWorkflowStep, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, stepId, summarizeAgentTaskRun, toAgentEvalTrace };
+export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskRunSummary, AgentTaskSpec, AgentTaskStatus, type BackendRetryPolicy, BackendTransportError, type ChatModelCandidate, type ChatModelValidation, type ChatStreamEvent, ChatTurnError, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnMessage, type ChatTurnOverlay, type ChatTurnProducer, type ChatTurnResult, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, DEFAULT_ROUTER_BASE_URL, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, type ModelInfo, type ResolvedChatModel, type RouterEnv, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnInput, type RunChatTurnOptions, type RuntimeEventCollector, type RuntimeRunCompleteInput, type RuntimeRunCost, type RuntimeRunHandle, type RuntimeRunOptions, type RuntimeRunPersistenceAdapter, type RuntimeRunRow, RuntimeRunStateError, type RuntimeRunStatus, RuntimeSession, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeStreamEventSink, type RuntimeStreamEventSummary, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, SessionMismatchError, type SubagentMatcher, type TraceBridge, type TraceBridgeOptions, assertProfileConformance, classifyIntent, cleanModelId, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createTraceBridge, decideKnowledgeReadiness, deriveExecutionId, encodeServerSentEvent, getModels, handleChatTurn, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runChatTurn, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, summarizeAgentTaskRun, toAgentEvalTrace, validateChatModelId, withConfiguredModels };