@dudousxd/nestjs-agent-react 0.7.5 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as ai from 'ai';
-import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart } from 'ai';
+import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart, DataUIPart, UIDataTypes } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
 import { StoredMessage, ThreadSummary, SkillCatalogEntry, ThreadDetail, MessageAttachment, QuotaView } from '@dudousxd/nestjs-agent-core';
 import React from 'react';
@@ -69,6 +69,15 @@ interface AgentChatTransportOptions {
  * message, and are rendered as native model content parts. Optimistic display of
  * the user's own attachment thumbnails is the consumer's concern (it stages the
  * upload), the same way history rendering reads `StoredMessage.attachments`.
+ *
+ * Frames beyond text/reasoning/tools become AI SDK data parts (seen by `useChat`'s `onData`):
+ *  - `ui`                 → `data-ui` part, `id` = the component id (a repeat id updates it in place)
+ *  - `approval-requested` → `data-approval-requested` part keyed by the call id, plus the SDK's
+ *                           native `tool-approval-request` (the part moves to `approval-requested`)
+ *  - `title`, `cancelled` → transient `data-title` / `data-cancelled` (never stored on the message)
+ *  - any other kind       → `data-<kind>` part carrying the frame minus `kind`, keyed by its `id`
+ *                           when it has one — forwarded, never dropped
+ * `parentId` on a tool frame rides the part's `toolMetadata` next to `toolKind`.
  */
 declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private readonly options;
@@ -105,7 +114,8 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
      * Parse the backend's SSE byte stream and re-emit it as a valid v7 UI-message chunk stream.
      * Recognized frames:
      *  - `event: meta`  `data: {"runId","threadId"}`   → records identity
-     *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool)
+     *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool /
+     *                                                     `data-*`; see {@link AgentChatTransport} docs)
      *  - `event: done`  `data: {}`                      → terminates
      *  - `event: error` `data: {code,message}`          → error chunk
      *
@@ -335,6 +345,12 @@ interface TranscriptReasoningBlock {
     key: string;
     text: string;
     isStreaming: boolean;
+    /**
+     * How long the model thought, in ms — the backend's measurement once the run closed (live) or as
+     * persisted (reloaded). `null` while it still streams, or when nothing was recorded: pair it with
+     * `useElapsed(block.isStreaming)` for a ticking label (`block.durationMs ?? elapsed`).
+     */
+    durationMs: number | null;
     isOpen: boolean;
     toggle: (open?: boolean) => void;
 }
@@ -352,11 +368,33 @@ interface TranscriptSettleState {
     isSubmitting: boolean;
     run: () => void;
 }
