@dudousxd/nestjs-agent-react 0.27.0 → 0.29.0

package/dist/index.d.cts

@@ -1,13 +1,49 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
-import { A as AgentBackend, U as UploadAttachmentOptions, H as HttpErrorListener, a as AttachmentUploadStrategy } from './client-DNM5Qm5N.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, Q as QueuedMessageUpdate, j as QueuedSendResult, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-DNM5Qm5N.cjs';
+import { A as AgentRequestError, a as AgentBackend, U as UploadAttachmentOptions, H as HttpErrorListener, b as AttachmentUploadStrategy } from './client-DhHEJi7c.cjs';
+export { c as AgentBackendUnsupportedError, d as AgentClient, e as AgentClientOptions, f as AgentConnection, g as AgentHttpError, C as CancelResult, h as ChatStreamRequest, i as ChatStreamResponse, M as MessageFeedbackInput, Q as QueuedMessageUpdate, j as QueuedSendResult, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-DhHEJi7c.cjs';
 import { MessageAttachment, AgentClientConfig, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, ModelCatalogLock, QuotaReport, QuotaWindow, QuotaBlock, QuotaWarning, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, QueuePause, ToolCatalogEntry } from '@dudousxd/nestjs-agent-core';
 export { ALL_AGENTS, ChatQueueState, ElicitationInput, ElicitationInputType, QueuePause, QueuePauseReason, QueuedMessageView, 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, w as TranscriptFile, M as MessageUsageInfo, x as ToolCatalog, y as AnyToolUIPart } from './generative-ui-jT9TYfCi.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-jT9TYfCi.cjs';
+import { o as GenuiProviderValue, T as TranscriptUiBlock, A as ApproveOptions, t as TranscriptBlock, U as UsageSummary, v as TimestampInfo, C as ChatStatus, w as TranscriptFile, M as MessageUsageInfo, x as ToolCatalog, y as AnyToolUIPart } from './generative-ui-VTZ1EADD.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-VTZ1EADD.cjs';
+
+/**
+ * The `code`s this library's own loop closes a failed run's stream with (`event: error`). A client
+ * branches on the code and words the failure itself — the frame's `message` is a sentence in
+ * English, and for a crash deliberately a generic one.
+ *
+ *  - `quota_exceeded` — the actor's budget is spent; `message` says which.
+ *  - `output_rejected` — an output processor refused the answer.
+ *  - `structured_output_invalid` — the answer never satisfied the agent's output schema.
+ *  - `replay_diverged` — the durable runtime refused to resume the run (its journal and the
+ *    deployed code disagree). The turn is over; sending again starts a new one.
+ *  - `model_no_output` — a model call ended without producing anything.
+ *  - `run_failed` — anything else.
+ *
+ * A host's own runner may send codes of its own, which is why {@link AgentRunFailure.code} is a
+ * plain string.
+ */
+declare const AGENT_RUN_ERROR_CODES: readonly ["quota_exceeded", "output_rejected", "structured_output_invalid", "replay_diverged", "model_no_output", "run_failed"];
+type AgentRunErrorCode = (typeof AGENT_RUN_ERROR_CODES)[number];
+/** How a run's stream said it failed: the `event: error` frame, read. */
+interface AgentRunFailure {
+    /** The frame's machine-readable `code`; `undefined` when the server sent none. */
+    code: AgentRunErrorCode | (string & {}) | undefined;
+    /** The frame's `message` — the server's words, safe to show but not translated. */
+    message: string;
+    /** The run that failed, when the stream had named it. */
+    runId?: string;
+}
+/** The `code` a decision is refused with when the run it was for has ended (`409`). */
+declare const RUN_NOT_ACTIVE_CODE = "run_not_active";
+/**
+ * Whether `error` is the server refusing an approve / reject / answer / skip because the turn that
+ * asked is over (`409 { code: 'run_not_active' }`): nothing is waiting for the decision, and nothing
+ * will run. The card it was made on is stale — say so, and let the person send the message again.
+ */
+declare function isRunNotActiveError(error: unknown): error is AgentRequestError;
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
@@ -100,6 +136,12 @@ interface AgentChatTransportOptions {
      * what the run wrote — `useAgentChat` re-reads the thread.
      */
     onResumeGone?: (runId: string) => void;
+    /**
+     * The run's stream ended with the backend's `event: error` frame — called with its `code` and
+     * `message` right before the stream is closed with an error chunk. The chunk can only carry the
+     * text; this is where the `code` reaches a caller, so it can word the failure itself.
+     */
+    onRunError?: (failure: AgentRunFailure) => void;
     /** Injectable for tests / non-browser runtimes. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -195,6 +237,11 @@ interface MessageFile {
 }
 /** The {@link MessageFileKind} of a MIME type. */
 declare function fileKind(mediaType: string): MessageFileKind;
+/**
+ * An uploaded attachment as the {@link MessageFile} it is once its message is sent — so a message
+ * still waiting (in the queue, in the composer) draws its files with the same code a sent one does.
+ */
+declare function attachmentFile(attachment: MessageAttachment): MessageFile;
 /**
  * The files on a message — the user's attachments (live, or replayed from `StoredMessage.attachments`
  * by `storedMessageToUiMessage`) and any the model produced — in part order. Data only: pair it with
@@ -660,12 +707,27 @@ declare function ChatInput({ onSubmit, disabled, placeholder, rows, enableSpeech
  *  - `'block'` — the composer refuses it (`blockedBy: 'busy'`), as before queues existed.
  */
 type WhileRunning = 'queue' | 'interrupt' | 'block';
+/**
+ * A per-call answer to "a turn is still running" — `composer.submit({ mode })`,
+ * `sendMessage(message, { mode })`. It overrides the chat's `whileRunning` for that one send
+ * (including `'block'`), and means nothing when no turn is running: the message is simply sent.
+ */
+interface SendWhileRunning {
+    /** `'queue'` — wait for the running turn. `'interrupt'` — cancel it and run this next. */
+    mode?: 'queue' | 'interrupt';
+}
 /** A message waiting in the thread's queue, as the chat shows it. */
 interface QueuedChatMessage {
     /** The server's id once it is queued; a local id while `state` is `'sending'`. */
     id: string;
     text: string;
+    /** The uploaded attachments as they were queued — what a re-send carries. */
     attachments: MessageAttachment[];
+    /**
+     * The same attachments as {@link MessageFile}s — the shape `messageFiles()` gives for a sent
+     * message, so one renderer draws the files of a waiting message and of a sent one.
+     */
+    files: MessageFile[];
     /**
      * `'sending'` — on its way to the server (it has no server id yet, so it cannot be edited).
      * `'queued'` — waiting its turn.
@@ -692,6 +754,13 @@ interface ChatQueue {
         mode?: 'queue' | 'interrupt';
     }) => Promise<void>;
     remove: (id: string) => Promise<void>;
+    /**
+     * Run a waiting message now: it moves to the head as an interrupt and the running turn is
+     * cancelled for it (with nothing running, it starts at once). One server call — the message keeps
+     * its id and never leaves the queue, unlike a `remove` followed by an `add`. Needs a backend with
+     * `interruptQueuedMessage`.
+     */
+    interrupt: (id: string) => Promise<void>;
     edit: (id: string, text: string) => Promise<void>;
     /** Move a waiting message to `index` (0 → next). */
     move: (id: string, index: number) => Promise<void>;
@@ -902,11 +971,16 @@ interface UseChatTranscriptOptions extends TranscriptItemOptions {
      * after the transcript as {@link ChatTranscript.queued}: pending user messages, not yet sent.
      */
     queue?: {
-        items: QueuedChatMessage[];
+        /** `files` may be left out by a host that builds these itself: it is derived from `attachments`. */
+        items: Array<Omit<QueuedChatMessage, 'files'> & {
+            files?: MessageFile[];
+        }>;
         paused: QueuePause | null;
         remove?: (id: string) => void | Promise<void>;
     } | null;
 }
+/** One file on a waiting message: a sent message's {@link MessageFile}, and a `TranscriptFile`. */
+type TranscriptQueuedFile = MessageFile & TranscriptFile;
 /**
  * A message waiting in the thread's queue, as the transcript shows it: a user message that has not
  * been sent to the model yet. Render it after {@link ChatTranscript.items}, dimmed or tagged.
@@ -915,7 +989,12 @@ interface TranscriptQueuedItem {
     id: string;
     role: 'user';
     text: string;
-    files: TranscriptFile[];
+    /**
+     * The message's files, in the shape a sent message's have: a {@link MessageFile} (what
+     * `messageFiles()` gives — `kind`, `extension`, `mediaId`) that is also a `TranscriptFile`
+     * (`isImage`), so either renderer takes it as it is.
+     */
+    files: TranscriptQueuedFile[];
     /**
      * `'sending'` — on its way to the server. `'queued'` — waiting for the running turn.
      * `'paused'` — waiting, but the queue is paused (see {@link ChatTranscript.queuePaused}).
@@ -1592,7 +1671,8 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentBackend> {
      * the message waits in the thread's queue (server-side — it survives a reload) and runs when the
      * turn settles; `chat.queue` lists and edits what is waiting. `'interrupt'` cancels the running
      * turn and runs the message next. `'block'` refuses the send (`composer.blockedBy === 'busy'`).
-     * A backend without `enqueueMessage` behaves as `'block'`.
+     * A backend without `enqueueMessage` behaves as `'block'`. One send can answer differently:
+     * `composer.submit({ mode })`, `sendMessage(message, { mode })`.
      */
     whileRunning?: WhileRunning;
     /**
@@ -1704,8 +1784,14 @@ interface ChatComposer {
     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>;
+    /**
+     * Send the draft with the ready files attached, then clear both. A no-op while blocked.
+     *
+     * `submit({ mode })` says what to do if a turn is running, for this send only — `'interrupt'`
+     * for a "send now" button next to a plain send that queues. It overrides `whileRunning`
+     * (`'block'` included) and clears the draft like any other submit.
+     */
+    submit: (options?: SendWhileRunning) => Promise<void>;
 }
 interface AddToolResultArgs {
     tool: string;
@@ -1723,7 +1809,25 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
     status: ChatStatus;
     /** Where the live stream stands — see {@link StreamConnectionState}. */
     connection: StreamConnectionState;
-    sendMessage: (message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
+    sendMessage: (message?: Parameters<(message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
+        id?: string;
+        role?: "user" | "assistant" | "system";
+    } & {
+        text?: never;
+        files?: never;
+        messageId?: string;
+    }) | {
+        text: string;
+        files?: FileList | ai.FileUIPart[];
+        metadata?: unknown;
+        parts?: never;
+        messageId?: string;
+    } | {
+        files: FileList | ai.FileUIPart[];
+        metadata?: unknown;
+        parts?: never;
+        messageId?: string;
+    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>>[0], options?: Parameters<(message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
         role?: "user" | "assistant" | "system";
     } & {
@@ -1741,7 +1845,7 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
         metadata?: unknown;
         parts?: never;
         messageId?: string;
-    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>;
+    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>>[1] & SendWhileRunning) => Promise<void>;
     addToolResult: ({ tool, toolCallId, output }: AddToolResultArgs) => void | PromiseLike<void>;
     /** Sub-agents this conversation started and did not wait for. */
     background: ChatBackground;
@@ -1752,6 +1856,13 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
     isLoadingHistory: boolean;
     /** Reading the thread's history failed. */
     historyError: Error | null;
+    /**
+     * How the last run's stream said it failed — the `event: error` frame's `code` and `message` —
+     * or `null`. Cleared when the next attempt starts and when the chat moves to another thread.
+     * `chat.error` still carries the message; this is where the `code` is, so the app can word each
+     * failure itself (`replay_diverged`, `model_no_output`, `run_failed`, `quota_exceeded`, …).
+     */
+    runError: AgentRunFailure | 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.
@@ -1805,4 +1916,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, type ChatQueue, 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, type QueuedChatMessage, 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 TranscriptQueuedItem, 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, type WhileRunning, 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 { AGENT_RUN_ERROR_CODES, AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentConfigState, type AgentMessageMetadata, AgentProvider, type AgentProviderProps, AgentRequestError, type AgentRunErrorCode, type AgentRunFailure, 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, type ChatQueue, 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, type QueuedChatMessage, QuotaBlockedError, type QuotaState, RUN_NOT_ACTIVE_CODE, type ReconnectOptions, type RejectInput, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SendWhileRunning, 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 TranscriptQueuedFile, type TranscriptQueuedItem, 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, type WhileRunning, acceptsFile, applyCompletion, approvalCountdown, attachmentFile, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, isRunNotActiveError, 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,49 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
-import { A as AgentBackend, U as UploadAttachmentOptions, H as HttpErrorListener, a as AttachmentUploadStrategy } from './client-DNM5Qm5N.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, Q as QueuedMessageUpdate, j as QueuedSendResult, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-DNM5Qm5N.js';
+import { A as AgentRequestError, a as AgentBackend, U as UploadAttachmentOptions, H as HttpErrorListener, b as AttachmentUploadStrategy } from './client-DhHEJi7c.js';
+export { c as AgentBackendUnsupportedError, d as AgentClient, e as AgentClientOptions, f as AgentConnection, g as AgentHttpError, C as CancelResult, h as ChatStreamRequest, i as ChatStreamResponse, M as MessageFeedbackInput, Q as QueuedMessageUpdate, j as QueuedSendResult, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-DhHEJi7c.js';
 import { MessageAttachment, AgentClientConfig, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, ModelCatalogLock, QuotaReport, QuotaWindow, QuotaBlock, QuotaWarning, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, QueuePause, ToolCatalogEntry } from '@dudousxd/nestjs-agent-core';
 export { ALL_AGENTS, ChatQueueState, ElicitationInput, ElicitationInputType, QueuePause, QueuePauseReason, QueuedMessageView, 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, w as TranscriptFile, M as MessageUsageInfo, x as ToolCatalog, y as AnyToolUIPart } from './generative-ui-jT9TYfCi.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-jT9TYfCi.js';
+import { o as GenuiProviderValue, T as TranscriptUiBlock, A as ApproveOptions, t as TranscriptBlock, U as UsageSummary, v as TimestampInfo, C as ChatStatus, w as TranscriptFile, M as MessageUsageInfo, x as ToolCatalog, y as AnyToolUIPart } from './generative-ui-VTZ1EADD.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-VTZ1EADD.js';
+
+/**
+ * The `code`s this library's own loop closes a failed run's stream with (`event: error`). A client
+ * branches on the code and words the failure itself — the frame's `message` is a sentence in
+ * English, and for a crash deliberately a generic one.
+ *
+ *  - `quota_exceeded` — the actor's budget is spent; `message` says which.
+ *  - `output_rejected` — an output processor refused the answer.
+ *  - `structured_output_invalid` — the answer never satisfied the agent's output schema.
+ *  - `replay_diverged` — the durable runtime refused to resume the run (its journal and the
+ *    deployed code disagree). The turn is over; sending again starts a new one.
+ *  - `model_no_output` — a model call ended without producing anything.
+ *  - `run_failed` — anything else.
+ *
+ * A host's own runner may send codes of its own, which is why {@link AgentRunFailure.code} is a
+ * plain string.
+ */
+declare const AGENT_RUN_ERROR_CODES: readonly ["quota_exceeded", "output_rejected", "structured_output_invalid", "replay_diverged", "model_no_output", "run_failed"];
+type AgentRunErrorCode = (typeof AGENT_RUN_ERROR_CODES)[number];
+/** How a run's stream said it failed: the `event: error` frame, read. */
+interface AgentRunFailure {
+    /** The frame's machine-readable `code`; `undefined` when the server sent none. */
+    code: AgentRunErrorCode | (string & {}) | undefined;
+    /** The frame's `message` — the server's words, safe to show but not translated. */
+    message: string;
+    /** The run that failed, when the stream had named it. */
+    runId?: string;
+}
+/** The `code` a decision is refused with when the run it was for has ended (`409`). */
+declare const RUN_NOT_ACTIVE_CODE = "run_not_active";
+/**
+ * Whether `error` is the server refusing an approve / reject / answer / skip because the turn that
+ * asked is over (`409 { code: 'run_not_active' }`): nothing is waiting for the decision, and nothing
+ * will run. The card it was made on is stale — say so, and let the person send the message again.
+ */
+declare function isRunNotActiveError(error: unknown): error is AgentRequestError;
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
@@ -100,6 +136,12 @@ interface AgentChatTransportOptions {
      * what the run wrote — `useAgentChat` re-reads the thread.
      */
     onResumeGone?: (runId: string) => void;
+    /**
+     * The run's stream ended with the backend's `event: error` frame — called with its `code` and
+     * `message` right before the stream is closed with an error chunk. The chunk can only carry the
+     * text; this is where the `code` reaches a caller, so it can word the failure itself.
+     */
+    onRunError?: (failure: AgentRunFailure) => void;
     /** Injectable for tests / non-browser runtimes. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -195,6 +237,11 @@ interface MessageFile {
 }
 /** The {@link MessageFileKind} of a MIME type. */
 declare function fileKind(mediaType: string): MessageFileKind;
+/**
+ * An uploaded attachment as the {@link MessageFile} it is once its message is sent — so a message
+ * still waiting (in the queue, in the composer) draws its files with the same code a sent one does.
+ */
+declare function attachmentFile(attachment: MessageAttachment): MessageFile;
 /**
  * The files on a message — the user's attachments (live, or replayed from `StoredMessage.attachments`
  * by `storedMessageToUiMessage`) and any the model produced — in part order. Data only: pair it with
@@ -660,12 +707,27 @@ declare function ChatInput({ onSubmit, disabled, placeholder, rows, enableSpeech
  *  - `'block'` — the composer refuses it (`blockedBy: 'busy'`), as before queues existed.
  */
 type WhileRunning = 'queue' | 'interrupt' | 'block';
+/**
+ * A per-call answer to "a turn is still running" — `composer.submit({ mode })`,
+ * `sendMessage(message, { mode })`. It overrides the chat's `whileRunning` for that one send
+ * (including `'block'`), and means nothing when no turn is running: the message is simply sent.
+ */
+interface SendWhileRunning {
+    /** `'queue'` — wait for the running turn. `'interrupt'` — cancel it and run this next. */
+    mode?: 'queue' | 'interrupt';
+}
 /** A message waiting in the thread's queue, as the chat shows it. */
 interface QueuedChatMessage {
     /** The server's id once it is queued; a local id while `state` is `'sending'`. */
     id: string;
     text: string;
+    /** The uploaded attachments as they were queued — what a re-send carries. */
     attachments: MessageAttachment[];
+    /**
+     * The same attachments as {@link MessageFile}s — the shape `messageFiles()` gives for a sent
+     * message, so one renderer draws the files of a waiting message and of a sent one.
+     */
+    files: MessageFile[];
     /**
      * `'sending'` — on its way to the server (it has no server id yet, so it cannot be edited).
      * `'queued'` — waiting its turn.
@@ -692,6 +754,13 @@ interface ChatQueue {
         mode?: 'queue' | 'interrupt';
     }) => Promise<void>;
     remove: (id: string) => Promise<void>;
+    /**
+     * Run a waiting message now: it moves to the head as an interrupt and the running turn is
+     * cancelled for it (with nothing running, it starts at once). One server call — the message keeps
+     * its id and never leaves the queue, unlike a `remove` followed by an `add`. Needs a backend with
+     * `interruptQueuedMessage`.
+     */
+    interrupt: (id: string) => Promise<void>;
     edit: (id: string, text: string) => Promise<void>;
     /** Move a waiting message to `index` (0 → next). */
     move: (id: string, index: number) => Promise<void>;
@@ -902,11 +971,16 @@ interface UseChatTranscriptOptions extends TranscriptItemOptions {
      * after the transcript as {@link ChatTranscript.queued}: pending user messages, not yet sent.
      */
     queue?: {
-        items: QueuedChatMessage[];
+        /** `files` may be left out by a host that builds these itself: it is derived from `attachments`. */
+        items: Array<Omit<QueuedChatMessage, 'files'> & {
+            files?: MessageFile[];
+        }>;
         paused: QueuePause | null;
         remove?: (id: string) => void | Promise<void>;
     } | null;
 }
+/** One file on a waiting message: a sent message's {@link MessageFile}, and a `TranscriptFile`. */
+type TranscriptQueuedFile = MessageFile & TranscriptFile;
 /**
  * A message waiting in the thread's queue, as the transcript shows it: a user message that has not
  * been sent to the model yet. Render it after {@link ChatTranscript.items}, dimmed or tagged.
@@ -915,7 +989,12 @@ interface TranscriptQueuedItem {
     id: string;
     role: 'user';
     text: string;
-    files: TranscriptFile[];
+    /**
+     * The message's files, in the shape a sent message's have: a {@link MessageFile} (what
+     * `messageFiles()` gives — `kind`, `extension`, `mediaId`) that is also a `TranscriptFile`
+     * (`isImage`), so either renderer takes it as it is.
+     */
+    files: TranscriptQueuedFile[];
     /**
      * `'sending'` — on its way to the server. `'queued'` — waiting for the running turn.
      * `'paused'` — waiting, but the queue is paused (see {@link ChatTranscript.queuePaused}).
@@ -1592,7 +1671,8 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentBackend> {
      * the message waits in the thread's queue (server-side — it survives a reload) and runs when the
      * turn settles; `chat.queue` lists and edits what is waiting. `'interrupt'` cancels the running
      * turn and runs the message next. `'block'` refuses the send (`composer.blockedBy === 'busy'`).
-     * A backend without `enqueueMessage` behaves as `'block'`.
+     * A backend without `enqueueMessage` behaves as `'block'`. One send can answer differently:
+     * `composer.submit({ mode })`, `sendMessage(message, { mode })`.
      */
     whileRunning?: WhileRunning;
     /**
@@ -1704,8 +1784,14 @@ interface ChatComposer {
     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>;
+    /**
+     * Send the draft with the ready files attached, then clear both. A no-op while blocked.
+     *
+     * `submit({ mode })` says what to do if a turn is running, for this send only — `'interrupt'`
+     * for a "send now" button next to a plain send that queues. It overrides `whileRunning`
+     * (`'block'` included) and clears the draft like any other submit.
+     */
+    submit: (options?: SendWhileRunning) => Promise<void>;
 }
 interface AddToolResultArgs {
     tool: string;
@@ -1723,7 +1809,25 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
     status: ChatStatus;
     /** Where the live stream stands — see {@link StreamConnectionState}. */
     connection: StreamConnectionState;
-    sendMessage: (message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
+    sendMessage: (message?: Parameters<(message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
+        id?: string;
+        role?: "user" | "assistant" | "system";
+    } & {
+        text?: never;
+        files?: never;
+        messageId?: string;
+    }) | {
+        text: string;
+        files?: FileList | ai.FileUIPart[];
+        metadata?: unknown;
+        parts?: never;
+        messageId?: string;
+    } | {
+        files: FileList | ai.FileUIPart[];
+        metadata?: unknown;
+        parts?: never;
+        messageId?: string;
+    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>>[0], options?: Parameters<(message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
         role?: "user" | "assistant" | "system";
     } & {
@@ -1741,7 +1845,7 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
         metadata?: unknown;
         parts?: never;
         messageId?: string;
-    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>;
+    } | undefined, options?: ai.ChatRequestOptions) => Promise<void>>[1] & SendWhileRunning) => Promise<void>;
     addToolResult: ({ tool, toolCallId, output }: AddToolResultArgs) => void | PromiseLike<void>;
     /** Sub-agents this conversation started and did not wait for. */
     background: ChatBackground;
@@ -1752,6 +1856,13 @@ declare function useAgentChat<B extends AgentBackend = AgentBackend>(options?: U
     isLoadingHistory: boolean;
     /** Reading the thread's history failed. */
     historyError: Error | null;
+    /**
+     * How the last run's stream said it failed — the `event: error` frame's `code` and `message` —
+     * or `null`. Cleared when the next attempt starts and when the chat moves to another thread.
+     * `chat.error` still carries the message; this is where the `code` is, so the app can word each
+     * failure itself (`replay_diverged`, `model_no_output`, `run_failed`, `quota_exceeded`, …).
+     */
+    runError: AgentRunFailure | 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.
@@ -1805,4 +1916,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, type ChatQueue, 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, type QueuedChatMessage, 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 TranscriptQueuedItem, 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, type WhileRunning, 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 { AGENT_RUN_ERROR_CODES, AgentBackend, AgentChatTransport, type AgentChatTransportOptions, type AgentConfigState, type AgentMessageMetadata, AgentProvider, type AgentProviderProps, AgentRequestError, type AgentRunErrorCode, type AgentRunFailure, 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, type ChatQueue, 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, type QueuedChatMessage, QuotaBlockedError, type QuotaState, RUN_NOT_ACTIVE_CODE, type ReconnectOptions, type RejectInput, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SendWhileRunning, 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 TranscriptQueuedFile, type TranscriptQueuedItem, 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, type WhileRunning, acceptsFile, applyCompletion, approvalCountdown, attachmentFile, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, isRunNotActiveError, 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 };