@deuz-sdk/react 1.7.1 → 1.9.0

package/dist/index.d.ts

@@ -1,11 +1,28 @@
-import { Message, ToolApprovalRequest, ToolApprovalResponse, DeepPartial } from '@deuz-sdk/core';
+import { Message, ToolApprovalRequest, Usage, FinishReason, ToolApprovalResponse, ImagePart, DeepPartial } from '@deuz-sdk/core';
 export { Message, ToolApprovalRequest, ToolApprovalResponse } from '@deuz-sdk/core';
-import { UIMessage, AssistantTurnState } from '@deuz-sdk/core/chat';
-export { AssistantTurnState, ChatHistory, UIMessage, UIToolCall } from '@deuz-sdk/core/chat';
+import { UIMessage, ChatHistory, UIToolCall, AssistantTurnState, ChatInput } from '@deuz-sdk/core/chat';
+export { AssistantTurnState, ChatHistory, ChatInput, UIMessage, UIMessagePart, UIToolCall } from '@deuz-sdk/core/chat';
 import * as react from 'react';
 import { ReactNode } from 'react';
 export { DeuzUIPart } from '@deuz-sdk/core/ui';
 
+/**
+ * Picked files → canonical parts for a {@link ChatInput}. A thin, null-tolerant
+ * wrapper over core's `filesToImageParts`: the bytes work (Web APIs only, no
+ * `FileReader`, no `Buffer`) lives THERE and is deliberately not reimplemented
+ * here. `ImagePart` is the single carrier for all binary media, so images and
+ * PDFs both ride this call.
+ *
+ * ```tsx
+ * <input type="file" multiple onChange={async (e) => {
+ *   const parts = await partsFromFiles(e.target.files);
+ *   await sendMessage({ text: 'what is in these?', parts });
+ * }} />
+ * ```
+ */
+declare function partsFromFiles(files: FileList | Iterable<Blob & {
+    type?: string;
+}> | null | undefined): Promise<ImagePart[]>;
 /** Live cumulative USD cost, from the wire's `cost` parts (last one wins). */
 interface UseChatCost {
     costUsd: number;
@@ -17,6 +34,21 @@ interface UseChatBudgetExceeded {
     limit: number;
     value: number;
 }
+/**
+ * Where the resume cursor lives ACROSS a page reload.
+ *
+ * An adapter rather than a hardcoded `localStorage`: core's own
+ * `connectDeuzStream` frames the cursor as the caller's choice, and hardcoding
+ * web storage would break SSR (no `window`), React Native (no `localStorage`)
+ * and privacy modes that throw on write. Both methods may throw — the hook
+ * swallows it, because losing a cursor must never kill a live stream.
+ */
+interface UseChatCursorStore {
+    /** The persisted cursor, or `undefined` when there is nothing to resume. */
+    load(): string | undefined;
+    /** Persist the cursor. Called on every advance. */
+    save(id: string): void;
+}
 interface UseChatResumeOptions {
     /**
      * Resume endpoint (see core's `resumeDeuzStreamResponse`): a GET URL or a
@@ -28,59 +60,207 @@ interface UseChatResumeOptions {
     }) => Response | Promise<Response>);
     /** Cursor to resume from (e.g. persisted across a page reload). */
     lastEventId?: string;
+    /**
+     * Attempt `reconnect()` ONCE per mounted hook — the canonical scenario
+     * resumability exists for (the user refreshes mid-generation) with zero app
+     * wiring. Fires exactly once under React 18/19 StrictMode's deliberate
+     * mount → unmount → mount double-invoke.
+     *
+     * An AUTOMATIC attempt that fails is NOT an error state and does NOT reach
+     * `onError`: the user did not ask for it, and every cold load of a chat app
+     * whose resume endpoint answers 404 (nothing in flight) would otherwise paint
+     * a permanent error. A caught-up endpoint (immediate `[DONE]`) is a silent
+     * no-op — no bubble, no state change. Call `reconnect()` yourself when you
+     * want the failure surfaced.
+     */
+    auto?: boolean;
+    /** Cursor persistence adapter (see {@link UseChatCursorStore}). */
+    cursor?: UseChatCursorStore;
 }
 interface UseChatOptions {
     /** Endpoint serving `toDeuzStreamResponse` output. */
     api: string;
-    /** Seed canonical history (e.g. restored from a ChatStore) — rendered via `uiFromMessages`. */
+    /**
+     * Seed canonical history (e.g. restored from a ChatStore) — rendered via
+     * `uiFromMessages`.
+     *
+     * READ ONCE, at mount, like any `useState` initial value. It is deliberately
+     * NOT re-adopted when the prop changes: apps pass an inline array literal, so
+     * a new identity arrives on EVERY render and adopting it would reset the
+     * transcript continuously — and mid-stream it would clobber the turn being
+     * folded. Switching chats or hydrating later is an explicit action: call
+     * `setHistory` (both views) or `setMessages` (re-derives canonical).
+     */
     initialMessages?: Message[];
     headers?: Record<string, string>;
     /** Extra fields merged into every request body. */
     body?: Record<string, unknown>;
     /** Chat identity — merged into every request body (server-side ChatStore persistence). */
     chatId?: string;
-    /** Enables `reconnect()` against a resume endpoint (wire v2, `connectDeuzStream`). */
+    /** Enables `reconnect()` / `resume.auto` against a resume endpoint (wire v2). */
     resume?: UseChatResumeOptions;
     /** Id source for UI messages/turns. Default: `crypto.randomUUID` (with a fallback). */
     generateId?: () => string;
+    /**
+     * Coalesce React commits to at most one per `throttleMs` (trailing edge).
+     * Default `0` — commit on every wire part, exactly as 1.8 did.
+     *
+     * A fast model emits hundreds of text deltas per second; with markdown
+     * rendering over a long transcript that visibly janks. The terminal frame is
+     * ALWAYS flushed (stream end, error, abort, an external tool result), so the
+     * final text can never be lost to coalescing. A plain `setTimeout` is fine
+     * here: unlike core's `src/**`, this package is not edge-lint-constrained and
+     * has no `deps.clock` seam.
+     */
+    throttleMs?: number;
     /**
      * Client-tool executor: called for every streamed tool call the SERVER did
      * not execute. The return value is appended as its tool_result and the chat
      * auto-continues; a throw self-heals as an is_error result.
+     *
+     * OMIT it to drive client tools from outside the hook instead: the
+     * round-trip PARKS, the calls appear in `pendingToolCalls`, and
+     * `addToolResult` answers them.
      */
     onToolCall?: (call: {
         toolCallId: string;
         toolName: string;
         input: unknown;
     }) => Promise<unknown> | unknown;
+    /**
+     * Fired for every `data-{name}` part as it arrives, BEFORE reconciliation —
+     * so a caller sees each intermediate write of an addressable `(name, id)`
+     * entry, which `dataParts` collapses to the last one. A throw is swallowed
+     * (G2: a consumer callback is not a transport error).
+     */
+    onData?: (data: {
+        name: string;
+        id?: string;
+        payload: unknown;
+    }) => void;
     onError?: (error: Error) => void;
+    /**
+     * How a NON-2xx response from `api` is reported (default `'error-part'`: the
+     * failure becomes `status: 'error'` instead of an empty assistant bubble).
+     * Forwarded verbatim to core's `readDeuzStream`.
+     */
+    onHttpError?: 'error-part' | 'ignore';
     /** Injectable for tests / custom transports. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
 interface UseChatResult {
+    /** The render view. Each message carries its ordered `parts` (1.9) when it has any. */
     messages: UIMessage[];
+    /**
+     * BOTH views in one object (`{ ui, canonical }`). Only the canonical one is
+     * POSTable and only it survives a round-trip through a provider, so an app
+     * that persists a chat should persist `history.canonical`. Identity is stable
+     * until either view changes.
+     */
+    history: ChatHistory;
     status: 'idle' | 'streaming' | 'error';
     error: Error | undefined;
     /** Gated tool calls awaiting verdicts — the chat is PAUSED while non-empty. */
     pendingApprovals: ToolApprovalRequest[];
+    /**
+     * Client tool calls the round-trip is PARKED on (no `onToolCall` executor).
+     * Answer each with `addToolResult`; the chat continues once all are answered.
+     */
+    pendingToolCalls: UIToolCall[];
     /** Live cumulative cost from the wire's `cost` parts (last one wins). */
     cost?: UseChatCost;
     /** Set when the server's budget guardrail tripped this turn. */
     budgetExceeded?: UseChatBudgetExceeded;
-    /** This turn's app-defined `data-{name}` parts, in arrival order. */
+    /**
+     * This turn's app-defined `data-{name}` parts. Entries written with an `id`
+     * are RECONCILED by `(name, id)` — one live status widget stays one entry, at
+     * its original position — while id-less entries stay append-only (1.7/1.8).
+     */
     dataParts: Array<{
         name: string;
+        id?: string;
         payload: unknown;
     }>;
     /** This turn's RAG citations. */
     citations: AssistantTurnState['citations'];
-    sendMessage: (text: string) => Promise<void>;
+    /** Latest live plan snapshot for this turn (autonomous runs, 1.8). */
+    plan?: AssistantTurnState['plan'];
+    /** This turn's live activity feed ("Computer" view, 1.8). */
+    activity: AssistantTurnState['activity'];
+    /** This turn's `verifyStep` verdicts, in arrival order (1.9). */
+    verifications?: AssistantTurnState['verifications'];
+    /**
+     * Non-fatal execution notices for this turn, in arrival order (1.9): a
+     * sampling param the wire could not carry, a clamped ceiling, an unknown model
+     * slug served from the conservative fallback row. Render them as a dismissible
+     * banner — the run itself succeeded.
+     */
+    warnings?: AssistantTurnState['warnings'];
+    /**
+     * `false-finish` rejections for this turn (1.9): the server's guard decided
+     * the work was not actually done. A trailing entry with `willRetry: false`
+     * means the guard's budget ran out, so the answer on screen is the one it
+     * stopped on rather than one it was happy with.
+     */
+    falseFinishes?: AssistantTurnState['falseFinishes'];
+    /**
+     * Live sub-agent (`agentTool`) frames for this turn, one per `agentPath`
+     * (1.9). Each holds the child's OWN turn — its text, ordered `parts` and tool
+     * cards — so a delegated run is renderable instead of invisible, and
+     * `afterPart` says where in the parent's `parts` it belongs. Nothing here is
+     * mixed into the parent's `content`: a sub-agent's words are its own.
+     */
+    subAgents?: AssistantTurnState['subAgents'];
+    /** Per-step usage/finish from `step-finish` parts, in arrival order (1.9). */
+    steps?: AssistantTurnState['steps'];
+    /** Terminal token usage for this turn, from the wire's `finish` part (1.9). */
+    usage?: Usage;
+    /** Terminal finish reason (1.9) — `'length'` means the answer was truncated. */
+    finishReason?: FinishReason;
+    /**
+     * Send one user turn: plain text (1.8-identical, including the canonical
+     * `content` string) or text plus canonical parts — images/PDFs from
+     * {@link partsFromFiles}, `imagePart`/`filePart`, anything the wires accept.
+     */
+    sendMessage: (input: ChatInput) => Promise<void>;
     /** Abort the in-flight stream (not an error). */
     stop: () => void;
     /** Drop the trailing assistant/tool turns (core `dropTrailingAssistant`) and re-run. */
     regenerate: () => Promise<void>;
-    /** Cut history before `messageId` (core `branchBeforeUserMessage`) and send `text`. */
-    editAndResend: (messageId: string, text: string) => Promise<void>;
+    /** Cut history before `messageId` (core `branchBeforeUserMessage`) and send `input`. */
+    editAndResend: (messageId: string, input: ChatInput) => Promise<void>;
+    /**
+     * Replace BOTH views in one commit — the honest primitive, because Deuz keeps
+     * two of them and only the canonical one is POSTable. Use it to switch chats,
+     * hydrate after mount, or delete/edit a rendered message while keeping a
+     * system prompt and provider round-trip data that the UI view cannot carry.
+     *
+     * Pending gates (approvals, parked client tool calls) are DROPPED: they were
+     * anchored to the transcript you just replaced.
+     */
+    setHistory: (update: ChatHistory | ((prev: ChatHistory) => ChatHistory)) => void;
+    /**
+     * Sugar over `setHistory`: re-derives the canonical view with core's
+     * `canonicalFromUI`. That inverse projection is LOSSY — system messages,
+     * `Message.providerMetadata` and UI-only state do not survive it, and a
+     * message without ordered `parts` loses its attachments entirely — so drive
+     * `setHistory` directly when your history has any of those.
+     */
+    setMessages: (update: UIMessage[] | ((prev: UIMessage[]) => UIMessage[])) => void;
+    /**
+     * Answer ONE parked client tool call from outside the hook. Feeds the exact
+     * path `onToolCall`'s return value takes (core `clientToolResultMessage`), so
+     * the chat auto-continues once every call in `pendingToolCalls` is answered.
+     * A result for an id that is not parked is ignored — an orphan `tool_result`
+     * would 400 the next request.
+     */
+    addToolResult: (result: {
+        toolCallId: string;
+        output: unknown;
+        isError?: boolean;
+    }) => Promise<void>;
+    /** Dismiss the error: `status: 'error'` → `'idle'`. Leaves a live stream alone. */
+    clearError: () => void;
     /**
      * Record one verdict (the request's signed `token` is auto-preserved). Once
      * EVERY pending approval has a verdict, the chat auto-resumes with
@@ -99,6 +279,17 @@ interface UseObjectOptions {
     /** Endpoint serving `toDeuzObjectStreamResponse` output. */
     api: string;
     headers?: Record<string, string>;
+    /**
+     * How a NON-2xx response from `api` is reported (default `'error-part'`,
+     * which lands in `error`). Forwarded verbatim to core's `readDeuzStream`.
+     */
+    onHttpError?: 'error-part' | 'ignore';
+    /**
+     * Coalesce partials to at most one React commit per `throttleMs` (trailing
+     * edge). Default `0` — commit every partial, exactly as 1.8 did. The final
+     * partial is ALWAYS flushed, so the completed object is never lost.
+     */
+    throttleMs?: number;
     /** Injectable for tests / custom transports. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -139,4 +330,4 @@ interface CostBadgeProps {
 /** Live cost readout: `$X.XXXX`, plus ` (saved $Y.YYYY)` when caching saved money. */
 declare function CostBadge({ cost, format }: CostBadgeProps): react.JSX.Element | null;
 
-export { CostBadge, type CostBadgeProps, ToolApprovalCard, type ToolApprovalCardProps, type UseChatBudgetExceeded, type UseChatCost, type UseChatOptions, type UseChatResult, type UseChatResumeOptions, type UseObjectOptions, type UseObjectResult, useChat, useObject };
+export { CostBadge, type CostBadgeProps, ToolApprovalCard, type ToolApprovalCardProps, type UseChatBudgetExceeded, type UseChatCost, type UseChatCursorStore, type UseChatOptions, type UseChatResult, type UseChatResumeOptions, type UseObjectOptions, type UseObjectResult, partsFromFiles, useChat, useObject };