@dudousxd/nestjs-agent-core 0.15.5 → 0.17.0

package/dist/index.d.ts

@@ -1,812 +1,8 @@
+import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, E as ElicitationRequest, A as Actor, d as ThreadSummary, e as ThreadDetail, S as StoredMessage, f as ToolResult, g as MessageAttachment, h as ToolCallStatus, U as UsagePurpose, i as ToolSpec, Q as QuotaState, j as AgentRunInput, H as HumanReply, T as ToolHandler, k as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, l as ProcessedPrompt, m as ModelAnswer, n as PageContext, o as AgentDefinition, p as AgentDelegation, D as DetachedDelivery, q as AiToolCtx, r as PromptBuilder, s as PromptContributor, t as ToolTransientRetrySetting, u as AgentIntake, v as Decision, L as LlmStepEnvelope, w as ToolStepEnvelope } from './tool-CL9oEytW.js';
+export { x as ASK_TOOL_DESCRIPTION, y as ASK_TOOL_NAME, z as AgentCatalogEntry, B as AgentHistoryWindow, C as AskToolInput, F as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, G as DEFAULT_INTAKE_PREAMBLE, J as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, K as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, N as ElicitationOption, R as ElicitationOutcome, V as ElicitationQuestion, W as ElicitationReply, X as ElicitationResult, Y as HistoryPolicyContext, Z as HistorySelection, _ as HistorySummary, $ as IncrementalGating, a0 as InvokeWithTransientRetryOptions, a1 as MAX_ASK_QUESTIONS, a2 as MessageRole, a3 as OutputRejectedError, a4 as OutputVerdict, a5 as ProcessorFailedError, a6 as PromptContext, a7 as QuotaView, a8 as ToolKind, a9 as ToolStepCtx, aa as ToolTransientRetryNumbers, ab as ToolTransientRetryOptions, ac as askInputSchema, ad as askToolDefinition, ae as invokeWithTransientRetry, af as isTransientToolError, ag as normalizeElicitationReply, ah as renderElicitationAnswers, ai as resolveElicitation, aj as resolveToolTransientRetryNumbers, ak as settleElicitation } from './tool-CL9oEytW.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
-/**
- * Asking the USER a structured question, and waiting for the answer.
- *
- * `awaitApproval` collects a yes/no about work already proposed; this collects the scope BEFORE the
- * work. Two surfaces produce it — a configured intake (`AgentLoopDeps.intake`) and the model-callable
- * `ask` tool (`AgentLoopDeps.ask`) — and they deliberately produce the SAME {@link
- * ElicitationRequest}, persist through the same tool-call row, and resume through the same
- * `tool:<runId>:<callId>` signal. A consumer cannot tell which one asked, and should not have to.
- */
-
-/** One choice a question offers. */
-interface ElicitationOption {
-    /** Stable identifier submitted back. Never shown to the user. */
-    value: string;
-    /** What the user reads. */
-    label: string;
-    /**
-     * A single character a UI may bind as a keyboard shortcut for this option. Advisory — nothing in
-     * the library reads it, and a client is free to render its own.
-     */
-    hotkey?: string;
-}
-/** One question in a set. */
-interface ElicitationQuestion {
-    /** Unique within its request; the key answers come back under. */
-    id: string;
-    prompt: string;
-    options: ElicitationOption[];
-    /** More than one option may be chosen. Omit → single choice. */
-    multiple?: boolean;
-    /**
-     * The options already picked for the user. The claim this whole surface makes is that confirming
-     * is enough, so a question with no defaults is a question the user must stop and think about —
-     * which is the case the design is trying to avoid. Empty/omitted is allowed and means exactly
-     * that: submitting without answering leaves this question unanswered.
-     */
-    defaults?: string[];
-    /** Accept values that are not among `options` (a typed-in answer). Omit → options only. */
-    allowFreeText?: boolean;
-}
-/**
- * A question set awaiting a human. Identical in shape whether an `@Agent`'s configured intake or
- * the model's `ask` tool authored it — `source` records which, for audit, not for control flow.
- *
- * `questions.length` is known when the request is written, which is what lets a client render
- * "Question 1 of 3" without guessing whether a fourth is coming.
- */
-interface ElicitationRequest {
-    /** The tool-call id this request is persisted under, and the signal it is answered through. */
-    id: string;
-    source: 'intake' | 'ask';
-    /** What the assistant says above the form. */
-    preamble?: string;
-    questions: ElicitationQuestion[];
-}
-/** What a human sent back for an {@link ElicitationRequest}. */
-interface ElicitationReply {
-    /**
-     * questionId → chosen values. A question whose id is ABSENT takes the request's own `defaults` —
-     * that is what makes "just submit" mean "yes, your pre-picked answers". A present-but-empty array
-     * is an explicit "none of these" and does NOT fall back.
-     */
-    answers: Record<string, string[]>;
-    /**
-     * The user declined to answer and told the agent to proceed on its own assumptions. Distinct from
-     * confirming the defaults even though the resulting values are the same: one is a decision the
-     * user made, the other is one they refused to make, and only the first is evidence of intent.
-     */
-    skipped?: boolean;
-    /** Opaque ref of WHO answered, when it wasn't the run's own actor. */
-    answeredByRef?: string;
-}
-/** A settled elicitation: what the agent proceeds on, and how it got there. */
-interface ElicitationOutcome {
-    /** One entry per question, in request order — always present, so a caller never re-applies defaults. */
-    answers: Record<string, string[]>;
-    skipped: boolean;
-    /** Question ids filled from the request's `defaults` rather than by the human. */
-    defaulted: string[];
-}
-/**
- * Read whatever the human channel delivered as an {@link ElicitationReply}.
- *
- * A question set is persisted as an `action` tool call in `pending_approval` — that is what puts it
- * in the approvals inbox a deployment already has, instead of needing one of its own. The cost of
- * that choice is that the thing which comes back may be a {@link Decision} someone pressed
- * Approve/Reject on rather than a set of answers, and a `Decision` carries no `answers` at all.
- *
- * Approve means every question keeps its own pre-picked `defaults`, which is exactly what "just
- * submit" already means on this surface; Reject is the same declining-to-answer a skip is. Neither
- * reading is a guess — a yes/no channel cannot say more than that, and saying it here is what lets
- * one inbox settle both kinds of pending work.
- *
- * Returns the reply UNCHANGED when it already carries answers, so the common path allocates nothing
- * and a caller can identity-compare.
- */
-declare function normalizeElicitationReply(reply: ElicitationReply | Decision): ElicitationReply;
-/**
- * Settle a reply against the request it answers: fill every unanswered question from its own
- * `defaults`, drop submitted values that aren't on offer, and collapse a single-choice question to
- * one value.
- *
- * PURE, and deliberately so. Both of its inputs are already journaled by the time the loop calls it
- * — the request came from module config or from an `llm:<i>` checkpoint, the reply from the signal
- * checkpoint — so every process replaying the turn reaches the same values without a checkpoint of
- * its own. Resolving defaults in the HTTP layer instead would put them behind a store read that a
- * replay would have to repeat.
- */
-declare function resolveElicitation(request: ElicitationRequest, raw: ElicitationReply | Decision): ElicitationOutcome;
-/**
- * What a settled elicitation looks like to everyone downstream: the model reading it back as a tool
- * result, the thread reader rendering it, the auditor asking what the agent was told to do. One
- * shape for both surfaces — nothing here records which of them asked.
- */
-interface ElicitationResult extends ElicitationOutcome {
-    /** The questions against the chosen LABELS, so a reader (and a model) can act on it. */
-    summary: string;
-}
-/** {@link resolveElicitation} plus its human-readable rendering. Pure, for the same reason. */
-declare function settleElicitation(request: ElicitationRequest, reply: ElicitationReply | Decision): ElicitationResult;
-/**
- * The answers as the model reads them: the question's own prompt against the chosen options' LABELS,
- * not their opaque `value`s — a model shown `{"scope":["b"]}` has been told nothing.
- */
-declare function renderElicitationAnswers(request: ElicitationRequest, outcome: ElicitationOutcome): string;
-/** The reserved tool name the model calls to ask the user something. */
-declare const ASK_TOOL_NAME = "ask";
-/** What the model must supply when it calls `ask`. */
-interface AskToolInput {
-    preamble?: string;
-    questions: ElicitationQuestion[];
-}
-/** How many questions one `ask` may carry. A form the user has to scroll is a form they skip. */
-declare const MAX_ASK_QUESTIONS = 5;
-/**
- * The `ask` tool's input schema, hand-written rather than borrowed from a validation library: core
- * depends on no validator, and the schema has to carry a JSON Schema a provider can constrain
- * generation against. It publishes one through the Standard JSON Schema extension
- * (`~standard.jsonSchema.input`), which is the path the AI SDK adapter already recognises for
- * Valibot / ArkType / Zod 4.
- */
-declare const askInputSchema: StandardSchemaV1<unknown, AskToolInput>;
-/**
- * What the model is told the `ask` tool is for. Written to discourage the two failure modes that
- * make a clarifying question worse than a guess: asking about something the conversation already
- * settled, and asking without saying what you would have done.
- */
-declare const ASK_TOOL_DESCRIPTION = "Ask the user to settle the scope of the work before you do it. Use it when a reasonable person would produce a materially different result depending on the answer \u2014 not to confirm something the conversation already says. Every question must pre-pick the answer you would choose, so the user can confirm instead of deciding. The user may decline, in which case you proceed on those pre-picked answers.";
-/**
- * The `ask` tool as the model sees it. NOT a `ToolSpec` and never registered: `ask` has no handler,
- * because the loop settles it against a human instead of invoking anything. Keeping it out of the
- * `ToolRegistry` is also what keeps the kind decision off a process-local lookup — see
- * `claimToolCall`.
- */
-declare function askToolDefinition(): ToolDefinition;
-/** A question set an `@Agent` asks before it starts working. See `AgentLoopDeps.intake`. */
-interface AgentIntake {
-    questions: ElicitationQuestion[];
-    /** What the assistant says above the form. Omit → {@link DEFAULT_INTAKE_PREAMBLE}. */
-    preamble?: string;
-    /**
-     * `'thread-start'` (default) asks once, on the first turn of a thread; `'every-turn'` asks before
-     * every turn. Both are decided from what `load:thread` recorded about the thread when the turn
-     * began, never from anything this process happens to know — by the time a replay reaches the
-     * question, the thread already holds the assistant message the first attempt wrote.
-     */
-    when?: 'thread-start' | 'every-turn';
-}
-declare const DEFAULT_INTAKE_PREAMBLE = "A few questions before I start. I have pre-picked what I would choose, so confirming is enough.";
-
-/**
- * The ceiling on how much of a thread rides into a turn. Without one, `runAgentLoop` maps EVERY
- * message the store returns into the model's messages, so a long-lived thread grows until the
- * provider rejects the request — and every turn before that one pays for the whole transcript.
- * `@dudousxd/nestjs-agent-core` ships `windowHistory` as the built-in; anything satisfying this SPI
- * works. Wire it as `AgentLoopDeps.historyPolicy`, or via `AgentModule.forRoot({ history })` /
- * `@Agent({ history })`.
- */
-
-/** Whose history this is — enough for a policy to size the window per agent or per actor. */
-interface HistoryPolicyContext {
-    threadId: string;
-    actor: Actor;
-    /** The agent running this turn. Undefined → the default agent. */
-    agentName?: string;
-}
-/** How a policy split the thread: what rides into the turn, and what the ceiling left out. */
-interface HistorySelection {
-    /** Sent to the model, oldest-first. */
-    keep: ModelMessage[];
-    /** Left out, oldest-first. Folded into a leading summary when the policy implements `summarize`. */
-    drop: ModelMessage[];
-}
-/** A stand-in for the messages a window left out, plus what producing it cost. */
-interface HistorySummary {
-    /** Prose the loop folds into the window as a leading `system` message. */
-    text: string;
-    /**
-     * What the summarizer spent, when it called a model. Recorded as a `history_summary` usage row, so
-     * a ceiling on context cost cannot itself become spend nothing accounts for. Omit for a summarizer
-     * that calls no model (a rollup of tool names, a digest the app already stored).
-     */
-    usage?: MessageUsage;
-    /** Accounting label for the model that produced it; falls back to `AgentLoopDeps.modelId`. */
-    modelId?: string;
-}
-interface HistoryPolicy {
-    /**
-     * The most messages {@link select} can ever keep, where the ceiling can be stated as a row count.
-     *
-     * A hint the loop hands to the store, which then reads that many of the thread's newest rows
-     * rather than its whole transcript (see `ThreadTurnReader`). Declaring it is a PROMISE about
-     * `select`: that it keeps at most this many messages, and that they are the NEWEST ones — so a
-     * window of this size is indistinguishable, to `select`, from the full transcript. A policy that
-     * can keep more than this, or can keep something older than the newest `maxMessages`, must omit it
-     * rather than select over rows the store was never asked for.
-     *
-     * Omit where the ceiling is not a row count at all — a token budget alone cannot name one, since
-     * one message can be four tokens or forty thousand. Omitting costs only the bound on the READ; the
-     * prompt is identical either way.
-     */
-    readonly maxMessages?: number;
-    /**
-     * Decide what the model sees.
-     *
-     * MUST be a pure function of `messages`. The loop calls it INSIDE the `load:thread` checkpoint and
-     * records its result there, so the ceiling bounds the journal as well as the prompt: what the
-     * checkpoint holds is the selection rather than the store's whole `ThreadDetail`, on a payload
-     * every replay re-reads. It still adds no position of its own — a policy cannot change the name or
-     * position of a single existing checkpoint.
-     *
-     * Read a clock, a feature flag or a database here and the resumed run windows differently from the
-     * one that suspended: the model gets a different prompt, and any step whose existence depends on
-     * the split lands at a position the history has no room for. Anything non-deterministic belongs in
-     * {@link summarize}, which has a checkpoint of its own.
-     *
-     * The newest message must always be in `keep` — dropping it leaves the turn with nothing to answer.
-     */
-    select(messages: ModelMessage[], ctx: HistoryPolicyContext): HistorySelection;
-    /**
-     * Fold the dropped messages into prose the model reads in their place, prepended to the window as
-     * a `system` message. Optional — without it, dropped messages are simply gone, and `load:thread`
-     * does not record them either: a summarizer is the only thing that ever reads them back.
-     *
-     * Runs inside the loop's `history:summarize` checkpoint, so it may call a model or hit the
-     * network: the first attempt's result is journaled and every replay reads it back instead of
-     * re-summarizing. It runs once per RUN (not per model step), and only when `select` actually
-     * dropped something.
-     */
-    summarize?(dropped: ModelMessage[], ctx: HistoryPolicyContext): Promise<HistorySummary>;
-}
-/**
- * The window an agent asks for declaratively — `AgentModule.forRoot({ history })` and
- * `@Agent({ history })`. Plain data, so it can live in a decorator's metadata; the NestJS layer
- * turns it into a `windowHistory` policy. A consumer needing anything the window can't express
- * supplies a {@link HistoryPolicy} instead.
- */
-interface AgentHistoryWindow {
-    /** Keep at most this many of the newest messages. */
-    maxMessages?: number;
-    /** Keep the newest messages whose estimated tokens fit this budget. */
-    maxTokens?: number;
-    /** Fold what the window left out into a leading summary — one extra model call per run. */
-    summarize?: boolean;
-}
-
-/**
- * Transient tool-error classification + the retry loop that wraps a tool's own invocation. A
- * classified-transient error (a DB deadlock, a lock-wait timeout, a serialization failure) means
- * the server rolled the tool's work back — retrying THAT class is safe, unlike a tool's general
- * business failure, which stays a one-shot outcome (no durable step retries: a tool may not be
- * idempotent). See `runAgentLoop`'s `tool:<call.id>` step body and `AgentRunSteps.tool` — both wrap
- * `registry.invoke(...)` with {@link invokeWithTransientRetry} so a retry never becomes a new
- * checkpoint; history still shows exactly one step per tool call.
- */
-/**
- * Default transient-tool-error classifier: true for a recognized MySQL/Postgres/SQLite
- * lock-contention shape (by driver `code`/`errno`/`sqlState`, or a matching message), checked on
- * the error itself and one level of `cause` (drivers commonly wrap the original error). A plain
- * `Error` with none of these markers — any other business failure — is `false`.
- */
-declare function isTransientToolError(error: unknown): boolean;
-/** Total attempts (initial try + retries) when `toolTransientRetry` doesn't set `attempts`. */
-declare const DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS = 2;
-/** Backoff base in ms — the wait between attempt N and N+1 is `backoffMs * N`. */
-declare const DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS = 150;
-/** The host-configurable half of the policy — everything except the (non-wire-safe) `classify` fn. */
-interface ToolTransientRetryOptions {
-    /** Total attempts (initial try + retries). Defaults to {@link DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS}. */
-    attempts?: number;
-    /** Backoff base in ms. Defaults to {@link DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS}. */
-    backoffMs?: number;
-    /** Overrides the default classifier — widen or narrow which errors are treated as transient. */
-    classify?: (error: unknown) => boolean;
-}
-/** `false` disables transient retry entirely — a tool's own thrown error surfaces immediately. */
-type ToolTransientRetrySetting = ToolTransientRetryOptions | false;
-/** Just the wire-safe (numeric) half of a resolved policy — what a dispatched envelope carries. */
-interface ToolTransientRetryNumbers {
-    attempts: number;
-    backoffMs: number;
-}
-/**
- * Resolves the numeric half of `toolTransientRetry` for the dispatched wire envelope: `false` when
- * explicitly disabled, else concrete `{ attempts, backoffMs }` (defaults filled in) — never
- * `undefined`, so the dispatched handler always gets a definite answer instead of re-deriving its
- * own default. The `classify` function never rides this — it isn't wire-safe; the dispatched
- * handler resolves its own `classify` from its local module options (see `AgentRunSteps.tool`).
- */
-declare function resolveToolTransientRetryNumbers(setting: ToolTransientRetrySetting | undefined): ToolTransientRetryNumbers | false;
-interface InvokeWithTransientRetryOptions {
-    /**
-     * Widens what counts as a control-flow signal (durable suspend / continue-as-new) so a retry never
-     * swallows one — same rule the loop's tool catch applies. An ADDITION to the built-in marker check
-     * ({@link isControlFlowSignal}), which already covers every signal the durable runtimes raise;
-     * supply this only for a runner whose signals carry no marker.
-     */
-    isControlFlowError?: (error: unknown) => boolean;
-    /**
-     * Called before each wait-and-retry, with the 1-based ordinal of the attempt that just failed and
-     * the error it threw. The call site uses this to emit the `tool.retry` diagnostics point event —
-     * `invokeWithTransientRetry` itself carries no tool identity (name/callId), only the thunk.
-     */
-    onRetry?: (attempt: number, error: unknown) => void;
-}
-/**
- * Retries `fn` in place — never a new durable step/checkpoint, just repeated attempts inside
- * whichever step body already wraps this call. `setting: false` runs `fn` once, unwrapped (no
- * classify/backoff bookkeeping at all). Otherwise: try; on a thrown error, rethrow immediately if
- * it's a recognized control-flow signal, else if the (possibly custom) classifier calls it
- * transient AND attempts remain, wait `backoffMs * attemptNumber` and retry; otherwise rethrow the
- * error as-is.
- */
-declare function invokeWithTransientRetry<T>(fn: () => Promise<T>, setting: ToolTransientRetrySetting, options?: InvokeWithTransientRetryOptions): Promise<T>;
-
-/** Who is driving the turn. Roles + tenant come from the host app (nestjs-context/authz). */
-interface Actor {
-    id: string;
-    /** The caller's roles. Tool authorization is a set intersection against a tool's `roles`. */
-    roles?: string[];
-    tenantRef?: string;
-}
-type ToolKind = 'read' | 'action' | 'agent' | 'ask' | 'skill' | 'memory';
-/**
- * One agent->agent edge on {@link AgentDefinition.delegatesTo}. A bare name is the awaited
- * delegation that has always existed; the object form is how an author says this one runs in the
- * background.
- */
-type AgentDelegation = string | {
-    agent: string;
-    detached?: boolean;
-};
-/**
- * Where a detached sub-agent run posts its answer: the thread that delegated it, and the
- * `agent`-kind tool call that started it. Carried on the child run's own {@link AgentRunInput},
- * because by the time the child finishes the parent turn is over and nothing is holding the
- * address.
- */
-interface DetachedDelivery {
-    threadId: string;
-    toolCallId: string;
-}
-/**
- * Declared shape of a tool.
- *  - `read`   auto-executes.
- *  - `action` never auto-executes — requires HITL approval.
- *  - `agent`  delegates to another named agent (durable: a child workflow; inline: a nested loop),
- *             handled at the loop level — NOT via a handler. Carries `targetAgent`.
- *  - `ask`    puts a question set to the user and waits for the answers (see `elicitation.ts`).
- *             Handled at the loop level and never registered, so no `ToolSpec` carries this kind:
- *             the only tool that has it is the built-in `ask`, whose definition the loop supplies.
- *  - `skill`  reads one of the procedures offered in the turn's `<skills>` catalog (see `skills.ts`).
- *             Auto-executes like a read and performs nothing, but is served by the LOOP from the
- *             catalog the journal holds rather than by a registered handler — so, like `ask`, no
- *             `ToolSpec` carries this kind.
- *  - `memory` records one fact about the actor for later turns (see `memory.ts`). Served by the LOOP
- *             and never registered, like `skill`. It WRITES, but auto-executes rather than asking
- *             for approval: an agent may only ever write the scope of the actor it is running for,
- *             so the blast radius of a bad one is the prompt of the person who was talking, and the
- *             remedy is the read-back that lets them delete it.
- */
-interface ToolSpec {
-    name: string;
-    kind: ToolKind;
-    description: string;
-    /**
-     * Input schema as a [Standard Schema](https://standardschema.dev) — validation-agnostic, so
-     * Zod, Valibot, or ArkType all work. The loop validates input via `~standard.validate` before
-     * running the handler, and providers convert it to the model's tool-parameter JSON schema.
-     */
-    inputSchema: StandardSchemaV1;
-    /** For `kind: 'agent'` — the name of the agent to delegate to. */
-    targetAgent?: string;
-    /**
-     * For `kind: 'agent'` — start the delegation and let the calling turn END, instead of holding it
-     * open until the delegate answers. The call's result is a {@link DetachedDelegationReceipt}, and
-     * the answer arrives later as its own message in the same thread (see
-     * {@link AgentRunInput.deliverTo}).
-     *
-     * Authored per EDGE, never chosen by the model: a model that can decide to detach can decide to
-     * detach the one thing the user is sitting there waiting for, and it has no way to know which that
-     * is. The person wiring `A -> B` does.
-     *
-     * Settled into the call's `persist:toolcall` checkpoint alongside `targetAgent`, so every replay
-     * reads the branch back rather than re-deciding it against a registry that may have changed.
-     */
-    detached?: boolean;
-    /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
-    roles?: string[];
-    /**
-     * Whether the tool exists in this deployment. `false` (or a predicate returning `false`) drops it
-     * before the role filter, so it is never offered to the model and cannot be invoked. Undefined →
-     * enabled.
-     *
-     * A predicate is re-evaluated every turn, so a flag flipped at runtime takes effect on the next
-     * message with nothing re-registered. For availability that depends on injected services, put
-     * `isEnabled()` on the handler instead — a spec is data, a handler is a provider.
-     */
-    enabled?: boolean | (() => boolean | Promise<boolean>);
-    /**
-     * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
-     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
-     * and rely on `roles` instead — both live on the same SPI, so neither is required.
-     */
-    ability?: string;
-}
-/** What the model is told a tool looks like (no handler, no host types). */
-interface ToolDefinition {
-    name: string;
-    kind: ToolKind;
-    description: string;
-    inputSchema: StandardSchemaV1;
-}
-/** A tool call the model asked for during a turn. */
-interface ToolCallRequest {
-    id: string;
-    name: string;
-    input: unknown;
-    /**
-     * The tool's declared kind (`ToolSpec.kind`), stamped where the tool was OFFERED — inside the llm
-     * checkpoint, by the process that built the definition list the model chose from. It travels with
-     * the call from there, so thread-read consumers know a call's kind without hardcoding a tool-name
-     * allowlist, and the approval branch does not depend on which process replays the turn.
-     * Undefined only for a call that predates the stamp, or one no registry could resolve
-     * (defensively treated as `read` wherever a definite value is required).
-     */
-    kind?: ToolKind;
-}
-/** Result of running a tool. */
-interface ToolResult {
-    /**
-     * A person declined this action, so the tool never ran. Set INSTEAD of a failure, and read by
-     * every consumer that has to tell the two apart — the stream frame, the replayed transcript. The
-     * `error` field still carries what the MODEL is told, because that is the channel a model reads a
-     * tool's outcome on; this flag is what everything else reads.
-     */
-    denied?: true;
-    id: string;
-    name: string;
-    output: unknown;
-    error?: string;
-}
-interface MessageUsage {
-    /**
-     * Total input (prompt) tokens for the turn — the whole input side, cached and uncached alike.
-     * `cacheWriteTokens` + `cacheReadTokens` are subsets of this count, not additions to it, so
-     * token totals and quota never change when a breakdown is present.
-     */
-    inputTokens: number;
-    /** Total output (completion) tokens for the turn; `reasoningTokens` is a subset of this. */
-    outputTokens: number;
-    /**
-     * How many of `inputTokens` were written to the prompt cache this turn (billed at a premium,
-     * ~1.25× base input). Undefined when the provider doesn't report caching. Refines the cost
-     * estimate only — priced by the pricing row's cache-write rate (falling back to the input rate).
-     */
-    cacheWriteTokens?: number;
-    /**
-     * How many of `inputTokens` were served from the prompt cache this turn (billed at a discount,
-     * ~0.1× base input). Undefined when the provider doesn't report caching.
-     */
-    cacheReadTokens?: number;
-    /**
-     * How many of `outputTokens` the model spent on reasoning/thinking. Observability only — reasoning
-     * tokens are billed at the output rate, so they don't change the cost estimate. Undefined for
-     * non-reasoning models or providers that don't report it.
-     */
-    reasoningTokens?: number;
-    /**
-     * This turn's USD cost: the provider's own reported figure when it has one, else an estimate from
-     * the bound `AgentPricingStore` (cached once per run — see `AgentLoopDeps.pricingStore`), else
-     * `null` when no pricing store is bound or the model has no price row. Never `0` for an unpriced
-     * model — a real $0 turn and "we don't know" must stay distinguishable.
-     */
-    costUsd?: number | null;
-}
-/**
- * What a usage row was spent ON. `chat` is a model step of the turn itself; `follow_ups` is the
- * extra call that proposes follow-up questions; `history_summary` is the extra call a
- * {@link import('./spi/history-policy.js').HistoryPolicy} makes to fold windowed-out messages into a
- * summary — so bounding context cost never becomes spend nothing accounts for; `structured_output`
- * is the formatting pass that restates a finished answer as `AgentLoopDeps.outputSchema` requires.
- */
-type UsagePurpose = 'chat' | 'follow_ups' | 'history_summary' | 'structured_output';
-interface QuotaState {
-    usedTokens: number;
-    limitTokens: number;
-    withinLimit: boolean;
-}
-/**
- * The read-model the quota-today endpoint returns to a client — a superset of {@link QuotaState}
- * for rendering a usage badge. `limitTokens` is `null` when no quota is configured (unlimited, so
- * `withinLimit` is always true); `costUsd` is the day's summed provider-reported USD spend (`0`
- * when only tokens were reported).
- */
-interface QuotaView {
-    usedTokens: number;
-    limitTokens: number | null;
-    withinLimit: boolean;
-    costUsd: number;
-}
-/**
- * Anything a human sends back into a parked run: a {@link Decision} on an action tool, or an
- * `ElicitationReply` answering a question set. Both travel the same `tool:<runId>:<toolCallId>`
- * signal, so the runner that delivers them does not need to know which it is carrying.
- */
-type HumanReply = Decision | ElicitationReply;
-/** A human decision on a pending action tool call. */
-interface Decision {
-    approved: boolean;
-    reason?: string;
-    /**
-     * Opaque ref of WHO decided (e.g. a console admin). When absent, the run's own actor decided
-     * (the chat flow).
-     */
-    executedByRef?: string;
-}
-type MessageRole = 'user' | 'assistant' | 'system';
-/**
- * A file a user attached to a message so a vision-capable model sees it natively (an image, a PDF).
- * The lib stays provider-agnostic: it passes {@link MessageAttachment.url} straight through as the
- * model's image/file part data — making that URL reachable by the provider (presigned S3, a proxy)
- * is the consumer's job. The lib never fetches bytes or talks to a store.
- */
-interface MessageAttachment {
-    /** Stable id of the stored media object in the consumer's media store. Provenance + replay key. */
-    mediaId: string;
-    /** A URL the model provider can fetch the bytes from at turn time. */
-    url: string;
-    /** MIME type — routes the part: `image/*` → image part, otherwise → file part. */
-    contentType: string;
-    /** Original filename, for display and the file part's filename. */
-    name: string;
-}
-/** A neutral chat message exchanged with the model. */
-interface ModelMessage {
-    role: MessageRole;
-    content: string;
-    toolCalls?: ToolCallRequest[];
-    toolResults?: ToolResult[];
-    /** User-message attachments (image/PDF), rendered as native model content parts by the adapter. */
-    attachments?: MessageAttachment[];
-}
-interface PageContext {
-    kind?: string;
-    [key: string]: unknown;
-}
-/**
- * Inputs a {@link PromptBuilder} or {@link PromptContributor} may use to compose the system prompt
- * for a turn. Resolved once per turn from stable inputs (actor / agent / pageContext) so it stays
- * replay-safe.
- */
-interface PromptContext {
-    actor: Actor;
-    /** The selected agent's name. */
-    agentName: string;
-    pageContext?: PageContext;
-}
-/**
- * An agent's base system prompt. Return a string (optionally async) built from the turn's context —
- * e.g. injecting the actor, the current page, or a data-shape description. Set on an `@Agent` class
- * via a `@SystemPrompt()` method (or a flat string).
- */
-type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
-/**
- * A cross-agent system-prompt contributor. Returns an ordered section to APPEND to the composed
- * prompt (after the agent's base), or `null` to contribute nothing this turn — so conditional
- * sections (base-scope, a mentions legend, schema hints) stay clean when they don't apply.
- * Registered app-wide via `@SystemPromptContributor()`; the loop runs every contributor in order.
- */
-type PromptContributor = (ctx: PromptContext) => string | null | Promise<string | null>;
-/** Everything needed to run one agent turn. */
-interface AgentRunInput {
-    threadId: string;
-    actor: Actor;
-    /** The latest user message text. */
-    userText: string;
-    /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
-    attachments?: MessageAttachment[];
-    pageContext?: PageContext;
-    /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
-    day?: string;
-    /** Which named agent runs this turn. Omitted → the default/single agent. */
-    agentName?: string;
-    /**
-     * How many agent→agent delegations deep this run already is (0 for a top-level turn). The runner
-     * increments it for each child run; the loop refuses to delegate past its depth ceiling.
-     */
-    delegationDepth?: number;
-    /**
-     * The named agents already on this delegation chain, root first — what {@link delegationDepth}
-     * counts, spelled out. The runner appends its own agent's name for each child it starts.
-     *
-     * A count can only say a chain is LONG. This says whether it is going in circles, and how often:
-     * an agent that appears here is one the chain has already passed through, so a delegation back to
-     * it is a cycle by inspection rather than by proxy. A run whose runner does not supply it falls
-     * back to the depth ceiling alone.
-     */
-    delegationPath?: readonly string[];
-    /**
-     * When set, this run streams into ANOTHER run's sink instead of its own. A sub-agent run carries
-     * its top-level ancestor's runId here so its tokens (and its pending action-tool frames) land in
-     * the live stream the human is already watching — the only way a human can see, and therefore
-     * approve, a sub-agent's HITL action. Propagated unchanged down the delegation chain.
-     */
-    sinkRunId?: string;
-    /**
-     * Set on a DETACHED sub-agent run: the thread and tool call this run answers into when it
-     * finishes. Its presence is also what makes a run detached from the inside — it has no ancestor
-     * sink to stream into, so nothing else distinguishes it from a top-level turn.
-     */
-    deliverTo?: DetachedDelivery;
-    /**
-     * The run that started this one (a delegation's parent). Recorded with the run so a governance
-     * surface can roll a delegation's cost up to the turn that asked for it; a detached child is
-     * otherwise a row with nothing pointing at it.
-     */
-    parentRunId?: string;
-    /**
-     * Re-run the last exchange instead of adding a new message: the loop truncates everything after
-     * the thread's last user message and re-answers it (no `userText` is appended). Used by a
-     * "regenerate" button. `userText` is ignored when set.
-     */
-    regenerate?: boolean;
-}
-/**
- * A named agent: its prompt, the tools it may use, and who it can hand off to. This is the
- * internal record the loop and `AgentDepsFactory` consume; in an app it is authored as an
- * `@Agent`-decorated class and populated into the `AgentRegistry` by discovery (name, base prompt
- * from `@SystemPrompt`, tool allow-list, handoff targets). An orchestrator hands off to others via
- * `ctx.handoff(OtherAgent)`. Model/store/sink/governance are shared from the module.
- */
-interface AgentDefinition {
-    name: string;
-    /** Human-readable summary from `@Agent({ description })`. Surfaced by the `GET agents` catalog. */
-    description?: string;
-    /** Base prompt for this agent. A flat string, or a {@link PromptBuilder} resolved per turn. */
-    systemPrompt?: string | PromptBuilder;
-    /** Allow-list of tool names this agent may use (subset of all registered tools). */
-    tools?: string[];
-    /**
-     * Other agents this agent may hand off to (auto-registered as `agent`-kind tools). A bare name
-     * is the awaited form; `{ agent, detached: true }` starts the delegate and lets this agent's turn
-     * finish without its answer — see {@link ToolSpec.detached}.
-     */
-    delegatesTo?: AgentDelegation[];
-    modelId?: string;
-    maxSteps?: number;
-    /**
-     * How deep delegation may nest below this agent. Undefined → {@link MAX_DELEGATION_DEPTH}.
-     *
-     * Bounds the CHAIN, not the fan-out: how many agents a turn delegates to is the model's.
-     */
-    maxDelegationDepth?: number;
-    /**
-     * How many times one agent may appear on a single delegation chain.
-     * Undefined → {@link DEFAULT_MAX_AGENT_APPEARANCES}.
-     */
-    maxAgentAppearances?: number;
-    /**
-     * This agent's own ceiling on how much of a thread rides into its turn, overriding the
-     * module-wide one. A persona that reasons over a long back-and-forth and one that answers a single
-     * question from a page context want very different windows.
-     */
-    history?: AgentHistoryWindow;
-    /**
-     * Constrain this agent's final answer to a schema. A live schema INSTANCE, so it is resolved from
-     * DI on whichever process runs the turn and never travels on `AgentRunInput` — a Standard Schema
-     * cannot survive the JSON hop into a durable workflow, which is why there is no per-request
-     * override on the HTTP surface.
-     */
-    outputSchema?: StandardSchemaV1;
-    /**
-     * Extra model calls allowed to fix an answer that failed {@link outputSchema}. Undefined → 1.
-     */
-    outputRepairAttempts?: number;
-    /**
-     * Questions this agent puts to the user BEFORE it starts working. Authored, so the turn pays no
-     * model call to produce them and a client knows the total up front. Undefined → no intake.
-     */
-    intake?: AgentIntake;
-    /**
-     * Whether this agent is offered the built-in `ask` tool. Undefined → the module-wide setting.
-     */
-    ask?: boolean;
-}
-/**
- * The read-model the `GET agents` endpoint returns to a client — the safe public subset of an
- * {@link AgentDefinition} so a host can render a persona picker instead of hardcoding one.
- */
-interface AgentCatalogEntry {
-    name: string;
-    description: string;
-    /** Whether this is the agent a turn uses when the caller names none. Omitted when not the default. */
-    isDefault?: boolean;
-}
-interface ThreadSummary {
-    id: string;
-    title: string;
-    transient: boolean;
-    createdAt: string;
-    updatedAt: string;
-    lastMessagePreview?: string;
-    /**
-     * The agent a `chat()` call on this thread uses when the caller doesn't name one explicitly.
-     * Optional — undefined for a store that doesn't implement `AgentStore.updateThread` (the only
-     * way to set it). The REST/service read-model normalizes this to `null` when absent.
-     */
-    defaultAgent?: string | null;
-    /**
-     * The runId of a currently-running turn on this thread, or `null` if none is running. Optional —
-     * undefined for a store that doesn't implement `AgentStore.activeRunForThread`. The REST/service
-     * read-model normalizes this to `null` when absent, so a client can always do `?? null`.
-     */
-    activeRunId?: string | null;
-}
-interface StoredMessage {
-    id: string;
-    role: MessageRole;
-    content: string;
-    /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
-    agentName?: string;
-    toolCalls?: ToolCallRequest[];
-    toolResults?: ToolResult[];
-    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
-    attachments?: MessageAttachment[];
-    followUps?: string[];
-    usage?: MessageUsage;
-    /** The run (turn) that produced this message; absent on a row written before this was recorded. */
-    runId?: string;
-    createdAt: string;
-}
-interface ThreadDetail extends ThreadSummary {
-    messages: StoredMessage[];
-    activeStreamId?: string;
-}
-type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
-/**
- * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
- * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
- */
-interface LlmStepEnvelope {
-    /** Undefined = default agent (same semantics as {@link AgentRunInput.agentName}). */
-    agentName?: string;
-    system: string;
-    messages: ModelMessage[];
-    /** The turn's actor — the handler re-derives tool definitions from it (definitionsFor). */
-    actor: Actor;
-    /**
-     * Hold this call's stream frames rather than writing them to the run's sink, and return them on
-     * the result. Set by the loop when an output processor has to see the whole answer before the
-     * subscriber does — the dispatched handler streams to a worker-side sink the loop cannot
-     * interpose on, so the instruction has to ride the envelope. Absent → stream live, as before.
-     */
-    bufferOutput?: boolean;
-}
-/**
- * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
- * from DI).
- */
-interface ToolStepCtx {
-    actor: Actor;
-    threadId: string;
-    runId: string;
-    requestId: string;
-    agentName?: string;
-    pageContext?: PageContext;
-}
-/** Serializable input for a dispatched tool-execution step. */
-interface ToolStepEnvelope {
-    toolName: string;
-    input: unknown;
-    ctx: ToolStepCtx;
-    /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
-    timeoutMs?: number;
-    /**
-     * The numeric half of `toolTransientRetry` (resolved by the loop from `AgentLoopDeps`, always a
-     * definite value — `false` when disabled, else concrete `{ attempts, backoffMs }` with defaults
-     * already filled in) — never `undefined`, so the dispatched handler gets the SAME policy the
-     * loop would have used locally. The `classify` function is deliberately absent: it isn't
-     * wire-safe, so the handler resolves its own from its local module options (see
-     * `AgentRunSteps.tool`) instead of trying to serialize a function.
-     */
-    transientRetry: ToolTransientRetryNumbers | false;
-}
-
 /**
  * Public, cross-lib-discoverable DI tokens.
  *
@@ -879,54 +75,6 @@ declare const AGENT_MEMORY: unique symbol;
  */
 declare const AGENT_SKILL_SOURCES: unique symbol;
 
