@dudousxd/nestjs-agent-react 0.24.0 → 0.26.0

package/README.md

@@ -38,11 +38,11 @@ handlers passed. On top of the AI SDK chat it returns:
 |---|---|
 | `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; `blockedBy` is `'empty' \| 'busy' \| 'uploading' \| 'quota'`. |
-| `models` | `{ list, providers, selected, select(id), pinToThread(id) }` — loaded the first time `list` is read. |
+| `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. |
 | `fork` / `truncateFrom` / `promote` | `({ messageId, threadId? })` / `({ threadId? })`, defaulting to this chat's thread. |
-| `cancel`, `regenerate`, `getThreadId`, `backend`, `runId`, `activeRunId`, `isLoadingHistory`, `connection`, `background` | — |
+| `cancel`, `regenerate`, `getThreadId`, `backend`, `runId`, `activeRunId`, `isLoadingHistory`, `connection`, `background` | — `isLoadingHistory` is already `true` on the first render with a `threadId`, so a page can show a skeleton instead of flashing its empty state |
 
 Threads (list, rename, delete) are `useThreads()`; the granular hooks stay the escape hatch.
 
@@ -170,6 +170,8 @@ catalog to the transcript and every tool call carries a `description`, and every
 ```tsx
 const chat = useAgentChat();
 const { catalog } = useToolCatalog(); // the provider's backend; `{ backend, agent }` to override
+// Several agents on one surface: every tool the actor reaches through any of them.
+const all = useToolCatalog({ agent: ALL_AGENTS }); // GET /agent/tools?agent=*
 const transcript = useChatTranscript({ messages: chat.messages, status: chat.status, toolCatalog: catalog });
 
 // in a `tools` block:
@@ -253,11 +255,19 @@ ones a human actually decided. A settled set keeps its block (`isPending: false`
 `selected` showing what was chosen), so one piece of markup renders both states.
 
 Detection is structural rather than by tool name — an intake and an `ask` persist under whatever
-name their row holds — and lifting is opt-in on `onAnswer` for the same reason `sources` is: with
-nowhere to send an answer, a question set is still just a tool card.
+name their row holds.
 
-**A tool call awaiting approval.** Wire `onApprove`/`onReject` and every call in a `tools` block
-carries its own decision:
+**Decisions settle through the backend by default.** `onApprove`, `onReject`, `onAnswer` and
+`onSkip` left undefined are NOT "off": each defaults to the in-scope backend's call (the enclosing
+`<AgentProvider>`'s `approveToolCall` / `rejectToolCall` / `answerToolCall` / `skipToolCall`), so a
+parked approval or question set is actionable with no wiring. Pass your own handler to route it
+elsewhere, `null` to drop one affordance (`onAnswer: null` keeps question sets as plain tool
+cards), or `readOnly: true` for a surface nobody acts on — an audit view, a shared or archived
+conversation. `readOnly` keeps parked approvals and question sets rendered (with their outcome)
+but offers no approve / reject / answer / skip, edit, fork, regenerate or stop, whatever is in
+scope; `<MessageList readOnly>` and `useAgentChat({ transcript: { readOnly: true } })` take it too.
+
+**A tool call awaiting approval.** Every call in a `tools` block carries its own decision:
 
 ```tsx
 {block.calls.map((call) => (
@@ -619,9 +629,12 @@ const { providers, selected, select } = chat.models; // loaded on first read
 
 `chat.models` reads `GET <base>/models?agent=` (models grouped by provider, with badges and
 availability; `list` is the same flattened) the first time `list`/`providers` is read. `select(id)`
-runs the following turns on it (sent as the body's `model`); `selected` is the pick, else the
-thread's pin, else the server default. `pinToThread(id)` pins it on the thread (`null` unpins) so
-it survives reloads — on a chat with no thread yet, the pin lands when the first send creates one.
+runs this chat's following sends on it (sent as the body's `model`, which the server applies to
+that turn only; switching threads drops the pick); `selected` is the pick, else the thread's pin
+(`pinned`), else the server default. `pinToThread(id)` pins it on the thread (`null` unpins) so it
+survives reloads, replacing the pick — on a chat with no thread yet, the pin lands when the first
+send creates one. `locked` (`{ model, reason? }`) is set when the agent always runs on one model:
+`selected` is then that model and `select` does nothing.
 `useAgentChat({ model })` controls the model yourself; a single send can override it with
 `sendMessage(msg, { body: { model } })`. `useModels()` / `useAgents()` are the standalone hooks
 (an agent picker: `useAgents().agents`, sent as `useAgentChat({ agent })`). The server refuses a

package/dist/{client-ioKDyV2q.d.cts → client-D4ZSbZJ8.d.cts}

@@ -1,5 +1,32 @@
 import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
 
+/**
+ * What a server said when it refused a request, read once so every error class of this package
+ * reports it the same way. Bundled into each entry that throws (the root and `/media`), which is
+ * why it holds no class of its own.
+ */
+interface ErrorAnswer {
+    /** The body, parsed as JSON when it is JSON, else the raw text; `undefined` when empty. */
+    body: unknown;
+    /** `body.message` — a string, or NestJS's list of validation messages joined with `; `. */
+    message: string | undefined;
+    /** `body.code`, the machine-readable reason (`quota_exceeded`, …), when the server sent one. */
+    code: string | undefined;
+}
+/**
+ * The shape both {@link import('./client.js').AgentHttpError} and `MediaUploadError` share, for
+ * code that handles either without an `instanceof` (the two live in separate bundles).
+ */
+interface AgentRequestError extends Error {
+    status: number;
+    method: string;
+    path: string;
+    body: unknown;
+    code: string | undefined;
+}
+/** Called with every error answer before it is thrown — for app-wide reactions (401, 402, …). */
+type HttpErrorListener = (error: AgentRequestError) => void;
+
 /**
  * Partial update accepted by `PATCH <base>/threads/:threadId`. `defaultAgent: null` clears a
  * previously-set default back to the module's own default; omitting it leaves the thread's
@@ -62,6 +89,8 @@ interface AgentConnection {
     headers: () => Promise<Record<string, string>>;
     credentials?: RequestCredentials;
     fetch: typeof fetch;
+    /** The client's `onHttpError` — call it with an upload's error answer before throwing it. */
+    onHttpError?: HttpErrorListener;
 }
 /**
  * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <path>/attachments`) — e.g.
@@ -110,9 +139,11 @@ interface AgentBackend {
     answerToolCall?(input: {
         toolCallId: string;
         answers?: Record<string, string[]>;
+        via?: string;
     }): Promise<unknown>;
     skipToolCall?(input: {
         toolCallId: string;
+        via?: string;
     }): Promise<unknown>;
     uploadAttachment?(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
     listTools?(agent?: string): Promise<ToolCatalogEntry[]>;
@@ -145,13 +176,22 @@ declare function requireBackendMethod<K extends OptionalMethod>(backend: AgentBa
 
 /**
  * Thrown by {@link AgentClient} on a non-2xx response. Carries the HTTP `status` so callers can
- * branch (e.g. 403 → "not your thread", 429 → quota) instead of string-matching a generic Error.
+ * branch (e.g. 403 → "not your thread", 429 → quota) instead of string-matching a generic Error,
+ * and what the server said: `message` is the body's `message` when it sent one (so a hook that
+ * shows `error.message` shows the server's words), `code` its machine-readable `code`, and `body`
+ * the whole answer, parsed when it is JSON.
  */
-declare class AgentHttpError extends Error {
+declare class AgentHttpError extends Error implements AgentRequestError {
     readonly status: number;
     readonly method: string;
     readonly path: string;
-    constructor(status: number, method: string, path: string, statusText: string);
+    /** The answer's body: parsed JSON, else its text; `undefined` when empty. */
+    readonly body: unknown;
+    /** The body's `code` (`quota_exceeded`, …), when the server sent one. */
+    readonly code: string | undefined;
+    constructor(status: number, method: string, path: string, statusText: string, answer?: ErrorAnswer);
+    /** Read a refused `response`'s body into an error. */
+    static from(response: Response, method: string, path: string): Promise<AgentHttpError>;
 }
 interface CancelResult {
     aborted: boolean;
@@ -185,6 +225,13 @@ interface AgentClientOptions {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
+    /**
+     * Called with every error answer (an {@link AgentHttpError}, or a `MediaUploadError` from a
+     * `mediaAttachments()` upload) right before it is thrown — the place for app-wide reactions such
+     * as "401 → sign in again". The error still reaches the caller. Not called for the `404` a
+     * resume answers when nothing is streaming, which is an answer, not a failure.
+     */
+    onHttpError?: HttpErrorListener;
     /** Attachment uploads. */
     attachments?: {
         /**
@@ -272,10 +319,12 @@ declare class AgentClient implements AgentBackend {
      * out takes the pre-picked default the request carried, resolved server-side against the request
      * the run already holds. Omit the whole object and the user has confirmed every pre-picked
      * answer — which is the point of the surface, so it is a valid submission rather than a blank.
+     * `via` names the surface the answer came through (the server records `'web'` when omitted).
      */
     answerToolCall(input: {
         toolCallId: string;
         answers?: Record<string, string[]>;
+        via?: string;
     }): Promise<void>;
     /**
      * Decline to answer and let the agent proceed on its own pre-picked values. Lands on the same
@@ -284,6 +333,7 @@ declare class AgentClient implements AgentBackend {
      */
     skipToolCall(input: {
         toolCallId: string;
+        via?: string;
     }): Promise<void>;
     private fetchImpl;
     /** This client's connection, for an {@link AttachmentUploadStrategy}. */
@@ -295,7 +345,9 @@ declare class AgentClient implements AgentBackend {
     private resolveHeaders;
     private credentials;
     private request;
+    /** The error for a refused `response`, already reported to `onHttpError`. */
+    private failure;
     private handleResponse;
 }
 
-export { type AgentBackend as A, type CancelResult as C, type MessageFeedbackInput as M, 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 ChatStreamRequest as g, type ChatStreamResponse as h, requireBackendMethod as r };
+export { type AgentBackend as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, 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, requireBackendMethod as r };

package/dist/{client-ioKDyV2q.d.ts → client-D4ZSbZJ8.d.ts}

@@ -1,5 +1,32 @@
 import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
 
+/**
+ * What a server said when it refused a request, read once so every error class of this package
+ * reports it the same way. Bundled into each entry that throws (the root and `/media`), which is
+ * why it holds no class of its own.
+ */
+interface ErrorAnswer {
+    /** The body, parsed as JSON when it is JSON, else the raw text; `undefined` when empty. */
+    body: unknown;
+    /** `body.message` — a string, or NestJS's list of validation messages joined with `; `. */
+    message: string | undefined;
+    /** `body.code`, the machine-readable reason (`quota_exceeded`, …), when the server sent one. */
+    code: string | undefined;
+}
+/**
+ * The shape both {@link import('./client.js').AgentHttpError} and `MediaUploadError` share, for
+ * code that handles either without an `instanceof` (the two live in separate bundles).
+ */
+interface AgentRequestError extends Error {
+    status: number;
+    method: string;
+    path: string;
+    body: unknown;
+    code: string | undefined;
+}
+/** Called with every error answer before it is thrown — for app-wide reactions (401, 402, …). */
+type HttpErrorListener = (error: AgentRequestError) => void;
+
 /**
  * Partial update accepted by `PATCH <base>/threads/:threadId`. `defaultAgent: null` clears a
  * previously-set default back to the module's own default; omitting it leaves the thread's
@@ -62,6 +89,8 @@ interface AgentConnection {
     headers: () => Promise<Record<string, string>>;
     credentials?: RequestCredentials;
     fetch: typeof fetch;
+    /** The client's `onHttpError` — call it with an upload's error answer before throwing it. */
+    onHttpError?: HttpErrorListener;
 }
 /**
  * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <path>/attachments`) — e.g.
@@ -110,9 +139,11 @@ interface AgentBackend {
     answerToolCall?(input: {
         toolCallId: string;
         answers?: Record<string, string[]>;
+        via?: string;
     }): Promise<unknown>;
     skipToolCall?(input: {
         toolCallId: string;
+        via?: string;
     }): Promise<unknown>;
     uploadAttachment?(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
     listTools?(agent?: string): Promise<ToolCatalogEntry[]>;
@@ -145,13 +176,22 @@ declare function requireBackendMethod<K extends OptionalMethod>(backend: AgentBa
 
 /**
  * Thrown by {@link AgentClient} on a non-2xx response. Carries the HTTP `status` so callers can
- * branch (e.g. 403 → "not your thread", 429 → quota) instead of string-matching a generic Error.
+ * branch (e.g. 403 → "not your thread", 429 → quota) instead of string-matching a generic Error,
+ * and what the server said: `message` is the body's `message` when it sent one (so a hook that
+ * shows `error.message` shows the server's words), `code` its machine-readable `code`, and `body`
+ * the whole answer, parsed when it is JSON.
  */
-declare class AgentHttpError extends Error {
+declare class AgentHttpError extends Error implements AgentRequestError {
     readonly status: number;
     readonly method: string;
     readonly path: string;
-    constructor(status: number, method: string, path: string, statusText: string);
+    /** The answer's body: parsed JSON, else its text; `undefined` when empty. */
+    readonly body: unknown;
+    /** The body's `code` (`quota_exceeded`, …), when the server sent one. */
+    readonly code: string | undefined;
+    constructor(status: number, method: string, path: string, statusText: string, answer?: ErrorAnswer);
+    /** Read a refused `response`'s body into an error. */
+    static from(response: Response, method: string, path: string): Promise<AgentHttpError>;
 }
 interface CancelResult {
     aborted: boolean;
@@ -185,6 +225,13 @@ interface AgentClientOptions {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
+    /**
+     * Called with every error answer (an {@link AgentHttpError}, or a `MediaUploadError` from a
+     * `mediaAttachments()` upload) right before it is thrown — the place for app-wide reactions such
+     * as "401 → sign in again". The error still reaches the caller. Not called for the `404` a
+     * resume answers when nothing is streaming, which is an answer, not a failure.
+     */
+    onHttpError?: HttpErrorListener;
     /** Attachment uploads. */
     attachments?: {
         /**
@@ -272,10 +319,12 @@ declare class AgentClient implements AgentBackend {
      * out takes the pre-picked default the request carried, resolved server-side against the request
      * the run already holds. Omit the whole object and the user has confirmed every pre-picked
      * answer — which is the point of the surface, so it is a valid submission rather than a blank.
+     * `via` names the surface the answer came through (the server records `'web'` when omitted).
      */
     answerToolCall(input: {
         toolCallId: string;
         answers?: Record<string, string[]>;
+        via?: string;
     }): Promise<void>;
     /**
      * Decline to answer and let the agent proceed on its own pre-picked values. Lands on the same
@@ -284,6 +333,7 @@ declare class AgentClient implements AgentBackend {
      */
     skipToolCall(input: {
         toolCallId: string;
+        via?: string;
     }): Promise<void>;
     private fetchImpl;
     /** This client's connection, for an {@link AttachmentUploadStrategy}. */
@@ -295,7 +345,9 @@ declare class AgentClient implements AgentBackend {
     private resolveHeaders;
     private credentials;
     private request;
+    /** The error for a refused `response`, already reported to `onHttpError`. */
+    private failure;
     private handleResponse;
 }
 
-export { type AgentBackend as A, type CancelResult as C, type MessageFeedbackInput as M, 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 ChatStreamRequest as g, type ChatStreamResponse as h, requireBackendMethod as r };
+export { type AgentBackend as A, type CancelResult as C, type ErrorAnswer as E, type HttpErrorListener as H, type MessageFeedbackInput as M, 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, requireBackendMethod as r };

package/dist/{generative-ui-9AJNVKBZ.d.cts → generative-ui-BejHxxbR.d.cts}

@@ -427,6 +427,10 @@ interface TranscriptElicitationOutcome {
     defaulted: string[];
     /** The questions against the chosen labels, as the model read them back. */
     summary: string | null;
+    /** Who answered (or skipped) — an approval's `decidedBy`. `null` when the run did not record it. */
+    answeredBy: string | null;
+    /** The surface it came through (`'web'`, `'slack'`, …) — an approval's `decidedVia`. */
+    answeredVia: string | null;
 }
 /**
  * A question set the run put to the user, parked until someone settles it — the intake an agent

package/dist/{generative-ui-9AJNVKBZ.d.ts → generative-ui-BejHxxbR.d.ts}

@@ -427,6 +427,10 @@ interface TranscriptElicitationOutcome {
     defaulted: string[];
     /** The questions against the chosen labels, as the model read them back. */
     summary: string | null;
+    /** Who answered (or skipped) — an approval's `decidedBy`. `null` when the run did not record it. */
+    answeredBy: string | null;
+    /** The surface it came through (`'web'`, `'slack'`, …) — an approval's `decidedVia`. */
+    answeredVia: string | null;
 }
 /**
  * A question set the run put to the user, parked until someone settles it — the intake an agent

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-9AJNVKBZ.cjs';
+import { n as GenuiProviderProps$1, c as GenerativeUIElement, q as GenuiRenderer, p as GenuiRegistry } from './generative-ui-BejHxxbR.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-9AJNVKBZ.js';
+import { n as GenuiProviderProps$1, c as GenerativeUIElement, q as GenuiRenderer, p as GenuiRegistry } from './generative-ui-BejHxxbR.js';
 import '@dudousxd/nestjs-agent-core';
 import 'ai';
 

package/dist/genui.d.cts

@@ -1,5 +1,5 @@
-import { G as GenerativeUIItem } from './generative-ui-9AJNVKBZ.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-9AJNVKBZ.cjs';
+import { G as GenerativeUIItem } from './generative-ui-BejHxxbR.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-BejHxxbR.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-9AJNVKBZ.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-9AJNVKBZ.js';
+import { G as GenerativeUIItem } from './generative-ui-BejHxxbR.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-BejHxxbR.js';
 import 'react';
 import '@dudousxd/nestjs-agent-core';
 import 'ai';