@tangle-network/agent-runtime 0.15.0 → 0.15.1

package/dist/index.d.ts

@@ -250,6 +250,42 @@ interface EventRecord {
     payload: unknown;
     emittedAt: string;
 }
+/**
+ * A pointer to a substrate run that outlives the worker isolate — the sandbox
+ * container is orchestrator-managed and survives a Worker death or a Durable
+ * Object migration. Persisted on the run row so a fresh supervisor re-attaches
+ * to the in-flight run instead of re-prompting.
+ */
+interface RunHandle {
+    /** Which substrate owns the run. `sandbox` runs are reconnectable;
+     *  `tcloud` runs have no cross-process replay endpoint. */
+    kind: 'sandbox' | 'tcloud';
+    /** Orchestrator-managed sandbox id — stable across worker isolates. */
+    sandboxId?: string;
+    /** Sandbox conversation/session id. */
+    sessionId?: string;
+    /** The substrate run id (the sandbox SDK's `executionId`). The replay
+     *  endpoint keys on it. */
+    runId?: string;
+    /** Lifecycle of the substrate run as last observed. */
+    status: 'running' | 'completed' | 'failed';
+    /** Last substrate event id seen — the adapter's reconnect cursor. */
+    cursor?: string;
+}
+/**
+ * One event in a run's ordered, replayable stream log. The supervisor drains
+ * a run's event stream into this log as it flows, so replay is guaranteed by
+ * the substrate rather than by the sandbox runtime's own buffering.
+ */
+interface StreamEventRecord {
+    runId: string;
+    /** Monotonic 0-based sequence — the store's ordering + cursor. */
+    seq: number;
+    /** Producer-supplied stable id — the dedup key and the substrate cursor. */
+    eventId: string;
+    payload: unknown;
+    appendedAt: string;
+}
 type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'suspended';
 interface RunOutcome {
     pass?: boolean;
@@ -284,6 +320,9 @@ interface RunRecord {
     leaseExpiresAt?: string;
     outcome?: RunOutcome;
     stepCount: number;
+    /** Pointer to the in-flight substrate run, when one has been registered.
+     *  A fresh supervisor re-attaches by it. */
+    handle?: RunHandle;
 }
 /**
  * The durable-run substrate. Implementations: in-memory (dev), file-system
@@ -367,6 +406,31 @@ interface DurableRunStore {
     }>;
     /** Load the cached event payload if it has been emitted. */
     loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    /**
+     * Append an event to the run's ordered stream log. The store assigns the
+     * monotonic `seq`. Idempotent on `eventId`: re-appending a known id is a
+     * no-op that returns the existing record under `accepted: false` — so an
+     * adapter that re-yields a boundary event on reconnect cannot double-log.
+     */
+    appendStreamEvent(input: {
+        runId: string;
+        eventId: string;
+        payload: unknown;
+    }): Promise<{
+        accepted: boolean;
+        record: StreamEventRecord;
+    }>;
+    /**
+     * Read the stream log in `seq` order. `afterSeq` (exclusive) resumes a
+     * reader from a cursor; omit for the whole log.
+     */
+    readStreamEvents(runId: string, afterSeq?: number): Promise<ReadonlyArray<StreamEventRecord>>;
+    /** Persist the run handle — the pointer a fresh supervisor re-attaches by.
+     *  One per run; overwrites. */
+    setRunHandle(input: {
+        runId: string;
+        handle: RunHandle;
+    }): Promise<void>;
     /** Cleanup hook for in-memory / fs stores; no-op for D1. Idempotent. */
     close(): Promise<void>;
 }
@@ -696,6 +760,16 @@ declare class D1DurableRunStore implements DurableRunStore {
         payload: unknown;
     }): ReturnType<DurableRunStore['emitEvent']>;
     loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    appendStreamEvent(input: {
+        runId: string;
+        eventId: string;
+        payload: unknown;
+    }): ReturnType<DurableRunStore['appendStreamEvent']>;
+    readStreamEvents(runId: string, afterSeq?: number): Promise<ReadonlyArray<StreamEventRecord>>;
+    setRunHandle(input: {
+        runId: string;
+        handle: RunHandle;
+    }): Promise<void>;
     close(): Promise<void>;
     /** Inspect the currently-applied schema version. */
     getSchemaVersion(): Promise<number | undefined>;
