@dudousxd/nestjs-agent-react 0.16.0 → 0.18.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, StoredMessage } 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';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React__default from 'react';
 import { 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, T as TranscriptUiBlock } from './model-gHqjNjLJ.cjs';
@@ -106,6 +106,8 @@ interface AgentBackend {
     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. */
@@ -292,6 +294,138 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private toChunkStream;
 }
 
+/** How a renderer is likely to show a file. */
+type MessageFileKind = 'image' | 'pdf' | 'text' | 'audio' | 'video' | 'other';
+/** One file on a message, live or replayed, with what a renderer needs to decide how to show it. */
+interface MessageFile {
+    url: string;
+    mediaType: string;
+    /** The original name, or `null` when the part carried none. */
+    filename: string | null;
+    kind: MessageFileKind;
+    /** Lower-case extension from the name (`'pdf'`), or `null`. */
+    extension: string | null;
+    /** The stored media id — present on files replayed from history (`StoredMessage.attachments`). */
+    mediaId: string | null;
+}
+/** The {@link MessageFileKind} of a MIME type. */
+declare function fileKind(mediaType: string): MessageFileKind;
+/**
+ * The files on a message — the user's attachments (live, or replayed from `StoredMessage.attachments`
+ * by `storedMessageToUiMessage`) and any the model produced — in part order. Data only: pair it with
+ * your own thumbnails/links.
+ */
+declare function messageFiles(message: Pick<UIMessage, 'parts'>): MessageFile[];
+/**
+ * Whether `file` matches an `accept` list in the `<input accept>` grammar: MIME types
+ * (`application/pdf`), wildcards (`image/*`) and extensions (`.csv`). An empty list accepts all.
+ */
+declare function acceptsFile(accept: string | readonly string[] | undefined, file: Pick<File, 'name' | 'type'>): boolean;
+/** Files carried by a paste — screenshots and copied files. Text-only pastes give `[]`. */
+declare function filesFromClipboard(data: DataTransfer | null | undefined): File[];
+/** Whether a drag carries files (as opposed to text or a link) — gate your drop highlight on it. */
+declare function dragHasFiles(data: DataTransfer | null | undefined): boolean;
+
+/** Where one staged file stands. `rejected` never uploaded (validation); `error` can be retried. */
+type StagedAttachmentStatus = 'uploading' | 'ready' | 'error' | 'rejected';
+interface StagedAttachment {
+    /** Local id, stable for the item's life — use it as the React key and for `remove`/`retry`. */
+    id: string;
+    file: File;
+    name: string;
+    size: number;
+    type: string;
+    status: StagedAttachmentStatus;
+    /** 0..1 while uploading (0 until the backend reports progress), 1 once ready. */
+    progress: number;
+    /** Why it was rejected or failed. */
+    error?: string;
+    /** What the server returned — present once `ready`. */
+    attachment?: MessageAttachment;
+    /** An object URL for image previews (revoked on remove/unmount), when the runtime has one. */
+    previewUrl?: string;
+}
+/** Why a file was turned away before any upload. */
+type AttachmentRejection = 'type' | 'size' | 'count';
+interface UseAttachmentsOptions {
+    /**
+     * Upload one file — defaults to `backend.uploadAttachment`. Resolve with what the server
+     * answered; honour `signal` so `remove` can cancel; call `onProgress(0..1)` if you can.
+     */
+    upload?: (file: File, options: UploadAttachmentOptions) => Promise<MessageAttachment>;
+    /** Used for the default `upload`. One of `upload` / `backend` is required. */
+    backend?: AgentBackend;
+    /** `<input accept>` grammar: `'image/*,.pdf'` or `['image/*', 'application/pdf']`. */
+    accept?: string | readonly string[];
+    /** Per-file ceiling, in bytes. */
+    maxBytes?: number;
+    /** How many files may be staged at once (rejected ones do not count). */
+    maxFiles?: number;
+    /** Words for a rejection; default English. */
+    describeRejection?: (reason: AttachmentRejection, file: File) => string;
+}
+interface AttachmentsState {
+    items: StagedAttachment[];
+    /** Stage files: validate, then upload each that passes. */
+    add: (files: Iterable<File> | ArrayLike<File> | null | undefined) => void;
+    /** Drop an item, cancelling its upload. */
+    remove: (id: string) => void;
+    /** Upload a failed item again. */
+    retry: (id: string) => void;
+    /** Drop everything — call after a send. */
+    clear: () => void;
+    /** An upload is still running — hold the send button. */
+    isUploading: boolean;
+    /** What to send: the ready uploads, in order. */
+    attachments: MessageAttachment[];
+    /** The same, as the `{ mediaId }` refs `POST <base>/chat` takes. */
+    refs: Array<{
+        mediaId: string;
+    }>;
+    /** Props for a hidden `<input type="file">`: `accept`, `multiple`, `onChange`. */
+    inputProps: {
+        type: 'file';
+        accept: string | undefined;
+        multiple: boolean;
+        onChange: (event: {
+            currentTarget: HTMLInputElement;
+        }) => void;
+    };
+    /** Handlers for any element that should take dropped files. */
+    dropZoneProps: {
+        onDragEnter: (event: DragLikeEvent) => void;
+        onDragOver: (event: DragLikeEvent) => void;
+        onDragLeave: (event: DragLikeEvent) => void;
+        onDrop: (event: DragLikeEvent) => void;
+    };
+    /** Files are being dragged over the drop zone — for a highlight. */
+    isDragging: boolean;
+    /** Paste handler for the composer: stages pasted files (screenshots), leaves text alone. */
+    onPaste: (event: ClipboardLikeEvent) => void;
+}
+/** The slice of a React/DOM drag event these handlers read. */
+interface DragLikeEvent {
+    dataTransfer: DataTransfer | null;
+    preventDefault: () => void;
+}
+/** The slice of a React/DOM clipboard event `onPaste` reads. */
+interface ClipboardLikeEvent {
+    clipboardData: DataTransfer | null;
+    preventDefault: () => void;
+}
+/**
+ * Staged attachments for a composer, headless: validation (`accept`, `maxBytes`, `maxFiles`),
+ * one upload per file with progress and cancel, retry, previews, and the event handlers for a file
+ * input, a drop zone and paste — no markup, no styles. Send `attachments` (or `refs`) with the
+ * message, then `clear()`:
+ *
+ * ```ts
+ * await chat.sendMessage({ text }, { body: { attachments: files.refs } });
+ * files.clear();
+ * ```
+ */
+declare function useAttachments(options: UseAttachmentsOptions): AttachmentsState;
+
 interface UseAgentsOptions {
     /** `useAgentChat(...).backend`, or your own. Must implement `listAgents`. */
     backend: AgentBackend;
@@ -347,6 +481,34 @@ interface ModelsState {
  */
 declare function useModels(options: UseModelsOptions): ModelsState;
 
+interface UseQuotaOptions {
+    /** `useAgentChat(...).backend`, or your own. Must implement `getQuota`. */
+    backend: AgentBackend;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+    /** Re-read every `pollMs` ms as well. Default: only on mount, after runs, and on `refresh`. */
+    pollMs?: number;
+}
+interface QuotaState {
+    /** The full report, once loaded. */
+    report: QuotaReport | undefined;
+    windows: QuotaWindow[];
+    /** The `day` / `month` windows, when the server reports them. */
+    day: QuotaWindow | undefined;
+    month: QuotaWindow | undefined;
+    /** The window that blocks sends, or `null` — pass it to `useAgentChat({ blocked })`. */
+    blocked: QuotaBlock | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The caller's budget (`GET <base>/quota`): every window's usage against its ceilings, and which
+ * one — if any — blocks sends. Re-read after every run a chat on the same backend settles, so a
+ * meter moves with the conversation. Headless: draw the meter yourself.
+ */
+declare function useQuota(options: UseQuotaOptions): QuotaState;
+
 interface UseMessageFeedbackOptions {
     /** `useAgentChat(...).backend`, or your own. Must implement `setMessageFeedback`. */
     backend: AgentBackend;
@@ -540,12 +702,15 @@ declare class AgentClient implements AgentBackend {
      * 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>;
     /**
@@ -1373,6 +1538,12 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
     client?: B;
     /** Named agent to run each turn. */
     agent?: string;
+    /**
+     * The quota window blocking sends — `useQuota(...).blocked`. While set, `sendMessage` and
+     * `regenerate` refuse with {@link QuotaBlockedError} instead of starting a turn the server would
+     * refuse anyway.
+     */
+    blocked?: QuotaBlock | null;
     /**
      * Catalog model to run each turn on (see `useModels`), sent as the body's `model`. Read at every
      * send, so a picker can change it between turns. Omitted → the thread's pinned model, else the
@@ -1563,5 +1734,10 @@ declare function useAgentChat<B extends AgentBackend = AgentClient>(options: Use
     addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
     clearError: () => void;
 };
+/** A send refused on the client because a quota window is exhausted (`useAgentChat({ blocked })`). */
+declare class QuotaBlockedError extends Error {
+    readonly block: QuotaBlock;
+    constructor(block: QuotaBlock);
+}
 
-export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, 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 CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type MessageFeedbackInput, type MessageFeedbackState, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, 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 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 UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, 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, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ChatTransport, UIMessage, UIMessageChunk, DataUIPart, UIDataTypes } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaView, ModelCatalogView, AgentCatalogEntry, MessageFeedbackValue, MessageFeedback, ModelCatalogEntry, StoredMessage } 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';
 export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React__default from 'react';
 import { 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, T as TranscriptUiBlock } from './model-gHqjNjLJ.js';
@@ -106,6 +106,8 @@ interface AgentBackend {
     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. */
@@ -292,6 +294,138 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private toChunkStream;
 }
 
+/** How a renderer is likely to show a file. */
+type MessageFileKind = 'image' | 'pdf' | 'text' | 'audio' | 'video' | 'other';
+/** One file on a message, live or replayed, with what a renderer needs to decide how to show it. */
+interface MessageFile {
+    url: string;
+    mediaType: string;
+    /** The original name, or `null` when the part carried none. */
+    filename: string | null;
+    kind: MessageFileKind;
+    /** Lower-case extension from the name (`'pdf'`), or `null`. */
+    extension: string | null;
+    /** The stored media id — present on files replayed from history (`StoredMessage.attachments`). */
+    mediaId: string | null;
+}
+/** The {@link MessageFileKind} of a MIME type. */
+declare function fileKind(mediaType: string): MessageFileKind;
+/**
+ * The files on a message — the user's attachments (live, or replayed from `StoredMessage.attachments`
+ * by `storedMessageToUiMessage`) and any the model produced — in part order. Data only: pair it with
+ * your own thumbnails/links.
+ */
+declare function messageFiles(message: Pick<UIMessage, 'parts'>): MessageFile[];
+/**
+ * Whether `file` matches an `accept` list in the `<input accept>` grammar: MIME types
+ * (`application/pdf`), wildcards (`image/*`) and extensions (`.csv`). An empty list accepts all.
+ */
+declare function acceptsFile(accept: string | readonly string[] | undefined, file: Pick<File, 'name' | 'type'>): boolean;
+/** Files carried by a paste — screenshots and copied files. Text-only pastes give `[]`. */
+declare function filesFromClipboard(data: DataTransfer | null | undefined): File[];
+/** Whether a drag carries files (as opposed to text or a link) — gate your drop highlight on it. */
+declare function dragHasFiles(data: DataTransfer | null | undefined): boolean;
+
+/** Where one staged file stands. `rejected` never uploaded (validation); `error` can be retried. */
+type StagedAttachmentStatus = 'uploading' | 'ready' | 'error' | 'rejected';
+interface StagedAttachment {
+    /** Local id, stable for the item's life — use it as the React key and for `remove`/`retry`. */
+    id: string;
+    file: File;
+    name: string;
+    size: number;
+    type: string;
+    status: StagedAttachmentStatus;
+    /** 0..1 while uploading (0 until the backend reports progress), 1 once ready. */
+    progress: number;
+    /** Why it was rejected or failed. */
+    error?: string;
+    /** What the server returned — present once `ready`. */
+    attachment?: MessageAttachment;
+    /** An object URL for image previews (revoked on remove/unmount), when the runtime has one. */
+    previewUrl?: string;
+}
+/** Why a file was turned away before any upload. */
+type AttachmentRejection = 'type' | 'size' | 'count';
+interface UseAttachmentsOptions {
+    /**
+     * Upload one file — defaults to `backend.uploadAttachment`. Resolve with what the server
+     * answered; honour `signal` so `remove` can cancel; call `onProgress(0..1)` if you can.
+     */
+    upload?: (file: File, options: UploadAttachmentOptions) => Promise<MessageAttachment>;
+    /** Used for the default `upload`. One of `upload` / `backend` is required. */
+    backend?: AgentBackend;
+    /** `<input accept>` grammar: `'image/*,.pdf'` or `['image/*', 'application/pdf']`. */
+    accept?: string | readonly string[];
+    /** Per-file ceiling, in bytes. */
+    maxBytes?: number;
+    /** How many files may be staged at once (rejected ones do not count). */
+    maxFiles?: number;
+    /** Words for a rejection; default English. */
+    describeRejection?: (reason: AttachmentRejection, file: File) => string;
+}
+interface AttachmentsState {
+    items: StagedAttachment[];
+    /** Stage files: validate, then upload each that passes. */
+    add: (files: Iterable<File> | ArrayLike<File> | null | undefined) => void;
+    /** Drop an item, cancelling its upload. */
+    remove: (id: string) => void;
+    /** Upload a failed item again. */
+    retry: (id: string) => void;
+    /** Drop everything — call after a send. */
+    clear: () => void;
+    /** An upload is still running — hold the send button. */
+    isUploading: boolean;
+    /** What to send: the ready uploads, in order. */
+    attachments: MessageAttachment[];
+    /** The same, as the `{ mediaId }` refs `POST <base>/chat` takes. */
+    refs: Array<{
+        mediaId: string;
+    }>;
+    /** Props for a hidden `<input type="file">`: `accept`, `multiple`, `onChange`. */
+    inputProps: {
+        type: 'file';
+        accept: string | undefined;
+        multiple: boolean;
+        onChange: (event: {
+            currentTarget: HTMLInputElement;
+        }) => void;
+    };
+    /** Handlers for any element that should take dropped files. */
+    dropZoneProps: {
+        onDragEnter: (event: DragLikeEvent) => void;
+        onDragOver: (event: DragLikeEvent) => void;
+        onDragLeave: (event: DragLikeEvent) => void;
+        onDrop: (event: DragLikeEvent) => void;
+    };
+    /** Files are being dragged over the drop zone — for a highlight. */
+    isDragging: boolean;
+    /** Paste handler for the composer: stages pasted files (screenshots), leaves text alone. */
+    onPaste: (event: ClipboardLikeEvent) => void;
+}
+/** The slice of a React/DOM drag event these handlers read. */
+interface DragLikeEvent {
+    dataTransfer: DataTransfer | null;
+    preventDefault: () => void;
+}
+/** The slice of a React/DOM clipboard event `onPaste` reads. */
+interface ClipboardLikeEvent {
+    clipboardData: DataTransfer | null;
+    preventDefault: () => void;
+}
+/**
+ * Staged attachments for a composer, headless: validation (`accept`, `maxBytes`, `maxFiles`),
+ * one upload per file with progress and cancel, retry, previews, and the event handlers for a file
+ * input, a drop zone and paste — no markup, no styles. Send `attachments` (or `refs`) with the
+ * message, then `clear()`:
+ *
+ * ```ts
+ * await chat.sendMessage({ text }, { body: { attachments: files.refs } });
+ * files.clear();
+ * ```
+ */
+declare function useAttachments(options: UseAttachmentsOptions): AttachmentsState;
+
 interface UseAgentsOptions {
     /** `useAgentChat(...).backend`, or your own. Must implement `listAgents`. */
     backend: AgentBackend;
@@ -347,6 +481,34 @@ interface ModelsState {
  */
 declare function useModels(options: UseModelsOptions): ModelsState;
 
+interface UseQuotaOptions {
+    /** `useAgentChat(...).backend`, or your own. Must implement `getQuota`. */
+    backend: AgentBackend;
+    /** `false` holds the request. Default `true`. */
+    enabled?: boolean;
+    /** Re-read every `pollMs` ms as well. Default: only on mount, after runs, and on `refresh`. */
+    pollMs?: number;
+}
+interface QuotaState {
+    /** The full report, once loaded. */
+    report: QuotaReport | undefined;
+    windows: QuotaWindow[];
+    /** The `day` / `month` windows, when the server reports them. */
+    day: QuotaWindow | undefined;
+    month: QuotaWindow | undefined;
+    /** The window that blocks sends, or `null` — pass it to `useAgentChat({ blocked })`. */
+    blocked: QuotaBlock | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * The caller's budget (`GET <base>/quota`): every window's usage against its ceilings, and which
+ * one — if any — blocks sends. Re-read after every run a chat on the same backend settles, so a
+ * meter moves with the conversation. Headless: draw the meter yourself.
+ */
+declare function useQuota(options: UseQuotaOptions): QuotaState;
+
 interface UseMessageFeedbackOptions {
     /** `useAgentChat(...).backend`, or your own. Must implement `setMessageFeedback`. */
     backend: AgentBackend;
@@ -540,12 +702,15 @@ declare class AgentClient implements AgentBackend {
      * 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>;
     /**
@@ -1373,6 +1538,12 @@ interface UseAgentChatOptions<B extends AgentBackend = AgentClient> {
     client?: B;
     /** Named agent to run each turn. */
     agent?: string;
+    /**
+     * The quota window blocking sends — `useQuota(...).blocked`. While set, `sendMessage` and
+     * `regenerate` refuse with {@link QuotaBlockedError} instead of starting a turn the server would
+     * refuse anyway.
+     */
+    blocked?: QuotaBlock | null;
     /**
      * Catalog model to run each turn on (see `useModels`), sent as the body's `model`. Read at every
      * send, so a picker can change it between turns. Omitted → the thread's pinned model, else the
@@ -1563,5 +1734,10 @@ declare function useAgentChat<B extends AgentBackend = AgentClient>(options: Use
     addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
     clearError: () => void;
 };
+/** A send refused on the client because a quota window is exhausted (`useAgentChat({ blocked })`). */
+declare class QuotaBlockedError extends Error {
+    readonly block: QuotaBlock;
+    constructor(block: QuotaBlock);
+}
 
-export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, AnyToolUIPart, type ApprovalCountdown, ApproveOptions, 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 CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type MessageFeedbackInput, type MessageFeedbackState, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, MessageUsageInfo, type ModelOption, type ModelsState, 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 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 UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseMessageFeedbackOptions, type UseModelsOptions, type UseSpeechRecognitionOptions, type UseThreadsOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, createSkillsSource, filterAutocompleteItems, findActiveTrigger, formatElapsed, loadStoredSpeechLang, notifyThreads, onThreadsEvent, persistSpeechLang, readReasoningMs, requireBackendMethod, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useAgents, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };
+export { type AgentBackend, AgentBackendUnsupportedError, AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentMessageMetadata, type AgentStreamMeta, type AgentsState, type AggregatedTurnUsage, 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, useApprovalCountdown, useAttachments, useChatTranscript, useComposerAutocomplete, useElapsed, useMessageFeedback, useModels, useQuota, useSpeechRecognition, useStickToBottom, useThreads, useToolCatalog, useTranscriptItem };