-/**
- * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
- * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
- * no denormalized copies).
- */
-interface AiToolCtx {
-    actor: Actor;
-    threadId: string;
-    runId: string;
-    requestId: string;
-    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
-    agentName?: string;
-    pageContext?: PageContext;
-    /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
-    host?: unknown;
-}
-/** A tool implementation. `I` is the parsed (Zod-validated) input. */
-interface ToolHandler<I = unknown> {
-    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
-    /**
-     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
-     * policy, so a `false` here means the model is never shown the tool rather than being shown one
-     * it will be refused. Omit → always enabled.
-     *
-     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
-     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
-     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
-     * separate question "may THIS actor use it?", and both still run.
-     *
-     * Prefer this over conditionally registering the provider: registration happens while the
-     * `@Module` metadata is built, which in most apps is before configuration is loaded.
-     */
-    isEnabled?(): boolean | Promise<boolean>;
-    /**
-     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
-     *
-     * The three existing gates all answer the question somewhere else: `roles` is static data,
-     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
-     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
-     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
-     * this actor own the base being queried, is the per-user override in the DB set today.
-     *
-     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
-     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
-     */
-    canUse?(actor: Actor): boolean | Promise<boolean>;
-}
-
 /**
  * The "data plane": live token transport, decoupled from the durable control plane.
  *
@@ -1065,8 +213,51 @@ interface ModelProvider {
  *
  * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
  * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ *
+ * The vocabulary is also a CONTRACT for runners that are not this library's loop: anything that
+ * writes these frames (one JSON object per SSE `data:` line) gets the React transport, transcript
+ * model and hooks for free. Two rules keep it evolvable:
+ *  - every frame is a JSON object with a string `kind`; a reader MUST tolerate kinds it does not
+ *    know (the React transport forwards them as `data-<kind>` parts rather than dropping them);
+ *  - fields are only ever added, and new fields are optional.
  */
 
