@dudousxd/nestjs-agent-react 0.23.0 → 0.25.0

package/README.md

@@ -38,7 +38,7 @@ 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. |
@@ -619,9 +619,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';