@dudousxd/nestjs-agent-core 0.35.0 → 0.37.0

package/dist/index.d.ts

@@ -82,6 +82,12 @@ declare const AGENT_MEMORY: unique symbol;
  * lazily by the bound {@link AGENT_SKILLS} provider — discovery runs after DI has built it.
  */
 declare const AGENT_SKILL_SOURCES: unique symbol;
+/**
+ * The `ConfirmTokenStore` that makes a `defineConfirmedTool` confirmation single use. Bound by the
+ * store modules (`DrizzleAgentStoreModule`, `MikroOrmAgentStoreModule`); inject it into the factory
+ * that builds the tool (`provideAgentTool(factory, [AGENT_CONFIRM_TOKEN_STORE])`).
+ */
+declare const AGENT_CONFIRM_TOKEN_STORE: unique symbol;
 
 /**
  * The "data plane": live token transport, decoupled from the durable control plane.
@@ -2572,10 +2578,44 @@ declare class ToolRegistry {
  * tools still park on approval either way.
  */
 declare class DefaultRolesPolicy implements RolesPolicy {
-    private readonly defaultRoles;
-    constructor(defaultRoles?: string[]);
+    readonly defaultRoles: string[];
+    /** What an empty roles list means here — see {@link EmptyRoles}. */
+    readonly emptyRoles: EmptyRoles;
+    constructor(defaultRoles?: string[], options?: RolesPolicyOptions);
     can(actor: Actor, tool: ToolSpec): boolean;
 }
