@dudousxd/nestjs-agent-core 0.19.0 → 0.21.0

package/dist/{tool-Q2rmGeaG.d.cts → tool-CwXibnce.d.cts}

@@ -1,5 +1,74 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * Typed answers for a question set: a question that asks for a number, a date, an email or a
+ * sentence instead of offering options to pick.
+ *
+ * Answers stay `string[]` on the wire whatever the type — the signal that carries them, the row that
+ * records them and the model that reads them back all see strings — so this module fixes ONE
+ * canonical string per type and validates against it:
+ *
+ * | `type`     | canonical value                              |
+ * |------------|----------------------------------------------|
+ * | `text`     | the text                                      |
+ * | `textarea` | the text (newlines kept)                      |
+ * | `number`   | a finite decimal, e.g. `"42"`, `"-1.5"`       |
+ * | `boolean`  | `"true"` or `"false"`                         |
+ * | `date`     | `YYYY-MM-DD`                                  |
+ * | `email`    | an address with one `@` and a dotted domain   |
+ * | `url`      | an absolute `http:`/`https:` URL              |
+ * | `select`   | one of the question's `options[].value`       |
+ *
+ * Pure and dependency-free, so the loop (which filters what it settles on), the HTTP surface (which
+ * refuses what it cannot settle) and a client (which says so before sending) all agree.
+ */
+
+declare const ELICITATION_INPUT_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "url", "select"];
+type ElicitationInputType = (typeof ELICITATION_INPUT_TYPES)[number];
+/** How a question takes its answer when it is not (only) a pick from `options`. */
+interface ElicitationInput {
+    type: ElicitationInputType;
+    /** Hint shown in an empty field. Advisory. */
+    placeholder?: string;
+    /** Submitting without a value is refused. Skipping the whole set is still allowed. */
+    required?: boolean;
+    /**
+     * Lower bound: the smallest number for `number`, the shortest length for `text`/`textarea`, the
+     * earliest `YYYY-MM-DD` for `date`. Ignored for the other types.
+     */
+    min?: number | string;
+    /** Upper bound, read like {@link min}. */
+    max?: number | string;
+    /** A regular expression the WHOLE value must match (`text`, `textarea`, `email`, `url`). */
+    pattern?: string;
+}
+/** The question's options, or none — `options` may be omitted on a typed question. */
+declare function questionOptions(question: ElicitationQuestion): ElicitationOption[];
+/** A question answered by a typed value rather than by picking one of its options. */
+declare function isTypedQuestion(question: ElicitationQuestion): boolean;
+/**
+ * Why `value` is not an acceptable answer to `question`, or `null` when it is. Checks ONE value;
+ * {@link validateElicitationAnswer} checks the list (required, single choice).
+ */
+declare function validateElicitationValue(question: ElicitationQuestion, value: string): string | null;
+/**
+ * Why `values` is not an acceptable answer to `question`, or `null` when it is: a `required`
+ * question left empty, more than one value for a single-choice question, or any value
+ * {@link validateElicitationValue} refuses. An empty string counts as no value.
+ */
+declare function validateElicitationAnswer(question: ElicitationQuestion, values: readonly string[]): string | null;
+/**
+ * Read an {@link ElicitationInput} from untrusted JSON, or `undefined` when it is not one. Unknown
+ * keys are dropped; a malformed optional field is dropped rather than failing the input.
+ */
+declare function readElicitationInput(raw: unknown): ElicitationInput | undefined;
+/**
+ * The questions a parked call carries, read leniently from its recorded input (`{ questions }` —
+ * what both an intake and an `ask` persist). Used where a reply is checked against the questions it
+ * answers; a question that cannot be read is left out rather than failing the rest.
+ */
+declare function readElicitationQuestions(input: unknown): ElicitationQuestion[];
+
 /**
  * Asking the USER a structured question, and waiting for the answer.
  *
@@ -27,7 +96,19 @@ interface ElicitationQuestion {
     /** Unique within its request; the key answers come back under. */
     id: string;
     prompt: string;
