@dudousxd/nestjs-agent-core 0.40.0 → 0.42.0

package/dist/{processors-BR3nICcp.d.ts → processors-BKILjME5.d.ts}

@@ -1,4 +1,4 @@
-import { M as ModelMessage, a as Actor, e as ToolCallRequest } from './stream-events-DAmes2Of.js';
+import { M as ModelMessage, a as Actor, r as ToolCallRequest } from './stream-events-D92SgfRk.js';
 
 /**
  * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites

package/dist/{processors-B7nfbU6E.d.cts → processors-DpHBqRuE.d.cts}

@@ -1,4 +1,4 @@
-import { M as ModelMessage, a as Actor, e as ToolCallRequest } from './stream-events-M0jc7lSW.cjs';
+import { M as ModelMessage, a as Actor, r as ToolCallRequest } from './stream-events-C-pj3bVY.cjs';
 
 /**
  * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites

package/dist/{stream-events-M0jc7lSW.d.cts → stream-events-C-pj3bVY.d.cts}

@@ -1,5 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { a as Catalog } from './catalog-CrzetM3_.cjs';
+import { a as Catalog, C as ComponentDefinition, J as JsonSchema, d as CatalogOptions } from './catalog-BKS3Yxo6.cjs';
 
 /**
  * Typed answers for a question set: a question that asks for a number, a date, an email or a
@@ -531,6 +531,11 @@ interface CreateThreadInput {
     id?: string;
     /** The persona the thread's turns run under when a send names none. See {@link ThreadSummary.persona}. */
     persona?: string;
