@dudousxd/nestjs-agent-react 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
-import { A as AgentBackend, U as UploadAttachmentOptions, a as AgentClient, b as AttachmentUploadStrategy, Q as QuotaToday } from './client-0Wd-WPsu.js';
-export { c as AgentBackendUnsupportedError, d as AgentClientOptions, e as AgentConnection, f as AgentHttpError, C as CancelResult, g as ChatStreamRequest, h as ChatStreamResponse, M as MessageFeedbackInput, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-0Wd-WPsu.js';
-import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { MessageAttachment, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, QuotaReport, QuotaWindow, QuotaBlock, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, ToolCatalogEntry, ThreadDetail } from '@dudousxd/nestjs-agent-core';
+import { A as AgentBackend, U as UploadAttachmentOptions, a as AttachmentUploadStrategy } from './client-CYlhK7XD.js';
+export { b as AgentBackendUnsupportedError, c as AgentClient, d as AgentClientOptions, e as AgentConnection, f as AgentHttpError, C as CancelResult, g as ChatStreamRequest, h as ChatStreamResponse, M as MessageFeedbackInput, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-CYlhK7XD.js';
+import { MessageAttachment, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, QuotaReport, QuotaWindow, QuotaBlock, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, ToolCatalogEntry } from '@dudousxd/nestjs-agent-core';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
+import * as React from 'react';
 import React__default, { ReactNode, Context } from 'react';
-import { T as TranscriptUiBlock, 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 } 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';
+import { o as GenuiProviderValue, T as TranscriptUiBlock, A as ApproveOptions, t as TranscriptBlock, U as UsageSummary, v as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, w as ToolCatalog, x as AnyToolUIPart, y as TranscriptFile } from './generative-ui-9AJNVKBZ.js';
+export { z as ApprovalBlockOptions, B as BuildBlocksOptions, D as CoercibleQuestion, E as DescribeToolCallOptions, F as ElicitationBlockOptions, H as GroupToolActivityOptions, I as RawAnswer, J as ResolvedReading, K as ResolvedResultView, L as RetrievedPassage, S as SettleAction, N as ToolActivityGroup, O as ToolCallDescription, P as ToolCallState, Q as ToolCallStatus, V as TranscriptApproval, W as TranscriptApprovalStatus, X as TranscriptElicitationBlock, Y as TranscriptElicitationOutcome, Z as TranscriptFilesBlock, _ as TranscriptQuestion, $ as TranscriptQuestionOption, a0 as TranscriptReasoningBlock, a1 as TranscriptSettleState, a2 as TranscriptSource, a3 as TranscriptSourcesBlock, a4 as TranscriptTextBlock, a5 as TranscriptToolBlock, a6 as TranscriptToolCall, a7 as buildTranscriptBlocks, a8 as coerceAnswer, a9 as correctedCallIds, aa as describeTimestamp, ab as describeToolCall, ac as describeUsage, ad as extractMessageText, ae as fillTemplate, af as formatRelativeTime, ag as groupToolActivity, ah as inferResultView, ai as isActionCall, aj as phraseFor, ak as readPath, al as resolveResultView, am as toolCallState, an as toolCatalogFrom } from './generative-ui-9AJNVKBZ.js';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
@@ -56,12 +56,10 @@ interface AgentChatTransportOptions {
     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
-     * `${baseUrl}/agent/chat` etc. Defaults to `''` (same origin).
-     */
+    /** The server's origin, e.g. `https://api.example.com`. Defaults to `''` (same origin). */
     baseUrl?: string;
+    /** The agent's route prefix (`AgentModule`'s `path`, global prefix included). Default `'agent'`. */
+    path?: string;
     /** Static headers merged into every request (e.g. a tenant ref). */
     headers?: Record<string, string>;
     /**
@@ -232,7 +230,7 @@ interface UseAttachmentsOptions {
      * answered; honour `signal` so `remove` can cancel; call `onProgress(0..1)` if you can.
      */
     upload?: (file: File, options: UploadAttachmentOptions) => Promise<MessageAttachment>;
-    /** Used for the default `upload`. One of `upload` / `backend` is required. */
+    /** Used for the default `upload`. Default: the enclosing `<AgentProvider>`'s. */
     backend?: AgentBackend;
     /** `<input accept>` grammar: `'image/*,.pdf'` or `['image/*', 'application/pdf']`. */
     accept?: string | readonly string[];
@@ -303,11 +301,65 @@ interface ClipboardLikeEvent {
  * files.clear();
  * ```
  */
-declare function useAttachments(options: UseAttachmentsOptions): AttachmentsState;
+declare function useAttachments(options?: UseAttachmentsOptions): AttachmentsState;
+
+interface AgentProviderProps {
+    /**
+     * A backend of your own — see {@link AgentBackend}. Omitted → an {@link AgentClient} over this
+     * library's REST routes, built from the connection props below (which are ignored when a backend
+     * is given). Must be stable across renders.
+     */
+    backend?: AgentBackend;
+    /** The server's origin, e.g. `https://api.example.com`. Default `''` (same origin). */
+    baseUrl?: string;
+    /** `AgentModule`'s `path`, global prefix included (`'api/agent'`). Default `'agent'`. */
+    path?: string;
+    /** Static headers on every request. */
+    headers?: Record<string, string>;
+    /**
+     * Read at every request — a short-lived bearer token, or a CSRF header read from a cookie
+     * (`{ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }`).
+     */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** `'include'` when the API is on another origin and authenticates by cookie. */
+    credentials?: RequestCredentials;
+    /** Injectable for tests / non-browser runtimes. */
+    fetch?: typeof fetch;
+    /** Attachment uploads of the built-in client. */
+    attachments?: {
+        /** e.g. `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`. */
+        upload?: AttachmentUploadStrategy;
+    };
+    /**
+     * Set generative UI up here — the same settings `<GenuiProvider>` takes (registry, catalog,
+     * resolver, fallback, …). Every message then draws pushed components with them.
+     */
+    genui?: GenuiProviderValue;
+    children?: ReactNode;
+}
+/**
+ * The agent connection, once, at the app root. Every hook below it — `useAgentChat`, `useThreads`,
+ * `useModels`, `useAgents`, `useQuota`, `useToolCatalog`, `useMessageFeedback`, `useAttachments` —
+ * talks to it unless handed a `backend` of its own.
+ *
+ * ```tsx
+ * <AgentProvider baseUrl="https://api.example.com" credentials="include">
+ *   <App />
+ * </AgentProvider>
+ * ```
+ *
+ * Without a provider every hook shares one same-origin client on `/agent`.
+ */
+declare function AgentProvider({ backend, baseUrl, path, headers, getHeaders, credentials, fetch, attachments, genui, children, }: AgentProviderProps): React.JSX.Element;
+/**
+ * The backend a hook talks to: `own` when given, else the enclosing {@link AgentProvider}'s, else a
+ * shared same-origin client on `/agent`. For your own hooks over the same connection.
+ */
+declare function useAgentBackend<B extends AgentBackend = AgentBackend>(own?: B): B;
 
 interface UseAgentsOptions {
-    /** `useAgentChat(...).backend`, or your own. Must implement `listAgents`. */
-    backend: AgentBackend;
+    /** Default: the enclosing `<AgentProvider>`'s. Must implement `listAgents`. */
+    backend?: AgentBackend;
     /** `false` holds the request. Default `true`. */
     enabled?: boolean;
 }
@@ -324,11 +376,11 @@ interface AgentsState {
  * 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;
+declare function useAgents(options?: UseAgentsOptions): AgentsState;
 
 interface UseModelsOptions {
-    /** `useAgentChat(...).backend`, or your own. Must implement `listModels`. */
-    backend: AgentBackend;
+    /** Default: the enclosing `<AgentProvider>`'s. Must implement `listModels`. */
+    backend?: AgentBackend;
     /** The agent to list models for; omitted → the default agent. */
     agent?: string;
     /** `false` holds the request. Default `true`. */
@@ -358,11 +410,11 @@ interface ModelsState {
  * as `useAgentChat({ model })`, `sendMessage(msg, { body: { model } })`, or pin it on the thread
  * with `chat.setThreadModel(id)`.
  */
-declare function useModels(options: UseModelsOptions): ModelsState;
+declare function useModels(options?: UseModelsOptions): ModelsState;
 
 interface UseQuotaOptions {
-    /** `useAgentChat(...).backend`, or your own. Must implement `getQuota`. */
-    backend: AgentBackend;
+    /** Default: the enclosing `<AgentProvider>`'s. Must implement `getQuota`. */
+    backend?: AgentBackend;
     /** `false` holds the request. Default `true`. */
     enabled?: boolean;
     /** Re-read every `pollMs` ms as well. Default: only on mount, after runs, and on `refresh`. */
@@ -386,11 +438,11 @@ interface QuotaState {
  * one — if any — blocks sends. Re-read after every run a chat on the same backend settles, so a
  * meter moves with the conversation. Headless: draw the meter yourself.
  */
-declare function useQuota(options: UseQuotaOptions): QuotaState;
+declare function useQuota(options?: UseQuotaOptions): QuotaState;
 
 interface UseMessageFeedbackOptions {
-    /** `useAgentChat(...).backend`, or your own. Must implement `setMessageFeedback`. */
-    backend: AgentBackend;
+    /** Default: the enclosing `<AgentProvider>`'s. 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
@@ -415,7 +467,7 @@ interface MessageFeedbackState {
  * 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;
+declare function useMessageFeedback(options?: UseMessageFeedbackOptions): MessageFeedbackState;
 
 /**
  * What changed about a backend's thread list. `changed` → refetch (a thread was created, or a run
@@ -439,11 +491,11 @@ declare function onThreadsEvent(backend: AgentBackend, listener: Listener): () =
 
 interface UseThreadsOptions {
     /**
-     * The backend to list — `useAgentChat(...).backend`, or your own. Must be STABLE across renders:
+     * The backend to list. Default: the enclosing `<AgentProvider>`'s. 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;
+    backend?: AgentBackend;
     /** `false` holds the first request (e.g. until the user is signed in). Default `true`. */
     enabled?: boolean;
 }
@@ -464,7 +516,7 @@ interface ThreadsState {
  * backend reports thread creation and settled runs (refetch) and streamed titles (patched in
  * place). Headless — it renders nothing.
  */
-declare function useThreads(options: UseThreadsOptions): ThreadsState;
+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
@@ -635,15 +687,47 @@ interface TranscriptItem {
     fork: TranscriptActionState;
     regenerate: TranscriptActionState;
 }
+/** What an edit-and-resubmit sends. */
+interface EditSubmitInput {
+    messageId: string;
+    text: string;
+}
+/** Names the message an action is about. */
+interface MessageActionInput {
+    messageId: string;
+}
+/** Settling a parked question set. `answers` holds only the questions the user touched. */
+interface AnswerInput {
+    toolCallId: string;
+    answers?: Record<string, string[]>;
+}
+/** Declining a parked question set. */
+interface SkipInput {
+    toolCallId: string;
+}
+/** Approving a tool call parked on a human. */
+interface ApproveInput extends ApproveOptions {
+    toolCallId: string;
+    /** The surface the decision came through; the server records `'web'` when omitted. */
+    via?: string;
+}
+/** Rejecting a tool call parked on a human. */
+interface RejectInput {
+    toolCallId: string;
+    reason?: string;
+    via?: string;
+}
 interface TranscriptItemOptions {
     /** User messages get an inline edit-and-resubmit machine. */
     editable?: boolean;
-    onEditSubmit?: (messageId: string, text: string) => void | Promise<void>;
-    onFork?: (messageId: string) => void | Promise<void>;
+    onEditSubmit?: (input: EditSubmitInput) => void | Promise<void>;
+    onFork?: (input: MessageActionInput) => void | Promise<void>;
     /** Only the LAST assistant message gets a regenerate machine. */
     regeneratable?: boolean;
-    onRegenerate?: (messageId: string) => void | Promise<void>;
+    onRegenerate?: (input: MessageActionInput) => void | Promise<void>;
+    /** Default: `metadata.usage` (replayed turns; see `AgentMessageMetadata`). */
     getUsage?: (message: UIMessage) => MessageUsageInfo | null;
+    /** Default: `metadata.createdAt` (replayed and streamed messages). */
     getCreatedAt?: (message: UIMessage) => string | null;
     /** How long `copy.copied` stays true. Default 1500ms. */
     copyResetMs?: number;
@@ -660,23 +744,24 @@ interface TranscriptItemOptions {
      */
     toolCatalog?: ToolCatalog;
     /**
-     * Settle a parked question set — wire to `useAgentChat`'s `answer`. Supplying it is what lifts a
-     * question set out of the tool run into an `elicitation` block: without somewhere to send an
-     * answer, a form is a card the user cannot act on.
+     * Settle a parked question set. Default: the in-scope backend's `answerToolCall` (the enclosing
+     * `<AgentProvider>`'s), so a question set is an `elicitation` block the user can act on without
+     * any wiring. `null` turns question sets back into plain tool calls.
      *
      * `answers` holds ONLY the questions the user touched. An omitted one takes its own pre-picked
      * default server-side, which is what keeps "just confirmed" and "picked exactly what was
      * pre-picked" distinguishable in the settled row.
      */
-    onAnswer?: (toolCallId: string, answers: Record<string, string[]>) => void | Promise<void>;
-    /** Decline the question set and let the agent proceed on its own picks — `useAgentChat`'s `skip`. */
-    onSkip?: (toolCallId: string) => void | Promise<void>;
+    onAnswer?: ((input: AnswerInput) => void | Promise<void>) | null;
+    /** Decline the question set and let the agent proceed on its own picks. Default: the backend's. */
+    onSkip?: ((input: SkipInput) => void | Promise<void>) | null;
     /**
-     * Settle a tool call parked on a human — `useAgentChat`'s `approve` / `reject`. `options.remember`
-     * is what `call.approve.run({ remember: true })` passed.
+     * Settle a tool call parked on a human. Default: the in-scope backend's `approveToolCall` /
+     * `rejectToolCall`. `remember` is what `call.approve.run({ remember: true })` passed. `null`
+     * leaves the call without the affordance.
      */
-    onApprove?: (toolCallId: string, options?: ApproveOptions) => void | Promise<void>;
-    onReject?: (toolCallId: string) => void | Promise<void>;
+    onApprove?: ((input: ApproveInput) => void | Promise<void>) | null;
+    onReject?: ((input: RejectInput) => void | Promise<void>) | null;
 }
 interface TranscriptWindow {
     visibleCount: number;
@@ -805,12 +890,12 @@ interface MessageItemProps extends MessageRenderSlots {
     isStreaming?: boolean;
     /** User bubble gets a pencil → inline textarea; submitting calls back with the new text. */
     editable?: boolean;
-    onEditSubmit?: (newText: string) => void | Promise<void>;
+    onEditSubmit?: (input: EditSubmitInput) => void | Promise<void>;
     /** Assistant bubble gets a "Regenerate" affordance. */
     regeneratable?: boolean;
-    onRegenerate?: () => void | Promise<void>;
+    onRegenerate?: (input: MessageActionInput) => void | Promise<void>;
     /** When provided, a "Fork" affordance calls back with this message's id. */
-    onFork?: (uiMessageId: string) => void | Promise<void>;
+    onFork?: (input: MessageActionInput) => void | Promise<void>;
     /** Server-aggregated usage for this assistant turn (cost + tokens line). */
     usage?: MessageUsageInfo | null;
     /** ISO timestamp of the persisted message; rendered as a relative-time line when set. */
@@ -860,13 +945,13 @@ interface MessageListProps {
     /** Extra content for one message's action row — e.g. a badge naming which agent answered. */
     getMeta?: (message: UIMessage) => React__default.ReactNode;
     /** When set, every message gets a "Fork" affordance calling back with its id. */
-    onFork?: (uiMessageId: string) => void | Promise<void>;
+    onFork?: (input: MessageActionInput) => void | Promise<void>;
     /** User messages get an inline edit-and-resubmit affordance. */
     editable?: boolean;
-    onEditSubmit?: (uiMessageId: string, newText: string) => void | Promise<void>;
+    onEditSubmit?: (input: EditSubmitInput) => void | Promise<void>;
     /** The last assistant message gets a "Regenerate" affordance. */
     regeneratable?: boolean;
-    onRegenerate?: (uiMessageId: string) => void | Promise<void>;
+    onRegenerate?: (input: MessageActionInput) => void | Promise<void>;
     /** Per-message resolvers for the usage line and the persisted timestamp. */
     getUsage?: (message: UIMessage) => MessageUsageInfo | null;
     getCreatedAt?: (message: UIMessage) => string | null;
@@ -1025,8 +1110,8 @@ interface SkillSuggestionData {
     shadows?: string[];
 }
 interface SkillsSourceOptions {
-    /** Any backend with `listSkills` — `useAgentChat(...).backend`. */
-    client: Pick<AgentBackend, 'listSkills'>;
+    /** Any backend with `listSkills` — `useAgentBackend()`, or `useAgentChat().backend`. */
+    backend: 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.
@@ -1122,13 +1207,12 @@ declare function useComposerAutocomplete(options: UseComposerAutocompleteOptions
 
 /** 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.
+     * The backend to ask. Default: the enclosing `<AgentProvider>`'s. Must be STABLE across renders
+     * (the shared copy is keyed by it): a backend constructed inline refetches every render.
      */
-    client: ToolsBackend;
+    backend?: 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`. */
@@ -1149,7 +1233,7 @@ interface ToolCatalogState {
  * `phraseFor`, `describeToolCall` and `groupToolActivity` — or pass `catalog` to
  * `useChatTranscript({ toolCatalog })` and read the phrases off the transcript's calls.
  */
-declare function useToolCatalog(options: UseToolCatalogOptions): ToolCatalogState;
+declare function useToolCatalog(options?: UseToolCatalogOptions): ToolCatalogState;
 
 interface ApprovalCountdown {
     /** Milliseconds until the request lapses, floored at 0; `null` when it never does. */
@@ -1231,6 +1315,8 @@ interface AgentMessageMetadata extends Partial<StoredTurnMetadata> {
     feedback?: MessageFeedback;
     runId?: string;
     costUsd?: number | null;
+    /** ISO timestamp: the stored row's `createdAt` (a merged turn: its first row's), or when a live turn started streaming. */
+    createdAt?: string;
 }
 /**
  * Convert a thread's full `StoredMessage[]` history into `UIMessage[]`, merging consecutive
@@ -1272,11 +1358,10 @@ interface AgentMessageMetadata extends Partial<StoredTurnMetadata> {
  */
 declare function storedThreadToUiMessages(messages: StoredMessage[]): UIMessage[];
 
-interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
+interface UseAgentChatOptions<B extends AgentBackend = AgentBackend> {
     /**
-     * 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.
+     * What the chat talks to — see {@link AgentBackend}. Omitted → the enclosing `<AgentProvider>`'s,
+     * else a same-origin client on `/agent`. Must be stable across renders.
      */
     backend?: B;
     /**
@@ -1285,86 +1370,77 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
      * it off.
      */
     reconnect?: ReconnectOptions | false;
-    /** 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. */
-    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    /** Forwarded to fetch so cookie auth/impersonation works. */
-    credentials?: RequestCredentials;
-    /** Injectable for tests / non-browser runtimes. */
-    fetch?: typeof fetch;
-    /**
-     * How the built-in client uploads attachments (ignored when a backend is given) — e.g.
-     * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`. Pass `chat.backend` to
-     * `useAttachments` and every composer uses it.
-     */
-    attachments?: AttachmentUploadStrategy;
-    /** Reuse an existing client instead of constructing one. Prefer {@link backend}. */
-    client?: B;
     /** Named agent to run each turn. */
     agent?: string;
     /**
-     * The quota window blocking sends — `useQuota(...).blocked`. While set, `sendMessage` and
-     * `regenerate` refuse with {@link QuotaBlockedError} instead of starting a turn the server would
-     * refuse anyway.
+     * Thread this chat is bound to. Omitted → the backend creates one on the first send
+     * ({@link UseAgentChatOptions.onThreadCreated}). Changing it switches the chat to that thread:
+     * its history loads and a turn still streaming on it is re-attached. Switching to the thread this
+     * chat just created (syncing a URL) keeps the live conversation as it is.
      */
-    blocked?: QuotaBlock | null;
+    threadId?: 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 } })`.
+     * Load a `threadId`'s persisted history into the chat (`GET <base>/threads/:id`). Default `true`;
+     * skipped when {@link UseAgentChatOptions.initialMessages} is given. `false` opts out.
      */
-    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). */
+    history?: boolean;
+    /** Persisted history you already have — seeds the chat instead of loading it (read per thread). */
     initialMessages?: UIMessage[];
     /**
-     * Run id of a buffered stream to reconnect to on mount — wire this to the thread's
-     * `activeStreamId`. Its presence both gates the SDK's `resume` and names the run, so a normal
-     * mount (no id) never fires a doomed resume GET. Omitted → no resume.
-     *
-     * For the common case (no id in hand yet), prefer {@link UseAgentChatOptions.resume} — it does
-     * this fetch-and-wire for you.
+     * Re-attach to a turn that was still streaming on `threadId` when the page (re)loaded — read off
+     * the thread's `activeRunId`, so a reload mid-answer keeps streaming it. Default `true`; `false`
+     * opts out.
+     */
+    resume?: boolean;
+    /**
+     * A run id you already know is streaming — attached to on mount without reading the thread first.
+     * Rarely needed: {@link UseAgentChatOptions.resume} finds it by itself.
      */
     resumeRunId?: string;
     /**
-     * When `true` and the hook (re)mounts with a `threadId`, the hook fetches the thread and, if its
-     * `activeRunId` is non-null (a turn was still streaming when the page loaded/reloaded), attaches
-     * to that run's `GET /agent/chat/:runId/stream` automatically — the in-flight turn streams into
-     * this session's message state exactly as if the send had happened here. A no-op when `threadId`
-     * is omitted (nothing to resume) or the fetched thread has no active run. Default `false`.
+     * The model every turn runs on, controlled by you. Omitted → `chat.models.selected` (what
+     * `chat.models.select(id)` picked), else the thread's pinned model, else the server default. A
+     * single send can still override it with `sendMessage(msg, { body: { model } })`.
      */
-    resume?: boolean;
+    model?: string;
+    /**
+     * Read the caller's budget (`GET <base>/quota`) and refuse sends while a window is exhausted.
+     * Default `true` when the backend implements `getQuota`; `false` skips the request.
+     */
+    quota?: boolean;
+    /**
+     * Override the quota gate: `null` never blocks, a {@link QuotaBlock} always does. Omitted → the
+     * gate follows {@link UseAgentChatOptions.quota}'s report. While blocked, `sendMessage` and
+     * `regenerate` refuse with {@link QuotaBlockedError}.
+     */
+    blocked?: QuotaBlock | null;
+    /** Validation and upload for `chat.composer.files` — see `useAttachments`. */
+    composer?: Omit<UseAttachmentsOptions, 'backend'>;
+    /**
+     * Overrides for `chat.transcript` — anything `useChatTranscript` takes (`sources`, `editable` +
+     * `onEditSubmit`, `followUps`, `getUsage`, a `toolCatalog` of your own, `onApprove: null`, …).
+     * Yours win over the chat's own wiring.
+     */
+    transcript?: Partial<Omit<UseChatTranscriptOptions, 'messages' | 'status'>>;
     /** Read at every send to capture a page snapshot for the page-assistant. */
     getPageContext?: () => Record<string, unknown> | null;
     /** Fired after each streamed turn finishes (e.g. to refetch the sidebar). */
     onFinish?: () => void;
     /**
-     * Fired once when a threadless chat's first send makes the backend create a thread — carries the
-     * new id so the consumer can sync its URL/router. Not fired when `threadId` was supplied. The hook
-     * ALSO remembers the id internally, so every subsequent send reuses it (no new thread per message)
-     * even before the consumer navigates.
+     * Fired when this chat moves to a thread it created: the first send of a threadless chat (the
+     * backend created one), or `chat.fork(…)`. Carries the id so the host can sync its URL/router.
+     * The hook already remembers a created thread, so every later send reuses it even before the
+     * host navigates.
      */
     onThreadCreated?: (threadId: string) => void;
     /**
      * Fired exactly once per run when its stream settles — normally (`'completed'`) or via a thrown
      * failure / the backend's `event: error` frame (`'failed'`) — including a RESUMED stream's own
      * completion. By the time this fires, the server has already derived and persisted the thread's
-     * title (and the run's terminal state), so it's the signal `onFinish` doesn't give you: `onFinish`
-     * only says "a turn rendered," never "the server is done writing" — without this, a host has no
-     * reason to refetch the thread/list queries, and the header/sidebar title is stuck on "Untitled".
-     *
-     * Skipped when the attempt never got far enough to learn a run id (e.g. the initial POST itself
-     * failed before any response headers/meta frame arrived) — nothing was created server-side, so
-     * there's nothing to refetch.
+     * title (and the run's terminal state).
      *
-     * A user-initiated `cancel()`/`stop()` reports `'completed'` here (the AI SDK's own abort signal
-     * doesn't set its `isError` flag) — the server-side cancel already recorded its own terminal run
-     * state; this callback only reflects whether the CLIENT's stream loop exited with or without an
-     * error, not why it stopped.
+     * Skipped when the attempt never got far enough to learn a run id. A user-initiated `cancel()`
+     * reports `'completed'` (the server-side cancel records its own terminal state).
      */
     onRunSettled?: (outcome: {
         runId: string;
@@ -1377,29 +1453,16 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
      * `data-<kind>`. See `AgentChatTransport` for the full mapping.
      */
     onData?: (part: DataUIPart<UIDataTypes>) => void;
-    /**
-     * The server set or changed the thread's title while a turn streamed. Lets a header/sidebar
-     * update the moment the title exists instead of refetching after the run settles.
-     */
+    /** The server set or changed the thread's title while a turn streamed. */
     onTitle?: (title: string) => void;
     /**
      * Track DETACHED sub-agents this conversation started: which are still working, and their answers
      * as they land (see {@link ChatBackground}). Default `false`.
-     *
-     * Opt-in for the same reason {@link UseAgentChatOptions.resume} is — it reads the thread, and a
-     * plain mount must not spend a request on a feature the host is not using. Leaving it off still
-     * leaves {@link ChatBackground.refresh} callable, for a host that would rather drive it itself.
      */
     background?: boolean;
     /**
      * How often to re-read the thread while a detached sub-agent is still working, in ms. Default
      * 5000; `0` turns the interval off, leaving {@link ChatBackground.refresh} as the only trigger.
-     *
-     * A poll rather than a second stream, because what a background run produces is a persisted
-     * MESSAGE, not tokens this chat should render as they arrive: its answer belongs to its own run,
-     * it can land while the user is mid-turn or has the tab closed, and it has to be there on the next
-     * reload either way. The interval exists only while something is outstanding, which is rare and
-     * bounded by how many delegations a conversation has started.
      */
     backgroundPollMs?: number;
 }
@@ -1411,18 +1474,51 @@ interface ChatBackground {
     /** Re-read the thread now, instead of waiting for the next poll. */
     refresh: () => Promise<void>;
 }
+/** The chat's model picker state. Loaded the first time `list`/`providers` is read. */
+interface ChatModels {
+    /** Every model the caller may pick, flattened (`[]` until loaded). */
+    readonly list: ModelOption[];
+    /** The same, grouped by provider. */
+    readonly providers: ModelsState['providers'];
+    /** What the next turn runs on: the `model` option, the pick, the thread's pin, else the default. */
+    selected: string | null;
+    /** Run the following turns on `id` (sent as the body's `model`). */
+    select: (id: string) => void;
+    /**
+     * Pin `id` on the thread (`null` unpins) — every later turn without its own `model` runs on it,
+     * across reloads. On a chat with no thread yet, the pin lands when the first send creates one.
+     */
+    pinToThread: (id: string | null) => Promise<void>;
+    isLoading: boolean;
+    error: Error | null;
+}
+/** Why the composer cannot send right now. */
+type ComposerBlock = 'empty' | 'busy' | 'uploading' | 'quota';
+/** A headless composer: the draft, its files, and whether (and why not) it can send. */
+interface ChatComposer {
+    text: string;
+    setText: (text: string) => void;
+    /** The staged attachments — `useAttachments` state on the chat's backend. */
+    files: AttachmentsState;
+    canSend: boolean;
+    /** Why `canSend` is false, or `null`. */
+    blockedBy: ComposerBlock | null;
+    /** Send the draft with the ready files attached, then clear both. A no-op while blocked. */
+    submit: () => Promise<void>;
+}
 interface AddToolResultArgs {
     tool: string;
     toolCallId: string;
     output: unknown;
 }
 /**
- * Generalized `useChat` wiring for the nestjs-agent backend. Wraps the
- * AI SDK v7 hook with `AgentChatTransport`, plus thread list/load/delete/
- * fork, quota, cancel, and HITL approve/reject — all driven through
- * `AgentClient`. Mirrors flip's `useAdminChat`, generalized.
+ * The agent chat, wired: the AI SDK v7 `useChat` over `AgentChatTransport`, a thread's history
+ * loaded and a streaming turn re-attached on its own, a quota send gate, a model picker, a headless
+ * composer with attachments, and a transcript whose approve/reject/answer/skip/stop/fork/regenerate
+ * are already bound. Every piece is also a hook of its own (`useChatTranscript`, `useAttachments`,
+ * `useModels`, `useQuota`, `useThreads`) for a host that wants to wire it differently.
  */
-declare function useAgentChat<B extends AgentBackend = AgentClient>(options: UseAgentChatOptions<B>): {
+declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: UseAgentChatOptions<B>): {
     status: ChatStatus;
     /** Where the live stream stands — see {@link StreamConnectionState}. */
     connection: StreamConnectionState;
@@ -1449,48 +1545,44 @@ declare function useAgentChat<B extends AgentBackend = AgentClient>(options: Use
     /** Sub-agents this conversation started and did not wait for. */
     background: ChatBackground;
     runId: string | undefined;
-    /** The `resume`-fetched thread's active run id, or `null` once resolved with none. */
+    /** The loaded thread's running turn, or `null` once read with none. */
     activeRunId: string | null;
+    /** The thread's history is being read. */
+    isLoadingHistory: boolean;
+    /** Reading the thread's history failed. */
+    historyError: Error | null;
     /**
      * 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`, … */
+    /** The backend this chat talks to — the same one every other hook under the provider uses. */
     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>;
-    deleteThread: (id: string) => Promise<void>;
-    forkThread: (threadId: string, messageId: string) => Promise<ThreadSummary>;
-    renameThread: (id: string, title: string) => Promise<void>;
-    promoteThread: (id: string) => Promise<void>;
-    truncateFromMessage: (threadId: string, messageId: string) => Promise<void>;
-    quota: _dudousxd_nestjs_agent_core.QuotaView | null;
-    loadQuota: () => Promise<QuotaToday>;
+    /** The transcript model, with every action already bound to this chat. */
+    transcript: ChatTranscript;
+    /** A headless composer: draft, files, send gate, `submit()`. */
+    composer: ChatComposer;
+    /** The model picker: `list`, `selected`, `select(id)`, `pinToThread(id)`. */
+    models: ChatModels;
+    /** The caller's budget (`GET <base>/quota`); `quota.blocked` gates sends. */
+    quota: QuotaState;
+    /** The window blocking sends right now (the `blocked` option, else the quota report's). */
+    blocked: QuotaBlock | null;
     cancel: () => Promise<void>;
-    approve: ({ toolCallId, remember, via, }: {
-        toolCallId: string;
-        /** Approve later calls of the same tool in this thread without asking. */
-        remember?: boolean;
-        via?: string;
-    }) => Promise<void>;
-    reject: ({ toolCallId, reason, via, }: {
-        toolCallId: string;
-        reason?: string;
-        via?: string;
-    }) => Promise<void>;
-    answer: ({ toolCallId, answers, }: {
-        toolCallId: string;
-        answers?: Record<string, string[]>;
+    approve: ({ toolCallId, remember, via }: ApproveInput) => Promise<void>;
+    reject: ({ toolCallId, reason, via }: RejectInput) => Promise<void>;
+    answer: ({ toolCallId, answers }: AnswerInput) => Promise<void>;
+    skip: ({ toolCallId }: SkipInput) => Promise<void>;
+    regenerate: (_input?: Partial<MessageActionInput>) => void;
+    fork: ({ messageId, threadId, }: MessageActionInput & {
+        threadId?: string;
+    }) => Promise<ThreadSummary>;
+    truncateFrom: ({ messageId, threadId }: MessageActionInput & {
+        threadId?: string;
     }) => Promise<void>;
-    skip: ({ toolCallId }: {
-        toolCallId: string;
+    promote: ({ threadId }?: {
+        threadId?: string;
     }) => Promise<void>;
-    regenerate: () => void;
     id: string;
     setMessages: (messages: UIMessage<unknown, UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, UIDataTypes, ai.UITools>[]) => UIMessage<unknown, UIDataTypes, ai.UITools>[])) => void;
     error: Error | undefined;
@@ -1501,10 +1593,10 @@ declare function useAgentChat<B extends AgentBackend = AgentClient>(options: Use
     addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
     clearError: () => void;
 };
-/** A send refused on the client because a quota window is exhausted (`useAgentChat({ blocked })`). */
+/** A send refused on the client because a quota window is exhausted. */
 declare class QuotaBlockedError extends Error {
     readonly block: QuotaBlock;
     constructor(block: QuotaBlock);
 }
 
-export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, AttachmentUploadStrategy, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, 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, UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentMessageMetadata, AgentProvider, type AgentProviderProps, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, type AnswerInput, AnyToolUIPart, type ApprovalCountdown, type ApproveInput, ApproveOptions, type AttachmentRejection, AttachmentUploadStrategy, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type EditSubmitInput, type MessageActionInput, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type ReconnectOptions, type RejectInput, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SkipInput, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, 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, UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentBackend, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };