@dudousxd/nestjs-agent-react 0.24.0 → 0.26.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';
-export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } 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 { ALL_AGENTS, 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 {
@@ -741,6 +761,16 @@ interface RejectInput {
     via?: string;
 }
 interface TranscriptItemOptions {
+    /**
+     * A transcript nobody acts on (an audit view, a shared or archived conversation): no approve /
+     * reject, answer / skip, edit, fork, regenerate or stop — whatever handlers or backend are in
+     * scope. Parked approvals and question sets still render, with their actions unavailable.
+     *
+     * Without it the decision handlers DEFAULT to the in-scope backend (`<AgentProvider>`'s), so a
+     * parked call is actionable with no wiring; a read-only surface would otherwise have to pass
+     * `onApprove: null`, `onReject: null`, `onAnswer: null` and `onSkip: null` one by one.
+     */
+    readOnly?: boolean;
     /** User messages get an inline edit-and-resubmit machine. */
     editable?: boolean;
     onEditSubmit?: (input: EditSubmitInput) => void | Promise<void>;
@@ -967,6 +997,11 @@ interface MessageListProps {
     reasoningLabel?: React__default.ReactNode;
     /** Extra content for one message's action row — e.g. a badge naming which agent answered. */
     getMeta?: (message: UIMessage) => React__default.ReactNode;
+    /**
+     * Nobody acts on this list (an audit or shared view): parked approvals and question sets render
+     * without their actions, and no fork / edit / regenerate — see `useChatTranscript({ readOnly })`.
+     */
+    readOnly?: boolean;
     /** When set, every message gets a "Fork" affordance calling back with its id. */
     onFork?: (input: MessageActionInput) => void | Promise<void>;
     /** User messages get an inline edit-and-resubmit affordance. */
@@ -999,7 +1034,7 @@ interface MessageListProps {
  * Every decision here comes from `useChatTranscript`; the file below it is markup. A host that
  * wants a different layout drives that hook directly and never imports this component.
  */
-declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React__default.JSX.Element;
+declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, readOnly, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React__default.JSX.Element;
 
 /**
  * Languages the dictation mic offers. The Web Speech API expects a
@@ -1236,7 +1271,11 @@ interface UseToolCatalogOptions {
      * (the shared copy is keyed by it): a backend constructed inline refetches every render.
      */
     backend?: ToolsBackend;
-    /** The agent whose tools to list. Omitted → the server's default agent. */
+    /**
+     * The agent whose tools to list. Omitted → the server's default agent. {@link ALL_AGENTS} (`'*'`)
+     * → every tool the actor reaches through any agent, each once — for an app with several agents
+     * whose conversations one surface shows.
+     */
     agent?: string;
     /** `false` holds the request (e.g. until the user is signed in). Default `true`. */
     enabled?: boolean;
@@ -1425,7 +1464,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;
     /**
@@ -1499,21 +1540,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;
+    /** 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;
-    /** Run the following turns on `id` (sent as the body's `model`). */
+    /**
+     * 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;
@@ -1598,8 +1659,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;
@@ -1626,4 +1687,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';
-export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } 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 { ALL_AGENTS, 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 {
@@ -741,6 +761,16 @@ interface RejectInput {
     via?: string;
 }
 interface TranscriptItemOptions {
+    /**
+     * A transcript nobody acts on (an audit view, a shared or archived conversation): no approve /
+     * reject, answer / skip, edit, fork, regenerate or stop — whatever handlers or backend are in
+     * scope. Parked approvals and question sets still render, with their actions unavailable.
+     *
+     * Without it the decision handlers DEFAULT to the in-scope backend (`<AgentProvider>`'s), so a
+     * parked call is actionable with no wiring; a read-only surface would otherwise have to pass
+     * `onApprove: null`, `onReject: null`, `onAnswer: null` and `onSkip: null` one by one.
+     */
+    readOnly?: boolean;
     /** User messages get an inline edit-and-resubmit machine. */
     editable?: boolean;
     onEditSubmit?: (input: EditSubmitInput) => void | Promise<void>;
@@ -967,6 +997,11 @@ interface MessageListProps {
     reasoningLabel?: React__default.ReactNode;
     /** Extra content for one message's action row — e.g. a badge naming which agent answered. */
     getMeta?: (message: UIMessage) => React__default.ReactNode;
+    /**
+     * Nobody acts on this list (an audit or shared view): parked approvals and question sets render
+     * without their actions, and no fork / edit / regenerate — see `useChatTranscript({ readOnly })`.
+     */
+    readOnly?: boolean;
     /** When set, every message gets a "Fork" affordance calling back with its id. */
     onFork?: (input: MessageActionInput) => void | Promise<void>;
     /** User messages get an inline edit-and-resubmit affordance. */
@@ -999,7 +1034,7 @@ interface MessageListProps {
  * Every decision here comes from `useChatTranscript`; the file below it is markup. A host that
  * wants a different layout drives that hook directly and never imports this component.
  */
-declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React__default.JSX.Element;
+declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, readOnly, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React__default.JSX.Element;
 
 /**
  * Languages the dictation mic offers. The Web Speech API expects a
@@ -1236,7 +1271,11 @@ interface UseToolCatalogOptions {
      * (the shared copy is keyed by it): a backend constructed inline refetches every render.
      */
     backend?: ToolsBackend;
-    /** The agent whose tools to list. Omitted → the server's default agent. */
+    /**
+     * The agent whose tools to list. Omitted → the server's default agent. {@link ALL_AGENTS} (`'*'`)
+     * → every tool the actor reaches through any agent, each once — for an app with several agents
+     * whose conversations one surface shows.
+     */
     agent?: string;
     /** `false` holds the request (e.g. until the user is signed in). Default `true`. */
     enabled?: boolean;
@@ -1425,7 +1464,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;
     /**
@@ -1499,21 +1540,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;
+    /** 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;
-    /** Run the following turns on `id` (sent as the body's `model`). */
+    /**
+     * 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;
@@ -1598,8 +1659,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;
@@ -1626,4 +1687,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 };