+/**
+ * A component the server pushed into the conversation: generative UI that is NOT a tool call's
+ * rendering. It is addressed by `component` (a key in the client's own component registry), never
+ * by a tool name, so a runner can emit one from anywhere — a tool body, a post-processing step, a
+ * sandboxed agent that renders through its own protocol.
+ *
+ * `id` is the component's identity within the message: a second frame with the same `id` REPLACES
+ * the first (streaming props into a chart, flipping a card from "loading" to "ready"), it never
+ * adds a second component.
+ */
+interface AgentUiComponent {
+    id: string;
+    /** Registry key the client resolves to its own renderer, e.g. `data-table`. */
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
+    version?: number;
+}
+/**
+ * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
+ * settled through the tool-call approve/reject routes, by its `toolCallId`.
+ */
+interface AgentApprovalRequest {
+    /** The tool call awaiting the decision — the `id` of a call already announced on this stream. */
+    id: string;
+    /**
+     * Who may decide. Open vocabulary the host defines — `'requester'` (the person chatting),
+     * `'admin'`, a role name, a team. A client uses it to say "waiting on an admin" instead of
+     * offering buttons the viewer cannot use.
+     */
+    approver: string;
+    /** ISO-8601 instant after which the request lapses. Absent → it never expires. */
+    expiresAt?: string;
+    /** Why this call needs a person, in words for that person. */
+    reason?: string;
+}
 type AgentStreamEvent = {
     kind: 'step-start';
 }
