@dudousxd/nestjs-agent-core 0.36.0 → 0.38.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.
@@ -101,6 +107,13 @@ interface SinkWriter {
      * — so the transport can surface a typed failure frame instead of leaking it as assistant text.
      */
     fail(error: StreamError): void | Promise<void>;
+    /**
+     * OPTIONAL: write out anything this writer is still holding back, without ending the stream. Only
+     * a sink that gathers frames before writing them (the SQL sink coalesces text) has anything to do
+     * here; a delegated run's child writer calls it where it would have ended the stream, so nothing
+     * of the delegate's is still held back when its parent — possibly on another replica — writes next.
+     */
+    flush?(): void | Promise<void>;
 }
 /** A machine-readable stream failure. `code` is a stable slug; `message` is human-facing. */
 interface StreamError {
@@ -3562,4 +3575,385 @@ 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, ClosedRolesPolicy, 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, 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, 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, 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, closeEmptyRoles, 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;
+}
+
+/** One stored row of a run's stream. `frame` is `null` on the terminal row. */
+interface StreamFrameRow {
+    seq: number;
+    /** One NDJSON line (`{...}\n`) as the writer wrote it; `null` marks the end of the run. */
+    frame: string | null;
+    /** On the terminal row of a FAILED run: the `StreamError` as JSON. `null` otherwise. */
+    error: string | null;
+}
+/**
+ * The table a {@link SqlTokenStreamSink} keeps its rows in — the only part of it that speaks SQL, so
+ * a store package implements this and inherits the rest (coalescing, ordering, polling, TTL).
+ * `@dudousxd/nestjs-agent-store-drizzle` and `-store-mikro-orm` ship one each, over
+ * `agent_stream_frame` (`run_id`, `seq`, `frame`, `error`, `created_at`; primary key
+ * `(run_id, seq)`).
+ */
+interface StreamFrameTable {
+    /**
+     * Insert the run's NEXT row: `seq = MAX(seq) + 1` for the run, taken in the SAME statement as the
+     * insert, so the `(run_id, seq)` primary key settles two writers that ask at once. Throws on that
+     * collision ({@link isUniqueViolation} says which errors are one) — the sink retries.
+     */
+    append(runId: string, row: {
+        frame: string | null;
+        error: string | null;
+        createdAt: number;
+    }): Promise<void>;
+    /** The run's rows with `seq > after`, ascending, at most `limit`. */
+    read(runId: string, after: number, limit: number): Promise<StreamFrameRow[]>;
+    /** Does the table hold any row for the run? */
+    has(runId: string): Promise<boolean>;
+    /** Delete every row of these runs. */
+    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)? */
+    isUniqueViolation(error: unknown): boolean;
+}
+interface SqlTokenStreamSinkOptions {
+    /**
+     * Gap (ms) between two reads of a run a subscriber is following — the most a frame waits in the
+     * table before a browser sees it. Default 250.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Gap (ms) between two reads once the run has written nothing for five seconds (parked on a
+     * person, a slow tool), so an open SSE connection on a quiet run costs one query a second. The
+     * first frame to arrive puts the subscriber back on `pollIntervalMs`. Default 1000; never below
+     * `pollIntervalMs`.
+     */
+    idlePollIntervalMs?: number;
+    /**
+     * Window (ms) consecutive `text` frames are gathered over and written as ONE row — a model
+     * streams token by token, and a row per token is more writes than a database should take for a
+     * chat answer. Any other frame, `end()`, `fail()` and `flush()` write what is gathered first, so
+     * order is kept. Default 50. `0` writes every frame as its own row.
+     */
+    flushMs?: number;
+    /**
+     * TTL (seconds) of a run's rows, counted from its LAST write — a long run stays, a run that
+     * crashed without ending still lapses. {@link SqlTokenStreamSink.purgeExpired} deletes them.
+     * Default 3600 (1h). `0` keeps rows until `close()`.
+     */
+    ttlSeconds?: number;
+    /**
+     * Purge lapsed runs as a side effect of ending a run, at most once a minute, so the table stays
+     * bounded in an app that never schedules {@link SqlTokenStreamSink.purgeExpired}. Default `true`.
+     */
+    autoPurge?: boolean;
+}
+/**
+ * A multi-replica {@link TokenStreamSink} over the app's SQL database — for a deployment with
+ * several replicas and NO Redis. The replica running the turn appends each frame as a row; any
+ * replica serves the run's SSE by reading the rows past its cursor, in order, until the terminal
+ * row. A late subscriber replays from the first row, as with the in-process and Redis sinks, and a
+ * run that `fail()`ed throws its {@link AgentStreamError} after the replay.
+ *
+ * Two things differ from the Redis sink, both the price of having no broker:
+ *
+ *  - **Delivery is polled** — a frame waits up to `pollIntervalMs` before a browser sees it.
+ *  - **Text is coalesced on the way in.** Consecutive `text` frames written within `flushMs` are
+ *    stored as ONE `text` frame. The stored rows ARE the run's stream: every subscriber, on every
+ *    replica, reads the same rows in the same order, so the SSE ids `chat/:runId/stream` numbers
+ *    them with — and an `?after=` cursor — stay exact across replicas.
+ *
+ * Sequence numbers are per run, start at 1 and have no gaps (see {@link StreamFrameTable.append}).
+ * Text a writer is still gathering lives in the process for at most `flushMs`; a process that dies
+ * in that window loses it from the LIVE stream (the persisted message is unaffected).
+ *
+ * Framework- and dialect-free: the SQL is the {@link StreamFrameTable}'s. Use
+ * `DrizzleTokenStreamSink` / `MikroOrmTokenStreamSink` from the store packages.
+ */
+declare class SqlTokenStreamSink implements TokenStreamSink {
+    private readonly table;
+    private readonly pollIntervalMs;
+    private readonly idlePollIntervalMs;
+    private readonly flushMs;
+    private readonly ttlSeconds;
+    private readonly autoPurge;
+    private readonly writes;
+    private lastAutoPurge;
+    constructor(table: StreamFrameTable, options?: SqlTokenStreamSinkOptions);
+    private runWrites;
+    /** Forget a run's write state once nothing is gathered, queued or left to report. */
+    private release;
+    /** Queue `work` behind every write already queued for the run, so rows land in call order. */
+    private enqueue;
+    /** Queue the gathered text (if any) as one `text` row. */
+    private flushText;
+    /** Raise, once, a gathered write that failed with nobody awaiting it. */
+    private raiseFailure;
+    /** Append one row — a frame, or the terminal row (`frame: null`, with `error` on a failure). */
+    private append;
+    /** Write out what is gathered, then a terminal row; raise a failure nobody saw. */
+    private terminate;
+    /**
+     * The run's writer. Writers opened for the same run in one process share what they are gathering,
+     * so a delegated run's text (forwarded through a child writer) and its parent's next frame keep
+     * the order they were written in.
+     */
+    open(runId: string): SinkWriter;
+    subscribe(runId: string): AsyncIterable<Uint8Array>;
+    /** Does the table hold anything for the run — a frame, or its end? */
+    has(runId: string): Promise<boolean>;
+    close(runId: string): Promise<void>;
+    /**
+     * Delete every run whose last write is older than `ttlSeconds` at `now` (epoch-ms) — ended runs
+     * past their replay window and runs that crashed without ending alike. Returns how many runs went.
+     * Safe from any replica, and from several at once. A no-op under `ttlSeconds: 0`.
+     */
+    purgeExpired(now?: number): Promise<number>;
+    /** {@link purgeExpired}, unawaited and at most once a minute. Its failure is not the run's. */
+    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 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, 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, 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 };