+/**
+ * What an empty roles list means to {@link DefaultRolesPolicy}: `'allow'` (the default) — no
+ * restriction; `'deny'` — nobody.
+ *
+ * The open default is what makes a one-line `AgentModule.forRoot({ model })` a working chat. It is
+ * also why an app that used `[]` to DENY — a `roles` computed from permissions that can come out
+ * empty, `defaultRoles: []` on a multi-tenant MCP surface — reaches everyone instead, silently.
+ * `'deny'` keeps such an app closed.
+ */
+type EmptyRoles = 'allow' | 'deny';
+interface RolesPolicyOptions {
+    /** What an empty roles list means. Default `'allow'`. */
+    emptyRoles?: EmptyRoles;
+}
+/**
+ * The closed gate — {@link DefaultRolesPolicy} with `emptyRoles: 'deny'`: the actor needs a role the
+ * tool declares (else one of the default roles). A tool with no `roles` and no default roles, or with
+ * an explicitly empty list, reaches nobody. What `AgentModule.forRoot({ emptyRoles: 'deny' })` binds.
+ */
+declare class ClosedRolesPolicy extends DefaultRolesPolicy {
+    constructor(defaultRoles?: string[]);
+}
+/**
+ * Close a policy you did not build: a tool whose roles come out empty — declared `[]`, or undeclared
+ * with no default roles to fall back on — reaches nobody; anything else is the inner policy's call.
+ *
+ * The default roles are read off a {@link DefaultRolesPolicy}; any other inner policy keeps its own
+ * defaults to itself, so for it an undeclared list counts as empty. A tool gated by `ability` has
+ * nothing to do with roles and is always left to the inner policy. What the MCP server's
+ * `emptyRoles: 'deny'` wraps the agent's shared policy in.
+ */
+declare function closeEmptyRoles(inner: RolesPolicy): RolesPolicy;
 
 interface AgentLoopDeps<TOutput = unknown> {
     model: ModelProvider;
@@ -3528,4 +3568,251 @@ declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
     private toSummary;
 }
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_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, ChatQueueStore, type CostUsage, CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, 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, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, 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, 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 RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type 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, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type 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, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, toolCallApprovalFromRow, toolCallContext, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+/** One confirmation being spent — what {@link ConfirmTokenStore.claim} records. */
+interface ConfirmTokenClaim {
+    /** SHA-256 (hex) of the token. The token itself is never stored. */
+    hash: string;
+    /** `ctx.actor.id` of the confirming actor. */
+    actorRef: string;
+    /** The tool the token was issued for. */
+    tool: string;
+    /** Epoch-ms the token stops being valid — after it the mark is dead weight and can be purged. */
+    expiresAt: number;
+}
+/**
+ * Makes a confirm token single use (see `defineConfirmedTool`). A signed token is stateless, so on
+ * its own it stays valid until it expires: a double tap, a network retry or a model repeating the
+ * call would commit twice inside that window. The store remembers which tokens were spent.
+ *
+ * Only the token's hash, the actor and the tool name are kept — never an argument or a value.
+ */
+interface ConfirmTokenStore {
+    /**
+     * Spend the token. `true` = this caller holds it and may commit; `false` = it was already spent.
+     * MUST be atomic: of two concurrent claims for one hash, exactly one gets `true`.
+     */
+    claim(input: ConfirmTokenClaim): Promise<boolean>;
+    /** Give the token back — the commit failed after the claim, so the caller may try again. */
+    release(hash: string): Promise<void>;
+    /** Drop the marks of tokens that expired before `now` (epoch-ms, default the clock). Returns how many. */
+    purgeExpired?(now?: number): Promise<number>;
+}
+
+/** How long a preview stays confirmable unless the tool says otherwise. */
+declare const DEFAULT_CONFIRM_TTL_MS: number;
+/** What a confirm token is bound to. Change any of it and the token stops matching. */
+interface ConfirmTokenSubject {
+    /** The tool's name. */
+    tool: string;
+    /** `ctx.actor.id`. */
+    actorId: string;
+    /** `ctx.actor.tenantRef`; absent and `''` sign the same. */
+    tenantRef?: string;
+    /** The call's arguments, WITHOUT `confirm` / `confirmToken`. */
+    args: unknown;
+}
+/**
+ * JSON with object keys sorted at every depth, so two argument objects that differ only in key
+ * order produce the same text. `undefined` properties are dropped (as `JSON.stringify` does); a
+ * bare `undefined` and an `undefined` array element are `null`.
+ */
+declare function canonicalJson(value: unknown): string;
+/**
+ * Issue a confirm token: `<expiresAt>.<signature>`, an HMAC-SHA256 (keyed by `secret`) over the tool,
+ * the actor, the tenant, the expiry and the canonical arguments. Stateless — nothing is stored — and
+ * useless for another actor, tenant, tool or argument, or after `expiresAt` (epoch-ms).
+ */
+declare function signConfirmToken(subject: ConfirmTokenSubject, options: {
+    secret: string;
+    expiresAt: number;
+}): string;
+/** The expiry (epoch-ms) a token carries, or `undefined` for a malformed one. Not a verification. */
+declare function confirmTokenExpiry(token: string): number | undefined;
+/** Was this token issued for exactly this subject, with this secret, and is it still valid at `now`? */
+declare function verifyConfirmToken(token: string | null | undefined, subject: ConfirmTokenSubject, options: {
+    secret: string;
+    now?: number;
+}): boolean;
+/** SHA-256 (hex) of a token — what a {@link ConfirmTokenStore} keys on, so the token is never stored. */
+declare function hashConfirmToken(token: string): string;
+/**
+ * A single-process {@link ConfirmTokenStore}: tests, scripts, and a deployment that runs ONE replica.
+ * With more than one, a token spent on replica A is still fresh on replica B — use the Drizzle or
+ * MikroORM store (`AGENT_CONFIRM_TOKEN_STORE`, bound by their modules).
+ * Expired marks are dropped lazily, on the next claim.
+ */
+declare class InMemoryConfirmTokenStore implements ConfirmTokenStore {
+    private readonly claims;
+    claim(input: ConfirmTokenClaim): Promise<boolean>;
+    release(hash: string): Promise<void>;
+    purgeExpired(now?: number): Promise<number>;
+    /** How many tokens are currently marked as spent. */
+    get size(): number;
+}
+
+/** The two fields {@link defineConfirmedTool} adds to a tool's input. */
+interface ConfirmFields {
+    /** `true` to commit; absent (or `false`) to preview. */
+    confirm?: boolean;
+    /** The `confirmToken` the preview returned. */
+    confirmToken?: string;
+}
+/** The words a confirmed tool says to the model. Each has an English default. */
+interface ConfirmedToolMessages {
+    /** Sent with every preview: how to confirm. `{minutes}` is replaced with the token's lifetime. */
+    confirm?: string;
+    /** Thrown for a missing, tampered, mismatched or expired token. */
+    invalid?: string;
+    /** Thrown for a token that already committed. */
+    used?: string;
+}
+/** Thrown by a confirmed tool that refused a confirmation. Nothing was written. */
+declare class ConfirmTokenError extends Error {
+    /** `invalid`: missing, tampered, mismatched or expired. `used`: it already committed once. */
+    readonly reason: 'invalid' | 'used';
+    constructor(
+    /** `invalid`: missing, tampered, mismatched or expired. `used`: it already committed once. */
+    reason: 'invalid' | 'used', message: string);
+}
+/** What {@link defineConfirmedTool} takes: the usual spec fields (no `kind`), plus the gate's own. */
+interface ConfirmedToolOptions extends Omit<ToolSpec, 'kind' | 'inputSchema' | 'targetAgent' | 'detached' | 'terminal'> {
+    /** The app's own input schema. `confirm` / `confirmToken` are added by {@link withConfirmFields}. */
+    input: StandardSchemaV1;
+    /**
+     * The HMAC key the tokens are signed with — the app's secret (`ConfigService.getOrThrow(...)`), or
+     * one of its own. A function is read on every call. Required: there is no default, and an empty
+     * one throws.
+     */
+    secret: string | (() => string);
+    /** How long a preview stays confirmable. Default 15 minutes. */
+    ttlMs?: number;
+    /**
+     * Makes a token single use. WITHOUT a store a token commits as many times as it is sent until it
+     * expires — a retry or a repeated call writes twice. The store modules bind one to
+     * `AGENT_CONFIRM_TOKEN_STORE`; `InMemoryConfirmTokenStore` is for one replica.
+     */
+    store?: ConfirmTokenStore;
+    messages?: ConfirmedToolMessages;
+}
+/** What a step reports: a sentence for the model to relay, and the structured detail behind it. */
+interface ConfirmedToolOutcome {
+    summary: string;
+    data?: unknown;
+}
+/** The three steps of a confirmed write. */
+interface ConfirmedToolSteps<Args, Prepared> {
+    /**
+     * Resolve and validate everything the write needs, applying the SAME rules the commit relies on.
+     * Throw to refuse. Writes nothing. Runs for the preview AND again for the confirmation — state may
+     * have changed in between — and a refusal here does not spend the token.
+     */
+    prepare(args: Args, ctx: AiToolCtx): Promise<Prepared> | Prepared;
+    /** What is about to happen. Writes nothing. */
+    preview(prepared: Prepared, ctx: AiToolCtx): Promise<ConfirmedToolOutcome> | ConfirmedToolOutcome;
+    /** Write, and say what was written. A throw gives the token back. */
+    commit(prepared: Prepared, ctx: AiToolCtx): Promise<ConfirmedToolOutcome> | ConfirmedToolOutcome;
+}
+/** A confirmed tool's answer to a call without `confirm`. */
+interface ConfirmedToolPreview {
+    status: 'preview';
+    summary: string;
+    data?: unknown;
+    confirmToken: string;
+    /** ISO-8601 instant the token stops working. */
+    expiresAt: string;
+    /** Instructions for the model: show the preview, then call again with the token. */
+    confirm: string;
+}
+/** A confirmed tool's answer to a confirmation that committed. */
+interface ConfirmedToolDone {
+    status: 'done';
+    summary: string;
+    data?: unknown;
+}
+type ConfirmedToolResult = ConfirmedToolPreview | ConfirmedToolDone;
+/** The JSON Schema of {@link ConfirmFields}, merged into the schema the model is shown. */
+declare const CONFIRM_JSON_SCHEMA_PROPERTIES: {
+    readonly confirm: {
+        readonly type: "boolean";
+        readonly description: "Omit to get a preview (nothing is written). Send true, with confirmToken, to commit.";
+    };
+    readonly confirmToken: {
+        readonly type: "string";
+        readonly description: "The confirmToken the preview returned. Required when confirm is true.";
+    };
+};
+/**
+ * Marks a schema that is ANOTHER schema plus a few JSON Schema properties. A converter that knows the
+ * inner schema better than the wrapper can (a Zod 3 schema has no Standard JSON Schema extension, so
+ * only the AI SDK's or the MCP SDK's own converter can describe it) converts `base` and adds
+ * `properties`. `@dudousxd/nestjs-agent-ai-sdk` and `-mcp-server` both read it.
+ */
+declare const SCHEMA_EXTENSION: unique symbol;
+interface SchemaExtension {
+    base: StandardSchemaV1;
+    properties: Record<string, unknown>;
+}
+/** The {@link SchemaExtension} a schema carries, if any. */
+declare function schemaExtensionOf(schema: StandardSchemaV1): SchemaExtension | undefined;
+/**
+ * Wrap a tool's input schema so it also accepts {@link ConfirmFields}, without the app declaring
+ * them. `validate` takes the two fields off, checks them itself, hands the REST to the app's schema
+ * (so a strict schema never sees a key it did not declare) and puts them back on the validated value.
+ *
+ * The wrapper always carries the Standard JSON Schema extension: the app schema's own JSON Schema
+ * plus the two properties. A schema without the extension (Zod 3, a bare Standard Schema) degrades
+ * there to a permissive object that still declares the two fields — but the wrapper also carries a
+ * {@link SchemaExtension}, so the AI SDK adapter and the MCP server convert a Zod 3 schema with their
+ * own converters and show the model its real shape. `validate` stays the authority either way.
+ */
+declare function withConfirmFields<Schema extends StandardSchemaV1>(schema: Schema): StandardSchemaV1<StandardSchemaV1.InferInput<Schema> & ConfirmFields, StandardSchemaV1.InferOutput<Schema> & ConfirmFields>;
+/**
+ * A write with a human gate that lives INSIDE the tool: preview first, commit on confirmation.
+ *
+ * - Called without `confirm`: runs `prepare`, writes nothing, and returns the `preview` with a signed
+ *   `confirmToken`.
+ * - Called again with the SAME arguments, `confirm: true` and that token: runs `prepare` again, then
+ *   `commit`.
+ *
+ * The token is an HMAC over the tool, `ctx.actor.id`, `ctx.actor.tenantRef`, the expiry and the
+ * canonical arguments, so it cannot be replayed by another actor, in another tenant, on another
+ * tool or with a changed argument. With a `store` it is also single use: it is claimed right before
+ * `commit` (a refusal in `prepare` does not spend it) and released if `commit` throws.
+ *
+ * Registered as `kind: 'read'` on purpose. An `action` parks on the loop's HITL approval, which an
+ * MCP caller cannot answer — `AgentMcpServerModule` keeps `action` tools off the surface, and MCP clients
+ * without elicitation have no other channel. The gate being in the handler is what lets the same
+ * tool serve the chat loop and MCP; the user sees the preview because the model has to relay it to
+ * get a token it can confirm with.
+ *
+ * ```ts
+ * provideAgentTool(
+ *   (store: ConfirmTokenStore, config: ConfigService, orders: OrdersService) =>
+ *     defineConfirmedTool(
+ *       { name: 'refund_order', description: '...', input: z.object({ orderId: z.string() }),
+ *         secret: () => config.getOrThrow('CONFIRM_SECRET'), store },
+ *       {
+ *         prepare: ({ orderId }, ctx) => orders.loadRefundable(orderId, ctx.actor),
+ *         preview: (order) => ({ summary: `Refund ${order.total} to ${order.customer}?`, data: order }),
+ *         commit: async (order) => ({ summary: 'Refunded.', data: await orders.refund(order) }),
+ *       },
+ *     ),
+ *   [AGENT_CONFIRM_TOKEN_STORE, ConfigService, OrdersService],
+ * );
+ * ```
+ *
+ * `input` is the app's own schema: `confirm` and `confirmToken` are added by
+ * {@link withConfirmFields}, and `prepare` receives the arguments without them.
+ */
+declare function defineConfirmedTool<Args = unknown, Prepared = unknown>(options: ConfirmedToolOptions, steps: ConfirmedToolSteps<Args, Prepared>): ConfirmedTool;
+/**
+ * What {@link defineConfirmedTool} returns: a functional tool (`{ spec, handler }`) — pass it to
+ * `AgentModule.forRoot({ tools })`, or build it in `provideAgentTool(factory, inject)` when it
+ * needs injected services (the confirm-token store, the secret from `ConfigService`).
+ */
+interface ConfirmedTool {
+    spec: ToolSpec;
+    handler: ToolHandler;
+}
+
+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 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, 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, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type 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, gateFollowUps, gateTail, hashConfirmToken, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, 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 };