@dudousxd/nestjs-agent-react 0.23.0 → 0.25.0

package/dist/index.d.cts

@@ -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 AttachmentUploadStrategy } from './client-ioKDyV2q.cjs';
-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-ioKDyV2q.cjs';
-import { MessageAttachment, AgentClientConfig, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, QuotaReport, QuotaWindow, QuotaBlock, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, ToolCatalogEntry } from '@dudousxd/nestjs-agent-core';
+import { A as AgentBackend, U as UploadAttachmentOptions, H as HttpErrorListener, a as AttachmentUploadStrategy } from './client-D4ZSbZJ8.cjs';
+export { b as AgentBackendUnsupportedError, c as AgentClient, d as AgentClientOptions, e as AgentConnection, f as AgentHttpError, g as AgentRequestError, C as CancelResult, h as ChatStreamRequest, i as ChatStreamResponse, M as MessageFeedbackInput, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-D4ZSbZJ8.cjs';
+import { MessageAttachment, AgentClientConfig, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, ModelCatalogLock, QuotaReport, QuotaWindow, QuotaBlock, QuotaWarning, 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 { 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.cjs';
-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.cjs';
+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-BejHxxbR.cjs';
+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-BejHxxbR.cjs';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
@@ -329,6 +329,12 @@ interface AgentProviderProps {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
+    /**
+     * Every error answer of the built-in client (an `AgentHttpError`, or a `MediaUploadError` from
+     * `mediaAttachments()`), right before it is thrown — for app-wide reactions such as "401 → sign
+     * in again". Read at call time, so it may change between renders.
+     */
+    onHttpError?: HttpErrorListener;
     /** Attachment uploads of the built-in client. */
     attachments?: {
         /** e.g. `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`. */
@@ -354,7 +360,7 @@ interface AgentProviderProps {
  *
  * 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;
+declare function AgentProvider({ backend, baseUrl, path, headers, getHeaders, credentials, fetch, onHttpError, 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.
@@ -421,6 +427,11 @@ interface ModelsState {
     models: ModelOption[];
     /** The model a turn runs on when none is picked, or `null` when the provider decides. */
     defaultModel: string | null;
+    /**
+     * The agent always runs on one model (`{ model, reason? }`), or `null`. A picker shows it
+     * read-only: the server runs every turn on it and refuses any other.
+     */
+    locked: ModelCatalogLock | null;
     /** The entry for `id`, or `undefined`. */
     find: (id: string | null | undefined) => ModelOption | undefined;
     isLoading: boolean;
@@ -430,8 +441,8 @@ interface ModelsState {
 /**
  * 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)`.
+ * as `useAgentChat({ model })` or `sendMessage(msg, { body: { model } })` (that turn only), or
+ * pin it on the thread with `chat.models.pinToThread(id)`.
  */
 declare function useModels(options?: UseModelsOptions): ModelsState;
 
@@ -452,6 +463,11 @@ interface QuotaState {
     month: QuotaWindow | undefined;
     /** The window that blocks sends, or `null` — pass it to `useAgentChat({ blocked })`. */
     blocked: QuotaBlock | null;
+    /**
+     * The soft limit: the fullest window past its `warnAt` (`{ period, ratio, reason? }`), or `null`.
+     * The server's `warning`, else derived from the windows; never set while `blocked`.
+     */
+    warning: QuotaWarning | null;
     isLoading: boolean;
     error: Error | null;
     refresh: () => Promise<void>;
@@ -723,10 +739,14 @@ interface MessageActionInput {
 interface AnswerInput {
     toolCallId: string;
     answers?: Record<string, string[]>;
+    /** The surface the answer came through; the server records `'web'` when omitted. */
+    via?: string;
 }
 /** Declining a parked question set. */
 interface SkipInput {
     toolCallId: string;
+    /** The surface the skip came through; the server records `'web'` when omitted. */
+    via?: string;
 }
 /** Approving a tool call parked on a human. */
 interface ApproveInput extends ApproveOptions {
@@ -1340,6 +1360,8 @@ interface AgentMessageMetadata extends Partial<StoredTurnMetadata> {
     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;
+    /** Host-defined keys: `StoredMessage.metadata` and the stream's `message-metadata` frames. */
+    [key: string]: unknown;
 }
 /**
  * Convert a thread's full `StoredMessage[]` history into `UIMessage[]`, merging consecutive
@@ -1423,7 +1445,9 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentBackend> {
     /**
      * 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 } })`.
+     * single send can still override it with `sendMessage(msg, { body: { model } })`. Sent as the
+     * turn's `model`, which the server applies to that turn only — pinning a model on the thread is
+     * `chat.models.pinToThread(id)`.
      */
     model?: string;
     /**
@@ -1497,19 +1521,41 @@ 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. */
+/**
+ * The chat's model picker state. Loaded the first time `list`/`providers`/`defaultModel`/`locked`
+ * is read.
+ *
+ * Two different choices: `select(id)` picks the model this chat's following sends name — each send
+ * carries it as `model`, which the server applies to that turn only and never stores; the pick is
+ * this conversation's, so switching threads drops it. `pinToThread(id)` stores a model on the
+ * thread (`PATCH threads/:id { model }`), which every later turn without a `model` of its own runs
+ * on, across reloads and devices.
+ */
 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. */
+    /**
+     * What the next turn runs on: the lock, 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`). */
+    /** The model pinned on the thread (`null` when none, or before the thread is read). */
+    pinned: string | null;
+    /** The catalog's default — what a turn runs on when nothing is picked or pinned (`null` until loaded). */
+    readonly defaultModel: string | null;
+    /**
+     * The agent always runs on one model (`{ model, reason? }`), or `null`. While locked, `select`
+     * does nothing and `selected` is the locked model.
+     */
+    readonly locked: ModelsState['locked'];
+    /** Run this chat's following sends on `id` — each send's `model`, that turn only. */
     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.
+     * across reloads. Replaces the pick, so the next send runs on the pin. On a chat with no thread
+     * yet, the pin lands when the first send creates one.
      */
     pinToThread: (id: string | null) => Promise<void>;
     isLoading: boolean;
@@ -1594,8 +1640,8 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
     cancel: () => Promise<void>;
     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>;
+    answer: ({ toolCallId, answers, via }: AnswerInput) => Promise<void>;
+    skip: ({ toolCallId, via }: SkipInput) => Promise<void>;
     regenerate: (_input?: Partial<MessageActionInput>) => void;
     fork: ({ messageId, threadId, }: MessageActionInput & {
         threadId?: string;
@@ -1622,4 +1668,4 @@ declare class QuotaBlockedError extends Error {
     constructor(block: QuotaBlock);
 }
 
-export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentConfigState, 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 UseAgentConfigOptions, 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, useAgentConfig, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentConfigState, 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, HttpErrorListener, 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 UseAgentConfigOptions, 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, useAgentConfig, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };

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 AttachmentUploadStrategy } from './client-ioKDyV2q.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-ioKDyV2q.js';
-import { MessageAttachment, AgentClientConfig, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, QuotaReport, QuotaWindow, QuotaBlock, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, ToolCatalogEntry } from '@dudousxd/nestjs-agent-core';
+import { A as AgentBackend, U as UploadAttachmentOptions, H as HttpErrorListener, a as AttachmentUploadStrategy } from './client-D4ZSbZJ8.js';
+export { b as AgentBackendUnsupportedError, c as AgentClient, d as AgentClientOptions, e as AgentConnection, f as AgentHttpError, g as AgentRequestError, C as CancelResult, h as ChatStreamRequest, i as ChatStreamResponse, M as MessageFeedbackInput, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-D4ZSbZJ8.js';
+import { MessageAttachment, AgentClientConfig, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, ModelCatalogLock, QuotaReport, QuotaWindow, QuotaBlock, QuotaWarning, 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 { 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';
+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-BejHxxbR.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-BejHxxbR.js';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
@@ -329,6 +329,12 @@ interface AgentProviderProps {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
+    /**
+     * Every error answer of the built-in client (an `AgentHttpError`, or a `MediaUploadError` from
+     * `mediaAttachments()`), right before it is thrown — for app-wide reactions such as "401 → sign
+     * in again". Read at call time, so it may change between renders.
+     */
+    onHttpError?: HttpErrorListener;
     /** Attachment uploads of the built-in client. */
     attachments?: {
         /** e.g. `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`. */
@@ -354,7 +360,7 @@ interface AgentProviderProps {
  *
  * 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;
+declare function AgentProvider({ backend, baseUrl, path, headers, getHeaders, credentials, fetch, onHttpError, 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.
@@ -421,6 +427,11 @@ interface ModelsState {
     models: ModelOption[];
     /** The model a turn runs on when none is picked, or `null` when the provider decides. */
     defaultModel: string | null;
+    /**
+     * The agent always runs on one model (`{ model, reason? }`), or `null`. A picker shows it
+     * read-only: the server runs every turn on it and refuses any other.
+     */
+    locked: ModelCatalogLock | null;
     /** The entry for `id`, or `undefined`. */
     find: (id: string | null | undefined) => ModelOption | undefined;
     isLoading: boolean;
@@ -430,8 +441,8 @@ interface ModelsState {
 /**
  * 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)`.
+ * as `useAgentChat({ model })` or `sendMessage(msg, { body: { model } })` (that turn only), or
+ * pin it on the thread with `chat.models.pinToThread(id)`.
  */
 declare function useModels(options?: UseModelsOptions): ModelsState;
 
@@ -452,6 +463,11 @@ interface QuotaState {
     month: QuotaWindow | undefined;
     /** The window that blocks sends, or `null` — pass it to `useAgentChat({ blocked })`. */
     blocked: QuotaBlock | null;
+    /**
+     * The soft limit: the fullest window past its `warnAt` (`{ period, ratio, reason? }`), or `null`.
+     * The server's `warning`, else derived from the windows; never set while `blocked`.
+     */
+    warning: QuotaWarning | null;
     isLoading: boolean;
     error: Error | null;
     refresh: () => Promise<void>;
@@ -723,10 +739,14 @@ interface MessageActionInput {
 interface AnswerInput {
     toolCallId: string;
     answers?: Record<string, string[]>;
+    /** The surface the answer came through; the server records `'web'` when omitted. */
+    via?: string;
 }
 /** Declining a parked question set. */
 interface SkipInput {
     toolCallId: string;
+    /** The surface the skip came through; the server records `'web'` when omitted. */
+    via?: string;
 }
 /** Approving a tool call parked on a human. */
 interface ApproveInput extends ApproveOptions {
@@ -1340,6 +1360,8 @@ interface AgentMessageMetadata extends Partial<StoredTurnMetadata> {
     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;
+    /** Host-defined keys: `StoredMessage.metadata` and the stream's `message-metadata` frames. */
+    [key: string]: unknown;
 }
 /**
  * Convert a thread's full `StoredMessage[]` history into `UIMessage[]`, merging consecutive
@@ -1423,7 +1445,9 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentBackend> {
     /**
      * 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 } })`.
+     * single send can still override it with `sendMessage(msg, { body: { model } })`. Sent as the
+     * turn's `model`, which the server applies to that turn only — pinning a model on the thread is
+     * `chat.models.pinToThread(id)`.
      */
     model?: string;
     /**
@@ -1497,19 +1521,41 @@ 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. */
+/**
+ * The chat's model picker state. Loaded the first time `list`/`providers`/`defaultModel`/`locked`
+ * is read.
+ *
+ * Two different choices: `select(id)` picks the model this chat's following sends name — each send
+ * carries it as `model`, which the server applies to that turn only and never stores; the pick is
+ * this conversation's, so switching threads drops it. `pinToThread(id)` stores a model on the
+ * thread (`PATCH threads/:id { model }`), which every later turn without a `model` of its own runs
+ * on, across reloads and devices.
+ */
 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. */
+    /**
+     * What the next turn runs on: the lock, 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`). */
+    /** The model pinned on the thread (`null` when none, or before the thread is read). */
+    pinned: string | null;
+    /** The catalog's default — what a turn runs on when nothing is picked or pinned (`null` until loaded). */
+    readonly defaultModel: string | null;
+    /**
+     * The agent always runs on one model (`{ model, reason? }`), or `null`. While locked, `select`
+     * does nothing and `selected` is the locked model.
+     */
+    readonly locked: ModelsState['locked'];
+    /** Run this chat's following sends on `id` — each send's `model`, that turn only. */
     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.
+     * across reloads. Replaces the pick, so the next send runs on the pin. On a chat with no thread
+     * yet, the pin lands when the first send creates one.
      */
     pinToThread: (id: string | null) => Promise<void>;
     isLoading: boolean;
@@ -1594,8 +1640,8 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
     cancel: () => Promise<void>;
     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>;
+    answer: ({ toolCallId, answers, via }: AnswerInput) => Promise<void>;
+    skip: ({ toolCallId, via }: SkipInput) => Promise<void>;
     regenerate: (_input?: Partial<MessageActionInput>) => void;
     fork: ({ messageId, threadId, }: MessageActionInput & {
         threadId?: string;
@@ -1622,4 +1668,4 @@ declare class QuotaBlockedError extends Error {
     constructor(block: QuotaBlock);
 }
 
-export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentConfigState, 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 UseAgentConfigOptions, 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, useAgentConfig, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentConfigState, 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, HttpErrorListener, 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 UseAgentConfigOptions, 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, useAgentConfig, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };