@dudousxd/nestjs-agent-react 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -1,18 +1,180 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { StoredMessage, ThreadSummary, SkillCatalogEntry, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView } from '@dudousxd/nestjs-agent-core';
+import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, StoredMessage } from '@dudousxd/nestjs-agent-core';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React__default from 'react';
-import { a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile, T as TranscriptUiBlock } from './model-CMNhyau6.js';
-export { f as ApprovalBlockOptions, B as BuildBlocksOptions, g as CoercibleQuestion, D as DescribeToolCallOptions, E as ElicitationBlockOptions, G as GroupToolActivityOptions, R as RawAnswer, h as ResolvedReading, i as ResolvedResultView, j as RetrievedPassage, S as SettleAction, k as ToolActivityGroup, l as ToolCallDescription, m as ToolCallState, n as ToolCallStatus, o as TranscriptApproval, p as TranscriptApprovalStatus, q as TranscriptElicitationBlock, r as TranscriptElicitationOutcome, s as TranscriptFilesBlock, t as TranscriptQuestion, u as TranscriptQuestionOption, v as TranscriptReasoningBlock, w as TranscriptSettleState, x as TranscriptSource, y as TranscriptSourcesBlock, z as TranscriptTextBlock, F as TranscriptToolBlock, H as TranscriptToolCall, I as buildTranscriptBlocks, J as coerceAnswer, K as correctedCallIds, L as describeTimestamp, N as describeToolCall, O as describeUsage, P as extractMessageText, Q as fillTemplate, V as formatRelativeTime, W as groupToolActivity, X as inferResultView, Y as isActionCall, Z as phraseFor, _ as readPath, $ as resolveResultView, a0 as toolCallState, a1 as toolCatalogFrom } from './model-CMNhyau6.js';
+import { a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile, T as TranscriptUiBlock } from './model-gHqjNjLJ.js';
+export { f as ApprovalBlockOptions, B as BuildBlocksOptions, g as CoercibleQuestion, D as DescribeToolCallOptions, E as ElicitationBlockOptions, G as GroupToolActivityOptions, R as RawAnswer, h as ResolvedReading, i as ResolvedResultView, j as RetrievedPassage, S as SettleAction, k as ToolActivityGroup, l as ToolCallDescription, m as ToolCallState, n as ToolCallStatus, o as TranscriptApproval, p as TranscriptApprovalStatus, q as TranscriptElicitationBlock, r as TranscriptElicitationOutcome, s as TranscriptFilesBlock, t as TranscriptQuestion, u as TranscriptQuestionOption, v as TranscriptReasoningBlock, w as TranscriptSettleState, x as TranscriptSource, y as TranscriptSourcesBlock, z as TranscriptTextBlock, F as TranscriptToolBlock, H as TranscriptToolCall, I as buildTranscriptBlocks, J as coerceAnswer, K as correctedCallIds, L as describeTimestamp, N as describeToolCall, O as describeUsage, P as extractMessageText, Q as fillTemplate, V as formatRelativeTime, W as groupToolActivity, X as inferResultView, Y as isActionCall, Z as phraseFor, _ as readPath, $ as resolveResultView, a0 as toolCallState, a1 as toolCatalogFrom } from './model-gHqjNjLJ.js';
+
+/**
+ * Partial update accepted by `PATCH <base>/threads/:threadId`. `defaultAgent: null` clears a
+ * previously-set default back to the module's own default; omitting it leaves the thread's
+ * current default untouched.
+ */
+interface ThreadPatch {
+    title?: string;
+    defaultAgent?: string | null;
+    /** Pin a catalog model on the thread; `null` unpins it. */
+    model?: string | null;
+}
+/** Starting a turn: the body `POST <base>/chat` takes (see docs/stream-protocol.md). */
+interface ChatStreamRequest {
+    /** `{ message, threadId?, agent?, model?, attachments?, pageContext?, regenerate?, … }`. */
+    body: Record<string, unknown>;
+    /** Per-request headers the AI SDK was handed for this send. */
+    headers?: Record<string, string>;
+    /** Aborted when the user stops the turn. */
+    signal?: AbortSignal;
+}
+/** Attaching to a run that is already streaming: `GET <base>/chat/:runId/stream?after=<seq>`. */
+interface ResumeStreamRequest {
+    runId: string;
+    /**
+     * The sequence number (SSE `id:`) of the last frame the client already has. Omitted → replay
+     * from the first frame. A backend that cannot skip may ignore it: the transport also drops frames
+     * at or below it.
+     */
+    after?: number;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * An open chat stream: the raw `text/event-stream` bytes in the stream-protocol framing, plus the
+ * identity a backend may learn before the first frame (the `X-Agent-Run-Id` / `X-Agent-Thread-Id`
+ * headers). The body's own `event: meta` frame supplies them otherwise.
+ */
+interface ChatStreamResponse {
+    body: ReadableStream<Uint8Array>;
+    runId?: string;
+    threadId?: string;
+}
+/** What `POST <base>/messages/:id/feedback` takes. `value: null` clears the rating. */
+interface MessageFeedbackInput {
+    value: MessageFeedbackValue | null;
+    comment?: string;
+}
+interface UploadAttachmentOptions {
+    signal?: AbortSignal;
+    /** Called with 0..1 as the upload progresses, when the backend can observe it. */
+    onProgress?: (fraction: number) => void;
+}
+/**
+ * Everything the React layer asks of a server — the seam between `useAgentChat` (and the other
+ * hooks) and whatever serves the agent. {@link AgentClient} is the default implementation, over the
+ * library's own REST routes with `fetch`. An app with its own client — a generated one, a different
+ * auth scheme (cookie session + CSRF header), a backend that is not this library at all but speaks
+ * docs/stream-protocol.md — implements this instead and passes it as `useAgentChat({ backend })`.
+ *
+ * The streaming, thread and cancel members are required: without them there is no chat. The rest
+ * are optional; a hook that needs one the backend does not have throws
+ * {@link AgentBackendUnsupportedError} when it is called, so a backend only implements what its
+ * server supports.
+ */
+interface AgentBackend {
+    /** Start a turn and return its SSE stream. Throw on a non-2xx answer. */
+    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
+    /** Attach to a streaming run. Resolve `null` when nothing is streaming under that id (HTTP 404). */
+    resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
+    /** Hard-stop a run server-side. */
+    cancelStream(runId: string): Promise<unknown>;
+    listThreads(): Promise<ThreadSummary[]>;
+    getThread(id: string): Promise<ThreadDetail>;
+    updateThread(id: string, patch: ThreadPatch): Promise<unknown>;
+    deleteThread(id: string): Promise<unknown>;
+    forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
+    promoteThread?(id: string): Promise<unknown>;
+    truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
+    approveToolCall?(input: {
+        toolCallId: string;
+        remember?: boolean;
+        via?: string;
+    }): Promise<unknown>;
+    rejectToolCall?(input: {
+        toolCallId: string;
+        reason?: string;
+        via?: string;
+    }): Promise<unknown>;
+    answerToolCall?(input: {
+        toolCallId: string;
+        answers?: Record<string, string[]>;
+    }): Promise<unknown>;
+    skipToolCall?(input: {
+        toolCallId: string;
+    }): Promise<unknown>;
+    uploadAttachment?(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
+    listTools?(agent?: string): Promise<ToolCatalogEntry[]>;
+    listSkills?(threadId?: string): Promise<SkillCatalogEntry[]>;
+    getQuotaToday?(): Promise<QuotaView>;
+    /** `GET <base>/models?agent=` — what a model picker offers. */
+    listModels?(agent?: string): Promise<ModelCatalogView>;
+    /** `GET <base>/agents` — what an agent picker offers. */
+    listAgents?(): Promise<AgentCatalogEntry[]>;
+    setMessageFeedback?(messageId: string, input: MessageFeedbackInput): Promise<{
+        feedback: MessageFeedback | null;
+    }>;
+}
+/** An optional {@link AgentBackend} member the bound backend does not implement was called. */
+declare class AgentBackendUnsupportedError extends Error {
+    readonly method: string;
+    constructor(method: string);
+}
+type OptionalMethod = {
+    [K in keyof AgentBackend]-?: undefined extends AgentBackend[K] ? K : never;
+}[keyof AgentBackend];
+/**
+ * The optional backend method `name`, bound — or a throw naming it. For hook code that has to call
+ * something a backend may not offer.
+ */
+declare function requireBackendMethod<K extends OptionalMethod>(backend: AgentBackend, name: K): NonNullable<AgentBackend[K]>;
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
     runId: string;
     threadId: string;
 }
+/**
+ * How the transport retries a stream that dropped mid-run. It reconnects only to a server that
+ * numbers its frames (SSE `id:`) — without a cursor a reconnect would replay the run into the
+ * message it is already writing.
+ */
+interface ReconnectOptions {
+    /** Attempts before giving up with an error chunk. Default 6. */
+    maxAttempts?: number;
+    /** Delay before the first attempt, doubled each attempt. Default 500 ms. */
+    baseDelayMs?: number;
+    /** Cap on the delay between attempts. Default 8000 ms. */
+    maxDelayMs?: number;
+}
+/** Where a live stream stands. `reconnecting` → it dropped and the transport is retrying. */
+type StreamConnectionState = {
+    status: 'live';
+} | {
+    status: 'reconnecting';
+    runId: string;
+    attempt: number;
+    after: number;
+}
+/** The run ended while the client was away (the resume answered 404): reload the thread. */
+ | {
+    status: 'gone';
+    runId: string;
+}
+/** Every attempt failed; the stream ended with an error chunk. */
+ | {
+    status: 'failed';
+    runId: string;
+};
 interface AgentChatTransportOptions {
+    /**
+     * What the transport talks to. Default: an {@link AgentClient} built from `baseUrl`, `headers`,
+     * `getHeaders`, `credentials` and `fetch` below — which are ignored when a backend is given.
+     */
+    backend?: AgentBackend;
+    /** Retry a dropped stream from its last frame. Default on; `false` turns it off. */
+    reconnect?: ReconnectOptions | false;
+    /** Fires as a stream drops, reconnects, or gives up. */
+    onConnectionChange?: (state: StreamConnectionState) => void;
     /**
      * Origin + base path the agent endpoints hang off, e.g.
      * `https://api.example.com`. Endpoints are appended as
@@ -96,6 +258,7 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
      * several entries under each id — which React renders as duplicate keys.
      */
     private attemptLive;
+    private readonly backend;
     constructor(options?: AgentChatTransportOptions);
     /** Run id of the most recent stream — HITL approve/reject target this. */
     get runId(): string | undefined;
@@ -110,10 +273,8 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     get isAttemptLive(): boolean;
     sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
     reconnectToStream(options: Parameters<ChatTransport<UIMessage>['reconnectToStream']>[0]): Promise<ReadableStream<UIMessageChunk> | null>;
-    private fetchImpl;
-    private baseUrl;
-    private resolveHeaders;
     private captureHeaderMeta;
+    private reconnectPolicy;
     private recordMeta;
     /**
      * Parse the backend's SSE byte stream and re-emit it as a valid v7 UI-message chunk stream.
@@ -131,6 +292,139 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private toChunkStream;
 }
 
+interface UseAgentsOptions {
+    /** `useAgentChat(...).backend`, or your own. Must implement `listAgents`. */
+    backend: AgentBackend;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+}
+interface AgentsState {
+    /** `[]` until loaded. */
+    agents: AgentCatalogEntry[];
+    /** The agent a turn runs as when none is named. */
+    defaultAgent: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The registered agents (`GET <base>/agents`) — the data behind an agent picker. Send the pick as
+ * `useAgentChat({ agent })`, or pin it on a thread with `PATCH <base>/threads/:id { defaultAgent }`.
+ */
+declare function useAgents(options: UseAgentsOptions): AgentsState;
+
+interface UseModelsOptions {
+    /** `useAgentChat(...).backend`, or your own. Must implement `listModels`. */
+    backend: AgentBackend;
+    /** The agent to list models for; omitted → the default agent. */
+    agent?: string;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+}
+/** A catalog entry with the provider it sits under, for a flat list or a search. */
+interface ModelOption extends ModelCatalogEntry {
+    providerId: string;
+    providerLabel: string;
+}
+interface ModelsState {
+    /** Grouped as the server sent them. `[]` until loaded. */
+    providers: ModelCatalogView['providers'];
+    /** Every model, flattened in provider order. */
+    models: ModelOption[];
+    /** The model a turn runs on when none is picked, or `null` when the provider decides. */
+    defaultModel: string | null;
+    /** The entry for `id`, or `undefined`. */
+    find: (id: string | null | undefined) => ModelOption | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The models this caller may pick (`GET <base>/models?agent=`), with badges and availability — the
+ * data behind a model picker. Headless: render the options however you like, then send the pick
+ * as `useAgentChat({ model })`, `sendMessage(msg, { body: { model } })`, or pin it on the thread
+ * with `chat.setThreadModel(id)`.
+ */
+declare function useModels(options: UseModelsOptions): ModelsState;
+
+interface UseMessageFeedbackOptions {
+    /** `useAgentChat(...).backend`, or your own. Must implement `setMessageFeedback`. */
+    backend: AgentBackend;
+    /**
+     * The thread the messages belong to — `useAgentChat(...).getThreadId`, or an id. Needed to rate a
+     * message streamed in this session: its id is the client's own, so the persisted row it became is
+     * looked up by the run that wrote it.
+     */
+    threadId?: string | (() => string | undefined);
+}
+interface MessageFeedbackState {
+    /** The rating to show: the one set in this session, else the persisted one, else `null`. */
+    feedbackOf: (message: UIMessage) => MessageFeedback | null;
+    /** A rating for this message is on its way to the server. */
+    isPending: (message: UIMessage) => boolean;
+    /** Set `'up'`/`'down'` (optionally with a comment), or clear with `null`. Optimistic. */
+    rate: (message: UIMessage, value: MessageFeedbackValue | null, comment?: string) => Promise<void>;
+    /** Thumbs-button semantics: the same value again clears it, another value replaces it. */
+    toggle: (message: UIMessage, value: MessageFeedbackValue) => Promise<void>;
+    /** The last failure; cleared by the next successful rating. */
+    error: Error | null;
+}
+/**
+ * Thumbs-up/down (+ comment) on assistant messages, over `POST <base>/messages/:id/feedback`.
+ * Headless: it holds the state and the calls, the host draws the buttons. A rating shows at once
+ * and rolls back if the server refuses it.
+ */
+declare function useMessageFeedback(options: UseMessageFeedbackOptions): MessageFeedbackState;
+
+/**
+ * What changed about a backend's thread list. `changed` → refetch (a thread was created, or a run
+ * settled and the server wrote its title); `title` → the stream announced a title, patch in place.
+ */
+type ThreadsEvent = {
+    type: 'changed';
+} | {
+    type: 'title';
+    threadId: string;
+    title: string;
+} | {
+    type: 'removed';
+    threadId: string;
+};
+type Listener = (event: ThreadsEvent) => void;
+/** Tell every {@link useThreads} on `backend` that its list moved. */
+declare function notifyThreads(backend: AgentBackend, event: ThreadsEvent): void;
+/** Subscribe to {@link notifyThreads} for `backend`; returns the unsubscribe. */
+declare function onThreadsEvent(backend: AgentBackend, listener: Listener): () => void;
+
+interface UseThreadsOptions {
+    /**
+     * The backend to list — `useAgentChat(...).backend`, or your own. Must be STABLE across renders:
+     * the list refreshes itself when a chat on the SAME backend creates a thread, settles a run or
+     * streams a title.
+     */
+    backend: AgentBackend;
+    /** `false` holds the first request (e.g. until the user is signed in). Default `true`. */
+    enabled?: boolean;
+}
+interface ThreadsState {
+    /** Newest first, as the server orders them. `[]` until loaded. */
+    threads: ThreadSummary[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Ask the server again. */
+    refresh: () => Promise<void>;
+    /** Rename on the server; the list shows the new title at once and rolls back on failure. */
+    rename: (id: string, title: string) => Promise<void>;
+    /** Delete on the server; the thread leaves the list at once and comes back on failure. */
+    remove: (id: string) => Promise<void>;
+}
+/**
+ * The actor's conversations, kept current without the host wiring refetches: a chat on the same
+ * backend reports thread creation and settled runs (refetch) and streamed titles (patched in
+ * place). Headless — it renders nothing.
+ */
+declare function useThreads(options: UseThreadsOptions): ThreadsState;
+
 /**
  * A sub-agent the conversation started and did not wait for. The chat is free while it works, so a
  * client has to be able to say what is still running and to show the answer when it lands — neither
@@ -180,34 +474,46 @@ interface CancelResult {
 interface OkResult {
     ok: boolean;
 }
-/**
- * Partial update accepted by `PATCH /agent/threads/:threadId`. `defaultAgent: null` clears a
- * previously-set default back to the module's own default; omitting it leaves the thread's
- * current default untouched.
- */
-interface ThreadPatch {
-    title?: string;
-    defaultAgent?: string | null;
-}
 interface AgentClientOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
     /** Static headers merged into every request. */
     headers?: Record<string, string>;
-    /** Resolved per request — for short-lived bearer tokens. */
+    /**
+     * Resolved per request — for short-lived bearer tokens, or a CSRF header read from a cookie
+     * (`{ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }`), which has to be read at request time because
+     * the server may rotate it.
+     */
     getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    /** Forwarded to fetch so cookie auth works. */
+    /**
+     * Forwarded to fetch so cookie auth works. Same-origin requests send cookies by default; set
+     * `'include'` when the API lives on another origin (and have it answer with credentialed CORS).
+     */
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
 }
 /**
- * Framework-agnostic REST client for the nestjs-agent endpoints. Used by
- * `useAgentChat`, but standalone-usable (vanilla fetch, no React).
+ * Framework-agnostic REST client for the nestjs-agent endpoints — the default {@link AgentBackend}.
+ * Used by `useAgentChat`, but standalone-usable (vanilla fetch, no React).
  */
-declare class AgentClient {
+declare class AgentClient implements AgentBackend {
     private readonly options;
     constructor(options?: AgentClientOptions);
+    /** `POST /agent/chat` → the turn's SSE stream. Throws {@link AgentHttpError} on a non-2xx. */
+    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
+    /**
+     * `GET /agent/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
+     * streaming under that id (404).
+     */
+    resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
+    /**
+     * Rate a message (`'up'`/`'down'`, optional comment) or clear its rating (`value: null`). Answers
+     * the stored rating.
+     */
+    setMessageFeedback(messageId: string, input: MessageFeedbackInput): Promise<{
+        feedback: MessageFeedback | null;
+    }>;
     listThreads(): Promise<ThreadSummary[]>;
     /**
      * The skills this caller can invoke right now, scope-resolved — the same list, built by the same
@@ -233,9 +539,13 @@ declare class AgentClient {
      * mirrors the backend's `POST /agent/attachments`. The returned {@link MessageAttachment} is
      * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
      */
-    uploadAttachment(file: File): Promise<MessageAttachment>;
+    uploadAttachment(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
+    /** `GET /agent/models?agent=` — the models this caller may pick, grouped by provider. */
+    listModels(agent?: string): Promise<ModelCatalogView>;
+    /** `GET /agent/agents` — the registered agents, the default one flagged. */
+    listAgents(): Promise<AgentCatalogEntry[]>;
     getQuotaToday(): Promise<QuotaToday>;
     cancelStream(runId: string): Promise<CancelResult>;
     /**
@@ -270,6 +580,10 @@ declare class AgentClient {
     skipToolCall(input: {
         toolCallId: string;
     }): Promise<void>;
+    private fetchImpl;
+    private baseUrl;
+    private resolveHeaders;
+    private credentials;
     private request;
     private handleResponse;
 }
@@ -785,7 +1099,8 @@ interface SkillSuggestionData {
     shadows?: string[];
 }
 interface SkillsSourceOptions {
-    client: AgentClient;
+    /** Any backend with `listSkills` — `useAgentChat(...).backend`. */
+    client: Pick<AgentBackend, 'listSkills'>;
     /**
      * Read at query time, not captured once: a threadless chat learns its id only when the backend
      * creates one on the first send, and a skill may be scoped to a conversation.
@@ -879,12 +1194,15 @@ interface ComposerAutocomplete {
  */
 declare function useComposerAutocomplete(options: UseComposerAutocompleteOptions): ComposerAutocomplete;
 
+/** What the catalog needs of a backend. */
+type ToolsBackend = Pick<AgentBackend, 'listTools'>;
+
 interface UseToolCatalogOptions {
     /**
      * The client to ask — `useAgentChat(...).client`, or one of your own. Must be STABLE across
      * renders (the shared copy is keyed by it): a client constructed inline refetches every render.
      */
-    client: AgentClient;
+    client: ToolsBackend;
     /** The agent whose tools to list. Omitted → the server's default agent. */
     agent?: string;
     /** `false` holds the request (e.g. until the user is signed in). Default `true`. */
@@ -978,6 +1296,16 @@ interface AggregatedTurnUsage {
 interface StoredTurnMetadata {
     usage: AggregatedTurnUsage;
 }
+/**
+ * Everything a message's `metadata` may carry from this library: `usage` on a merged replayed turn,
+ * `feedback` on a replayed message that was rated (a merged turn is rated through its last row,
+ * whose id it carries), `runId` on a live-streamed one, `costUsd` from the stream's step ends.
+ */
+interface AgentMessageMetadata extends Partial<StoredTurnMetadata> {
+    feedback?: MessageFeedback;
+    runId?: string;
+    costUsd?: number | null;
+}
 /**
  * Convert a thread's full `StoredMessage[]` history into `UIMessage[]`, merging consecutive
  * assistant rows (no user message between them) into ONE `UIMessage` per turn.
@@ -1018,7 +1346,19 @@ interface StoredTurnMetadata {
  */
 declare function storedThreadToUiMessages(messages: StoredMessage[]): UIMessage[];
 
-interface UseAgentChatOptions {
+interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
+    /**
+     * What the chat talks to — see {@link AgentBackend}. Omitted → an {@link AgentClient} over this
+     * library's REST routes, built from `baseUrl`, `headers`, `getHeaders`, `credentials` and `fetch`
+     * (which are ignored when a backend is given). Must be stable across renders.
+     */
+    backend?: B;
+    /**
+     * Retry a stream that dropped mid-run from its last frame (`GET <base>/chat/:runId/stream?after=`),
+     * with exponential backoff. `status` reads `'reconnecting'` meanwhile. Default on; `false` turns
+     * it off.
+     */
+    reconnect?: ReconnectOptions | false;
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
     /** Static headers merged into every request. */
@@ -1029,10 +1369,16 @@ interface UseAgentChatOptions {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
-    /** Reuse an existing client instead of constructing one. */
-    client?: AgentClient;
+    /** Reuse an existing client instead of constructing one. Prefer {@link backend}. */
+    client?: B;
     /** Named agent to run each turn. */
     agent?: string;
+    /**
+     * Catalog model to run each turn on (see `useModels`), sent as the body's `model`. Read at every
+     * send, so a picker can change it between turns. Omitted → the thread's pinned model, else the
+     * server default. A single send can still override it with `sendMessage(msg, { body: { model } })`.
+     */
+    model?: string;
     /** Thread this chat is bound to. Omitted → backend creates one on send. */
     threadId?: string;
     /** Persisted history to seed `useChat` with (consumed on mount only). */
@@ -1138,10 +1484,13 @@ interface AddToolResultArgs {
  * fork, quota, cancel, and HITL approve/reject — all driven through
  * `AgentClient`. Mirrors flip's `useAdminChat`, generalized.
  */
-declare function useAgentChat(options: UseAgentChatOptions): {
+declare function useAgentChat<B extends AgentBackend = AgentClient>(options: UseAgentChatOptions<B>): {
+    status: ChatStatus;
+    /** Where the live stream stands — see {@link StreamConnectionState}. */
+    connection: StreamConnectionState;
     sendMessage: (message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
-        role?: "system" | "user" | "assistant";
+        role?: "user" | "assistant" | "system";
     } & {
         text?: never;
         files?: never;
@@ -1164,7 +1513,16 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     runId: string | undefined;
     /** The `resume`-fetched thread's active run id, or `null` once resolved with none. */
     activeRunId: string | null;
-    client: AgentClient;
+    /**
+     * The thread this chat is on right now: the `threadId` option, else the one the backend created
+     * on the first send. A getter, because the created id is learned mid-stream.
+     */
+    getThreadId: () => string | undefined;
+    setThreadModel: (model: string | null) => Promise<void>;
+    /** The backend this chat talks to — pass it to `useThreads`, `useMessageFeedback`, … */
+    backend: B;
+    /** Same object as {@link backend}; kept for callers that read it under its old name. */
+    client: B;
     threads: ThreadSummary[];
     loadThreads: () => Promise<ThreadSummary[]>;
     loadThread: (id: string) => Promise<ThreadDetail>;
@@ -1199,7 +1557,6 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     setMessages: (messages: UIMessage<unknown, UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, UIDataTypes, ai.UITools>[]) => UIMessage<unknown, UIDataTypes, ai.UITools>[])) => void;
     error: Error | undefined;
     stop: () => Promise<void>;
-    status: ai.ChatStatus;
     messages: UIMessage<unknown, UIDataTypes, ai.UITools>[];
     resumeStream: (options?: ai.ChatRequestOptions) => Promise<void>;
     addToolOutput: ai.ChatAddToolOutputFunction<UIMessage<unknown, UIDataTypes, ai.UITools>>;
@@ -1207,4 +1564,4 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     clearError: () => void;
 };
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type QuotaToday, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type ThreadPatch, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, UsageSummary, type UseAgentChatOptions, type UseApprovalCountdownOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseSpeechRecognitionOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useToolCatalog, useTranscriptItem };
+export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type MessageFeedbackInput, type MessageFeedbackState, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };