@dudousxd/nestjs-agent-react 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 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, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView, ToolPresentation, ToolResultField, ToolResultView, ToolPresentationTone } from '@dudousxd/nestjs-agent-core';
+import { StoredMessage, ThreadSummary, SkillCatalogEntry, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView, ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React from 'react';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
@@ -74,6 +75,8 @@ interface AgentChatTransportOptions {
  *  - `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`)
+ *  - `approval-settled`   → `data-approval-settled` part keyed by the call id (who decided, through
+ *                           what, remembered or not); the outcome still rides the call's own output
  *  - `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
@@ -233,12 +236,19 @@ declare class AgentClient {
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
     getQuotaToday(): Promise<QuotaToday>;
     cancelStream(runId: string): Promise<CancelResult>;
+    /**
+     * `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).
+     */
     approveToolCall(input: {
         toolCallId: string;
+        remember?: boolean;
+        via?: string;
     }): Promise<void>;
     rejectToolCall(input: {
         toolCallId: string;
         reason?: string;
+        via?: string;
     }): Promise<void>;
     /**
      * Settle a parked question set. `answers` is questionId → chosen option values; a question left
@@ -305,6 +315,26 @@ 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;
 
+/** 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[];
+/** The question fields {@link coerceAnswer} reads. A transcript question and a core one both fit. */
+type CoercibleQuestion = Pick<ElicitationQuestion, 'multiple'> & {
+    input?: {
+        type: ElicitationInputType;
+    } | null;
+};
+/**
+ * Turn whatever a form control produced into the `string[]` the answer route takes, in the
+ * question's canonical form: numbers as decimals, booleans as `"true"`/`"false"`, dates as
+ * `YYYY-MM-DD` (a `Date` is read as the local calendar day), trimmed where whitespace means
+ * nothing. An empty value becomes `[]` — no answer, not an empty string. A single-choice question
+ * keeps the first value.
+ *
+ * Coercion never judges: pair it with {@link validateAnswer} (the same rules the server applies) to
+ * say what is wrong before sending.
+ */
+declare function coerceAnswer(question: CoercibleQuestion, raw: RawAnswer): string[];
+
 /** 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. */
@@ -540,16 +570,38 @@ interface TranscriptSettleState {
     isSubmitting: boolean;
     run: () => void;
 }
+/** How an approval stands. */
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
 /**
- * Who has to settle a parked call, and until when — from the stream's `approval-requested` frame.
+ * 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 {
     /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
     approver: string;
-    /** ISO-8601; `null` when the request never lapses. */
+    /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
     expiresAt: string | null;
+    /** Why the call needs a person, when the runner said. */
     reason: string | null;
