@deuz-sdk/react 2.2.0 → 2.3.0

package/dist/index.d.cts

@@ -1,11 +1,23 @@
 import { Message, ToolApprovalRequest, Usage, FinishReason, ToolApprovalResponse, ImagePart, DeepPartial } from '@deuz-sdk/core';
 export { Message, ToolApprovalRequest, ToolApprovalResponse } from '@deuz-sdk/core';
-import { UIMessage, ChatHistory, UIToolCall, AssistantTurnState, ChatInput } from '@deuz-sdk/core/chat';
+import { AssistantTurnState, UIMessage, ChatHistory, UIToolCall, 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';
 
+/**
+ * The native agent run a turn carries (2.3): core's `DeuzAgentState`, read off
+ * `AssistantTurnState.agent`. Derived rather than imported, so these types
+ * still compile against a core older than 2.3 (where it is `unknown`).
+ */
+type UseChatAgent = AssistantTurnState extends {
+    agent?: infer A;
+} ? Exclude<A, undefined> : unknown;
+/** The provider's explanation of a stop (2.3): core's `StopDetails`, derived like `UseChatAgent`. */
+type UseChatStopDetails = AssistantTurnState extends {
+    stopDetails?: infer S;
+} ? Exclude<S, undefined> : unknown;
 /**
  * Picked files → canonical parts for a {@link ChatInput}. A thin, null-tolerant
  * wrapper over core's `filesToImageParts`: the bytes work (Web APIs only, no
@@ -71,10 +83,21 @@ interface UseChatResumeOptions {
      * 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.
+     * want the failure surfaced. Only the READ is silent: when the replayed turn
+     * continues the chat (2.3 — `onToolCall` answered its client calls), that
+     * POST to `api` reports a failure like any other.
      */
     auto?: boolean;
-    /** Cursor persistence adapter (see {@link UseChatCursorStore}). */
+    /**
+     * Cursor persistence adapter (see {@link UseChatCursorStore}). Only reads
+     * through `endpoint` save the cursor, so it marks how far the RESUME reads
+     * got. (Since 2.3 a POST response that carries the journal's `id:` lines
+     * moves the hook's in-memory cursor too, so a `reconnect()` within the same
+     * mounted hook resumes after what the POST read delivered; it is not saved
+     * here, because a reload mid-turn must replay that turn from its start.
+     * `setHistory` drops that in-memory cursor, so a chat switch never sends
+     * one chat's cursor to another chat's endpoint.)
+     */
     cursor?: UseChatCursorStore;
 }
 interface UseChatOptions {
@@ -116,11 +139,23 @@ interface UseChatOptions {
     /**
      * 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.
+     * auto-continues; a throw self-heals as an is_error result. A result that
+     * lands after the chat moved on (a new message, a regenerate, a replaced
+     * history) is dropped (2.3).
      *
      * OMIT it to drive client tools from outside the hook instead: the
      * round-trip PARKS, the calls appear in `pendingToolCalls`, and
      * `addToolResult` answers them.
+     *
+     * Since 2.3 a turn read back through `reconnect()` / `resume.auto` reaches
+     * this the same way. A replayed call is dispatched AT MOST ONCE per mounted
+     * hook: not when the canonical history already holds its result, and not
+     * while it is parked or still running. Across a reload that evidence is the
+     * history the app restored — a call whose result was not persisted before
+     * the page went away runs again, so make such tools idempotent, or omit
+     * `onToolCall` and confirm parked calls yourself. A tab that only WATCHES a
+     * stream another tab drives should omit it too, or it would run that tab's
+     * calls.
      */
     onToolCall?: (call: {
         toolCallId: string;
@@ -160,11 +195,15 @@ interface UseChatResult {
     history: ChatHistory;
     status: 'idle' | 'streaming' | 'error';
     error: Error | undefined;
-    /** Gated tool calls awaiting verdicts — the chat is PAUSED while non-empty. */
+    /**
+     * Gated tool calls awaiting verdicts — the chat is PAUSED while non-empty.
+     * One entry per request: a repeated wire frame does not add a second card.
+     */
     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.
+     * A turn read back through `reconnect()` parks its calls here too (2.3).
      */
     pendingToolCalls: UIToolCall[];
     /** Live cumulative cost from the wire's `cost` parts (last one wins). */
@@ -217,6 +256,22 @@ interface UseChatResult {
     usage?: Usage;
     /** Terminal finish reason (1.9) — `'length'` means the answer was truncated. */
     finishReason?: FinishReason;
+    /**
+     * The provider's explanation of this turn's stop (2.3), from the wire's
+     * `finish`: with `finishReason: 'content_filter'`, a refusal's `category`
+     * and `explanation`. Absent when the provider explained nothing.
+     */
+    stopDetails?: UseChatStopDetails;
+    /**
+     * The native agent run behind this turn (2.3), on a route that serves
+     * `toDeuzAgentStreamResponse`: its `runId`, `status` (`'running'`,
+     * `'suspended'`, `'completed'`, `'stopped'`, `'failed'`), the latest `partial`
+     * draft while it runs, and — only once `completed` — the `output` the server
+     * validated. Absent on a chat route. Pending approvals and client calls of a
+     * suspended run also appear in `pendingApprovals` / `pendingToolCalls`, and
+     * the hook resumes the run with them.
+     */
+    agent?: UseChatAgent;
     /**
      * Send one user turn: plain text (1.8-identical, including the canonical
      * `content` string) or text plus canonical parts — images/PDFs from
@@ -236,7 +291,9 @@ interface UseChatResult {
      * 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.
+     * anchored to the transcript you just replaced. So is the in-memory resume
+     * cursor (2.3), which addresses that transcript's stream: the next
+     * `reconnect()` reads from the persisted cursor or from the start.
      */
     setHistory: (update: ChatHistory | ((prev: ChatHistory) => ChatHistory)) => void;
     /**
@@ -263,13 +320,32 @@ interface UseChatResult {
     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
+     * EVERY pending approval has a verdict, the chat auto-resumes ONCE with
      * `approvalResponses` in the request body.
+     *
+     * The verdict must answer an approval in `pendingApprovals`: its
+     * `approvalId`, and — when the verdict carries a `token` — that request's
+     * token, which binds it to the run that issued it. ANYTHING ELSE IS A NO-OP
+     * (2.3): no request, no state change, and the promise resolves — the same
+     * contract as `addToolResult`. That covers a verdict with nothing pending, a
+     * repeat of one already sent (a double click), a card left over from an
+     * earlier turn or a replaced transcript, and another run's verdict. Before
+     * the last verdict lands, answering an approval again replaces its verdict.
      */
     addToolApprovalResponse: (response: ToolApprovalResponse) => Promise<void>;
     /**
      * Re-read the stream from `resume.endpoint` via `connectDeuzStream` and fold
      * the parts into the current turn. No-op unless `options.resume` is set.
+     *
+     * The read turn settles exactly like a streamed one (2.3): its approvals
+     * pause the chat, its unresolved client calls reach `onToolCall` (and the
+     * chat continues with a POST) or `pendingToolCalls`, and a call the replay
+     * re-delivers after this client answered it is not dispatched again. A
+     * `stop()` during the read settles nothing; the next call continues it.
+     *
+     * Since 2.3 a POST read whose response carries the journal's event ids
+     * moves the cursor too, so a reconnect after a settled turn resumes after
+     * it and appends nothing the hook already holds.
      */
     reconnect: () => Promise<void>;
 }
@@ -330,4 +406,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 UseChatCursorStore, type UseChatOptions, type UseChatResult, type UseChatResumeOptions, type UseObjectOptions, type UseObjectResult, partsFromFiles, useChat, useObject };
+export { CostBadge, type CostBadgeProps, ToolApprovalCard, type ToolApprovalCardProps, type UseChatAgent, type UseChatBudgetExceeded, type UseChatCost, type UseChatCursorStore, type UseChatOptions, type UseChatResult, type UseChatResumeOptions, type UseChatStopDetails, type UseObjectOptions, type UseObjectResult, partsFromFiles, useChat, useObject };

package/dist/index.d.ts

@@ -1,11 +1,23 @@
 import { Message, ToolApprovalRequest, Usage, FinishReason, ToolApprovalResponse, ImagePart, DeepPartial } from '@deuz-sdk/core';
 export { Message, ToolApprovalRequest, ToolApprovalResponse } from '@deuz-sdk/core';
-import { UIMessage, ChatHistory, UIToolCall, AssistantTurnState, ChatInput } from '@deuz-sdk/core/chat';
+import { AssistantTurnState, UIMessage, ChatHistory, UIToolCall, 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';
 
+/**
+ * The native agent run a turn carries (2.3): core's `DeuzAgentState`, read off
+ * `AssistantTurnState.agent`. Derived rather than imported, so these types
+ * still compile against a core older than 2.3 (where it is `unknown`).
+ */
+type UseChatAgent = AssistantTurnState extends {
+    agent?: infer A;
+} ? Exclude<A, undefined> : unknown;
+/** The provider's explanation of a stop (2.3): core's `StopDetails`, derived like `UseChatAgent`. */
+type UseChatStopDetails = AssistantTurnState extends {
+    stopDetails?: infer S;
+} ? Exclude<S, undefined> : unknown;
 /**
  * Picked files → canonical parts for a {@link ChatInput}. A thin, null-tolerant
  * wrapper over core's `filesToImageParts`: the bytes work (Web APIs only, no
@@ -71,10 +83,21 @@ interface UseChatResumeOptions {
      * 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.
+     * want the failure surfaced. Only the READ is silent: when the replayed turn
+     * continues the chat (2.3 — `onToolCall` answered its client calls), that
+     * POST to `api` reports a failure like any other.
      */
     auto?: boolean;
-    /** Cursor persistence adapter (see {@link UseChatCursorStore}). */
+    /**
+     * Cursor persistence adapter (see {@link UseChatCursorStore}). Only reads
+     * through `endpoint` save the cursor, so it marks how far the RESUME reads
+     * got. (Since 2.3 a POST response that carries the journal's `id:` lines
+     * moves the hook's in-memory cursor too, so a `reconnect()` within the same
+     * mounted hook resumes after what the POST read delivered; it is not saved
+     * here, because a reload mid-turn must replay that turn from its start.
+     * `setHistory` drops that in-memory cursor, so a chat switch never sends
+     * one chat's cursor to another chat's endpoint.)
+     */
     cursor?: UseChatCursorStore;
 }
 interface UseChatOptions {
@@ -116,11 +139,23 @@ interface UseChatOptions {
     /**
      * 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.
+     * auto-continues; a throw self-heals as an is_error result. A result that
+     * lands after the chat moved on (a new message, a regenerate, a replaced
+     * history) is dropped (2.3).
      *
      * OMIT it to drive client tools from outside the hook instead: the
      * round-trip PARKS, the calls appear in `pendingToolCalls`, and
      * `addToolResult` answers them.
+     *
+     * Since 2.3 a turn read back through `reconnect()` / `resume.auto` reaches
+     * this the same way. A replayed call is dispatched AT MOST ONCE per mounted
+     * hook: not when the canonical history already holds its result, and not
+     * while it is parked or still running. Across a reload that evidence is the
+     * history the app restored — a call whose result was not persisted before
+     * the page went away runs again, so make such tools idempotent, or omit
+     * `onToolCall` and confirm parked calls yourself. A tab that only WATCHES a
+     * stream another tab drives should omit it too, or it would run that tab's
+     * calls.
      */
     onToolCall?: (call: {
         toolCallId: string;
@@ -160,11 +195,15 @@ interface UseChatResult {
     history: ChatHistory;
     status: 'idle' | 'streaming' | 'error';
     error: Error | undefined;
-    /** Gated tool calls awaiting verdicts — the chat is PAUSED while non-empty. */
+    /**
+     * Gated tool calls awaiting verdicts — the chat is PAUSED while non-empty.
+     * One entry per request: a repeated wire frame does not add a second card.
+     */
     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.
+     * A turn read back through `reconnect()` parks its calls here too (2.3).
      */
     pendingToolCalls: UIToolCall[];
     /** Live cumulative cost from the wire's `cost` parts (last one wins). */
@@ -217,6 +256,22 @@ interface UseChatResult {
     usage?: Usage;
     /** Terminal finish reason (1.9) — `'length'` means the answer was truncated. */
     finishReason?: FinishReason;
+    /**
+     * The provider's explanation of this turn's stop (2.3), from the wire's
+     * `finish`: with `finishReason: 'content_filter'`, a refusal's `category`
+     * and `explanation`. Absent when the provider explained nothing.
+     */
+    stopDetails?: UseChatStopDetails;
+    /**
+     * The native agent run behind this turn (2.3), on a route that serves
+     * `toDeuzAgentStreamResponse`: its `runId`, `status` (`'running'`,
+     * `'suspended'`, `'completed'`, `'stopped'`, `'failed'`), the latest `partial`
+     * draft while it runs, and — only once `completed` — the `output` the server
+     * validated. Absent on a chat route. Pending approvals and client calls of a
+     * suspended run also appear in `pendingApprovals` / `pendingToolCalls`, and
+     * the hook resumes the run with them.
+     */
+    agent?: UseChatAgent;
     /**
      * Send one user turn: plain text (1.8-identical, including the canonical
      * `content` string) or text plus canonical parts — images/PDFs from
@@ -236,7 +291,9 @@ interface UseChatResult {
      * 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.
+     * anchored to the transcript you just replaced. So is the in-memory resume
+     * cursor (2.3), which addresses that transcript's stream: the next
+     * `reconnect()` reads from the persisted cursor or from the start.
      */
     setHistory: (update: ChatHistory | ((prev: ChatHistory) => ChatHistory)) => void;
     /**
@@ -263,13 +320,32 @@ interface UseChatResult {
     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
+     * EVERY pending approval has a verdict, the chat auto-resumes ONCE with
      * `approvalResponses` in the request body.
+     *
+     * The verdict must answer an approval in `pendingApprovals`: its
+     * `approvalId`, and — when the verdict carries a `token` — that request's
+     * token, which binds it to the run that issued it. ANYTHING ELSE IS A NO-OP
+     * (2.3): no request, no state change, and the promise resolves — the same
+     * contract as `addToolResult`. That covers a verdict with nothing pending, a
+     * repeat of one already sent (a double click), a card left over from an
+     * earlier turn or a replaced transcript, and another run's verdict. Before
+     * the last verdict lands, answering an approval again replaces its verdict.
      */
     addToolApprovalResponse: (response: ToolApprovalResponse) => Promise<void>;
     /**
      * Re-read the stream from `resume.endpoint` via `connectDeuzStream` and fold
      * the parts into the current turn. No-op unless `options.resume` is set.
+     *
+     * The read turn settles exactly like a streamed one (2.3): its approvals
+     * pause the chat, its unresolved client calls reach `onToolCall` (and the
+     * chat continues with a POST) or `pendingToolCalls`, and a call the replay
+     * re-delivers after this client answered it is not dispatched again. A
+     * `stop()` during the read settles nothing; the next call continues it.
+     *
+     * Since 2.3 a POST read whose response carries the journal's event ids
+     * moves the cursor too, so a reconnect after a settled turn resumes after
+     * it and appends nothing the hook already holds.
      */
     reconnect: () => Promise<void>;
 }
@@ -330,4 +406,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 UseChatCursorStore, type UseChatOptions, type UseChatResult, type UseChatResumeOptions, type UseObjectOptions, type UseObjectResult, partsFromFiles, useChat, useObject };
+export { CostBadge, type CostBadgeProps, ToolApprovalCard, type ToolApprovalCardProps, type UseChatAgent, type UseChatBudgetExceeded, type UseChatCost, type UseChatCursorStore, type UseChatOptions, type UseChatResult, type UseChatResumeOptions, type UseChatStopDetails, type UseObjectOptions, type UseObjectResult, partsFromFiles, useChat, useObject };