@dudousxd/nestjs-agent-react 0.32.0 → 0.34.0

package/README.md

@@ -7,6 +7,13 @@ SSE, plus threads, personas, quota, cancel, and human-in-the-loop approve/reject
 turns the streamed messages into a renderable model — grouped parts, derived values, actions as state
 machines — and the chat components are one rendering of it. Optional rich-markdown subpath.
 
+## Component registries and server rendering
+
+Tools support a `present` hook in both functional and decorated class forms. Register custom components per app, share React renderers between web screens and static exports, and generate paginated PNG/PDF tables and charts for your own delivery adapters.
+
+See the [component rendering guide](../../docs/component-rendering.md) for complete examples, schemas, text fallbacks, and capture configuration.
+
+
 ## Install
 
 ```bash

package/dist/{client-C7eu9WMJ.d.cts → client-BdHUuqy-.d.cts}

@@ -1,4 +1,4 @@
-import { ChatQueueState, ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
+import { ActionProposalMutationView, ChatQueueState, ThreadSummary, ThreadDetail, ActionProposalView, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
 
 /**
  * What a server said when it refused a request, read once so every error class of this package
@@ -67,6 +67,14 @@ interface ResumeStreamRequest {
  * headers). The body's own `event: meta` frame supplies them otherwise.
  */
 interface ChatStreamResponse {
+    proposalDecision?: {
+        threadId: string;
+        proposalDecision: ActionProposalMutationView | {
+            status: 'ambiguous';
+            proposalIds: string[];
+        };
+        text?: string;
+    };
     body: ReadableStream<Uint8Array>;
     runId?: string;
     threadId?: string;
@@ -189,6 +197,19 @@ interface AgentBackend {
     forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
     promoteThread?(id: string): Promise<unknown>;
     truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
+    listActionProposals?(input: {
+        threadId: string;
+    }): Promise<ActionProposalView[]>;
+    approveActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationView>;
+    rejectActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationView>;
     approveToolCall?(input: {
         toolCallId: string;
         remember?: boolean;
@@ -392,6 +413,19 @@ declare class AgentClient implements AgentBackend {
      * `remember` approves later calls of the same tool in the same thread; `via` names the surface
      * the decision came through (the server records `'web'` when omitted).
      */
+    listActionProposals({ threadId }: {
+        threadId: string;
+    }): Promise<ActionProposalView[]>;
+    approveActionProposal({ threadId, proposalId, remember, }: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationView>;
+    rejectActionProposal({ threadId, proposalId, reason, }: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationView>;
     approveToolCall(input: {
         toolCallId: string;
         remember?: boolean;
@@ -433,6 +467,7 @@ declare class AgentClient implements AgentBackend {
     private resolveHeaders;
     private credentials;
     private request;
+    private requestResponse;
     /** The error for a refused `response`, already reported to `onHttpError`. */
     private failure;
     private handleResponse;

package/dist/{client-C7eu9WMJ.d.ts → client-BdHUuqy-.d.ts}

@@ -1,4 +1,4 @@
-import { ChatQueueState, ThreadSummary, ThreadDetail, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
+import { ActionProposalMutationView, ChatQueueState, ThreadSummary, ThreadDetail, ActionProposalView, MessageAttachment, ToolCatalogEntry, SkillCatalogEntry, QuotaReport, ModelCatalogView, AgentCatalogEntry, AgentClientConfig, MessageFeedbackValue, MessageFeedback } from '@dudousxd/nestjs-agent-core';
 
 /**
  * What a server said when it refused a request, read once so every error class of this package
@@ -67,6 +67,14 @@ interface ResumeStreamRequest {
  * headers). The body's own `event: meta` frame supplies them otherwise.
  */
 interface ChatStreamResponse {
+    proposalDecision?: {
+        threadId: string;
+        proposalDecision: ActionProposalMutationView | {
+            status: 'ambiguous';
+            proposalIds: string[];
+        };
+        text?: string;
+    };
     body: ReadableStream<Uint8Array>;
     runId?: string;
     threadId?: string;
@@ -189,6 +197,19 @@ interface AgentBackend {
     forkFromMessage?(threadId: string, messageId: string): Promise<ThreadSummary>;
     promoteThread?(id: string): Promise<unknown>;
     truncateFromMessage?(threadId: string, messageId: string): Promise<unknown>;
+    listActionProposals?(input: {
+        threadId: string;
+    }): Promise<ActionProposalView[]>;
+    approveActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationView>;
+    rejectActionProposal?(input: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationView>;
     approveToolCall?(input: {
         toolCallId: string;
         remember?: boolean;
@@ -392,6 +413,19 @@ declare class AgentClient implements AgentBackend {
      * `remember` approves later calls of the same tool in the same thread; `via` names the surface
      * the decision came through (the server records `'web'` when omitted).
      */
+    listActionProposals({ threadId }: {
+        threadId: string;
+    }): Promise<ActionProposalView[]>;
+    approveActionProposal({ threadId, proposalId, remember, }: {
+        threadId: string;
+        proposalId: string;
+        remember?: boolean;
+    }): Promise<ActionProposalMutationView>;
+    rejectActionProposal({ threadId, proposalId, reason, }: {
+        threadId: string;
+        proposalId: string;
+        reason?: string;
+    }): Promise<ActionProposalMutationView>;
     approveToolCall(input: {
         toolCallId: string;
         remember?: boolean;
@@ -433,6 +467,7 @@ declare class AgentClient implements AgentBackend {
     private resolveHeaders;
     private credentials;
     private request;
+    private requestResponse;
     /** The error for a refused `response`, already reported to `onHttpError`. */
     private failure;
     private handleResponse;

package/dist/{generative-ui-VTZ1EADD.d.cts → generative-ui-CyHY8Lh1.d.cts}

@@ -1,7 +1,20 @@
 import * as React from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
-import { ToolUIPart, DynamicToolUIPart, UIMessage } from 'ai';
+import { ReactNode } from 'react';
+import { ActionProposalView, StoredMessage, ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ToolConfirmation, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+import { UIMessage, ToolUIPart, DynamicToolUIPart } from 'ai';
+import { c as GenerativeUIOptions, G as GenerativeUIItem, d as GenerativeUIProblem, b as GenerativeUIElement, e as GenerativeUIState } from './types-DZtFsWec.cjs';
+
+type ApprovalTarget = {
+    kind: 'legacy';
+    toolCallId: string;
+} | {
+    kind: 'proposal';
+    proposalId: string;
+    threadId?: string;
+};
+declare function proposalNeedsPolling(proposal: ActionProposalView): boolean;
+/** Patch proposal metadata and append outcome facts; never replace live text with stored rows. */
+declare function reconcileProposalMessages(current: UIMessage[], proposals: ActionProposalView[], facts: StoredMessage[]): UIMessage[];
 
 /** What a form control can hand over: a field's value, a checkbox's state, a picked date, a list. */
 type RawAnswer = string | number | boolean | Date | null | undefined | readonly RawAnswer[];
@@ -96,7 +109,7 @@ declare function resolveResultView(output: unknown, view: ToolResultView | undef
  *  - `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';
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied' | 'queued' | 'executing' | 'succeeded';
 interface ToolCallState {
     status: ToolCallStatus;
     isSettled: boolean;
@@ -136,6 +149,8 @@ interface ToolCallDescription {
     presentation: ToolPresentation | null;
 }
 interface DescribeToolCallOptions {
+    /** Resolved strings from the call preflight override the tool catalog templates. */
+    confirmation?: ToolConfirmation;
     /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
     fallback?: {
         running: string;
@@ -263,13 +278,16 @@ interface TranscriptSettleState {
     run: () => void;
 }
 /** How an approval stands. */
-type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
 /**
  * Who has to settle a parked call, until when, and — once it settled — how. From the stream's
  * `approval-requested` / `approval-settled` frames, or the same parts a reloaded thread carries.
  * `null` on a call whose runner never said (the call can still be awaiting approval).
  */
 interface TranscriptApproval {
+    target?: ApprovalTarget;
+    executionStatus?: 'queued' | 'executing' | 'succeeded' | 'failed' | null;
+    confirmation?: ToolConfirmation;
     /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
     approver: string;
     /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
@@ -371,6 +389,8 @@ interface TranscriptUiBlock {
     props: Record<string, unknown>;
     /** Schema version of `props`; `null` when the server did not stamp one. */
     version: number | null;
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     /** The tool call that pushed it (`ctx.emitUi`); `null` for a component pushed outside a tool. */
     toolCallId: string | null;
 }
@@ -516,8 +536,8 @@ interface ElicitationBlockOptions {
 interface ApprovalBlockOptions {
     canApprove: boolean;
     canReject: boolean;
-    approve: (toolCallId: string, options?: ApproveOptions) => void;
-    reject: (toolCallId: string) => void;
+    approve: (toolCallId: string, options?: ApproveOptions, target?: ApprovalTarget) => void;
+    reject: (toolCallId: string, target?: ApprovalTarget) => void;
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
@@ -576,97 +596,6 @@ declare function describeTimestamp(createdAt: string | null | undefined): Timest
  */
 declare function formatRelativeTime(date: Date): string;
 
-/** The `ui` frame component a composed tree is pushed under (`GENUI_TREE_COMPONENT` of `@dudousxd/nestjs-agent-core/genui`). */
-declare const GENUI_TREE_COMPONENT = "genui:tree";
-/** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
-interface GenerativeUIItem {
-    id: string;
-    component: string;
-    props: Record<string, unknown>;
-    version: number | null;
-    toolCallId: string | null;
-}
-/** A node of a composed tree (`genui:tree` frames): `{ type, props, children? }`. */
-interface GenerativeUIElement {
-    type: string;
-    props: Record<string, unknown>;
-    children?: GenerativeUIElement[];
-}
-/**
- * An app's renderer for one component: it receives the component's props spread, plus `children`
- * when it is a layout node in a tree. Any React component — the library never styles anything.
- */
-type GenuiRenderer<P = any> = ComponentType<P & {
-    children?: ReactNode;
-}>;
-/** Component name → the app's renderer. */
-type GenuiRegistry = Record<string, GenuiRenderer>;
-/**
- * Resolve a component the registry does not have — typically a tenant's own component, fetched for
- * the exact `version` a message was rendered with. Return `null`/`undefined` for "no such
- * component". May be async; results are cached per resolver, name and version.
- */
-type ResolveComponent = (name: string, version: number | null) => GenuiRenderer | null | undefined | Promise<GenuiRenderer | null | undefined>;
-interface GenuiIssueLike {
-    path: (string | number)[];
-    message: string;
-}
-type ValidationLike = {
-    ok: true;
-    value: Record<string, unknown>;
-} | {
-    ok: false;
-    issues: GenuiIssueLike[];
-};
-/**
- * What the renderer needs from a catalog to validate props before drawing them. A `Catalog` from
- * `@dudousxd/nestjs-agent-core/genui` satisfies it; declared structurally so any catalog-shaped
- * object does too.
- */
-interface GenuiCatalogLike {
-    has(name: string): boolean;
-    validate(name: string, props: unknown): Promise<ValidationLike>;
-    validateSync?(name: string, props: unknown): ValidationLike | undefined;
-}
-interface GenerativeUIOptions {
-    registry: GenuiRegistry;
-    /** Validate props against it before rendering. Components the catalog does not know render unvalidated. */
-    catalog?: GenuiCatalogLike;
-    resolveComponent?: ResolveComponent;
-    /**
-     * Draws a composed tree frame (`genui:tree`) whole — e.g. through json-render (see the
-     * `/genui/json-render` subpath's `GenuiProvider`). Omitted → trees render node by node through
-     * `registry`.
-     */
-    treeRenderer?: GenuiRenderer<{
-        root?: GenerativeUIElement;
-    }>;
-}
-/** Why an item did not render. */
-type GenerativeUIProblem = {
-    reason: 'unknown';
-    item: GenerativeUIItem;
-} | {
-    reason: 'invalid';
-    item: GenerativeUIItem;
-    issues: GenuiIssueLike[];
-} | {
-    reason: 'error';
-    item: GenerativeUIItem;
-    error: unknown;
-};
-type GenerativeUIState = {
-    status: 'ready';
-    item: GenerativeUIItem;
-    Component: GenuiRenderer;
-    props: Record<string, unknown>;
-} | {
-    status: 'loading';
-    item: GenerativeUIItem;
-} | ({
-    status: 'problem';
-} & GenerativeUIProblem);
-
 /** What to draw instead of a component that did not render. Default: nothing. */
 type GenerativeUIFallback = ReactNode | ((problem: GenerativeUIProblem) => ReactNode);
 /**
@@ -678,6 +607,8 @@ declare function GenuiTree({ root }: {
     root?: GenerativeUIElement;
 }): React.JSX.Element | null;
 interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     fallback?: GenerativeUIFallback;
     loading?: ReactNode;
     onError?: (error: unknown, item: GenerativeUIItem) => void;
@@ -687,7 +618,7 @@ interface GenerativeUIScopeProps extends GenerativeUIOptions {
  * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
  * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
  */
-declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, fallbackText, componentVersions, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
 /** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
 interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
     fallback?: GenerativeUIFallback;
@@ -720,7 +651,7 @@ declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOp
 interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
     /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
     part: TranscriptUiBlock | GenerativeUIItem | unknown;
-    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, then the item's persisted text. */
     fallback?: GenerativeUIFallback;
     /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
     loading?: ReactNode;
@@ -738,4 +669,4 @@ interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
  */
 declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 
-export { type TranscriptQuestionOption as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type CoercibleQuestion as D, type DescribeToolCallOptions as E, type ElicitationBlockOptions as F, type GenerativeUIItem as G, type GroupToolActivityOptions as H, type RawAnswer as I, type ResolvedReading as J, type ResolvedResultView as K, type RetrievedPassage as L, type MessageUsageInfo as M, type ToolActivityGroup as N, type ToolCallDescription as O, type ToolCallState as P, type ToolCallStatus as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptApproval as V, type TranscriptApprovalStatus as W, type TranscriptElicitationBlock as X, type TranscriptElicitationOutcome as Y, type TranscriptFilesBlock as Z, type TranscriptQuestion as _, GENUI_TREE_COMPONENT as a, type TranscriptReasoningBlock as a0, type TranscriptSettleState as a1, type TranscriptSource as a2, type TranscriptSourcesBlock as a3, type TranscriptTextBlock as a4, type TranscriptToolBlock as a5, type TranscriptToolCall as a6, buildTranscriptBlocks as a7, coerceAnswer as a8, correctedCallIds as a9, describeTimestamp as aa, describeToolCall as ab, describeUsage as ac, extractMessageText as ad, fillTemplate as ae, formatRelativeTime as af, groupToolActivity as ag, inferResultView as ah, isActionCall as ai, phraseFor as aj, readPath as ak, resolveResultView as al, toolCallState as am, toolCatalogFrom as an, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type TranscriptBlock as t, useGenerativeUI as u, type TimestampInfo as v, type TranscriptFile as w, type ToolCatalog as x, type AnyToolUIPart as y, type ApprovalBlockOptions as z };
+export { correctedCallIds as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type DescribeToolCallOptions as D, type ElicitationBlockOptions as E, type TranscriptApproval as F, GenerativeUI as G, type TranscriptApprovalStatus as H, type TranscriptElicitationBlock as I, type TranscriptElicitationOutcome as J, type TranscriptFilesBlock as K, type TranscriptQuestion as L, type MessageUsageInfo as M, type TranscriptQuestionOption as N, type TranscriptReasoningBlock as O, type TranscriptSettleState as P, type TranscriptSource as Q, type RawAnswer as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptSourcesBlock as V, type TranscriptTextBlock as W, type TranscriptToolBlock as X, type TranscriptToolCall as Y, buildTranscriptBlocks as Z, coerceAnswer as _, type GenerativeUIFallback as a, describeTimestamp as a0, describeToolCall as a1, describeUsage as a2, extractMessageText as a3, fillTemplate as a4, formatRelativeTime as a5, groupToolActivity as a6, inferResultView as a7, isActionCall as a8, phraseFor as a9, proposalNeedsPolling as aa, readPath as ab, reconcileProposalMessages as ac, resolveResultView as ad, toolCallState as ae, toolCatalogFrom as af, type GenerativeUIProps as b, GenerativeUIScope as c, type GenerativeUIScopeProps as d, GenuiProvider as e, type GenuiProviderProps as f, type GenuiProviderValue as g, GenuiTree as h, useGenuiProvider as i, type ApprovalTarget as j, type TranscriptBlock as k, type TimestampInfo as l, type TranscriptFile as m, type ToolCatalog as n, type AnyToolUIPart as o, type ApprovalBlockOptions as p, type CoercibleQuestion as q, type GroupToolActivityOptions as r, type ResolvedReading as s, type ResolvedResultView as t, useGenerativeUI as u, type RetrievedPassage as v, type ToolActivityGroup as w, type ToolCallDescription as x, type ToolCallState as y, type ToolCallStatus as z };

package/dist/{generative-ui-VTZ1EADD.d.ts → generative-ui-DdUZPCXX.d.ts}

@@ -1,7 +1,20 @@
 import * as React from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
-import { ToolUIPart, DynamicToolUIPart, UIMessage } from 'ai';
+import { ReactNode } from 'react';
+import { ActionProposalView, StoredMessage, ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ToolConfirmation, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+import { UIMessage, ToolUIPart, DynamicToolUIPart } from 'ai';
+import { c as GenerativeUIOptions, G as GenerativeUIItem, d as GenerativeUIProblem, b as GenerativeUIElement, e as GenerativeUIState } from './types-DZtFsWec.js';
+
+type ApprovalTarget = {
+    kind: 'legacy';
+    toolCallId: string;
+} | {
+    kind: 'proposal';
+    proposalId: string;
+    threadId?: string;
+};
+declare function proposalNeedsPolling(proposal: ActionProposalView): boolean;
+/** Patch proposal metadata and append outcome facts; never replace live text with stored rows. */
+declare function reconcileProposalMessages(current: UIMessage[], proposals: ActionProposalView[], facts: StoredMessage[]): UIMessage[];
 
 /** What a form control can hand over: a field's value, a checkbox's state, a picked date, a list. */
 type RawAnswer = string | number | boolean | Date | null | undefined | readonly RawAnswer[];
@@ -96,7 +109,7 @@ declare function resolveResultView(output: unknown, view: ToolResultView | undef
  *  - `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';
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied' | 'queued' | 'executing' | 'succeeded';
 interface ToolCallState {
     status: ToolCallStatus;
     isSettled: boolean;
@@ -136,6 +149,8 @@ interface ToolCallDescription {
     presentation: ToolPresentation | null;
 }
 interface DescribeToolCallOptions {
+    /** Resolved strings from the call preflight override the tool catalog templates. */
+    confirmation?: ToolConfirmation;
     /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
     fallback?: {
         running: string;
@@ -263,13 +278,16 @@ interface TranscriptSettleState {
     run: () => void;
 }
 /** How an approval stands. */
-type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
 /**
  * Who has to settle a parked call, until when, and — once it settled — how. From the stream's
  * `approval-requested` / `approval-settled` frames, or the same parts a reloaded thread carries.
  * `null` on a call whose runner never said (the call can still be awaiting approval).
  */
 interface TranscriptApproval {
+    target?: ApprovalTarget;
+    executionStatus?: 'queued' | 'executing' | 'succeeded' | 'failed' | null;
+    confirmation?: ToolConfirmation;
     /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
     approver: string;
     /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
@@ -371,6 +389,8 @@ interface TranscriptUiBlock {
     props: Record<string, unknown>;
     /** Schema version of `props`; `null` when the server did not stamp one. */
     version: number | null;
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     /** The tool call that pushed it (`ctx.emitUi`); `null` for a component pushed outside a tool. */
     toolCallId: string | null;
 }
@@ -516,8 +536,8 @@ interface ElicitationBlockOptions {
 interface ApprovalBlockOptions {
     canApprove: boolean;
     canReject: boolean;
-    approve: (toolCallId: string, options?: ApproveOptions) => void;
-    reject: (toolCallId: string) => void;
+    approve: (toolCallId: string, options?: ApproveOptions, target?: ApprovalTarget) => void;
+    reject: (toolCallId: string, target?: ApprovalTarget) => void;
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
     errorOf: (toolCallId: string) => string | null;
@@ -576,97 +596,6 @@ declare function describeTimestamp(createdAt: string | null | undefined): Timest
  */
 declare function formatRelativeTime(date: Date): string;
 
-/** The `ui` frame component a composed tree is pushed under (`GENUI_TREE_COMPONENT` of `@dudousxd/nestjs-agent-core/genui`). */
-declare const GENUI_TREE_COMPONENT = "genui:tree";
-/** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
-interface GenerativeUIItem {
-    id: string;
-    component: string;
-    props: Record<string, unknown>;
-    version: number | null;
-    toolCallId: string | null;
-}
-/** A node of a composed tree (`genui:tree` frames): `{ type, props, children? }`. */
-interface GenerativeUIElement {
-    type: string;
-    props: Record<string, unknown>;
-    children?: GenerativeUIElement[];
-}
-/**
- * An app's renderer for one component: it receives the component's props spread, plus `children`
- * when it is a layout node in a tree. Any React component — the library never styles anything.
- */
-type GenuiRenderer<P = any> = ComponentType<P & {
-    children?: ReactNode;
-}>;
-/** Component name → the app's renderer. */
-type GenuiRegistry = Record<string, GenuiRenderer>;
-/**
- * Resolve a component the registry does not have — typically a tenant's own component, fetched for
- * the exact `version` a message was rendered with. Return `null`/`undefined` for "no such
- * component". May be async; results are cached per resolver, name and version.
- */
-type ResolveComponent = (name: string, version: number | null) => GenuiRenderer | null | undefined | Promise<GenuiRenderer | null | undefined>;
-interface GenuiIssueLike {
-    path: (string | number)[];
-    message: string;
-}
-type ValidationLike = {
-    ok: true;
-    value: Record<string, unknown>;
-} | {
-    ok: false;
-    issues: GenuiIssueLike[];
-};
-/**
- * What the renderer needs from a catalog to validate props before drawing them. A `Catalog` from
- * `@dudousxd/nestjs-agent-core/genui` satisfies it; declared structurally so any catalog-shaped
- * object does too.
- */
-interface GenuiCatalogLike {
-    has(name: string): boolean;
-    validate(name: string, props: unknown): Promise<ValidationLike>;
-    validateSync?(name: string, props: unknown): ValidationLike | undefined;
-}
-interface GenerativeUIOptions {
-    registry: GenuiRegistry;
-    /** Validate props against it before rendering. Components the catalog does not know render unvalidated. */
-    catalog?: GenuiCatalogLike;
-    resolveComponent?: ResolveComponent;
-    /**
-     * Draws a composed tree frame (`genui:tree`) whole — e.g. through json-render (see the
-     * `/genui/json-render` subpath's `GenuiProvider`). Omitted → trees render node by node through
-     * `registry`.
-     */
-    treeRenderer?: GenuiRenderer<{
-        root?: GenerativeUIElement;
-    }>;
-}
-/** Why an item did not render. */
-type GenerativeUIProblem = {
-    reason: 'unknown';
-    item: GenerativeUIItem;
-} | {
-    reason: 'invalid';
-    item: GenerativeUIItem;
-    issues: GenuiIssueLike[];
-} | {
-    reason: 'error';
-    item: GenerativeUIItem;
-    error: unknown;
-};
-type GenerativeUIState = {
-    status: 'ready';
-    item: GenerativeUIItem;
-    Component: GenuiRenderer;
-    props: Record<string, unknown>;
-} | {
-    status: 'loading';
-    item: GenerativeUIItem;
-} | ({
-    status: 'problem';
-} & GenerativeUIProblem);
-
 /** What to draw instead of a component that did not render. Default: nothing. */
 type GenerativeUIFallback = ReactNode | ((problem: GenerativeUIProblem) => ReactNode);
 /**
@@ -678,6 +607,8 @@ declare function GenuiTree({ root }: {
     root?: GenerativeUIElement;
 }): React.JSX.Element | null;
 interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
     fallback?: GenerativeUIFallback;
     loading?: ReactNode;
     onError?: (error: unknown, item: GenerativeUIItem) => void;
@@ -687,7 +618,7 @@ interface GenerativeUIScopeProps extends GenerativeUIOptions {
  * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
  * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
  */
-declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, fallbackText, componentVersions, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
 /** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
 interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
     fallback?: GenerativeUIFallback;
@@ -720,7 +651,7 @@ declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOp
 interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
     /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
     part: TranscriptUiBlock | GenerativeUIItem | unknown;
-    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, then the item's persisted text. */
     fallback?: GenerativeUIFallback;
     /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
     loading?: ReactNode;
@@ -738,4 +669,4 @@ interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
  */
 declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
 
-export { type TranscriptQuestionOption as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type CoercibleQuestion as D, type DescribeToolCallOptions as E, type ElicitationBlockOptions as F, type GenerativeUIItem as G, type GroupToolActivityOptions as H, type RawAnswer as I, type ResolvedReading as J, type ResolvedResultView as K, type RetrievedPassage as L, type MessageUsageInfo as M, type ToolActivityGroup as N, type ToolCallDescription as O, type ToolCallState as P, type ToolCallStatus as Q, type ResolveComponent as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptApproval as V, type TranscriptApprovalStatus as W, type TranscriptElicitationBlock as X, type TranscriptElicitationOutcome as Y, type TranscriptFilesBlock as Z, type TranscriptQuestion as _, GENUI_TREE_COMPONENT as a, type TranscriptReasoningBlock as a0, type TranscriptSettleState as a1, type TranscriptSource as a2, type TranscriptSourcesBlock as a3, type TranscriptTextBlock as a4, type TranscriptToolBlock as a5, type TranscriptToolCall as a6, buildTranscriptBlocks as a7, coerceAnswer as a8, correctedCallIds as a9, describeTimestamp as aa, describeToolCall as ab, describeUsage as ac, extractMessageText as ad, fillTemplate as ae, formatRelativeTime as af, groupToolActivity as ag, inferResultView as ah, isActionCall as ai, phraseFor as aj, readPath as ak, resolveResultView as al, toolCallState as am, toolCatalogFrom as an, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, type TranscriptBlock as t, useGenerativeUI as u, type TimestampInfo as v, type TranscriptFile as w, type ToolCatalog as x, type AnyToolUIPart as y, type ApprovalBlockOptions as z };
+export { correctedCallIds as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type DescribeToolCallOptions as D, type ElicitationBlockOptions as E, type TranscriptApproval as F, GenerativeUI as G, type TranscriptApprovalStatus as H, type TranscriptElicitationBlock as I, type TranscriptElicitationOutcome as J, type TranscriptFilesBlock as K, type TranscriptQuestion as L, type MessageUsageInfo as M, type TranscriptQuestionOption as N, type TranscriptReasoningBlock as O, type TranscriptSettleState as P, type TranscriptSource as Q, type RawAnswer as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, type TranscriptSourcesBlock as V, type TranscriptTextBlock as W, type TranscriptToolBlock as X, type TranscriptToolCall as Y, buildTranscriptBlocks as Z, coerceAnswer as _, type GenerativeUIFallback as a, describeTimestamp as a0, describeToolCall as a1, describeUsage as a2, extractMessageText as a3, fillTemplate as a4, formatRelativeTime as a5, groupToolActivity as a6, inferResultView as a7, isActionCall as a8, phraseFor as a9, proposalNeedsPolling as aa, readPath as ab, reconcileProposalMessages as ac, resolveResultView as ad, toolCallState as ae, toolCatalogFrom as af, type GenerativeUIProps as b, GenerativeUIScope as c, type GenerativeUIScopeProps as d, GenuiProvider as e, type GenuiProviderProps as f, type GenuiProviderValue as g, GenuiTree as h, useGenuiProvider as i, type ApprovalTarget as j, type TranscriptBlock as k, type TimestampInfo as l, type TranscriptFile as m, type ToolCatalog as n, type AnyToolUIPart as o, type ApprovalBlockOptions as p, type CoercibleQuestion as q, type GroupToolActivityOptions as r, type ResolvedReading as s, type ResolvedResultView as t, useGenerativeUI as u, type RetrievedPassage as v, type ToolActivityGroup as w, type ToolCallDescription as x, type ToolCallState as y, type ToolCallStatus as z };