@dudousxd/nestjs-agent-core 0.21.0 → 0.22.0

package/dist/{tool-CwXibnce.d.cts → tool-BQqFt06V.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[];
     /**
@@ -1259,6 +1276,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 +1456,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 +1510,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 ElicitationInputType as $, type Actor as A, type ToolStepEnvelope as B, ASK_TOOL_DESCRIPTION as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_NAME as F, type AgentApprovalRequest as G, type HumanReply as H, type InputProcessor as I, type AgentApprovalSettlement as J, type AgentCatalogEntry as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentHistoryWindow 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 AiToolCtx as e, type AgentStreamEvent as f, type ThreadSummary as g, type ThreadDetail as h, type ToolResult as i, type MessageAttachment as j, type ToolCallStatus as k, type ToolSpec as l, type AgentRunInput as m, type ToolKind as n, type ToolCallApproval as o, type HistoryPolicy as p, type ProcessedPrompt as q, type ModelAnswer as r, type PageContext as s, type AgentDefinition as t, type AgentDelegation as u, type PromptBuilder as v, type PromptContributor as w, type ToolTransientRetrySetting as x, type AgentIntake as y, type Decision as z };

package/dist/{tool-CwXibnce.d.ts → tool-BQqFt06V.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[];
     /**
@@ -1259,6 +1276,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 +1456,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 +1510,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 ElicitationInputType as $, type Actor as A, type ToolStepEnvelope as B, ASK_TOOL_DESCRIPTION as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_NAME as F, type AgentApprovalRequest as G, type HumanReply as H, type InputProcessor as I, type AgentApprovalSettlement as J, type AgentCatalogEntry as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentHistoryWindow 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 AiToolCtx as e, type AgentStreamEvent as f, type ThreadSummary as g, type ThreadDetail as h, type ToolResult as i, type MessageAttachment as j, type ToolCallStatus as k, type ToolSpec as l, type AgentRunInput as m, type ToolKind as n, type ToolCallApproval as o, type HistoryPolicy as p, type ProcessedPrompt as q, type ModelAnswer as r, type PageContext as s, type AgentDefinition as t, type AgentDelegation as u, type PromptBuilder as v, type PromptContributor as w, type ToolTransientRetrySetting as x, type AgentIntake as y, type Decision as z };

package/package.json

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