+    /**
+     * `pending` until a settlement arrives; then what it said. Falls back to the call's own state
+     * (denied → `rejected`, an output → `approved`) for a runner that streams no settlement.
+     */
+    status: TranscriptApprovalStatus;
+    /** The approval also covers later calls of this tool in this thread. */
+    remember: boolean;
+    /** Opaque ref of who decided; `null` while pending, on an expiry, or when the runner did not say. */
+    decidedBy: string | null;
+    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    decidedVia: string | null;
+    /** What the person said when declining. */
+    decisionReason: string | null;
+}
+/** What an approval can carry beyond yes. */
+interface ApproveOptions {
+    /** Approve later calls of the same tool in the same thread without asking again. */
+    remember?: boolean;
 }
 /** One call in a tool run, with whatever human decision it is parked on. */
 interface TranscriptToolCall {
@@ -578,7 +630,10 @@ interface TranscriptToolCall {
      * IS the pending approval.
      */
     isAwaitingApproval: boolean;
-    approve: TranscriptSettleState;
+    /** `run({ remember: true })` approves this tool for the rest of the thread. */
+    approve: TranscriptSettleState & {
+        run: (options?: ApproveOptions) => void;
+    };
     reject: TranscriptSettleState;
     /** A failed decision — the call is still parked, so the affordance stays live. */
     error: string | null;
@@ -635,6 +690,14 @@ interface TranscriptQuestionOption {
 interface TranscriptQuestion {
     id: string;
     prompt: string;
+    /** A line of help under the prompt; `null` when the request gave none. */
+    description: string | null;
+    /**
+     * How the answer is typed — `{ type, placeholder?, required?, min?, max?, pattern? }` — or `null`
+     * for a plain pick from `options`. Render the control from `input.type`; `select` still picks
+     * from `options`.
+     */
+    input: ElicitationInput | null;
     multiple: boolean;
     /** 1-based. The request carries every question up front, so "Question 1 of N" is honest. */
     position: number;
@@ -646,6 +709,20 @@ interface TranscriptQuestion {
      * first is recorded as `defaulted` rather than as a choice the user made.
      */
     isPristine: boolean;
+    /** The first selected value, or `''` — what a single text/number/date field shows. */
+    value: string;
+    /**
+     * Set a typed answer from whatever the control produced (a string, a number, a checkbox's
+     * boolean, a `Date`, a list); coerced to the question's canonical strings with `coerceAnswer`.
+     * `null`/`''` clears it. Does nothing once the set settled.
+     */
+    setValue: (raw: RawAnswer) => void;
+    /**
+     * Why the current selection would be refused (the server's own rules — `validateAnswer`), or
+     * `null`. A pristine required question with no default reads `requires an answer`; show it once
+     * the user tried to submit, or right away — the model does not decide that for you.
+     */
+    error: string | null;
 }
 /** How a question set settled, once it did. */
 interface TranscriptElicitationOutcome {
@@ -672,6 +749,8 @@ interface TranscriptElicitationBlock {
     questionCount: number;
     /** Still waiting on a human. */
     isPending: boolean;
+    /** Every question's current selection is acceptable (no question has an `error`). */
+    isValid: boolean;
     outcome: TranscriptElicitationOutcome | null;
     /** A failed submission — the run is still parked, so the form stays live. */
     error: string | null;
@@ -729,7 +808,7 @@ interface ElicitationBlockOptions {
 interface ApprovalBlockOptions {
     canApprove: boolean;
     canReject: boolean;
-    approve: (toolCallId: string) => void;
+    approve: (toolCallId: string, options?: ApproveOptions) => void;
     reject: (toolCallId: string) => void;
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
@@ -904,8 +983,11 @@ interface TranscriptItemOptions {
     onAnswer?: (toolCallId: string, answers: Record<string, string[]>) => void | Promise<void>;
     /** Decline the question set and let the agent proceed on its own picks — `useAgentChat`'s `skip`. */
     onSkip?: (toolCallId: string) => void | Promise<void>;
-    /** Settle a tool call parked on a human — `useAgentChat`'s `approve` / `reject`. */
-    onApprove?: (toolCallId: string) => void | Promise<void>;
+    /**
+     * Settle a tool call parked on a human — `useAgentChat`'s `approve` / `reject`. `options.remember`
+     * is what `call.approve.run({ remember: true })` passed.
+     */
+    onApprove?: (toolCallId: string, options?: ApproveOptions) => void | Promise<void>;
     onReject?: (toolCallId: string) => void | Promise<void>;
 }
 interface TranscriptWindow {
@@ -1374,6 +1456,28 @@ interface ToolCatalogState {
  */
 declare function useToolCatalog(options: UseToolCatalogOptions): ToolCatalogState;
 
+interface ApprovalCountdown {
+    /** Milliseconds until the request lapses, floored at 0; `null` when it never does. */
+    remainingMs: number | null;
+    /** The instant has passed. Always `false` for a request with no expiry. */
+    isExpired: boolean;
+}
+interface UseApprovalCountdownOptions {
+    /** How often the value re-renders while counting. Default 1000 — a seconds label needs no more. */
+    intervalMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+/** What {@link useApprovalCountdown} reads for `expiresAt` at `now`, without the ticking. */
+declare function approvalCountdown(expiresAt: string | null | undefined, now?: number): ApprovalCountdown;
+/**
+ * Time left on an approval request (`call.approval.expiresAt`), ticking until it lapses and then
+ * holding at zero. Headless: pair `remainingMs` with `formatElapsed` or any label of your own, and
+ * use `isExpired` to stop offering buttons the server would refuse (`410 Gone`). The server stays
+ * the authority — a lapse is final only once the call settles `expired`.
+ */
+declare function useApprovalCountdown(expiresAt: string | null | undefined, options?: UseApprovalCountdownOptions): ApprovalCountdown;
+
 /** The thinking time stamped on a reasoning part, or `null` when it carries none. */
 declare function readReasoningMs(part: {
     providerMetadata?: unknown;
@@ -1621,12 +1725,16 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     quota: _dudousxd_nestjs_agent_core.QuotaView | null;
     loadQuota: () => Promise<QuotaToday>;
     cancel: () => Promise<void>;
-    approve: ({ toolCallId }: {
+    approve: ({ toolCallId, remember, via, }: {
         toolCallId: string;
+        /** Approve later calls of the same tool in this thread without asking. */
+        remember?: boolean;
+        via?: string;
     }) => Promise<void>;
-    reject: ({ toolCallId, reason, }: {
+    reject: ({ toolCallId, reason, via, }: {
         toolCallId: string;
         reason?: string;
+        via?: string;
     }) => Promise<void>;
     answer: ({ toolCallId, answers, }: {
         toolCallId: string;
@@ -1648,4 +1756,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 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 };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type ApprovalBlockOptions, type ApprovalCountdown, type ApproveOptions, 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 CoercibleQuestion, 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 RawAnswer, 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 TranscriptApprovalStatus, 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 UseApprovalCountdownOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseSpeechRecognitionOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, buildTranscriptBlocks, coerceAnswer, 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, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useToolCatalog, useTranscriptItem };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView, ToolPresentation, ToolResultField, ToolResultView, ToolPresentationTone } from '@dudousxd/nestjs-agent-core';
+import { StoredMessage, ThreadSummary, SkillCatalogEntry, ToolCatalogEntry, ThreadDetail, MessageAttachment, QuotaView, ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+export { ElicitationInput, ElicitationInputType, validateElicitationAnswer as validateAnswer, validateElicitationValue as validateAnswerValue } from '@dudousxd/nestjs-agent-core';
 import React from 'react';
 
 /** Identity surfaced by the backend's `meta` SSE frame / response headers. */
@@ -74,6 +75,8 @@ interface AgentChatTransportOptions {
  *  - `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`)
+ *  - `approval-settled`   → `data-approval-settled` part keyed by the call id (who decided, through
+ *                           what, remembered or not); the outcome still rides the call's own output
  *  - `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
@@ -233,12 +236,19 @@ declare class AgentClient {
     truncateFromMessage(threadId: string, messageId: string): Promise<OkResult>;
     getQuotaToday(): Promise<QuotaToday>;
     cancelStream(runId: string): Promise<CancelResult>;
+    /**
+     * `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).
+     */
     approveToolCall(input: {
         toolCallId: string;
+        remember?: boolean;
+        via?: string;
     }): Promise<void>;
     rejectToolCall(input: {
         toolCallId: string;
         reason?: string;
+        via?: string;
     }): Promise<void>;
     /**
      * Settle a parked question set. `answers` is questionId → chosen option values; a question left
@@ -305,6 +315,26 @@ 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;
 
+/** 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[];
+/** The question fields {@link coerceAnswer} reads. A transcript question and a core one both fit. */
+type CoercibleQuestion = Pick<ElicitationQuestion, 'multiple'> & {
+    input?: {
+        type: ElicitationInputType;
+    } | null;
+};
+/**
+ * Turn whatever a form control produced into the `string[]` the answer route takes, in the
+ * question's canonical form: numbers as decimals, booleans as `"true"`/`"false"`, dates as
+ * `YYYY-MM-DD` (a `Date` is read as the local calendar day), trimmed where whitespace means
+ * nothing. An empty value becomes `[]` — no answer, not an empty string. A single-choice question
+ * keeps the first value.
+ *
+ * Coercion never judges: pair it with {@link validateAnswer} (the same rules the server applies) to
+ * say what is wrong before sending.
+ */
+declare function coerceAnswer(question: CoercibleQuestion, raw: RawAnswer): string[];
+
 /** 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. */
@@ -540,16 +570,38 @@ interface TranscriptSettleState {
     isSubmitting: boolean;
     run: () => void;
 }
+/** How an approval stands. */
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
 /**
- * Who has to settle a parked call, and until when — from the stream's `approval-requested` frame.
+ * 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 {
     /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
     approver: string;
-    /** ISO-8601; `null` when the request never lapses. */
+    /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
     expiresAt: string | null;
+    /** Why the call needs a person, when the runner said. */
     reason: string | null;
+    /**
+     * `pending` until a settlement arrives; then what it said. Falls back to the call's own state
+     * (denied → `rejected`, an output → `approved`) for a runner that streams no settlement.
+     */
+    status: TranscriptApprovalStatus;
+    /** The approval also covers later calls of this tool in this thread. */
+    remember: boolean;
+    /** Opaque ref of who decided; `null` while pending, on an expiry, or when the runner did not say. */
+    decidedBy: string | null;
+    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    decidedVia: string | null;
+    /** What the person said when declining. */
+    decisionReason: string | null;
+}
+/** What an approval can carry beyond yes. */
+interface ApproveOptions {
+    /** Approve later calls of the same tool in the same thread without asking again. */
+    remember?: boolean;
 }
 /** One call in a tool run, with whatever human decision it is parked on. */
 interface TranscriptToolCall {
@@ -578,7 +630,10 @@ interface TranscriptToolCall {
      * IS the pending approval.
      */
     isAwaitingApproval: boolean;
-    approve: TranscriptSettleState;
+    /** `run({ remember: true })` approves this tool for the rest of the thread. */
+    approve: TranscriptSettleState & {
+        run: (options?: ApproveOptions) => void;
+    };
     reject: TranscriptSettleState;
     /** A failed decision — the call is still parked, so the affordance stays live. */
     error: string | null;
@@ -635,6 +690,14 @@ interface TranscriptQuestionOption {
 interface TranscriptQuestion {
     id: string;
     prompt: string;
+    /** A line of help under the prompt; `null` when the request gave none. */
+    description: string | null;
+    /**
+     * How the answer is typed — `{ type, placeholder?, required?, min?, max?, pattern? }` — or `null`
+     * for a plain pick from `options`. Render the control from `input.type`; `select` still picks
+     * from `options`.
+     */
+    input: ElicitationInput | null;
     multiple: boolean;
     /** 1-based. The request carries every question up front, so "Question 1 of N" is honest. */
     position: number;
@@ -646,6 +709,20 @@ interface TranscriptQuestion {
      * first is recorded as `defaulted` rather than as a choice the user made.
      */
     isPristine: boolean;
+    /** The first selected value, or `''` — what a single text/number/date field shows. */
+    value: string;
+    /**
+     * Set a typed answer from whatever the control produced (a string, a number, a checkbox's
+     * boolean, a `Date`, a list); coerced to the question's canonical strings with `coerceAnswer`.
+     * `null`/`''` clears it. Does nothing once the set settled.
+     */
+    setValue: (raw: RawAnswer) => void;
+    /**
+     * Why the current selection would be refused (the server's own rules — `validateAnswer`), or
+     * `null`. A pristine required question with no default reads `requires an answer`; show it once
+     * the user tried to submit, or right away — the model does not decide that for you.
+     */
+    error: string | null;
 }
 /** How a question set settled, once it did. */
 interface TranscriptElicitationOutcome {
@@ -672,6 +749,8 @@ interface TranscriptElicitationBlock {
     questionCount: number;
     /** Still waiting on a human. */
     isPending: boolean;
+    /** Every question's current selection is acceptable (no question has an `error`). */
+    isValid: boolean;
     outcome: TranscriptElicitationOutcome | null;
     /** A failed submission — the run is still parked, so the form stays live. */
     error: string | null;
@@ -729,7 +808,7 @@ interface ElicitationBlockOptions {
 interface ApprovalBlockOptions {
     canApprove: boolean;
     canReject: boolean;
-    approve: (toolCallId: string) => void;
+    approve: (toolCallId: string, options?: ApproveOptions) => void;
     reject: (toolCallId: string) => void;
     /** Which decision this call is sending, or `null` for none. */
     submitting: (toolCallId: string) => SettleAction | null;
@@ -904,8 +983,11 @@ interface TranscriptItemOptions {
     onAnswer?: (toolCallId: string, answers: Record<string, string[]>) => void | Promise<void>;
     /** Decline the question set and let the agent proceed on its own picks — `useAgentChat`'s `skip`. */
     onSkip?: (toolCallId: string) => void | Promise<void>;
-    /** Settle a tool call parked on a human — `useAgentChat`'s `approve` / `reject`. */
-    onApprove?: (toolCallId: string) => void | Promise<void>;
+    /**
+     * Settle a tool call parked on a human — `useAgentChat`'s `approve` / `reject`. `options.remember`
+     * is what `call.approve.run({ remember: true })` passed.
+     */
+    onApprove?: (toolCallId: string, options?: ApproveOptions) => void | Promise<void>;
     onReject?: (toolCallId: string) => void | Promise<void>;
 }
 interface TranscriptWindow {
@@ -1374,6 +1456,28 @@ interface ToolCatalogState {
  */
 declare function useToolCatalog(options: UseToolCatalogOptions): ToolCatalogState;
 
+interface ApprovalCountdown {
+    /** Milliseconds until the request lapses, floored at 0; `null` when it never does. */
+    remainingMs: number | null;
+    /** The instant has passed. Always `false` for a request with no expiry. */
+    isExpired: boolean;
+}
+interface UseApprovalCountdownOptions {
+    /** How often the value re-renders while counting. Default 1000 — a seconds label needs no more. */
+    intervalMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+}
+/** What {@link useApprovalCountdown} reads for `expiresAt` at `now`, without the ticking. */
+declare function approvalCountdown(expiresAt: string | null | undefined, now?: number): ApprovalCountdown;
+/**
+ * Time left on an approval request (`call.approval.expiresAt`), ticking until it lapses and then
+ * holding at zero. Headless: pair `remainingMs` with `formatElapsed` or any label of your own, and
+ * use `isExpired` to stop offering buttons the server would refuse (`410 Gone`). The server stays
+ * the authority — a lapse is final only once the call settles `expired`.
+ */
+declare function useApprovalCountdown(expiresAt: string | null | undefined, options?: UseApprovalCountdownOptions): ApprovalCountdown;
+
 /** The thinking time stamped on a reasoning part, or `null` when it carries none. */
 declare function readReasoningMs(part: {
     providerMetadata?: unknown;
@@ -1621,12 +1725,16 @@ declare function useAgentChat(options: UseAgentChatOptions): {
     quota: _dudousxd_nestjs_agent_core.QuotaView | null;
     loadQuota: () => Promise<QuotaToday>;
     cancel: () => Promise<void>;
-    approve: ({ toolCallId }: {
+    approve: ({ toolCallId, remember, via, }: {
         toolCallId: string;
+        /** Approve later calls of the same tool in this thread without asking. */
+        remember?: boolean;
+        via?: string;
     }) => Promise<void>;
-    reject: ({ toolCallId, reason, }: {
+    reject: ({ toolCallId, reason, via, }: {
         toolCallId: string;
         reason?: string;
+        via?: string;
     }) => Promise<void>;
     answer: ({ toolCallId, answers, }: {
         toolCallId: string;
@@ -1648,4 +1756,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 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 };
+export { AgentChatTransport, type AgentChatTransportOptions, AgentClient, type AgentClientOptions, AgentHttpError, type AgentStreamMeta, type AggregatedTurnUsage, type AnyToolUIPart, type ApprovalBlockOptions, type ApprovalCountdown, type ApproveOptions, 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 CoercibleQuestion, 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 RawAnswer, 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 TranscriptApprovalStatus, 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 UseApprovalCountdownOptions, type UseChatTranscriptOptions, type UseComposerAutocompleteOptions, type UseElapsedOptions, type UseSpeechRecognitionOptions, type UseToolCatalogOptions, type UseTranscriptItemOptions, applyCompletion, approvalCountdown, backgroundRunsFromThread, buildTranscriptBlocks, coerceAnswer, 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, useApprovalCountdown, useChatTranscript, useComposerAutocomplete, useElapsed, useSpeechRecognition, useStickToBottom, useToolCatalog, useTranscriptItem };