@dudousxd/nestjs-agent-core 0.39.0 → 0.41.0

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, a as Actor, A as AgentStreamEvent, T as ToolSpec, Q as QuotaState, g as AgentRunInput, H as HumanReply, h as MessageAttachment, i as ToolKind, j as ToolCallStatus, k as ToolCallApproval, l as AgentDefinition, P as Persona, m as PersonaCatalogEntry, n as HistoryPolicy, o as PageContext, p as AgentStore, q as AgentDelegation, D as DetachedDelivery, r as PromptBuilder, s as PromptContributor, t as ToolTransientRetrySetting, u as AgentIntake, v as Decision, E as ElicitationRequest, L as LlmStepEnvelope, w as ToolStepEnvelope, C as ChatQueueStore, x as CreateThreadInput, y as ThreadSummary, z as ThreadDetail, B as ToolCallApprovalState, U as UpdateThreadInput, R as RecordRunStartInput, F as EnqueueMessageInput, G as QueuedMessage, I as QueuedMessagePatch, J as QueuePause, K as AppendMessageInput, S as StoredMessage, N as ToolResult, O as MessageFeedback, V as RecordToolCallInput, W as ToolCallOutcome, X as UpdateToolCallInput, Y as RecordUsageInput } from './stream-events-CbVEowYb.js';
-export { Z as ALL_AGENTS, _ as ASK_TOOL_DESCRIPTION, $ as ASK_TOOL_NAME, a0 as AgentApprovalRequest, a1 as AgentApprovalSettlement, a2 as AgentAttachmentConfig, a3 as AgentCatalogEntry, a4 as AgentClientConfig, a5 as AgentHistoryWindow, a6 as AgentStreamErrorCode, a7 as AskToolInput, a8 as ChatQueueState, a9 as DEFAULT_INTAKE_PREAMBLE, aa as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, ab as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, ac as ELICITATION_INPUT_TYPES, ad as ElicitationInput, ae as ElicitationInputType, af as ElicitationOption, ag as ElicitationOutcome, ah as ElicitationQuestion, ai as ElicitationReply, aj as ElicitationResult, ak as HistoryPolicyContext, al as HistorySelection, am as HistorySummary, an as InvokeWithTransientRetryOptions, ao as MAX_ASK_QUESTIONS, ap as MessageFeedbackValue, aq as MessageRole, ar as PersonaRef, as as PromptContext, at as QueuePauseReason, au as QueuedMessageView, av as QuotaView, aw as RUN_ENDED_BEFORE_TOOL_CALL, ax as RecordRunEndInput, ay as ThreadTurnPage, az as ThreadTurnQuery, aA as ThreadTurnReader, aB as ToolCallApprovalStatus, aC as ToolCatalogEntry, aD as ToolConfirmation, b as ToolPresentation, aE as ToolPresentationTone, aF as ToolResultField, aG as ToolResultView, aH as ToolStepCtx, aI as ToolTransientRetryNumbers, aJ as ToolTransientRetryOptions, aK as TurnPersona, aL as UNFINISHED_TOOL_CALL, aM as UsagePurpose, aN as askInputSchema, aO as askToolDefinition, aP as danglingToolCallIds, aQ as decodeStreamEvent, aR as encodeStreamEvent, aS as invokeWithTransientRetry, aT as isChatQueueStore, aU as isTransientToolError, aV as isTypedQuestion, aW as normalizeElicitationReply, aX as questionOptions, aY as queuedMessageView, aZ as readElicitationInput, a_ as readElicitationQuestions, a$ as releaseThreadRun, b0 as renderElicitationAnswers, b1 as resolveElicitation, b2 as resolveToolTransientRetryNumbers, b3 as settleDanglingToolCalls, b4 as settleElicitation, b5 as validateElicitationAnswer, b6 as validateElicitationValue } from './stream-events-CbVEowYb.js';
-import { A as AiToolCtx, T as ToolHandler, a as ToolDescribeScope } from './tool-_iq4xRyk.js';
-export { b as ToolDescription } from './tool-_iq4xRyk.js';
+import { M as ModelMessage, q as ToolDefinition, r as ToolCallRequest, u as MessageUsage, w as AgentUiComponent, a as Actor, x as AiToolCtx, A as AgentStreamEvent, T as ToolSpec, Q as QuotaState, y as AgentRunInput, H as HumanReply, z as MessageAttachment, B as ActionProposalMutationResult, D as ActionProposal, E as ActionProposalExecution, F as ActionProposalOutcomeDelivery, b as ToolHandler, G as AgentDefinition, I as Persona, J as PersonaCatalogEntry, K as HistoryPolicy, L as PageContext, N as AgentStore, O as AgentDelegation, R as DetachedDelivery, S as ToolDescribeScope, V as ToolPreflightResult, W as ApprovalPolicy, X as PromptBuilder, Y as PromptContributor, Z as ToolTransientRetrySetting, _ as AgentIntake, $ as Decision, a0 as ElicitationRequest, a1 as LlmStepEnvelope, a2 as ToolStepEnvelope, a3 as ClaimActionProposal, a4 as ActionProposalStore, a5 as ActionProposalStoreOptions, a6 as CreateActionProposal, a7 as CreateActionProposalResult, a8 as ActionProposalScope, a9 as ListActionProposals, aa as ActionProposalDecisionCommand, ab as ExtendActionProposalLease, ac as SettleActionProposal, ad as ActionProposalOutcome, ae as ActionProposalOutcomeLease, af as ToolCallStatus, ag as ChatQueueStore, ah as ActionProposalOutcomeStore, ai as CreateThreadInput, aj as ThreadSummary, ak as ThreadDetail, al as ToolCallApprovalState, am as UpdateThreadInput, an as RecordRunStartInput, ao as EnqueueMessageInput, ap as QueuedMessage, aq as QueuedMessagePatch, ar as QueuePause, as as AppendMessageInput, at as StoredMessage, au as ToolResult, av as MessageFeedback, aw as RecordToolCallInput, ax as ToolCallOutcome, ay as UpdateToolCallInput, az as RecordUsageInput, aA as ToolConfirmation, aB as ActionProposalDecision, aC as ActionProposalSupersessionStore } from './stream-events-BGKLD6RX.js';
+export { aD as ALL_AGENTS, aE as ASK_TOOL_DESCRIPTION, aF as ASK_TOOL_NAME, aG as ActionProposalDecisionAudit, aH as ActionProposalExecutionContext, aI as ActionProposalLease, aJ as AgentApprovalRequest, aK as AgentApprovalSettlement, aL as AgentAttachmentConfig, aM as AgentCatalogEntry, aN as AgentClientConfig, aO as AgentHistoryWindow, aP as AgentStreamErrorCode, aQ as ApprovalDecisionRef, aR as ApprovalRequirement, aS as ApprovalThreadRef, aT as ApprovalToolRef, aU as AskToolInput, aV as ChatQueueState, aW as ClaimedActionApproval, aX as DEFAULT_INTAKE_PREAMBLE, aY as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, aZ as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, a_ as DefaultApprovalPolicy, a$ as ELICITATION_INPUT_TYPES, b0 as ElicitationInput, b1 as ElicitationInputType, b2 as ElicitationOption, b3 as ElicitationOutcome, b4 as ElicitationQuestion, b5 as ElicitationReply, b6 as ElicitationResult, b7 as EmitUiOptions, b8 as HistoryPolicyContext, b9 as HistorySelection, ba as HistorySummary, bb as InvokeWithTransientRetryOptions, bc as MAX_ASK_QUESTIONS, bd as MessageFeedbackValue, be as MessageRole, bf as PersonaRef, bg as PromptContext, bh as QueuePauseReason, bi as QueuedMessageView, bj as QuotaView, bk as REQUESTER_APPROVER, bl as RUN_ENDED_BEFORE_TOOL_CALL, bm as RecordRunEndInput, bn as ResolveActionProposalApprovalInput, bo as ThreadTurnPage, bp as ThreadTurnQuery, bq as ThreadTurnReader, br as ToolCallApproval, bs as ToolCallApprovalColumns, bt as ToolCallApprovalStatus, bu as ToolCatalogEntry, bv as ToolDescription, bw as ToolKind, bx as ToolPreflightOptions, c as ToolPresentation, by as ToolPresentationTone, bz as ToolResultField, bA as ToolResultView, bB as ToolStepCtx, bC as ToolTransientRetryNumbers, bD as ToolTransientRetryOptions, bE as TurnPersona, bF as UNFINISHED_TOOL_CALL, bG as UsagePurpose, bH as askInputSchema, bI as askToolDefinition, bJ as danglingToolCallIds, bK as decodeStreamEvent, bL as defaultCanDecide, bM as encodeStreamEvent, bN as invokeWithTransientRetry, bO as isChatQueueStore, bP as isTransientToolError, bQ as isTypedQuestion, bR as mayDecideApproval, bS as normalizeElicitationReply, bT as questionOptions, bU as queuedMessageView, bV as readElicitationInput, bW as readElicitationQuestions, bX as releaseThreadRun, bY as renderElicitationAnswers, bZ as resolveActionProposalApproval, b_ as resolveElicitation, b$ as resolveToolTransientRetryNumbers, c0 as settleDanglingToolCalls, c1 as settleElicitation, c2 as toolCallApprovalFromRow, c3 as validateElicitationAnswer, c4 as validateElicitationValue } from './stream-events-BGKLD6RX.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-Bp5XmF6V.js';
-export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-Bp5XmF6V.js';
+import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-ByDr5POu.js';
+export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-ByDr5POu.js';
+import { a as Catalog } from './catalog-BKS3Yxo6.js';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
 /**
@@ -30,6 +29,11 @@ declare const AGENT_DURABLE_RUNNER: unique symbol;
 declare const AGENT_SINK: unique symbol;
 declare const AGENT_MODEL: unique symbol;
 declare const AGENT_ROLES_POLICY: unique symbol;
+/**
+ * @deprecated Nothing binds or injects this token since the quota rework (#230): `AgentModule`
+ * enforces and reports the budget through {@link AGENT_QUOTA_PROVIDER}, configured with
+ * `AgentModule.forRoot({ quota })`. Inject `AGENT_QUOTA_PROVIDER` instead. Removed in the next major.
+ */
 declare const AGENT_QUOTA_STORE: unique symbol;
 declare const AGENT_TOOL_REGISTRY: unique symbol;
 declare const AGENT_REGISTRY: unique symbol;
