@dudousxd/nestjs-agent-core 0.21.0 → 0.22.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, A as Actor, e as ThreadSummary, f as ThreadDetail, S as StoredMessage, g as ToolResult, h as MessageAttachment, i as ToolCallStatus, U as UsagePurpose, j as ToolSpec, Q as QuotaState, k as AgentRunInput, H as HumanReply, l as ToolKind, m as ToolCallApproval, T as ToolHandler, n as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, o as ProcessedPrompt, p as ModelAnswer, q as PageContext, r as AgentDefinition, s as AgentDelegation, D as DetachedDelivery, t as AiToolCtx, u as PromptBuilder, v as PromptContributor, w as ToolTransientRetrySetting, x as AgentIntake, y as Decision, E as ElicitationRequest, L as LlmStepEnvelope, z as ToolStepEnvelope } from './tool-CwXibnce.cjs';
-export { B as ASK_TOOL_DESCRIPTION, C as ASK_TOOL_NAME, F as AgentApprovalRequest, G as AgentApprovalSettlement, J as AgentCatalogEntry, K as AgentHistoryWindow, N as AgentStreamEvent, R as AskToolInput, V as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, W as DEFAULT_INTAKE_PREAMBLE, X as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Y as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, Z as ELICITATION_INPUT_TYPES, _ as ElicitationInput, $ as ElicitationInputType, a0 as ElicitationOption, a1 as ElicitationOutcome, a2 as ElicitationQuestion, a3 as ElicitationReply, a4 as ElicitationResult, a5 as HistoryPolicyContext, a6 as HistorySelection, a7 as HistorySummary, a8 as IncrementalGating, a9 as InvokeWithTransientRetryOptions, aa as MAX_ASK_QUESTIONS, ab as MessageRole, ac as OutputRejectedError, ad as OutputVerdict, ae as ProcessorFailedError, af as PromptContext, ag as QuotaView, ah as ToolCallApprovalStatus, ai as ToolCatalogEntry, aj as ToolConfirmation, ak as ToolPresentation, al as ToolPresentationTone, am as ToolResultField, an as ToolResultView, ao as ToolStepCtx, ap as ToolTransientRetryNumbers, aq as ToolTransientRetryOptions, ar as askInputSchema, as as askToolDefinition, at as decodeStreamEvent, au as encodeStreamEvent, av as invokeWithTransientRetry, aw as isTransientToolError, ax as isTypedQuestion, ay as normalizeElicitationReply, az as questionOptions, aA as readElicitationInput, aB as readElicitationQuestions, aC as renderElicitationAnswers, aD as resolveElicitation, aE as resolveToolTransientRetryNumbers, aF as settleElicitation, aG as validateElicitationAnswer, aH as validateElicitationValue } from './tool-CwXibnce.cjs';
+import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, e as AiToolCtx, f as AgentStreamEvent, A as Actor, g as ThreadSummary, h as ThreadDetail, S as StoredMessage, i as ToolResult, j as MessageAttachment, k as ToolCallStatus, U as UsagePurpose, l as ToolSpec, Q as QuotaState, m as AgentRunInput, H as HumanReply, n as ToolKind, o as ToolCallApproval, T as ToolHandler, p as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, q as ProcessedPrompt, r as ModelAnswer, s as PageContext, t as AgentDefinition, u as AgentDelegation, D as DetachedDelivery, v as PromptBuilder, w as PromptContributor, x as ToolTransientRetrySetting, y as AgentIntake, z as Decision, E as ElicitationRequest, L as LlmStepEnvelope, B as ToolStepEnvelope } from './tool-BQqFt06V.cjs';
+export { C as ASK_TOOL_DESCRIPTION, F as ASK_TOOL_NAME, G as AgentApprovalRequest, J as AgentApprovalSettlement, K as AgentCatalogEntry, N as AgentHistoryWindow, R as AskToolInput, V as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, W as DEFAULT_INTAKE_PREAMBLE, X as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Y as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, Z as ELICITATION_INPUT_TYPES, _ as ElicitationInput, $ as ElicitationInputType, a0 as ElicitationOption, a1 as ElicitationOutcome, a2 as ElicitationQuestion, a3 as ElicitationReply, a4 as ElicitationResult, a5 as HistoryPolicyContext, a6 as HistorySelection, a7 as HistorySummary, a8 as IncrementalGating, a9 as InvokeWithTransientRetryOptions, aa as MAX_ASK_QUESTIONS, ab as MessageRole, ac as OutputRejectedError, ad as OutputVerdict, ae as ProcessorFailedError, af as PromptContext, ag as QuotaView, ah as ToolCallApprovalStatus, ai as ToolCatalogEntry, aj as ToolConfirmation, ak as ToolPresentation, al as ToolPresentationTone, am as ToolResultField, an as ToolResultView, ao as ToolStepCtx, ap as ToolTransientRetryNumbers, aq as ToolTransientRetryOptions, ar as askInputSchema, as as askToolDefinition, at as decodeStreamEvent, au as encodeStreamEvent, av as invokeWithTransientRetry, aw as isTransientToolError, ax as isTypedQuestion, ay as normalizeElicitationReply, az as questionOptions, aA as readElicitationInput, aB as readElicitationQuestions, aC as renderElicitationAnswers, aD as resolveElicitation, aE as resolveToolTransientRetryNumbers, aF as settleElicitation, aG as validateElicitationAnswer, aH as validateElicitationValue } from './tool-BQqFt06V.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
@@ -239,6 +239,33 @@ declare function observeTurnFrames(writer: SinkWriter, now?: () => number): Obse
 /** Fill what a provider did not report from what its frames showed. A provider's own value wins. */
 declare function withTurnFrames<T extends ModelTurnResult>(result: T, frames: TurnFrameSummary): T;
 
