@dudousxd/nestjs-agent-react 0.28.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-CKwSMitS.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-CKwSMitS.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;
 }
@@ -1814,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.
@@ -1867,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 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, 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-CKwSMitS.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-CKwSMitS.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;
 }
@@ -1814,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.
@@ -1867,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 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, 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.js

@@ -615,6 +615,15 @@ var AgentChatTransport = class {
     const backend = this.backend;
     const policy = this.reconnectPolicy();
     const notify = (state) => this.options.onConnectionChange?.(state);
+    const reportRunError = (failure) => {
+      try {
+        this.options.onRunError?.({
+          ...failure,
+          ...streamRunId !== void 0 ? { runId: streamRunId } : {}
+        });
+      } catch {
+      }
+    };
     const aborted = () => cancelled || context.signal?.aborted === true;
     const canResume = () => policy !== null && lastSeq !== void 0 && streamRunId !== void 0 && !aborted();
     const resume = async () => {
@@ -939,7 +948,9 @@ var AgentChatTransport = class {
                 return;
               }
               if (frame.event === "error") {
-                fail(parseErrorText(frame.data));
+                const failure = parseErrorFrame(frame.data);
+                reportRunError(failure);
+                fail(failure.message);
                 return;
               }
               if (frame.event === "meta") {
@@ -1006,16 +1017,21 @@ function parseMeta(data) {
   }
   return null;
 }
-function parseErrorText(data) {
-  if (!data) return "Agent run failed";
+function parseErrorFrame(data) {
+  const fallback2 = { code: void 0, message: "Agent run failed" };
+  if (!data) return fallback2;
   try {
     const parsed = JSON.parse(data);
-    if (parsed !== null && typeof parsed === "object" && "message" in parsed && typeof parsed.message === "string") {
-      return parsed.message;
+    if (parsed !== null && typeof parsed === "object") {
+      const record = parsed;
+      return {
+        code: typeof record.code === "string" && record.code !== "" ? record.code : void 0,
+        message: typeof record.message === "string" && record.message !== "" ? record.message : fallback2.message
+      };
     }
   } catch {
   }
-  return "Agent run failed";
+  return fallback2;
 }
 function parseEvent(data) {
   try {
@@ -2872,7 +2888,8 @@ function buildToolCall(part, options, approval, catalog) {
       isSubmitting: sending === "reject",
       run: () => options?.reject(toolCallId)
     },
-    error: options?.errorOf(toolCallId) ?? null
+    error: options?.errorOf(toolCallId) ?? null,
+    errorCode: options?.errorCodeOf?.(toolCallId) ?? null
   };
 }
 function readElicitationRequest(part) {
@@ -3003,6 +3020,7 @@ function buildElicitationBlock(key, part, request, options) {
     isValid: questions.every((question) => question.error === null),
     outcome,
     error: options.errorOf(toolCallId),
+    errorCode: options.errorCodeOf?.(toolCallId) ?? null,
     answer: {
       available: isPending && options.canAnswer,
       isSubmitting: sending === "answer",
@@ -3471,10 +3489,10 @@ function useTranscriptItems({
           return next;
         });
         setSettleErrors(
-          (current) => new Map(current).set(
-            toolCallId,
-            error instanceof Error ? error.message : "Could not settle this"
-          )
+          (current) => new Map(current).set(toolCallId, {
+            message: error instanceof Error ? error.message : "Could not settle this",
+            code: settleErrorCode(error)
+          })
         );
       };
       try {
@@ -3655,7 +3673,8 @@ function useTranscriptItems({
             answer,
             skip,
             submitting: (toolCallId) => settling.get(toolCallId) ?? null,
-            errorOf: (toolCallId) => settleErrors.get(toolCallId) ?? null
+            errorOf: (toolCallId) => settleErrors.get(toolCallId)?.message ?? null,
+            errorCodeOf: (toolCallId) => settleErrors.get(toolCallId)?.code ?? null
           }
         } : {},
         ...handlers.onApprove !== void 0 || handlers.onReject !== void 0 ? {
@@ -3665,7 +3684,8 @@ function useTranscriptItems({
             approve,
             reject,
             submitting: (toolCallId) => settling.get(toolCallId) ?? null,
-            errorOf: (toolCallId) => settleErrors.get(toolCallId) ?? null
+            errorOf: (toolCallId) => settleErrors.get(toolCallId)?.message ?? null,
+            errorCodeOf: (toolCallId) => settleErrors.get(toolCallId)?.code ?? null
           }
         } : {}
       }),
@@ -3785,6 +3805,10 @@ function contentSignature(messages) {
   }
   return `${messages.length}|${last.id}|${last.parts?.length ?? 0}|${length}`;
 }
+function settleErrorCode(error) {
+  const code = error?.code;
+  return typeof code === "string" && code !== "" ? code : null;
+}
 
 // src/components/message-item.tsx
 import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
@@ -4854,6 +4878,7 @@ function useAgentChat(options = {}) {
   const [activeRunId, setActiveRunId] = useState15(null);
   const [historyFor, setHistoryFor] = useState15(void 0);
   const [historyError, setHistoryError] = useState15(null);
+  const [runError, setRunError] = useState15(null);
   const [threadModel, setThreadModel] = useState15(null);
   const [pickedModel, setPickedModel] = useState15(void 0);
   const pickedModelRef = useRef12(pickedModel);
@@ -4929,7 +4954,9 @@ function useAgentChat(options = {}) {
       onMeta,
       onAttemptStart: () => {
         settlingRunIdRef.current = void 0;
+        setRunError(null);
       },
+      onRunError: (failure) => setRunError(failure),
       // A queued turn this chat went to attach to had already finished: read what it wrote.
       onResumeGone: () => {
         void resyncFromThread();
@@ -5048,6 +5075,7 @@ function useAgentChat(options = {}) {
     setPickedModel(void 0);
     setBackgroundRuns([]);
     setHistoryError(null);
+    setRunError(null);
     autoResumeRunIdRef.current = void 0;
     pendingPin.current = void 0;
     applyQueue(EMPTY_QUEUE);
@@ -5651,6 +5679,13 @@ function useAgentChat(options = {}) {
     isLoadingHistory,
     /** Reading the thread's history failed. */
     historyError,
+    /**
+     * 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,
     /**
      * 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.
@@ -5692,7 +5727,22 @@ var QuotaBlockedError = class extends Error {
   }
   block;
 };
+
+// src/run-errors.ts
+var AGENT_RUN_ERROR_CODES = [
+  "quota_exceeded",
+  "output_rejected",
+  "structured_output_invalid",
+  "replay_diverged",
+  "model_no_output",
+  "run_failed"
+];
+var RUN_NOT_ACTIVE_CODE = "run_not_active";
+function isRunNotActiveError(error) {
+  return error instanceof Error && error.status === 409 && error.code === RUN_NOT_ACTIVE_CODE;
+}
 export {
+  AGENT_RUN_ERROR_CODES,
   ALL_AGENTS,
   AgentBackendUnsupportedError,
   AgentChatTransport,
@@ -5706,6 +5756,7 @@ export {
   MessageItemView,
   MessageList,
   QuotaBlockedError,
+  RUN_NOT_ACTIVE_CODE,
   SPEECH_LANGUAGES,
   acceptsFile,
   applyCompletion,
@@ -5731,6 +5782,7 @@ export {
   groupToolActivity,
   inferResultView,
   isActionCall,
+  isRunNotActiveError,
   loadStoredSpeechLang,
   messageFiles,
   notifyThreads,