@dudousxd/nestjs-agent-core 0.39.0 → 0.40.0

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

@@ -1,4 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { a as Catalog } from './catalog-CrzetM3_.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';
@@ -703,96 +1123,145 @@ interface AgentHistoryWindow {
 }
 
 /**
- * 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.
+ * 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 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;
+interface AiToolCtx {
+    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;
+    }>;
 }
-/**
- * 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[];
+/** When the action state is being checked. */
+interface ToolPreflightOptions {
+    phase: 'prepare' | 'execute';
 }
-/** `rows` is a path to an array; each column's `path` is read WITHIN a row. */
- | {
-    kind: 'table';
-    columns: ToolResultField[];
-    rows: string;
-    empty?: 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>;
+    /** 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>;
 }
-/** `lines` is a path to an array of strings, drawn as a log tail. */
- | {
-    kind: 'log';
-    lines: 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;
 }
-/** One sentence, templated over the output. */
- | {
-    kind: 'note';
-    text: string;
+/** 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;
 }
-/** 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;
+/** Metadata recorded with a pushed UI component. */
+interface EmitUiOptions {
+    id?: string;
+    version?: number;
+    fallbackText?: string;
+    componentVersions?: Record<string, number>;
 }
 
 /**
@@ -911,6 +1380,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;
@@ -980,6 +1451,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 +1633,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 +1721,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 +1897,7 @@ interface ThreadSummary {
     persona?: string | null;
 }
 interface StoredMessage {
+    actionProposalOutcome?: ActionProposalOutcome;
     id: string;
     role: MessageRole;
     content: string;
@@ -1476,6 +1963,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 +1995,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 +2003,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 +2045,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 +2338,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 +2354,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 +2575,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 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 };