@dudousxd/nestjs-agent-core 0.19.0 → 0.20.0

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

@@ -323,6 +323,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 +433,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 +765,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 +850,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 +1093,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 +1385,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 ElicitationQuestion 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, type ElicitationOption as Z, type ElicitationOutcome as _, type ToolDefinition as a, type ElicitationReply as a0, type ElicitationResult as a1, type HistoryPolicyContext as a2, type HistorySelection as a3, type HistorySummary as a4, type IncrementalGating as a5, type InvokeWithTransientRetryOptions as a6, MAX_ASK_QUESTIONS as a7, type MessageRole as a8, OutputRejectedError as a9, type OutputVerdict as aa, ProcessorFailedError as ab, type PromptContext as ac, type QuotaView as ad, type ToolCallApprovalStatus as ae, type ToolCatalogEntry as af, type ToolConfirmation as ag, type ToolPresentation as ah, type ToolPresentationTone as ai, type ToolResultField as aj, type ToolResultView as ak, type ToolStepCtx as al, type ToolTransientRetryNumbers as am, type ToolTransientRetryOptions as an, askInputSchema as ao, askToolDefinition as ap, decodeStreamEvent as aq, encodeStreamEvent as ar, invokeWithTransientRetry as as, isTransientToolError as at, normalizeElicitationReply as au, renderElicitationAnswers as av, resolveElicitation as aw, resolveToolTransientRetryNumbers as ax, settleElicitation as ay, 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-B2Dq9ZwF.d.ts}

@@ -323,6 +323,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 +433,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 +765,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 +850,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 +1093,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 +1385,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 ElicitationQuestion 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, type ElicitationOption as Z, type ElicitationOutcome as _, type ToolDefinition as a, type ElicitationReply as a0, type ElicitationResult as a1, type HistoryPolicyContext as a2, type HistorySelection as a3, type HistorySummary as a4, type IncrementalGating as a5, type InvokeWithTransientRetryOptions as a6, MAX_ASK_QUESTIONS as a7, type MessageRole as a8, OutputRejectedError as a9, type OutputVerdict as aa, ProcessorFailedError as ab, type PromptContext as ac, type QuotaView as ad, type ToolCallApprovalStatus as ae, type ToolCatalogEntry as af, type ToolConfirmation as ag, type ToolPresentation as ah, type ToolPresentationTone as ai, type ToolResultField as aj, type ToolResultView as ak, type ToolStepCtx as al, type ToolTransientRetryNumbers as am, type ToolTransientRetryOptions as an, askInputSchema as ao, askToolDefinition as ap, decodeStreamEvent as aq, encodeStreamEvent as ar, invokeWithTransientRetry as as, isTransientToolError as at, normalizeElicitationReply as au, renderElicitationAnswers as av, resolveElicitation as aw, resolveToolTransientRetryNumbers as ax, settleElicitation as ay, 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.20.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",