-    options: ElicitationOption[];
+    /** A line of help under the prompt. */
+    description?: string;
+    /**
+     * The choices. Required unless {@link input} asks for a typed value — then optional, and a UI may
+     * offer them as suggestions. An `input` of type `select` still picks from these.
+     */
+    options?: ElicitationOption[];
+    /**
+     * Ask for a typed value (a number, a date, a sentence…) instead of — or, for `select`, on top of —
+     * a pick from `options`. The answer is still a `string[]`, in the type's canonical form; see
+     * `elicitation-input.ts`.
+     */
+    input?: ElicitationInput;
     /** More than one option may be chosen. Omit → single choice. */
     multiple?: boolean;
     /**
@@ -323,6 +404,25 @@ interface AgentApprovalRequest {
     /** Why this call needs a person, in words for that person. */
     reason?: string;
 }
+/**
+ * How an approval settled — the other half of {@link AgentApprovalRequest}, under the same `id`.
+ * Metadata again: the call's own outcome still arrives as `tool-output` (approved and ran),
+ * `tool-output-error` (approved and failed) or `tool-output-denied` (rejected or expired).
+ */
+interface AgentApprovalSettlement {
+    id: string;
+    status: 'approved' | 'rejected' | 'expired';
+    /** Repeated from the request, for a call approved without one being streamed (a remembered approval). */
+    approver?: string;
+    /** Opaque ref of who decided. Absent on an expiry. */
+    decidedBy?: string;
+    /** The surface the decision came through: `'web'`, `'slack'`, `'remembered'`, … */
+    decidedVia?: string;
+    /** The approval also covers later calls of this tool in this thread. */
+    remember?: boolean;
+    /** What the person said when declining. */
+    reason?: string;
+}
 type AgentStreamEvent = {
     kind: 'step-start';
 }
