@dudousxd/nestjs-agent-core 0.21.0 → 0.23.0

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

@@ -385,6 +385,12 @@ interface AgentUiComponent {
     props: Record<string, unknown>;
     /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
     version?: number;
+    /**
+     * The tool call that pushed the component (`ctx.emitUi`), when one did. Lets a client place it
+     * with that call — a reloaded message puts it right after the call's tool part, where the live
+     * stream showed it. Absent for a component pushed outside a tool.
+     */
+    toolCallId?: string;
 }
 /**
  * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
@@ -796,6 +802,17 @@ interface ToolSpec {
      * reads the branch back rather than re-deciding it against a registry that may have changed.
      */
     detached?: boolean;
+    /**
+     * The turn ends once a call to this tool SUCCEEDS: the loop finishes the step (results persisted
+     * and streamed) and makes no further model call. For a tool whose effect IS the answer — pushing
+     * a composed UI, handing off — where a model call narrating it would only repeat it. A failed or
+     * refused call does not end the turn, so the model can correct it.
+     *
+     * Settled into the call's `persist:toolcall` checkpoint (like `targetAgent`), so a replay takes
+     * the same branch. Ending early skips what a final step would do: follow-ups and the
+     * `outputSchema` formatting pass.
+     */
+    terminal?: boolean;
     /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
     roles?: string[];
     /**
@@ -1181,8 +1198,22 @@ interface StoredMessage {
      * for one, or on a store that does not record approvals.
      */
     approvals?: ToolCallApproval[];
+    /**
+     * The thread owner's rating of this message (`POST <base>/messages/:id/feedback`). Absent when
+     * nobody rated it, or on a store that does not record feedback.
+     */
+    feedback?: MessageFeedback;
     createdAt: string;
 }
