@dudousxd/nestjs-agent-react 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as ai 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 { StoredMessage, ThreadSummary, SkillCatalogEntry, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView, ToolPresentation, ToolResultField, ToolResultView, ToolPresentationTone } from '@dudousxd/nestjs-agent-core';
 import React from 'react';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
@@ -211,6 +211,12 @@ declare class AgentClient {
      * one conversation; omitted, the server reads it as a brand-new thread.
      */
     listSkills(threadId?: string): Promise<SkillCatalogEntry[]>;
+    /**
+     * The tools this caller can reach through `agent` (the default agent when omitted), each with the
+     * server-declared `presentation` a chat narrates it by — the same list the model is offered.
+     * Prefer {@link useToolCatalog}, which fetches it once and shares it.
+     */
+    listTools(agent?: string): Promise<ToolCatalogEntry[]>;
     getThread(id: string): Promise<ThreadDetail>;
     deleteThread(id: string): Promise<void>;
     forkFromMessage(threadId: string, messageId: string): Promise<ThreadSummary>;
@@ -299,6 +305,172 @@ interface ChatInputProps {
  */
 declare function ChatInput({ onSubmit, disabled, placeholder, rows, enableSpeech, speechLang, sendLabel, onStop, isStreaming, stopLabel, className, textareaClassName, sendButtonClassName, micButtonClassName, stopButtonClassName, renderMic, }: ChatInputProps): React.JSX.Element;
 
+/** Tool name → how the server said it is spoken about. */
+type ToolCatalog = Record<string, ToolPresentation>;
+/** Index `GET <base>/tools` by tool name, keeping only the tools that declared a presentation. */
+declare function toolCatalogFrom(entries: readonly ToolCatalogEntry[]): ToolCatalog;
+/** Dotted-path read. `undefined` rather than a throw, so a template can outlive a field. */
+declare function readPath(value: unknown, path: string): unknown;
+/**
+ * Fill `{dotted.path}` placeholders from `context`. A placeholder with nothing behind it collapses
+ * along with the whitespace in front of it, so "Reading {key}" degrades to "Reading" rather than
+ * printing braces at a person; a filled one keeps the whitespace the author wrote ("({n} files)").
+ */
+declare function fillTemplate(template: string, context: unknown): string;
+/**
+ * The sentence for one call: the presentation's `running` or `done` template over the call's input.
+ *
+ * Nothing here reads the tool's name. A tool the catalog does not describe — added since the catalog
+ * loaded, or declared without a presentation — is narrated generically (`fallback`), because the only
+ * other thing available to say is its identifier.
+ */
+declare function phraseFor(presentation: ToolPresentation | undefined, input: unknown, isSettled: boolean, fallback?: {
+    running: string;
+    done: string;
+}): string;
+
+/** One labelled reading of a `metrics` view. */
+interface ResolvedReading {
+    label: string;
+    /** The value as text (`—` for nothing). */
+    value: string;
+    unit: string | null;
+}
+/**
+ * A tool's output resolved through its view into plain data a renderer draws — never the payload
+ * itself. `null` from {@link resolveResultView} means "draw nothing".
+ */
+type ResolvedResultView = {
+    kind: 'metrics';
+    readings: ResolvedReading[];
+} | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string[][];
+    empty: string | null;
+} | {
+    kind: 'log';
+    lines: string[];
+} | {
+    kind: 'note';
+    text: string;
+};
+/**
+ * A view for an output whose tool declared none, from its shape: an array of flat records is a
+ * table, an array of strings a log, a flat record a set of readings. `undefined` when nothing fits —
+ * a serialized payload is what a person-facing surface exists to avoid, so failing to infer must not
+ * fall back to one.
+ */
+declare function inferResultView(output: unknown): ToolResultView | undefined;
+/**
+ * Read `output` through `view` (or one inferred from its shape when `view` is omitted and `infer` is
+ * on). `null` when there is nothing to draw: an `elsewhere` view, an empty reading set, a missing
+ * array. A table whose rows array is present but empty resolves with no rows and its `empty` line.
+ */
+declare function resolveResultView(output: unknown, view: ToolResultView | undefined, options?: {
+    infer?: boolean;
+}): ResolvedResultView | null;
+
+/**
+ * Where one call stands, as a person reads it:
+ *  - `running` — input streaming or the tool executing;
+ *  - `awaiting-approval` — an `action` call parked on a person;
+ *  - `done` / `failed` / `denied` — settled. A tool that RETURNS `{ error }` has failed just as much
+ *    as one that threw; the two arrive differently and read the same to a person.
+ */
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied';
+interface ToolCallState {
+    status: ToolCallStatus;
+    isSettled: boolean;
+    isFailed: boolean;
+    isDenied: boolean;
+    output: unknown;
+    error: string | null;
+}
+/** Whether the stream classified this call as an `action` (it parks for approval before it runs). */
+declare function isActionCall(part: AnyToolUIPart): boolean;
+declare function toolCallState(part: AnyToolUIPart): ToolCallState;
+/**
+ * Which failed calls the model went on to correct, by call id: a call that failed and was followed,
+ * in the same run, by a SUCCESS of the same tool. The operator wants to know a retry happened, not
+ * to read every attempt. A failed read is not corrected by a successful query.
+ */
+declare function correctedCallIds(parts: readonly AnyToolUIPart[]): Set<string>;
+/** Everything a surface needs to talk about one call without naming it. */
+interface ToolCallDescription {
+    status: ToolCallStatus;
+    /** "Querying orders" / "Queried orders" — or the generic fallback when the tool declared nothing. */
+    phrase: string;
+    /** The server's noun phrase for the tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    tone: ToolPresentationTone;
+    detail: string | null;
+    /** The approval prompt, templated over the call's input; `null` when the tool declared none. */
+    confirm: {
+        title: string;
+        verb: string;
+        detail: string | null;
+    } | null;
+    /** The output read through its view, once the call is `done`; `null` otherwise or when nothing to draw. */
+    result: ResolvedResultView | null;
+    error: string | null;
+    presentation: ToolPresentation | null;
+}
+interface DescribeToolCallOptions {
+    /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
+    fallback?: {
+        running: string;
+        done: string;
+    };
+    /** Infer a result view from the output's shape when the tool declared none. Default `false`. */
+    inferResult?: boolean;
+}
+declare function describeToolCall(part: AnyToolUIPart, catalog: ToolCatalog | undefined, options?: DescribeToolCallOptions): ToolCallDescription;
+/**
+ * Calls folded under one key — "Database query ×3" — with the state that matters most across them.
+ */
+interface ToolActivityGroup {
+    key: string;
+    /** The server's label for the group's tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    /** Worst-first across the calls: running › awaiting-approval › failed › denied › done. */
+    status: ToolCallStatus;
+    count: number;
+    /** The phrase of the group's LATEST call — what is happening now. */
+    phrase: string;
+    calls: TranscriptToolCall[];
+    /** Calls nested under the group's calls (all depths), when nesting was not expanded. */
+    innerCount: number;
+}
+interface GroupToolActivityOptions {
+    catalog?: ToolCatalog;
+    /**
+     * What makes two calls "the same activity". Default: the tool's presentation `label`, else its
+     * name. Flippy-style source grouping passes its own (e.g. `github:search`).
+     */
+    keyOf?: (call: TranscriptToolCall, presentation: ToolPresentation | undefined) => string;
+    /**
+     * Replace a call that has nested calls with those calls (recursively), so the activity reads as
+     * what the code-mode run DID rather than "ran code". Default `false`: groups are built over the
+     * top-level calls, and `innerCount` says how much ran beneath them.
+     */
+    expandNested?: boolean;
+    /** Drop failed calls the model corrected with a later success of the same tool. Default `false`. */
+    hideCorrected?: boolean;
+    fallback?: {
+        running: string;
+        done: string;
+    };
+}
+/**
+ * Fold a tool run into activity groups, in order of first appearance. Pass `block.roots` (the
+ * transcript's call tree) so nesting is honoured; a flat `block.calls` works too and simply has
+ * nothing nested.
+ */
+declare function groupToolActivity(calls: readonly TranscriptToolCall[], options?: GroupToolActivityOptions): ToolActivityGroup[];
+
 /** A tool UI part on a `UIMessage` — a static `tool-*` part or the `dynamic-tool` part. */
 type AnyToolUIPart = ToolUIPart | DynamicToolUIPart;
 type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error';
@@ -395,6 +567,11 @@ interface TranscriptToolCall {
     children: TranscriptToolCall[];
     /** Who has to decide, when the runner said so. See {@link TranscriptApproval}. */
     approval: TranscriptApproval | null;
+    /**
+     * How to talk about this call without naming it — status, phrase, label, icon, approval prompt,
+     * resolved result — from the server's presentation when `toolCatalog` was given, generic otherwise.
+     */
+    description: ToolCallDescription;
     /**
      * 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
@@ -422,6 +599,11 @@ interface TranscriptToolBlock {
      * nested calls in `children`. Equal to `calls` when nothing is nested.
      */
     roots: TranscriptToolCall[];
+    /**
+     * The run folded into activity groups ("Database query ×3"), over `roots`, keyed by each tool's
+     * presentation label (else its name). For another grouping, call `groupToolActivity` yourself.
+     */
+    activity: ToolActivityGroup[];
 }
 /**
  * A component the server pushed into the message (the stream's `ui` frame, or a persisted
@@ -569,6 +751,8 @@ interface BuildBlocksOptions {
     elicitation?: ElicitationBlockOptions;
     /** Wire approve/reject onto the calls parked on a human. Omitted → they are reported, not actionable. */
     approval?: ApprovalBlockOptions;
+    /** Server-declared tool presentations (`useToolCatalog`), for each call's `description`. */
+    toolCatalog?: ToolCatalog;
 }
 /**
  * Walk a message's parts into renderable blocks, buffering consecutive tool parts into one run and
@@ -703,6 +887,11 @@ interface TranscriptItemOptions {
      * run. Off by default, so a renderer already drawing tool cards keeps drawing them.
      */
     sources?: boolean;