@@ -774,7 +848,18 @@ declare class FileSystemDurableRunStore implements DurableRunStore {
         payload: unknown;
     }): ReturnType<DurableRunStore['emitEvent']>;
     loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    appendStreamEvent(input: {
+        runId: string;
+        eventId: string;
+        payload: unknown;
+    }): ReturnType<DurableRunStore['appendStreamEvent']>;
+    readStreamEvents(runId: string, afterSeq?: number): Promise<ReadonlyArray<StreamEventRecord>>;
+    setRunHandle(input: {
+        runId: string;
+        handle: RunHandle;
+    }): Promise<void>;
     close(): Promise<void>;
+    private readStreamEventsRaw;
     /** @internal — used by tests to list runs in the store. */
     _listRunIds(): Promise<string[]>;
     private runDir;
@@ -875,6 +960,16 @@ declare class InMemoryDurableRunStore implements DurableRunStore {
         payload: unknown;
     }): ReturnType<DurableRunStore['emitEvent']>;
     loadEvent(runId: string, key: string): Promise<EventRecord | undefined>;
+    appendStreamEvent(input: {
+        runId: string;
+        eventId: string;
+        payload: unknown;
+    }): ReturnType<DurableRunStore['appendStreamEvent']>;
+    readStreamEvents(runId: string, afterSeq?: number): Promise<ReadonlyArray<StreamEventRecord>>;
+    setRunHandle(input: {
+        runId: string;
+        handle: RunHandle;
+    }): Promise<void>;
     close(): Promise<void>;
     /** @internal — used by tests to inspect lease metadata. */
     _inspect(runId: string): RunRecord | undefined;
@@ -983,8 +1078,178 @@ declare function runDurable<TResult>(input: RunDurableInput<TResult>): Promise<R
  * 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";