+    /**
+     * The agent the send that creates the thread names (already resolved: an explicit pick, else the
+     * default). A store that keeps an agent per thread starts it there; others ignore it.
+     */
+    agentName?: string;
 }
 interface AppendMessageInput {
     actionProposalOutcome?: ActionProposalOutcome;
@@ -919,6 +924,8 @@ interface QueuedMessage {
     model?: string;
     pageContext?: PageContext;
     uiCapabilities?: UiCapabilities;
+    /** The send's {@link AgentRunInput.hostContext}, carried to the turn it starts. Never on the wire view. */
+    hostContext?: AgentHostContext;
     /**
      * Queued by an interrupt (`POST chat { mode: 'interrupt' }`): the running turn was cancelled to
      * make room for it, so the cancel starts it instead of pausing the queue.
@@ -958,6 +965,7 @@ interface EnqueueMessageInput {
     model?: string;
     pageContext?: PageContext;
     uiCapabilities?: UiCapabilities;
+    hostContext?: AgentHostContext;
     interrupt?: boolean;
     /** `'tail'` (default) runs it after everything already waiting; `'head'` runs it next. */
     at?: 'tail' | 'head';
@@ -1122,12 +1130,78 @@ interface AgentHistoryWindow {
     summarize?: boolean;
 }
 
+/** Plain, durable data. Renderer functions and binary attachments never enter a UI frame. */
+interface ComponentPresentation<P = Record<string, unknown>> {
+    component: string;
+    props: P;
+    version: number;
+    fallbackText: string;
+}
+interface ComponentFactory<Input, Output = Input> {
+    (props: Input): Promise<ComponentPresentation<Output>>;
+    readonly definition: ComponentDefinition<Output>;
+}
+/** Reject values JSON would silently discard/coerce, and detach from caller-owned objects. */
+declare function snapshotComponentPresentation<T>(value: T): T;
+declare function createComponent<S extends StandardSchemaV1>(definition: Omit<ComponentDefinition<StandardSchemaV1.InferOutput<S>>, 'props'> & {
+    props: S;
+}, options?: CatalogOptions): ComponentFactory<StandardSchemaV1.InferInput<S>, StandardSchemaV1.InferOutput<S>>;
+declare function createComponent<P = Record<string, unknown>>(definition: ComponentDefinition<P>, options?: CatalogOptions): ComponentFactory<P>;
+type ComponentRenderer<P = Record<string, unknown>, Context = unknown> = (props: P, context?: Context) => unknown | Promise<unknown>;
+interface ComponentManifest {
+    name: string;
+    title: string;
+    description: string;
+    version: number;
+    props?: JsonSchema;
+}
+interface ComponentRegistry<Context = unknown> {
+    readonly catalog: Catalog;
+    readonly manifest: readonly ComponentManifest[];
+    register<P>(definition: ComponentDefinition<P>, renderers: Record<string, ComponentRenderer<P, Context>>): this;
+    /** Revalidate against the app's authoritative definition and regenerate trusted fallback text. */
+    prepare(presentation: ComponentPresentation): Promise<ComponentPresentation>;
+    render(presentation: ComponentPresentation, channel: string, context?: Context): Promise<unknown>;
+}
+/** A registry is owned by one app/tenant; registering never mutates a shared singleton. */
+declare function createComponentRegistry<Context = unknown>(options?: CatalogOptions): ComponentRegistry<Context>;
+type TableCell = string | number | boolean | null;
+interface TableProps {
+    title?: string;
+    columns: {
+        key: string;
+        label: string;
+        align?: 'left' | 'right' | 'center';
+        format?: 'text' | 'number' | 'currency' | 'percent' | 'date' | 'link';
+    }[];
+    rows: Record<string, TableCell>[];
+}
+interface ChartProps {
+    type: 'bar' | 'line';
+    title?: string;
+    xKey: string;
+    series: {
+        key: string;
+        label?: string;
+    }[];
+    data: Record<string, TableCell>[];
+    unit?: string;
+}
+declare const table: ComponentFactory<TableProps, TableProps>;
+declare const chart: ComponentFactory<ChartProps, ChartProps>;
+/** Prepare all JSON emissions before any sink receives a partial batch. Factories validate schemas. */
+declare function validatePresentationBatch(presentations: ComponentPresentation<object> | readonly ComponentPresentation<object>[]): ComponentPresentation[];
+
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
  * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
  * no denormalized copies).
  */
 interface AiToolCtx {
+    /** Reports presentation failures separately from successful domain execution. */
+    onPresentationError?(error: unknown, details: {
+        toolName: string;
+    }): void | Promise<void>;
     uiCapabilities?: UiCapabilities;
     actor: Actor;
     threadId: string;
@@ -1198,6 +1272,8 @@ type ToolPreflightResult<O = unknown> = {
 /** A tool implementation. `I` is the input parsed by its registered Standard Schema. */
 interface ToolHandler<I = unknown, O = unknown> {
     execute(input: I, ctx: AiToolCtx): Promise<O>;
+    /** Optional UI derived from successful domain output; errors never fail the domain action. */
+    present?(output: O, ctx: AiToolCtx): ComponentPresentation<object> | readonly ComponentPresentation<object>[] | undefined | Promise<ComponentPresentation<object> | readonly ComponentPresentation<object>[] | undefined>;
     /** Read-only action check. Runs after authorization and validation, before approval and again
      * immediately before execution. Confirmation strings are resolved, never templates. */
     preflight?(input: I, ctx: AiToolCtx, options: ToolPreflightOptions): ToolPreflightResult<O> | Promise<ToolPreflightResult<O>>;
@@ -1437,8 +1513,9 @@ interface ToolSpec {
     enabled?: boolean | (() => boolean | Promise<boolean>);
     /**
      * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
-     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
-     * and rely on `roles` instead — both live on the same SPI, so neither is required.
+     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. A policy that can't evaluate one (the
+     * role-based default) refuses a tool that names an `ability` and no `roles` — fail closed rather
+     * than open; a tool naming both falls back to its `roles` there.
      */
     ability?: string;
 }
@@ -1713,6 +1790,10 @@ type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
  */
 type PromptContributor = (ctx: PromptContext) => string | null | Promise<string | null>;
 /** Everything needed to run one agent turn. */
+/** See {@link AgentRunInput.hostContext}. JSON only. */
+type AgentHostContext = {
+    readonly [key: string]: unknown;
+};
 interface AgentRunInput {
     threadId: string;
     actor: Actor;
@@ -1779,6 +1860,13 @@ interface AgentRunInput {
      * label when the provider reports none. Omitted → the provider's default.
      */
     model?: string;
+    /**
+     * What the HOST knows about this turn that the library does not model — where it came from, where
+     * its answer goes, on whose behalf (e.g. `{ source: 'slack', delivery: { channel, ts } }`). Plain
+     * JSON: it travels through the queue and the durable journal untouched, and reaches the runner's
+     * hooks (an engine's host callbacks) as it was sent. Never shown to the model or to clients.
+     */
+    hostContext?: AgentHostContext;
 }
 /**
  * A named agent: its prompt, the tools it may use, and who it can hand off to. This is the
@@ -2575,4 +2663,4 @@ type AgentStreamErrorCode = 'quota_exceeded' | 'output_rejected' | 'structured_o
 /** A model call ended without producing anything. */
  | 'model_no_output' | 'run_failed';
 
-export { type ToolCallStatus as $, type AgentStreamEvent as A, type ToolTransientRetrySetting as B, type AgentIntake as C, type DetachedDelivery as D, type Decision as E, type ElicitationRequest as F, type ToolStepEnvelope as G, type HumanReply as H, type ClaimActionProposal as I, type ActionProposal as J, type ActionProposalStore as K, type LlmStepEnvelope as L, type ModelMessage as M, type ActionProposalStoreOptions as N, type CreateActionProposal as O, type PreparedUiEmission as P, type QuotaState as Q, type CreateActionProposalResult as R, type ActionProposalScope as S, type ToolSpec as T, type UiCapabilities as U, type ListActionProposals as V, type ActionProposalDecisionCommand as W, type ExtendActionProposalLease as X, type SettleActionProposal as Y, type ActionProposalOutcome as Z, type ActionProposalOutcomeLease as _, type Actor as a, type MessageFeedbackValue as a$, type ChatQueueStore as a0, type ActionProposalOutcomeStore as a1, type CreateThreadInput as a2, type ThreadSummary as a3, type ThreadDetail as a4, type ToolCallApprovalState as a5, type UpdateThreadInput as a6, type RecordRunStartInput as a7, type EnqueueMessageInput as a8, type QueuedMessage as a9, type AgentHistoryWindow as aA, type AgentStreamErrorCode as aB, type ApprovalDecisionRef as aC, type ApprovalRequirement as aD, type ApprovalThreadRef as aE, type ApprovalToolRef as aF, type AskToolInput as aG, type ChatQueueState as aH, type ClaimedActionApproval as aI, DEFAULT_INTAKE_PREAMBLE as aJ, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aK, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as aL, DefaultApprovalPolicy as aM, ELICITATION_INPUT_TYPES as aN, type ElicitationInput as aO, type ElicitationInputType as aP, type ElicitationOption as aQ, type ElicitationOutcome as aR, type ElicitationQuestion as aS, type ElicitationReply as aT, type ElicitationResult as aU, type EmitUiOptions as aV, type HistoryPolicyContext as aW, type HistorySelection as aX, type HistorySummary as aY, type InvokeWithTransientRetryOptions as aZ, MAX_ASK_QUESTIONS as a_, type QueuedMessagePatch as aa, type QueuePause as ab, type AppendMessageInput as ac, type StoredMessage as ad, type ToolResult as ae, type MessageFeedback as af, type RecordToolCallInput as ag, type ToolCallOutcome as ah, type UpdateToolCallInput as ai, type RecordUsageInput as aj, type ToolConfirmation as ak, type ActionProposalDecision as al, type ActionProposalSupersessionStore as am, ALL_AGENTS as an, ASK_TOOL_DESCRIPTION as ao, ASK_TOOL_NAME as ap, type ActionProposalDecisionAudit as aq, type ActionProposalExecution as ar, type ActionProposalExecutionContext as as, type ActionProposalLease as at, type ActionProposalOutcomeDelivery as au, type AgentApprovalRequest as av, type AgentApprovalSettlement as aw, type AgentAttachmentConfig as ax, type AgentCatalogEntry as ay, type AgentClientConfig as az, type ToolHandler as b, type MessageRole as b0, type PersonaRef as b1, type PromptContext as b2, type QueuePauseReason as b3, type QueuedMessageView as b4, type QuotaView as b5, REQUESTER_APPROVER as b6, RUN_ENDED_BEFORE_TOOL_CALL as b7, type RecordRunEndInput as b8, type ResolveActionProposalApprovalInput as b9, isChatQueueStore as bA, isTransientToolError as bB, isTypedQuestion as bC, mayDecideApproval as bD, normalizeElicitationReply as bE, questionOptions as bF, queuedMessageView as bG, readElicitationInput as bH, readElicitationQuestions as bI, releaseThreadRun as bJ, renderElicitationAnswers as bK, resolveActionProposalApproval as bL, resolveElicitation as bM, resolveToolTransientRetryNumbers as bN, settleDanglingToolCalls as bO, settleElicitation as bP, toolCallApprovalFromRow as bQ, validateElicitationAnswer as bR, validateElicitationValue as bS, type ThreadTurnPage as ba, type ThreadTurnQuery as bb, type ThreadTurnReader as bc, type ToolCallApproval as bd, type ToolCallApprovalColumns as be, type ToolCallApprovalStatus as bf, type ToolCatalogEntry as bg, type ToolDescription as bh, type ToolKind as bi, type ToolPreflightOptions as bj, type ToolPresentationTone as bk, type ToolResultField as bl, type ToolResultView as bm, type ToolStepCtx as bn, type ToolTransientRetryNumbers as bo, type ToolTransientRetryOptions as bp, type TurnPersona as bq, UNFINISHED_TOOL_CALL as br, type UsagePurpose as bs, askInputSchema as bt, askToolDefinition as bu, danglingToolCallIds as bv, decodeStreamEvent as bw, defaultCanDecide as bx, encodeStreamEvent as by, invokeWithTransientRetry as bz, type ToolPresentation as c, type ToolDefinition as d, type ToolCallRequest as e, type MessageUsage as f, type AgentUiComponent as g, type AiToolCtx as h, type AgentRunInput as i, type MessageAttachment as j, type ActionProposalMutationResult as k, type AgentDefinition as l, type Persona as m, negotiateCatalog as n, type PersonaCatalogEntry as o, prepareUiEmission as p, type HistoryPolicy as q, type PageContext as r, type AgentStore as s, type AgentDelegation as t, type ToolDescribeScope as u, validateUiCapabilities as v, type ToolPreflightResult as w, type ApprovalPolicy as x, type PromptBuilder as y, type PromptContributor as z };
+export { type Decision as $, type AgentStreamEvent as A, type ActionProposalMutationResult as B, type ChartProps as C, type ActionProposal as D, type ActionProposalExecution as E, type ActionProposalOutcomeDelivery as F, type AgentDefinition as G, type HumanReply as H, type Persona as I, type PersonaCatalogEntry as J, type HistoryPolicy as K, type PageContext as L, type ModelMessage as M, type AgentStore as N, type AgentDelegation as O, type PreparedUiEmission as P, type QuotaState as Q, type DetachedDelivery as R, type ToolDescribeScope as S, type ToolSpec as T, type UiCapabilities as U, type ToolPreflightResult as V, type ApprovalPolicy as W, type PromptBuilder as X, type PromptContributor as Y, type ToolTransientRetrySetting as Z, type AgentIntake as _, type Actor as a, DefaultApprovalPolicy as a$, type ElicitationRequest as a0, type LlmStepEnvelope as a1, type ToolStepEnvelope as a2, type ClaimActionProposal as a3, type ActionProposalStore as a4, type ActionProposalStoreOptions as a5, type CreateActionProposal as a6, type CreateActionProposalResult as a7, type ActionProposalScope as a8, type ListActionProposals as a9, type ToolConfirmation as aA, type ActionProposalDecision as aB, type ActionProposalSupersessionStore as aC, ALL_AGENTS as aD, ASK_TOOL_DESCRIPTION as aE, ASK_TOOL_NAME as aF, type ActionProposalDecisionAudit as aG, type ActionProposalExecutionContext as aH, type ActionProposalLease as aI, type AgentApprovalRequest as aJ, type AgentApprovalSettlement as aK, type AgentAttachmentConfig as aL, type AgentCatalogEntry as aM, type AgentClientConfig as aN, type AgentHistoryWindow as aO, type AgentHostContext as aP, type AgentStreamErrorCode as aQ, type ApprovalDecisionRef as aR, type ApprovalRequirement as aS, type ApprovalThreadRef as aT, type ApprovalToolRef as aU, type AskToolInput as aV, type ChatQueueState as aW, type ClaimedActionApproval as aX, DEFAULT_INTAKE_PREAMBLE as aY, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aZ, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as a_, type ActionProposalDecisionCommand as aa, type ExtendActionProposalLease as ab, type SettleActionProposal as ac, type ActionProposalOutcome as ad, type ActionProposalOutcomeLease as ae, type ToolCallStatus as af, type ChatQueueStore as ag, type ActionProposalOutcomeStore as ah, type CreateThreadInput as ai, type ThreadSummary as aj, type ThreadDetail as ak, type ToolCallApprovalState as al, type UpdateThreadInput as am, type RecordRunStartInput as an, type EnqueueMessageInput as ao, type QueuedMessage as ap, type QueuedMessagePatch as aq, type QueuePause as ar, type AppendMessageInput as as, type StoredMessage as at, type ToolResult as au, type MessageFeedback as av, type RecordToolCallInput as aw, type ToolCallOutcome as ax, type UpdateToolCallInput as ay, type RecordUsageInput as az, type ToolHandler as b, resolveElicitation as b$, ELICITATION_INPUT_TYPES as b0, type ElicitationInput as b1, type ElicitationInputType as b2, type ElicitationOption as b3, type ElicitationOutcome as b4, type ElicitationQuestion as b5, type ElicitationReply as b6, type ElicitationResult as b7, type EmitUiOptions as b8, type HistoryPolicyContext as b9, type ToolResultField as bA, type ToolResultView as bB, type ToolStepCtx as bC, type ToolTransientRetryNumbers as bD, type ToolTransientRetryOptions as bE, type TurnPersona as bF, UNFINISHED_TOOL_CALL as bG, type UsagePurpose as bH, askInputSchema as bI, askToolDefinition as bJ, danglingToolCallIds as bK, decodeStreamEvent as bL, defaultCanDecide as bM, encodeStreamEvent as bN, invokeWithTransientRetry as bO, isChatQueueStore as bP, isTransientToolError as bQ, isTypedQuestion as bR, mayDecideApproval as bS, normalizeElicitationReply as bT, questionOptions as bU, queuedMessageView as bV, readElicitationInput as bW, readElicitationQuestions as bX, releaseThreadRun as bY, renderElicitationAnswers as bZ, resolveActionProposalApproval as b_, type HistorySelection as ba, type HistorySummary as bb, type InvokeWithTransientRetryOptions as bc, MAX_ASK_QUESTIONS as bd, type MessageFeedbackValue as be, type MessageRole as bf, type PersonaRef as bg, type PromptContext as bh, type QueuePauseReason as bi, type QueuedMessageView as bj, type QuotaView as bk, REQUESTER_APPROVER as bl, RUN_ENDED_BEFORE_TOOL_CALL as bm, type RecordRunEndInput as bn, type ResolveActionProposalApprovalInput as bo, type ThreadTurnPage as bp, type ThreadTurnQuery as bq, type ThreadTurnReader as br, type ToolCallApproval as bs, type ToolCallApprovalColumns as bt, type ToolCallApprovalStatus as bu, type ToolCatalogEntry as bv, type ToolDescription as bw, type ToolKind as bx, type ToolPreflightOptions as by, type ToolPresentationTone as bz, type ToolPresentation as c, resolveToolTransientRetryNumbers as c0, settleDanglingToolCalls as c1, settleElicitation as c2, toolCallApprovalFromRow as c3, validateElicitationAnswer as c4, validateElicitationValue as c5, type ComponentFactory as d, type ComponentManifest as e, type ComponentPresentation as f, type ComponentRegistry as g, type ComponentRenderer as h, type TableCell as i, type TableProps as j, chart as k, createComponent as l, createComponentRegistry as m, negotiateCatalog as n, validateUiCapabilities as o, prepareUiEmission as p, type ToolDefinition as q, type ToolCallRequest as r, snapshotComponentPresentation as s, table as t, type MessageUsage as u, validatePresentationBatch as v, type AgentUiComponent as w, type AiToolCtx as x, type AgentRunInput as y, type MessageAttachment as z };

package/dist/{stream-events-DAmes2Of.d.ts → stream-events-D92SgfRk.d.ts}

@@ -1,5 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { a as Catalog } from './catalog-CrzetM3_.js';
+import { a as Catalog, C as ComponentDefinition, J as JsonSchema, d as CatalogOptions } from './catalog-BKS3Yxo6.js';
 
 /**
  * Typed answers for a question set: a question that asks for a number, a date, an email or a
@@ -531,6 +531,11 @@ interface CreateThreadInput {
     id?: string;
     /** The persona the thread's turns run under when a send names none. See {@link ThreadSummary.persona}. */
     persona?: string;
+    /**
+     * The agent the send that creates the thread names (already resolved: an explicit pick, else the
+     * default). A store that keeps an agent per thread starts it there; others ignore it.
+     */
+    agentName?: string;
 }
 interface AppendMessageInput {
     actionProposalOutcome?: ActionProposalOutcome;
@@ -919,6 +924,8 @@ interface QueuedMessage {
     model?: string;
     pageContext?: PageContext;
     uiCapabilities?: UiCapabilities;
+    /** The send's {@link AgentRunInput.hostContext}, carried to the turn it starts. Never on the wire view. */
+    hostContext?: AgentHostContext;
     /**
      * Queued by an interrupt (`POST chat { mode: 'interrupt' }`): the running turn was cancelled to
      * make room for it, so the cancel starts it instead of pausing the queue.
@@ -958,6 +965,7 @@ interface EnqueueMessageInput {
     model?: string;
     pageContext?: PageContext;
     uiCapabilities?: UiCapabilities;
+    hostContext?: AgentHostContext;
     interrupt?: boolean;
     /** `'tail'` (default) runs it after everything already waiting; `'head'` runs it next. */
     at?: 'tail' | 'head';
@@ -1122,12 +1130,78 @@ interface AgentHistoryWindow {
     summarize?: boolean;
 }
 
+/** Plain, durable data. Renderer functions and binary attachments never enter a UI frame. */
+interface ComponentPresentation<P = Record<string, unknown>> {
+    component: string;
+    props: P;
+    version: number;
+    fallbackText: string;
+}
+interface ComponentFactory<Input, Output = Input> {
+    (props: Input): Promise<ComponentPresentation<Output>>;
+    readonly definition: ComponentDefinition<Output>;
+}
+/** Reject values JSON would silently discard/coerce, and detach from caller-owned objects. */
+declare function snapshotComponentPresentation<T>(value: T): T;
+declare function createComponent<S extends StandardSchemaV1>(definition: Omit<ComponentDefinition<StandardSchemaV1.InferOutput<S>>, 'props'> & {
+    props: S;
+}, options?: CatalogOptions): ComponentFactory<StandardSchemaV1.InferInput<S>, StandardSchemaV1.InferOutput<S>>;
+declare function createComponent<P = Record<string, unknown>>(definition: ComponentDefinition<P>, options?: CatalogOptions): ComponentFactory<P>;
+type ComponentRenderer<P = Record<string, unknown>, Context = unknown> = (props: P, context?: Context) => unknown | Promise<unknown>;
+interface ComponentManifest {
+    name: string;
+    title: string;
+    description: string;
+    version: number;
+    props?: JsonSchema;
+}
+interface ComponentRegistry<Context = unknown> {
+    readonly catalog: Catalog;
+    readonly manifest: readonly ComponentManifest[];
+    register<P>(definition: ComponentDefinition<P>, renderers: Record<string, ComponentRenderer<P, Context>>): this;
+    /** Revalidate against the app's authoritative definition and regenerate trusted fallback text. */
+    prepare(presentation: ComponentPresentation): Promise<ComponentPresentation>;
+    render(presentation: ComponentPresentation, channel: string, context?: Context): Promise<unknown>;
+}
+/** A registry is owned by one app/tenant; registering never mutates a shared singleton. */
+declare function createComponentRegistry<Context = unknown>(options?: CatalogOptions): ComponentRegistry<Context>;
+type TableCell = string | number | boolean | null;
+interface TableProps {
+    title?: string;
+    columns: {
+        key: string;
+        label: string;
+        align?: 'left' | 'right' | 'center';
+        format?: 'text' | 'number' | 'currency' | 'percent' | 'date' | 'link';
+    }[];
+    rows: Record<string, TableCell>[];
+}
+interface ChartProps {
+    type: 'bar' | 'line';
+    title?: string;
+    xKey: string;
+    series: {
+        key: string;
+        label?: string;
+    }[];
+    data: Record<string, TableCell>[];
+    unit?: string;
+}
+declare const table: ComponentFactory<TableProps, TableProps>;
+declare const chart: ComponentFactory<ChartProps, ChartProps>;
+/** Prepare all JSON emissions before any sink receives a partial batch. Factories validate schemas. */
+declare function validatePresentationBatch(presentations: ComponentPresentation<object> | readonly ComponentPresentation<object>[]): ComponentPresentation[];
+
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
  * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
  * no denormalized copies).
  */
 interface AiToolCtx {
+    /** Reports presentation failures separately from successful domain execution. */
+    onPresentationError?(error: unknown, details: {
+        toolName: string;
+    }): void | Promise<void>;
     uiCapabilities?: UiCapabilities;
     actor: Actor;
     threadId: string;
@@ -1198,6 +1272,8 @@ type ToolPreflightResult<O = unknown> = {
 /** A tool implementation. `I` is the input parsed by its registered Standard Schema. */
 interface ToolHandler<I = unknown, O = unknown> {
     execute(input: I, ctx: AiToolCtx): Promise<O>;
+    /** Optional UI derived from successful domain output; errors never fail the domain action. */
+    present?(output: O, ctx: AiToolCtx): ComponentPresentation<object> | readonly ComponentPresentation<object>[] | undefined | Promise<ComponentPresentation<object> | readonly ComponentPresentation<object>[] | undefined>;
     /** Read-only action check. Runs after authorization and validation, before approval and again
      * immediately before execution. Confirmation strings are resolved, never templates. */
     preflight?(input: I, ctx: AiToolCtx, options: ToolPreflightOptions): ToolPreflightResult<O> | Promise<ToolPreflightResult<O>>;
@@ -1437,8 +1513,9 @@ interface ToolSpec {
     enabled?: boolean | (() => boolean | Promise<boolean>);
     /**
      * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
-     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
-     * and rely on `roles` instead — both live on the same SPI, so neither is required.
+     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. A policy that can't evaluate one (the
+     * role-based default) refuses a tool that names an `ability` and no `roles` — fail closed rather
+     * than open; a tool naming both falls back to its `roles` there.
      */
     ability?: string;
 }
@@ -1713,6 +1790,10 @@ type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
  */
 type PromptContributor = (ctx: PromptContext) => string | null | Promise<string | null>;
 /** Everything needed to run one agent turn. */
+/** See {@link AgentRunInput.hostContext}. JSON only. */
+type AgentHostContext = {
+    readonly [key: string]: unknown;
+};
 interface AgentRunInput {
     threadId: string;
     actor: Actor;
@@ -1779,6 +1860,13 @@ interface AgentRunInput {
      * label when the provider reports none. Omitted → the provider's default.
      */
     model?: string;
+    /**
+     * What the HOST knows about this turn that the library does not model — where it came from, where
+     * its answer goes, on whose behalf (e.g. `{ source: 'slack', delivery: { channel, ts } }`). Plain
+     * JSON: it travels through the queue and the durable journal untouched, and reaches the runner's
+     * hooks (an engine's host callbacks) as it was sent. Never shown to the model or to clients.
+     */
+    hostContext?: AgentHostContext;
 }
 /**
  * A named agent: its prompt, the tools it may use, and who it can hand off to. This is the
@@ -2575,4 +2663,4 @@ type AgentStreamErrorCode = 'quota_exceeded' | 'output_rejected' | 'structured_o
 /** A model call ended without producing anything. */
  | 'model_no_output' | 'run_failed';
 
-export { type ToolCallStatus as $, type AgentStreamEvent as A, type ToolTransientRetrySetting as B, type AgentIntake as C, type DetachedDelivery as D, type Decision as E, type ElicitationRequest as F, type ToolStepEnvelope as G, type HumanReply as H, type ClaimActionProposal as I, type ActionProposal as J, type ActionProposalStore as K, type LlmStepEnvelope as L, type ModelMessage as M, type ActionProposalStoreOptions as N, type CreateActionProposal as O, type PreparedUiEmission as P, type QuotaState as Q, type CreateActionProposalResult as R, type ActionProposalScope as S, type ToolSpec as T, type UiCapabilities as U, type ListActionProposals as V, type ActionProposalDecisionCommand as W, type ExtendActionProposalLease as X, type SettleActionProposal as Y, type ActionProposalOutcome as Z, type ActionProposalOutcomeLease as _, type Actor as a, type MessageFeedbackValue as a$, type ChatQueueStore as a0, type ActionProposalOutcomeStore as a1, type CreateThreadInput as a2, type ThreadSummary as a3, type ThreadDetail as a4, type ToolCallApprovalState as a5, type UpdateThreadInput as a6, type RecordRunStartInput as a7, type EnqueueMessageInput as a8, type QueuedMessage as a9, type AgentHistoryWindow as aA, type AgentStreamErrorCode as aB, type ApprovalDecisionRef as aC, type ApprovalRequirement as aD, type ApprovalThreadRef as aE, type ApprovalToolRef as aF, type AskToolInput as aG, type ChatQueueState as aH, type ClaimedActionApproval as aI, DEFAULT_INTAKE_PREAMBLE as aJ, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aK, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as aL, DefaultApprovalPolicy as aM, ELICITATION_INPUT_TYPES as aN, type ElicitationInput as aO, type ElicitationInputType as aP, type ElicitationOption as aQ, type ElicitationOutcome as aR, type ElicitationQuestion as aS, type ElicitationReply as aT, type ElicitationResult as aU, type EmitUiOptions as aV, type HistoryPolicyContext as aW, type HistorySelection as aX, type HistorySummary as aY, type InvokeWithTransientRetryOptions as aZ, MAX_ASK_QUESTIONS as a_, type QueuedMessagePatch as aa, type QueuePause as ab, type AppendMessageInput as ac, type StoredMessage as ad, type ToolResult as ae, type MessageFeedback as af, type RecordToolCallInput as ag, type ToolCallOutcome as ah, type UpdateToolCallInput as ai, type RecordUsageInput as aj, type ToolConfirmation as ak, type ActionProposalDecision as al, type ActionProposalSupersessionStore as am, ALL_AGENTS as an, ASK_TOOL_DESCRIPTION as ao, ASK_TOOL_NAME as ap, type ActionProposalDecisionAudit as aq, type ActionProposalExecution as ar, type ActionProposalExecutionContext as as, type ActionProposalLease as at, type ActionProposalOutcomeDelivery as au, type AgentApprovalRequest as av, type AgentApprovalSettlement as aw, type AgentAttachmentConfig as ax, type AgentCatalogEntry as ay, type AgentClientConfig as az, type ToolHandler as b, type MessageRole as b0, type PersonaRef as b1, type PromptContext as b2, type QueuePauseReason as b3, type QueuedMessageView as b4, type QuotaView as b5, REQUESTER_APPROVER as b6, RUN_ENDED_BEFORE_TOOL_CALL as b7, type RecordRunEndInput as b8, type ResolveActionProposalApprovalInput as b9, isChatQueueStore as bA, isTransientToolError as bB, isTypedQuestion as bC, mayDecideApproval as bD, normalizeElicitationReply as bE, questionOptions as bF, queuedMessageView as bG, readElicitationInput as bH, readElicitationQuestions as bI, releaseThreadRun as bJ, renderElicitationAnswers as bK, resolveActionProposalApproval as bL, resolveElicitation as bM, resolveToolTransientRetryNumbers as bN, settleDanglingToolCalls as bO, settleElicitation as bP, toolCallApprovalFromRow as bQ, validateElicitationAnswer as bR, validateElicitationValue as bS, type ThreadTurnPage as ba, type ThreadTurnQuery as bb, type ThreadTurnReader as bc, type ToolCallApproval as bd, type ToolCallApprovalColumns as be, type ToolCallApprovalStatus as bf, type ToolCatalogEntry as bg, type ToolDescription as bh, type ToolKind as bi, type ToolPreflightOptions as bj, type ToolPresentationTone as bk, type ToolResultField as bl, type ToolResultView as bm, type ToolStepCtx as bn, type ToolTransientRetryNumbers as bo, type ToolTransientRetryOptions as bp, type TurnPersona as bq, UNFINISHED_TOOL_CALL as br, type UsagePurpose as bs, askInputSchema as bt, askToolDefinition as bu, danglingToolCallIds as bv, decodeStreamEvent as bw, defaultCanDecide as bx, encodeStreamEvent as by, invokeWithTransientRetry as bz, type ToolPresentation as c, type ToolDefinition as d, type ToolCallRequest as e, type MessageUsage as f, type AgentUiComponent as g, type AiToolCtx as h, type AgentRunInput as i, type MessageAttachment as j, type ActionProposalMutationResult as k, type AgentDefinition as l, type Persona as m, negotiateCatalog as n, type PersonaCatalogEntry as o, prepareUiEmission as p, type HistoryPolicy as q, type PageContext as r, type AgentStore as s, type AgentDelegation as t, type ToolDescribeScope as u, validateUiCapabilities as v, type ToolPreflightResult as w, type ApprovalPolicy as x, type PromptBuilder as y, type PromptContributor as z };
+export { type Decision as $, type AgentStreamEvent as A, type ActionProposalMutationResult as B, type ChartProps as C, type ActionProposal as D, type ActionProposalExecution as E, type ActionProposalOutcomeDelivery as F, type AgentDefinition as G, type HumanReply as H, type Persona as I, type PersonaCatalogEntry as J, type HistoryPolicy as K, type PageContext as L, type ModelMessage as M, type AgentStore as N, type AgentDelegation as O, type PreparedUiEmission as P, type QuotaState as Q, type DetachedDelivery as R, type ToolDescribeScope as S, type ToolSpec as T, type UiCapabilities as U, type ToolPreflightResult as V, type ApprovalPolicy as W, type PromptBuilder as X, type PromptContributor as Y, type ToolTransientRetrySetting as Z, type AgentIntake as _, type Actor as a, DefaultApprovalPolicy as a$, type ElicitationRequest as a0, type LlmStepEnvelope as a1, type ToolStepEnvelope as a2, type ClaimActionProposal as a3, type ActionProposalStore as a4, type ActionProposalStoreOptions as a5, type CreateActionProposal as a6, type CreateActionProposalResult as a7, type ActionProposalScope as a8, type ListActionProposals as a9, type ToolConfirmation as aA, type ActionProposalDecision as aB, type ActionProposalSupersessionStore as aC, ALL_AGENTS as aD, ASK_TOOL_DESCRIPTION as aE, ASK_TOOL_NAME as aF, type ActionProposalDecisionAudit as aG, type ActionProposalExecutionContext as aH, type ActionProposalLease as aI, type AgentApprovalRequest as aJ, type AgentApprovalSettlement as aK, type AgentAttachmentConfig as aL, type AgentCatalogEntry as aM, type AgentClientConfig as aN, type AgentHistoryWindow as aO, type AgentHostContext as aP, type AgentStreamErrorCode as aQ, type ApprovalDecisionRef as aR, type ApprovalRequirement as aS, type ApprovalThreadRef as aT, type ApprovalToolRef as aU, type AskToolInput as aV, type ChatQueueState as aW, type ClaimedActionApproval as aX, DEFAULT_INTAKE_PREAMBLE as aY, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aZ, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as a_, type ActionProposalDecisionCommand as aa, type ExtendActionProposalLease as ab, type SettleActionProposal as ac, type ActionProposalOutcome as ad, type ActionProposalOutcomeLease as ae, type ToolCallStatus as af, type ChatQueueStore as ag, type ActionProposalOutcomeStore as ah, type CreateThreadInput as ai, type ThreadSummary as aj, type ThreadDetail as ak, type ToolCallApprovalState as al, type UpdateThreadInput as am, type RecordRunStartInput as an, type EnqueueMessageInput as ao, type QueuedMessage as ap, type QueuedMessagePatch as aq, type QueuePause as ar, type AppendMessageInput as as, type StoredMessage as at, type ToolResult as au, type MessageFeedback as av, type RecordToolCallInput as aw, type ToolCallOutcome as ax, type UpdateToolCallInput as ay, type RecordUsageInput as az, type ToolHandler as b, resolveElicitation as b$, ELICITATION_INPUT_TYPES as b0, type ElicitationInput as b1, type ElicitationInputType as b2, type ElicitationOption as b3, type ElicitationOutcome as b4, type ElicitationQuestion as b5, type ElicitationReply as b6, type ElicitationResult as b7, type EmitUiOptions as b8, type HistoryPolicyContext as b9, type ToolResultField as bA, type ToolResultView as bB, type ToolStepCtx as bC, type ToolTransientRetryNumbers as bD, type ToolTransientRetryOptions as bE, type TurnPersona as bF, UNFINISHED_TOOL_CALL as bG, type UsagePurpose as bH, askInputSchema as bI, askToolDefinition as bJ, danglingToolCallIds as bK, decodeStreamEvent as bL, defaultCanDecide as bM, encodeStreamEvent as bN, invokeWithTransientRetry as bO, isChatQueueStore as bP, isTransientToolError as bQ, isTypedQuestion as bR, mayDecideApproval as bS, normalizeElicitationReply as bT, questionOptions as bU, queuedMessageView as bV, readElicitationInput as bW, readElicitationQuestions as bX, releaseThreadRun as bY, renderElicitationAnswers as bZ, resolveActionProposalApproval as b_, type HistorySelection as ba, type HistorySummary as bb, type InvokeWithTransientRetryOptions as bc, MAX_ASK_QUESTIONS as bd, type MessageFeedbackValue as be, type MessageRole as bf, type PersonaRef as bg, type PromptContext as bh, type QueuePauseReason as bi, type QueuedMessageView as bj, type QuotaView as bk, REQUESTER_APPROVER as bl, RUN_ENDED_BEFORE_TOOL_CALL as bm, type RecordRunEndInput as bn, type ResolveActionProposalApprovalInput as bo, type ThreadTurnPage as bp, type ThreadTurnQuery as bq, type ThreadTurnReader as br, type ToolCallApproval as bs, type ToolCallApprovalColumns as bt, type ToolCallApprovalStatus as bu, type ToolCatalogEntry as bv, type ToolDescription as bw, type ToolKind as bx, type ToolPreflightOptions as by, type ToolPresentationTone as bz, type ToolPresentation as c, resolveToolTransientRetryNumbers as c0, settleDanglingToolCalls as c1, settleElicitation as c2, toolCallApprovalFromRow as c3, validateElicitationAnswer as c4, validateElicitationValue as c5, type ComponentFactory as d, type ComponentManifest as e, type ComponentPresentation as f, type ComponentRegistry as g, type ComponentRenderer as h, type TableCell as i, type TableProps as j, chart as k, createComponent as l, createComponentRegistry as m, negotiateCatalog as n, validateUiCapabilities as o, prepareUiEmission as p, type ToolDefinition as q, type ToolCallRequest as r, snapshotComponentPresentation as s, table as t, type MessageUsage as u, validatePresentationBatch as v, type AgentUiComponent as w, type AiToolCtx as x, type AgentRunInput as y, type MessageAttachment as z };

package/package.json

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