+    /**
+     * Server-declared tool presentations (`useToolCatalog(...).catalog`). Given → each tool call's
+     * `description` and each tool block's `activity` speak in the tool's own words; omitted → generic.
+     */
+    toolCatalog?: ToolCatalog;
     /**
      * Settle a parked question set — wire to `useAgentChat`'s `answer`. Supplying it is what lifts a
      * question set out of the tool run into an `elicitation` block: without somewhere to send an
@@ -1157,6 +1346,34 @@ interface ComposerAutocomplete {
  */
 declare function useComposerAutocomplete(options: UseComposerAutocompleteOptions): ComposerAutocomplete;
 
+interface UseToolCatalogOptions {
+    /**
+     * The client to ask — `useAgentChat(...).client`, or one of your own. Must be STABLE across
+     * renders (the shared copy is keyed by it): a client constructed inline refetches every render.
+     */
+    client: AgentClient;
+    /** The agent whose tools to list. Omitted → the server's default agent. */
+    agent?: string;
+    /** `false` holds the request (e.g. until the user is signed in). Default `true`. */
+    enabled?: boolean;
+}
+interface ToolCatalogState {
+    /** Tool name → presentation, for the tools that declared one. `{}` until loaded. */
+    catalog: ToolCatalog;
+    /** Everything `GET <base>/tools` returned, kinds included. */
+    entries: ToolCatalogEntry[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Drop the shared copy and ask again. */
+    refresh: () => void;
+}
+/**
+ * The server-declared presentation of the tools this actor can reach (`GET <base>/tools`), for
+ * `phraseFor`, `describeToolCall` and `groupToolActivity` — or pass `catalog` to
+ * `useChatTranscript({ toolCatalog })` and read the phrases off the transcript's calls.
+ */
+declare function useToolCatalog(options: UseToolCatalogOptions): ToolCatalogState;
+
 /** The thinking time stamped on a reasoning part, or `null` when it carries none. */
 declare function readReasoningMs(part: {
     providerMetadata?: unknown;
@@ -1431,4 +1648,4 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     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 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 };
+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 DescribeToolCallOptions, type ElicitationBlockOptions, type GroupToolActivityOptions, 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 ResolvedReading, type ResolvedResultView, 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 ToolActivityGroup, type ToolCallDescription, type ToolCallState, type ToolCallStatus, type ToolCatalog, type ToolCatalogState, 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 UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, backgroundRunsFromThread, buildTranscriptBlocks, correctedCallIds, createSkillsSource, describeTimestamp, describeToolCall, describeUsage, extractMessageText, fillTemplate, filterAutocompleteItems, findActiveTrigger, formatElapsed, formatRelativeTime, groupToolActivity, inferResultView, isActionCall, loadStoredSpeechLang, persistSpeechLang, phraseFor, readPath, readReasoningMs, resolveResultView, storedMessageToUiMessage, storedThreadToUiMessages, toolCallState, toolCatalogFrom, useAgentChat, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useToolCatalog, useTranscriptItem };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as ai 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 { StoredMessage, ThreadSummary, SkillCatalogEntry, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView, ToolPresentation, ToolResultField, ToolResultView, ToolPresentationTone } from '@dudousxd/nestjs-agent-core';
 import React from 'react';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
@@ -211,6 +211,12 @@ declare class AgentClient {
      * one conversation; omitted, the server reads it as a brand-new thread.
      */
     listSkills(threadId?: string): Promise<SkillCatalogEntry[]>;
+    /**
+     * The tools this caller can reach through `agent` (the default agent when omitted), each with the
+     * server-declared `presentation` a chat narrates it by — the same list the model is offered.
+     * Prefer {@link useToolCatalog}, which fetches it once and shares it.
+     */
+    listTools(agent?: string): Promise<ToolCatalogEntry[]>;
     getThread(id: string): Promise<ThreadDetail>;
     deleteThread(id: string): Promise<void>;
     forkFromMessage(threadId: string, messageId: string): Promise<ThreadSummary>;
@@ -299,6 +305,172 @@ interface ChatInputProps {
  */
 declare function ChatInput({ onSubmit, disabled, placeholder, rows, enableSpeech, speechLang, sendLabel, onStop, isStreaming, stopLabel, className, textareaClassName, sendButtonClassName, micButtonClassName, stopButtonClassName, renderMic, }: ChatInputProps): React.JSX.Element;
 
+/** Tool name → how the server said it is spoken about. */
+type ToolCatalog = Record<string, ToolPresentation>;
+/** Index `GET <base>/tools` by tool name, keeping only the tools that declared a presentation. */
+declare function toolCatalogFrom(entries: readonly ToolCatalogEntry[]): ToolCatalog;
+/** Dotted-path read. `undefined` rather than a throw, so a template can outlive a field. */
+declare function readPath(value: unknown, path: string): unknown;
+/**
+ * Fill `{dotted.path}` placeholders from `context`. A placeholder with nothing behind it collapses
+ * along with the whitespace in front of it, so "Reading {key}" degrades to "Reading" rather than
+ * printing braces at a person; a filled one keeps the whitespace the author wrote ("({n} files)").
+ */
+declare function fillTemplate(template: string, context: unknown): string;
+/**
+ * The sentence for one call: the presentation's `running` or `done` template over the call's input.
+ *
+ * Nothing here reads the tool's name. A tool the catalog does not describe — added since the catalog
+ * loaded, or declared without a presentation — is narrated generically (`fallback`), because the only
+ * other thing available to say is its identifier.
+ */
+declare function phraseFor(presentation: ToolPresentation | undefined, input: unknown, isSettled: boolean, fallback?: {
+    running: string;
+    done: string;
+}): string;
+
+/** One labelled reading of a `metrics` view. */
+interface ResolvedReading {
+    label: string;
+    /** The value as text (`—` for nothing). */
+    value: string;
+    unit: string | null;
+}
+/**
+ * A tool's output resolved through its view into plain data a renderer draws — never the payload
+ * itself. `null` from {@link resolveResultView} means "draw nothing".
+ */
+type ResolvedResultView = {
+    kind: 'metrics';
+    readings: ResolvedReading[];
+} | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string[][];
+    empty: string | null;
+} | {
+    kind: 'log';
+    lines: string[];
+} | {
+    kind: 'note';
+    text: string;
+};
+/**
+ * A view for an output whose tool declared none, from its shape: an array of flat records is a
+ * table, an array of strings a log, a flat record a set of readings. `undefined` when nothing fits —
+ * a serialized payload is what a person-facing surface exists to avoid, so failing to infer must not
+ * fall back to one.
+ */
+declare function inferResultView(output: unknown): ToolResultView | undefined;
+/**
+ * Read `output` through `view` (or one inferred from its shape when `view` is omitted and `infer` is
+ * on). `null` when there is nothing to draw: an `elsewhere` view, an empty reading set, a missing
+ * array. A table whose rows array is present but empty resolves with no rows and its `empty` line.
+ */
+declare function resolveResultView(output: unknown, view: ToolResultView | undefined, options?: {
+    infer?: boolean;
+}): ResolvedResultView | null;
+
+/**
+ * Where one call stands, as a person reads it:
+ *  - `running` — input streaming or the tool executing;
+ *  - `awaiting-approval` — an `action` call parked on a person;
+ *  - `done` / `failed` / `denied` — settled. A tool that RETURNS `{ error }` has failed just as much
+ *    as one that threw; the two arrive differently and read the same to a person.
+ */
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied';
+interface ToolCallState {
+    status: ToolCallStatus;
+    isSettled: boolean;
+    isFailed: boolean;
+    isDenied: boolean;
+    output: unknown;
+    error: string | null;
+}
+/** Whether the stream classified this call as an `action` (it parks for approval before it runs). */
+declare function isActionCall(part: AnyToolUIPart): boolean;
+declare function toolCallState(part: AnyToolUIPart): ToolCallState;
+/**
+ * Which failed calls the model went on to correct, by call id: a call that failed and was followed,
+ * in the same run, by a SUCCESS of the same tool. The operator wants to know a retry happened, not
+ * to read every attempt. A failed read is not corrected by a successful query.
+ */
+declare function correctedCallIds(parts: readonly AnyToolUIPart[]): Set<string>;
+/** Everything a surface needs to talk about one call without naming it. */
+interface ToolCallDescription {
+    status: ToolCallStatus;
+    /** "Querying orders" / "Queried orders" — or the generic fallback when the tool declared nothing. */
+    phrase: string;
+    /** The server's noun phrase for the tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    tone: ToolPresentationTone;
+    detail: string | null;
+    /** The approval prompt, templated over the call's input; `null` when the tool declared none. */
+    confirm: {
+        title: string;
+        verb: string;
+        detail: string | null;
+    } | null;
+    /** The output read through its view, once the call is `done`; `null` otherwise or when nothing to draw. */
+    result: ResolvedResultView | null;
+    error: string | null;
+    presentation: ToolPresentation | null;
+}
+interface DescribeToolCallOptions {
+    /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
+    fallback?: {
+        running: string;
+        done: string;
+    };
+    /** Infer a result view from the output's shape when the tool declared none. Default `false`. */
+    inferResult?: boolean;
+}
+declare function describeToolCall(part: AnyToolUIPart, catalog: ToolCatalog | undefined, options?: DescribeToolCallOptions): ToolCallDescription;
+/**
+ * Calls folded under one key — "Database query ×3" — with the state that matters most across them.
+ */
+interface ToolActivityGroup {
+    key: string;
+    /** The server's label for the group's tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    /** Worst-first across the calls: running › awaiting-approval › failed › denied › done. */
+    status: ToolCallStatus;
+    count: number;
+    /** The phrase of the group's LATEST call — what is happening now. */
+    phrase: string;
+    calls: TranscriptToolCall[];
+    /** Calls nested under the group's calls (all depths), when nesting was not expanded. */
+    innerCount: number;
+}
+interface GroupToolActivityOptions {
+    catalog?: ToolCatalog;
+    /**
+     * What makes two calls "the same activity". Default: the tool's presentation `label`, else its
+     * name. Flippy-style source grouping passes its own (e.g. `github:search`).
+     */
+    keyOf?: (call: TranscriptToolCall, presentation: ToolPresentation | undefined) => string;
+    /**
+     * Replace a call that has nested calls with those calls (recursively), so the activity reads as
+     * what the code-mode run DID rather than "ran code". Default `false`: groups are built over the
+     * top-level calls, and `innerCount` says how much ran beneath them.
+     */
+    expandNested?: boolean;
+    /** Drop failed calls the model corrected with a later success of the same tool. Default `false`. */
+    hideCorrected?: boolean;
+    fallback?: {
+        running: string;
+        done: string;
+    };
+}
+/**
+ * Fold a tool run into activity groups, in order of first appearance. Pass `block.roots` (the
+ * transcript's call tree) so nesting is honoured; a flat `block.calls` works too and simply has
+ * nothing nested.
+ */
+declare function groupToolActivity(calls: readonly TranscriptToolCall[], options?: GroupToolActivityOptions): ToolActivityGroup[];
+
 /** A tool UI part on a `UIMessage` — a static `tool-*` part or the `dynamic-tool` part. */
 type AnyToolUIPart = ToolUIPart | DynamicToolUIPart;
 type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error';
@@ -395,6 +567,11 @@ interface TranscriptToolCall {
     children: TranscriptToolCall[];
     /** Who has to decide, when the runner said so. See {@link TranscriptApproval}. */
     approval: TranscriptApproval | null;
+    /**
+     * How to talk about this call without naming it — status, phrase, label, icon, approval prompt,
+     * resolved result — from the server's presentation when `toolCatalog` was given, generic otherwise.
+     */
+    description: ToolCallDescription;
     /**
      * 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
@@ -422,6 +599,11 @@ interface TranscriptToolBlock {
      * nested calls in `children`. Equal to `calls` when nothing is nested.
      */
     roots: TranscriptToolCall[];
+    /**
+     * The run folded into activity groups ("Database query ×3"), over `roots`, keyed by each tool's
+     * presentation label (else its name). For another grouping, call `groupToolActivity` yourself.
+     */
+    activity: ToolActivityGroup[];
 }
 /**
  * A component the server pushed into the message (the stream's `ui` frame, or a persisted
@@ -569,6 +751,8 @@ interface BuildBlocksOptions {
     elicitation?: ElicitationBlockOptions;
     /** Wire approve/reject onto the calls parked on a human. Omitted → they are reported, not actionable. */
     approval?: ApprovalBlockOptions;
+    /** Server-declared tool presentations (`useToolCatalog`), for each call's `description`. */
+    toolCatalog?: ToolCatalog;
 }
 /**
  * Walk a message's parts into renderable blocks, buffering consecutive tool parts into one run and
@@ -703,6 +887,11 @@ interface TranscriptItemOptions {
      * run. Off by default, so a renderer already drawing tool cards keeps drawing them.
      */
     sources?: boolean;
+    /**
+     * Server-declared tool presentations (`useToolCatalog(...).catalog`). Given → each tool call's
+     * `description` and each tool block's `activity` speak in the tool's own words; omitted → generic.
+     */
+    toolCatalog?: ToolCatalog;
     /**
      * Settle a parked question set — wire to `useAgentChat`'s `answer`. Supplying it is what lifts a
      * question set out of the tool run into an `elicitation` block: without somewhere to send an
@@ -1157,6 +1346,34 @@ interface ComposerAutocomplete {
  */
 declare function useComposerAutocomplete(options: UseComposerAutocompleteOptions): ComposerAutocomplete;
 
+interface UseToolCatalogOptions {
+    /**
+     * The client to ask — `useAgentChat(...).client`, or one of your own. Must be STABLE across
+     * renders (the shared copy is keyed by it): a client constructed inline refetches every render.
+     */
+    client: AgentClient;
+    /** The agent whose tools to list. Omitted → the server's default agent. */
+    agent?: string;
+    /** `false` holds the request (e.g. until the user is signed in). Default `true`. */
+    enabled?: boolean;
+}
+interface ToolCatalogState {
+    /** Tool name → presentation, for the tools that declared one. `{}` until loaded. */
+    catalog: ToolCatalog;
+    /** Everything `GET <base>/tools` returned, kinds included. */
+    entries: ToolCatalogEntry[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Drop the shared copy and ask again. */
+    refresh: () => void;
+}
+/**
+ * The server-declared presentation of the tools this actor can reach (`GET <base>/tools`), for
+ * `phraseFor`, `describeToolCall` and `groupToolActivity` — or pass `catalog` to
+ * `useChatTranscript({ toolCatalog })` and read the phrases off the transcript's calls.
+ */
+declare function useToolCatalog(options: UseToolCatalogOptions): ToolCatalogState;
+
 /** The thinking time stamped on a reasoning part, or `null` when it carries none. */
 declare function readReasoningMs(part: {
     providerMetadata?: unknown;
@@ -1431,4 +1648,4 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     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 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 };
+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 DescribeToolCallOptions, type ElicitationBlockOptions, type GroupToolActivityOptions, 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 ResolvedReading, type ResolvedResultView, 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 ToolActivityGroup, type ToolCallDescription, type ToolCallState, type ToolCallStatus, type ToolCatalog, type ToolCatalogState, 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 UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, backgroundRunsFromThread, buildTranscriptBlocks, correctedCallIds, createSkillsSource, describeTimestamp, describeToolCall, describeUsage, extractMessageText, fillTemplate, filterAutocompleteItems, findActiveTrigger, formatElapsed, formatRelativeTime, groupToolActivity, inferResultView, isActionCall, loadStoredSpeechLang, persistSpeechLang, phraseFor, readPath, readReasoningMs, resolveResultView, storedMessageToUiMessage, storedThreadToUiMessages, toolCallState, toolCatalogFrom, useAgentChat, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useToolCatalog, useTranscriptItem };