@@ -335,11 +339,15 @@ declare function observeTurnFrames(writer: SinkWriter, now?: () => number): Obse
 declare function withTurnFrames<T extends ModelTurnResult>(result: T, frames: TurnFrameSummary): T;
 
 /** The tool step's journaled result: the bare output, or the output plus the components it pushed. */
-declare function wrapToolStepOutput(output: unknown, ui: readonly AgentUiComponent[]): unknown;
+declare function wrapToolStepOutput(output: unknown, ui: readonly AgentUiComponent[], text?: string): unknown;
+/** Carry domain refusal across a remote step without losing its type in error serialization. */
+declare function wrapToolPreflightDenied(reason: string): unknown;
 /** Read a tool step's result back — either shape. */
 declare function unwrapToolStepOutput(raw: unknown): {
     output: unknown;
     ui: AgentUiComponent[];
+    preflightDenied?: string;
+    text?: string;
 };
 type EmitUi = AiToolCtx['emitUi'];
 /**
@@ -366,6 +374,8 @@ interface UiCollector {
 declare function createUiCollector(toolCallId: string, write?: (event: AgentStreamEvent) => void | Promise<void>): UiCollector;
 /** Merge component lists: first-seen order, the last props for each id. */
 declare function mergeUi(...lists: readonly (readonly AgentUiComponent[] | undefined)[]): AgentUiComponent[];