+/** The tool step's journaled result: the bare output, or the output plus the components it pushed. */
+declare function wrapToolStepOutput(output: unknown, ui: readonly AgentUiComponent[]): unknown;
+/** Read a tool step's result back — either shape. */
+declare function unwrapToolStepOutput(raw: unknown): {
+    output: unknown;
+    ui: AgentUiComponent[];
+};
+type EmitUi = NonNullable<AiToolCtx['emitUi']>;
+/** Collects what one tool invocation pushes, streaming each push as it happens. */
+interface UiCollector {
+    emit: EmitUi;
+    /** Everything pushed so far: first-seen order, last props per id. */
+    components(): AgentUiComponent[];
+    /**
+     * A new ATTEMPT of the same call (a transient retry): numbering restarts, so the retry's pushes
+     * reuse — and replace — the ids the failed attempt used.
+     */
+    restart(): void;
+}
+/**
+ * `write` streams one frame; omit it where there is no live stream (the component is still
+ * collected and persisted).
+ */
+declare function createUiCollector(toolCallId: string, write?: (event: AgentStreamEvent) => void | Promise<void>): UiCollector;
+/** Merge component lists: first-seen order, the last props for each id. */
+declare function mergeUi(...lists: readonly (readonly AgentUiComponent[] | undefined)[]): AgentUiComponent[];
+
 interface CreateThreadInput {
     actor: Actor;
     transient?: boolean;
@@ -473,6 +500,17 @@ interface AgentStore {
      * fail to compile instead.
      */
     setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
+    /**
+     * Replace the components persisted on an already-appended message (see {@link StoredMessage.ui}).
+     * The loop calls it once per step, after the step's tools ran, with every component the step
+     * showed — the model turn's own `ui` frames first, then what its tools pushed through
+     * `ctx.emitUi`, in call order, deduplicated by `id`. A full replacement, never an append, so a
+     * repeated call writes the same value.
+     *
+     * OPTIONAL: a store without it still streams tool-pushed components live; a reload then shows
+     * only the ones the model turn itself produced.
+     */
+    setMessageUi?(messageId: string, ui: AgentUiComponent[]): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
@@ -3293,4 +3331,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, A as Actor, e as ThreadSummary, f as ThreadDetail, S as StoredMessage, g as ToolResult, h as MessageAttachment, i as ToolCallStatus, U as UsagePurpose, j as ToolSpec, Q as QuotaState, k as AgentRunInput, H as HumanReply, l as ToolKind, m as ToolCallApproval, T as ToolHandler, n as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, o as ProcessedPrompt, p as ModelAnswer, q as PageContext, r as AgentDefinition, s as AgentDelegation, D as DetachedDelivery, t as AiToolCtx, u as PromptBuilder, v as PromptContributor, w as ToolTransientRetrySetting, x as AgentIntake, y as Decision, E as ElicitationRequest, L as LlmStepEnvelope, z as ToolStepEnvelope } from './tool-CwXibnce.js';
-export { B as ASK_TOOL_DESCRIPTION, C as ASK_TOOL_NAME, F as AgentApprovalRequest, G as AgentApprovalSettlement, J as AgentCatalogEntry, K as AgentHistoryWindow, N as AgentStreamEvent, R as AskToolInput, V as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, W as DEFAULT_INTAKE_PREAMBLE, X as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Y as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, Z as ELICITATION_INPUT_TYPES, _ as ElicitationInput, $ as ElicitationInputType, a0 as ElicitationOption, a1 as ElicitationOutcome, a2 as ElicitationQuestion, a3 as ElicitationReply, a4 as ElicitationResult, a5 as HistoryPolicyContext, a6 as HistorySelection, a7 as HistorySummary, a8 as IncrementalGating, a9 as InvokeWithTransientRetryOptions, aa as MAX_ASK_QUESTIONS, ab as MessageRole, ac as OutputRejectedError, ad as OutputVerdict, ae as ProcessorFailedError, af as PromptContext, ag as QuotaView, ah as ToolCallApprovalStatus, ai as ToolCatalogEntry, aj as ToolConfirmation, ak as ToolPresentation, al as ToolPresentationTone, am as ToolResultField, an as ToolResultView, ao as ToolStepCtx, ap as ToolTransientRetryNumbers, aq as ToolTransientRetryOptions, ar as askInputSchema, as as askToolDefinition, at as decodeStreamEvent, au as encodeStreamEvent, av as invokeWithTransientRetry, aw as isTransientToolError, ax as isTypedQuestion, ay as normalizeElicitationReply, az as questionOptions, aA as readElicitationInput, aB as readElicitationQuestions, aC as renderElicitationAnswers, aD as resolveElicitation, aE as resolveToolTransientRetryNumbers, aF as settleElicitation, aG as validateElicitationAnswer, aH as validateElicitationValue } from './tool-CwXibnce.js';
+import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, e as AiToolCtx, f as AgentStreamEvent, A as Actor, g as ThreadSummary, h as ThreadDetail, S as StoredMessage, i as ToolResult, j as MessageAttachment, k as ToolCallStatus, U as UsagePurpose, l as ToolSpec, Q as QuotaState, m as AgentRunInput, H as HumanReply, n as ToolKind, o as ToolCallApproval, T as ToolHandler, p as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, q as ProcessedPrompt, r as ModelAnswer, s as PageContext, t as AgentDefinition, u as AgentDelegation, D as DetachedDelivery, v as PromptBuilder, w as PromptContributor, x as ToolTransientRetrySetting, y as AgentIntake, z as Decision, E as ElicitationRequest, L as LlmStepEnvelope, B as ToolStepEnvelope } from './tool-BQqFt06V.js';
+export { C as ASK_TOOL_DESCRIPTION, F as ASK_TOOL_NAME, G as AgentApprovalRequest, J as AgentApprovalSettlement, K as AgentCatalogEntry, N as AgentHistoryWindow, R as AskToolInput, V as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, W as DEFAULT_INTAKE_PREAMBLE, X as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Y as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, Z as ELICITATION_INPUT_TYPES, _ as ElicitationInput, $ as ElicitationInputType, a0 as ElicitationOption, a1 as ElicitationOutcome, a2 as ElicitationQuestion, a3 as ElicitationReply, a4 as ElicitationResult, a5 as HistoryPolicyContext, a6 as HistorySelection, a7 as HistorySummary, a8 as IncrementalGating, a9 as InvokeWithTransientRetryOptions, aa as MAX_ASK_QUESTIONS, ab as MessageRole, ac as OutputRejectedError, ad as OutputVerdict, ae as ProcessorFailedError, af as PromptContext, ag as QuotaView, ah as ToolCallApprovalStatus, ai as ToolCatalogEntry, aj as ToolConfirmation, ak as ToolPresentation, al as ToolPresentationTone, am as ToolResultField, an as ToolResultView, ao as ToolStepCtx, ap as ToolTransientRetryNumbers, aq as ToolTransientRetryOptions, ar as askInputSchema, as as askToolDefinition, at as decodeStreamEvent, au as encodeStreamEvent, av as invokeWithTransientRetry, aw as isTransientToolError, ax as isTypedQuestion, ay as normalizeElicitationReply, az as questionOptions, aA as readElicitationInput, aB as readElicitationQuestions, aC as renderElicitationAnswers, aD as resolveElicitation, aE as resolveToolTransientRetryNumbers, aF as settleElicitation, aG as validateElicitationAnswer, aH as validateElicitationValue } from './tool-BQqFt06V.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
@@ -239,6 +239,33 @@ declare function observeTurnFrames(writer: SinkWriter, now?: () => number): Obse
 /** Fill what a provider did not report from what its frames showed. A provider's own value wins. */
 declare function withTurnFrames<T extends ModelTurnResult>(result: T, frames: TurnFrameSummary): T;
 