+declare const DURABLE_SCHEMA_VERSION = 2;
+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\n-- \u2500\u2500 Migration v2 \u2014 durable event-stream log + run handle \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n-- Run once on a database created at v1. `ALTER TABLE` is not idempotent; the\n-- version trail in `durable_schema_info` is how migrations are sequenced \u2014\n-- never by blind re-execution of this block.\n--\n--   - `durable_stream_events` is the ordered, replayable per-run event log.\n--     `seq` is the store-assigned monotonic cursor; the UNIQUE index on\n--     (run_id, event_id) makes appends idempotent \u2014 a reconnecting adapter\n--     that re-yields a boundary event cannot double-log it.\n--   - `durable_runs.handle_json` is the pointer (sandbox + substrate run id +\n--     cursor) a fresh supervisor re-attaches by.\n\nALTER TABLE durable_runs ADD COLUMN handle_json TEXT;\n\nCREATE TABLE IF NOT EXISTS durable_stream_events (\n  run_id       TEXT    NOT NULL,\n  seq          INTEGER NOT NULL,\n  event_id     TEXT    NOT NULL,\n  payload_json TEXT,\n  appended_at  TEXT    NOT NULL,\n  PRIMARY KEY (run_id, seq)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_durable_stream_events_event_id\n  ON durable_stream_events(run_id, event_id);\n\nINSERT OR IGNORE INTO durable_schema_info (version, applied_at)\nVALUES (2, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));\n";
+
+/**
+ * `runSupervisedTurn` — relocates the durability boundary off the ephemeral
+ * worker isolate.
+ *
+ * `runDurableTurn` replays a *completed* turn; an interrupted turn re-runs.
+ * `runSupervisedTurn` closes that gap for sandbox-backed runs: the sandbox
+ * container is orchestrator-managed and outlives the worker, so instead of
+ * re-prompting, a fresh supervisor re-attaches to the in-flight substrate run
+ * and resumes draining its event stream.
+ *
+ * Durability is owned by the substrate, not hoped-for from the sandbox. The
+ * supervisor drains every event into the store's stream log as it flows
+ * (`appendStreamEvent`), persists the reconnect pointer the instant the
+ * substrate yields it (`setRunHandle`), and heartbeats the lease. A fresh
+ * supervisor reads the log for its cursor and calls `adapter.attach` to
+ * resume strictly after it — the append's idempotency on `eventId` dedups
+ * the reconnect seam, so no event is lost and none is delivered twice.
+ *
+ * The platform-agnostic core is here; `SessionSupervisorDO` hosts it on a
+ * Cloudflare Durable Object. The reconnect glue is one typed contract —
+ * `SandboxReconnectAdapter` — implemented once per substrate, never per
+ * product.
+ */
+
+/** One event drained from a supervised run. */
+interface SupervisedEvent<TEvent> {
+    /** Stable substrate id — the dedup key and the reconnect cursor. */
+    eventId: string;
+    payload: TEvent;
+    /**
+     * The substrate run handle, carried on the first frame(s) once the run id
+     * is known. The supervisor persists it so a fresh supervisor can re-attach.
+     * Omit on later frames; the last non-undefined handle wins.
+     */
+    handle?: RunHandle;
+}
+/**
+ * Product-supplied glue to a reconnectable substrate run. The dangerous
+ * reconnect logic — re-attaching to a live distributed run — lives behind
+ * this one typed contract: implement it once per substrate (the sandbox SDK,
+ * etc.), never per product.
+ *
+ * Conformance (asserted by `supervisor.test.ts`):
+ *  - `start()` yields the run's events; at least one early event carries a
+ *    `handle` with `status: 'running'` and a defined `runId`.
+ *  - `attach(handle, afterEventId)` yields only events strictly after
+ *    `afterEventId`, and terminates cleanly when the run has no more.
+ *  - `eventId`s are unique within a run.
+ */
+interface SandboxReconnectAdapter<TEvent> {
+    /** Begin a fresh substrate run. */
+    start(): AsyncIterable<SupervisedEvent<TEvent>>;
+    /**
+     * Re-attach to an in-flight run, resuming strictly after `afterEventId`
+     * (`undefined` → from the first event).
+     */
+    attach(handle: RunHandle, afterEventId: string | undefined): AsyncIterable<SupervisedEvent<TEvent>>;
+}
+/** How the supervised turn resolved. */
+type SupervisedRunMode = 'fresh' | 'resumed' | 'replayed';
+interface RunSupervisorOptions<TEvent> {
+    store: DurableRunStore;
+    /** Stable per-turn run id — the same id on a retry is what enables both
+     *  replay (completed turn) and resume (in-flight turn). */
+    runId: string;
+    manifest: DurableRunManifest;
+    /** Stable per-isolate worker id. */
+    workerId: string;
+    adapter: SandboxReconnectAdapter<TEvent>;
+    /** Lease window in ms. Default 60_000 — deliberately short: the heartbeat
+     *  keeps an actively-draining supervisor's lease alive, so an abandoned
+     *  supervisor's lease lapses fast and a fresh supervisor can take over. */
+    leaseMs?: number;
+    /** Renew the lease at most this often while draining. Default 30_000 —
+     *  must be below `leaseMs` or an active drain loses its own lease. */
+    heartbeatMs?: number;
+    /** Human-readable step label. Default `turn`. */
+    intent?: string;
+    /** Time source override — tests pin this for deterministic heartbeats. */
+    now?: () => number;
+}
+interface SupervisedRunHandle<TEvent> {
+    /** Drop-in stream. Fresh forwards live events; resumed re-yields the logged
+     *  prefix then forwards live events; replayed re-yields the full log. */
+    stream: AsyncGenerator<TEvent, void, unknown>;
+    /** Which path ran. Valid after `stream` drains. */
+    mode(): SupervisedRunMode;
+    /** The durable RunRecord for the turn. Valid after `stream` drains. */
+    record(): RunRecord | undefined;
+}
+declare function runSupervisedTurn<TEvent>(options: RunSupervisorOptions<TEvent>): SupervisedRunHandle<TEvent>;
+
+/**
+ * `SessionSupervisorDO` — the Cloudflare Durable Object host for
+ * `runSupervisedTurn`.
+ *
+ * A stateless Worker isolate is the wrong place to own a 15-minute run: it
+ * dies on a deploy roll or CPU limit. A Durable Object is addressable by
+ * session id and survives across requests — it is the right home for the
+ * supervisor. This host is deliberately thin: all the durability logic lives
+ * in the platform-agnostic `runSupervisedTurn`; the DO only hosts it and
+ * uses an `alarm()` to re-attach a run the response stream abandoned.
+ *
+ * - `fetch` resolves the run, records it, arms the orphan-check alarm, and
+ *   streams the supervised events back. If the client disconnects, the
+ *   supervisor stops being pulled and its short lease lapses.
+ * - `alarm()` is the recovery mechanism: it finds a recorded-but-unfinished
+ *   run and re-drives `runSupervisedTurn` headlessly to completion (events
+ *   land in the durable log; a later `fetch` replays them). A run still held
+ *   by a live `fetch` raises `DurableRunLeaseHeldError` — not orphaned, so
+ *   the alarm just re-arms.
+ *
+ * Structural CF types (`DurableObjectStateLike`) are defined locally so
+ * agent-runtime keeps no dependency on `@cloudflare/workers-types` — the same
+ * discipline as `D1DatabaseLike` in `d1-store.ts`.
+ */
+
+/** Minimal Durable Object storage surface this host uses. Compatible with
+ *  Cloudflare's `DurableObjectStorage`. */
+interface DurableObjectStorageLike {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    /** Schedule the next `alarm()` invocation at an epoch-ms time. */
+    setAlarm(scheduledTime: number): Promise<void>;
+}
+/** Minimal Durable Object state surface — the `state` ctor argument. */
+interface DurableObjectStateLike {
+    storage: DurableObjectStorageLike;
+}
+/**
+ * Product-supplied wiring for the host. `resolveRun` / `resolveOrphan` build
+ * the supervisor inputs (store, adapter, manifest) — the host owns no
+ * product policy.
+ */
+interface SupervisorHostConfig<TEvent, TEnv> {
+    /** Build supervisor inputs for an incoming request. `undefined` → 404. */
+    resolveRun(request: Request, env: TEnv, state: DurableObjectStateLike): Promise<RunSupervisorOptions<TEvent> | undefined>;
+    /** Rebuild supervisor inputs for an orphan re-attach, from the recorded
+     *  runId. `undefined` → the run is untrackable; the host stops tracking it. */
+    resolveOrphan(runId: string, env: TEnv, state: DurableObjectStateLike): Promise<RunSupervisorOptions<TEvent> | undefined>;
+    /** Serialize one event into a response-stream chunk (an SSE or NDJSON
+     *  line — the product owns the framing). */
+    encodeEvent(event: TEvent): string;
+    /** Delay before the orphan-check alarm fires. Default 60_000. */
+    orphanCheckMs?: number;
+    /** Time source — tests pin this. */
+    now?: () => number;
+}
+/** The host instance surface — what a Cloudflare DO runtime invokes. */
+interface SessionSupervisorDO {
+    fetch(request: Request): Promise<Response>;
+    alarm(): Promise<void>;
+}
+/**
+ * Build the `SessionSupervisorDO` class for a product. Export the result from
+ * the Worker entrypoint and bind it in `wrangler.toml`:
+ *
+ *   export const SessionSupervisor = createSessionSupervisorDO(config)
+ *
+ *   # wrangler.toml
+ *   [[durable_objects.bindings]]
+ *   name = "SESSION_SUPERVISOR"
+ *   class_name = "SessionSupervisor"
+ *   [[migrations]]
+ *   tag = "v1"
+ *   new_classes = ["SessionSupervisor"]
+ */
+declare function createSessionSupervisorDO<TEvent, TEnv>(config: SupervisorHostConfig<TEvent, TEnv>): new (state: DurableObjectStateLike, env: TEnv) => SessionSupervisorDO;
 
 /**
  * Cloudflare Workflows integration for the durable-run substrate.
@@ -1206,6 +1471,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 +2009,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 ChatTurnResult, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, type D1DatabaseLike, D1DurableRunStore, type D1PreparedStatementLike, DEFAULT_ROUTER_BASE_URL, DURABLE_SCHEMA_SQL, DURABLE_SCHEMA_VERSION, DurableAwaitEventTimeoutError, DurableChatTurnEngine, type DurableContext, type DurableObjectStateLike, type DurableObjectStorageLike, DurableRunDivergenceError, DurableRunError, DurableRunInputMismatchError, DurableRunLeaseHeldError, type DurableRunManifest, type DurableRunStore, type DurableTurnHandle, type DurableTurnProducer, type EventRecord, FileSystemDurableRunStore, InMemoryDurableRunStore, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, type ModelInfo, type ResolvedChatModel, type RouterEnv, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnInput, type RunChatTurnOptions, type RunDurableInput, type RunDurableResult, type RunDurableTurnOptions, type RunHandle, type RunOnWorkflowStepInput, type RunOutcome, type RunStatus, type RunSupervisorOptions, 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 SandboxReconnectAdapter, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, SessionMismatchError, type SessionSupervisorDO, type StepError, type StepKind, type StepRecord, type StepStatus, type StreamEventRecord, type SubagentMatcher, type SupervisedEvent, type SupervisedRunHandle, type SupervisedRunMode, type SupervisorHostConfig, type TraceBridge, type TraceBridgeOptions, type WorkflowStepConfig, type WorkflowStepLike, assertProfileConformance, canonicalHash, canonicalJson, classifyIntent, cleanModelId, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createSessionSupervisorDO, createTraceBridge, decideKnowledgeReadiness, deriveWorkerId, durableChatTurnEngine, encodeServerSentEvent, getModels, manifestHash, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runChatTurn, runDurable, runDurableTurn, runOnWorkflowStep, runSupervisedTurn, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, stepId, summarizeAgentTaskRun, toAgentEvalTrace, validateChatModelId, withConfiguredModels };