@dudousxd/nestjs-agent-react 0.19.0 → 0.20.0

package/dist/index.d.cts

@@ -1,135 +1,14 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
+import { A as AgentBackend, U as UploadAttachmentOptions, a as AgentClient, b as AttachmentUploadStrategy, Q as QuotaToday } from './client-0Wd-WPsu.cjs';
+export { c as AgentBackendUnsupportedError, d as AgentClientOptions, e as AgentConnection, f as AgentHttpError, C as CancelResult, g as ChatStreamRequest, h as ChatStreamResponse, M as MessageFeedbackInput, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-0Wd-WPsu.cjs';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, QuotaReport, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, QuotaWindow, QuotaBlock, StoredMessage } from '@dudousxd/nestjs-agent-core';
+import { MessageAttachment, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, QuotaReport, QuotaWindow, QuotaBlock, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, ToolCatalogEntry, ThreadDetail } from '@dudousxd/nestjs-agent-core';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React__default, { ReactNode, Context } from 'react';
 import { T as TranscriptUiBlock, a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile } from './model-gHqjNjLJ.cjs';
 export { f as ApprovalBlockOptions, B as BuildBlocksOptions, g as CoercibleQuestion, D as DescribeToolCallOptions, E as ElicitationBlockOptions, G as GroupToolActivityOptions, R as RawAnswer, h as ResolvedReading, i as ResolvedResultView, j as RetrievedPassage, S as SettleAction, k as ToolActivityGroup, l as ToolCallDescription, m as ToolCallState, n as ToolCallStatus, o as TranscriptApproval, p as TranscriptApprovalStatus, q as TranscriptElicitationBlock, r as TranscriptElicitationOutcome, s as TranscriptFilesBlock, t as TranscriptQuestion, u as TranscriptQuestionOption, v as TranscriptReasoningBlock, w as TranscriptSettleState, x as TranscriptSource, y as TranscriptSourcesBlock, z as TranscriptTextBlock, F as TranscriptToolBlock, H as TranscriptToolCall, I as buildTranscriptBlocks, J as coerceAnswer, K as correctedCallIds, L as describeTimestamp, N as describeToolCall, O as describeUsage, P as extractMessageText, Q as fillTemplate, V as formatRelativeTime, W as groupToolActivity, X as inferResultView, Y as isActionCall, Z as phraseFor, _ as readPath, $ as resolveResultView, a0 as toolCallState, a1 as toolCatalogFrom } from './model-gHqjNjLJ.cjs';
 
-/**
- * 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
- * current default untouched.
- */
-interface ThreadPatch {
-    title?: string;
-    defaultAgent?: string | null;
-    /** Pin a catalog model on the thread; `null` unpins it. */
-    model?: string | null;
-}
-/** Starting a turn: the body `POST <base>/chat` takes (see docs/stream-protocol.md). */
-interface ChatStreamRequest {
-    /** `{ message, threadId?, agent?, model?, attachments?, pageContext?, regenerate?, … }`. */
-    body: Record<string, unknown>;
-    /** Per-request headers the AI SDK was handed for this send. */
-    headers?: Record<string, string>;
-    /** Aborted when the user stops the turn. */
-    signal?: AbortSignal;
-}
-/** Attaching to a run that is already streaming: `GET <base>/chat/:runId/stream?after=<seq>`. */
-interface ResumeStreamRequest {
-    runId: string;
-    /**
-     * The sequence number (SSE `id:`) of the last frame the client already has. Omitted → replay
-     * from the first frame. A backend that cannot skip may ignore it: the transport also drops frames
-     * at or below it.
-     */
-    after?: number;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-}
-/**
- * An open chat stream: the raw `text/event-stream` bytes in the stream-protocol framing, plus the
- * identity a backend may learn before the first frame (the `X-Agent-Run-Id` / `X-Agent-Thread-Id`
- * headers). The body's own `event: meta` frame supplies them otherwise.
- */
-interface ChatStreamResponse {
-    body: ReadableStream<Uint8Array>;
-    runId?: string;
-    threadId?: string;
-}
-/** What `POST <base>/messages/:id/feedback` takes. `value: null` clears the rating. */
-interface MessageFeedbackInput {
-    value: MessageFeedbackValue | null;
-    comment?: string;
-}
-interface UploadAttachmentOptions {
-    signal?: AbortSignal;
-    /** Called with 0..1 as the upload progresses, when the backend can observe it. */
-    onProgress?: (fraction: number) => void;
-}
-/**
- * Everything the React layer asks of a server — the seam between `useAgentChat` (and the other
- * 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 })`.
- *
- * 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
- * {@link AgentBackendUnsupportedError} when it is called, so a backend only implements what its
- * server supports.
- */
-interface AgentBackend {
-    /** Start a turn and return its SSE stream. Throw on a non-2xx answer. */
-    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
-    /** Attach to a streaming run. Resolve `null` when nothing is streaming under that id (HTTP 404). */
-    resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
-    /** Hard-stop a run server-side. */
-    cancelStream(runId: string): Promise<unknown>;
-    listThreads(): Promise<ThreadSummary[]>;
-    getThread(id: string): Promise<ThreadDetail>;
-    updateThread(id: string, patch: ThreadPatch): Promise<unknown>;
-    deleteThread(id: string): Promise<unknown>;
-    forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
-    promoteThread?(id: string): Promise<unknown>;
-    truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
-    approveToolCall?(input: {
-        toolCallId: string;
-        remember?: boolean;
-        via?: string;
-    }): Promise<unknown>;
-    rejectToolCall?(input: {
-        toolCallId: string;
-        reason?: string;
-        via?: string;
-    }): Promise<unknown>;
-    answerToolCall?(input: {
-        toolCallId: string;
-        answers?: Record<string, string[]>;
-    }): Promise<unknown>;
-    skipToolCall?(input: {
-        toolCallId: string;
-    }): Promise<unknown>;
-    uploadAttachment?(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
-    listTools?(agent?: string): Promise<ToolCatalogEntry[]>;
-    listSkills?(threadId?: string): Promise<SkillCatalogEntry[]>;
-    getQuotaToday?(): Promise<QuotaView>;
-    /** `GET <base>/quota` — every budget window, and which one blocks sends, if any. */
-    getQuota?(): Promise<QuotaReport>;
-    /** `GET <base>/models?agent=` — what a model picker offers. */
-    listModels?(agent?: string): Promise<ModelCatalogView>;
-    /** `GET <base>/agents` — what an agent picker offers. */
-    listAgents?(): Promise<AgentCatalogEntry[]>;
-    setMessageFeedback?(messageId: string, input: MessageFeedbackInput): Promise<{
-        feedback: MessageFeedback | null;
-    }>;
-}
-/** An optional {@link AgentBackend} member the bound backend does not implement was called. */
-declare class AgentBackendUnsupportedError extends Error {
-    readonly method: string;
-    constructor(method: string);
-}
-type OptionalMethod = {
-    [K in keyof AgentBackend]-?: undefined extends AgentBackend[K] ? K : never;
-}[keyof AgentBackend];
-/**
- * The optional backend method `name`, bound — or a throw naming it. For hook code that has to call
- * something a backend may not offer.
- */
-declare function requireBackendMethod<K extends OptionalMethod>(backend: AgentBackend, name: K): NonNullable<AgentBackend[K]>;
-
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
     runId: string;
@@ -618,141 +497,6 @@ interface BackgroundRun {
  */
 declare function backgroundRunsFromThread(messages: readonly StoredMessage[]): BackgroundRun[];
 
-/**
- * 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.
- */
-declare class AgentHttpError extends Error {
-    readonly status: number;
-    readonly method: string;
-    readonly path: string;
-    constructor(status: number, method: string, path: string, statusText: string);
-}
-/** The quota-today read-model: usage, the configured limit (null → unlimited), and USD spend. */
-type QuotaToday = QuotaView;
-interface CancelResult {
-    aborted: boolean;
-}
-interface OkResult {
-    ok: boolean;
-}
-interface AgentClientOptions {
-    /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
-    baseUrl?: string;
-    /** Static headers merged into every request. */
-    headers?: Record<string, string>;
-    /**
-     * Resolved per request — for short-lived bearer tokens, or a CSRF header read from a cookie
-     * (`{ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }`), which has to be read at request time because
-     * the server may rotate it.
-     */
-    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    /**
-     * Forwarded to fetch so cookie auth works. Same-origin requests send cookies by default; set
-     * `'include'` when the API lives on another origin (and have it answer with credentialed CORS).
-     */
-    credentials?: RequestCredentials;
-    /** Injectable for tests / non-browser runtimes. */
-    fetch?: typeof fetch;
-}
-/**
- * Framework-agnostic REST client for the nestjs-agent endpoints — the default {@link AgentBackend}.
- * Used by `useAgentChat`, but standalone-usable (vanilla fetch, no React).
- */
-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. */
-    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
-    /**
-     * `GET /agent/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>;
-    /**
-     * Rate a message (`'up'`/`'down'`, optional comment) or clear its rating (`value: null`). Answers
-     * the stored rating.
-     */
-    setMessageFeedback(messageId: string, input: MessageFeedbackInput): Promise<{
-        feedback: MessageFeedback | null;
-    }>;
-    listThreads(): Promise<ThreadSummary[]>;
-    /**
-     * The skills this caller can invoke right now, scope-resolved — the same list, built by the same
-     * call, that the model is offered, so what a user can type after a `/` and what the agent can
-     * reach cannot drift apart. `threadId` reaches the host's own resolver, which may scope a skill to
-     * one conversation; omitted, the server reads it as a brand-new thread.
-     */
-    listSkills(threadId?: string): Promise<SkillCatalogEntry[]>;
-    /**
-     * The tools this caller can reach through `agent` (the default agent when omitted), each with the
-     * server-declared `presentation` a chat narrates it by — the same list the model is offered.
-     * Prefer {@link useToolCatalog}, which fetches it once and shares it.
-     */
-    listTools(agent?: string): Promise<ToolCatalogEntry[]>;
-    getThread(id: string): Promise<ThreadDetail>;
-    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, 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. */
-    listModels(agent?: string): Promise<ModelCatalogView>;
-    /** `GET /agent/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. */
-    getQuota(): Promise<QuotaReport>;
-    getQuotaToday(): Promise<QuotaToday>;
-    cancelStream(runId: string): Promise<CancelResult>;
-    /**
-     * `remember` approves later calls of the same tool in the same thread; `via` names the surface
-     * the decision came through (the server records `'web'` when omitted).
-     */
-    approveToolCall(input: {
-        toolCallId: string;
-        remember?: boolean;
-        via?: string;
-    }): Promise<void>;
-    rejectToolCall(input: {
-        toolCallId: string;
-        reason?: string;
-        via?: string;
-    }): Promise<void>;
-    /**
-     * Settle a parked question set. `answers` is questionId → chosen option values; a question left
-     * 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.
-     */
-    answerToolCall(input: {
-        toolCallId: string;
-        answers?: Record<string, string[]>;
-    }): Promise<void>;
-    /**
-     * Decline to answer and let the agent proceed on its own pre-picked values. Lands on the same
-     * values a confirmation would, and persists differently on purpose — only one of them is
-     * evidence the user chose them.
-     */
-    skipToolCall(input: {
-        toolCallId: string;
-    }): Promise<void>;
-    private fetchImpl;
-    private baseUrl;
-    private resolveHeaders;
-    private credentials;
-    private request;
-    private handleResponse;
-}
-
 /** Draws a server-pushed component block. */
 type AmbientRenderUi = (block: TranscriptUiBlock) => ReactNode;
 /**
@@ -1551,6 +1295,12 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
+    /**
+     * How the built-in client uploads attachments (ignored when a backend is given) — e.g.
+     * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`. Pass `chat.backend` to
+     * `useAttachments` and every composer uses it.
+     */
+    attachments?: AttachmentUploadStrategy;
     /** Reuse an existing client instead of constructing one. Prefer {@link backend}. */
     client?: B;
     /** Named agent to run each turn. */
@@ -1757,4 +1507,4 @@ declare class QuotaBlockedError extends Error {
     constructor(block: QuotaBlock);
 }
 
-export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackInput, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, AttachmentUploadStrategy, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };

package/dist/index.d.ts

@@ -1,135 +1,14 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
+import { A as AgentBackend, U as UploadAttachmentOptions, a as AgentClient, b as AttachmentUploadStrategy, Q as QuotaToday } from './client-0Wd-WPsu.js';
+export { c as AgentBackendUnsupportedError, d as AgentClientOptions, e as AgentConnection, f as AgentHttpError, C as CancelResult, g as ChatStreamRequest, h as ChatStreamResponse, M as MessageFeedbackInput, R as ResumeStreamRequest, T as ThreadPatch, r as requireBackendMethod } from './client-0Wd-WPsu.js';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, QuotaReport, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, QuotaWindow, QuotaBlock, StoredMessage } from '@dudousxd/nestjs-agent-core';
+import { MessageAttachment, AgentCatalogEntry, ModelCatalogEntry, ModelCatalogView, QuotaReport, QuotaWindow, QuotaBlock, MessageFeedback, MessageFeedbackValue, ThreadSummary, StoredMessage, ToolCatalogEntry, ThreadDetail } from '@dudousxd/nestjs-agent-core';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React__default, { ReactNode, Context } from 'react';
 import { T as TranscriptUiBlock, a as TranscriptBlock, U as UsageSummary, b as TimestampInfo, C as ChatStatus, M as MessageUsageInfo, c as ToolCatalog, A as ApproveOptions, d as AnyToolUIPart, e as TranscriptFile } from './model-gHqjNjLJ.js';
 export { f as ApprovalBlockOptions, B as BuildBlocksOptions, g as CoercibleQuestion, D as DescribeToolCallOptions, E as ElicitationBlockOptions, G as GroupToolActivityOptions, R as RawAnswer, h as ResolvedReading, i as ResolvedResultView, j as RetrievedPassage, S as SettleAction, k as ToolActivityGroup, l as ToolCallDescription, m as ToolCallState, n as ToolCallStatus, o as TranscriptApproval, p as TranscriptApprovalStatus, q as TranscriptElicitationBlock, r as TranscriptElicitationOutcome, s as TranscriptFilesBlock, t as TranscriptQuestion, u as TranscriptQuestionOption, v as TranscriptReasoningBlock, w as TranscriptSettleState, x as TranscriptSource, y as TranscriptSourcesBlock, z as TranscriptTextBlock, F as TranscriptToolBlock, H as TranscriptToolCall, I as buildTranscriptBlocks, J as coerceAnswer, K as correctedCallIds, L as describeTimestamp, N as describeToolCall, O as describeUsage, P as extractMessageText, Q as fillTemplate, V as formatRelativeTime, W as groupToolActivity, X as inferResultView, Y as isActionCall, Z as phraseFor, _ as readPath, $ as resolveResultView, a0 as toolCallState, a1 as toolCatalogFrom } from './model-gHqjNjLJ.js';
 
