@dudousxd/nestjs-agent-react 0.20.0 → 0.21.0

package/README.md

@@ -19,10 +19,7 @@ pnpm add @dudousxd/nestjs-agent-react @ai-sdk/react ai react
 import { useAgentChat, MessageList, ChatInput } from '@dudousxd/nestjs-agent-react';
 
 function Chat() {
-  const chat = useAgentChat({
-    baseUrl: '/agent',
-    getHeaders: () => ({ 'x-actor-id': me.id, 'x-actor-role': me.roles.join(',') }),
-  });
+  const chat = useAgentChat(); // same-origin, `/agent` — no provider needed
   return (
     <>
       <MessageList
@@ -37,6 +34,31 @@ function Chat() {
 }
 ```
 
+### Configure the connection once: `<AgentProvider>`
+
+Every hook (`useAgentChat`, `useThreads`, `useModels`, `useAgents`, `useQuota`, `useToolCatalog`,
+`useMessageFeedback`, `useAttachments`) talks to the enclosing provider's backend unless handed a
+`backend` of its own. Without a provider they share one same-origin client on `/agent`.
+
+```tsx
+import { AgentProvider } from '@dudousxd/nestjs-agent-react';
+import { mediaAttachments } from '@dudousxd/nestjs-agent-react/media';
+
+<AgentProvider
+  baseUrl="https://api.example.com" // origin only; default '' (same origin)
+  path="api/agent"                  // AgentModule's `path` + global prefix; default 'agent'
+  credentials="include"
+  getHeaders={() => ({ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') })}
+  attachments={{ upload: mediaAttachments() }} // optional
+  genui={{ registry, catalog }}                // optional — same props as <GenuiProvider>
+>
+  <App />
+</AgentProvider>
+```
+
+`<AgentProvider backend={myBackend}>` takes any `AgentBackend` instead of the connection props.
+`useAgentBackend()` returns the backend in scope, for your own calls.
+
 ## Bring your own UI
 
 The package is **headless by design**, in four layers, and only the top one renders anything:
@@ -58,7 +80,7 @@ tool grouping, the edit machine, or the copy flash, and it never imports `Messag
 import { useAgentChat, useChatTranscript } from '@dudousxd/nestjs-agent-react';
 
 function Chat() {
-  const chat = useAgentChat({ baseUrl: '/agent' });
+  const chat = useAgentChat();
   const transcript = useChatTranscript({
     messages: chat.messages,
     status: chat.status,
@@ -134,8 +156,8 @@ catalog to the transcript and every tool call carries a `description`, and every
 `activity` grouping:
 
 ```tsx
-const chat = useAgentChat({ baseUrl: '/agent' });
-const { catalog } = useToolCatalog({ client: chat.client });
+const chat = useAgentChat();
+const { catalog } = useToolCatalog(); // the provider's backend; `{ backend, agent }` to override
 const transcript = useChatTranscript({ messages: chat.messages, status: chat.status, toolCatalog: catalog });
 
 // in a `tools` block:
@@ -330,11 +352,11 @@ the model, so a `/` menu and the agent's own reach cannot drift apart:
 ```tsx
 import { createSkillsSource, useAgentChat } from '@dudousxd/nestjs-agent-react';
 
-const chat = useAgentChat({ baseUrl: '/agent', onThreadCreated: setThreadId });
+const chat = useAgentChat({ onThreadCreated: setThreadId });
 // Identity-stable so the list is read once per thread, not once per keystroke.
 const sources = useMemo(
-  () => [createSkillsSource({ client: chat.client, getThreadId: () => threadId })],
-  [chat.client],
+  () => [createSkillsSource({ backend: chat.backend, getThreadId: () => threadId })],
+  [chat.backend],
 );
 ```
 
@@ -420,14 +442,12 @@ import { isTextUIPart, isToolUIPart } from 'ai';
 
 function CustomChat({ threadId }: { threadId?: string }) {
   const chat = useAgentChat({
-    baseUrl: '/agent',
     // Omit the key entirely when absent — `UseAgentChatOptions` is built with
     // `exactOptionalPropertyTypes`, so an explicit `threadId: undefined` doesn't type-check.
     ...(threadId !== undefined ? { threadId } : {}),
     agent: 'support',
     // Reattach to a turn still streaming when the page loaded — survives a refresh.
     resume: true,
-    getHeaders: () => ({ 'x-actor-id': currentUser.id }),
     onThreadCreated: (newThreadId) => router.replace(`/chat/${newThreadId}`),
     // Fires once per run when the SERVER is done writing (title + terminal state persisted) —
     // the right signal to refetch a thread list/sidebar; `onFinish` only means "a turn rendered".
@@ -517,7 +537,8 @@ const backend: AgentBackend = {
   setMessageFeedback: (id, input) => api.messages.feedback(id, input),
 };
 
-const chat = useAgentChat({ backend }); // chat.backend === backend, typed as yours
+<AgentProvider backend={backend}>…</AgentProvider>; // every hook below uses it
+const chat = useAgentChat({ backend }); // or per hook — chat.backend === backend, typed as yours
 ```
 
 Calling a hook method whose optional backend member is missing throws
@@ -528,15 +549,17 @@ attachments?, pageContext?, regenerate? }`; the SSE it returns and the REST shap
 **Cookie session + CSRF with the default client.** `credentials` and `getHeaders` are all it takes —
 `getHeaders` runs per request, so a rotated token is picked up:
 
-```ts
+```tsx
 const readCookie = (name: string) =>
   decodeURIComponent(document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`))?.[1] ?? '');
 
-useAgentChat({
-  baseUrl: '/api',
-  credentials: 'include', // 'same-origin' (the fetch default) is enough when the API is same-origin
-  getHeaders: () => ({ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }),
-});
+<AgentProvider
+  path="api/agent"
+  credentials="include" // 'same-origin' (the fetch default) is enough when the API is same-origin
+  getHeaders={() => ({ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') })}
+>
+  <App />
+</AgentProvider>;
 ```
 
 ### Reconnecting a dropped stream
@@ -554,8 +577,8 @@ the last failed attempt the turn ends with an error.
 ```tsx
 import { useMessageFeedback, useThreads } from '@dudousxd/nestjs-agent-react';
 
-const { threads, isLoading, rename, remove, refresh } = useThreads({ backend: chat.backend });
-const feedback = useMessageFeedback({ backend: chat.backend, threadId: chat.getThreadId });
+const { threads, isLoading, rename, remove, refresh } = useThreads();
+const feedback = useMessageFeedback({ threadId: chat.getThreadId });
 
 <button aria-pressed={feedback.feedbackOf(message)?.value === 'up'}
         onClick={() => feedback.toggle(message, 'up')}>Helpful</button>
@@ -573,9 +596,9 @@ its run persisted (the live message carries `metadata.runId`).
 import { useAgents, useModels } from '@dudousxd/nestjs-agent-react';
 
 const [model, setModel] = useState<string | undefined>();
-const chat = useAgentChat({ backend, model }); // sent as the body's `model` on every turn
-const { providers, find, defaultModel } = useModels({ backend: chat.backend, agent: 'support' });
-const { agents } = useAgents({ backend: chat.backend });
+const chat = useAgentChat({ model }); // sent as the body's `model` on every turn
+const { providers, find, defaultModel } = useModels({ agent: 'support' });
+const { agents } = useAgents();
 
 <select value={model ?? defaultModel ?? ''} onChange={(e) => setModel(e.target.value)}>
   {providers.map((p) => (
@@ -601,8 +624,8 @@ model its catalog does not offer as available.
 ```tsx
 import { QuotaBlockedError, useQuota } from '@dudousxd/nestjs-agent-react';
 
-const quota = useQuota({ backend });                // GET <base>/quota
-const chat = useAgentChat({ backend, blocked: quota.blocked });
+const quota = useQuota();                           // GET <base>/quota
+const chat = useAgentChat({ blocked: quota.blocked });
 
 <meter value={quota.month?.usedUsd} max={quota.month?.limitUsd} />
 {quota.blocked ? <p>{quota.blocked.reason}</p> : null}
@@ -623,7 +646,7 @@ import { useChat } from '@ai-sdk/react';
 import { AgentChatTransport } from '@dudousxd/nestjs-agent-react';
 
 const transport = new AgentChatTransport({
-  baseUrl: '/agent',
+  path: 'agent', // the default
   getHeaders: () => ({ 'x-actor-id': currentUser.id }),
   onMeta: ({ runId, threadId }) => console.log('turn started', runId, threadId),
 });
@@ -653,7 +676,7 @@ before it can seed `useChat`'s `initialMessages`:
 ```ts
 import { storedThreadToUiMessages } from '@dudousxd/nestjs-agent-react';
 
-const detail = await chat.client.getThread(threadId);
+const detail = await chat.backend.getThread(threadId);
 const initialMessages = storedThreadToUiMessages(detail.messages);
 // Feed into useAgentChat({ threadId, initialMessages, ... }) on the mount that owns this thread —
 // `initialMessages` is only read once, on mount.
@@ -676,7 +699,7 @@ paste.
 import { messageFiles, useAttachments } from '@dudousxd/nestjs-agent-react';
 
 const files = useAttachments({
-  backend: chat.backend, // or `upload: (file, { signal, onProgress }) => myUpload(file)`
+  // uploads through the provider's backend; or `upload: (file, { signal, onProgress }) => myUpload(file)`
   accept: 'image/*,.pdf',
   maxBytes: 20 * 1024 * 1024,
   maxFiles: 5,
@@ -713,25 +736,25 @@ flight. `messageFiles(message)` reads the files back off any message — live or
 
 With `AgentMediaAttachmentsModule` on the server (`@dudousxd/nestjs-agent/media`), one option turns
 it on — uploads go in chunks through nestjs-media's tus endpoint, with progress, abort (`remove`)
-and retry, on the chat client's own connection (base url, headers, credentials):
+and retry, on the client's own connection (origin, path, headers, credentials):
 
 ```tsx
 import { mediaAttachments } from '@dudousxd/nestjs-agent-react/media';
 
-const chat = useAgentChat({ attachments: mediaAttachments() });
-const files = useAttachments({ backend: chat.backend });
+<AgentProvider attachments={{ upload: mediaAttachments() }}>…</AgentProvider>;
+const files = useAttachments(); // uploads resumably
 ```
 
 Headless; `@dudousxd/nestjs-media-client` is an optional peer only this subpath uses. Extending it:
 
-- `mediaAttachments({ path: '/api/agent', chunkSize, retries })` — a prefixed API, tuning.
-- `new AgentClient({ …connection, attachments: mediaAttachments() })` — your own client instance.
-- `withMediaUploads(backend, connection)` — any other `AgentBackend`; `createMediaUpload(connection)`
-  — a bare `upload` for `useAttachments({ upload })`.
+- `mediaAttachments({ chunkSize, retries })` — tuning (the path comes from the client's `path`).
+- `new AgentClient({ …connection, attachments: { upload: mediaAttachments() } })` — your own client.
+- `createMediaUpload(connection)` — a bare `upload` for `useAttachments({ upload })`, or the
+  `uploadAttachment` member of your own `AgentBackend`.
 - Refusals throw `MediaUploadError` with the HTTP `status` (`413`, `415`, …); an aborted or failed
   upload is discarded on the server.
 
-Your own storage instead: `useAgentChat({ attachments: (file, { signal, onProgress }, connection) => … })`
+Your own storage instead: `<AgentProvider attachments={{ upload: (file, { signal, onProgress }, connection) => … }}>`
 (an `AttachmentUploadStrategy`), or `useAttachments({ upload })`, resolving to a
 `{ mediaId, url, contentType, name }` your server's `AGENT_ATTACHMENT_STAGING` recognises.
 

package/dist/{client-0Wd-WPsu.d.cts → client-ePlgRwP-.d.cts}

@@ -54,15 +54,17 @@ interface UploadAttachmentOptions {
 }
 /** How {@link AgentClient} reaches the server — handed to an {@link AttachmentUploadStrategy}. */
 interface AgentConnection {
-    /** Origin + base path, trailing slash removed (`''` for same-origin). */
+    /** The server's origin, trailing slash removed (`''` for same-origin). */
     baseUrl: string;
+    /** The agent's route prefix, normalized to a leading slash (`'/agent'`), or `''`. */
+    path: string;
     /** The client's static + per-request headers, resolved now (auth, CSRF). */
     headers: () => Promise<Record<string, string>>;
     credentials?: RequestCredentials;
     fetch: typeof fetch;
 }
 /**
- * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <base>/agent/attachments`) — e.g.
+ * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <path>/attachments`) — e.g.
  * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`, or your own storage. Gets the
  * client's connection so it needs no configuration of its own. Resolve with the attachment your
  * server's `AGENT_ATTACHMENT_STAGING` recognises by `mediaId`.
@@ -73,7 +75,8 @@ type AttachmentUploadStrategy = (file: File, options: UploadAttachmentOptions, c
  * hooks) and whatever serves the agent. {@link AgentClient} is the default implementation, over the
  * library's own REST routes with `fetch`. An app with its own client — a generated one, a different
  * auth scheme (cookie session + CSRF header), a backend that is not this library at all but speaks
- * docs/stream-protocol.md — implements this instead and passes it as `useAgentChat({ backend })`.
+ * docs/stream-protocol.md — implements this instead and passes it as `<AgentProvider backend>` (or
+ * per hook, `useAgentChat({ backend })`).
  *
  * The streaming, thread and cancel members are required: without them there is no chat. The rest
  * are optional; a hook that needs one the backend does not have throws
@@ -158,8 +161,16 @@ interface OkResult {
     ok: boolean;
 }
 interface AgentClientOptions {
-    /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
+    /**
+     * The server's origin, e.g. `https://api.example.com`. Defaults to `''` (same origin). The
+     * agent's route prefix is {@link AgentClientOptions.path}, not part of this.
+     */
     baseUrl?: string;
+    /**
+     * The agent's route prefix — `AgentModule`'s `path`, with any global prefix in front
+     * (`'api/agent'`). Leading/trailing slashes are optional. Defaults to `'agent'`.
+     */
+    path?: string;
     /** Static headers merged into every request. */
     headers?: Record<string, string>;
     /**
@@ -175,12 +186,15 @@ interface AgentClientOptions {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
-    /**
-     * How `uploadAttachment` uploads. Omitted → `POST <base>/agent/attachments` (multipart). Pass
-     * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media` for resumable uploads through
-     * nestjs-media, or your own {@link AttachmentUploadStrategy}.
-     */
-    attachments?: AttachmentUploadStrategy;
+    /** Attachment uploads. */
+    attachments?: {
+        /**
+         * How `uploadAttachment` uploads. Omitted → `POST <path>/attachments` (multipart). Pass
+         * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media` for resumable uploads through
+         * nestjs-media, or your own {@link AttachmentUploadStrategy}.
+         */
+        upload?: AttachmentUploadStrategy;
+    };
 }
 /**
  * Framework-agnostic REST client for the nestjs-agent endpoints — the default {@link AgentBackend}.
@@ -189,10 +203,10 @@ interface AgentClientOptions {
 declare class AgentClient implements AgentBackend {
     private readonly options;
     constructor(options?: AgentClientOptions);
-    /** `POST /agent/chat` → the turn's SSE stream. Throws {@link AgentHttpError} on a non-2xx. */
+    /** `POST <path>/chat` → the turn's SSE stream. Throws {@link AgentHttpError} on a non-2xx. */
     openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
     /**
-     * `GET /agent/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
+     * `GET <path>/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
      * streaming under that id (404).
      */
     resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
@@ -221,22 +235,22 @@ declare class AgentClient implements AgentBackend {
     deleteThread(id: string): Promise<void>;
     forkFromMessage(threadId: string, messageId: string): Promise<ThreadSummary>;
     renameThread(id: string, title: string): Promise<OkResult>;
-    /** General `PATCH /agent/threads/:threadId` — title and/or the thread's pinned default agent. */
+    /** General `PATCH <path>/threads/:threadId` — title and/or the thread's pinned default agent. */
     updateThread(id: string, patch: ThreadPatch): Promise<OkResult>;
     /**
      * Uploads a file (image/PDF) for a vision-capable model turn. Multipart, field name `file` —
-     * mirrors the backend's `POST /agent/attachments`. The returned {@link MessageAttachment} is
+     * mirrors the backend's `POST <path>/attachments`. The returned {@link MessageAttachment} is
      * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
      */
     uploadAttachment(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
     private uploadWithProgress;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
-    /** `GET /agent/models?agent=` — the models this caller may pick, grouped by provider. */
+    /** `GET <path>/models?agent=` — the models this caller may pick, grouped by provider. */
     listModels(agent?: string): Promise<ModelCatalogView>;
-    /** `GET /agent/agents` — the registered agents, the default one flagged. */
+    /** `GET <path>/agents` — the registered agents, the default one flagged. */
     listAgents(): Promise<AgentCatalogEntry[]>;
-    /** `GET /agent/quota` — the caller's budget windows and the one blocking sends, if any. */
+    /** `GET <path>/quota` — the caller's budget windows and the one blocking sends, if any. */
     getQuota(): Promise<QuotaReport>;
     getQuotaToday(): Promise<QuotaToday>;
     cancelStream(runId: string): Promise<CancelResult>;
@@ -276,10 +290,13 @@ declare class AgentClient implements AgentBackend {
     /** This client's connection, for an {@link AttachmentUploadStrategy}. */
     private connection;
     private baseUrl;
+    private agentPath;
+    /** Origin + agent path: what every route hangs off. */
+    private root;
     private resolveHeaders;
     private credentials;
     private request;
     private handleResponse;
 }
 
-export { type AgentBackend as A, type CancelResult as C, type MessageFeedbackInput as M, type QuotaToday as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, AgentClient as a, type AttachmentUploadStrategy as b, AgentBackendUnsupportedError 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 MessageFeedbackInput as M, type QuotaToday 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 ChatStreamRequest as g, type ChatStreamResponse as h, requireBackendMethod as r };

package/dist/{client-0Wd-WPsu.d.ts → client-ePlgRwP-.d.ts}

@@ -54,15 +54,17 @@ interface UploadAttachmentOptions {
 }
 /** How {@link AgentClient} reaches the server — handed to an {@link AttachmentUploadStrategy}. */
 interface AgentConnection {
-    /** Origin + base path, trailing slash removed (`''` for same-origin). */
+    /** The server's origin, trailing slash removed (`''` for same-origin). */
     baseUrl: string;
+    /** The agent's route prefix, normalized to a leading slash (`'/agent'`), or `''`. */
+    path: string;
     /** The client's static + per-request headers, resolved now (auth, CSRF). */
     headers: () => Promise<Record<string, string>>;
     credentials?: RequestCredentials;
     fetch: typeof fetch;
 }
 /**
- * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <base>/agent/attachments`) — e.g.
+ * Replaces {@link AgentClient}'s own `uploadAttachment` (`POST <path>/attachments`) — e.g.
  * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`, or your own storage. Gets the
  * client's connection so it needs no configuration of its own. Resolve with the attachment your
  * server's `AGENT_ATTACHMENT_STAGING` recognises by `mediaId`.
@@ -73,7 +75,8 @@ type AttachmentUploadStrategy = (file: File, options: UploadAttachmentOptions, c
  * hooks) and whatever serves the agent. {@link AgentClient} is the default implementation, over the
  * library's own REST routes with `fetch`. An app with its own client — a generated one, a different
  * auth scheme (cookie session + CSRF header), a backend that is not this library at all but speaks
- * docs/stream-protocol.md — implements this instead and passes it as `useAgentChat({ backend })`.
+ * docs/stream-protocol.md — implements this instead and passes it as `<AgentProvider backend>` (or
+ * per hook, `useAgentChat({ backend })`).
  *
  * The streaming, thread and cancel members are required: without them there is no chat. The rest
  * are optional; a hook that needs one the backend does not have throws
@@ -158,8 +161,16 @@ interface OkResult {
     ok: boolean;
 }
 interface AgentClientOptions {
-    /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
+    /**
+     * The server's origin, e.g. `https://api.example.com`. Defaults to `''` (same origin). The
+     * agent's route prefix is {@link AgentClientOptions.path}, not part of this.
+     */
     baseUrl?: string;
+    /**
+     * The agent's route prefix — `AgentModule`'s `path`, with any global prefix in front
+     * (`'api/agent'`). Leading/trailing slashes are optional. Defaults to `'agent'`.
+     */
+    path?: string;
     /** Static headers merged into every request. */
     headers?: Record<string, string>;
     /**
@@ -175,12 +186,15 @@ interface AgentClientOptions {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
-    /**
-     * How `uploadAttachment` uploads. Omitted → `POST <base>/agent/attachments` (multipart). Pass
-     * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media` for resumable uploads through
-     * nestjs-media, or your own {@link AttachmentUploadStrategy}.
-     */
-    attachments?: AttachmentUploadStrategy;
+    /** Attachment uploads. */
+    attachments?: {
+        /**
+         * How `uploadAttachment` uploads. Omitted → `POST <path>/attachments` (multipart). Pass
+         * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media` for resumable uploads through
+         * nestjs-media, or your own {@link AttachmentUploadStrategy}.
+         */
+        upload?: AttachmentUploadStrategy;
+    };
 }
 /**
  * Framework-agnostic REST client for the nestjs-agent endpoints — the default {@link AgentBackend}.
@@ -189,10 +203,10 @@ interface AgentClientOptions {
 declare class AgentClient implements AgentBackend {
     private readonly options;
     constructor(options?: AgentClientOptions);
-    /** `POST /agent/chat` → the turn's SSE stream. Throws {@link AgentHttpError} on a non-2xx. */
+    /** `POST <path>/chat` → the turn's SSE stream. Throws {@link AgentHttpError} on a non-2xx. */
     openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
     /**
-     * `GET /agent/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
+     * `GET <path>/chat/:runId/stream[?after=<seq>]` → the run's SSE stream, or `null` when nothing is
      * streaming under that id (404).
      */
     resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
@@ -221,22 +235,22 @@ declare class AgentClient implements AgentBackend {
     deleteThread(id: string): Promise<void>;
     forkFromMessage(threadId: string, messageId: string): Promise<ThreadSummary>;
     renameThread(id: string, title: string): Promise<OkResult>;
-    /** General `PATCH /agent/threads/:threadId` — title and/or the thread's pinned default agent. */
+    /** General `PATCH <path>/threads/:threadId` — title and/or the thread's pinned default agent. */
     updateThread(id: string, patch: ThreadPatch): Promise<OkResult>;
     /**
      * Uploads a file (image/PDF) for a vision-capable model turn. Multipart, field name `file` —
-     * mirrors the backend's `POST /agent/attachments`. The returned {@link MessageAttachment} is
+     * mirrors the backend's `POST <path>/attachments`. The returned {@link MessageAttachment} is
      * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
      */
     uploadAttachment(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
     private uploadWithProgress;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
-    /** `GET /agent/models?agent=` — the models this caller may pick, grouped by provider. */
+    /** `GET <path>/models?agent=` — the models this caller may pick, grouped by provider. */
     listModels(agent?: string): Promise<ModelCatalogView>;
-    /** `GET /agent/agents` — the registered agents, the default one flagged. */
+    /** `GET <path>/agents` — the registered agents, the default one flagged. */
     listAgents(): Promise<AgentCatalogEntry[]>;
-    /** `GET /agent/quota` — the caller's budget windows and the one blocking sends, if any. */
+    /** `GET <path>/quota` — the caller's budget windows and the one blocking sends, if any. */
     getQuota(): Promise<QuotaReport>;
     getQuotaToday(): Promise<QuotaToday>;
     cancelStream(runId: string): Promise<CancelResult>;
@@ -276,10 +290,13 @@ declare class AgentClient implements AgentBackend {
     /** This client's connection, for an {@link AttachmentUploadStrategy}. */
     private connection;
     private baseUrl;
+    private agentPath;
+    /** Origin + agent path: what every route hangs off. */
+    private root;
     private resolveHeaders;
     private credentials;
     private request;
     private handleResponse;
 }
 
-export { type AgentBackend as A, type CancelResult as C, type MessageFeedbackInput as M, type QuotaToday as Q, type ResumeStreamRequest as R, type ThreadPatch as T, type UploadAttachmentOptions as U, AgentClient as a, type AttachmentUploadStrategy as b, AgentBackendUnsupportedError 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 MessageFeedbackInput as M, type QuotaToday 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 ChatStreamRequest as g, type ChatStreamResponse as h, requireBackendMethod as r };

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

@@ -1,3 +1,5 @@
+import * as React from 'react';
+import { ComponentType, ReactNode } from 'react';
 import { ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
 import { ToolUIPart, DynamicToolUIPart, UIMessage } from 'ai';
 
@@ -558,4 +560,166 @@ declare function describeTimestamp(createdAt: string | null | undefined): Timest
  */
 declare function formatRelativeTime(date: Date): string;
 
-export { resolveResultView as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type DescribeToolCallOptions as D, type ElicitationBlockOptions as E, type TranscriptToolBlock as F, type GroupToolActivityOptions as G, type TranscriptToolCall as H, buildTranscriptBlocks as I, coerceAnswer as J, correctedCallIds as K, describeTimestamp as L, type MessageUsageInfo as M, describeToolCall as N, describeUsage as O, extractMessageText as P, fillTemplate as Q, type RawAnswer as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, formatRelativeTime as V, groupToolActivity as W, inferResultView as X, isActionCall as Y, phraseFor as Z, readPath as _, type TranscriptBlock as a, toolCallState as a0, toolCatalogFrom as a1, type TimestampInfo as b, type ToolCatalog as c, type AnyToolUIPart as d, type TranscriptFile as e, type ApprovalBlockOptions as f, type CoercibleQuestion as g, type ResolvedReading as h, type ResolvedResultView as i, type RetrievedPassage as j, type ToolActivityGroup as k, type ToolCallDescription as l, type ToolCallState as m, type ToolCallStatus as n, type TranscriptApproval as o, type TranscriptApprovalStatus as p, type TranscriptElicitationBlock as q, type TranscriptElicitationOutcome as r, type TranscriptFilesBlock as s, type TranscriptQuestion as t, type TranscriptQuestionOption as u, type TranscriptReasoningBlock as v, type TranscriptSettleState as w, type TranscriptSource as x, type TranscriptSourcesBlock as y, type TranscriptTextBlock as z };
+/** The `ui` frame component a composed tree is pushed under (`GENUI_TREE_COMPONENT` of `@dudousxd/nestjs-agent-core/genui`). */
+declare const GENUI_TREE_COMPONENT = "genui:tree";
+/** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
+interface GenerativeUIItem {
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    version: number | null;
+    toolCallId: string | null;
+}
+/** A node of a composed tree (`genui:tree` frames): `{ type, props, children? }`. */
+interface GenerativeUIElement {
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenerativeUIElement[];
+}
+/**
+ * An app's renderer for one component: it receives the component's props spread, plus `children`
+ * when it is a layout node in a tree. Any React component — the library never styles anything.
+ */
+type GenuiRenderer<P = any> = ComponentType<P & {
+    children?: ReactNode;
+}>;
+/** Component name → the app's renderer. */
+type GenuiRegistry = Record<string, GenuiRenderer>;
+/**
+ * Resolve a component the registry does not have — typically a tenant's own component, fetched for
+ * the exact `version` a message was rendered with. Return `null`/`undefined` for "no such
+ * component". May be async; results are cached per resolver, name and version.
+ */
+type ResolveComponent = (name: string, version: number | null) => GenuiRenderer | null | undefined | Promise<GenuiRenderer | null | undefined>;
+interface GenuiIssueLike {
+    path: (string | number)[];
+    message: string;
+}
+type ValidationLike = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    issues: GenuiIssueLike[];
+};
+/**
+ * What the renderer needs from a catalog to validate props before drawing them. A `Catalog` from
+ * `@dudousxd/nestjs-agent-core/genui` satisfies it; declared structurally so any catalog-shaped
+ * object does too.
+ */
+interface GenuiCatalogLike {
+    has(name: string): boolean;
+    validate(name: string, props: unknown): Promise<ValidationLike>;
+    validateSync?(name: string, props: unknown): ValidationLike | undefined;
+}
+interface GenerativeUIOptions {
+    registry: GenuiRegistry;
+    /** Validate props against it before rendering. Components the catalog does not know render unvalidated. */
+    catalog?: GenuiCatalogLike;
+    resolveComponent?: ResolveComponent;
+    /**
+     * Draws a composed tree frame (`genui:tree`) whole — e.g. through json-render (see the
+     * `/genui/json-render` subpath's `GenuiProvider`). Omitted → trees render node by node through
+     * `registry`.
+     */
+    treeRenderer?: GenuiRenderer<{
+        root?: GenerativeUIElement;
+    }>;
+}
+/** Why an item did not render. */
+type GenerativeUIProblem = {
+    reason: 'unknown';
+    item: GenerativeUIItem;
+} | {
+    reason: 'invalid';
+    item: GenerativeUIItem;
+    issues: GenuiIssueLike[];
+} | {
+    reason: 'error';
+    item: GenerativeUIItem;
+    error: unknown;
+};
+type GenerativeUIState = {
+    status: 'ready';
+    item: GenerativeUIItem;
+    Component: GenuiRenderer;
+    props: Record<string, unknown>;
+} | {
+    status: 'loading';
+    item: GenerativeUIItem;
+} | ({
+    status: 'problem';
+} & GenerativeUIProblem);
+
+/** What to draw instead of a component that did not render. Default: nothing. */
+type GenerativeUIFallback = ReactNode | ((problem: GenerativeUIProblem) => ReactNode);
+/**
+ * Renders a `genui:tree` frame's `{ root }` node by node through the same registry, catalog and
+ * resolver as top-level components. Used automatically for tree frames unless a `treeRenderer`
+ * (e.g. the json-render one) or a registry entry for `genui:tree` takes over.
+ */
+declare function GenuiTree({ root }: {
+    root?: GenerativeUIElement;
+}): React.JSX.Element | null;
+interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallback?: GenerativeUIFallback;
+    loading?: ReactNode;
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+    children?: ReactNode;
+}
+/**
+ * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
+ * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
+ */
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+/** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
+interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
+    fallback?: GenerativeUIFallback;
+    loading?: ReactNode;
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+}
+/** The enclosing `<GenuiProvider>`'s settings, or `null` outside one. */
+declare function useGenuiProvider(): GenuiProviderValue | null;
+interface GenuiProviderProps extends GenuiProviderValue {
+    children?: ReactNode;
+}
+/**
+ * Set generative UI up once, at the app root: the registry of your renderers, the catalog to
+ * validate against, a resolver for components the registry lacks, and what to draw when one does
+ * not render. Every `<GenerativeUI>` below reads it (its own props still win), and `MessageItem` /
+ * `MessageList` draw pushed components with it — no `renderUi` per message.
+ *
+ * ```tsx
+ * <GenuiProvider registry={registry} catalog={catalog} fallback={({ item }) => <Unknown name={item.component} />}>
+ *   <App />
+ * </GenuiProvider>
+ * ```
+ */
+declare function GenuiProvider({ registry, catalog, resolveComponent, treeRenderer, fallback, loading, onError, children, }: GenuiProviderProps): React.JSX.Element;
+/**
+ * The headless half of {@link GenerativeUI}: what to draw for one pushed component, or `null` when
+ * `part` is not one. Options default to the enclosing `<GenuiProvider>`'s.
+ */
+declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOptions>): GenerativeUIState | null;
+interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
+    /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
+    part: TranscriptUiBlock | GenerativeUIItem | unknown;
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    fallback?: GenerativeUIFallback;
+    /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
+    loading?: ReactNode;
+    /** A renderer threw (the item shows `fallback`). */
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+}
+/**
+ * Draws one server-pushed component with the app's own renderer. Headless: it adds no element and
+ * no style of its own — only what the registry's component renders (and whatever `fallback` /
+ * `loading` you pass). Everything but `part` defaults to the enclosing `<GenuiProvider>`.
+ *
+ * ```tsx
+ * <GenerativeUI part={block} />
+ * ```
+ */
+declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+
+export { type TranscriptQuestionOption as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type CoercibleQuestion as D, type DescribeToolCallOptions as E, type ElicitationBlockOptions as F, type GenerativeUIItem as G, type GroupToolActivityOptions as H, type RawAnswer as I, type ResolvedReading as J, type ResolvedResultView as K, type RetrievedPassage as L, type MessageUsageInfo as M, type ToolActivityGroup as N, type ToolCallDescription as O, type ToolCallState as P, type ToolCallStatus as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptApproval as V, type TranscriptApprovalStatus as W, type TranscriptElicitationBlock as X, type TranscriptElicitationOutcome as Y, type TranscriptFilesBlock as Z, type TranscriptQuestion as _, GENUI_TREE_COMPONENT as a, type TranscriptReasoningBlock as a0, type TranscriptSettleState as a1, type TranscriptSource as a2, type TranscriptSourcesBlock as a3, type TranscriptTextBlock as a4, type TranscriptToolBlock as a5, type TranscriptToolCall as a6, buildTranscriptBlocks as a7, coerceAnswer as a8, correctedCallIds as a9, describeTimestamp as aa, describeToolCall as ab, describeUsage as ac, extractMessageText as ad, fillTemplate as ae, formatRelativeTime as af, groupToolActivity as ag, inferResultView as ah, isActionCall as ai, phraseFor as aj, readPath as ak, resolveResultView as al, toolCallState as am, toolCatalogFrom as an, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type TranscriptBlock as t, useGenerativeUI as u, type TimestampInfo as v, type ToolCatalog as w, type AnyToolUIPart as x, type TranscriptFile as y, type ApprovalBlockOptions as z };