+/** Escape code units native PostgreSQL/MySQL TEXT cannot store; retain ordinary prose and emoji. */
+declare function escapeUnsafeToolUiText(text: string): string;
 
 /**
  * Decides whether an actor may invoke a tool. The default impl checks the actor's role
@@ -444,7 +454,7 @@ interface QuotaQuery {
 }
 /**
  * The actor's budget across windows — the read behind `GET <base>/quota` and, when the host binds
- * one (`AgentModule.forRoot({ quotaProvider })`), the gate a send passes: a report with `blocked`
+ * one (`AgentModule.forRoot({ quota })`), the gate a send passes: a report with `blocked`
  * refuses the turn with `429` before it starts.
  *
  * The default reads the usage ledger (`LedgerQuotaProvider` in `@dudousxd/nestjs-agent`); a host
@@ -1131,12 +1141,48 @@ interface AttachmentStagingDescription {
     upload?: 'multipart' | 'resumable';
 }
 
+/**
+ * What leaves the server about a proposal — the routes, a text decision's answer, AG-UI, the approval
+ * port. The stored row minus what only the worker and the store may hold: the execution and
+ * delivery leases (whose token lets a holder settle the work), the idempotency key the tool's side
+ * effect is keyed on, and the execution address (the original preparation input and the request's
+ * context).
+ */
+interface ActionProposalView extends Omit<ActionProposal, 'execution' | 'outcomeDelivery' | 'idempotencyKey' | 'preparationInput' | 'executionContext'> {
+    execution: Omit<ActionProposalExecution, 'lease'> | null;
+    outcomeDelivery?: Omit<ActionProposalOutcomeDelivery, 'lease'>;
+}
+/** {@link ActionProposalMutationResult} with its proposal as an {@link ActionProposalView}. */
+interface ActionProposalMutationView extends Omit<ActionProposalMutationResult, 'proposal'> {
+    proposal?: ActionProposalView;
+}
+/** The public view of a stored proposal. See {@link ActionProposalView}. */
+declare function toActionProposalView(proposal: ActionProposal): ActionProposalView;
+/** The public view of a mutation's answer. See {@link ActionProposalView}. */
+declare function toActionProposalMutationView(result: ActionProposalMutationResult): ActionProposalMutationView;
+
 /**
  * Console-side HITL decisions. Implemented by the agent runtime (the nestjs package binds it to
  * the same signal path chat approvals use); the dashboard injects it OPTIONALLY — absent = the
  * approvals inbox renders read-only.
  */
 interface AgentApprovalPort {
+    approveActionProposal?(actor: Actor, target: {
+        kind: 'proposal';
+        threadId: string;
+        proposalId: string;
+    }, opts?: {
+        remember?: boolean;
+        decidedVia?: string;
+    }): Promise<ActionProposalMutationView>;
+    rejectActionProposal?(actor: Actor, target: {
+        kind: 'proposal';
+        threadId: string;
+        proposalId: string;
+    }, opts?: {
+        reason?: string;
+        decidedVia?: string;
+    }): Promise<ActionProposalMutationView>;
     /**
      * `remember` approves later calls of the same tool in the same thread; `decidedVia` names the
      * surface the decision came through (`'console'`, `'slack'`, …) and is persisted with the call.
@@ -1153,89 +1199,6 @@ interface AgentApprovalPort {
     }): Promise<void>;
 }
 
-/** 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 {
-    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;
-
 /**
  * The pure aggregation core shared by every {@link import('../spi/governance-queries.js').AgentGovernanceQueries}
  * adapter (MikroORM, Drizzle, in-memory). An adapter's only job is the DB-specific row fetch; the
@@ -2553,6 +2516,17 @@ declare class ToolInputInvalidError extends Error {
     readonly issues: readonly StandardSchemaV1.Issue[];
     constructor(toolName: string, issues: readonly StandardSchemaV1.Issue[]);
 }
+/** An action refused by its current domain state, rather than by a person. */
+declare class ToolPreflightDeniedError extends Error {
+    readonly toolName: string;
+    readonly reason: string;
+    constructor(toolName: string, reason: string);
+}
+/** Trusted preparation or a fresh schema parse changed the approved JSON input. */
+declare class ToolInputDriftError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
 /**
  * Holds every registered tool and gates invocation.
  *
@@ -2563,6 +2537,10 @@ declare class ToolInputInvalidError extends Error {
 declare class ToolRegistry {
     private readonly entries;
     register(spec: ToolSpec, handler: ToolHandler): void;
+    /** Whether a successful preflight shortcut has UI to journal. */
+    hasPresentation(name: string): boolean;
+    /** Present an already authorized successful domain result without executing its action again. */
+    presentOutput(name: string, output: unknown, ctx: AiToolCtx): Promise<void>;
     has(name: string): boolean;
     /**
      * Give a name back, and report whether it was held. For an importer that registered tools on
@@ -2601,6 +2579,11 @@ declare class ToolRegistry {
      * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
      */
     invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy, options?: InvokeOptions): Promise<unknown>;