-/**
- * 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
- * current default untouched.
- */
-interface ThreadPatch {
-    title?: string;
-    defaultAgent?: string | null;
-    /** Pin a catalog model on the thread; `null` unpins it. */
-    model?: string | null;
-}
-/** Starting a turn: the body `POST <base>/chat` takes (see docs/stream-protocol.md). */
-interface ChatStreamRequest {
-    /** `{ message, threadId?, agent?, model?, attachments?, pageContext?, regenerate?, … }`. */
-    body: Record<string, unknown>;
-    /** Per-request headers the AI SDK was handed for this send. */
-    headers?: Record<string, string>;
-    /** Aborted when the user stops the turn. */
-    signal?: AbortSignal;
-}
-/** Attaching to a run that is already streaming: `GET <base>/chat/:runId/stream?after=<seq>`. */
-interface ResumeStreamRequest {
-    runId: string;
-    /**
-     * The sequence number (SSE `id:`) of the last frame the client already has. Omitted → replay
-     * from the first frame. A backend that cannot skip may ignore it: the transport also drops frames
-     * at or below it.
-     */
-    after?: number;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-}
-/**
- * An open chat stream: the raw `text/event-stream` bytes in the stream-protocol framing, plus the
- * identity a backend may learn before the first frame (the `X-Agent-Run-Id` / `X-Agent-Thread-Id`
- * headers). The body's own `event: meta` frame supplies them otherwise.
- */
-interface ChatStreamResponse {
-    body: ReadableStream<Uint8Array>;
-    runId?: string;
-    threadId?: string;
-}
-/** What `POST <base>/messages/:id/feedback` takes. `value: null` clears the rating. */
-interface MessageFeedbackInput {
-    value: MessageFeedbackValue | null;
-    comment?: string;
-}
-interface UploadAttachmentOptions {
-    signal?: AbortSignal;
-    /** Called with 0..1 as the upload progresses, when the backend can observe it. */
-    onProgress?: (fraction: number) => void;
-}
-/**
- * Everything the React layer asks of a server — the seam between `useAgentChat` (and the other
- * 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 })`.
- *
- * 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
- * {@link AgentBackendUnsupportedError} when it is called, so a backend only implements what its
- * server supports.
- */
-interface AgentBackend {
-    /** Start a turn and return its SSE stream. Throw on a non-2xx answer. */
-    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
-    /** Attach to a streaming run. Resolve `null` when nothing is streaming under that id (HTTP 404). */
-    resumeChatStream(request: ResumeStreamRequest): Promise<ChatStreamResponse | null>;
-    /** Hard-stop a run server-side. */
-    cancelStream(runId: string): Promise<unknown>;
-    listThreads(): Promise<ThreadSummary[]>;
-    getThread(id: string): Promise<ThreadDetail>;
-    updateThread(id: string, patch: ThreadPatch): Promise<unknown>;
-    deleteThread(id: string): Promise<unknown>;
-    forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
-    promoteThread?(id: string): Promise<unknown>;
-    truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
-    approveToolCall?(input: {
-        toolCallId: string;
-        remember?: boolean;
-        via?: string;
-    }): Promise<unknown>;
-    rejectToolCall?(input: {
-        toolCallId: string;
-        reason?: string;
-        via?: string;
-    }): Promise<unknown>;
-    answerToolCall?(input: {
-        toolCallId: string;
-        answers?: Record<string, string[]>;
-    }): Promise<unknown>;
-    skipToolCall?(input: {
-        toolCallId: string;
-    }): Promise<unknown>;
-    uploadAttachment?(file: File, options?: UploadAttachmentOptions): Promise<MessageAttachment>;
-    listTools?(agent?: string): Promise<ToolCatalogEntry[]>;
-    listSkills?(threadId?: string): Promise<SkillCatalogEntry[]>;
-    getQuotaToday?(): Promise<QuotaView>;
-    /** `GET <base>/quota` — every budget window, and which one blocks sends, if any. */
-    getQuota?(): Promise<QuotaReport>;
-    /** `GET <base>/models?agent=` — what a model picker offers. */
-    listModels?(agent?: string): Promise<ModelCatalogView>;
-    /** `GET <base>/agents` — what an agent picker offers. */
-    listAgents?(): Promise<AgentCatalogEntry[]>;
-    setMessageFeedback?(messageId: string, input: MessageFeedbackInput): Promise<{
-        feedback: MessageFeedback | null;
-    }>;
-}
-/** An optional {@link AgentBackend} member the bound backend does not implement was called. */
-declare class AgentBackendUnsupportedError extends Error {
-    readonly method: string;
-    constructor(method: string);
-}
-type OptionalMethod = {
-    [K in keyof AgentBackend]-?: undefined extends AgentBackend[K] ? K : never;
-}[keyof AgentBackend];
-/**
- * The optional backend method `name`, bound — or a throw naming it. For hook code that has to call
- * something a backend may not offer.
- */
-declare function requireBackendMethod<K extends OptionalMethod>(backend: AgentBackend, name: K): NonNullable<AgentBackend[K]>;
-
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
 interface AgentStreamMeta {
     runId: string;
@@ -618,141 +497,6 @@ interface BackgroundRun {
  */
 declare function backgroundRunsFromThread(messages: readonly StoredMessage[]): BackgroundRun[];
 
-/**
- * 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.
- */
-declare class AgentHttpError extends Error {
-    readonly status: number;
-    readonly method: string;
-    readonly path: string;
-    constructor(status: number, method: string, path: string, statusText: string);
-}
-/** The quota-today read-model: usage, the configured limit (null → unlimited), and USD spend. */
-type QuotaToday = QuotaView;
-interface CancelResult {
-    aborted: boolean;
-}
-interface OkResult {
-    ok: boolean;
-}
-interface AgentClientOptions {
-    /** Origin + base path, e.g. `https://api.example.com`. Defaults to `''`. */
-    baseUrl?: string;
-    /** Static headers merged into every request. */
-    headers?: Record<string, string>;
-    /**
-     * Resolved per request — for short-lived bearer tokens, or a CSRF header read from a cookie
-     * (`{ 'X-XSRF-TOKEN': readCookie('XSRF-TOKEN') }`), which has to be read at request time because
-     * the server may rotate it.
-     */
-    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    /**
-     * Forwarded to fetch so cookie auth works. Same-origin requests send cookies by default; set
-     * `'include'` when the API lives on another origin (and have it answer with credentialed CORS).
-     */
-    credentials?: RequestCredentials;
-    /** Injectable for tests / non-browser runtimes. */
-    fetch?: typeof fetch;
-}
-/**
- * Framework-agnostic REST client for the nestjs-agent endpoints — the default {@link AgentBackend}.
- * Used by `useAgentChat`, but standalone-usable (vanilla fetch, no React).
- */
-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. */
-    openChatStream(request: ChatStreamRequest): Promise<ChatStreamResponse>;
-    /**
-     * `GET /agent/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>;
-    /**
-     * Rate a message (`'up'`/`'down'`, optional comment) or clear its rating (`value: null`). Answers
-     * the stored rating.
-     */
-    setMessageFeedback(messageId: string, input: MessageFeedbackInput): Promise<{
-        feedback: MessageFeedback | null;
-    }>;
-    listThreads(): Promise<ThreadSummary[]>;
-    /**
-     * The skills this caller can invoke right now, scope-resolved — the same list, built by the same
-     * call, that the model is offered, so what a user can type after a `/` and what the agent can
-     * reach cannot drift apart. `threadId` reaches the host's own resolver, which may scope a skill to
-     * one conversation; omitted, the server reads it as a brand-new thread.
-     */
-    listSkills(threadId?: string): Promise<SkillCatalogEntry[]>;
-    /**
-     * The tools this caller can reach through `agent` (the default agent when omitted), each with the
-     * server-declared `presentation` a chat narrates it by — the same list the model is offered.
-     * Prefer {@link useToolCatalog}, which fetches it once and shares it.
-     */
-    listTools(agent?: string): Promise<ToolCatalogEntry[]>;
-    getThread(id: string): Promise<ThreadDetail>;
-    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, 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. */
-    listModels(agent?: string): Promise<ModelCatalogView>;
-    /** `GET /agent/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. */
-    getQuota(): Promise<QuotaReport>;
-    getQuotaToday(): Promise<QuotaToday>;
-    cancelStream(runId: string): Promise<CancelResult>;
-    /**
-     * `remember` approves later calls of the same tool in the same thread; `via` names the surface
-     * the decision came through (the server records `'web'` when omitted).
-     */
-    approveToolCall(input: {
-        toolCallId: string;
-        remember?: boolean;
-        via?: string;
-    }): Promise<void>;
-    rejectToolCall(input: {
-        toolCallId: string;
-        reason?: string;
-        via?: string;
-    }): Promise<void>;
-    /**
-     * Settle a parked question set. `answers` is questionId → chosen option values; a question left
-     * 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.
-     */
-    answerToolCall(input: {
-        toolCallId: string;
-        answers?: Record<string, string[]>;
-    }): Promise<void>;
-    /**
-     * Decline to answer and let the agent proceed on its own pre-picked values. Lands on the same
-     * values a confirmation would, and persists differently on purpose — only one of them is
-     * evidence the user chose them.
-     */
-    skipToolCall(input: {
-        toolCallId: string;
-    }): Promise<void>;
-    private fetchImpl;
-    private baseUrl;
-    private resolveHeaders;
-    private credentials;
-    private request;
-    private handleResponse;
-}
-
 /** Draws a server-pushed component block. */
 type AmbientRenderUi = (block: TranscriptUiBlock) => ReactNode;
 /**
@@ -1551,6 +1295,12 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
     credentials?: RequestCredentials;
     /** Injectable for tests / non-browser runtimes. */
     fetch?: typeof fetch;
+    /**
+     * How the built-in client uploads attachments (ignored when a backend is given) — e.g.
+     * `mediaAttachments()` from `@dudousxd/nestjs-agent-react/media`. Pass `chat.backend` to
+     * `useAttachments` and every composer uses it.
+     */
+    attachments?: AttachmentUploadStrategy;
     /** Reuse an existing client instead of constructing one. Prefer {@link backend}. */
     client?: B;
     /** Named agent to run each turn. */
@@ -1757,4 +1507,4 @@ declare class QuotaBlockedError extends Error {
     constructor(block: QuotaBlock);
 }
 
-export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatStreamRequest, type ChatStreamResponse, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackInput, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, type QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type ResumeStreamRequest, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadPatch, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { AgentBackend, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, type AmbientRenderUi, AmbientRenderUiContext, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, type AttachmentRejection, AttachmentUploadStrategy, type AttachmentsState, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type ChatBackground, ChatInput, type ChatInputProps, ChatStatus, type ChatTranscript, type ClipboardLikeEvent, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type DragLikeEvent, type MessageFeedbackState, type MessageFile, type MessageFileKind, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, QuotaBlockedError, type QuotaState, QuotaToday, type ReconnectOptions, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, SPEECH_LANGUAGES, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StagedAttachment, type StagedAttachmentStatus, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type StreamConnectionState, type ThreadsEvent, type ThreadsState, TimestampInfo, ToolCatalog, type ToolCatalogState, type TranscriptActionState, TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, TranscriptFile, type TranscriptItem, type TranscriptItemOptions, type TranscriptStopState, TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, UploadAttachmentOptions, UsageSummary, type UseAgentChatOptions, type UseAgentsOptions, type UseApprovalCountdownOptions, type UseAttachmentsOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseQuotaOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, acceptsFile, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, dragHasFiles, fileKind, filesFromClipboard, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, messageFiles, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useAmbientRenderUi, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };

package/dist/index.js

@@ -125,6 +125,9 @@ var AgentClient = class {
   * what a caller then rides on `sendMessage({ text }, { body: { attachments: [...] } })`.
   */
   async uploadAttachment(file, options = {}) {
+    if (this.options.attachments !== void 0) {
+      return this.options.attachments(file, options, this.connection());
+    }
     if (options.onProgress !== void 0 && this.options.fetch === void 0 && typeof XMLHttpRequest !== "undefined") {
       return this.uploadWithProgress(file, options);
     }
@@ -239,6 +242,15 @@ var AgentClient = class {
   fetchImpl() {
     return this.options.fetch ?? globalThis.fetch;
   }
+  /** This client's connection, for an {@link AttachmentUploadStrategy}. */
+  connection() {
+    return {
+      baseUrl: this.baseUrl(),
+      headers: /* @__PURE__ */ __name(() => this.resolveHeaders(), "headers"),
+      fetch: this.fetchImpl(),
+      ...this.credentials()
+    };
+  }
   baseUrl() {
     return (this.options.baseUrl ?? "").replace(/\/$/, "");
   }
@@ -4437,6 +4449,9 @@ function useAgentChat(options) {
       ...options.fetch !== void 0 ? {
         fetch: options.fetch
       } : {},
+      ...options.attachments !== void 0 ? {
+        attachments: options.attachments
+      } : {},
       getHeaders: /* @__PURE__ */ __name(async () => mergeHeaders(latest.current), "getHeaders")
     });
   }, []);