@dudousxd/nestjs-agent-react 0.27.0 → 0.29.0

package/README.md

@@ -37,8 +37,8 @@ handlers passed. On top of the AI SDK chat it returns:
 | On `chat` | What it is |
 |---|---|
 | `transcript` | `useChatTranscript` already bound to the chat — approve/reject/answer/skip, stop, fork, regenerate, the tool catalog, and timestamps/usage read from message metadata. Override any of it with `useAgentChat({ transcript: { … } })`. |
-| `composer` | `{ text, setText, files, canSend, blockedBy, submit() }` — `files` is `useAttachments` on the chat's backend; `submit()` sends the draft with the ready files attached and clears both — while a turn runs it QUEUES it (see *Typing ahead*); `blockedBy` is `'empty' \| 'busy' \| 'uploading' \| 'quota'` (`'busy'` only with `whileRunning: 'block'`). |
-| `queue` | `{ items, paused, isSupported, add(text, { attachments?, mode? }), remove(id), edit(id, text), move(id, index), clear(), resume(), error }` — messages sent mid-turn, waiting server-side for the running turn to settle. |
+| `composer` | `{ text, setText, files, canSend, blockedBy, submit() }` — `files` is `useAttachments` on the chat's backend; `submit()` sends the draft with the ready files attached and clears both — while a turn runs it QUEUES it (see *Typing ahead*), and `submit({ mode: 'interrupt' \| 'queue' })` picks what happens mid-turn for that one send; `blockedBy` is `'empty' \| 'busy' \| 'uploading' \| 'quota'` (`'busy'` only with `whileRunning: 'block'`). |
+| `queue` | `{ items, paused, isSupported, add(text, { attachments?, mode? }), remove(id), interrupt(id), edit(id, text), move(id, index), clear(), resume(), error }` — messages sent mid-turn, waiting server-side for the running turn to settle. |
 | `models` | `{ list, providers, selected, pinned, locked, select(id), pinToThread(id) }` — loaded the first time `list` is read. |
 | `quota` / `blocked` | `useQuota`'s state, and the window blocking sends (the `blocked` option overrides it). |
 | `approve` / `reject` / `answer` / `skip` | `({ toolCallId, … })` — the same object shape the transcript's handlers take. |
@@ -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
@@ -607,8 +647,21 @@ const chat = useAgentChat({ threadId });
 - `useAgentChat({ whileRunning })`: `'queue'` (default), `'interrupt'` (cancel the running turn and
   run this next), or `'block'` (refuse, `composer.blockedBy === 'busy'` — the old behaviour, also
   what a backend without `enqueueMessage` gets).
+- One send can answer differently from the chat's `whileRunning`: `composer.submit({ mode })` and
+  `sendMessage(message, { mode })` take `'queue'` or `'interrupt'` — a "send now" button next to a
+  plain send that queues. The composer clears its own draft and files either way; with nothing
+  running, `mode` means nothing and the message is simply sent. It also lifts `'block'` for that
+  send.
 - `chat.queue.edit(id, text)`, `move(id, index)`, `remove(id)`, `clear()` change what is waiting;
   `add(text, { attachments, mode })` queues from your own code.
+- `chat.queue.interrupt(id)` runs a message that is already waiting NOW: it moves to the head as an
+  interrupt and the running turn is cancelled for it, in one server call (the message keeps its id
+  and never leaves the queue — do not `remove` and `add` it again). With nothing running it starts
+  at once.
+- A waiting message's files have the shape a sent message's do: `chat.queue.items[n].files` is
+  `MessageFile[]` — what `messageFiles(message)` gives — and `chat.transcript.queued[n].files` is the
+  same plus `isImage`, so one file renderer draws both. `attachmentFile(attachment)` makes one from
+  an uploaded `MessageAttachment`.
 - The queue pauses behind a failed turn (`run_failed`), a Stop (`cancelled`) or an exhausted quota
   (`quota_exceeded`); `chat.queue.paused` says which, `resume()` lifts it. A queue left waiting with
   nothing running is started when the thread loads.

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

@@ -168,6 +168,16 @@ interface AgentBackend {
     updateQueuedMessage?(messageId: string, update: QueuedMessageUpdate): Promise<ChatQueueState>;
     /** `DELETE <base>/queue/:messageId`. */
     removeQueuedMessage?(messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/queue/:messageId/interrupt` — run a waiting message now: it moves to the head as an
+     * interrupt and the running turn is cancelled for it. `interrupting` is the run that was
+     * cancelled; `runId` is set instead when nothing was running and the message started at once.
+     * What `chat.queue.interrupt(id)` calls.
+     */
+    interruptQueuedMessage?(messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
     /** `DELETE <base>/threads/:id/queue`. */
     clearQueue?(threadId: string): Promise<ChatQueueState>;
     /** `POST <base>/threads/:id/queue/resume` — `runId` when the head started. */
@@ -313,6 +323,14 @@ declare class AgentClient implements AgentBackend {
     updateQueuedMessage(messageId: string, update: QueuedMessageUpdate): Promise<ChatQueueState>;
     /** `DELETE <path>/queue/:messageId`. */
     removeQueuedMessage(messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <path>/queue/:messageId/interrupt` — run a waiting message now, cancelling the running
+     * turn for it. `runId` when nothing was running and it started; else `interrupting`.
+     */
+    interruptQueuedMessage(messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
     /** `DELETE <path>/threads/:id/queue` — drop every waiting message. */
     clearQueue(threadId: string): Promise<ChatQueueState>;
     /** `POST <path>/threads/:id/queue/resume` — lift a pause; `runId` when the head started. */
@@ -418,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-DNM5Qm5N.d.ts → client-DhHEJi7c.d.ts}

@@ -168,6 +168,16 @@ interface AgentBackend {
     updateQueuedMessage?(messageId: string, update: QueuedMessageUpdate): Promise<ChatQueueState>;
     /** `DELETE <base>/queue/:messageId`. */
     removeQueuedMessage?(messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/queue/:messageId/interrupt` — run a waiting message now: it moves to the head as an
+     * interrupt and the running turn is cancelled for it. `interrupting` is the run that was
+     * cancelled; `runId` is set instead when nothing was running and the message started at once.
+     * What `chat.queue.interrupt(id)` calls.
+     */
+    interruptQueuedMessage?(messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
     /** `DELETE <base>/threads/:id/queue`. */
     clearQueue?(threadId: string): Promise<ChatQueueState>;
     /** `POST <base>/threads/:id/queue/resume` — `runId` when the head started. */
@@ -313,6 +323,14 @@ declare class AgentClient implements AgentBackend {
     updateQueuedMessage(messageId: string, update: QueuedMessageUpdate): Promise<ChatQueueState>;
     /** `DELETE <path>/queue/:messageId`. */
     removeQueuedMessage(messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <path>/queue/:messageId/interrupt` — run a waiting message now, cancelling the running
+     * turn for it. `runId` when nothing was running and it started; else `interrupting`.
+     */
+    interruptQueuedMessage(messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
     /** `DELETE <path>/threads/:id/queue` — drop every waiting message. */
     clearQueue(threadId: string): Promise<ChatQueueState>;
     /** `POST <path>/threads/:id/queue/resume` — lift a pause; `runId` when the head started. */
@@ -418,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. */