+/** The tool step's journaled result: the bare output, or the output plus the components it pushed. */
+declare function wrapToolStepOutput(output: unknown, ui: readonly AgentUiComponent[]): unknown;
+/** Read a tool step's result back — either shape. */
+declare function unwrapToolStepOutput(raw: unknown): {
+    output: unknown;
+    ui: AgentUiComponent[];
+};
+type EmitUi = NonNullable<AiToolCtx['emitUi']>;
+/** Collects what one tool invocation pushes, streaming each push as it happens. */
+interface UiCollector {
+    emit: EmitUi;
+    /** Everything pushed so far: first-seen order, last props per id. */
+    components(): AgentUiComponent[];
+    /**
+     * A new ATTEMPT of the same call (a transient retry): numbering restarts, so the retry's pushes
+     * reuse — and replace — the ids the failed attempt used.
+     */
+    restart(): void;
+}
+/**
+ * `write` streams one frame; omit it where there is no live stream (the component is still
+ * collected and persisted).
+ */
+declare function createUiCollector(toolCallId: string, write?: (event: AgentStreamEvent) => void | Promise<void>): UiCollector;
+/** Merge component lists: first-seen order, the last props for each id. */
+declare function mergeUi(...lists: readonly (readonly AgentUiComponent[] | undefined)[]): AgentUiComponent[];
+
 interface CreateThreadInput {
     actor: Actor;
     transient?: boolean;
@@ -473,6 +500,17 @@ interface AgentStore {
      * fail to compile instead.
      */
     setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
+    /**
+     * Replace the components persisted on an already-appended message (see {@link StoredMessage.ui}).
+     * The loop calls it once per step, after the step's tools ran, with every component the step
+     * showed — the model turn's own `ui` frames first, then what its tools pushed through
+     * `ctx.emitUi`, in call order, deduplicated by `id`. A full replacement, never an append, so a
+     * repeated call writes the same value.
+     *
+     * OPTIONAL: a store without it still streams tool-pushed components live; a reload then shows
+     * only the ones the model turn itself produced.
+     */
+    setMessageUi?(messageId: string, ui: AgentUiComponent[]): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
@@ -3293,4 +3331,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };

package/dist/index.js

@@ -157,6 +157,95 @@ function withTurnFrames(result, frames) {
 }
 __name(withTurnFrames, "withTurnFrames");
 
+// src/tool-ui.ts
+var TOOL_STEP_UI = "@@nestjs-agent/tool-step-ui";
+function wrapToolStepOutput(output, ui) {
+  if (ui.length === 0) {
+    return output;
+  }
+  const wrapped = {
+    [TOOL_STEP_UI]: 1,
+    output,
+    ui: [
+      ...ui
+    ]
+  };
+  return wrapped;
+}
+__name(wrapToolStepOutput, "wrapToolStepOutput");
+function unwrapToolStepOutput(raw) {
+  if (typeof raw === "object" && raw !== null && raw[TOOL_STEP_UI] === 1) {
+    const wrapped = raw;
+    return {
+      output: wrapped.output,
+      ui: Array.isArray(wrapped.ui) ? wrapped.ui : []
+    };
+  }
+  return {
+    output: raw,
+    ui: []
+  };
+}
+__name(unwrapToolStepOutput, "unwrapToolStepOutput");
+function createUiCollector(toolCallId, write) {
+  const pushed = /* @__PURE__ */ new Map();
+  let next = 0;
+  const emit2 = /* @__PURE__ */ __name(async (component, props, options = {}) => {
+    if (typeof component !== "string" || component.length === 0) {
+      throw new Error("emitUi: component must be a non-empty string");
+    }
+    if (typeof props !== "object" || props === null || Array.isArray(props)) {
+      throw new Error("emitUi: props must be a JSON object");
+    }
+    let id = options.id;
+    if (id === void 0) {
+      id = `${toolCallId}:ui:${next}`;
+      next += 1;
+    }
+    const entry = {
+      id,
+      component,
+      // Snapshot: the frame and the persisted value are what the tool pushed at THIS moment, not
+      // whatever the object it handed over looks like when the step settles.
+      props: JSON.parse(JSON.stringify(props)),
+      ...options.version !== void 0 ? {
+        version: options.version
+      } : {},
+      toolCallId
+    };
+    pushed.set(id, entry);
+    await write?.({
+      kind: "ui",
+      ...entry
+    });
+    return {
+      id
+    };
+  }, "emit");
+  return {
+    emit: emit2,
+    components: /* @__PURE__ */ __name(() => [
+      ...pushed.values()
+    ], "components"),
+    restart: /* @__PURE__ */ __name(() => {
+      next = 0;
+    }, "restart")
+  };
+}
+__name(createUiCollector, "createUiCollector");
+function mergeUi(...lists) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const component of list ?? []) {
+      merged.set(component.id, component);
+    }
+  }
+  return [
+    ...merged.values()
+  ];
+}
+__name(mergeUi, "mergeUi");
+
 // src/spi/pricing-store.ts
 async function seedModelPrices(store, prices) {
   for (const price of prices) {
@@ -3171,6 +3260,11 @@ async function claimToolCall(turn, call) {
       ...spec?.detached === true ? {
         detached: true
       } : {},
+      // Same for `terminal`: absent unless declared, so a deployment with no terminal tool writes
+      // the bytes it always has, and a replay reads the branch back instead of re-deciding it.
+      ...spec?.terminal === true ? {
+        terminal: true
+      } : {},
       ...approval !== void 0 ? {
         approval
       } : {}
@@ -3192,6 +3286,9 @@ async function claimToolCall(turn, call) {
     ...persisted?.detached === true ? {
       detached: true
     } : {},
+    ...persisted?.terminal === true ? {
+      terminal: true
+    } : {},
     ...toolType === "action" && persisted?.approval !== void 0 ? {
       approval: persisted.approval
     } : {},
@@ -3358,7 +3455,7 @@ async function invokeClaimedTool(turn, claimed) {
     if (claimed.toolType === "memory") {
       return await rememberIntoTurn(turn, claimed, startedAt);
     }
-    let output;
+    let raw;
     if (hooks.dispatchTool) {
       const stepCtx = {
         actor: input.actor,
@@ -3381,28 +3478,47 @@ async function invokeClaimedTool(turn, claimed) {
         } : {},
         // Numeric-only: the handler applies withToolTimeout AND its own local `classify` — see
         // ToolStepEnvelope.transientRetry.
-        transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry)
+        transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry),
+        // The handler hands back what the tool pushed through `ctx.emitUi` with its output.
+        collectUi: true
       };
-      output = await hooks.dispatchTool(resolvedCall, envelope);
+      raw = await hooks.dispatchTool(resolvedCall, envelope);
     } else {
-      const invocation = hooks.step(`tool:${call.id}`, () => traceToolExecution(hooks.runId, {
-        toolCallId: call.id,
-        toolName: call.name,
-        toolType
-      }, () => invokeWithTransientRetry(() => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy), deps.toolTransientRetry ?? {}, {
-        ...hooks.isControlFlowError !== void 0 ? {
-          isControlFlowError: hooks.isControlFlowError
-        } : {},
-        onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
-          publishAgentToolRetry({
-            toolName: call.name,
-            toolCallId: call.id,
-            attempt,
-            message: retryError instanceof Error ? retryError.message : String(retryError)
-          });
-        }, "onRetry")
-      })));
-      output = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+      const invocation = hooks.step(`tool:${call.id}`, async () => {
+        const ui2 = createUiCollector(call.id, (event) => turn.writer.write(encodeStreamEvent(event)));
+        const output2 = await traceToolExecution(hooks.runId, {
+          toolCallId: call.id,
+          toolName: call.name,
+          toolType
+        }, () => invokeWithTransientRetry(() => {
+          ui2.restart();
+          return deps.registry.invoke(call.name, call.input, {
+            ...ctx,
+            emitUi: ui2.emit
+          }, deps.rolesPolicy);
+        }, deps.toolTransientRetry ?? {}, {
+          ...hooks.isControlFlowError !== void 0 ? {
+            isControlFlowError: hooks.isControlFlowError
+          } : {},
+          onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
+            publishAgentToolRetry({
+              toolName: call.name,
+              toolCallId: call.id,
+              attempt,
+              message: retryError instanceof Error ? retryError.message : String(retryError)
+            });
+          }, "onRetry")
+        }));
+        return wrapToolStepOutput(output2, ui2.components());
+      });
+      raw = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+    }
+    const { output, ui } = unwrapToolStepOutput(raw);
+    if (ui.length > 0) {
+      turn.toolUi.set(call.id, ui);
+    }
+    if (claimed.terminal === true) {
+      turn.halt.terminal = true;
     }
     return {
       status: "executed",
@@ -4300,6 +4416,10 @@ ${block}`;
       hooks,
       messageId: assistant.id,
       writer,
+      toolUi: /* @__PURE__ */ new Map(),
+      halt: {
+        terminal: false
+      },
       ...skillOffer !== void 0 ? {
         skills: skillOffer
       } : {},
@@ -4332,6 +4452,10 @@ ${block}`;
     assistantMessage.toolResults = settledResults;
     await hooks.step(`stream:tool-outputs:${i}`, async () => {
       await deps.store.setMessageToolResults(assistant.id, settledResults);
+      const toolUi = toolCallsWithKind.flatMap((call) => turnCalls.toolUi.get(call.id) ?? []);
+      if (toolUi.length > 0) {
+        await deps.store.setMessageUi?.(assistant.id, mergeUi(turn.ui, toolUi));
+      }
       for (const result of results) {
         await writer.write(encodeStreamEvent(outputFrame(result)));
       }
@@ -4346,6 +4470,9 @@ ${block}`;
         } : {}
       }));
     });
+    if (turnCalls.halt.terminal) {
+      break;
+    }
   }
   if (history.title === "" || history.title === "New chat") {
     await hooks.step("persist:title", () => deps.store.setTitle(input.threadId, deriveTitle(input.userText)));
@@ -4475,6 +4602,7 @@ export {
   compositeSkillProvider,
   createFrameBuffer,
   createIncrementalGate,
+  createUiCollector,
   dayBoundsUtc,
   decodeStreamEvent,
   defaultCanDecide,
@@ -4502,6 +4630,7 @@ export {
   mayDecideApproval,
   memoryForgetVerdict,
   memoryWriteVerdict,
+  mergeUi,
   normalizeDelegation,
   normalizeElicitationReply,
   observeTurnFrames,
@@ -4552,6 +4681,7 @@ export {
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,
+  unwrapToolStepOutput,
   validateElicitationAnswer,
   validateElicitationValue,
   validateStructured,
@@ -4561,6 +4691,7 @@ export {
   withSkillTool,
   withToolTimeout,
   withTurnFrames,
+  wrapToolStepOutput,
   writeMemory
 };
 //# sourceMappingURL=index.js.map