@@ -414,6 +514,14 @@ type AgentStreamEvent = {
  | ({
     kind: 'approval-requested';
 } & AgentApprovalRequest)
+/**
+ * A parked action call was decided (or lapsed). Optional, like `approval-requested`: it adds WHO
+ * decided, THROUGH WHAT and whether the approval is REMEMBERED; the outcome itself rides the
+ * call's own output frame. See {@link AgentApprovalSettlement}.
+ */
+ | ({
+    kind: 'approval-settled';
+} & AgentApprovalSettlement)
 /**
  * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
  * call. See {@link AgentUiComponent}.
@@ -738,6 +846,12 @@ interface ToolResult {
      * tool's outcome on; this flag is what everything else reads.
      */
     denied?: true;
+    /**
+     * The approval request lapsed before anyone decided, so the tool never ran. Always set together
+     * with {@link denied}: an expiry IS a refusal to every consumer that only knows that much, and this
+     * flag is for the ones that tell "nobody answered" from "someone said no".
+     */
+    expired?: true;
     id: string;
     name: string;
     output: unknown;
@@ -817,6 +931,22 @@ interface Decision {
      * (the chat flow).
      */
     executedByRef?: string;
+    /**
+     * Approve later calls of the SAME tool in the SAME thread without asking again. Read only on an
+     * approval; the loop answers it through {@link import('./spi/agent-store.js').AgentStore.rememberedApprovals}.
+     */
+    remember?: boolean;
+    /**
+     * The surface the decision came through — `'web'`, `'slack'`, `'console'`, anything the caller
+     * names. Provenance only: persisted with the call, never authorized against.
+     */
+    decidedVia?: string;
+    /**
+     * Nobody decided before the request lapsed. Set by the RUNNER when the approval wait times out
+     * (see `AgentLoopHooks.awaitApproval`'s `timeoutMs`), never by a person — the HTTP surface does not
+     * accept it. Read as a denial the model is told expired.
+     */
+    expired?: true;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
 /**
@@ -1044,13 +1174,44 @@ interface StoredMessage {
      * props for each `id` — a reloaded thread replays them as `data-ui` parts.
      */
     ui?: AgentUiComponent[];
+    /**
+     * The approval record of every call on this message that was put to a person under an
+     * {@link import('./spi/approval-policy.js').ApprovalPolicy} — who had to decide, until when, and how
+     * it settled. Read off the tool-call rows by the store; absent when no call on the message asked
+     * for one, or on a store that does not record approvals.
+     */
+    approvals?: ToolCallApproval[];
     createdAt: string;
 }
+/**
+ * How one approval stands. `pending` → still parked; `approved` → someone said yes (or a remembered
+ * approval did); `rejected` → someone said no; `expired` → nobody answered before `expiresAt`.
+ */
+type ToolCallApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+/** The persisted approval metadata of one action tool call. See {@link StoredMessage.approvals}. */
+interface ToolCallApproval {
+    toolCallId: string;
+    /** Who may decide: `'requester'` (the thread's own actor) or a role name. */
+    approver: string;
+    /** ISO-8601 instant the request lapses; absent → it never does. */
+    expiresAt?: string;
+    status: ToolCallApprovalStatus;
+    /** The decision asked for later calls of this tool in this thread to be approved automatically. */
+    remember?: boolean;
+    /** Opaque ref of who decided. Absent while pending and on an expiry. */
+    decidedBy?: string;
+    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    decidedVia?: string;
+    /** What the person said when declining. */
+    reason?: string;
+}
 interface ThreadDetail extends ThreadSummary {
     messages: StoredMessage[];
     activeStreamId?: string;
 }
-type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
+type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
+/** An approval request lapsed before anyone decided; the tool never ran. */
+ | 'expired';
 /**
  * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
  * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
@@ -1305,4 +1466,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-export { type HistoryPolicyContext as $, type Actor as A, type AgentApprovalRequest as B, type AgentCatalogEntry as C, type DetachedDelivery as D, type ElicitationRequest as E, type AgentHistoryWindow as F, type AgentStreamEvent as G, type HumanReply as H, type InputProcessor as I, type AskToolInput as J, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as K, type LlmStepEnvelope as L, type ModelMessage as M, DEFAULT_INTAKE_PREAMBLE as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as V, type ElicitationOption as W, type ElicitationOutcome as X, type ElicitationQuestion as Y, type ElicitationReply as Z, type ElicitationResult as _, type ToolDefinition as a, type HistorySelection as a0, type HistorySummary as a1, type IncrementalGating as a2, type InvokeWithTransientRetryOptions as a3, MAX_ASK_QUESTIONS as a4, type MessageRole as a5, OutputRejectedError as a6, type OutputVerdict as a7, ProcessorFailedError as a8, type PromptContext as a9, type QuotaView as aa, type ToolCatalogEntry as ab, type ToolConfirmation as ac, type ToolKind as ad, type ToolPresentation as ae, type ToolPresentationTone as af, type ToolResultField as ag, type ToolResultView as ah, type ToolStepCtx as ai, type ToolTransientRetryNumbers as aj, type ToolTransientRetryOptions as ak, askInputSchema as al, askToolDefinition as am, decodeStreamEvent as an, encodeStreamEvent as ao, invokeWithTransientRetry as ap, isTransientToolError as aq, normalizeElicitationReply as ar, renderElicitationAnswers as as, resolveElicitation as at, resolveToolTransientRetryNumbers as au, settleElicitation as av, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type ThreadSummary as e, type ThreadDetail as f, type ToolResult as g, type MessageAttachment as h, type ToolCallStatus as i, type ToolSpec as j, type AgentRunInput as k, type HistoryPolicy as l, type ProcessedPrompt as m, type ModelAnswer as n, type PageContext as o, type AgentDefinition as p, type AgentDelegation as q, type AiToolCtx as r, type PromptBuilder as s, type PromptContributor as t, type ToolTransientRetrySetting as u, type AgentIntake as v, type Decision as w, type ToolStepEnvelope as x, ASK_TOOL_DESCRIPTION as y, ASK_TOOL_NAME as z };
+export { type ElicitationInputType as $, type Actor as A, ASK_TOOL_DESCRIPTION as B, ASK_TOOL_NAME as C, type DetachedDelivery as D, type ElicitationRequest as E, type AgentApprovalRequest as F, type AgentApprovalSettlement as G, type HumanReply as H, type InputProcessor as I, type AgentCatalogEntry as J, type AgentHistoryWindow as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentStreamEvent as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type AskToolInput as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as V, DEFAULT_INTAKE_PREAMBLE as W, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as X, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as Y, ELICITATION_INPUT_TYPES as Z, type ElicitationInput as _, type ToolDefinition as a, type ElicitationOption as a0, type ElicitationOutcome as a1, type ElicitationQuestion as a2, type ElicitationReply as a3, type ElicitationResult as a4, type HistoryPolicyContext as a5, type HistorySelection as a6, type HistorySummary as a7, type IncrementalGating as a8, type InvokeWithTransientRetryOptions as a9, readElicitationInput as aA, readElicitationQuestions as aB, renderElicitationAnswers as aC, resolveElicitation as aD, resolveToolTransientRetryNumbers as aE, settleElicitation as aF, validateElicitationAnswer as aG, validateElicitationValue as aH, MAX_ASK_QUESTIONS as aa, type MessageRole as ab, OutputRejectedError as ac, type OutputVerdict as ad, ProcessorFailedError as ae, type PromptContext as af, type QuotaView as ag, type ToolCallApprovalStatus as ah, type ToolCatalogEntry as ai, type ToolConfirmation as aj, type ToolPresentation as ak, type ToolPresentationTone as al, type ToolResultField as am, type ToolResultView as an, type ToolStepCtx as ao, type ToolTransientRetryNumbers as ap, type ToolTransientRetryOptions as aq, askInputSchema as ar, askToolDefinition as as, decodeStreamEvent as at, encodeStreamEvent as au, invokeWithTransientRetry as av, isTransientToolError as aw, isTypedQuestion as ax, normalizeElicitationReply as ay, questionOptions as az, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type ThreadSummary as e, type ThreadDetail as f, type ToolResult as g, type MessageAttachment as h, type ToolCallStatus as i, type ToolSpec as j, type AgentRunInput as k, type ToolKind as l, type ToolCallApproval as m, type HistoryPolicy as n, type ProcessedPrompt as o, type ModelAnswer as p, type PageContext as q, type AgentDefinition as r, type AgentDelegation as s, type AiToolCtx as t, type PromptBuilder as u, type PromptContributor as v, type ToolTransientRetrySetting as w, type AgentIntake as x, type Decision as y, type ToolStepEnvelope as z };

package/dist/{tool-Q2rmGeaG.d.ts → tool-CwXibnce.d.ts}

@@ -1,5 +1,74 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * Typed answers for a question set: a question that asks for a number, a date, an email or a
+ * sentence instead of offering options to pick.
+ *
+ * Answers stay `string[]` on the wire whatever the type — the signal that carries them, the row that
+ * records them and the model that reads them back all see strings — so this module fixes ONE
+ * canonical string per type and validates against it:
+ *
+ * | `type`     | canonical value                              |
+ * |------------|----------------------------------------------|
+ * | `text`     | the text                                      |
+ * | `textarea` | the text (newlines kept)                      |
+ * | `number`   | a finite decimal, e.g. `"42"`, `"-1.5"`       |
+ * | `boolean`  | `"true"` or `"false"`                         |
+ * | `date`     | `YYYY-MM-DD`                                  |
+ * | `email`    | an address with one `@` and a dotted domain   |
+ * | `url`      | an absolute `http:`/`https:` URL              |
+ * | `select`   | one of the question's `options[].value`       |
+ *
+ * Pure and dependency-free, so the loop (which filters what it settles on), the HTTP surface (which
+ * refuses what it cannot settle) and a client (which says so before sending) all agree.
+ */
+
+declare const ELICITATION_INPUT_TYPES: readonly ["text", "textarea", "number", "boolean", "date", "email", "url", "select"];
+type ElicitationInputType = (typeof ELICITATION_INPUT_TYPES)[number];
+/** How a question takes its answer when it is not (only) a pick from `options`. */
+interface ElicitationInput {
+    type: ElicitationInputType;
+    /** Hint shown in an empty field. Advisory. */
+    placeholder?: string;
+    /** Submitting without a value is refused. Skipping the whole set is still allowed. */
+    required?: boolean;
+    /**
+     * Lower bound: the smallest number for `number`, the shortest length for `text`/`textarea`, the
+     * earliest `YYYY-MM-DD` for `date`. Ignored for the other types.
+     */
+    min?: number | string;
+    /** Upper bound, read like {@link min}. */
+    max?: number | string;
+    /** A regular expression the WHOLE value must match (`text`, `textarea`, `email`, `url`). */
+    pattern?: string;
+}
+/** The question's options, or none — `options` may be omitted on a typed question. */
+declare function questionOptions(question: ElicitationQuestion): ElicitationOption[];
+/** A question answered by a typed value rather than by picking one of its options. */
+declare function isTypedQuestion(question: ElicitationQuestion): boolean;
+/**
+ * Why `value` is not an acceptable answer to `question`, or `null` when it is. Checks ONE value;
+ * {@link validateElicitationAnswer} checks the list (required, single choice).
+ */
+declare function validateElicitationValue(question: ElicitationQuestion, value: string): string | null;
+/**
+ * Why `values` is not an acceptable answer to `question`, or `null` when it is: a `required`
+ * question left empty, more than one value for a single-choice question, or any value
+ * {@link validateElicitationValue} refuses. An empty string counts as no value.
+ */
+declare function validateElicitationAnswer(question: ElicitationQuestion, values: readonly string[]): string | null;
+/**
+ * Read an {@link ElicitationInput} from untrusted JSON, or `undefined` when it is not one. Unknown
+ * keys are dropped; a malformed optional field is dropped rather than failing the input.
+ */
+declare function readElicitationInput(raw: unknown): ElicitationInput | undefined;
+/**
+ * The questions a parked call carries, read leniently from its recorded input (`{ questions }` —
+ * what both an intake and an `ask` persist). Used where a reply is checked against the questions it
+ * answers; a question that cannot be read is left out rather than failing the rest.
+ */
+declare function readElicitationQuestions(input: unknown): ElicitationQuestion[];
+
 /**
  * Asking the USER a structured question, and waiting for the answer.
  *
@@ -27,7 +96,19 @@ interface ElicitationQuestion {
     /** Unique within its request; the key answers come back under. */
     id: string;
     prompt: string;
-    options: ElicitationOption[];
+    /** A line of help under the prompt. */
+    description?: string;
+    /**
+     * The choices. Required unless {@link input} asks for a typed value — then optional, and a UI may
+     * offer them as suggestions. An `input` of type `select` still picks from these.
+     */
+    options?: ElicitationOption[];
+    /**
+     * Ask for a typed value (a number, a date, a sentence…) instead of — or, for `select`, on top of —
+     * a pick from `options`. The answer is still a `string[]`, in the type's canonical form; see
+     * `elicitation-input.ts`.
+     */
+    input?: ElicitationInput;
     /** More than one option may be chosen. Omit → single choice. */
     multiple?: boolean;
     /**
@@ -323,6 +404,25 @@ interface AgentApprovalRequest {
     /** Why this call needs a person, in words for that person. */
     reason?: string;
 }