+    /** Authorize and validate without executing. The caller journals this result before approval. */
+    prepare(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy, options?: PrepareOptions): Promise<ToolPreflightResult>;
+    /** Expose the single schema parse; snapshotInput opts proposal callers into immutable JSON. */
+    prepareValidated(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy, options?: PrepareOptions): Promise<ToolPreparationResult>;
+    private validated;
 }
 /** Per-call narrowing for {@link ToolRegistry.invoke}. */
 interface InvokeOptions {
@@ -2609,6 +2592,16 @@ interface InvokeOptions {
      * roles policy and `canUse`. Undefined → no such check (every caller predating personas).
      */
     allowedTools?: readonly string[];
+    /** Trusted normalized JSON input. Own-property presence requires comparison even if undefined. */
+    approvedInput?: unknown;
+}
+interface PrepareOptions extends InvokeOptions {
+    /** Preserve a detached normalized JSON snapshot and refuse mutation by the prepare hook. */
+    snapshotInput?: boolean;
+}
+interface ToolPreparationResult {
+    input: unknown;
+    preflight: ToolPreflightResult;
 }
 /**
  * Default gate: a tool that names `roles` is callable by an actor holding one of them; a tool that
@@ -2617,6 +2610,10 @@ interface InvokeOptions {
  * visitor included, when no resolver is configured); restrict with `@AiTool({ roles })` per tool,
  * `AgentModule.forRoot({ defaultRoles })` module-wide, or a `rolesPolicy` of your own. `action`
  * tools still park on approval either way.
+ *
+ * A tool gated by an `ability` and naming no `roles` is refused: this policy cannot evaluate an
+ * ability, and falling through to the open default would hand the tool to everyone. Bind an
+ * ability-aware policy (`AgentAuthzModule`) to reach it — or give the tool `roles` as well.
  */
 declare class DefaultRolesPolicy implements RolesPolicy {
     readonly defaultRoles: string[];
@@ -2658,7 +2655,27 @@ declare class ClosedRolesPolicy extends DefaultRolesPolicy {
  */
 declare function closeEmptyRoles(inner: RolesPolicy): RolesPolicy;
 
+type ActionApprovalMode = 'blocking' | 'independent';
+type ActionProposalTarget = {
+    kind: 'proposal';
+    proposalId: string;
+};
+interface ActionProposalReceipt {
+    proposalId: string;
+    status: 'pending';
+    executed: false;
+}
+declare function actionProposalReceipt(proposalId: string): ActionProposalReceipt;
+
+type ResolveToolUiCatalog = (scope: ToolDescribeScope) => Catalog | Promise<Catalog>;
+interface NegotiatedUiCollector extends UiCollector {
+    text(): string;
+}
+declare function createNegotiatedUiCollector(toolCallId: string, scope: ToolDescribeScope, resolveCatalog?: ResolveToolUiCatalog, write?: (event: AgentStreamEvent) => void | Promise<void>): NegotiatedUiCollector;
+
 interface AgentLoopDeps<TOutput = unknown> {
+    actionApprovalMode?: ActionApprovalMode;
+    resolveUiCatalog?: ResolveToolUiCatalog;
     model: ModelProvider;
     store: AgentStore;
     registry: ToolRegistry;
@@ -3188,10 +3205,22 @@ interface AgentToolCallEvent {
     status: string;
     durationMs?: number;
 }
+/**
+ * A turn refused for budget. Published by the send gate (`429`) and the message queue when a
+ * `QuotaProvider` reports `blocked`, and by the loop's own per-day `QuotaStore` gate. The figures
+ * are the exhausted window's: a window that does not count tokens (a USD-only spend cap) carries no
+ * token figures, never a made-up `0`.
+ */
 interface AgentQuotaExceeded {
     actorId: string;
-    usedTokens: number;
-    limitTokens: number;
+    /** The window that ran out. Absent from the loop's per-day `QuotaStore` gate. */
+    period?: QuotaPeriod;
+    /** The provider's words for the block, when it gave some. */
+    reason?: string;
+    usedTokens?: number;
+    limitTokens?: number;
+    usedUsd?: number;
+    limitUsd?: number;
 }
 interface AgentRunFinished {
     runId: string;
@@ -3399,6 +3428,51 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
+/** Privileged worker-only discovery; never expose this unscoped capability on public routes. */
+interface ActionProposalWorkerStore {
+    /** Claim one queued or expired-lease action across scopes; null means no claim was won. */
+    claimNextActionProposal(command: ClaimActionProposal): Promise<ActionProposal | null>;
+    /** Expire at most limit (1..1000) due pending proposals using the store's trusted clock. */
+    expireActionProposals(command: {
+        limit: number;
+    }): Promise<number>;
+}
+/** SQL upgrade capability. Run bounded batches after additive DDL and before starting workers. */
+interface ActionProposalDiscoveryIndexStore {
+    backfillActionProposalDiscoveryIndex(command: {
+        limit: number;
+    }): Promise<number>;
+}
+
+/** Reference single-process implementation; durable adapters use the same transitions under CAS. */
+declare class InMemoryActionProposalStore implements ActionProposalStore, ActionProposalWorkerStore {
+    protected readonly rows: Map<string, ActionProposal>;
+    protected readonly clock: () => number;
+    constructor(options?: ActionProposalStoreOptions);
+    createActionProposal(input: CreateActionProposal): Promise<CreateActionProposalResult>;
+    getActionProposal(scope: ActionProposalScope, id: string): Promise<ActionProposal | null>;
+    listActionProposals(scope: ActionProposalScope, query?: ListActionProposals): Promise<ActionProposal[]>;
+    private mutate;
+    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>;
+    claimNextActionProposal(command: ClaimActionProposal): Promise<ActionProposal | null>;
+    expireActionProposals(command: {
+        limit: number;
+    }): Promise<number>;
+    claimNextActionProposalOutcome(command: ClaimActionProposal): Promise<{
+        outcome: ActionProposalOutcome;
+        lease: ActionProposalOutcomeLease;
+    } | null>;
+    createReplacingActionProposal(input: CreateActionProposal): Promise<CreateActionProposalResult>;
+    supersedeActionProposal(scope: ActionProposalScope, id: string, command: {
+        replacementProposalId: string;
+        actorRef: string;
+        via: string;
+    }): Promise<ActionProposalMutationResult>;
+}
+
 /** A recorded usage row exposed to the governance read-model (input/output split + thread/day). */
 interface GovernanceUsageRow {
     actorRef: string;
@@ -3484,7 +3558,7 @@ interface GovernanceRunRow {
     parentRunId?: string;
 }
 /** A fully in-memory `AgentStore` for tests and the offline demo. */
-declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
+declare class InMemoryAgentStore extends InMemoryActionProposalStore implements AgentStore, ChatQueueStore, ActionProposalOutcomeStore {
     private readonly threads;
     /** Each thread's waiting messages, in run order. */
     private readonly queues;
@@ -3553,6 +3627,8 @@ declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
     queuePause(threadId: string): Promise<QueuePause | null>;
     setQueuePause(threadId: string, pause: QueuePause | null): Promise<void>;
     private findQueued;
+    getThreadActionProposalScope(threadId: string): Promise<ActionProposalScope | null>;
+    admitActionProposalOutcome(command: ActionProposalOutcomeLease): ReturnType<ActionProposalOutcomeStore['admitActionProposalOutcome']>;
     appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
     setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
     setMessageUi(messageId: string, ui: AgentUiComponent[]): Promise<void>;
@@ -3901,7 +3977,11 @@ interface StreamFrameTable {
     remove(runIds: readonly string[]): Promise<void>;
     /** Runs whose LAST row was written before `cutoff` (epoch-ms). */
     lapsedRuns(cutoff: number): Promise<string[]>;
-    /** Is this error a lost race for a `(run_id, seq)` — and nothing else (a missing table, a dead connection)? */
+    /**
+     * Is this error a lost race for a `(run_id, seq)` — a duplicate key, or the database rolling this
+     * writer back as a deadlock victim (InnoDB's way of settling two concurrent `INSERT … SELECT`) —
+     * and nothing else (a missing table, a dead connection)?
+     */
     isUniqueViolation(error: unknown): boolean;
 }
 interface SqlTokenStreamSinkOptions {
@@ -4001,4 +4081,216 @@ declare class SqlTokenStreamSink implements TokenStreamSink {
     private purgeInBackground;
 }
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_CONFIRM_TOKEN_STORE, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStartOptions, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, CONFIRM_JSON_SCHEMA_PROPERTIES, ChatQueueStore, ClosedRolesPolicy, type ConfirmFields, type ConfirmTokenClaim, ConfirmTokenError, type ConfirmTokenStore, type ConfirmTokenSubject, type ConfirmedTool, type ConfirmedToolDone, type ConfirmedToolMessages, type ConfirmedToolOptions, type ConfirmedToolOutcome, type ConfirmedToolPreview, type ConfirmedToolResult, type ConfirmedToolSteps, type CostUsage, CreateThreadInput, type CurrentModelPrice, DEFAULT_CONFIRM_TTL_MS, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type EmptyRoles, EnqueueMessageInput, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, InMemoryConfirmTokenStore, type IncrementalGate, InputProcessor, type InvokeOptions, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogLock, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, Persona, type PersonaAlias, PersonaCatalogEntry, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QueuePause, QueuedMessage, QueuedMessagePatch, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWarning, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, RUN_FAILED_MESSAGE, RUN_NOT_ACTIVE_CODE, RUN_NOT_ACTIVE_MESSAGE, RUN_NO_LONGER_RUNNING, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RolesPolicyOptions, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SCHEMA_EXTENSION, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type SchemaExtension, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettleDeadRunInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, SqlTokenStreamSink, type SqlTokenStreamSinkOptions, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StreamFrameRow, type StreamFrameTable, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, ToolCallApprovalState, ToolCallOutcome, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, UpdateThreadInput, UpdateToolCallInput, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, canonicalJson, closeEmptyRoles, compositeSkillProvider, confirmTokenExpiry, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, defineConfirmedTool, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, findPersona, gateFollowUps, gateTail, hashConfirmToken, intersectAllowLists, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, personaCatalogEntry, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolvePersonaAlias, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, schemaExtensionOf, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, signConfirmToken, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, toolCallApprovalFromRow, toolCallContext, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, verifyConfirmToken, windowHistory, withAskTool, withConfirmFields, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+declare function validateActionProposalCreation(input: CreateActionProposal): void;
+declare function validateActionProposalListQuery(query?: ListActionProposals): number;
+/** Canonical JSON snapshots keep replay equality independent of object key insertion order. */
+declare function canonicalActionProposalJson(value: unknown): string;
+declare function snapshotActionProposal<T>(value: T): T;
+declare function actionProposalScopeMatches(row: ActionProposalScope, scope: ActionProposalScope): boolean;
+declare function initialActionProposal(input: CreateActionProposal, now: number): ActionProposal;
+declare function actionProposalCreationMatches(row: ActionProposal, input: CreateActionProposal): boolean;
+declare function transitionActionProposalDecision(row: ActionProposal, command: ActionProposalDecisionCommand, now: number): ActionProposalMutationResult;
+declare function transitionActionProposalClaim(row: ActionProposal, command: ClaimActionProposal, now: number, token: string): ActionProposalMutationResult;
+declare function transitionActionProposalLease(row: ActionProposal, command: ExtendActionProposalLease, now: number): ActionProposalMutationResult;
+declare function transitionActionProposalSettlement(row: ActionProposal, command: SettleActionProposal, now: number): ActionProposalMutationResult;
+/** Caller must obtain the replacement through the same full scope and persistence authority. */
+declare function transitionActionProposalSupersession(row: ActionProposal, replacement: ActionProposal, command: {
+    replacementProposalId: string;
+    actorRef: string;
+    via: string;
+}, now: number): ActionProposalMutationResult;
+
+/** Trusted producer path: retain the original JSON and the exact data shown for approval. */
+declare function prepareActionProposal(registry: ToolRegistry, name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy, options?: InvokeOptions): Promise<{
+    preparationInput: unknown;
+    input: unknown;
+    preflight: {
+        status: "ready";
+        confirmation?: ToolConfirmation;
+    } | {
+        status: "denied";
+        reason: string;
+    } | {
+        status: "completed";
+        output: unknown;
+    };
+    replacementKey?: string;
+}>;
+
+declare function validateActionProposalWorkerClaim(command: ClaimActionProposal, now: number): void;
+declare function validateActionProposalExpiryBatch(command: {
+    limit: number;
+}, now: number): void;
+declare function validateActionProposalDiscoveryIndexBatch(command: {
+    limit: number;
+}): void;
+
+/** Resolves current server authority; persisted role snapshots are never execution authority. */
+interface BackgroundActorResolver {
+    resolve(ref: {
+        actorRef: string;
+        tenantRef: string | null;
+    }): Promise<Actor | null>;
+}
+
+declare function attachActionProposalOutcome(row: ActionProposal, now: number, ui?: AgentUiComponent[], text?: string): ActionProposal;
+declare function claimActionProposalOutcome(row: ActionProposal, command: {
+    workerId: string;
+    leaseMs: number;
+}, now: number, token: string): ActionProposal | null;
+declare function actionProposalOutcomeFenceValid(row: ActionProposal, command: ActionProposalOutcomeLease, now: number): boolean;
+declare function actionProposalOutcomeScope(outcome: ActionProposalOutcome): ActionProposalScope;
+declare function actionProposalOutcomeText(outcome: ActionProposalOutcome): string;
+
+interface TextActionProposalCandidate {
+    id: string;
+    decision: ActionProposalDecision;
+}
+type TextActionProposalResolution = {
+    status: 'unmatched';
+} | {
+    status: 'ambiguous';
+    proposalIds: string[];
+} | {
+    status: 'decision';
+    proposalId: string;
+    decision: 'approved' | 'rejected';
+    remember: boolean;
+};
+/**
+ * Recognizes complete, explicit decision messages. This grants no authority: callers must
+ * resolve the authenticated actor and use the normal scoped decision service with via=text.
+ * Never feed model output here or consume an unmatched message as an approval.
+ */
+declare function resolveTextActionProposalDecision(text: string, proposals: readonly TextActionProposalCandidate[], vocabulary?: TextActionProposalVocabulary): TextActionProposalResolution;
+type TextActionProposalCommand = {
+    status: 'unmatched';
+} | {
+    status: 'command';
+    decision: 'approved' | 'rejected';
+    remember: boolean;
+    proposalId?: string;
+};
+/**
+ * The words a whole chat message must consist of to decide a proposal by text. Matched
+ * case-insensitively, as the complete message (an optional trailing `.`/`!`, an optional `#ID`).
+ */
+interface TextActionProposalVocabulary {
+    /** Approve, e.g. `sim`, `yes`. */
+    approve: readonly string[];
+    /** Reject, e.g. `não`, `no`. */
+    reject: readonly string[];
+    /** The phrase after an approve word that also approves later calls of the tool in this thread. */
+    remember: readonly string[];
+}
+/**
+ * English. Portuguese ships as {@link ptBrActionProposalText}; any other language through
+ * `AgentModule.forRoot({ actionProposalText })`.
+ */
+declare const DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY: TextActionProposalVocabulary;
+/** What the agent answers to a text decision. Every field has an English default. */
+interface TextActionProposalReplies {
+    approved: string;
+    rejected: string;
+    expired: string;
+    /** The proposal could not change (already decided by someone else, superseded, …). */
+    unchanged: string;
+    /** More than one pending proposal could be meant: ask for the `#ID`. */
+    ambiguous(proposalIds: readonly string[]): string;
+    /** Too many pending proposals to pick one without an explicit `#ID`. */
+    tooMany: string;
+}
+declare const DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES: TextActionProposalReplies;
+/** `AgentModule.forRoot({ actionProposalText })`: either part replaces the default it names. */
+interface TextActionProposalConfig {
+    vocabulary?: Partial<TextActionProposalVocabulary>;
+    replies?: Partial<TextActionProposalReplies>;
+}
+/** The reply to a decision the store answered with `result`. */
+declare function textActionProposalReply(result: Pick<ActionProposalMutationResult, 'status'> & {
+    proposal?: {
+        decision: ActionProposalDecision;
+    };
+}, decision: 'approved' | 'rejected', replies?: TextActionProposalReplies): string;
+/** Parse exact consent syntax only. Authentication and target lookup remain the caller's responsibility. */
+declare function parseTextActionProposalCommand(text: string, vocabulary?: TextActionProposalVocabulary): TextActionProposalCommand;
+/**
+ * Brazilian Portuguese text decisions — `AgentModule.forRoot({ actionProposalText: ptBrActionProposalText })`.
+ * Commands in Portuguese (English ones still work), replies in Portuguese.
+ */
+declare const ptBrActionProposalText: Required<TextActionProposalConfig>;
+
+interface ActionProposalExecutionDeps {
+    registry: ToolRegistry;
+    rolesPolicy: RolesPolicy;
+    allowedTools?: string[];
+    host?: unknown;
+    resolveUiCatalog?: ResolveToolUiCatalog;
+}
+interface ActionProposalExecutorOptions {
+    resolver: BackgroundActorResolver;
+    /** Resolve exact recorded agent/persona against current configuration; throw if it disappeared. */
+    resolveExecution(proposal: ActionProposal, actor: Actor): Promise<ActionProposalExecutionDeps>;
+}
+type ActionProposalExecutionResult = {
+    status: 'succeeded';
+    result?: unknown;
+    ui: AgentUiComponent[];
+    text?: string;
+} | {
+    status: 'failed';
+    error: string;
+    ui: AgentUiComponent[];
+    text?: string;
+};
+declare class ActionProposalExecutor {
+    private readonly options;
+    constructor(options: ActionProposalExecutorOptions);
+    execute(proposal: ActionProposal): Promise<ActionProposalExecutionResult>;
+}
+
+interface ActionProposalWorkerOptions {
+    store: ActionProposalStore & ActionProposalWorkerStore & ActionProposalOutcomeStore;
+    executor: ActionProposalExecutor;
+    workerId: string;
+    pollIntervalMs?: number;
+    leaseMs?: number;
+    maxConcurrency?: number;
+    onError?(error: unknown): void;
+    onSettled?(proposal: ActionProposal): Promise<void>;
+}
+declare class ActionProposalWorker {
+    private readonly options;
+    private readonly leaseMs;
+    private readonly pollIntervalMs;
+    private readonly maxConcurrency;
+    private timer?;
+    private stopped;
+    private readonly renewals;
+    private active;
+    constructor(options: ActionProposalWorkerOptions);
+    start(): void;
+    stop(): Promise<void>;
+    runOnce(): Promise<void>;
+    private tick;
+    private execute;
+}
+
+type ActionProposalRuntimeStore = AgentStore & ActionProposalStore & ActionProposalWorkerStore & ActionProposalOutcomeStore & ActionProposalSupersessionStore;
+declare function assertIndependentActionCapabilities(store: AgentStore, resolver: BackgroundActorResolver | undefined): asserts store is ActionProposalRuntimeStore;
+
+interface FunctionalTool<I = unknown, O = unknown> {
+    spec: ToolSpec;
+    handler: ToolHandler<I, O>;
+}
+type FunctionalToolDefinition<I, O> = Omit<ToolSpec, 'inputSchema' | 'kind'> & {
+    input: StandardSchemaV1<unknown, I>;
+    kind?: ToolSpec['kind'];
+} & ToolHandler<I, O>;
+/** Framework-independent authoring; every method keeps the author's object as its receiver. */
+declare function createFunctionalTool<I, O>(definition: FunctionalToolDefinition<I, O>): FunctionalTool<I, O>;
+
+/** Presentation failures must never cause a successful side effect to be retried. */
+declare function emitToolPresentations<I, O>(handler: ToolHandler<I, O>, output: O, ctx: AiToolCtx, toolName: string): Promise<void>;
+
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_CONFIRM_TOKEN_STORE, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, type ActionApprovalMode, ActionProposal, ActionProposalDecision, ActionProposalDecisionCommand, type ActionProposalDiscoveryIndexStore, ActionProposalExecution, type ActionProposalExecutionDeps, type ActionProposalExecutionResult, ActionProposalExecutor, type ActionProposalExecutorOptions, ActionProposalMutationResult, type ActionProposalMutationView, ActionProposalOutcome, ActionProposalOutcomeDelivery, ActionProposalOutcomeLease, ActionProposalOutcomeStore, type ActionProposalReceipt, type ActionProposalRuntimeStore, ActionProposalScope, ActionProposalStore, ActionProposalStoreOptions, ActionProposalSupersessionStore, type ActionProposalTarget, type ActionProposalView, ActionProposalWorker, type ActionProposalWorkerOptions, type ActionProposalWorkerStore, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStartOptions, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, AppendMessageInput, ApprovalPolicy, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BackgroundActorResolver, type BufferedModelTurnResult, type BuildMemoryBlockInput, CONFIRM_JSON_SCHEMA_PROPERTIES, ChatQueueStore, ClaimActionProposal, ClosedRolesPolicy, type ConfirmFields, type ConfirmTokenClaim, ConfirmTokenError, type ConfirmTokenStore, type ConfirmTokenSubject, type ConfirmedTool, type ConfirmedToolDone, type ConfirmedToolMessages, type ConfirmedToolOptions, type ConfirmedToolOutcome, type ConfirmedToolPreview, type ConfirmedToolResult, type ConfirmedToolSteps, type CostUsage, CreateActionProposal, CreateActionProposalResult, CreateThreadInput, type CurrentModelPrice, DEFAULT_CONFIRM_TTL_MS, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES, DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY, Decision, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type EmptyRoles, EnqueueMessageInput, ExtendActionProposalLease, type ForgetMemoryInput, type FrameBuffer, type FunctionalTool, type FunctionalToolDefinition, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryActionProposalStore, InMemoryAgentStore, InMemoryConfirmTokenStore, type IncrementalGate, InputProcessor, type InvokeOptions, ListActionProposals, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogLock, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type NegotiatedUiCollector, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, Persona, type PersonaAlias, PersonaCatalogEntry, type PrepareOptions, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QueuePause, QueuedMessage, QueuedMessagePatch, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWarning, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, RUN_FAILED_MESSAGE, RUN_NOT_ACTIVE_CODE, RUN_NOT_ACTIVE_MESSAGE, RUN_NO_LONGER_RUNNING, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolveToolUiCatalog, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RolesPolicyOptions, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SCHEMA_EXTENSION, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type SchemaExtension, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, SettleActionProposal, type SettleDeadRunInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, SqlTokenStreamSink, type SqlTokenStreamSinkOptions, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StreamFrameRow, type StreamFrameTable, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type TextActionProposalCandidate, type TextActionProposalCommand, type TextActionProposalConfig, type TextActionProposalReplies, type TextActionProposalResolution, type TextActionProposalVocabulary, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApprovalState, ToolCallOutcome, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolConfirmation, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputDriftError, ToolInputInvalidError, type ToolKindDeps, ToolNotFoundError, ToolPreflightDeniedError, ToolPreflightResult, type ToolPreparationResult, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, UpdateThreadInput, UpdateToolCallInput, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actionProposalCreationMatches, actionProposalOutcomeFenceValid, actionProposalOutcomeScope, actionProposalOutcomeText, actionProposalReceipt, actionProposalScopeMatches, actorScope, agentDiagnosticKey, agentFailureCode, assertIndependentActionCapabilities, attachActionProposalOutcome, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, canonicalActionProposalJson, canonicalJson, claimActionProposalOutcome, closeEmptyRoles, compositeSkillProvider, confirmTokenExpiry, createFrameBuffer, createFunctionalTool, createIncrementalGate, createNegotiatedUiCollector, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultScopeResolver, defineConfirmedTool, detachedDelivered, detachedStarted, detachedUnsettled, emitToolPresentations, escapeUnsafeToolUiText, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, findPersona, gateFollowUps, gateTail, hashConfirmToken, initialActionProposal, intersectAllowLists, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, parseTextActionProposalCommand, personaCatalogEntry, prepareActionProposal, ptBrActionProposalText, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolvePersonaAlias, resolveSkillCatalog, resolveTextActionProposalDecision, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, schemaExtensionOf, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, signConfirmToken, skillInputSchema, skillToolDefinition, skillWriteVerdict, snapshotActionProposal, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, textActionProposalReply, toActionProposalMutationView, toActionProposalView, toolCallContext, traceLlmTurn, traceToolExecution, transitionActionProposalClaim, transitionActionProposalDecision, transitionActionProposalLease, transitionActionProposalSettlement, transitionActionProposalSupersession, truncateDetailContent, unwrapToolStepOutput, validateActionProposalCreation, validateActionProposalDiscoveryIndexBatch, validateActionProposalExpiryBatch, validateActionProposalListQuery, validateActionProposalWorkerClaim, validateStructured, verifyConfirmToken, windowHistory, withAskTool, withConfirmFields, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolPreflightDenied, wrapToolStepOutput, writeMemory };