+/**
+ * Who has to settle a parked call, and until when — from the stream's `approval-requested` frame.
+ * `null` on a call whose runner never said (the call can still be awaiting approval).
+ */
+interface TranscriptApproval {
+    /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
+    approver: string;
+    /** ISO-8601; `null` when the request never lapses. */
+    expiresAt: string | null;
+    reason: string | null;
+}
 /** One call in a tool run, with whatever human decision it is parked on. */
 interface TranscriptToolCall {
     part: AnyToolUIPart;
     toolCallId: string;
     name: string;
+    /** `read` / `action` as the stream classified the call; `null` when the backend did not say. */
+    toolKind: string | null;
+    /** The call this one ran inside (a code-mode `execute`, a delegated agent); `null` for a top-level call. */
+    parentId: string | null;
+    /**
+     * Calls nested under this one within the same block, in stream order. Always empty for a call
+     * nothing names as its parent.
+     */
+    children: TranscriptToolCall[];
+    /** Who has to decide, when the runner said so. See {@link TranscriptApproval}. */
+    approval: TranscriptApproval | null;
     /**
      * Parked on a person. An `action` tool's input lands and its output never follows on its own —
      * the loop waits for an approval between the two — so a settled-looking card that never settles
@@ -379,6 +417,25 @@ interface TranscriptToolBlock {
     parts: AnyToolUIPart[];
     /** The same calls, each with its human-decision state. Same order as `parts`. */
     calls: TranscriptToolCall[];
+    /**
+     * The same calls as a tree: every call whose parent is NOT in this block, each carrying its
+     * nested calls in `children`. Equal to `calls` when nothing is nested.
+     */
+    roots: TranscriptToolCall[];
+}
+/**
+ * A component the server pushed into the message (the stream's `ui` frame, or a persisted
+ * `data-ui` part). Rendered by looking `component` up in the host's own registry.
+ */
+interface TranscriptUiBlock {
+    kind: 'ui';
+    key: string;
+    /** The component's identity within the message. */
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`; `null` when the server did not stamp one. */
+    version: number | null;
 }
 /** One choice a question offers, with its live selection state. */
 interface TranscriptQuestionOption {
@@ -472,7 +529,7 @@ interface TranscriptSourcesBlock {
     sources: TranscriptSource[];
     passageCount: number;
 }
-type TranscriptBlock = TranscriptTextBlock | TranscriptFilesBlock | TranscriptReasoningBlock | TranscriptToolBlock | TranscriptSourcesBlock | TranscriptElicitationBlock;
+type TranscriptBlock = TranscriptTextBlock | TranscriptFilesBlock | TranscriptReasoningBlock | TranscriptToolBlock | TranscriptSourcesBlock | TranscriptElicitationBlock | TranscriptUiBlock;
 /** Where a question set's selection state is held, and where its settlement is sent. */
 interface ElicitationBlockOptions {
     /** The values a question is showing, or `undefined` while the user has not touched it. */
@@ -515,9 +572,11 @@ interface BuildBlocksOptions {
 }
 /**
  * Walk a message's parts into renderable blocks, buffering consecutive tool parts into one run and
- * consecutive files into one strip. Parts this library has no model for (`data-*`) are dropped
- * rather than guessed at, but they still terminate a tool run — their position in the transcript is
- * meaningful even when their content is not modelled here.
+ * consecutive files into one strip. A `data-ui` part becomes a `ui` block. A
+ * `data-approval-requested` part is metadata about a call — it is folded into that call's
+ * `approval` and takes no position of its own. Other `data-*` parts are dropped rather than guessed
+ * at, but they still terminate a tool run — their position in the transcript is meaningful even
+ * when their content is not modelled here.
  */
 declare function buildTranscriptBlocks(message: UIMessage, options: BuildBlocksOptions): TranscriptBlock[];
 /** The message's prose, joined for the clipboard. Reasoning is excluded — it is not the answer. */
@@ -729,6 +788,12 @@ type RenderTextFn = (text: string, ctx: {
 }) => React.ReactNode;
 /** Render a run of files — attachments on a user turn, or files the model produced. */
 type RenderFilesFn = (files: TranscriptFile[]) => React.ReactNode;
+/**
+ * Render a component the server pushed into the message — look `block.component` up in your own
+ * registry. Omitted → pushed components are not drawn (there is no sensible default for an app's
+ * own component).
+ */
+type RenderUiFn = (block: TranscriptUiBlock) => React.ReactNode;
 /** Render the body of a reasoning run; the disclosure toggle around it stays this component's. */
 type RenderReasoningFn = (text: string, ctx: {
     isStreaming: boolean;
@@ -761,6 +826,8 @@ interface MessageRenderSlots {
     renderReasoning?: RenderReasoningFn;
     /** Draw files yourself — a gallery, a viewer. Omitted → images inline, everything else a link. */
     renderFiles?: RenderFilesFn;
+    /** Draw a server-pushed component (a `ui` stream frame). Omitted → not drawn. */
+    renderUi?: RenderUiFn;
     /**
      * Extra content for the action row, after the built-in affordances and before usage — a badge
      * naming which agent answered, a status pill. Rendered for every message that has an action row.
@@ -825,6 +892,8 @@ interface MessageListProps {
     renderReasoning?: RenderReasoningFn;
     /** Draw a message's files yourself. Omitted → images inline, everything else a link. */
     renderFiles?: RenderFilesFn;
+    /** Draw a server-pushed component (a `ui` stream frame). Omitted → not drawn. */
+    renderUi?: RenderUiFn;
     reasoningLabel?: React.ReactNode;
     /** Extra content for one message's action row — e.g. a badge naming which agent answered. */
     getMeta?: (message: UIMessage) => React.ReactNode;
@@ -860,7 +929,7 @@ interface MessageListProps {
  * Every decision here comes from `useChatTranscript`; the file below it is markup. A host that
  * wants a different layout drives that hook directly and never imports this component.
  */
-declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React.JSX.Element;
+declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React.JSX.Element;
 
 /**
  * Languages the dictation mic offers. The Web Speech API expects a
@@ -1088,6 +1157,32 @@ interface ComposerAutocomplete {
  */
 declare function useComposerAutocomplete(options: UseComposerAutocompleteOptions): ComposerAutocomplete;
 
+/** The thinking time stamped on a reasoning part, or `null` when it carries none. */
+declare function readReasoningMs(part: {
+    providerMetadata?: unknown;
+}): number | null;
+interface UseElapsedOptions {
+    /** How often the value re-renders while running. Default 1000 — a seconds label needs no more. */
+    intervalMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+/**
+ * Milliseconds since `running` last turned true — ticking while it stays true, frozen at the final
+ * value once it turns false, `0` before it has ever run. Headless: pair it with
+ * {@link formatElapsed} or any label of your own.
+ *
+ * For a reasoning block, prefer the duration the block already carries (`block.durationMs`, the
+ * server's own measurement) and fall back to this only while the block streams:
+ * `block.durationMs ?? elapsed`.
+ */
+declare function useElapsed(running: boolean, options?: UseElapsedOptions): number;
+/**
+ * `"<1s"`, `"4s"`, `"1m 5s"`, `"1h 2m"` — whole units, the shape a "Thought for …" label wants.
+ * Negative or non-finite input reads as `"<1s"` rather than a nonsense figure.
+ */
+declare function formatElapsed(ms: number): string;
+
 declare function storedMessageToUiMessage(message: StoredMessage): UIMessage;
 
 /**
@@ -1219,6 +1314,18 @@ interface UseAgentChatOptions {
         runId: string;
         status: 'completed' | 'failed';
     }) => void;
+    /**
+     * Every data part the stream delivers, as it arrives — including transient ones that are never
+     * stored on a message (`data-title`, `data-cancelled`). Pushed components arrive as `data-ui`,
+     * approval metadata as `data-approval-requested`, and a frame kind this version does not map as
+     * `data-<kind>`. See `AgentChatTransport` for the full mapping.
+     */
+    onData?: (part: DataUIPart<UIDataTypes>) => void;
+    /**
+     * The server set or changed the thread's title while a turn streamed. Lets a header/sidebar
+     * update the moment the title exists instead of refetching after the run settles.
+     */
+    onTitle?: (title: string) => void;
     /**
      * Track DETACHED sub-agents this conversation started: which are still working, and their answers
      * as they land (see {@link ChatBackground}). Default `false`.
@@ -1260,7 +1367,7 @@ interface AddToolResultArgs {
  * `AgentClient`. Mirrors flip's `useAdminChat`, generalized.
  */
 declare function useAgentChat(options: UseAgentChatOptions): {
-    sendMessage: (message?: (Omit<UIMessage<unknown, ai.UIDataTypes, ai.UITools>, "id" | "role"> & {
+    sendMessage: (message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
         role?: "system" | "user" | "assistant";
     } & {
@@ -1313,15 +1420,15 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     }) => Promise<void>;
     regenerate: () => void;
     id: string;
-    setMessages: (messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[]) => UIMessage<unknown, ai.UIDataTypes, ai.UITools>[])) => void;
+    setMessages: (messages: UIMessage<unknown, UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, UIDataTypes, ai.UITools>[]) => UIMessage<unknown, UIDataTypes, ai.UITools>[])) => void;
     error: Error | undefined;
     stop: () => Promise<void>;
     status: ai.ChatStatus;
-    messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[];
+    messages: UIMessage<unknown, UIDataTypes, ai.UITools>[];
     resumeStream: (options?: ai.ChatRequestOptions) => Promise<void>;
-    addToolOutput: ai.ChatAddToolOutputFunction<UIMessage<unknown, ai.UIDataTypes, ai.UITools>>;
+    addToolOutput: ai.ChatAddToolOutputFunction<UIMessage<unknown, UIDataTypes, ai.UITools>>;
     addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
     clearError: () => void;
 };
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type ApprovalBlockOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type BuildBlocksOptions, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, type ChatStatus, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type ElicitationBlockOptions, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RetrievedPassage, SPEECH_LANGUAGES, type SettleAction, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type ThreadPatch, type TimestampInfo, type TranscriptActionState, type TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, type TranscriptElicitationBlock, type TranscriptElicitationOutcome, type TranscriptFile, type TranscriptFilesBlock, type TranscriptItem, type TranscriptItemOptions, type TranscriptQuestion, type TranscriptQuestionOption, type TranscriptReasoningBlock, type TranscriptSettleState, type TranscriptSource, type TranscriptSourcesBlock, type TranscriptStopState, type TranscriptTextBlock, type TranscriptToolBlock, type TranscriptToolCall, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UsageSummary, type UseAgentChatOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseSpeechRecognitionOptions, type UseTranscriptItemOptions, applyCompletion, backgroundRunsFromThread, buildTranscriptBlocks, createSkillsSource, describeTimestamp, describeUsage, extractMessageText, filterAutocompleteItems, findActiveTrigger, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useChatTranscript, useComposerAutocomplete, useSpeechRecognition, useStickToBottom, useTranscriptItem };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type ApprovalBlockOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type BuildBlocksOptions, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, type ChatStatus, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type ElicitationBlockOptions, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type RetrievedPassage, SPEECH_LANGUAGES, type SettleAction, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type ThreadPatch, type TimestampInfo, type TranscriptActionState, type TranscriptApproval, type TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, type TranscriptElicitationBlock, type TranscriptElicitationOutcome, type TranscriptFile, type TranscriptFilesBlock, type TranscriptItem, type TranscriptItemOptions, type TranscriptQuestion, type TranscriptQuestionOption, type TranscriptReasoningBlock, type TranscriptSettleState, type TranscriptSource, type TranscriptSourcesBlock, type TranscriptStopState, type TranscriptTextBlock, type TranscriptToolBlock, type TranscriptToolCall, type TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UsageSummary, type UseAgentChatOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseSpeechRecognitionOptions, type UseTranscriptItemOptions, applyCompletion, backgroundRunsFromThread, buildTranscriptBlocks, createSkillsSource, describeTimestamp, describeUsage, extractMessageText, filterAutocompleteItems, findActiveTrigger, formatElapsed, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useTranscriptItem };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as ai from 'ai';
-import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart } from 'ai';
+import { ChatTransport, UIMessage, UIMessageChunk, ToolUIPart, DynamicToolUIPart, DataUIPart, UIDataTypes } from 'ai';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
 import { StoredMessage, ThreadSummary, SkillCatalogEntry, ThreadDetail, MessageAttachment, QuotaView } from '@dudousxd/nestjs-agent-core';
 import React from 'react';
@@ -69,6 +69,15 @@ interface AgentChatTransportOptions {
  * message, and are rendered as native model content parts. Optimistic display of
  * the user's own attachment thumbnails is the consumer's concern (it stages the
  * upload), the same way history rendering reads `StoredMessage.attachments`.
+ *
+ * Frames beyond text/reasoning/tools become AI SDK data parts (seen by `useChat`'s `onData`):
+ *  - `ui`                 → `data-ui` part, `id` = the component id (a repeat id updates it in place)
+ *  - `approval-requested` → `data-approval-requested` part keyed by the call id, plus the SDK's
+ *                           native `tool-approval-request` (the part moves to `approval-requested`)
+ *  - `title`, `cancelled` → transient `data-title` / `data-cancelled` (never stored on the message)
+ *  - any other kind       → `data-<kind>` part carrying the frame minus `kind`, keyed by its `id`
+ *                           when it has one — forwarded, never dropped
+ * `parentId` on a tool frame rides the part's `toolMetadata` next to `toolKind`.
  */
 declare class AgentChatTransport implements ChatTransport<UIMessage> {
     private readonly options;
@@ -105,7 +114,8 @@ declare class AgentChatTransport implements ChatTransport<UIMessage> {
      * Parse the backend's SSE byte stream and re-emit it as a valid v7 UI-message chunk stream.
      * Recognized frames:
      *  - `event: meta`  `data: {"runId","threadId"}`   → records identity
-     *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool)
+     *  - `data: <AgentStreamEvent JSON>`                → mapped to UI chunks (text / reasoning / tool /
+     *                                                     `data-*`; see {@link AgentChatTransport} docs)
      *  - `event: done`  `data: {}`                      → terminates
      *  - `event: error` `data: {code,message}`          → error chunk
      *
@@ -335,6 +345,12 @@ interface TranscriptReasoningBlock {
     key: string;
     text: string;
     isStreaming: boolean;
+    /**
+     * How long the model thought, in ms — the backend's measurement once the run closed (live) or as
+     * persisted (reloaded). `null` while it still streams, or when nothing was recorded: pair it with
+     * `useElapsed(block.isStreaming)` for a ticking label (`block.durationMs ?? elapsed`).
+     */
+    durationMs: number | null;
     isOpen: boolean;
     toggle: (open?: boolean) => void;
 }
@@ -352,11 +368,33 @@ interface TranscriptSettleState {
     isSubmitting: boolean;
     run: () => void;
 }
+/**
+ * Who has to settle a parked call, and until when — from the stream's `approval-requested` frame.
+ * `null` on a call whose runner never said (the call can still be awaiting approval).
+ */
+interface TranscriptApproval {
+    /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
+    approver: string;
+    /** ISO-8601; `null` when the request never lapses. */
+    expiresAt: string | null;
+    reason: string | null;
+}
 /** One call in a tool run, with whatever human decision it is parked on. */
 interface TranscriptToolCall {
     part: AnyToolUIPart;
     toolCallId: string;
     name: string;
+    /** `read` / `action` as the stream classified the call; `null` when the backend did not say. */
+    toolKind: string | null;
+    /** The call this one ran inside (a code-mode `execute`, a delegated agent); `null` for a top-level call. */
+    parentId: string | null;
+    /**
+     * Calls nested under this one within the same block, in stream order. Always empty for a call
+     * nothing names as its parent.
+     */
+    children: TranscriptToolCall[];
+    /** Who has to decide, when the runner said so. See {@link TranscriptApproval}. */
+    approval: TranscriptApproval | null;
     /**
      * Parked on a person. An `action` tool's input lands and its output never follows on its own —
      * the loop waits for an approval between the two — so a settled-looking card that never settles
@@ -379,6 +417,25 @@ interface TranscriptToolBlock {
     parts: AnyToolUIPart[];
     /** The same calls, each with its human-decision state. Same order as `parts`. */
     calls: TranscriptToolCall[];
+    /**
+     * The same calls as a tree: every call whose parent is NOT in this block, each carrying its
+     * nested calls in `children`. Equal to `calls` when nothing is nested.
+     */
+    roots: TranscriptToolCall[];
+}
+/**
+ * A component the server pushed into the message (the stream's `ui` frame, or a persisted
+ * `data-ui` part). Rendered by looking `component` up in the host's own registry.
+ */
+interface TranscriptUiBlock {
+    kind: 'ui';
+    key: string;
+    /** The component's identity within the message. */
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`; `null` when the server did not stamp one. */
+    version: number | null;
 }
 /** One choice a question offers, with its live selection state. */
 interface TranscriptQuestionOption {
@@ -472,7 +529,7 @@ interface TranscriptSourcesBlock {
     sources: TranscriptSource[];
     passageCount: number;
 }
-type TranscriptBlock = TranscriptTextBlock | TranscriptFilesBlock | TranscriptReasoningBlock | TranscriptToolBlock | TranscriptSourcesBlock | TranscriptElicitationBlock;
+type TranscriptBlock = TranscriptTextBlock | TranscriptFilesBlock | TranscriptReasoningBlock | TranscriptToolBlock | TranscriptSourcesBlock | TranscriptElicitationBlock | TranscriptUiBlock;
 /** Where a question set's selection state is held, and where its settlement is sent. */
 interface ElicitationBlockOptions {
     /** The values a question is showing, or `undefined` while the user has not touched it. */
@@ -515,9 +572,11 @@ interface BuildBlocksOptions {
 }
 /**
  * Walk a message's parts into renderable blocks, buffering consecutive tool parts into one run and
- * consecutive files into one strip. Parts this library has no model for (`data-*`) are dropped
- * rather than guessed at, but they still terminate a tool run — their position in the transcript is
- * meaningful even when their content is not modelled here.
+ * consecutive files into one strip. A `data-ui` part becomes a `ui` block. A
+ * `data-approval-requested` part is metadata about a call — it is folded into that call's
+ * `approval` and takes no position of its own. Other `data-*` parts are dropped rather than guessed
+ * at, but they still terminate a tool run — their position in the transcript is meaningful even
+ * when their content is not modelled here.
  */
 declare function buildTranscriptBlocks(message: UIMessage, options: BuildBlocksOptions): TranscriptBlock[];
 /** The message's prose, joined for the clipboard. Reasoning is excluded — it is not the answer. */
@@ -729,6 +788,12 @@ type RenderTextFn = (text: string, ctx: {
 }) => React.ReactNode;
 /** Render a run of files — attachments on a user turn, or files the model produced. */
 type RenderFilesFn = (files: TranscriptFile[]) => React.ReactNode;
+/**
+ * Render a component the server pushed into the message — look `block.component` up in your own
+ * registry. Omitted → pushed components are not drawn (there is no sensible default for an app's
+ * own component).
+ */
+type RenderUiFn = (block: TranscriptUiBlock) => React.ReactNode;
 /** Render the body of a reasoning run; the disclosure toggle around it stays this component's. */
 type RenderReasoningFn = (text: string, ctx: {
     isStreaming: boolean;
@@ -761,6 +826,8 @@ interface MessageRenderSlots {
     renderReasoning?: RenderReasoningFn;
     /** Draw files yourself — a gallery, a viewer. Omitted → images inline, everything else a link. */
     renderFiles?: RenderFilesFn;
+    /** Draw a server-pushed component (a `ui` stream frame). Omitted → not drawn. */
+    renderUi?: RenderUiFn;
     /**
      * Extra content for the action row, after the built-in affordances and before usage — a badge
      * naming which agent answered, a status pill. Rendered for every message that has an action row.
@@ -825,6 +892,8 @@ interface MessageListProps {
     renderReasoning?: RenderReasoningFn;
     /** Draw a message's files yourself. Omitted → images inline, everything else a link. */
     renderFiles?: RenderFilesFn;
+    /** Draw a server-pushed component (a `ui` stream frame). Omitted → not drawn. */
+    renderUi?: RenderUiFn;
     reasoningLabel?: React.ReactNode;
     /** Extra content for one message's action row — e.g. a badge naming which agent answered. */
     getMeta?: (message: UIMessage) => React.ReactNode;
@@ -860,7 +929,7 @@ interface MessageListProps {
  * Every decision here comes from `useChatTranscript`; the file below it is markup. A host that
  * wants a different layout drives that hook directly and never imports this component.
  */
-declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React.JSX.Element;
+declare function MessageList({ messages, status, renderToolPart, renderToolGroup, renderText, renderReasoning, renderFiles, renderUi, reasoningLabel, getMeta, onFork, editable, onEditSubmit, regeneratable, onRegenerate, getUsage, getCreatedAt, emptyState, typingIndicator, followUps, onFollowUpClick, error, onRetry, classNames, }: MessageListProps): React.JSX.Element;
 
 /**
  * Languages the dictation mic offers. The Web Speech API expects a
@@ -1088,6 +1157,32 @@ interface ComposerAutocomplete {
  */
 declare function useComposerAutocomplete(options: UseComposerAutocompleteOptions): ComposerAutocomplete;
 
+/** The thinking time stamped on a reasoning part, or `null` when it carries none. */
+declare function readReasoningMs(part: {
+    providerMetadata?: unknown;
+}): number | null;
+interface UseElapsedOptions {
+    /** How often the value re-renders while running. Default 1000 — a seconds label needs no more. */
+    intervalMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+/**
+ * Milliseconds since `running` last turned true — ticking while it stays true, frozen at the final
+ * value once it turns false, `0` before it has ever run. Headless: pair it with
+ * {@link formatElapsed} or any label of your own.
+ *
+ * For a reasoning block, prefer the duration the block already carries (`block.durationMs`, the
+ * server's own measurement) and fall back to this only while the block streams:
+ * `block.durationMs ?? elapsed`.
+ */
+declare function useElapsed(running: boolean, options?: UseElapsedOptions): number;
+/**
+ * `"<1s"`, `"4s"`, `"1m 5s"`, `"1h 2m"` — whole units, the shape a "Thought for …" label wants.
+ * Negative or non-finite input reads as `"<1s"` rather than a nonsense figure.
+ */
+declare function formatElapsed(ms: number): string;
+
 declare function storedMessageToUiMessage(message: StoredMessage): UIMessage;
 
 /**
@@ -1219,6 +1314,18 @@ interface UseAgentChatOptions {
         runId: string;
         status: 'completed' | 'failed';
     }) => void;
+    /**
+     * Every data part the stream delivers, as it arrives — including transient ones that are never
+     * stored on a message (`data-title`, `data-cancelled`). Pushed components arrive as `data-ui`,
+     * approval metadata as `data-approval-requested`, and a frame kind this version does not map as
+     * `data-<kind>`. See `AgentChatTransport` for the full mapping.
+     */
+    onData?: (part: DataUIPart<UIDataTypes>) => void;
+    /**
+     * The server set or changed the thread's title while a turn streamed. Lets a header/sidebar
+     * update the moment the title exists instead of refetching after the run settles.
+     */
+    onTitle?: (title: string) => void;
     /**
      * Track DETACHED sub-agents this conversation started: which are still working, and their answers
      * as they land (see {@link ChatBackground}). Default `false`.
@@ -1260,7 +1367,7 @@ interface AddToolResultArgs {
  * `AgentClient`. Mirrors flip's `useAdminChat`, generalized.
  */
 declare function useAgentChat(options: UseAgentChatOptions): {
-    sendMessage: (message?: (Omit<UIMessage<unknown, ai.UIDataTypes, ai.UITools>, "id" | "role"> & {
+    sendMessage: (message?: (Omit<UIMessage<unknown, UIDataTypes, ai.UITools>, "id" | "role"> & {
         id?: string;
         role?: "system" | "user" | "assistant";
     } & {
@@ -1313,15 +1420,15 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     }) => Promise<void>;
     regenerate: () => void;
     id: string;
-    setMessages: (messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[]) => UIMessage<unknown, ai.UIDataTypes, ai.UITools>[])) => void;
+    setMessages: (messages: UIMessage<unknown, UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, UIDataTypes, ai.UITools>[]) => UIMessage<unknown, UIDataTypes, ai.UITools>[])) => void;
     error: Error | undefined;
     stop: () => Promise<void>;
     status: ai.ChatStatus;
-    messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[];
+    messages: UIMessage<unknown, UIDataTypes, ai.UITools>[];
     resumeStream: (options?: ai.ChatRequestOptions) => Promise<void>;
-    addToolOutput: ai.ChatAddToolOutputFunction<UIMessage<unknown, ai.UIDataTypes, ai.UITools>>;
+    addToolOutput: ai.ChatAddToolOutputFunction<UIMessage<unknown, UIDataTypes, ai.UITools>>;
     addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
     clearError: () => void;
 };
 
-export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type ApprovalBlockOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type BuildBlocksOptions, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, type ChatStatus, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type ElicitationBlockOptions, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RetrievedPassage, SPEECH_LANGUAGES, type SettleAction, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type ThreadPatch, type TimestampInfo, type TranscriptActionState, type TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, type TranscriptElicitationBlock, type TranscriptElicitationOutcome, type TranscriptFile, type TranscriptFilesBlock, type TranscriptItem, type TranscriptItemOptions, type TranscriptQuestion, type TranscriptQuestionOption, type TranscriptReasoningBlock, type TranscriptSettleState, type TranscriptSource, type TranscriptSourcesBlock, type TranscriptStopState, type TranscriptTextBlock, type TranscriptToolBlock, type TranscriptToolCall, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UsageSummary, type UseAgentChatOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseSpeechRecognitionOptions, type UseTranscriptItemOptions, applyCompletion, backgroundRunsFromThread, buildTranscriptBlocks, createSkillsSource, describeTimestamp, describeUsage, extractMessageText, filterAutocompleteItems, findActiveTrigger, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useChatTranscript, useComposerAutocomplete, useSpeechRecognition, useStickToBottom, useTranscriptItem };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type ApprovalBlockOptions, type AutocompleteInputProps, type AutocompleteItem, type AutocompleteListboxProps, type AutocompleteOptionProps, type AutocompleteSource, type BackgroundRun, type BuildBlocksOptions, type CancelResult, type ChatBackground, ChatInput, type ChatInputProps, type ChatStatus, type ChatTranscript, type CompletionEdit, type ComposerAutocomplete, DEFAULT_SPEECH_LANG, type ElicitationBlockOptions, MessageItem, type MessageItemClassNames, type MessageItemProps, MessageItemView, type MessageItemViewProps, MessageList, type MessageListClassNames, type MessageListProps, type MessageUsageInfo, type QuotaToday, type RenderFilesFn, type RenderReasoningFn, type RenderTextFn, type RenderToolGroupFn, type RenderToolPartFn, type RenderUiFn, type RetrievedPassage, SPEECH_LANGUAGES, type SettleAction, type SkillSuggestionData, type SkillsSourceOptions, type SpeechLanguage, type SpeechRecognitionHook, type StickToBottom, type StickToBottomOptions, type StoredTurnMetadata, type ThreadPatch, type TimestampInfo, type TranscriptActionState, type TranscriptApproval, type TranscriptBlock, type TranscriptCopyState, type TranscriptEditState, type TranscriptElicitationBlock, type TranscriptElicitationOutcome, type TranscriptFile, type TranscriptFilesBlock, type TranscriptItem, type TranscriptItemOptions, type TranscriptQuestion, type TranscriptQuestionOption, type TranscriptReasoningBlock, type TranscriptSettleState, type TranscriptSource, type TranscriptSourcesBlock, type TranscriptStopState, type TranscriptTextBlock, type TranscriptToolBlock, type TranscriptToolCall, type TranscriptUiBlock, type TranscriptWindow, type TriggerMatch, type TriggerPosition, type UsageSummary, type UseAgentChatOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseSpeechRecognitionOptions, type UseTranscriptItemOptions, applyCompletion, backgroundRunsFromThread, buildTranscriptBlocks, createSkillsSource, describeTimestamp, describeUsage, extractMessageText, filterAutocompleteItems, findActiveTrigger, formatElapsed, formatRelativeTime, loadStoredSpeechLang, persistSpeechLang, readReasoningMs, storedMessageToUiMessage, storedThreadToUiMessages, useAgentChat, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useTranscriptItem };