@dudousxd/nestjs-agent-core 0.39.0 → 0.41.0

package/dist/{stream-events-CbVEowYb.d.cts → stream-events-BGKLD6RX.d.ts}

@@ -1,4 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
+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
@@ -69,6 +70,419 @@ declare function readElicitationInput(raw: unknown): ElicitationInput | undefine
  */
 declare function readElicitationQuestions(input: unknown): ElicitationQuestion[];
 
+/**
+ * How a person-facing surface talks about a tool WITHOUT ever naming it. Declared on the server,
+ * beside the tool's input schema, because whoever changes the input is the one who has to re-word
+ * the sentence that mentions it — and a client that shipped its own name-to-sentence map would go
+ * stale the moment a tool was renamed. A tool name is an identifier, never copy.
+ *
+ * `running` / `done` (and `confirm.title`, `confirm.detail`, `result.text`) are templates:
+ * `{dotted.path}` placeholders are filled from the call's INPUT (or, for `result`, its OUTPUT), so one
+ * declaration covers every call the tool will ever receive and replays identically from history.
+ * A placeholder with nothing behind it collapses along with the space before it.
+ */
+interface ToolPresentation {
+    /** Noun phrase, for counts and headings: "Database query", "Knowledge base". */
+    label: string;
+    /** Present progressive, while the call is in flight: "Reading {bucket}". */
+    running: string;
+    /** Settled, once the output is in: "Read {bucket}". */
+    done: string;
+    /** A key into the client's own glyph map (`database`, `search`, …). Unknown keys fall back to a generic glyph there. */
+    icon?: string;
+    /** One line naming what the tool reaches, for when the activity line is opened. */
+    detail?: string;
+    /** `destructive` earns the warning treatment on an approval prompt. */
+    tone?: ToolPresentationTone;
+    /** What a person is being asked to allow when an `action` call parks for approval. */
+    confirm?: ToolConfirmation;
+    /** How the call's OUTPUT reads as content. */
+    result?: ToolResultView;
+}
+type ToolPresentationTone = 'neutral' | 'destructive';
+interface ToolConfirmation {
+    /** "Delete {count} files?" */
+    title: string;
+    /** The button: "Delete". */
+    verb: string;
+    /** A sentence under the title, when the title alone does not say what changes. */
+    detail?: string;
+}
+/** A value read out of a tool's output by dotted path, with the words to put next to it. */
+interface ToolResultField {
+    path: string;
+    label: string;
+    unit?: string;
+}
+/**
+ * How a tool's output reads as content. Every variant names dotted paths into the output rather
+ * than shapes, so a renderer never has to recognise which tool it is drawing: it receives
+ * `{ view, output }` and draws it.
+ */
+type ToolResultView = 
+/** A row of labelled readings — one result, several facets. */
+{
+    kind: 'metrics';
+    fields: ToolResultField[];
+}
+/** `rows` is a path to an array; each column's `path` is read WITHIN a row. */
+ | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string;
+    empty?: string;
+}
+/** `lines` is a path to an array of strings, drawn as a log tail. */
+ | {
+    kind: 'log';
+    lines: string;
+}
+/** One sentence, templated over the output. */
+ | {
+    kind: 'note';
+    text: string;
+}
+/** The output is drawn somewhere else on the screen already (a pushed component, a side panel). */
+ | {
+    kind: 'elsewhere';
+};
+/**
+ * `GET <base>/tools?agent=*` (and `useToolCatalog({ agent: ALL_AGENTS })`): every tool the actor
+ * reaches through ANY agent, each once — for a surface that shows several agents' conversations.
+ */
+declare const ALL_AGENTS = "*";
+/**
+ * One tool as `GET <base>/tools` reports it: the tools THIS actor may be offered by the chosen agent,
+ * with how each is spoken about. `presentation` is absent for a tool that declared none — a client
+ * then narrates it generically rather than falling back to its name.
+ */
+interface ToolCatalogEntry {
+    /** The wire name tool parts carry (`tool-<name>`) — the key a client looks a call up by. */
+    name: string;
+    kind: ToolKind;
+    presentation?: ToolPresentation;
+}
+
+/** The approver that means "the person the run is acting for" — the thread's own actor. */
+declare const REQUESTER_APPROVER = "requester";
+/** The tool a requirement is asked about. `spec` is absent where this process cannot resolve it. */
+interface ApprovalToolRef {
+    name: string;
+    kind: ToolKind;
+    spec?: ToolSpec;
+}
+/** Where the call is being made. */
+interface ApprovalThreadRef {
+    threadId: string;
+    runId: string;
+    agentName?: string;
+}
+/**
+ * What an action tool call needs before it runs.
+ *
+ *  - `required: false` → the call runs without asking anyone (it is still recorded as an action).
+ *  - `approver` → who may decide: {@link REQUESTER_APPROVER} (the thread's own actor — the default)
+ *    or any other string, which the default {@link ApprovalPolicy.canDecide} reads as a ROLE the
+ *    decider must hold. Streamed on `approval-requested` and persisted on the call.
+ *  - `ttlMs` → how long the request stays open. When it lapses the call settles `expired` and the
+ *    model is told nobody approved it. Absent → it waits indefinitely.
+ */
+interface ApprovalRequirement {
+    required: boolean;
+    approver: string;
+    ttlMs?: number;
+}
+/** A decision about to be taken on a call, as {@link ApprovalPolicy.canDecide} sees it. */
+interface ApprovalDecisionRef {
+    toolCallId: string;
+    /** The approver recorded on the call when it was put to a person. */
+    approver: string;
+    /** The actorRef the run is acting for — the owner of the call's thread. */
+    requesterRef: string;
+}
+/**
+ * Who has to approve an action tool call, and for how long the request stays open.
+ *
+ * Consulted by the LOOP once per `action` call, inside the call's `persist:toolcall` checkpoint — so
+ * a durable run reads the answer back on every replay instead of re-deciding it against a policy
+ * that may have changed while it was parked. Only `action` calls are asked about: a policy cannot
+ * put a `read` behind an approval, and an `ask` (a question set) is always the requester's.
+ */
+interface ApprovalPolicy {
+    requirementFor(tool: ApprovalToolRef, actor: Actor, thread: ApprovalThreadRef): ApprovalRequirement | Promise<ApprovalRequirement>;
+    /**
+     * May `actor` settle this call? Checked by the approve/reject routes before a decision is
+     * signalled. Absent → {@link defaultCanDecide}: the requester approver means the thread's own
+     * actor, anything else is a role the actor must hold. Plug an authz Gate here for abilities.
+     */
+    canDecide?(actor: Actor, decision: ApprovalDecisionRef): boolean | Promise<boolean>;
+}
+/**
+ * The behaviour the lib always had: every `action` call waits on the person who asked, with no
+ * expiry.
+ */
+declare class DefaultApprovalPolicy implements ApprovalPolicy {
+    requirementFor(tool: ApprovalToolRef): ApprovalRequirement;
+}
+/** The default decider rule — see {@link ApprovalPolicy.canDecide}. */
+declare function defaultCanDecide(actor: Actor, decision: ApprovalDecisionRef): boolean;
+/** Resolve whether `actor` may decide, through the policy's own rule when it has one. */
+declare function mayDecideApproval(policy: ApprovalPolicy | undefined, actor: Actor, decision: ApprovalDecisionRef): Promise<boolean>;
+/** The columns a store keeps for one call's approval, however it names them. */
+interface ToolCallApprovalColumns {
+    proposalId?: string | null;
+    confirmation?: ToolConfirmation | null | undefined;
+    toolCallId: string;
+    status: ToolCallStatus;
+    approver: string | null | undefined;
+    expiresAt: string | Date | null | undefined;
+    remember: boolean | null | undefined;
+    executedByRef: string | null | undefined;
+    decidedVia: string | null | undefined;
+    error: string | null | undefined;
+}
+/**
+ * Read a tool-call row back as the {@link ToolCallApproval} a thread carries, or `null` for a call
+ * no policy put to anyone (no approver recorded). Shared by every store so they agree on the
+ * status mapping: a call that ran — or ran and failed — after a decision was APPROVED.
+ */
+declare function toolCallApprovalFromRow(row: ToolCallApprovalColumns): ToolCallApproval | null;
+
+type ClaimedActionApproval = {
+    mode: 'auto';
+} | {
+    mode: 'remembered';
+    approver: string;
+} | {
+    mode: 'ask';
+    approver: string;
+    ttlMs?: number;
+    expiresAt?: string;
+};
+interface ResolveActionProposalApprovalInput {
+    actor: Actor;
+    thread: ApprovalThreadRef;
+    tool: ApprovalToolRef;
+    store: {
+        rememberedApprovals?(threadId: string): Promise<string[]>;
+    };
+    policy?: ApprovalPolicy;
+    clock?: () => number;
+}
+/** Journal this result on the trusted producer before choosing strict proposal preparation. */
+declare function resolveActionProposalApproval(input: ResolveActionProposalApprovalInput): Promise<ClaimedActionApproval>;
+
+/** Renderer support only. Component definitions and authorization remain server-owned. */
+interface UiCapabilities {
+    components: Array<{
+        name: string;
+        version: number;
+    }>;
+}
+declare function validateUiCapabilities(value: unknown): UiCapabilities;
+declare function negotiateCatalog(catalog: Catalog, capabilities?: UiCapabilities): Catalog;
+type PreparedUiEmission = {
+    kind: 'ui';
+    component: string;
+    props: Record<string, unknown>;
+    version: number;
+    fallbackText: string;
+    componentVersions?: Record<string, number>;
+} | {
+    kind: 'text';
+    text: string;
+};
+/** Validate against current trusted definitions before drawing or generating complete text. */
+declare function prepareUiEmission(catalog: Catalog, capabilities: UiCapabilities | undefined, component: string, props: Record<string, unknown>, version?: number): Promise<PreparedUiEmission>;
+
+interface ActionProposalScope {
+    /** Explicit null or string; scope strings have at most 255 UTF-16 code units. */
+    tenantRef: string | null;
+    actorRef: string;
+    threadId: string;
+}
+/** Persisted JSON execution descriptor; identity is resolved fresh from proposal scope. */
+interface ActionProposalExecutionContext {
+    agentName?: string;
+    persona?: string;
+    requestId: string;
+    uiCapabilities?: UiCapabilities;
+    pageContext?: PageContext;
+}
+interface CreateActionProposal extends ActionProposalScope {
+    /** Globally unique deterministic identifier, at most 255 UTF-16 code units. */
+    id: string;
+    originRunId: string;
+    originMessageId: string;
+    originToolCallId: string;
+    toolName: string;
+    /** JSON-serializable immutable snapshot. */
+    input: unknown;
+    /** Original JSON before schema parsing; absence on legacy rows falls back to input. Null is present. */
+    preparationInput?: unknown;
+    /** Original execution address, never requester roles or transport/host handles. */
+    executionContext?: ActionProposalExecutionContext;
+    confirmation: ToolConfirmation;
+    approver: string;
+    /** Milliseconds since epoch; null means no expiry. */
+    expiresAt: number | null;
+    /** Stable across claims and crash recovery; tools must honor this key. */
+    idempotencyKey: string;
+    /** Explicit tool-authored replacement identity; never inferred from model text. */
+    replacementKey?: string;
+}
+type ActionProposalDecision = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
+interface ActionProposalDecisionCommand {
+    decision: 'approved' | 'rejected' | 'expired';
+    actorRef: string;
+    via: string;
+    reason?: string;
+    remember?: boolean;
+}
+interface ActionProposalDecisionAudit extends Omit<ActionProposalDecisionCommand, 'decision'> {
+    at: number;
+    replacementProposalId?: string;
+}
+interface ActionProposalLease {
+    token: string;
+    generation: number;
+    workerId: string;
+    expiresAt: number;
+}
+interface ActionProposalExecution {
+    status: 'queued' | 'executing' | 'succeeded' | 'failed';
+    generation: number;
+    lease: ActionProposalLease | null;
+    result?: unknown;
+    error?: string;
+}
+interface ActionProposal extends CreateActionProposal {
+    decision: ActionProposalDecision;
+    decisionAudit: ActionProposalDecisionAudit | null;
+    /** Embedded durable execution work: created atomically with approval, absent before it. */
+    execution: ActionProposalExecution | null;
+    supersededBy?: string;
+    outcome?: ActionProposalOutcome;
+    outcomeDelivery?: ActionProposalOutcomeDelivery;
+    createdAt: number;
+    updatedAt: number;
+}
+interface CreateActionProposalResult {
+    status: 'created' | 'unchanged' | 'conflict';
+    proposal?: ActionProposal;
+}
+interface ActionProposalMutationResult {
+    status: 'applied' | 'unchanged' | 'conflict' | 'not_found' | 'expired';
+    /** Snapshot observed after the operation; concurrent operations may advance it. */
+    proposal?: ActionProposal;
+}
+interface ClaimActionProposal {
+    workerId: string;
+    leaseMs: number;
+}
+interface ExtendActionProposalLease {
+    token: string;
+    generation: number;
+    leaseMs: number;
+}
+type SettleActionProposal = {
+    token: string;
+    generation: number;
+    ui?: AgentUiComponent[];
+    text?: string;
+} & ({
+    status: 'succeeded';
+    result?: unknown;
+    error?: never;
+} | {
+    status: 'failed';
+    error: string;
+    result?: never;
+});
+interface ListActionProposals {
+    /** Default 100; integer 1..1000. Ties order by UTF-16 lexical logical id. */
+    limit?: number;
+    decision?: ActionProposalDecision;
+    /** Exclusive cursor in the same creation-time / exact logical-id order. */
+    after?: {
+        createdAt: number;
+        id: string;
+    };
+}
+interface ActionProposalStoreOptions {
+    /** Server-configured trusted clock, never a timestamp from a request. */
+    clock?: () => number;
+}
+/**
+ * Independent capability; AgentStore implementations are not required to implement it.
+ * All identifiers are looked up within the complete scope. Creation must compare the original
+ * immutable payload on replay and reject mismatches without disclosing a differently scoped row.
+ * Decisions are first-wins CAS; approving atomically queues durable execution work. At now >=
+ * expiresAt a pending proposal expires and cannot be approved or rejected. An explicit expiry
+ * before that instant conflicts. Duplicate matching decisions are unchanged without replacing
+ * audit data. Lease claims and recovery are atomic and fenced by token AND generation. Settlement
+ * and renewal require a matching, unexpired lease; leaseMs must be a positive safe integer.
+ * Execution recovery preserves the idempotency key (delivery is at least once, not exactly once).
+ */
+interface ActionProposalStore {
+    createActionProposal(input: CreateActionProposal): Promise<CreateActionProposalResult>;
+    getActionProposal(scope: ActionProposalScope, id: string): Promise<ActionProposal | null>;
+    listActionProposals(scope: ActionProposalScope, query?: ListActionProposals): Promise<ActionProposal[]>;
+    decideActionProposal(scope: ActionProposalScope, id: string, command: ActionProposalDecisionCommand): Promise<ActionProposalMutationResult>;
+    claimActionProposal(scope: ActionProposalScope, id: string, command: ClaimActionProposal): Promise<ActionProposalMutationResult>;
+    extendActionProposalLease(scope: ActionProposalScope, id: string, command: ExtendActionProposalLease): Promise<ActionProposalMutationResult>;
+    settleActionProposal(scope: ActionProposalScope, id: string, command: SettleActionProposal): Promise<ActionProposalMutationResult>;
+}
+interface ActionProposalSupersessionStore {
+    createReplacingActionProposal(input: CreateActionProposal): Promise<CreateActionProposalResult>;
+    supersedeActionProposal(scope: ActionProposalScope, id: string, command: {
+        replacementProposalId: string;
+        actorRef: string;
+        via: string;
+    }): Promise<ActionProposalMutationResult>;
+}
+
+interface ActionProposalOutcome extends ActionProposalScope {
+    id: string;
+    proposalId: string;
+    outcomeVersion: 1;
+    originRunId: string;
+    originToolCallId: string;
+    toolName: string;
+    decision: ActionProposalDecision;
+    executionStatus?: 'succeeded' | 'failed';
+    result?: unknown;
+    error?: string;
+    ui: AgentUiComponent[];
+    text?: string;
+    createdAt: number;
+}
+interface ActionProposalOutcomeDelivery {
+    status: 'pending' | 'admitted' | 'discarded';
+    generation: number;
+    lease: ActionProposalLease | null;
+    messageId?: string;
+}
+interface ActionProposalOutcomeLease {
+    outcomeId: string;
+    token: string;
+    generation: number;
+}
+interface ActionProposalOutcomeStore {
+    getThreadActionProposalScope(threadId: string): Promise<ActionProposalScope | null>;
+    claimNextActionProposalOutcome(command: {
+        workerId: string;
+        leaseMs: number;
+    }): Promise<{
+        outcome: ActionProposalOutcome;
+        lease: ActionProposalOutcomeLease;
+    } | null>;
+    admitActionProposalOutcome(command: ActionProposalOutcomeLease): Promise<{
+        status: 'applied' | 'unchanged' | 'busy' | 'conflict' | 'not_found' | 'discarded';
+        messageId?: string;
+    }>;
+}
+
 /**
  * What a store knows about a tool call, read back when its message carries no result for it — see
  * {@link import('./spi/agent-store.js').AgentStore.toolCallOutcomes}.
@@ -119,6 +533,7 @@ interface CreateThreadInput {
     persona?: string;
 }
 interface AppendMessageInput {
+    actionProposalOutcome?: ActionProposalOutcome;
     threadId: string;
     role: StoredMessage['role'];
     content: string;
@@ -148,6 +563,9 @@ interface AppendMessageInput {
     ui?: AgentUiComponent[];
 }
 interface RecordToolCallInput {
+    proposalId?: string;
+    /** Resolved confirmation from the action preflight; overrides presentation templates. */
+    confirmation?: ToolConfirmation;
     toolCallId: string;
     messageId: string;
     toolName: string;