+/** A thumbs-up/down on one message, with an optional free-text comment. */
+type MessageFeedbackValue = 'up' | 'down';
+/** What {@link StoredMessage.feedback} holds. Not copied when a thread is forked. */
+interface MessageFeedback {
+    value: MessageFeedbackValue;
+    comment?: string;
+    /** ISO-8601 instant the rating was last set. */
+    updatedAt: 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`.
@@ -1259,6 +1290,12 @@ interface ToolStepEnvelope {
      * `AgentRunSteps.tool`) instead of trying to serialize a function.
      */
     transientRetry: ToolTransientRetryNumbers | false;
+    /**
+     * The dispatching loop reads the components the tool pushed (`ctx.emitUi`) off the step's result.
+     * A handler that sees it returns {@link wrapToolStepOutput}'s envelope when the tool pushed any —
+     * and ONLY then, so a loop that predates this (and never sets it) always gets the bare output.
+     */
+    collectUi?: boolean;
 }
 
 /**
@@ -1433,6 +1470,27 @@ interface AiToolCtx {
     pageContext?: PageContext;
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;
+    /**
+     * Push a component into the assistant message: streamed live as a `ui` frame and persisted on
+     * the message, so a reload shows it where the live stream did. Resolves to the component's id.
+     *
+     * `id` defaults to `<toolCallId>:ui:<n>` (the n-th push without an `id` in this invocation), so a retried or
+     * re-executed call REPLACES what it pushed before instead of adding a second copy; pass your own
+     * `id` to update one component across pushes (streaming rows into a table). `props` must be
+     * JSON; it is snapshotted when pushed.
+     *
+     * Replay-safe under the durable runner: the pushed components ride the tool step's journaled
+     * result, so a replay neither streams nor persists them again. Present whenever the agent loop
+     * runs the tool (inline, durable, dispatched); absent on surfaces with no conversation to push
+     * into (the MCP server), hence optional — call it as `ctx.emitUi?.(…)` in a tool that is also
+     * served there.
+     */
+    emitUi?(component: string, props: Record<string, unknown>, options?: {
+        id?: string;
+        version?: number;
+    }): Promise<{
+        id: string;
+    }>;
 }
 /** A tool implementation. `I` is the parsed (Zod-validated) input. */
 interface ToolHandler<I = unknown> {
@@ -1466,4 +1524,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-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 };
+export { type ElicitationInput as $, type Actor as A, type Decision as B, type ToolStepEnvelope as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_DESCRIPTION as F, ASK_TOOL_NAME as G, type HumanReply as H, type InputProcessor as I, type AgentApprovalRequest as J, type AgentApprovalSettlement as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentCatalogEntry as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type AgentHistoryWindow as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, type AskToolInput as V, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as W, DEFAULT_INTAKE_PREAMBLE as X, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as Y, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as Z, ELICITATION_INPUT_TYPES as _, type ToolDefinition as a, type ElicitationInputType as a0, type ElicitationOption as a1, type ElicitationOutcome as a2, type ElicitationQuestion as a3, type ElicitationReply as a4, type ElicitationResult as a5, type HistoryPolicyContext as a6, type HistorySelection as a7, type HistorySummary as a8, type IncrementalGating as a9, normalizeElicitationReply as aA, questionOptions as aB, readElicitationInput as aC, readElicitationQuestions as aD, renderElicitationAnswers as aE, resolveElicitation as aF, resolveToolTransientRetryNumbers as aG, settleElicitation as aH, validateElicitationAnswer as aI, validateElicitationValue as aJ, type InvokeWithTransientRetryOptions as aa, MAX_ASK_QUESTIONS as ab, type MessageFeedbackValue as ac, type MessageRole as ad, OutputRejectedError as ae, type OutputVerdict as af, ProcessorFailedError as ag, type PromptContext as ah, type QuotaView as ai, type ToolCallApprovalStatus as aj, type ToolCatalogEntry as ak, type ToolConfirmation as al, type ToolPresentation as am, type ToolPresentationTone as an, type ToolResultField as ao, type ToolResultView as ap, type ToolStepCtx as aq, type ToolTransientRetryNumbers as ar, type ToolTransientRetryOptions as as, askInputSchema as at, askToolDefinition as au, decodeStreamEvent as av, encodeStreamEvent as aw, invokeWithTransientRetry as ax, isTransientToolError as ay, isTypedQuestion as az, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type AiToolCtx as e, type AgentStreamEvent as f, type ThreadSummary as g, type ThreadDetail as h, type ToolResult as i, type MessageAttachment as j, type MessageFeedback as k, type ToolCallStatus as l, type ToolSpec as m, type AgentRunInput as n, type ToolKind as o, type ToolCallApproval as p, type HistoryPolicy as q, type ProcessedPrompt as r, type ModelAnswer as s, type PageContext as t, type AgentDefinition as u, type AgentDelegation as v, type PromptBuilder as w, type PromptContributor as x, type ToolTransientRetrySetting as y, type AgentIntake as z };

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

@@ -385,6 +385,12 @@ interface AgentUiComponent {
     props: Record<string, unknown>;
     /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
     version?: number;
+    /**
+     * The tool call that pushed the component (`ctx.emitUi`), when one did. Lets a client place it
+     * with that call — a reloaded message puts it right after the call's tool part, where the live
+     * stream showed it. Absent for a component pushed outside a tool.
+     */
+    toolCallId?: string;
 }
 /**
  * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
@@ -796,6 +802,17 @@ interface ToolSpec {
      * reads the branch back rather than re-deciding it against a registry that may have changed.
      */
     detached?: boolean;
+    /**
+     * The turn ends once a call to this tool SUCCEEDS: the loop finishes the step (results persisted
+     * and streamed) and makes no further model call. For a tool whose effect IS the answer — pushing
+     * a composed UI, handing off — where a model call narrating it would only repeat it. A failed or
+     * refused call does not end the turn, so the model can correct it.
+     *
+     * Settled into the call's `persist:toolcall` checkpoint (like `targetAgent`), so a replay takes
+     * the same branch. Ending early skips what a final step would do: follow-ups and the
+     * `outputSchema` formatting pass.
+     */
+    terminal?: boolean;
     /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
     roles?: string[];
     /**
@@ -1181,8 +1198,22 @@ interface StoredMessage {
      * for one, or on a store that does not record approvals.
      */
     approvals?: ToolCallApproval[];
+    /**
+     * The thread owner's rating of this message (`POST <base>/messages/:id/feedback`). Absent when
+     * nobody rated it, or on a store that does not record feedback.
+     */
+    feedback?: MessageFeedback;
     createdAt: string;
 }
+/** A thumbs-up/down on one message, with an optional free-text comment. */
+type MessageFeedbackValue = 'up' | 'down';
+/** What {@link StoredMessage.feedback} holds. Not copied when a thread is forked. */
+interface MessageFeedback {
+    value: MessageFeedbackValue;
+    comment?: string;
+    /** ISO-8601 instant the rating was last set. */
+    updatedAt: 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`.
@@ -1259,6 +1290,12 @@ interface ToolStepEnvelope {
      * `AgentRunSteps.tool`) instead of trying to serialize a function.
      */
     transientRetry: ToolTransientRetryNumbers | false;
+    /**
+     * The dispatching loop reads the components the tool pushed (`ctx.emitUi`) off the step's result.
+     * A handler that sees it returns {@link wrapToolStepOutput}'s envelope when the tool pushed any —
+     * and ONLY then, so a loop that predates this (and never sets it) always gets the bare output.
+     */
+    collectUi?: boolean;
 }
 
 /**
@@ -1433,6 +1470,27 @@ interface AiToolCtx {
     pageContext?: PageContext;
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;
+    /**
+     * Push a component into the assistant message: streamed live as a `ui` frame and persisted on
+     * the message, so a reload shows it where the live stream did. Resolves to the component's id.
+     *
+     * `id` defaults to `<toolCallId>:ui:<n>` (the n-th push without an `id` in this invocation), so a retried or
+     * re-executed call REPLACES what it pushed before instead of adding a second copy; pass your own
+     * `id` to update one component across pushes (streaming rows into a table). `props` must be
+     * JSON; it is snapshotted when pushed.
+     *
+     * Replay-safe under the durable runner: the pushed components ride the tool step's journaled
+     * result, so a replay neither streams nor persists them again. Present whenever the agent loop
+     * runs the tool (inline, durable, dispatched); absent on surfaces with no conversation to push
+     * into (the MCP server), hence optional — call it as `ctx.emitUi?.(…)` in a tool that is also
+     * served there.
+     */
+    emitUi?(component: string, props: Record<string, unknown>, options?: {
+        id?: string;
+        version?: number;
+    }): Promise<{
+        id: string;
+    }>;
 }
 /** A tool implementation. `I` is the parsed (Zod-validated) input. */
 interface ToolHandler<I = unknown> {
@@ -1466,4 +1524,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-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 };
+export { type ElicitationInput as $, type Actor as A, type Decision as B, type ToolStepEnvelope as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_DESCRIPTION as F, ASK_TOOL_NAME as G, type HumanReply as H, type InputProcessor as I, type AgentApprovalRequest as J, type AgentApprovalSettlement as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentCatalogEntry as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type AgentHistoryWindow as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, type AskToolInput as V, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as W, DEFAULT_INTAKE_PREAMBLE as X, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as Y, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as Z, ELICITATION_INPUT_TYPES as _, type ToolDefinition as a, type ElicitationInputType as a0, type ElicitationOption as a1, type ElicitationOutcome as a2, type ElicitationQuestion as a3, type ElicitationReply as a4, type ElicitationResult as a5, type HistoryPolicyContext as a6, type HistorySelection as a7, type HistorySummary as a8, type IncrementalGating as a9, normalizeElicitationReply as aA, questionOptions as aB, readElicitationInput as aC, readElicitationQuestions as aD, renderElicitationAnswers as aE, resolveElicitation as aF, resolveToolTransientRetryNumbers as aG, settleElicitation as aH, validateElicitationAnswer as aI, validateElicitationValue as aJ, type InvokeWithTransientRetryOptions as aa, MAX_ASK_QUESTIONS as ab, type MessageFeedbackValue as ac, type MessageRole as ad, OutputRejectedError as ae, type OutputVerdict as af, ProcessorFailedError as ag, type PromptContext as ah, type QuotaView as ai, type ToolCallApprovalStatus as aj, type ToolCatalogEntry as ak, type ToolConfirmation as al, type ToolPresentation as am, type ToolPresentationTone as an, type ToolResultField as ao, type ToolResultView as ap, type ToolStepCtx as aq, type ToolTransientRetryNumbers as ar, type ToolTransientRetryOptions as as, askInputSchema as at, askToolDefinition as au, decodeStreamEvent as av, encodeStreamEvent as aw, invokeWithTransientRetry as ax, isTransientToolError as ay, isTypedQuestion as az, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type AiToolCtx as e, type AgentStreamEvent as f, type ThreadSummary as g, type ThreadDetail as h, type ToolResult as i, type MessageAttachment as j, type MessageFeedback as k, type ToolCallStatus as l, type ToolSpec as m, type AgentRunInput as n, type ToolKind as o, type ToolCallApproval as p, type HistoryPolicy as q, type ProcessedPrompt as r, type ModelAnswer as s, type PageContext as t, type AgentDefinition as u, type AgentDelegation as v, type PromptBuilder as w, type PromptContributor as x, type ToolTransientRetrySetting as y, type AgentIntake as z };

package/package.json

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