+/**
+ * How an approval settled — the other half of {@link AgentApprovalRequest}, under the same `id`.
+ * Metadata again: the call's own outcome still arrives as `tool-output` (approved and ran),
+ * `tool-output-error` (approved and failed) or `tool-output-denied` (rejected or expired).
+ */
+interface AgentApprovalSettlement {
+    id: string;
+    status: 'approved' | 'rejected' | 'expired';
+    /** Repeated from the request, for a call approved without one being streamed (a remembered approval). */
+    approver?: string;
+    /** Opaque ref of who decided. Absent on an expiry. */
+    decidedBy?: string;
+    /** The surface the decision came through: `'web'`, `'slack'`, `'remembered'`, … */
+    decidedVia?: string;
+    /** The approval also covers later calls of this tool in this thread. */
+    remember?: boolean;
+    /** What the person said when declining. */
+    reason?: string;
+}
 type AgentStreamEvent = {
     kind: 'step-start';
 }
@@ -414,6 +514,14 @@ type AgentStreamEvent = {
  | ({
     kind: 'approval-requested';
 } & AgentApprovalRequest)
+/**
+ * A parked action call was decided (or lapsed). Optional, like `approval-requested`: it adds WHO
+ * decided, THROUGH WHAT and whether the approval is REMEMBERED; the outcome itself rides the
+ * call's own output frame. See {@link AgentApprovalSettlement}.
+ */
+ | ({
+    kind: 'approval-settled';
+} & AgentApprovalSettlement)
 /**
  * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
  * call. See {@link AgentUiComponent}.
@@ -738,6 +846,12 @@ interface ToolResult {
      * tool's outcome on; this flag is what everything else reads.
      */
     denied?: true;
+    /**
+     * The approval request lapsed before anyone decided, so the tool never ran. Always set together
+     * with {@link denied}: an expiry IS a refusal to every consumer that only knows that much, and this
+     * flag is for the ones that tell "nobody answered" from "someone said no".
+     */
+    expired?: true;
     id: string;
     name: string;
     output: unknown;
@@ -817,6 +931,22 @@ interface Decision {
      * (the chat flow).
      */
     executedByRef?: string;
+    /**
+     * Approve later calls of the SAME tool in the SAME thread without asking again. Read only on an
+     * approval; the loop answers it through {@link import('./spi/agent-store.js').AgentStore.rememberedApprovals}.
+     */
+    remember?: boolean;
+    /**
+     * The surface the decision came through — `'web'`, `'slack'`, `'console'`, anything the caller
+     * names. Provenance only: persisted with the call, never authorized against.
+     */
+    decidedVia?: string;
+    /**
+     * Nobody decided before the request lapsed. Set by the RUNNER when the approval wait times out
+     * (see `AgentLoopHooks.awaitApproval`'s `timeoutMs`), never by a person — the HTTP surface does not
+     * accept it. Read as a denial the model is told expired.
+     */
+    expired?: true;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
 /**
@@ -1044,13 +1174,44 @@ interface StoredMessage {
      * props for each `id` — a reloaded thread replays them as `data-ui` parts.
      */
     ui?: AgentUiComponent[];
+    /**
+     * The approval record of every call on this message that was put to a person under an
+     * {@link import('./spi/approval-policy.js').ApprovalPolicy} — who had to decide, until when, and how
+     * it settled. Read off the tool-call rows by the store; absent when no call on the message asked
+     * for one, or on a store that does not record approvals.
+     */
+    approvals?: ToolCallApproval[];
     createdAt: string;
 }
+/**
+ * How one approval stands. `pending` → still parked; `approved` → someone said yes (or a remembered
+ * approval did); `rejected` → someone said no; `expired` → nobody answered before `expiresAt`.
+ */
+type ToolCallApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+/** The persisted approval metadata of one action tool call. See {@link StoredMessage.approvals}. */
+interface ToolCallApproval {
+    toolCallId: string;
+    /** Who may decide: `'requester'` (the thread's own actor) or a role name. */
+    approver: string;
+    /** ISO-8601 instant the request lapses; absent → it never does. */
+    expiresAt?: string;
+    status: ToolCallApprovalStatus;
+    /** The decision asked for later calls of this tool in this thread to be approved automatically. */
+    remember?: boolean;
+    /** Opaque ref of who decided. Absent while pending and on an expiry. */
+    decidedBy?: string;
+    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    decidedVia?: string;
+    /** What the person said when declining. */
+    reason?: string;
+}
 interface ThreadDetail extends ThreadSummary {
     messages: StoredMessage[];
     activeStreamId?: string;
 }
-type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
+type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
+/** An approval request lapsed before anyone decided; the tool never ran. */
+ | 'expired';
 /**
  * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
  * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
@@ -1305,4 +1466,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-export { type HistoryPolicyContext as $, type Actor as A, type AgentApprovalRequest as B, type AgentCatalogEntry as C, type DetachedDelivery as D, type ElicitationRequest as E, type AgentHistoryWindow as F, type AgentStreamEvent as G, type HumanReply as H, type InputProcessor as I, type AskToolInput as J, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as K, type LlmStepEnvelope as L, type ModelMessage as M, DEFAULT_INTAKE_PREAMBLE as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as V, type ElicitationOption as W, type ElicitationOutcome as X, type ElicitationQuestion as Y, type ElicitationReply as Z, type ElicitationResult as _, type ToolDefinition as a, type HistorySelection as a0, type HistorySummary as a1, type IncrementalGating as a2, type InvokeWithTransientRetryOptions as a3, MAX_ASK_QUESTIONS as a4, type MessageRole as a5, OutputRejectedError as a6, type OutputVerdict as a7, ProcessorFailedError as a8, type PromptContext as a9, type QuotaView as aa, type ToolCatalogEntry as ab, type ToolConfirmation as ac, type ToolKind as ad, type ToolPresentation as ae, type ToolPresentationTone as af, type ToolResultField as ag, type ToolResultView as ah, type ToolStepCtx as ai, type ToolTransientRetryNumbers as aj, type ToolTransientRetryOptions as ak, askInputSchema as al, askToolDefinition as am, decodeStreamEvent as an, encodeStreamEvent as ao, invokeWithTransientRetry as ap, isTransientToolError as aq, normalizeElicitationReply as ar, renderElicitationAnswers as as, resolveElicitation as at, resolveToolTransientRetryNumbers as au, settleElicitation as av, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type ThreadSummary as e, type ThreadDetail as f, type ToolResult as g, type MessageAttachment as h, type ToolCallStatus as i, type ToolSpec as j, type AgentRunInput as k, type HistoryPolicy as l, type ProcessedPrompt as m, type ModelAnswer as n, type PageContext as o, type AgentDefinition as p, type AgentDelegation as q, type AiToolCtx as r, type PromptBuilder as s, type PromptContributor as t, type ToolTransientRetrySetting as u, type AgentIntake as v, type Decision as w, type ToolStepEnvelope as x, ASK_TOOL_DESCRIPTION as y, ASK_TOOL_NAME as z };
+export { type ElicitationInputType as $, type Actor as A, ASK_TOOL_DESCRIPTION as B, ASK_TOOL_NAME as C, type DetachedDelivery as D, type ElicitationRequest as E, type AgentApprovalRequest as F, type AgentApprovalSettlement as G, type HumanReply as H, type InputProcessor as I, type AgentCatalogEntry as J, type AgentHistoryWindow as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentStreamEvent as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type AskToolInput as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as V, DEFAULT_INTAKE_PREAMBLE as W, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as X, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as Y, ELICITATION_INPUT_TYPES as Z, type ElicitationInput as _, type ToolDefinition as a, type ElicitationOption as a0, type ElicitationOutcome as a1, type ElicitationQuestion as a2, type ElicitationReply as a3, type ElicitationResult as a4, type HistoryPolicyContext as a5, type HistorySelection as a6, type HistorySummary as a7, type IncrementalGating as a8, type InvokeWithTransientRetryOptions as a9, readElicitationInput as aA, readElicitationQuestions as aB, renderElicitationAnswers as aC, resolveElicitation as aD, resolveToolTransientRetryNumbers as aE, settleElicitation as aF, validateElicitationAnswer as aG, validateElicitationValue as aH, MAX_ASK_QUESTIONS as aa, type MessageRole as ab, OutputRejectedError as ac, type OutputVerdict as ad, ProcessorFailedError as ae, type PromptContext as af, type QuotaView as ag, type ToolCallApprovalStatus as ah, type ToolCatalogEntry as ai, type ToolConfirmation as aj, type ToolPresentation as ak, type ToolPresentationTone as al, type ToolResultField as am, type ToolResultView as an, type ToolStepCtx as ao, type ToolTransientRetryNumbers as ap, type ToolTransientRetryOptions as aq, askInputSchema as ar, askToolDefinition as as, decodeStreamEvent as at, encodeStreamEvent as au, invokeWithTransientRetry as av, isTransientToolError as aw, isTypedQuestion as ax, normalizeElicitationReply as ay, questionOptions as az, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type ThreadSummary as e, type ThreadDetail as f, type ToolResult as g, type MessageAttachment as h, type ToolCallStatus as i, type ToolSpec as j, type AgentRunInput as k, type ToolKind as l, type ToolCallApproval as m, type HistoryPolicy as n, type ProcessedPrompt as o, type ModelAnswer as p, type PageContext as q, type AgentDefinition as r, type AgentDelegation as s, type AiToolCtx as t, type PromptBuilder as u, type PromptContributor as v, type ToolTransientRetrySetting as w, type AgentIntake as x, type Decision as y, type ToolStepEnvelope as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent-core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",