@@ -500,6 +918,7 @@ interface QueuedMessage {
     persona?: string;
     model?: string;
     pageContext?: PageContext;
+    uiCapabilities?: UiCapabilities;
     /**
      * 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.
@@ -538,6 +957,7 @@ interface EnqueueMessageInput {
     persona?: string;
     model?: string;
     pageContext?: PageContext;
+    uiCapabilities?: UiCapabilities;
     interrupt?: boolean;
     /** `'tail'` (default) runs it after everything already waiting; `'head'` runs it next. */
     at?: 'tail' | 'head';
@@ -702,97 +1122,214 @@ interface AgentHistoryWindow {
     summarize?: boolean;
 }
 
-/**
- * How a person-facing surface talks about a tool WITHOUT ever naming it. Declared on the server,
- * beside the tool's input schema, because whoever changes the input is the one who has to re-word
- * the sentence that mentions it — and a client that shipped its own name-to-sentence map would go
- * stale the moment a tool was renamed. A tool name is an identifier, never copy.
- *
- * `running` / `done` (and `confirm.title`, `confirm.detail`, `result.text`) are templates:
- * `{dotted.path}` placeholders are filled from the call's INPUT (or, for `result`, its OUTPUT), so one
- * declaration covers every call the tool will ever receive and replays identically from history.
- * A placeholder with nothing behind it collapses along with the space before it.
- */
-interface ToolPresentation {
-    /** Noun phrase, for counts and headings: "Database query", "Knowledge base". */
-    label: string;
-    /** Present progressive, while the call is in flight: "Reading {bucket}". */
-    running: string;
-    /** Settled, once the output is in: "Read {bucket}". */
-    done: string;
-    /** A key into the client's own glyph map (`database`, `search`, …). Unknown keys fall back to a generic glyph there. */
-    icon?: string;
-    /** One line naming what the tool reaches, for when the activity line is opened. */
-    detail?: string;
-    /** `destructive` earns the warning treatment on an approval prompt. */
-    tone?: ToolPresentationTone;
-    /** What a person is being asked to allow when an `action` call parks for approval. */
-    confirm?: ToolConfirmation;
-    /** How the call's OUTPUT reads as content. */
-    result?: ToolResultView;
-}
-type ToolPresentationTone = 'neutral' | 'destructive';
-interface ToolConfirmation {
-    /** "Delete {count} files?" */
+/** 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;
-    /** The button: "Delete". */
-    verb: string;
-    /** A sentence under the title, when the title alone does not say what changes. */
-    detail?: string;
-}
-/** A value read out of a tool's output by dotted path, with the words to put next to it. */
-interface ToolResultField {
-    path: string;
-    label: 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[];
+
 /**
- * How a tool's output reads as content. Every variant names dotted paths into the output rather
- * than shapes, so a renderer never has to recognise which tool it is drawing: it receives
- * `{ view, output }` and draws it.
+ * 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).
  */
-type ToolResultView = 
-/** A row of labelled readings — one result, several facets. */
-{
-    kind: 'metrics';
-    fields: ToolResultField[];
+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;
+    runId: string;
+    requestId: string;
+    /**
+     * The id of the tool call this invocation serves. Absent where a tool is invoked outside a turn
+     * (the MCP server, a direct `registry.invoke`).
+     */
+    toolCallId?: string;
+    /**
+     * `<runId>:<toolCallId>` — the same value for every execution of THIS call, and for no other.
+     *
+     * A tool's side effect and the checkpoint that records it are two writes. Under the durable
+     * runner a worker that dies between them leaves a call the journal does not know ran, and the
+     * runtime's recovery runs it again; an in-step transient retry (a deadlock, a lock-wait timeout)
+     * re-invokes it too. The library cannot make your write atomic with its journal — so it hands you
+     * the key that makes the second attempt recognisable: pass it to whatever you call as its
+     * idempotency key (a payment provider's `Idempotency-Key`, a unique column on the row you insert,
+     * a workflow's `id`), and a re-execution lands on the first one's result instead of doing it
+     * twice. Stable across replays and across pods: the run id is the run's own, and the call id
+     * comes out of the journaled model step.
+     *
+     * Absent where a tool is invoked outside a turn (the MCP server, a direct `registry.invoke`).
+     */
+    idempotencyKey?: string;
+    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
+    agentName?: string;
+    /** The persona of {@link agentName} the turn runs under, when it runs under one. */
+    persona?: string;
+    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.
+     *
+     * Always present. On a surface with no conversation to push into (the MCP server, a direct
+     * `registry.invoke` without one) it is a no-op that still resolves to an id, so a tool calls
+     * `ctx.emitUi(…)` unconditionally.
+     */
+    emitUi(component: string, props: Record<string, unknown>, options?: EmitUiOptions): Promise<{
+        id: string;
+    }>;
 }
-/** `rows` is a path to an array; each column's `path` is read WITHIN a row. */
- | {
-    kind: 'table';
-    columns: ToolResultField[];
-    rows: string;
-    empty?: string;
+/** When the action state is being checked. */
+interface ToolPreflightOptions {
+    phase: 'prepare' | 'execute';
 }
-/** `lines` is a path to an array of strings, drawn as a log tail. */
- | {
-    kind: 'log';
-    lines: string;
+type ToolPreflightResult<O = unknown> = {
+    status: 'ready';
+    confirmation?: ToolConfirmation;
+} | {
+    status: 'denied';
+    reason: string;
+} | {
+    status: 'completed';
+    output: O;
+};
+/** 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>>;
+    /**
+     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
+     * policy, so a `false` here means the model is never shown the tool rather than being shown one
+     * it will be refused. Omit → always enabled.
+     *
+     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
+     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
+     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
+     * separate question "may THIS actor use it?", and both still run.
+     *
+     * Prefer this over conditionally registering the provider: registration happens while the
+     * `@Module` metadata is built, which in most apps is before configuration is loaded.
+     */
+    isEnabled?(): boolean | Promise<boolean>;
+    /**
+     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
+     *
+     * The three existing gates all answer the question somewhere else: `roles` is static data,
+     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
+     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
+     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
+     * this actor own the base being queried, is the per-user override in the DB set today.
+     *
+     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
+     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
+     */
+    canUse?(actor: Actor): boolean | Promise<boolean>;
+    /**
+     * What the model is told about this tool for THIS turn — a description and/or input schema that
+     * depend on who is asking (a per-tenant component catalog, a per-plan list of options). Called
+     * when the turn's tool list is built, after every gate has passed; whatever it returns replaces
+     * the registered spec's `description` / `inputSchema` in the definition the model sees. Omit, or
+     * return `undefined`, to use the registered spec as is.
+     *
+     * It shapes what the model is SHOWN only: the registry still validates a call against the
+     * registered `inputSchema`, so a tool whose accepted input varies per turn registers a permissive
+     * schema and validates in `execute`.
+     */
+    describe?(scope: ToolDescribeScope): ToolDescription | undefined | Promise<ToolDescription | undefined>;
 }
-/** One sentence, templated over the output. */
- | {
-    kind: 'note';
-    text: string;
+/** Who a turn's tool list is being built for — what {@link ToolHandler.describe} can vary on. */
+interface ToolDescribeScope {
+    uiCapabilities?: UiCapabilities;
+    actor: Actor;
+    /** Absent where the list is built outside a conversation (the MCP server's `tools/list`). */
+    threadId?: string;
+    agentName?: string;
 }
-/** The output is drawn somewhere else on the screen already (a pushed component, a side panel). */
- | {
-    kind: 'elsewhere';
-};
-/**
- * `GET <base>/tools?agent=*` (and `useToolCatalog({ agent: ALL_AGENTS })`): every tool the actor
- * reaches through ANY agent, each once — for a surface that shows several agents' conversations.
- */
-declare const ALL_AGENTS = "*";
-/**
- * One tool as `GET <base>/tools` reports it: the tools THIS actor may be offered by the chosen agent,
- * with how each is spoken about. `presentation` is absent for a tool that declared none — a client
- * then narrates it generically rather than falling back to its name.
- */
-interface ToolCatalogEntry {
-    /** The wire name tool parts carry (`tool-<name>`) — the key a client looks a call up by. */
-    name: string;
-    kind: ToolKind;
-    presentation?: ToolPresentation;
+/** A per-turn override of a tool's model-facing definition ({@link ToolHandler.describe}). */
+interface ToolDescription {
+    /** False removes this tool from the current model-facing catalog. */
+    available?: boolean;
+    description?: string;
+    inputSchema?: StandardSchemaV1;
+}
+/** Metadata recorded with a pushed UI component. */
+interface EmitUiOptions {
+    id?: string;
+    version?: number;
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
 }
 
 /**
@@ -911,6 +1448,8 @@ interface DetachedDelivery {
  *             remedy is the read-back that lets them delete it.
  */
 interface ToolSpec {
+    /** Explicit domain identity for pending-only replacement; evaluated on approved normalized input. */
+    replacementKey?: string | ((input: unknown, ctx: AiToolCtx) => string | undefined | Promise<string | undefined>);
     name: string;
     kind: ToolKind;
     description: string;
@@ -966,8 +1505,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;
 }
@@ -980,6 +1520,19 @@ interface ToolDefinition {
 }
 /** A tool call the model asked for during a turn. */
 interface ToolCallRequest {
+    actionApproval?: ClaimedActionApproval;
+    prepared?: {
+        preparationInput: unknown;
+        input: unknown;
+        preflight: ToolPreflightResult;
+        replacementKey?: string;
+    };
+    /** Trusted action preparation from the dispatched model worker, journaled with its turn.
+     * Model-provider supplied values are overwritten by the worker. Absent on legacy turns. */
+    preflight?: ToolPreflightResult | {
+        status: 'failed';
+        error: string;
+    };
     id: string;
     name: string;
     input: unknown;
@@ -1149,6 +1702,7 @@ interface PromptContext {
     /** The selected agent's name. */
     agentName: string;
     pageContext?: PageContext;
+    uiCapabilities?: UiCapabilities;
     /**
      * The persona this turn runs under, when it runs under one — so an agent's own `@SystemPrompt`
      * (or a contributor) can vary by persona without the persona carrying a prompt of its own.
@@ -1236,6 +1790,7 @@ interface AgentRunInput {
     /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
     attachments?: MessageAttachment[];
     pageContext?: PageContext;
+    uiCapabilities?: UiCapabilities;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
     /** Which named agent runs this turn. Omitted → the default/single agent. */
@@ -1411,6 +1966,7 @@ interface ThreadSummary {
     persona?: string | null;
 }
 interface StoredMessage {
+    actionProposalOutcome?: ActionProposalOutcome;
     id: string;
     role: MessageRole;
     content: string;
@@ -1476,6 +2032,14 @@ interface MessageFeedback {
 type ToolCallApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
 /** The persisted approval metadata of one action tool call. See {@link StoredMessage.approvals}. */
 interface ToolCallApproval {
+    target?: {
+        kind: 'proposal';
+        proposalId: string;
+        threadId?: string;
+    };
+    proposalId?: string;
+    /** Resolved confirmation from the action preflight; overrides presentation templates. */
+    confirmation?: ToolConfirmation;
     toolCallId: string;
     /** Who may decide: `'requester'` (the thread's own actor) or a role name. */
     approver: string;
@@ -1500,7 +2064,7 @@ interface ThreadDetail extends ThreadSummary {
      */
     queue?: ChatQueueState;
 }
-type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
+type ToolCallStatus = 'proposed' | 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
 /** An approval request lapsed before anyone decided; the tool never ran. */
  | 'expired';
 /**
@@ -1508,6 +2072,9 @@ type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejec
  * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
  */
 interface LlmStepEnvelope {
+    actionApprovalMode?: 'blocking' | 'independent';
+    /** Full invocation identity for action preparation at the worker. Optional for old envelopes. */
+    preflightContext?: ToolStepCtx;
     /** Undefined = default agent (same semantics as {@link AgentRunInput.agentName}). */
     agentName?: string;
     system: string;
@@ -1547,6 +2114,7 @@ interface ToolStepCtx {
     /** The persona the turn runs under ({@link AiToolCtx.persona}). */
     persona?: string;
     pageContext?: PageContext;
+    uiCapabilities?: UiCapabilities;
 }
 /** Serializable input for a dispatched tool-execution step. */
 interface ToolStepEnvelope {
@@ -1839,6 +2407,10 @@ interface AgentUiComponent {
     props: Record<string, unknown>;
     /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
     version?: number;
+    /** Validated readable fallback retained for clients without this renderer. */
+    fallbackText?: string;
+    /** Trusted schema versions for every component in a persisted tree. */
+    componentVersions?: Record<string, 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
@@ -1851,6 +2423,12 @@ interface AgentUiComponent {
  * settled through the tool-call approve/reject routes, by its `toolCallId`.
  */
 interface AgentApprovalRequest {
+    target?: {
+        kind: 'proposal';
+        proposalId: string;
+    };
+    /** Resolved confirmation from the action preflight; overrides presentation templates. */
+    confirmation?: ToolConfirmation;
     /** The tool call awaiting the decision — the `id` of a call already announced on this stream. */
     id: string;
     /**
@@ -2066,4 +2644,4 @@ type AgentStreamErrorCode = 'quota_exceeded' | 'output_rejected' | 'structured_o
 /** A model call ended without producing anything. */
  | 'model_no_output' | 'run_failed';
 
-export { ASK_TOOL_NAME as $, type AgentStreamEvent as A, type ToolCallApprovalState as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type EnqueueMessageInput as F, type QueuedMessage as G, type HumanReply as H, type QueuedMessagePatch as I, type QueuePause as J, type AppendMessageInput as K, type LlmStepEnvelope as L, type ModelMessage as M, type ToolResult as N, type MessageFeedback as O, type Persona as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type RecordToolCallInput as V, type ToolCallOutcome as W, type UpdateToolCallInput as X, type RecordUsageInput as Y, ALL_AGENTS as Z, ASK_TOOL_DESCRIPTION as _, type Actor as a, releaseThreadRun as a$, type AgentApprovalRequest as a0, type AgentApprovalSettlement as a1, type AgentAttachmentConfig as a2, type AgentCatalogEntry as a3, type AgentClientConfig as a4, type AgentHistoryWindow as a5, type AgentStreamErrorCode as a6, type AskToolInput as a7, type ChatQueueState as a8, DEFAULT_INTAKE_PREAMBLE as a9, type ThreadTurnReader as aA, type ToolCallApprovalStatus as aB, type ToolCatalogEntry as aC, type ToolConfirmation as aD, type ToolPresentationTone as aE, type ToolResultField as aF, type ToolResultView as aG, type ToolStepCtx as aH, type ToolTransientRetryNumbers as aI, type ToolTransientRetryOptions as aJ, type TurnPersona as aK, UNFINISHED_TOOL_CALL as aL, type UsagePurpose as aM, askInputSchema as aN, askToolDefinition as aO, danglingToolCallIds as aP, decodeStreamEvent as aQ, encodeStreamEvent as aR, invokeWithTransientRetry as aS, isChatQueueStore as aT, isTransientToolError as aU, isTypedQuestion as aV, normalizeElicitationReply as aW, questionOptions as aX, queuedMessageView as aY, readElicitationInput as aZ, readElicitationQuestions as a_, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aa, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as ab, ELICITATION_INPUT_TYPES as ac, type ElicitationInput as ad, type ElicitationInputType as ae, type ElicitationOption as af, type ElicitationOutcome as ag, type ElicitationQuestion as ah, type ElicitationReply as ai, type ElicitationResult as aj, type HistoryPolicyContext as ak, type HistorySelection as al, type HistorySummary as am, type InvokeWithTransientRetryOptions as an, MAX_ASK_QUESTIONS as ao, type MessageFeedbackValue as ap, type MessageRole as aq, type PersonaRef as ar, type PromptContext as as, type QueuePauseReason as at, type QueuedMessageView as au, type QuotaView as av, RUN_ENDED_BEFORE_TOOL_CALL as aw, type RecordRunEndInput as ax, type ThreadTurnPage as ay, type ThreadTurnQuery as az, type ToolPresentation as b, renderElicitationAnswers as b0, resolveElicitation as b1, resolveToolTransientRetryNumbers as b2, settleDanglingToolCalls as b3, settleElicitation as b4, validateElicitationAnswer as b5, validateElicitationValue as b6, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AgentRunInput as g, type MessageAttachment as h, type ToolKind as i, type ToolCallStatus as j, type ToolCallApproval as k, type AgentDefinition as l, type PersonaCatalogEntry as m, type HistoryPolicy as n, type PageContext as o, type AgentStore as p, type AgentDelegation as q, type PromptBuilder as r, type PromptContributor as s, type ToolTransientRetrySetting as t, type AgentIntake as u, type Decision as v, type ToolStepEnvelope as w, type CreateThreadInput as x, type ThreadSummary as y, type ThreadDetail 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, ELICITATION_INPUT_TYPES 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 AgentStreamErrorCode as aP, type ApprovalDecisionRef as aQ, type ApprovalRequirement as aR, type ApprovalThreadRef as aS, type ApprovalToolRef as aT, type AskToolInput as aU, type ChatQueueState as aV, type ClaimedActionApproval as aW, DEFAULT_INTAKE_PREAMBLE as aX, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aY, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as aZ, DefaultApprovalPolicy 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, resolveToolTransientRetryNumbers as b$, type ElicitationInput as b0, type ElicitationInputType as b1, type ElicitationOption as b2, type ElicitationOutcome as b3, type ElicitationQuestion as b4, type ElicitationReply as b5, type ElicitationResult as b6, type EmitUiOptions as b7, type HistoryPolicyContext as b8, type HistorySelection as b9, type ToolResultView as bA, type ToolStepCtx as bB, type ToolTransientRetryNumbers as bC, type ToolTransientRetryOptions as bD, type TurnPersona as bE, UNFINISHED_TOOL_CALL as bF, type UsagePurpose as bG, askInputSchema as bH, askToolDefinition as bI, danglingToolCallIds as bJ, decodeStreamEvent as bK, defaultCanDecide as bL, encodeStreamEvent as bM, invokeWithTransientRetry as bN, isChatQueueStore as bO, isTransientToolError as bP, isTypedQuestion as bQ, mayDecideApproval as bR, normalizeElicitationReply as bS, questionOptions as bT, queuedMessageView as bU, readElicitationInput as bV, readElicitationQuestions as bW, releaseThreadRun as bX, renderElicitationAnswers as bY, resolveActionProposalApproval as bZ, resolveElicitation as b_, type HistorySummary as ba, type InvokeWithTransientRetryOptions as bb, MAX_ASK_QUESTIONS as bc, type MessageFeedbackValue as bd, type MessageRole as be, type PersonaRef as bf, type PromptContext as bg, type QueuePauseReason as bh, type QueuedMessageView as bi, type QuotaView as bj, REQUESTER_APPROVER as bk, RUN_ENDED_BEFORE_TOOL_CALL as bl, type RecordRunEndInput as bm, type ResolveActionProposalApprovalInput as bn, type ThreadTurnPage as bo, type ThreadTurnQuery as bp, type ThreadTurnReader as bq, type ToolCallApproval as br, type ToolCallApprovalColumns as bs, type ToolCallApprovalStatus as bt, type ToolCatalogEntry as bu, type ToolDescription as bv, type ToolKind as bw, type ToolPreflightOptions as bx, type ToolPresentationTone as by, type ToolResultField as bz, type ToolPresentation as c, settleDanglingToolCalls as c0, settleElicitation as c1, toolCallApprovalFromRow as c2, validateElicitationAnswer as c3, validateElicitationValue as c4, 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 };