@dudousxd/nestjs-agent-react 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ThreadSummary, ThreadDetail, QuotaView } from '@dudousxd/nestjs-agent-core';
+import { ThreadSummary, ThreadDetail, MessageAttachment, QuotaView, StoredMessage } from '@dudousxd/nestjs-agent-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 
@@ -55,6 +55,13 @@ interface AgentChatTransportOptions {
  * The backend hydrates prior history from its store, so only the latest
  * user message text is sent each turn — keeping payloads tiny and
  * preventing the client from corrupting replayed history.
+ *
+ * Attachments (image/PDF for a vision-capable model) ride the per-send body:
+ * `sendMessage({ text }, { body: { attachments: MessageAttachment[] } })`. They
+ * flow to the backend as the turn's `attachments`, get persisted on the user
+ * message, and are rendered as native model content parts. Optimistic display of
+ * the user's own attachment thumbnails is the consumer's concern (it stages the
+ * upload), the same way history rendering reads `StoredMessage.attachments`.
  */
 declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private readonly options;
@@ -73,11 +80,16 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private captureHeaderMeta;
     private recordMeta;
     /**
-     * Parse the backend's SSE byte stream and synthesize a valid v7
-     * UI-message chunk stream. Recognized backend frames:
-     *  - `event: meta`  `data: {"runId","threadId"}`  → records identity
-     *  - `data: {"delta":"..."}`                       → `text-delta`
-     *  - `event: done`  `data: {}`                     → terminates
+     * Parse the backend's SSE byte stream and re-emit it as a valid v7 UI-message chunk stream.
+     * Recognized frames:
+     *  - `event: meta`  `data: {"runId","threadId"}`   → records identity
+     *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool)
+     *  - `event: done`  `data: {}`                      → terminates
+     *  - `event: error` `data: {code,message}`          → error chunk
+     *
+     * A run is ONE UI message with N steps. Each `step-start`/`step-finish` pair brackets a model
+     * call plus its tool execution; text and reasoning open lazily and close at the step boundary, so
+     * tool-call cards (input streaming → output) render live between the prose.
      */
     private toChunkStream;
 }
@@ -100,6 +112,15 @@ interface CancelResult {
 interface OkResult {
     ok: boolean;
 }
+/**
+ * Partial update accepted by `PATCH /agent/threads/:threadId`. `defaultAgent: null` clears a
+ * previously-set default back to the module's own default; omitting it leaves the thread's
+ * current default untouched.
+ */
+interface ThreadPatch {
+    title?: string;
+    defaultAgent?: string | null;
+}
 interface AgentClientOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
@@ -124,6 +145,14 @@ declare class AgentClient {
     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. */
+    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
+     * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
+     */
+    uploadAttachment(file: File): Promise<MessageAttachment>;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
     getQuotaToday(): Promise<QuotaToday>;
@@ -136,8 +165,31 @@ declare class AgentClient {
         reason?: string;
     }): Promise<void>;
     private request;
+    private handleResponse;
 }
 
+/**
+ * Convert a persisted `StoredMessage` (the agent-lib's on-disk shape) into an AI SDK v7
+ * `UIMessage` so a loaded thread can seed `useChat`'s `initialMessages` / `messages`.
+ *
+ * The lib stores a message as flat `content` text plus `toolCalls`/`toolResults` arrays; the SDK
+ * renders from `parts`. This maps:
+ *   - `content`            → a single `text` part (skipped when empty).
+ *   - each `attachment`    → a `file` part (image/PDF) so the user bubble re-renders its
+ *                            thumbnails on a reloaded thread.
+ *   - each `toolCall`      → a `tool-<name>` part, pairing its `toolResult` (matched by id):
+ *       - a result found   → `output-available` state, carrying `output`.
+ *       - no result found  → `input-available` state (the call never finished, e.g. the run was
+ *                            interrupted) — `output` is omitted, never a fabricated value.
+ *     When the store reports the tool's kind (`'read' | 'action'`), it rides along as
+ *     `toolMetadata.toolKind` so a UI can render an approval affordance for `action` tools
+ *     without hardcoding tool-name sets, matching how live-streamed tool parts carry it.
+ *
+ * Live streaming still arrives as fully-typed SDK tool parts (see `AgentChatTransport`); this
+ * converter only feeds replayed history, so the tool cards render the same either way.
+ */
+declare function storedMessageToUiMessage(message: StoredMessage): UIMessage;
+
 interface UseAgentChatOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
