@happyvertical/smrt-web 0.51.32 → 0.51.34

package/dist/ai.d.ts

@@ -1,358 +1,330 @@
-/**
- * Reject a turn this module's backends cannot faithfully carry, narrowing
- * `messages` to {@link InferenceTextMessage} on success.
- *
- * Every backend here is a TEXT conversation: roles `user`/`assistant`/
- * `system`, string content, no tools. Each of those limits is a real
- * difference between the backends' transports, so refusing up front is the
- * only way a caller can tell "this backend can't carry my turn" from "this
- * backend answered". The route wire contract (`chat-stream.ts`
- * `normalizeMessages`) and the local adapter both silently DROP exactly these
- * shapes, which is why this check is shared rather than reimplemented per
- * backend — two copies would drift, and the whole point is that both backends
- * agree.
- *
- * `backendLabel` names the backend in the message so a caller knows which one
- * refused.
- */
-export declare function assertTextOnlyTurn(backendLabel: string, messages: InferenceMessage[], options?: InferenceChatOptions): asserts messages is InferenceTextMessage[];
-
-/**
- * Create the browser's single inference path over `options.backends`.
- *
- * Resolution happens inside every `chat`/`stream` call, so a `preference` or
- * `select()` change made between calls is honored by the next one. A call
- * whose resolution finds nothing usable throws `InferencePathError` with
- * `code: 'no_usable_backend'` rather than falling back to a fake answer.
- */
-export declare function createInferencePath(options: InferencePathOptions): InferencePath;
-
-/**
- * A backend over a `text/event-stream` inference route.
- *
- * The wire contract is `@happyvertical/smrt-chat`'s `ChatStreamEvent` framing
- * (token deltas, then a terminal `done` or `error`), consumed here without
- * depending on that package: smrt-web carries no inter-SMRT dependencies, so
- * the frame vocabulary is mirrored the same way the rest of this module is.
- *
- * `status` is always `'ready'` — there is nothing to load — so an `auto` path
- * picks this backend until a local one reports ready. It defines neither
- * `load` nor `unload`, so a control must not offer those actions for it.
- *
- * A turn this wire cannot carry (tool turns, multimodal content, tool
- * definitions) is REFUSED with `unsupported_message` rather than forwarded:
- * the route silently drops those shapes, so forwarding would answer a
- * different question than the caller asked.
- */
-export declare function createRouteInferenceBackend(options: RouteInferenceBackendOptions): InferenceBackend;
-
-export declare interface InferenceBackend {
-    /** Stable id, unique across a path. A preference names this. */
-    readonly id: string;
-    /**
-     * Where this backend runs. Purely descriptive: it exists so a UI can say
-     * "runs on your device" and so callers can order backends sensibly. The
-     * path's resolution never reads it.
-     */
-    readonly kind: InferenceBackendKind;
-    readonly status: InferenceBackendStatus;
-    /** Present while `status` is `loading` (and after a failure). */
-    readonly progress?: InferenceProgress;
-    /** Load whatever `status: 'idle'` is waiting on. No-op when already ready. */
-    load?(onProgress?: (progress: InferenceProgress) => void): Promise<void>;
-    /** Release loaded resources. No-op for backends with nothing to release. */
-    unload?(): Promise<void>;
-    chat(messages: InferenceMessage[], options?: InferenceChatOptions): Promise<InferenceResponse>;
-    stream(messages: InferenceMessage[], options?: InferenceChatOptions): AsyncIterable<string>;
-    /**
-     * Optional change notification. A backend that exposes this lets the path
-     * re-broadcast status/progress changes to UI subscribers; one that omits it
-     * is simply non-reactive for those fields.
-     */
-    subscribe?(listener: () => void): () => void;
-}
-
-/** Where a backend executes. Reporting only — the path never branches on it. */
-export declare type InferenceBackendKind = 'local' | 'route';
-
-/**
- * Whether a backend can answer right now.
- *
- * - `unavailable` — cannot run in this environment at all (no WebGPU, model
- *   not offered). Never auto-selected.
- * - `idle` — could run, nothing loaded yet. Not auto-selected; call `load()`.
- * - `loading` — a load is in progress. Not auto-selected.
- * - `ready` — can answer now. The only state auto-selection picks.
- * - `error` — the last load or call failed. Never auto-selected.
- */
-export declare type InferenceBackendStatus = 'unavailable' | 'idle' | 'loading' | 'ready' | 'error';
-
-/**
- * Per-call options (mirrors the `ChatOptions` fields a browser backend can
- * honor).
- *
- * `signal` is the cancellation seam a backend SHOULD respect — one that cannot
- * (the browser LLM adapter has no cancel path) ignores it rather than
- * pretending, so a caller must not read an abort as proof the work stopped.
- *
- * `tools` is refused, not ignored: every backend here is a text conversation,
- * and a backend that silently dropped a tool definition would let a caller
- * believe an answer was produced with tools it never received. Use
- * {@link assertTextOnlyTurn} to check a turn up front.
- */
-export declare interface InferenceChatOptions {
-    model?: string;
-    maxTokens?: number;
-    temperature?: number;
-    topP?: number;
-    stop?: string | string[];
-    tools?: InferenceTool[];
-    toolChoice?: 'auto' | 'none' | {
-        type: 'function';
-        function: {
-            name: string;
-        };
-    };
-    /** Token sink for a streamed reply. Backends that cannot stream ignore it. */
-    onProgress?: (chunk: string) => void;
-    /**
-     * Caller cancellation. Honored by the route backend and by bitgpu, which
-     * aborts a live generation; both compose it with `timeout`. The WebLLM
-     * adapter cannot cancel a generation already running on the GPU and does not
-     * read it.
-     */
-    signal?: AbortSignal;
-    /**
-     * Deadline in milliseconds for one call. Honored by the route backend, which
-     * aborts the request when it elapses, and by bitgpu, which aborts the
-     * generation. The WebLLM adapter has no cancellation seam and ignores it.
-     */
-    timeout?: number;
-}
-
-export declare type InferenceContentPart = InferenceTextPart | InferenceImagePart;
-
-/** Image content part (mirrors `ImageContentPart`). */
-export declare interface InferenceImagePart {
-    type: 'image_url';
-    image_url: {
-        url: string;
-        detail?: 'auto' | 'low' | 'high';
-    };
-}
-
-/** One conversation message (mirrors `AIMessage`). */
-export declare interface InferenceMessage {
-    role: InferenceRole;
-    content: string | InferenceContentPart[];
-    name?: string;
-    tool_calls?: InferenceToolCall[];
-}
-
-export declare interface InferencePath {
-    readonly backends: readonly InferenceBackend[];
-    /** The backend the NEXT call would use; `null` when none is usable. */
-    readonly activeId: string | null;
-    /** The configured preference, or `'auto'`. Settable; takes effect next call. */
-    preference: string;
-    /** The resolution the next call would produce, without making one. */
-    resolve(): InferenceResolution;
-    /** Pin to a backend id, or back to `'auto'`. */
-    select(preference: string): void;
-    chat(messages: InferenceMessage[], options?: InferenceChatOptions): Promise<InferenceResponse>;
-    stream(messages: InferenceMessage[], options?: InferenceChatOptions): AsyncIterable<string>;
-    /**
-     * Notified when a backend reports a status/progress change or the
-     * preference changes. Returns an unsubscribe function.
-     */
-    subscribe(listener: () => void): () => void;
-    /** Detach every backend subscription and drop all listeners. */
-    dispose(): void;
-}
-
-export declare class InferencePathError extends Error {
-    readonly code: InferencePathErrorCode;
-    constructor(message: string, code: InferencePathErrorCode);
-}
-
-export declare type InferencePathErrorCode = 'no_backends' | 'duplicate_backend' | 'unknown_backend' | 'no_usable_backend' | 'unsupported_message' | 'route_request_failed' | 'route_stream_error' | 'route_stream_truncated';
-
-export declare interface InferencePathOptions {
-    /**
-     * Candidate backends, in priority order. Order IS the auto-selection
-     * preference: list the local model first to prefer it when it is usable.
-     */
-    backends: readonly InferenceBackend[];
-    /** Backend id to prefer, or `'auto'`. Defaults to `'auto'`. */
-    preference?: string;
-    /**
-     * Whether a backend may answer. Defaults to `backend.status === 'ready'`,
-     * so an unloaded (`idle`) local backend is skipped rather than silently
-     * triggering a multi-gigabyte download mid-conversation.
-     */
-    canUse?: (backend: InferenceBackend) => boolean;
-}
-
-/**
- * Model load/download progress, mirroring the browser adapters'
- * `DownloadProgressInfo` so a `DownloadProgress` control can render it
- * directly.
- */
-export declare interface InferenceProgress {
-    state: 'idle' | 'downloading' | 'extracting' | 'complete' | 'error';
-    bytesLoaded: number;
-    bytesTotal: number;
-    percent: number;
-    currentFile?: string;
-    estimatedTimeRemaining?: number;
-    error?: string;
-}
-
-/** Why a call was routed to the backend it was routed to. */
-export declare interface InferenceResolution {
-    backend: InferenceBackend;
-    /**
-     * - `preferred` — an explicit preference named this backend and it is usable.
-     * - `fallback` — an explicit preference was unusable; `requested` names it.
-     * - `auto` — no explicit preference; first usable backend in declared order.
-     */
-    reason: 'preferred' | 'fallback' | 'auto';
-    /** The preference that could not be honored (`reason: 'fallback'` only). */
-    requested?: string;
-    /** Ids skipped because `canUse` returned false, in declared order. */
-    skipped: readonly string[];
-}
-
-/** A completion result (mirrors `AIResponse`). */
-export declare interface InferenceResponse {
-    content: string;
-    usage?: InferenceUsage;
-    model?: string;
-    finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
-    toolCalls?: InferenceToolCall[];
-}
-
-/** Message roles, mirroring `AIMessage['role']`. */
-export declare type InferenceRole = 'system' | 'user' | 'assistant' | 'function' | 'tool';
-
-/**
- * A turn in the subset every backend in this module can carry: a text
- * conversation with no tool traffic.
- */
-export declare interface InferenceTextMessage {
-    role: 'system' | 'user' | 'assistant';
-    content: string;
-}
-
-/**
- * Browser inference path — ONE call-site object over interchangeable inference
- * backends.
- *
- * A caller (a component, a hook, a workbench) holds a single `InferencePath`
- * and calls `chat()`/`stream()` on it. Which backend actually answers is
- * resolved **per call**, never cached on the path, so changing the preference
- * between two calls takes effect on the next one. That is what makes "switch
- * between the local model and the server route mid-session" a property
- * assignment rather than session state to unwind.
- *
- * ## Why a mirror rather than an import
- *
- * `InferenceMessage`/`InferenceResponse`/`InferenceChatOptions` are TEXTUAL
- * structural mirrors of `@happyvertical/ai`'s `AIMessage`/`AIResponse`/
- * `ChatOptions`, and `InferenceProgress` mirrors the browser adapters'
- * `DownloadProgressInfo`. smrt-web deliberately has no `@happyvertical/*`
- * dependency (`AGENTS.md`, "No inter-smrt dependencies"), so an `AIInterface`
- * — the ecosystem's canonical inference boundary — is described here by shape.
- *
- * The mirror covers the text-generation surface only. A backend whose
- * `chat`/`stream` accept these shapes satisfies the consumers in this
- * repository; a consumer that needs more of `AIInterface` adapts at its own
- * boundary rather than widening this contract.
- *
- * ## What this module does NOT own
- *
- * Backends arrive as arguments, the same way definitions and fetchers do
- * everywhere else in this package. A WebLLM backend lives beside the adapter
- * it wraps; `createRouteInferenceBackend` here covers the streaming-route case
- * because that one is pure `fetch` plus an SSE frame reader.
- *
- * @module
- */
-/** Text content part (mirrors `TextContentPart`). */
-export declare interface InferenceTextPart {
-    type: 'text';
-    text: string;
-}
-
-/** A tool definition offered to the model (mirrors `AITool`). */
-export declare interface InferenceTool {
-    type: 'function';
-    function: {
-        name: string;
-        description?: string;
-        parameters?: Record<string, unknown>;
-    };
-}
-
-export declare interface InferenceToolCall {
-    id: string;
-    type: 'function';
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-
-/** Token usage (mirrors `TokenUsage`). */
-export declare interface InferenceUsage {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-}
-
-/** Cap on the reply a route backend's `chat()` will assemble. */
-export declare const MAX_INFERENCE_REPLY_UNITS: number;
-
-/** Cap on total bytes read for one route call. */
-export declare const MAX_INFERENCE_STREAM_BYTES: number;
-
-/**
- * Cap on one undelivered SSE line, in UTF-16 code units. Without it a peer
- * that streams bytes with no `\n` grows the reader's buffer until the tab's
- * heap is exhausted.
- */
-export declare const MAX_INFERENCE_STREAM_LINE_UNITS = 1048576;
-
-/**
- * Compose the caller's cancellation signal with this call's deadline, so a
- * request with a `timeout` cannot outlive it even when no signal was passed.
- *
- * Exported so every backend that CAN cancel enforces `timeout` the same way: a
- * deadline the route backend would have enforced must not be quietly ignored
- * by a local one.
- */
-export declare function requestSignal(chatOptions?: InferenceChatOptions): AbortSignal | undefined;
-
-export declare interface RouteInferenceBackendOptions {
-    /** Full URL of a `text/event-stream` endpoint accepting `{ messages, session }`. */
-    endpoint: string;
-    /** Backend id. Defaults to `'route'`. */
-    id?: string;
-    /** Extra request headers, evaluated per call (auth tokens rotate). */
-    headers?: () => Record<string, string>;
-    /** Fetch credentials mode. Defaults to the platform default. */
-    credentials?: RequestCredentials;
-    /** Session metadata attached to the request body. */
-    session?: Record<string, unknown>;
-    /** Injectable fetch (tests, SSR-safe wrappers). */
-    fetchImpl?: typeof fetch;
-    /**
-     * Model id recorded on the returned `InferenceResponse`. Reporting only —
-     * the route resolves the model it actually uses, and a caller cannot widen
-     * it by naming one here (the generation caps live in the server-resolved
-     * stream context).
-     */
-    model?: string;
-}
-
-export { }
+/**
+ * Browser inference path — ONE call-site object over interchangeable inference
+ * backends.
+ *
+ * A caller (a component, a hook, a workbench) holds a single `InferencePath`
+ * and calls `chat()`/`stream()` on it. Which backend actually answers is
+ * resolved **per call**, never cached on the path, so changing the preference
+ * between two calls takes effect on the next one. That is what makes "switch
+ * between the local model and the server route mid-session" a property
+ * assignment rather than session state to unwind.
+ *
+ * ## Why a mirror rather than an import
+ *
+ * `InferenceMessage`/`InferenceResponse`/`InferenceChatOptions` are TEXTUAL
+ * structural mirrors of `@happyvertical/ai`'s `AIMessage`/`AIResponse`/
+ * `ChatOptions`, and `InferenceProgress` mirrors the browser adapters'
+ * `DownloadProgressInfo`. smrt-web deliberately has no `@happyvertical/*`
+ * dependency (`AGENTS.md`, "No inter-smrt dependencies"), so an `AIInterface`
+ * — the ecosystem's canonical inference boundary — is described here by shape.
+ *
+ * The mirror covers the text-generation surface only. A backend whose
+ * `chat`/`stream` accept these shapes satisfies the consumers in this
+ * repository; a consumer that needs more of `AIInterface` adapts at its own
+ * boundary rather than widening this contract.
+ *
+ * ## What this module does NOT own
+ *
+ * Backends arrive as arguments, the same way definitions and fetchers do
+ * everywhere else in this package. A WebLLM backend lives beside the adapter
+ * it wraps; `createRouteInferenceBackend` here covers the streaming-route case
+ * because that one is pure `fetch` plus an SSE frame reader.
+ *
+ * @module
+ */
+/** Text content part (mirrors `TextContentPart`). */
+export interface InferenceTextPart {
+    type: 'text';
+    text: string;
+}
+/** Image content part (mirrors `ImageContentPart`). */
+export interface InferenceImagePart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+export type InferenceContentPart = InferenceTextPart | InferenceImagePart;
+/** Message roles, mirroring `AIMessage['role']`. */
+export type InferenceRole = 'system' | 'user' | 'assistant' | 'function' | 'tool';
+export interface InferenceToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** One conversation message (mirrors `AIMessage`). */
+export interface InferenceMessage {
+    role: InferenceRole;
+    content: string | InferenceContentPart[];
+    name?: string;
+    tool_calls?: InferenceToolCall[];
+}
+/** A tool definition offered to the model (mirrors `AITool`). */
+export interface InferenceTool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+/** Token usage (mirrors `TokenUsage`). */
+export interface InferenceUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/** A completion result (mirrors `AIResponse`). */
+export interface InferenceResponse {
+    content: string;
+    usage?: InferenceUsage;
+    model?: string;
+    finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+    toolCalls?: InferenceToolCall[];
+}
+/**
+ * Per-call options (mirrors the `ChatOptions` fields a browser backend can
+ * honor).
+ *
+ * `signal` is the cancellation seam a backend SHOULD respect — one that cannot
+ * (the browser LLM adapter has no cancel path) ignores it rather than
+ * pretending, so a caller must not read an abort as proof the work stopped.
+ *
+ * `tools` is refused, not ignored: every backend here is a text conversation,
+ * and a backend that silently dropped a tool definition would let a caller
+ * believe an answer was produced with tools it never received. Use
+ * {@link assertTextOnlyTurn} to check a turn up front.
+ */
+export interface InferenceChatOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stop?: string | string[];
+    tools?: InferenceTool[];
+    toolChoice?: 'auto' | 'none' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    /** Token sink for a streamed reply. Backends that cannot stream ignore it. */
+    onProgress?: (chunk: string) => void;
+    /**
+     * Caller cancellation. Honored by the route backend and by bitgpu, which
+     * aborts a live generation; both compose it with `timeout`. The WebLLM
+     * adapter cannot cancel a generation already running on the GPU and does not
+     * read it.
+     */
+    signal?: AbortSignal;
+    /**
+     * Deadline in milliseconds for one call. Honored by the route backend, which
+     * aborts the request when it elapses, and by bitgpu, which aborts the
+     * generation. The WebLLM adapter has no cancellation seam and ignores it.
+     */
+    timeout?: number;
+}
+/**
+ * Model load/download progress, mirroring the browser adapters'
+ * `DownloadProgressInfo` so a `DownloadProgress` control can render it
+ * directly.
+ */
+export interface InferenceProgress {
+    state: 'idle' | 'downloading' | 'extracting' | 'complete' | 'error';
+    bytesLoaded: number;
+    bytesTotal: number;
+    percent: number;
+    currentFile?: string;
+    estimatedTimeRemaining?: number;
+    error?: string;
+}
+/**
+ * Cap on one undelivered SSE line, in UTF-16 code units. Without it a peer
+ * that streams bytes with no `\n` grows the reader's buffer until the tab's
+ * heap is exhausted.
+ */
+export declare const MAX_INFERENCE_STREAM_LINE_UNITS = 1048576;
+/** Cap on total bytes read for one route call. */
+export declare const MAX_INFERENCE_STREAM_BYTES: number;
+/** Cap on the reply a route backend's `chat()` will assemble. */
+export declare const MAX_INFERENCE_REPLY_UNITS: number;
+/**
+ * A turn in the subset every backend in this module can carry: a text
+ * conversation with no tool traffic.
+ */
+export interface InferenceTextMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Reject a turn this module's backends cannot faithfully carry, narrowing
+ * `messages` to {@link InferenceTextMessage} on success.
+ *
+ * Every backend here is a TEXT conversation: roles `user`/`assistant`/
+ * `system`, string content, no tools. Each of those limits is a real
+ * difference between the backends' transports, so refusing up front is the
+ * only way a caller can tell "this backend can't carry my turn" from "this
+ * backend answered". The route wire contract (`chat-stream.ts`
+ * `normalizeMessages`) and the local adapter both silently DROP exactly these
+ * shapes, which is why this check is shared rather than reimplemented per
+ * backend — two copies would drift, and the whole point is that both backends
+ * agree.
+ *
+ * `backendLabel` names the backend in the message so a caller knows which one
+ * refused.
+ */
+export declare function assertTextOnlyTurn(backendLabel: string, messages: InferenceMessage[], options?: InferenceChatOptions): asserts messages is InferenceTextMessage[];
+/**
+ * Whether a backend can answer right now.
+ *
+ * - `unavailable` — cannot run in this environment at all (no WebGPU, model
+ *   not offered). Never auto-selected.
+ * - `idle` — could run, nothing loaded yet. Not auto-selected; call `load()`.
+ * - `loading` — a load is in progress. Not auto-selected.
+ * - `ready` — can answer now. The only state auto-selection picks.
+ * - `error` — the last load or call failed. Never auto-selected.
+ */
+export type InferenceBackendStatus = 'unavailable' | 'idle' | 'loading' | 'ready' | 'error';
+/** Where a backend executes. Reporting only — the path never branches on it. */
+export type InferenceBackendKind = 'local' | 'route';
+export interface InferenceBackend {
+    /** Stable id, unique across a path. A preference names this. */
+    readonly id: string;
+    /**
+     * Where this backend runs. Purely descriptive: it exists so a UI can say
+     * "runs on your device" and so callers can order backends sensibly. The
+     * path's resolution never reads it.
+     */
+    readonly kind: InferenceBackendKind;
+    readonly status: InferenceBackendStatus;
+    /** Present while `status` is `loading` (and after a failure). */
+    readonly progress?: InferenceProgress;
+    /** Load whatever `status: 'idle'` is waiting on. No-op when already ready. */
+    load?(onProgress?: (progress: InferenceProgress) => void): Promise<void>;
+    /** Release loaded resources. No-op for backends with nothing to release. */
+    unload?(): Promise<void>;
+    chat(messages: InferenceMessage[], options?: InferenceChatOptions): Promise<InferenceResponse>;
+    stream(messages: InferenceMessage[], options?: InferenceChatOptions): AsyncIterable<string>;
+    /**
+     * Optional change notification. A backend that exposes this lets the path
+     * re-broadcast status/progress changes to UI subscribers; one that omits it
+     * is simply non-reactive for those fields.
+     */
+    subscribe?(listener: () => void): () => void;
+}
+/** Why a call was routed to the backend it was routed to. */
+export interface InferenceResolution {
+    backend: InferenceBackend;
+    /**
+     * - `preferred` — an explicit preference named this backend and it is usable.
+     * - `fallback` — an explicit preference was unusable; `requested` names it.
+     * - `auto` — no explicit preference; first usable backend in declared order.
+     */
+    reason: 'preferred' | 'fallback' | 'auto';
+    /** The preference that could not be honored (`reason: 'fallback'` only). */
+    requested?: string;
+    /** Ids skipped because `canUse` returned false, in declared order. */
+    skipped: readonly string[];
+}
+export interface InferencePathOptions {
+    /**
+     * Candidate backends, in priority order. Order IS the auto-selection
+     * preference: list the local model first to prefer it when it is usable.
+     */
+    backends: readonly InferenceBackend[];
+    /** Backend id to prefer, or `'auto'`. Defaults to `'auto'`. */
+    preference?: string;
+    /**
+     * Whether a backend may answer. Defaults to `backend.status === 'ready'`,
+     * so an unloaded (`idle`) local backend is skipped rather than silently
+     * triggering a multi-gigabyte download mid-conversation.
+     */
+    canUse?: (backend: InferenceBackend) => boolean;
+}
+export interface InferencePath {
+    readonly backends: readonly InferenceBackend[];
+    /** The backend the NEXT call would use; `null` when none is usable. */
+    readonly activeId: string | null;
+    /** The configured preference, or `'auto'`. Settable; takes effect next call. */
+    preference: string;
+    /** The resolution the next call would produce, without making one. */
+    resolve(): InferenceResolution;
+    /** Pin to a backend id, or back to `'auto'`. */
+    select(preference: string): void;
+    chat(messages: InferenceMessage[], options?: InferenceChatOptions): Promise<InferenceResponse>;
+    stream(messages: InferenceMessage[], options?: InferenceChatOptions): AsyncIterable<string>;
+    /**
+     * Notified when a backend reports a status/progress change or the
+     * preference changes. Returns an unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+    /** Detach every backend subscription and drop all listeners. */
+    dispose(): void;
+}
+export type InferencePathErrorCode = 'no_backends' | 'duplicate_backend' | 'unknown_backend' | 'no_usable_backend' | 'unsupported_message' | 'route_request_failed' | 'route_stream_error' | 'route_stream_truncated';
+export declare class InferencePathError extends Error {
+    readonly code: InferencePathErrorCode;
+    constructor(message: string, code: InferencePathErrorCode);
+}
+/**
+ * Create the browser's single inference path over `options.backends`.
+ *
+ * Resolution happens inside every `chat`/`stream` call, so a `preference` or
+ * `select()` change made between calls is honored by the next one. A call
+ * whose resolution finds nothing usable throws `InferencePathError` with
+ * `code: 'no_usable_backend'` rather than falling back to a fake answer.
+ */
+export declare function createInferencePath(options: InferencePathOptions): InferencePath;
+export interface RouteInferenceBackendOptions {
+    /** Full URL of a `text/event-stream` endpoint accepting `{ messages, session }`. */
+    endpoint: string;
+    /** Backend id. Defaults to `'route'`. */
+    id?: string;
+    /** Extra request headers, evaluated per call (auth tokens rotate). */
+    headers?: () => Record<string, string>;
+    /** Fetch credentials mode. Defaults to the platform default. */
+    credentials?: RequestCredentials;
+    /** Session metadata attached to the request body. */
+    session?: Record<string, unknown>;
+    /** Injectable fetch (tests, SSR-safe wrappers). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Model id recorded on the returned `InferenceResponse`. Reporting only —
+     * the route resolves the model it actually uses, and a caller cannot widen
+     * it by naming one here (the generation caps live in the server-resolved
+     * stream context).
+     */
+    model?: string;
+}
+/**
+ * Compose the caller's cancellation signal with this call's deadline, so a
+ * request with a `timeout` cannot outlive it even when no signal was passed.
+ *
+ * Exported so every backend that CAN cancel enforces `timeout` the same way: a
+ * deadline the route backend would have enforced must not be quietly ignored
+ * by a local one.
+ */
+export declare function requestSignal(chatOptions?: InferenceChatOptions): AbortSignal | undefined;
+/**
+ * A backend over a `text/event-stream` inference route.
+ *
+ * The wire contract is `@happyvertical/smrt-chat`'s `ChatStreamEvent` framing
+ * (token deltas, then a terminal `done` or `error`), consumed here without
+ * depending on that package: smrt-web carries no inter-SMRT dependencies, so
+ * the frame vocabulary is mirrored the same way the rest of this module is.
+ *
+ * `status` is always `'ready'` — there is nothing to load — so an `auto` path
+ * picks this backend until a local one reports ready. It defines neither
+ * `load` nor `unload`, so a control must not offer those actions for it.
+ *
+ * A turn this wire cannot carry (tool turns, multimodal content, tool
+ * definitions) is REFUSED with `unsupported_message` rather than forwarded:
+ * the route silently drops those shapes, so forwarding would answer a
+ * different question than the caller asked.
+ */
+export declare function createRouteInferenceBackend(options: RouteInferenceBackendOptions): InferenceBackend;
+//# sourceMappingURL=ai.d.ts.map