@dudousxd/nestjs-agent-react 0.28.0 → 0.29.0

package/README.md

@@ -305,6 +305,46 @@ A refused settlement (403 "not your thread" or "not your approval", 410 "expired
 `call.error` with the affordance still live, rather than escaping as an unhandled rejection. Render
 it — a button that silently does nothing is indistinguishable from a broken one.
 
+### When a run fails
+
+The server closes a failed run's stream with `event: error` + `{ code, message }`. `chat.error`
+carries the message; `chat.runError` carries the whole frame — `{ code, message, runId? }`, `null`
+again once the next attempt starts — so the app words each failure itself. The library renders
+nothing for it:
+
+```tsx
+import { isRunNotActiveError } from '@dudousxd/nestjs-agent-react';
+
+const FRIENDLY: Record<string, string> = {
+  replay_diverged: 'This answer was interrupted by an update. Send your message again.',
+  model_no_output: 'The model returned nothing. Try again.',
+  run_failed: 'Something went wrong on our side. Try again.',
+};
+
+{chat.runError && <p role="alert">{FRIENDLY[chat.runError.code ?? ''] ?? chat.runError.message}</p>}
+```
+
+`AGENT_RUN_ERROR_CODES` lists the codes this library's loop sends (`quota_exceeded`,
+`output_rejected`, `structured_output_invalid`, `replay_diverged`, `model_no_output`, `run_failed`).
+In production the `message` of the last three is one generic sentence — the error itself stays in
+the server's log.
+
+A failed turn leaves its thread usable: the next send starts a new turn. What it cannot do is
+answer a card the dead turn left on screen. `approve` / `reject` / `answer` / `skip` on one reject
+with an `AgentHttpError` whose `status` is `409` and `code` is `run_not_active`:
+
+```tsx
+try {
+  await chat.approve({ toolCallId });
+} catch (error) {
+  if (isRunNotActiveError(error)) showStale('This request expired with its turn — send it again.');
+  else throw error;
+}
+```
+
+On the transcript model the same refusal is `call.errorCode === 'run_not_active'` (and
+`elicitation.errorCode`) next to `call.error`, the server's message.
+
 ### Completing as you type
 
 `useComposerAutocomplete` is the state machine behind a `/`-style menu in the composer. It is

package/dist/{client-CKwSMitS.d.cts → client-DhHEJi7c.d.cts}

@@ -436,4 +436,4 @@ declare class AgentClient implements AgentBackend {
     private handleResponse;
 }
 
-export { type AgentBackend as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AttachmentUploadStrategy as a, AgentBackendUnsupportedError as b, AgentClient as c, type AgentClientOptions as d, type AgentConnection as e, AgentHttpError as f, type AgentRequestError as g, type ChatStreamRequest as h, type ChatStreamResponse as i, type QueuedSendResult as j, requireBackendMethod as r };
+export { type AgentRequestError as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AgentBackend as a, type AttachmentUploadStrategy as b, AgentBackendUnsupportedError as c, AgentClient as d, type AgentClientOptions as e, type AgentConnection as f, AgentHttpError as g, type ChatStreamRequest as h, type ChatStreamResponse as i, type QueuedSendResult as j, requireBackendMethod as r };

package/dist/{client-CKwSMitS.d.ts → client-DhHEJi7c.d.ts}

@@ -436,4 +436,4 @@ declare class AgentClient implements AgentBackend {
     private handleResponse;
 }
 
-export { type AgentBackend as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AttachmentUploadStrategy as a, AgentBackendUnsupportedError as b, AgentClient as c, type AgentClientOptions as d, type AgentConnection as e, AgentHttpError as f, type AgentRequestError as g, type ChatStreamRequest as h, type ChatStreamResponse as i, type QueuedSendResult as j, requireBackendMethod as r };
+export { type AgentRequestError as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, type QueuedMessageUpdate as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, type AgentBackend as a, type AttachmentUploadStrategy as b, AgentBackendUnsupportedError as c, AgentClient as d, type AgentClientOptions as e, type AgentConnection as f, AgentHttpError as g, type ChatStreamRequest as h, type ChatStreamResponse as i, type QueuedSendResult as j, requireBackendMethod as r };