@@ -161,12 +213,30 @@ interface UseAgentChatOptions {
      * Run id of a buffered stream to reconnect to on mount — wire this to the thread's
      * `activeStreamId`. Its presence both gates the SDK's `resume` and names the run, so a normal
      * mount (no id) never fires a doomed resume GET. Omitted → no resume.
+     *
+     * For the common case (no id in hand yet), prefer {@link UseAgentChatOptions.resume} — it does
+     * this fetch-and-wire for you.
      */
     resumeRunId?: string;
+    /**
+     * When `true` and the hook (re)mounts with a `threadId`, the hook fetches the thread and, if its
+     * `activeRunId` is non-null (a turn was still streaming when the page loaded/reloaded), attaches
+     * to that run's `GET /agent/chat/:runId/stream` automatically — the in-flight turn streams into
+     * this session's message state exactly as if the send had happened here. A no-op when `threadId`
+     * is omitted (nothing to resume) or the fetched thread has no active run. Default `false`.
+     */
+    resume?: boolean;
     /** Read at every send to capture a page snapshot for the page-assistant. */
     getPageContext?: () => Record<string, unknown> | null;
     /** Fired after each streamed turn finishes (e.g. to refetch the sidebar). */
     onFinish?: () => void;
+    /**
+     * Fired once when a threadless chat's first send makes the backend create a thread — carries the
+     * new id so the consumer can sync its URL/router. Not fired when `threadId` was supplied. The hook
+     * ALSO remembers the id internally, so every subsequent send reuses it (no new thread per message)
+     * even before the consumer navigates.
+     */
+    onThreadCreated?: (threadId: string) => void;
 }
 interface AddToolResultArgs {
     tool: string;
@@ -182,6 +252,8 @@ interface AddToolResultArgs {
 declare function useAgentChat(options: UseAgentChatOptions): {
     addToolResult: ({ tool, toolCallId, output }: AddToolResultArgs) => void | PromiseLike<void>;
     runId: string | undefined;
+    /** The `resume`-fetched thread's active run id, or `null` once resolved with none. */
+    activeRunId: string | null;
     client: AgentClient;
     threads: ThreadSummary[];
     loadThreads: () => Promise<ThreadSummary[]>;
@@ -210,7 +282,7 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     status: ai.ChatStatus;
     sendMessage: (message?: (Omit<UIMessage<unknown, ai.UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
-        role?: "system" | "user" | "assistant";
+        role?: "user" | "assistant" | "system";
     } & {
         text?: never;
         files?: never;
@@ -418,4 +490,4 @@ interface SpeechRecognitionHook {
  */
 declare function useSpeechRecognition({ lang, onFinalTranscript, onInterimTranscript, }: UseSpeechRecognitionOptions): SpeechRecognitionHook;
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, useAgentChat, useSpeechRecognition };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type ThreadPatch, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, useAgentChat, useSpeechRecognition };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ThreadSummary, ThreadDetail, QuotaView } from '@dudousxd/nestjs-agent-core';
+import { ThreadSummary, ThreadDetail, MessageAttachment, QuotaView, StoredMessage } from '@dudousxd/nestjs-agent-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 
@@ -55,6 +55,13 @@ interface AgentChatTransportOptions {
  * The backend hydrates prior history from its store, so only the latest
  * user message text is sent each turn — keeping payloads tiny and
  * preventing the client from corrupting replayed history.
+ *
+ * Attachments (image/PDF for a vision-capable model) ride the per-send body:
+ * `sendMessage({ text }, { body: { attachments: MessageAttachment[] } })`. They
+ * flow to the backend as the turn's `attachments`, get persisted on the user
+ * message, and are rendered as native model content parts. Optimistic display of
+ * the user's own attachment thumbnails is the consumer's concern (it stages the
+ * upload), the same way history rendering reads `StoredMessage.attachments`.
  */
 declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private readonly options;
@@ -73,11 +80,16 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private captureHeaderMeta;
     private recordMeta;
     /**
-     * Parse the backend's SSE byte stream and synthesize a valid v7
-     * UI-message chunk stream. Recognized backend frames:
-     *  - `event: meta`  `data: {"runId","threadId"}`  → records identity
-     *  - `data: {"delta":"..."}`                       → `text-delta`
-     *  - `event: done`  `data: {}`                     → terminates
+     * Parse the backend's SSE byte stream and re-emit it as a valid v7 UI-message chunk stream.
+     * Recognized frames:
+     *  - `event: meta`  `data: {"runId","threadId"}`   → records identity
+     *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool)
+     *  - `event: done`  `data: {}`                      → terminates
+     *  - `event: error` `data: {code,message}`          → error chunk
+     *
+     * A run is ONE UI message with N steps. Each `step-start`/`step-finish` pair brackets a model
+     * call plus its tool execution; text and reasoning open lazily and close at the step boundary, so
+     * tool-call cards (input streaming → output) render live between the prose.
      */
     private toChunkStream;
 }
@@ -100,6 +112,15 @@ interface CancelResult {
 interface OkResult {
     ok: boolean;
 }
+/**
+ * Partial update accepted by `PATCH /agent/threads/:threadId`. `defaultAgent: null` clears a
+ * previously-set default back to the module's own default; omitting it leaves the thread's
+ * current default untouched.
+ */
+interface ThreadPatch {
+    title?: string;
+    defaultAgent?: string | null;
+}
 interface AgentClientOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
@@ -124,6 +145,14 @@ declare class AgentClient {
     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. */
+    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
+     * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
+     */
+    uploadAttachment(file: File): Promise<MessageAttachment>;
     promoteThread(id: string): Promise<OkResult>;
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
     getQuotaToday(): Promise<QuotaToday>;
@@ -136,8 +165,31 @@ declare class AgentClient {
         reason?: string;
     }): Promise<void>;
     private request;
+    private handleResponse;
 }
 
+/**
+ * Convert a persisted `StoredMessage` (the agent-lib's on-disk shape) into an AI SDK v7
+ * `UIMessage` so a loaded thread can seed `useChat`'s `initialMessages` / `messages`.
+ *
+ * The lib stores a message as flat `content` text plus `toolCalls`/`toolResults` arrays; the SDK
+ * renders from `parts`. This maps:
+ *   - `content`            → a single `text` part (skipped when empty).
+ *   - each `attachment`    → a `file` part (image/PDF) so the user bubble re-renders its
+ *                            thumbnails on a reloaded thread.
+ *   - each `toolCall`      → a `tool-<name>` part, pairing its `toolResult` (matched by id):
+ *       - a result found   → `output-available` state, carrying `output`.
+ *       - no result found  → `input-available` state (the call never finished, e.g. the run was
+ *                            interrupted) — `output` is omitted, never a fabricated value.
+ *     When the store reports the tool's kind (`'read' | 'action'`), it rides along as
+ *     `toolMetadata.toolKind` so a UI can render an approval affordance for `action` tools
+ *     without hardcoding tool-name sets, matching how live-streamed tool parts carry it.
+ *
+ * Live streaming still arrives as fully-typed SDK tool parts (see `AgentChatTransport`); this
+ * converter only feeds replayed history, so the tool cards render the same either way.
+ */
+declare function storedMessageToUiMessage(message: StoredMessage): UIMessage;
+
 interface UseAgentChatOptions {
     /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
     baseUrl?: string;
@@ -161,12 +213,30 @@ interface UseAgentChatOptions {
      * Run id of a buffered stream to reconnect to on mount — wire this to the thread's
      * `activeStreamId`. Its presence both gates the SDK's `resume` and names the run, so a normal
      * mount (no id) never fires a doomed resume GET. Omitted → no resume.
+     *
+     * For the common case (no id in hand yet), prefer {@link UseAgentChatOptions.resume} — it does
+     * this fetch-and-wire for you.
      */
     resumeRunId?: string;
+    /**
+     * When `true` and the hook (re)mounts with a `threadId`, the hook fetches the thread and, if its
+     * `activeRunId` is non-null (a turn was still streaming when the page loaded/reloaded), attaches
+     * to that run's `GET /agent/chat/:runId/stream` automatically — the in-flight turn streams into
+     * this session's message state exactly as if the send had happened here. A no-op when `threadId`
+     * is omitted (nothing to resume) or the fetched thread has no active run. Default `false`.
+     */
+    resume?: boolean;
     /** Read at every send to capture a page snapshot for the page-assistant. */
     getPageContext?: () => Record<string, unknown> | null;
     /** Fired after each streamed turn finishes (e.g. to refetch the sidebar). */
     onFinish?: () => void;
+    /**
+     * Fired once when a threadless chat's first send makes the backend create a thread — carries the
+     * new id so the consumer can sync its URL/router. Not fired when `threadId` was supplied. The hook
+     * ALSO remembers the id internally, so every subsequent send reuses it (no new thread per message)
+     * even before the consumer navigates.
+     */
+    onThreadCreated?: (threadId: string) => void;
 }
 interface AddToolResultArgs {
     tool: string;
@@ -182,6 +252,8 @@ interface AddToolResultArgs {
 declare function useAgentChat(options: UseAgentChatOptions): {
     addToolResult: ({ tool, toolCallId, output }: AddToolResultArgs) => void | PromiseLike<void>;
     runId: string | undefined;
+    /** The `resume`-fetched thread's active run id, or `null` once resolved with none. */
+    activeRunId: string | null;
     client: AgentClient;
     threads: ThreadSummary[];
     loadThreads: () => Promise<ThreadSummary[]>;
@@ -210,7 +282,7 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     status: ai.ChatStatus;
     sendMessage: (message?: (Omit<UIMessage<unknown, ai.UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
-        role?: "system" | "user" | "assistant";
+        role?: "user" | "assistant" | "system";
     } & {
         text?: never;
         files?: never;
@@ -418,4 +490,4 @@ interface SpeechRecognitionHook {
  */
 declare function useSpeechRecognition({ lang, onFinalTranscript, onInterimTranscript, }: UseSpeechRecognitionOptions): SpeechRecognitionHook;
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, useAgentChat, useSpeechRecognition };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AnyToolUIPart, type CancelResult, ChatInput, type ChatInputProps, type ChatStatus, DEFAULT_SPEECH_LANG, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, SPEECH_LANGUAGES, type SpeechLanguage, type SpeechRecognitionHook, type ThreadPatch, type UseAgentChatOptions, type UseSpeechRecognitionOptions, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, useAgentChat, useSpeechRecognition };