@@ -1086,12 +277,19 @@ type AgentStreamEvent = {
     kind: 'reasoning';
     text: string;
 }
-/** `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool. */
+/**
+ * `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool.
+ *
+ * `parentId` nests this call under another call on the same stream: the inner calls a code-mode
+ * `execute` makes, the tools a delegated sub-agent runs. The parent must be announced first. A
+ * call's parent is fixed by its first frame that names one; later frames may omit it.
+ */
  | {
     kind: 'tool-input-start';
     id: string;
     name: string;
     toolKind: 'read' | 'action';
+    parentId?: string;
 } | {
     kind: 'tool-input-delta';
     id: string;
@@ -1102,6 +300,8 @@ type AgentStreamEvent = {
     name: string;
     input: unknown;
     toolKind: 'read' | 'action';
+    /** Same as on `tool-input-start`, for a runner that announces a call without streaming its input. */
+    parentId?: string;
 } | {
     kind: 'tool-output';
     id: string;
@@ -1134,6 +334,31 @@ type AgentStreamEvent = {
     id: string;
     request: ElicitationRequest;
 }
+/**
+ * An action tool call (already announced by `tool-input-start`/`tool-input-available` under the
+ * same `id`) is parked on a person. Optional: a client still treats an `action` call stuck at
+ * its input as pending — this frame adds WHO has to decide and UNTIL WHEN, and moves the call
+ * into the AI SDK's native `approval-requested` state.
+ */
+ | ({
+    kind: 'approval-requested';
+} & AgentApprovalRequest)
+/**
+ * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
+ * call. See {@link AgentUiComponent}.
+ */
+ | ({
+    kind: 'ui';
+} & AgentUiComponent)
+/**
+ * The thread's title was set or changed while this run streamed (typically derived from the
+ * first exchange). Thread-level, not message content: a client updates its header/sidebar and
+ * does not render it in the transcript.
+ */
+ | {
+    kind: 'title';
+    title: string;
+}
 /**
  * Someone stopped this run. The stream's LAST frame, written by the runner that settled the
  * cancel, immediately before a normal `end()` — never a `fail()`, because a cancel is not an
@@ -1486,163 +711,6 @@ interface Retriever {
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
-/**
- * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
- * the prompt on its way out, an {@link OutputProcessor} inspects the answer on its way back and may
- * redact, replace or refuse it. Wire them as `AgentLoopDeps.inputProcessors` /
- * `outputProcessors`, or via `AgentModule.forRoot({ inputProcessors, outputProcessors })`.
- *
- * WHAT THESE ARE NOT: a second way to decide what enters the context. `HistoryPolicy` owns
- * SELECTION — which of the thread's messages ride into the turn, and what stands in for the rest.
- * Processors run on whatever selection produced and own TRANSFORMATION — what those messages say.
- * The distinction is load-bearing rather than stylistic: selection is contractually pure and is what
- * the `load:thread` checkpoint records, so it bounds the journal as well as the prompt, while a
- * processor is allowed to call a model, runs in a checkpoint of its own per step, and rewrites a
- * DERIVED prompt that never becomes the thread's own memory of what was said. Splitting the same
- * decision across both means neither can be reasoned about alone, and the cheap one stops being the
- * whole answer to "why did this turn cost that much".
- */
-
-/** Which turn, and which model step of it, a processor is looking at. */
-interface ProcessorContext {
-    threadId: string;
-    actor: Actor;
-    /** The agent running this turn. Undefined → the default agent. */
-    agentName?: string;
-    /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
-    step: number;
-}
-/** Everything the model is about to be sent, as the previous processor in the chain left it. */
-interface ProcessedPrompt {
-    /** The composed system prompt (agent base + contributors + any injected retrieval block). */
-    system: string;
-    /** The turn's messages, oldest-first, already through the history ceiling. */
-    messages: ModelMessage[];
-}
-/**
- * Rewrites the prompt before each model call of a turn — masking identifiers, stamping a policy
- * preamble, collapsing an oversized tool result. Runs on EVERY step, not once per run, because the
- * transcript grows between steps: a redactor that only saw the opening prompt would wave through
- * whatever a tool result carried back.
- *
- * Runs inside the loop's `process:input:<step>` checkpoint and its result is journaled, so a
- * processor may call a model or hit the network — a resumed run reads back the prompt the suspended
- * attempt built rather than composing a different one.
- */
-interface InputProcessor {
-    /** Identifies this processor in a failure. Keep it stable — it is user-visible on an error. */
-    readonly name: string;
-    process(prompt: ProcessedPrompt, ctx: ProcessorContext): ProcessedPrompt | Promise<ProcessedPrompt>;
-}
-/** One model step's answer, as the previous processor in the chain left it. */
-interface ModelAnswer {
-    /** The assembled assistant text for this step. */
-    text: string;
-    /** The tool calls the same step asked for. Read-only context — a processor cannot change them. */
-    toolCalls: readonly ToolCallRequest[];
-}
-/**
- * What an {@link OutputProcessor} decided. `pass` hands the text to the next processor unchanged;
- * `replace` hands it on rewritten (a redaction is a replacement); `reject` ends the chain AND the
- * run — the text is never streamed, never persisted, and the caller gets an
- * {@link OutputRejectedError} rather than an answer.
- */
-type OutputVerdict = {
-    action: 'pass';
-} | {
-    action: 'replace';
-    text: string;
-} | {
-    action: 'reject';
-    reason: string;
-};
-/**
- * Characters an incremental gate keeps holding at the end of the transformed answer, when a
- * processor declares {@link IncrementalGating} without naming its own window. Wide enough for the
- * patterns a redactor is usually written against — an SSN, an email address, a card number — and
- * deliberately not wider: the window IS the answer's minimum latency tail, since those characters
- * are only released once the whole-answer pass runs.
- */
-declare const DEFAULT_INCREMENTAL_LOOKBACK_CHARS = 64;
-/**
- * A processor's statement that its verdict on a PREFIX of an answer is worth acting on, which is
- * what lets the loop release that prefix to the reader instead of holding the whole answer.
- *
- * Declaring it is a promise about every prefix `P` of the final answer, and the loop takes it at
- * face value on the streaming path:
- *
- * 1. REJECTION IS PREFIX-DECIDABLE. The refusal this processor would return for the whole answer is
- *    already returned for the first prefix that contains the reason. A refusal that only emerges
- *    from the complete answer still fails the run, but by then the reader has seen a prefix — there
- *    is no un-sending bytes, and that is the cost of opting in.
- * 2. REPLACEMENT IS PREFIX-STABLE UP TO THE WINDOW. Once a character of `process(P)`'s output is
- *    more than {@link lookbackChars} from the end of that output, it never changes as `P` grows.
- *
- * A broken second promise is caught, not tolerated: the whole-answer pass stays authoritative, and
- * the loop raises a `ProcessorFailedError` when its result is not an extension of what the chain
- * already released. So a window too short for a pattern fails loudly rather than streaming the text
- * it was supposed to redact.
- */
-interface IncrementalGating {
-    /**
-     * How many characters of this processor's own output stay held back. Undefined →
-     * {@link DEFAULT_INCREMENTAL_LOOKBACK_CHARS}. Set it to the length of the longest pattern the
-     * processor can act on — anything shorter is a run that fails on the pattern it was written for.
-     */
-    readonly lookbackChars?: number;
-}
-/**
- * Inspects each model step's answer before anything downstream sees it — before it reaches the live
- * stream, before it is persisted, before it becomes the next step's context.
- *
- * Gating an answer and streaming it as it is generated are mutually exclusive, so registering ANY
- * output processor switches the turn's model call off the run's sink: nothing reaches the
- * subscriber until this chain has ruled on it — see `AgentLoopDeps.outputProcessors`. How much of
- * that costs the reader is what {@link incremental} decides.
- *
- * Runs inside the loop's `process:output:<step>` checkpoint (which also performs the release), so a
- * processor may call a model — a moderation pass is the motivating case — and a replay reads the
- * verdict back instead of re-deciding it.
- */
-interface OutputProcessor {
-    /** Identifies this processor in a rejection or a failure. User-visible; keep it stable. */
-    readonly name: string;
-    /**
-     * Opt this processor into gating a PREFIX, so the turn keeps streaming — see
-     * {@link IncrementalGating} for what declaring it promises. Undefined means the whole answer,
-     * which is what a processor written against the complete text needs and therefore the only safe
-     * default; a chain is incremental only when EVERY member of it declares this, so a neighbour can
-     * never downgrade what another author was given.
-     */
-    readonly incremental?: IncrementalGating;
-    process(answer: ModelAnswer, ctx: ProcessorContext): OutputVerdict | Promise<OutputVerdict>;
-}
-/**
- * The run ended because an output processor refused the answer — NOT because the model failed. The
- * two must stay distinguishable: a model failure is worth retrying and worth paging someone about,
- * a refusal is the control doing its job. Both runners map this to the `output_rejected` stream
- * error code.
- */
-declare class OutputRejectedError extends Error {
-    /** {@link OutputProcessor.name} of the processor that refused. */
-    readonly processor: string;
-    /** The reason it gave, verbatim. */
-    readonly reason: string;
-    constructor(processor: string, reason: string);
-}
-/**
- * A processor threw. Wrapped so it can never be mistaken for the model call failing — the loop's
- * only other source of failure at that point in the turn — and so the failure names the processor
- * that produced it instead of surfacing a bare `TypeError` from someone else's code.
- */
-declare class ProcessorFailedError extends Error {
-    /** Which seam it was on, so a reader knows whether the prompt or the answer was in flight. */
-    readonly phase: 'input' | 'output';
-    /** The processor's `name`. */
-    readonly processor: string;
-    constructor(phase: 'input' | 'output', processor: string, cause: unknown);
-}
-
 /**
  * Turns text into embedding vectors — the sibling of {@link import('./model-provider.js').ModelProvider}
  * for the retrieval side. Batched (`texts` → one vector each, same order) so ingestion can embed many
@@ -4211,4 +3279,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-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_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, 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, ASK_TOOL_DESCRIPTION, ASK_TOOL_NAME, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentHistoryWindow, type 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, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AskToolInput, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_INCREMENTAL_LOOKBACK_CHARS, DEFAULT_INTAKE_PREAMBLE, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, type DetachedDelivery, type DetailThreadRef, type ElicitationOption, type ElicitationOutcome, type ElicitationQuestion, type ElicitationReply, type ElicitationRequest, type ElicitationResult, type EmbeddingProvider, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, type HistoryPolicy, type HistoryPolicyContext, type HistorySelection, type HistorySummary, type HumanReply, type IncrementalGate, type IncrementalGating, type InputProcessor, type InvokeWithTransientRetryOptions, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, type LlmStepEnvelope, type LoadSkillInput, MAX_ASK_QUESTIONS, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, type MessageAttachment, type MessageRole, type MessageUsage, type ModelAnswer, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, type OutputProcessor, OutputRejectedError, type OutputVerdict, type OverriddenMemory, type PageContext, type Passage, type PendingApprovalRow, type ProcessedPrompt, type ProcessorContext, ProcessorFailedError, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type 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 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, type StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, type ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, type ToolDefinition, ToolDisabledError, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type ToolTransientRetryNumbers, type ToolTransientRetryOptions, type ToolTransientRetrySetting, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, askInputSchema, askToolDefinition, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, dayBoundsUtc, decodeStreamEvent, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, encodeStreamEvent, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, invokeWithTransientRetry, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, isTransientToolError, loadSkill, memoryForgetVerdict, memoryWriteVerdict, normalizeDelegation, normalizeElicitationReply, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, renderElicitationAnswers, repairInstruction, resolveElicitation, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, resolveToolTransientRetryNumbers, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleElicitation, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, traceLlmTurn, traceToolExecution, truncateDetailContent, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, writeMemory };
+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_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, 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, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentApprovalRequest, 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 AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type 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, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, 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, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type 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 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 ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, dayBoundsUtc, decodeStreamEvent, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, encodeStreamEvent, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, memoryForgetVerdict, memoryWriteVerdict, normalizeDelegation, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, traceLlmTurn, traceToolExecution, truncateDetailContent, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, writeMemory };