package/dist/{generative-ui-jT9TYfCi.d.cts → generative-ui-VTZ1EADD.d.cts}

@@ -329,6 +329,12 @@ interface TranscriptToolCall {
     reject: TranscriptSettleState;
     /** A failed decision — the call is still parked, so the affordance stays live. */
     error: string | null;
+    /**
+     * The server's machine-readable reason for {@link error}, when it gave one. `run_not_active`
+     * means the turn that asked has ended: nothing is waiting for the decision, and pressing again
+     * will be refused again — word it yourself and let the person send the message again.
+     */
+    errorCode: string | null;
 }
 /**
  * A run of CONSECUTIVE tool parts, grouped so a UI can collapse "5 tools ran" into one affordance.
@@ -452,6 +458,8 @@ interface TranscriptElicitationBlock {
     outcome: TranscriptElicitationOutcome | null;
     /** A failed submission — the run is still parked, so the form stays live. */
     error: string | null;
+    /** The server's machine-readable reason for {@link error} (`run_not_active`, …), when it gave one. */
+    errorCode: string | null;
     answer: TranscriptSettleState;
     skip: TranscriptSettleState;
 }
@@ -501,6 +509,8 @@ interface ElicitationBlockOptions {
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
+    /** The `code` of the error `errorOf` reports, when the server sent one. */
+    errorCodeOf?: (toolCallId: string) => string | null;
 }
 /** Where an approval decision is sent, and what the last one did. */
 interface ApprovalBlockOptions {
@@ -511,6 +521,8 @@ interface ApprovalBlockOptions {
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
+    /** The `code` of the error `errorOf` reports, when the server sent one. */
+    errorCodeOf?: (toolCallId: string) => string | null;
 }
 interface BuildBlocksOptions {
     /** Disclosure lookup for a reasoning run; `isStreaming` is the fallback when untouched. */

package/dist/{generative-ui-jT9TYfCi.d.ts → generative-ui-VTZ1EADD.d.ts}

@@ -329,6 +329,12 @@ interface TranscriptToolCall {
     reject: TranscriptSettleState;
     /** A failed decision — the call is still parked, so the affordance stays live. */
     error: string | null;
+    /**
+     * The server's machine-readable reason for {@link error}, when it gave one. `run_not_active`
+     * means the turn that asked has ended: nothing is waiting for the decision, and pressing again
+     * will be refused again — word it yourself and let the person send the message again.
+     */
+    errorCode: string | null;
 }
 /**
  * A run of CONSECUTIVE tool parts, grouped so a UI can collapse "5 tools ran" into one affordance.
@@ -452,6 +458,8 @@ interface TranscriptElicitationBlock {
     outcome: TranscriptElicitationOutcome | null;
     /** A failed submission — the run is still parked, so the form stays live. */
     error: string | null;
+    /** The server's machine-readable reason for {@link error} (`run_not_active`, …), when it gave one. */
+    errorCode: string | null;
     answer: TranscriptSettleState;
     skip: TranscriptSettleState;
 }
@@ -501,6 +509,8 @@ interface ElicitationBlockOptions {
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
+    /** The `code` of the error `errorOf` reports, when the server sent one. */
+    errorCodeOf?: (toolCallId: string) => string | null;
 }
 /** Where an approval decision is sent, and what the last one did. */
 interface ApprovalBlockOptions {
@@ -511,6 +521,8 @@ interface ApprovalBlockOptions {
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
+    /** The `code` of the error `errorOf` reports, when the server sent one. */
+    errorCodeOf?: (toolCallId: string) => string | null;
 }
 interface BuildBlocksOptions {
     /** Disclosure lookup for a reasoning run; `isStreaming` is the fallback when untouched. */

package/dist/genui-json-render.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { ComponentRegistry } from '@json-render/react';
-import { n as GenuiProviderProps$1, c as GenerativeUIElement, q as GenuiRenderer, p as GenuiRegistry } from './generative-ui-jT9TYfCi.cjs';
+import { n as GenuiProviderProps$1, c as GenerativeUIElement, q as GenuiRenderer, p as GenuiRegistry } from './generative-ui-VTZ1EADD.cjs';
 import '@dudousxd/nestjs-agent-core';
 import 'ai';
 

package/dist/genui-json-render.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { ComponentRegistry } from '@json-render/react';
-import { n as GenuiProviderProps$1, c as GenerativeUIElement, q as GenuiRenderer, p as GenuiRegistry } from './generative-ui-jT9TYfCi.js';
+import { n as GenuiProviderProps$1, c as GenerativeUIElement, q as GenuiRenderer, p as GenuiRegistry } from './generative-ui-VTZ1EADD.js';
 import '@dudousxd/nestjs-agent-core';
 import 'ai';
 

package/dist/genui.d.cts

@@ -1,5 +1,5 @@
-import { G as GenerativeUIItem } from './generative-ui-jT9TYfCi.cjs';
-export { a as GENUI_TREE_COMPONENT, b as GenerativeUI, c as GenerativeUIElement, d as GenerativeUIFallback, e as GenerativeUIOptions, f as GenerativeUIProblem, g as GenerativeUIProps, h as GenerativeUIScope, i as GenerativeUIScopeProps, j as GenerativeUIState, k as GenuiCatalogLike, l as GenuiIssueLike, m as GenuiProvider, n as GenuiProviderProps, o as GenuiProviderValue, p as GenuiRegistry, q as GenuiRenderer, r as GenuiTree, R as ResolveComponent, u as useGenerativeUI, s as useGenuiProvider } from './generative-ui-jT9TYfCi.cjs';
+import { G as GenerativeUIItem } from './generative-ui-VTZ1EADD.cjs';
+export { a as GENUI_TREE_COMPONENT, b as GenerativeUI, c as GenerativeUIElement, d as GenerativeUIFallback, e as GenerativeUIOptions, f as GenerativeUIProblem, g as GenerativeUIProps, h as GenerativeUIScope, i as GenerativeUIScopeProps, j as GenerativeUIState, k as GenuiCatalogLike, l as GenuiIssueLike, m as GenuiProvider, n as GenuiProviderProps, o as GenuiProviderValue, p as GenuiRegistry, q as GenuiRenderer, r as GenuiTree, R as ResolveComponent, u as useGenerativeUI, s as useGenuiProvider } from './generative-ui-VTZ1EADD.cjs';
 import 'react';
 import '@dudousxd/nestjs-agent-core';
 import 'ai';

package/dist/genui.d.ts

@@ -1,5 +1,5 @@
-import { G as GenerativeUIItem } from './generative-ui-jT9TYfCi.js';
-export { a as GENUI_TREE_COMPONENT, b as GenerativeUI, c as GenerativeUIElement, d as GenerativeUIFallback, e as GenerativeUIOptions, f as GenerativeUIProblem, g as GenerativeUIProps, h as GenerativeUIScope, i as GenerativeUIScopeProps, j as GenerativeUIState, k as GenuiCatalogLike, l as GenuiIssueLike, m as GenuiProvider, n as GenuiProviderProps, o as GenuiProviderValue, p as GenuiRegistry, q as GenuiRenderer, r as GenuiTree, R as ResolveComponent, u as useGenerativeUI, s as useGenuiProvider } from './generative-ui-jT9TYfCi.js';
+import { G as GenerativeUIItem } from './generative-ui-VTZ1EADD.js';
+export { a as GENUI_TREE_COMPONENT, b as GenerativeUI, c as GenerativeUIElement, d as GenerativeUIFallback, e as GenerativeUIOptions, f as GenerativeUIProblem, g as GenerativeUIProps, h as GenerativeUIScope, i as GenerativeUIScopeProps, j as GenerativeUIState, k as GenuiCatalogLike, l as GenuiIssueLike, m as GenuiProvider, n as GenuiProviderProps, o as GenuiProviderValue, p as GenuiRegistry, q as GenuiRenderer, r as GenuiTree, R as ResolveComponent, u as useGenerativeUI, s as useGenuiProvider } from './generative-ui-VTZ1EADD.js';
 import 'react';
 import '@dudousxd/nestjs-agent-core';
 import 'ai';

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AGENT_RUN_ERROR_CODES: () => AGENT_RUN_ERROR_CODES,
   ALL_AGENTS: () => import_nestjs_agent_core4.ALL_AGENTS,
   AgentBackendUnsupportedError: () => AgentBackendUnsupportedError,
   AgentChatTransport: () => AgentChatTransport,
@@ -43,6 +44,7 @@ __export(src_exports, {
   MessageItemView: () => MessageItemView,
   MessageList: () => MessageList,
   QuotaBlockedError: () => QuotaBlockedError,
+  RUN_NOT_ACTIVE_CODE: () => RUN_NOT_ACTIVE_CODE,
   SPEECH_LANGUAGES: () => SPEECH_LANGUAGES,
   acceptsFile: () => acceptsFile,
   applyCompletion: () => applyCompletion,
@@ -68,6 +70,7 @@ __export(src_exports, {
   groupToolActivity: () => groupToolActivity,
   inferResultView: () => inferResultView,
   isActionCall: () => isActionCall,
+  isRunNotActiveError: () => isRunNotActiveError,
   loadStoredSpeechLang: () => loadStoredSpeechLang,
   messageFiles: () => messageFiles,
   notifyThreads: () => notifyThreads,
@@ -722,6 +725,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 () => {
@@ -1046,7 +1058,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") {
@@ -1113,16 +1127,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 {
@@ -2958,7 +2977,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) {
@@ -3089,6 +3109,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",
@@ -3557,10 +3578,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 {
@@ -3741,7 +3762,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 ? {
@@ -3751,7 +3773,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
           }
         } : {}
       }),
@@ -3871,6 +3894,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
 var import_jsx_runtime4 = require("react/jsx-runtime");
@@ -4940,6 +4967,7 @@ function useAgentChat(options = {}) {
   const [activeRunId, setActiveRunId] = (0, import_react23.useState)(null);
   const [historyFor, setHistoryFor] = (0, import_react23.useState)(void 0);
   const [historyError, setHistoryError] = (0, import_react23.useState)(null);
+  const [runError, setRunError] = (0, import_react23.useState)(null);
   const [threadModel, setThreadModel] = (0, import_react23.useState)(null);
   const [pickedModel, setPickedModel] = (0, import_react23.useState)(void 0);
   const pickedModelRef = (0, import_react23.useRef)(pickedModel);
@@ -5015,7 +5043,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();
@@ -5134,6 +5164,7 @@ function useAgentChat(options = {}) {
     setPickedModel(void 0);
     setBackgroundRuns([]);
     setHistoryError(null);
+    setRunError(null);
     autoResumeRunIdRef.current = void 0;
     pendingPin.current = void 0;
     applyQueue(EMPTY_QUEUE);
@@ -5737,6 +5768,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.
@@ -5778,8 +5816,23 @@ 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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENT_RUN_ERROR_CODES,
   ALL_AGENTS,
   AgentBackendUnsupportedError,
   AgentChatTransport,
@@ -5793,6 +5846,7 @@ var QuotaBlockedError = class extends Error {
   MessageItemView,
   MessageList,
   QuotaBlockedError,
+  RUN_NOT_ACTIVE_CODE,
   SPEECH_LANGUAGES,
   acceptsFile,
   applyCompletion,
@@ -5818,6 +5872,7 @@ var QuotaBlockedError = class extends Error {
   groupToolActivity,
   inferResultView,
   isActionCall,
+  isRunNotActiveError,
   loadStoredSpeechLang,
   messageFiles,
   notifyThreads,