@dudousxd/nestjs-agent-core 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -1,6 +1,272 @@
 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
@@ -47,9 +313,10 @@ interface ToolTransientRetryNumbers {
 declare function resolveToolTransientRetryNumbers(setting: ToolTransientRetrySetting | undefined): ToolTransientRetryNumbers | false;
 interface InvokeWithTransientRetryOptions {
     /**
-     * Recognizes the runner's control-flow signals (durable suspend / continue-as-new) so a retry
-     * never swallows one — same rule the loop's tool catch already applies. Undefined for a call site
-     * with no such notion (e.g. the dispatched step handler, which has no workflow ctx of its own).
+     * 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;
     /**
@@ -76,13 +343,44 @@ interface Actor {
     roles?: string[];
     tenantRef?: string;
 }
-type ToolKind = 'read' | 'action' | 'agent';
+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;
@@ -96,6 +394,20 @@ interface ToolSpec {
     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[];
     /**
@@ -176,7 +488,14 @@ interface MessageUsage {
      */
     costUsd?: number | null;
 }
-type UsagePurpose = 'chat' | 'follow_ups';
+/**
+ * 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;
@@ -194,6 +513,12 @@ interface QuotaView {
     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;
@@ -273,9 +598,19 @@ interface AgentRunInput {
     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 {@link MAX_DELEGATION_DEPTH}.
+     * 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
@@ -283,6 +618,18 @@ interface AgentRunInput {
      * 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
@@ -305,10 +652,51 @@ interface AgentDefinition {
     systemPrompt?: string | PromptBuilder;
     /** Allow-list of tool names this agent may use (subset of all registered tools). */
     tools?: string[];
-    /** Names of other agents this agent may hand off to (auto-registered as `agent`-kind tools). */
-    delegatesTo?: 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
@@ -352,6 +740,8 @@ interface StoredMessage {
     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 {
@@ -370,6 +760,13 @@ interface LlmStepEnvelope {
     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
@@ -455,6 +852,23 @@ declare const AGENT_ATTACHMENT_STAGING: unique symbol;
  * {@link import('./spi/approval-port.js').AgentApprovalPort}.
  */
 declare const AGENT_APPROVAL_PORT: unique symbol;
+/**
+ * The resolved `SkillsConfig` (provider + scope resolver + ceiling), or `undefined` where the host
+ * configured no skills. Bound once and read by BOTH the loop's deps and the listing endpoint, so
+ * what a user can invoke and what the model can reach are the same resolution.
+ */
+declare const AGENT_SKILLS: unique symbol;
+/**
+ * The resolved `MemoryConfig` (provider + scope resolver + ceilings), or `undefined` where the host
+ * configured no memory. Bound once and read by BOTH the loop's deps and the read-back endpoint, so
+ * what a person is shown and what the model was shown are the same resolution.
+ */
+declare const AGENT_MEMORY: unique symbol;
+/**
+ * A shared, mutable list `SkillDiscoveryService` fills with `@Skill`-decorated providers. Read
+ * lazily by the bound {@link AGENT_SKILLS} provider — discovery runs after DI has built it.
+ */
+declare const AGENT_SKILL_SOURCES: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -555,6 +969,14 @@ interface ModelTurnArgs {
     /** The model writes streamed text deltas here as it generates them. */
     sink: SinkWriter;
     abortSignal?: AbortSignal;
+    /**
+     * Constrain this turn's reply to a schema (a provider's JSON/response-format mode). Set only on
+     * the loop's structured-output formatting pass, which always sends `tools: []` — most providers
+     * refuse a response format and a tool set in the same request, and the ones that accept both stop
+     * calling tools. A provider that cannot constrain generation may ignore this: the loop validates
+     * the reply against the same schema either way, so ignoring it costs reliability, not safety.
+     */
+    outputSchema?: StandardSchemaV1;
 }
 /** The outcome of ONE assistant turn. The loop — not the model — drives tool execution. */
 interface ModelTurnResult {
@@ -574,6 +996,41 @@ interface ModelTurnResult {
      * governance read-model uses it verbatim; otherwise it estimates from tokens × the pricing table.
      */
     costUsd?: number;
+    /**
+     * The reply already parsed, for a provider that constrained generation against
+     * {@link ModelTurnArgs.outputSchema} and therefore has the value in hand. A fast path only — the
+     * loop validates it against the schema regardless, so omitting it (and leaving the loop to read
+     * the JSON out of `text`) is always correct.
+     */
+    object?: unknown;
+}
+/**
+ * A model turn whose live frames were HELD instead of streamed, because an output processor has to
+ * see the whole answer before anything downstream does. Produced by whatever ran the model call —
+ * the loop itself, or the dispatched-step handler when the envelope asked for it — and released to
+ * the real sink by the loop once the gate has passed.
+ */
+interface BufferedModelTurnResult extends ModelTurnResult {
+    /** The NDJSON stream lines the call produced, in write order. */
+    bufferedFrames?: string[];
+    /**
+     * The transformed PREFIX an incremental gate already wrote to the run's sink while the call was
+     * streaming. Its presence — not the chain configured on the process that reads it back — is what
+     * tells the gate step which release this turn still owes, so a run that resumes under a
+     * re-declared chain cannot flush the same text twice. Empty string when an incremental gate ran
+     * and released nothing; absent when none ran.
+     */
+    releasedText?: string;
+    /**
+     * The refusal an incremental gate reached from a prefix, carried on the RESULT rather than thrown
+     * from the call. The loop raises it only after the turn's `persist:usage` and `quota:bump`
+     * checkpoints — those tokens were genuinely spent, and a gate that hid its own cost would let a
+     * mis-tuned chain burn a budget invisibly.
+     */
+    gateRejection?: {
+        processor: string;
+        reason: string;
+    };
 }
 /**
  * Thin wrapper over the actual LLM. The concrete impl (e.g. Vercel AI SDK `streamText`
@@ -644,9 +1101,41 @@ type AgentStreamEvent = {
     kind: 'tool-output-error';
     id: string;
     error: string;
+}
+/**
+ * The run has put a question set to the user and is parked until someone answers it (or skips).
+ * Written by the LOOP for both elicitation surfaces — the configured intake and the model's `ask`
+ * tool — so a client renders one form either way rather than learning to recognise a tool name.
+ * The matching `tool-output` frame, under the same `id`, carries the settled answers.
+ */
+ | {
+    kind: 'elicitation';
+    id: string;
+    request: ElicitationRequest;
+}
+/**
+ * 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
+ * error and a client that retries on a failed stream must not retry this.
+ *
+ * A run that simply ends wrote everything it had; one that ends after this frame did not, and the
+ * difference is the whole point: without it a reader cannot tell a truncated answer from a
+ * complete one. Consumers that predate the frame ignore it and see the `end()` they always saw.
+ */
+ | {
+    kind: 'cancelled';
 };
 /** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
 declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+/**
+ * Read one NDJSON line back, or `null` when the line is not a stream event at all.
+ *
+ * `null` covers a genuinely opaque chunk, not just malformed JSON: the sink is a byte channel, so a
+ * model provider is free to write anything into it and some write bare text. A caller that has to
+ * CLASSIFY a chunk — the output gate, which may only forward what it can prove is not the answer —
+ * treats an unreadable frame as unclassifiable rather than guessing.
+ */
+declare function decodeStreamEvent(line: string): AgentStreamEvent | null;
 
 interface CreateThreadInput {
     actor: Actor;
@@ -665,6 +1154,14 @@ interface AppendMessageInput {
     attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
+    /**
+     * The run (turn) that produced this message. Without it a consumer can only guess which turn a
+     * message belongs to by comparing timestamps against the run's `startedAt`, and that guess breaks
+     * the moment a turn is regenerated — the replaced answer is truncated away, so the times no longer
+     * line up 1:1. Optional so a caller predating this (and a host that appends messages outside a
+     * run) can omit it; the store persists it as `null` when absent.
+     */
+    runId?: string;
 }
 interface RecordToolCallInput {
     toolCallId: string;
@@ -709,16 +1206,67 @@ interface RecordRunStartInput {
     threadId: string;
     actorRef: string;
     agentName?: string;
+    /**
+     * The run that started this one, for a delegation's child run. The parent->child edge exists in
+     * the durable runtime's own journal, but only there: a governance surface reading run rows alone
+     * cannot roll a delegation's cost up to the turn that asked for it, and a DETACHED child outlives
+     * its parent's turn entirely, so nothing in the transcript pairs them either.
+     *
+     * Optional, and a store that persists nothing for it still works — it loses the tree, not the run.
+     */
+    parentRunId?: string;
     /** sha256 hex of the run's resolved (pre-RAG) system prompt — identifies the prompt VERSION. */
     promptHash?: string;
 }
 interface RecordRunEndInput {
     runId: string;
-    status: 'completed' | 'failed';
+    /**
+     * `cancelled` is a THIRD terminal, not a flavour of `failed`: someone asked the run to stop and it
+     * did, which is the control working. A consumer computing a failure rate over these rows has to be
+     * able to leave it out — counting a user pressing Stop as an error pages whoever is on call for
+     * model failures. It carries no `errorCode`/`errorMessage`, since there is nothing to diagnose.
+     */
+    status: 'completed' | 'failed' | 'cancelled';
     durationMs?: number;
     errorCode?: string;
     errorMessage?: string;
 }
+/** Which thread, and how many of its newest messages, {@link ThreadTurnReader.loadThreadForTurn} reads. */
+interface ThreadTurnQuery {
+    threadId: string;
+    /** Omitted reads every message; `0` reads none. */
+    messageLimit?: number;
+}
+/** What a turn reads off a thread — a bounded window, not the transcript. */
+interface ThreadTurnPage {
+    title: string;
+    defaultAgent: string | null;
+    /** Whether the THREAD has ever been answered, not whether {@link messages} holds an answer. */
+    hasAssistantMessage: boolean;
+    /** Oldest first, carrying only the fields a model turn reads. */
+    messages: StoredMessage[];
+}
+/**
+ * A store that can hand a turn the WINDOW it is about to send, instead of the thread's transcript.
+ *
+ * {@link AgentStore.getThread} materializes every message row, every attachment and every tool
+ * output a thread ever recorded, and the run then journals what it loaded — so a long thread pays
+ * for its whole history on every turn and again on every replay, to send a prompt bounded to its
+ * last few messages. This read is bounded by the database (`order by created_at desc limit ?`),
+ * projected to the columns a model turn actually reads.
+ *
+ * `hasAssistantMessage` is answered over the WHOLE thread, never the page: it answers "has this
+ * conversation been answered before?" — what a `thread-start` intake asks — and a thread whose window
+ * happens to hold only the user's last questions has still been answered. `null` for a thread that is
+ * unknown or soft-deleted, matching `getThread`.
+ *
+ * Probed STRUCTURALLY rather than declared on {@link AgentStore}, the same way `defaultAgentForThread`
+ * is: it is an optimization a store either offers or does not, and one that predates it still answers
+ * correctly through the full read.
+ */
+interface ThreadTurnReader {
+    loadThreadForTurn(query: ThreadTurnQuery): Promise<ThreadTurnPage | null>;
+}
 /** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
 interface AgentStore {
     createThread(input: CreateThreadInput): Promise<ThreadSummary>;
@@ -769,11 +1317,15 @@ interface AgentStore {
      */
     ownerOfToolCall(toolCallId: string): Promise<string | null>;
     /**
-     * The runId currently streaming the thread a tool call belongs to (its thread's `activeStreamId`),
-     * or `null` if the call or its active run is unknown. HITL approve / reject route the decision to
-     * THIS run, derived server-side from the tool call alone — so a decision reaches the exact run
+     * The run awaiting a decision on `toolCallId`: the call's OWN `runId` when the row carries one,
+     * else the thread's `activeStreamId`. Both HITL approve/reject and an elicitation answer route
+     * through this, derived server-side from the tool call alone — so a decision reaches the exact run
      * awaiting it, including a sub-agent's own child run, which the client never sees and could not
      * name. No client-supplied runId is trusted (or needed).
+     *
+     * The row's own runId comes FIRST because `activeStreamId` names whichever run is streaming the
+     * thread right now, and that is only the same run while a thread holds exactly one. The fallback
+     * is for rows written before tool calls recorded a runId, which have nothing else to answer with.
      */
     runForToolCall(toolCallId: string): Promise<string | null>;
     /**
@@ -783,9 +1335,43 @@ interface AgentStore {
      */
     ownerOfActiveStream(runId: string): Promise<string | null>;
     appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
+    /**
+     * Attach a turn's settled tool RESULTS to a message that was already appended, replacing whatever
+     * it held. A message's tool calls are known when it is written and their outputs are not, but a
+     * thread reader pairs the two off THAT MESSAGE — so an output that only ever reaches the tool-call
+     * table leaves every call on a reopened thread looking like a tool still running.
+     *
+     * Required rather than optional: a store that silently declines this renders a finished turn as a
+     * permanently in-flight one, with nothing logged and nothing to notice. A missing method should
+     * fail to compile instead.
+     */
+    setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
+    /**
+     * OPTIONAL: of `mediaIds`, the ones a message that still exists — in a thread owned by
+     * `actorRef` — still carries as an attachment. The inverse of
+     * {@link import('./attachment-staging.js').AttachmentStagingStore.list}: the host can enumerate
+     * the media it staged but cannot see a transcript, and this side sees every transcript but never
+     * holds the bytes, so neither can decide alone what is safe to delete.
+     *
+     * DERIVED, not tracked. A reference is not permanent: `truncateFrom` deletes messages — which is
+     * exactly what regenerating a turn does — so media that was referenced becomes unreferenced
+     * again. A flag set when a message is sent would never be unset by that delete, and the bytes
+     * would be pinned for ever with nothing pointing at them. Answering from the surviving message
+     * rows on every call is the only form of this that stays true after a truncation.
+     *
+     * Scoped to one actor, like every other read on this surface: media referenced only by ANOTHER
+     * actor's thread is reported unreferenced here, so this can never be turned into a probe for what
+     * exists in someone else's conversation. A host pairs it with its own per-actor inventory, so the
+     * candidate ids are already the caller's own.
+     *
+     * Returns each id at most once, in the order asked. Absent on a store that predates this — a
+     * caller must treat the absence as "cannot answer" and collect NOTHING, never as "nothing is
+     * referenced", which would delete every attachment the actor ever sent.
+     */
+    referencedMediaIds?(actorRef: string, mediaIds: readonly string[]): Promise<string[]>;
     recordUsage(input: RecordUsageInput): Promise<void>;
     /**
      * The actor's spend for `day` (UTC): total tokens plus the summed provider-reported USD cost.
@@ -879,6 +1465,163 @@ 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
@@ -919,8 +1662,12 @@ interface AgentRunner {
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    /** Deliver a HITL decision for a pending action tool call. */
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    /**
+     * Deliver a human's reply to a parked tool call — a {@link import('../types.js').Decision} on an
+     * action tool, or an `ElicitationReply` answering a question set. One channel for both, because
+     * both park the run the same way and a runner has no reason to tell them apart.
+     */
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
     cancel(runId: string): Promise<void>;
 }
 
@@ -1048,7 +1795,11 @@ interface RecentRunRow {
     threadId: string;
     actorRef: string;
     agentName: string | null;
-    /** 'running' | 'completed' | 'failed'. */
+    /**
+     * `'running'` | `'completed'` | `'failed'` | `'cancelled'`. `cancelled` is a terminal of its own —
+     * someone asked the run to stop and it did — so a consumer computing a failure rate over these
+     * rows has to be able to leave it out rather than fold it into `failed`.
+     */
     status: string;
     durationMs: number | null;
     errorCode: string | null;
@@ -1058,6 +1809,14 @@ interface RecentRunRow {
     startedAt: string;
     /** sha256 hex of the run's resolved (pre-RAG) system prompt; `null` for a run recorded before this shipped. */
     promptHash: string | null;
+    /**
+     * The run that delegated this one; `null` for a turn nobody delegated, and for any run recorded
+     * before the column existed. Pairing a child with its parent is what lets a console draw the
+     * delegation tree and roll a child's cost up to the turn that asked for it — and for a DETACHED
+     * child it is the only pairing there is, since it outlives its parent's turn and the transcript
+     * holds no other link.
+     */
+    parentRunId: string | null;
 }
 /** One tool call awaiting a HITL decision, for the cross-thread approvals inbox. */
 interface PendingApprovalRow {
@@ -1335,13 +2094,57 @@ interface StageAttachmentInput {
     sizeBytes: number;
     actor: Actor;
 }
+/**
+ * All a chat turn may say about a file it attaches: the id of something already staged. Everything
+ * else about the attachment (url, content type, name) is read back from the staging store, never
+ * from the request — see {@link AttachmentStagingStore.resolve}.
+ */
+interface AttachmentRef {
+    mediaId: string;
+}
+/** Input to {@link AttachmentStagingStore.resolve} — the claimed id plus who is claiming it. */
+interface ResolveAttachmentInput {
+    mediaId: string;
+    actor: Actor;
+}
+/**
+ * One entry in an actor's staged-media inventory: enough to show the file and to decide whether it
+ * has aged out, and nothing more.
+ *
+ * Carries no url, unlike {@link MessageAttachment}. A url is minted per turn by
+ * {@link AttachmentStagingStore.resolve} precisely so it can be short-lived; a listing that handed
+ * one back would mint a fetchable url for every entry on the page, for a caller that asked to see
+ * a file list. Whoever needs the bytes goes through `resolve` and is checked there.
+ */
+interface StagedAttachment {
+    mediaId: string;
+    /** Original filename, as `stage` received it. */
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+    /** ISO-8601 UTC instant the bytes were staged — what an age threshold is measured against. */
+    createdAt: string;
+}
+/** Input to {@link AttachmentStagingStore.list} — whose inventory, and how much of it. */
+interface ListStagedAttachmentsInput {
+    actor: Actor;
+    /**
+     * Only media staged strictly before this ISO-8601 UTC instant. This is how a caller expresses
+     * "old enough to be worth looking at": freshly staged media belongs to an upload the user has
+     * not sent yet, which is in flight rather than garbage. The instant comes from the caller
+     * because how long a composer may sit open is the host's knowledge, not this library's.
+     */
+    stagedBefore?: string;
+    /** Cap on entries returned, newest first. */
+    limit?: number;
+}
 /**
  * Optional upload-side seam for message attachments (an image/PDF a user attaches to a chat
  * message before the model ever sees it). The lib never fetches bytes itself — {@link MessageAttachment.url}
  * must already be reachable by the model provider — so something has to turn an uploaded file into
  * that URL first. A store adapter (or a thin wrapper over the host's own media pipeline) implements
  * this; consumers inject via `AGENT_ATTACHMENT_STAGING`. Unbound, the optional `POST /agent/attachments`
- * upload controller is never mounted.
+ * upload controller is never mounted, and a chat turn cannot carry attachments at all.
  */
 interface AttachmentStagingStore {
     /**
@@ -1350,10 +2153,44 @@ interface AttachmentStagingStore {
      * returned url must be reachable by the model provider.
      */
     stage(input: StageAttachmentInput): Promise<MessageAttachment>;
-}
-
-/**
- * Console-side HITL decisions. Implemented by the agent runtime (the nestjs package binds it to
+    /**
+     * Turn a `mediaId` a chat turn claims back into the attachment to send with it, or `null` when
+     * the id is unknown OR is not this actor's. The two cases are deliberately indistinguishable, so
+     * the chat endpoint cannot be used to probe which media ids exist.
+     *
+     * SECURITY: this is the ONLY source of a url the model provider will be asked to fetch. The chat
+     * endpoint discards every other field a client sends and rebuilds each attachment from here — an
+     * implementation that echoes back a url taken from the request reopens the SSRF this seam exists
+     * to close. Called once per turn, so a short-lived presigned url is minted fresh rather than
+     * replayed stale.
+     */
+    resolve(input: ResolveAttachmentInput): Promise<MessageAttachment | null>;
+    /**
+     * OPTIONAL: the actor's staged media, newest first. The host staged these bytes, so only the host
+     * can enumerate them — this library holds references, never an inventory.
+     *
+     * Pairs with {@link import('./agent-store.js').AgentStore.referencedMediaIds}, which answers the
+     * half only the library can: of these ids, which a live message still carries. Together they are
+     * a sweep — inventory minus references, restricted to entries old enough not to be an upload in
+     * flight. Deleting whatever is left is the host's call and the host's alone; this library never
+     * removes a host's bytes.
+     *
+     * Scoped to `input.actor` without exception. An implementation that ignores it turns a file list
+     * into a way to read someone else's documents.
+     *
+     * `stagedBefore` and `limit` are the store's to apply — but a caller on a delete path must not
+     * assume they were, since getting that wrong deletes files. `AgentService.collectableAttachments`
+     * re-applies the age cut on the results for that reason.
+     *
+     * Absent on a store that predates this: there is no inventory to fall back on, so listing and
+     * collection are simply unavailable (the read surface answers 501) rather than quietly empty —
+     * an empty inventory and an unanswerable one look identical and mean opposite things.
+     */
+    list?(input: ListStagedAttachmentsInput): Promise<StagedAttachment[]>;
+}
+
+/**
+ * Console-side HITL decisions. Implemented by the agent runtime (the nestjs package binds it to
  * the same signal path chat approvals use); the dashboard injects it OPTIONALLY — absent = the
  * approvals inbox renders read-only.
  */
@@ -1450,7 +2287,7 @@ declare function dayBoundsUtc(range: GovernanceRange): {
  */
 declare function isToolEnabled(spec: ToolSpec, handler?: ToolHandler): Promise<boolean>;
 /**
- * Zeroth filter layer: drop tools this deployment has turned off, before anyone asks who may call
+ * Second filter layer: drop tools this deployment has turned off, before anyone asks who may call
  * them. A disabled tool is absent, not forbidden — the difference matters, because "forbidden"
  * tells the model (and the user reading a refusal) that the capability exists.
  */
@@ -1464,18 +2301,1011 @@ declare function filterToolsByEnabled<T extends {
  */
 declare function canActorUseTool(actor: Actor, handler?: ToolHandler): Promise<boolean>;
 /**
- * Third filter layer: drop tools whose own `canUse` refuses this actor. Runs after the app-wide
+ * Fourth filter layer: drop tools whose own `canUse` refuses this actor. Runs after the app-wide
  * `RolesPolicy`, and is additive to it — a tool can narrow who reaches it, never widen.
  */
 declare function filterToolsByCanUse<T extends {
     spec: ToolSpec;
     handler?: ToolHandler;
 }>(entries: T[], actor: Actor): Promise<T[]>;
-/** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
+/** Third filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
-/** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
+/**
+ * First filter layer: if the agent pins an allow-list, keep only those tool names. Pure and
+ * synchronous, which is why it runs ahead of the three gates that may do I/O — see
+ * `ToolRegistry.definitionsFor`.
+ */
 declare function filterToolsByAllowList(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
 
+/**
+ * The built-in {@link HistoryPolicy}: keep the newest messages that fit a count and/or a token
+ * budget, and (optionally) fold the rest into a summary. See `./spi/history-policy.ts` for the seam
+ * itself and the determinism contract `select` has to hold to.
+ */
+
+/**
+ * Rough token count for one message: ~4 characters per token over its content and its serialized
+ * tool calls/results, plus a small per-message envelope allowance for the role and part framing.
+ *
+ * A heuristic on purpose. A real tokenizer is model-specific and would drag a provider dependency
+ * into core, while a budget only has to be approximately right to keep a thread clear of the
+ * provider's hard limit — and it must be a pure function, because it runs inside `select`. Pass
+ * `estimate` to {@link windowHistory} to substitute a real one.
+ */
+declare function estimateMessageTokens(message: ModelMessage): number;
+interface WindowHistoryOptions {
+    /** Keep at most this many of the newest messages. Omit → no count limit. */
+    maxMessages?: number;
+    /** Keep the newest messages whose estimated tokens fit this budget. Omit → no token limit. */
+    maxTokens?: number;
+    /** Substitute for {@link estimateMessageTokens}. Must be pure — it runs inside `select`. */
+    estimate?: (message: ModelMessage) => number;
+    /** Folds the dropped messages into a leading summary. Omit → they are simply gone. */
+    summarize?: HistoryPolicy['summarize'];
+}
+/**
+ * Keep the newest messages that fit. Both limits apply when both are set — whichever cuts more wins.
+ * Neither set is a policy that keeps everything, which is what an unconfigured loop already does.
+ *
+ * A naive slice is safe here because a tool exchange is ONE message: the loop persists a call's
+ * results onto the same assistant message that made them (`toolCalls` + `toolResults`), and each
+ * model adapter expands that into the assistant/tool pair the provider wants. So a cut can't orphan
+ * a tool result from its call, the way it could against a provider-shaped transcript.
+ */
+declare function windowHistory(options: WindowHistoryOptions): HistoryPolicy;
+/**
+ * What a summarizer is told to produce when none is supplied. Written for a reader who will continue
+ * the conversation without seeing the messages themselves, so it asks for the parts a later turn
+ * still has to act on rather than a readable recap.
+ */
+declare const DEFAULT_HISTORY_SUMMARY_INSTRUCTION = "Summarize this conversation for an assistant that will continue it without seeing these messages. Preserve decisions made, facts and constraints the user stated, identifiers and names mentioned, and anything left unresolved. Omit pleasantries. Reply with the summary only \u2014 no preamble, no headings.";
+/**
+ * A {@link HistoryPolicy.summarize} backed by one extra, non-streamed model call — what
+ * `AgentModule.forRoot({ history: { summarize: true } })` binds. Writes to a discarding sink so the
+ * summary's tokens never reach the user's live stream, and reports its usage so the call lands in
+ * the spend read-model like any other.
+ */
+declare function summarizeWithModel(model: ModelProvider, instruction?: string): NonNullable<HistoryPolicy['summarize']>;
+
+/**
+ * Running the processor chains, and the stream buffering an output gate requires. See
+ * `./spi/processors.ts` for the seams themselves and the boundary against `HistoryPolicy`.
+ */
+
+/**
+ * Holds a model call's stream frames instead of letting them reach the subscriber. `end`/`fail` are
+ * swallowed for the same reason `childSinkWriter` swallows them: the loop owns the run's stream
+ * lifecycle across however many steps the turn takes, and the model call is one step of it.
+ *
+ * Frames are kept as the decoded NDJSON LINES rather than the raw `Uint8Array`s so the buffer can
+ * ride a durable checkpoint — the gate has to survive a suspend between the model call and the
+ * verdict, and bytes do not round-trip through JSON.
+ */
+interface FrameBuffer {
+    writer: SinkWriter;
+    /** Everything written so far, one entry per NDJSON line, in write order. */
+    frames(): string[];
+}
+declare function createFrameBuffer(): FrameBuffer;
+/**
+ * The chunks a passed gate releases to the live stream: the held frames, with every text frame
+ * collapsed into ONE carrying `text` — the answer as the chain left it, which is the only version
+ * anything downstream is allowed to see.
+ *
+ * A frame that does not decode is dropped along with them. It cannot be forwarded, because a gate
+ * that forwards bytes it cannot classify is not a gate: a provider writing bare text into the sink
+ * (rather than the `AgentStreamEvent` vocabulary) would otherwise stream the ungated answer past
+ * the processor that was supposed to hold it. That is the cost of an output gate for a provider
+ * outside the encoded vocabulary, and it is stated in `AgentLoopDeps.outputProcessors`.
+ */
+declare function releaseGatedFrames(frames: readonly string[], text: string): Uint8Array[];
+/**
+ * Fold the prompt through each processor in order, every one seeing what the previous one produced.
+ * A throw is wrapped so it cannot read as the model call failing — see {@link ProcessorFailedError}.
+ */
+declare function runInputProcessors(processors: readonly InputProcessor[], prompt: ProcessedPrompt, ctx: ProcessorContext): Promise<ProcessedPrompt>;
+/** A settled output chain: the answer as the chain left it, plus who refused it if anyone did. */
+interface OutputGateResult {
+    /** The text every downstream consumer sees — the stream, the persisted message, the next step. */
+    text: string;
+    /** Set only on a refusal; the run ends with an `OutputRejectedError` naming these. */
+    rejection?: {
+        processor: string;
+        reason: string;
+    };
+}
+/**
+ * Fold the answer through each processor in order. The FIRST rejection ends the chain: a later
+ * processor has nothing to add about text that is never going anywhere, and running it would bill
+ * a moderation call for a turn already refused.
+ */
+declare function runOutputProcessors(processors: readonly OutputProcessor[], answer: ModelAnswer, ctx: ProcessorContext): Promise<OutputGateResult>;
+/**
+ * Put each suggestion through the output chain on its own, and keep what survives.
+ *
+ * A follow-up is model-generated text that gets persisted and rendered, so the gate has to see it.
+ * What it does NOT get is the chain's usual answer to a refusal — ending the run. The suggestions
+ * are produced AFTER the turn's answer has already cleared the same chain, and retracting a cleared
+ * answer because a question nobody asked for was refused would make a run's outcome depend on a
+ * by-product. Dropping the suggestion removes it just as completely, which is what the refusal was
+ * for. A `replace` is honoured; a processor that empties one drops it too, since an empty suggestion
+ * is nothing to render.
+ *
+ * One suggestion at a time rather than the joined list, so a refusal is confined to the one that
+ * earned it and a `replace` cannot smear across a neighbour.
+ */
+declare function gateFollowUps(processors: readonly OutputProcessor[], followUps: readonly string[], ctx: ProcessorContext): Promise<string[]>;
+/**
+ * How much of a turn's stream an output chain costs the reader.
+ *
+ * `off` — nothing registered, the model writes straight to the run's sink.
+ * `whole` — at least one processor needs the complete answer, so every frame is held until the
+ * chain has passed and the answer arrives as one `text` frame.
+ * `incremental` — every processor declared {@link IncrementalGating}, so a lookback-bounded prefix
+ * is released while the call streams.
+ */
+type OutputGateMode = 'off' | 'whole' | 'incremental';
+/**
+ * ALL or nothing: one undeclared processor puts the whole chain on the whole-answer path. Its
+ * author wrote `process` against the complete text, and a chain that ran it on a prefix because a
+ * neighbour opted in would be handing it an input it never agreed to read.
+ */
+declare function resolveOutputGateMode(processors: readonly OutputProcessor[]): OutputGateMode;
+/**
+ * The chain's window is the WIDEST any member asked for: a release safe for the shortest-sighted
+ * processor is not safe for the one that matches longer patterns, and the gate makes one release
+ * decision for all of them.
+ *
+ * An undeclared processor contributes nothing rather than the default — it has no window, because a
+ * chain containing one never reaches the incremental path at all.
+ */
+declare function resolveGateLookback(processors: readonly OutputProcessor[]): number;
+/** A live gate over one model call: the sink the model writes to, plus what it let through. */
+interface IncrementalGate {
+    /** Hand this to the model instead of the run's writer. */
+    writer: SinkWriter;
+    /** Resolves once every chunk handed to {@link writer} has been ruled on. */
+    settled(): Promise<void>;
+    /** The transformed prefix already written to the run's sink. */
+    released(): string;
+    /** Set once a prefix was refused; nothing further was released after that. */
+    rejection(): OutputGateResult['rejection'];
+}
+/**
+ * Releases a model call's answer to `writer` as it arrives, holding back the last `lookbackChars`
+ * characters of what the chain produces so a processor can still change them.
+ *
+ * The chain runs over the whole PREFIX accumulated so far rather than over each new chunk, so a
+ * processor always sees well-formed text and never has to reassemble a pattern split across
+ * frames — which is what makes {@link IncrementalGating}'s promise a claim about prefixes. It runs
+ * once per streamed `text` frame.
+ *
+ * Only an EXTENSION of what the reader already has is ever written: a chain whose output stops
+ * agreeing with its earlier output has broken its promise, and the loop's whole-answer pass reports
+ * that rather than this gate papering over it by re-sending a different answer.
+ *
+ * Frames that are not text are forwarded live, in arrival order. They are not the answer, so the
+ * gate does not own them — but it does drop any frame it cannot decode, for the same reason
+ * {@link releaseGatedFrames} does: a gate that forwards bytes it cannot classify is not a gate.
+ */
+declare function createIncrementalGate(options: {
+    processors: readonly OutputProcessor[];
+    ctx: ProcessorContext;
+    lookbackChars: number;
+    writer: SinkWriter;
+}): IncrementalGate;
+/**
+ * The tail an incremental gate still owes the reader once the whole-answer pass has settled: the
+ * authoritative text minus the prefix already released.
+ *
+ * Throws when the settled answer is not an extension of that prefix. That check is the reason the
+ * final pass stays authoritative for both the stream and the store rather than the stream being
+ * stitched together from per-prefix results: agreement between what was streamed and what was
+ * stored becomes structural instead of assumed.
+ */
+declare function gateTail(processors: readonly OutputProcessor[], released: string, text: string): string;
+
+/**
+ * Constraining a turn's ANSWER to a schema. See `AgentLoopDeps.outputSchema` for where this sits in
+ * the loop and why it is a separate model call rather than a constraint on the turn's own calls.
+ */
+
+/**
+ * The turn produced an answer that does not satisfy `outputSchema`, and the bounded repair attempts
+ * did not fix it. A DEFINED outcome of asking for structured output, not a crash: it carries the
+ * validation issues and the text that failed them, so a caller can log what the model actually said
+ * instead of guessing from a parse error. Both runners map it to the `structured_output_invalid`
+ * stream error code.
+ */
+declare class StructuredOutputError extends Error {
+    /** Why it failed the schema. Empty only when the text was not JSON at all. */
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    /** The last text the model produced, verbatim. */
+    readonly text: string;
+    /** How many model calls were spent trying (1 = the formatting pass, no repairs). */
+    readonly attempts: number;
+    constructor(issues: readonly StandardSchemaV1.Issue[], text: string, attempts: number);
+}
+/** A validated answer, or the issues that stopped it being one. */
+type StructuredOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: readonly StandardSchemaV1.Issue[];
+};
+/**
+ * Pull a JSON value out of a model reply, tolerating the code fences and lead-in prose a provider
+ * that cannot constrain its own generation still emits. `undefined` when there is no JSON in there
+ * at all — distinct from a JSON `null`, which is a value the schema may well accept.
+ */
+declare function extractJson(text: string): unknown;
+/**
+ * Validate one attempt. The provider's own parsed `object` is preferred when it reported one (a
+ * provider that constrained generation already did the parse), but it is validated all the same —
+ * "the provider says it matched" is not the same claim as "it matches", and a provider that ignored
+ * `outputSchema` entirely must fail here rather than downstream.
+ */
+declare function validateStructured<T>(schema: StandardSchemaV1<unknown, T>, text: string, reported: unknown): Promise<StructuredOutcome<T>>;
+/**
+ * What the formatting pass is told to do. Written for a model that is being shown a finished answer
+ * and asked to restate it — never to extend or improve it, which would make the structured result
+ * disagree with the prose the user already read.
+ */
+declare const DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION = "Restate the assistant's final answer as a single JSON value matching the required schema. Use only information already present in the conversation \u2014 add nothing, and answer nothing that was not asked. Reply with ONLY the JSON: no prose, no explanation, no code fences.";
+/** Appends the previous attempt's validation issues, so a repair call knows what to fix. */
+declare function repairInstruction(instruction: string, issues: readonly StandardSchemaV1.Issue[]): string;
+
+/**
+ * Skills: an authored procedure the model pulls in when a task calls for it, instead of every
+ * instruction living in the system prompt.
+ *
+ * WHAT A SKILL IS NOT: an agent. An `@Agent` is WHO is answering — its persona, its tools, its
+ * history ceiling, its output schema. A skill is HOW one particular task is done, and any agent may
+ * pull one in. That is why a skill carries no model, no tool list and no schema: the moment it did,
+ * the two would be the same thing wearing different names, and a consumer would have to choose
+ * between them for reasons nobody could state.
+ *
+ * WHAT IT COSTS THE PROMPT: one line per skill. The catalog block below carries names, scopes and
+ * descriptions only; a BODY reaches the model as a tool result, on the transcript, where the
+ * `HistoryPolicy` ceiling already governs it. So skills are not a fourth thing competing for the
+ * system block with the agent's own prompt, its contributors and injected retrieval — see
+ * `AgentLoopDeps.skills` for how the four compose.
+ */
+
+/** How a skill is identified in the catalog, to the model and to a `/`-autocomplete alike. */
+interface SkillSummary {
+    /** Unique within a scope. The handle the model passes to the `skill` tool. */
+    name: string;
+    /** One line: what task this covers, and therefore when to load it. Read by the MODEL to choose. */
+    description: string;
+    /** The opaque scope token this skill is published at — see {@link ScopeResolver}. */
+    scope: string;
+}
+/** A skill with the instructions themselves. Only ever materialized when something loads it. */
+interface Skill extends SkillSummary {
+    body: string;
+}
+/** Whose turn is asking, and therefore which scopes apply. */
+interface ScopeContext {
+    actor: Actor;
+    threadId: string;
+    /** The agent running this turn. Undefined → the default agent. */
+    agentName?: string;
+    pageContext?: PageContext;
+}
+/**
+ * The skills-facing name for {@link ScopeContext}, so a `SkillProvider`'s signature reads in its own
+ * vocabulary. Deliberately the SAME type rather than a parallel one: skills and memory resolve
+ * scopes through one `ScopeResolver`, and a deployment that could answer "which scopes does this
+ * actor have" twice would eventually answer it differently.
+ */
+type SkillContext = ScopeContext;
+/** The scope token every deployment has: skills nobody narrowed. */
+declare const GLOBAL_SCOPE = "global";
+/** The token for one actor's own skills. */
+declare function actorScope(actor: Actor): string;
+/** The token for a tenant's skills — `Actor.tenantRef` is the only tenant key this library knows. */
+declare function tenantScope(tenantRef: string): string;
+/**
+ * Which scopes a turn may draw skills from, MOST SPECIFIC FIRST. Precedence is the order: a skill
+ * from an earlier token outranks a same-named one from a later token, and the model is shown which
+ * of them won.
+ *
+ * A HOST-SUPPLIED FUNCTION rather than an enum this library owns, because the axes a deployment
+ * scopes by are the deployment's own. `Actor` gives an id and a tenant; it does not give a sector, a
+ * squadron, a base, a shift — and every one of those is a real axis in some consumer. An enum here
+ * would make each of them a schema change in a library that has no business knowing they exist,
+ * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:base-7',
+ * 'global']` and precedence follows, with nothing in this package edited.
+ *
+ * MUST be a pure function of its context. It runs inside the `skills:catalog` checkpoint and its
+ * result is journaled, so a resumed run reads back the scopes the first attempt resolved rather than
+ * asking a membership table that may have changed since — which would otherwise let a run's prompt
+ * differ from the one its journal records. Read a database here at your peril; read it in the
+ * provider, whose answer is journaled at the same position.
+ */
+interface ScopeResolver {
+    resolve(ctx: SkillContext): string[] | Promise<string[]>;
+}
+/**
+ * The scopes derivable from an {@link Actor} alone — the common case, so a consumer wiring skills
+ * for the first time supplies no resolver at all: the actor's own, their tenant's (when they have
+ * one), and the deployment's. A host adding an axis of its own replaces this rather than extending
+ * it, since the ORDER is the precedence and only the host knows where its axis belongs.
+ */
+declare const defaultScopeResolver: ScopeResolver;
+/**
+ * Where skills come from. Deliberately two calls rather than one: `list` is asked on EVERY turn and
+ * must stay cheap, while a body is read only when the model decides it needs that procedure — the
+ * whole point of the surface. A provider over a table selects name/description/scope for the first
+ * and one row for the second.
+ *
+ * This library owns no skill table. A skill's real scoping axes, its authoring UI and its audit
+ * trail are all the host's, and a host that related its own `Sector` entity into a table this
+ * package created at boot would be writing migrations against a schema the boot-time heal also
+ * edits. Tokens split it the other way round: the library owns the contract (what a scope means, how
+ * precedence works, what is journaled), the host owns the rows.
+ */
+/** Arguments to {@link SkillProvider.list}. */
+interface ListSkillsInput {
+    scopes: readonly string[];
+    ctx: SkillContext;
+}
+/**
+ * Arguments to {@link SkillProvider.load}. An object rather than positional arguments because
+ * `name` and `scope` are both strings: transposed, a positional call compiles clean, returns `null`,
+ * and the skill silently fails to load.
+ */
+interface LoadSkillInput {
+    name: string;
+    scope: string;
+    ctx: SkillContext;
+}
+interface SkillProvider {
+    /**
+     * Every skill visible at `scopes`, in any order — this library sorts and resolves precedence. A
+     * provider MAY return skills outside `scopes`; they are dropped rather than trusted, so a filter
+     * bug in a host cannot widen what an actor is offered.
+     */
+    list(input: ListSkillsInput): SkillSummary[] | Promise<SkillSummary[]>;
+    /**
+     * The instructions for one skill, or `null` when it is gone. Called only from inside the loading
+     * checkpoint, so the body it returns is journaled and every replay reads THAT text back — an
+     * edited skill never rewrites the prompt of a run already in flight.
+     */
+    load(input: LoadSkillInput): string | null | Promise<string | null>;
+}
+/** A source of skills that is a fixed list — `@Skill()`-decorated classes, or plain config. */
+declare function staticSkillProvider(skills: readonly Skill[]): SkillProvider;
+/**
+ * Read several sources as one. The order is the tie-break and nothing else: precedence between
+ * skills is by SCOPE, so two sources only ever compete when they publish the same name at the same
+ * scope, and then the earlier source wins. Wire the host's own provider first — a row it can edit is
+ * a better answer than a body that needs a deploy to change.
+ */
+declare function compositeSkillProvider(providers: readonly SkillProvider[]): SkillProvider;
+/**
+ * One skill as it is offered — to the model in the catalog block, and to a client over
+ * `GET /agent/skills`. Both read the same list, built by the same call, so what a user can type
+ * after a `/` and what the model can reach cannot drift apart.
+ */
+interface SkillCatalogEntry {
+    name: string;
+    description: string;
+    /** The scope token it resolved from — the provenance a user is entitled to see. */
+    scope: string;
+    /**
+     * Scope tokens of same-named skills this one outranks, widest last. Present ONLY when something
+     * was shadowed, so a reader can tell "there is no org default" from "there is one and yours wins".
+     * The model is shown it for the same reason: a silent override is indistinguishable from an
+     * instruction nobody wrote, and the user can only be told "your setting differs from the org
+     * default" by something that knows both existed.
+     */
+    shadows?: string[];
+}
+/** What a turn resolved — journaled whole, so the prompt is reconstructible from the journal alone. */
+interface SkillOffer {
+    /** The scope tokens this turn drew from, most specific first. */
+    scopes: string[];
+    /** The skills offered, most specific first then by name. */
+    entries: SkillCatalogEntry[];
+    /** Applicable skills `maxSkills` left out. Non-zero means the catalog is not the whole truth. */
+    omitted: number;
+}
+/**
+ * How many skills a catalog offers before it starts leaving some out. A ceiling on the SYSTEM
+ * PROMPT's share, not on how many a deployment may have: the block costs one line each, and a
+ * hundred lines of "here is something you could load" crowds out the agent's own instructions while
+ * making the choice harder rather than easier.
+ */
+declare const DEFAULT_MAX_SKILLS = 20;
+/** How a turn reaches its skills. See `AgentLoopDeps.skills`. */
+interface SkillsConfig {
+    provider: SkillProvider;
+    /** Undefined → {@link defaultScopeResolver}: the actor's own, their tenant's, the deployment's. */
+    scopes?: ScopeResolver;
+    /** Undefined → {@link DEFAULT_MAX_SKILLS}. */
+    maxSkills?: number;
+}
+/**
+ * Resolve a provider's skills against an ordered scope list: most specific wins, and the loser's
+ * scope is recorded rather than discarded.
+ *
+ * Pure, and separately exported, because two callers must reach the identical answer — the loop, so
+ * the model is offered it, and the listing endpoint, so a user is. A second implementation of
+ * "which skills apply" is a second answer, and the two diverge the first time either is edited.
+ */
+declare function resolveSkillCatalog(summaries: readonly SkillSummary[], scopes: readonly string[], maxSkills?: number): Omit<SkillOffer, 'scopes'>;
+/** Resolve the scopes and the catalog for one turn. Called INSIDE the loop's `skills:catalog` step. */
+declare function offerSkills(config: SkillsConfig, ctx: SkillContext): Promise<SkillOffer>;
+/**
+ * The catalog as the model reads it. One line per skill — name, scope, description, and what it
+ * overrides — because the entire claim of progressive disclosure is that choosing what to read costs
+ * far less than reading everything.
+ */
+declare function buildSkillsBlock(entries: readonly SkillCatalogEntry[]): string;
+/** The reserved name of the built-in skill-loading tool. */
+declare const SKILL_TOOL_NAME = "skill";
+/** What the model passes to the `skill` tool. */
+interface SkillToolInput {
+    name: string;
+}
+/**
+ * The `skill` tool's input schema. Hand-written for the same reason `askInputSchema` is: core
+ * depends on no validator and the schema has to publish a JSON Schema a provider can constrain
+ * generation against.
+ *
+ * The available names are deliberately NOT an enum here. A per-turn enum would make the tool's
+ * definition depend on the catalog — and the dispatched llm step re-derives the tool list on
+ * whichever worker serves it, from ITS OWN provider, which is exactly the process-local lookup this
+ * design keeps off the turn's decisions. The names live in the prompt, where the journal holds them;
+ * a name that is not in the catalog comes back as an ordinary tool failure listing the ones that are.
+ */
+declare const skillInputSchema: StandardSchemaV1<unknown, SkillToolInput>;
+declare const SKILL_TOOL_DESCRIPTION = "Read one of the procedures listed in <skills>. Call it before doing a task a listed skill covers, and follow what it returns. It performs nothing and changes nothing \u2014 it only gives you instructions you do not yet have.";
+/**
+ * The `skill` tool as the model sees it. NOT a `ToolSpec` and never registered, exactly like `ask`:
+ * it has no handler, because the loop serves it from the catalog the journal holds. Keeping it out
+ * of the `ToolRegistry` is also what keeps its kind off a process-local lookup — see `claimToolCall`.
+ */
+declare function skillToolDefinition(): ToolDefinition;
+/**
+ * Append the built-in `skill` definition to a turn's tool list. Exported because the dispatched llm
+ * step re-derives the tool list on a worker and has to reach the same list the loop would have.
+ */
+declare function withSkillTool({ tools, enabled, }: {
+    tools: ToolDefinition[];
+    enabled: boolean;
+}): ToolDefinition[];
+/** What a `skill` call resolved to — the body, or why it did not. */
+type SkillLoadOutcome = {
+    ok: true;
+    skill: Skill;
+    shadows?: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Serve one `skill` call against the catalog THIS TURN was offered.
+ *
+ * The catalog is the authorization boundary, not just a menu: a name the turn was never offered is
+ * refused here, so a model that invents one (or repeats one it saw in another actor's thread) cannot
+ * reach a body through a provider that would happily serve it. Because the catalog came out of the
+ * `skills:catalog` checkpoint, that boundary is the one the journal records rather than the one this
+ * process's provider currently believes in.
+ */
+declare function loadSkill(config: SkillsConfig, offer: SkillOffer, name: string, ctx: SkillContext): Promise<SkillLoadOutcome>;
+/** Who is trying to write a skill. */
+interface SkillAuthor {
+    /**
+     * `'human'` is a person acting through a UI; `'agent'` is anything else — a tool, a turn, a
+     * batch job. The distinction is the whole of the rule below, so it is not inferable and has to
+     * be stated by the caller.
+     */
+    kind: 'human' | 'agent';
+    actorRef?: string;
+}
+/** A request to author a skill at a scope. */
+interface SkillWriteRequest {
+    /** The scope token the skill would be published at. */
+    scope: string;
+    actor: Actor;
+    /** The actor's resolved scopes, most specific first — the same list a turn draws from. */
+    scopes: readonly string[];
+    author: SkillAuthor;
+    /**
+     * The host's own answer to "may this person administer that scope" — a sector lead editing their
+     * sector's skills, an operator editing the deployment's. This library cannot know it: it has no
+     * notion of who administers `sector:logistics`, and inventing one would be a second, weaker
+     * authorization model next to the host's real one. Undefined/false → a wider scope is refused.
+     */
+    elevated?: boolean;
+}
+type SkillWriteVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * May this author publish a skill at this scope?
+ *
+ * A skill's body is instructions the model follows, which makes writing one at a scope an edit to
+ * everyone in that scope's system prompt. The rules follow from that, and only the third is
+ * interesting:
+ *
+ * 1. You may only write into a scope you are yourself in. Writing into a scope you are not in is
+ *    authoring for people you have no relationship with.
+ * 2. Your OWN scope is yours. A per-actor skill affects exactly one prompt — the author's.
+ * 3. NOTHING BUT A HUMAN MAY WRITE ABOVE ITS OWN SCOPE, whatever `elevated` says. An agent that can
+ *    write a `tenant:` skill is an agent whose prompt anyone in the tenant can edit by talking to
+ *    it: the user asks for something, the turn writes the instruction, and every later turn for
+ *    every other user follows it. That is prompt injection with persistence, and no elevation a
+ *    host could grant makes it a different shape. An agent that has genuinely learned something
+ *    worth sharing proposes it; a person publishes it.
+ * 4. A human writing above their own scope needs the host to say so (`elevated`).
+ */
+declare function skillWriteVerdict(request: SkillWriteRequest): SkillWriteVerdict;
+
+/**
+ * Memory: what the assistant has concluded about a person or an organisation, carried across turns
+ * and across threads.
+ *
+ * HOW A READER TELLS IT FROM RAG. Retrieval answers "what do the documents say"; memory answers
+ * "what did I decide about you". A passage is content a person authored and can correct at its
+ * source, and it is cited. A memory has no source to go and fix: it is the agent's own inference,
+ * which is why every record carries an {@link MemoryOrigin} (who wrote it, in which conversation),
+ * why the block tells the model to treat it as fallible, and why `forget` is a REQUIRED method on
+ * the provider rather than an optional one. A wrong document is a content problem. A wrong memory is
+ * the assistant being confidently wrong about someone with nobody aware it is there, so the whole
+ * design is arranged around making it visible and removable.
+ *
+ * WHAT IT COSTS THE PROMPT. One line per memory, capped by `maxMemories`, and each line capped by
+ * `maxFactChars` at WRITE time — so the block a turn can carry is the product of two numbers an
+ * operator sets, rather than however much the model felt like writing down. Unlike a skill, a memory
+ * has no body/catalog split: a fact that cannot be stated in a line is not a memory, it is a
+ * document, and documents are retrieval's job.
+ *
+ * WHAT IT IS NOT: recall over a TRANSCRIPT. Searching what was said earlier is retrieval, and this
+ * library already has `Retriever`/`Reranker` for that.
+ *
+ * RECALL OVER THE MEMORIES THEMSELVES IS A DIFFERENT QUESTION, and it is answered here. The prompt
+ * budget must be bounded; the store has no reason to be. A person accumulates preferences over
+ * months and an organisation publishes facts for everyone in it, so the applicable set outgrows
+ * `maxMemories` quickly — and once it does, WHICH of them the block carries is a decision somebody
+ * has to make. Making it by scope starves the widest scopes first, which is precisely backwards: the
+ * facts that apply to the most people are the ones nobody sees. So a provider MAY supply
+ * {@link MemoryProvider.search}, and where it does, the block is filled by relevance to the turn
+ * (see {@link resolveMemoryDigest}) with scope still a hard filter and never a ranking signal.
+ * `maxMemories` then means "how many matter right now" rather than "how many a person may have".
+ */
+
+/** Who wrote a memory, and out of what. Kept so a person reading it back can ask "says who?". */
+interface MemoryOrigin {
+    /** `'agent'` — a turn concluded it. `'human'` — a person wrote it in the host's own console. */
+    author: 'agent' | 'human';
+    /**
+     * The conversation the conclusion was drawn in. MAY name a thread whose messages the history
+     * ceiling has since dropped: a memory deliberately outlives its source, so this is a pointer that
+     * is allowed to dangle, and a read-back that cannot resolve it says so rather than hiding the row.
+     */
+    threadId?: string;
+    runId?: string;
+    actorRef?: string;
+}
+/** One thing the assistant believes, at one scope. */
+interface MemoryRecord {
+    /** The host's row id — what `forget` takes and what a read-back offers a delete button for. */
+    id: string;
+    /**
+     * What the fact is ABOUT. The handle that makes a conflict mechanically detectable: two memories
+     * sharing a key at different scopes are one question answered twice, and the narrower wins. A
+     * keyless store could only ever hope its facts did not contradict each other.
+     */
+    key: string;
+    /** The fact itself, as the model reads it. */
+    text: string;
+    /** The opaque scope token it is held at — see `ScopeResolver` in `skills.ts`. */
+    scope: string;
+    origin: MemoryOrigin;
+    /** ISO-8601, so the ceiling can keep the newest with a string comparison it can do purely. */
+    updatedAt: string;
+    /**
+     * Always-on: this fact is in the block whether or not the turn is about it. The difference between
+     * working memory and recall, drawn per record — "they report on the calendar year" must not depend
+     * on the turn mentioning dates, while "they prefer the shorter runway" can wait until it comes up.
+     *
+     * A PROPERTY OF THE ROW, NOT OF A WRITE. This library reads it and never sets it, the same way it
+     * never mints an `id`: an agent deciding its own conclusions are always-on is an agent deciding
+     * how much of every future prompt it gets, so pinning is an operator's act in the host's console.
+     * That is also why {@link StoreMemoryInput} carries no `pinned` — the `remember` tool has no
+     * parameter to refuse. A host whose upsert drops the flag has silently unpinned the row; preserve
+     * it across an upsert on (`scope`, `key`).
+     */
+    pinned?: boolean;
+}
+/** A same-key memory a narrower scope outranked, with the value it holds. */
+interface OverriddenMemory {
+    scope: string;
+    text: string;
+    /**
+     * Who asserted the beaten value. Travels because precedence is blind to it: an agent's own
+     * inference at `actor:` outranks an administrator's published policy at `global`, and an agent
+     * that knew only that a wider value existed could not tell the two apart — one is a stale guess,
+     * the other is what the organisation decided.
+     */
+    author: MemoryOrigin['author'];
+}
+/** One memory as the model and a read-back both meet it. */
+interface MemoryDigestEntry extends MemoryRecord {
+    /**
+     * Same-key memories this one outranks, widest last. Present ONLY where something was outranked.
+     *
+     * Carries the beaten TEXT, which is where memory departs from a skill's `shadows`. A skill only
+     * has to say which scope it beat — the agent follows one procedure either way. A memory is a
+     * VALUE, and an agent that knows only that a wider value existed cannot tell the user what the
+     * difference is; it can only choose, silently, which is the thing this is meant to prevent.
+     */
+    overrides?: OverriddenMemory[];
+}
+/** What a turn resolved — journaled whole, so its prompt is reconstructible from its journal alone. */
+interface MemoryDigest {
+    /** The scope tokens this turn drew from, most specific first. */
+    scopes: string[];
+    /** The memories in the block, most specific first then by key. */
+    entries: MemoryDigestEntry[];
+    /**
+     * Applicable memories `maxMemories` left out. Non-zero means the block is not the whole truth —
+     * and under {@link recalled} it counts what the SEARCH offered and the ceiling dropped, not what
+     * the store holds, because nothing asked the store for a total.
+     */
+    omitted: number;
+    /**
+     * Of {@link omitted}, how many were ALWAYS-ON. Reported separately because it means something else
+     * entirely: ordinary omission is the budget doing its job, while an always-on memory the ceiling
+     * dropped is a deployment's own standing policies having silently stopped reaching any prompt.
+     * Non-zero is a misconfiguration — more was pinned than the block holds — and the fix is to unpin
+     * something or raise `maxMemories`, not to wait for it to come back.
+     */
+    pinnedOmitted: number;
+    /**
+     * Whether the entries were selected by relevance to this turn rather than read whole. The model is
+     * told (see {@link buildMemoryBlock}), because a partial set read as a whole one turns an absence
+     * into evidence: "you never told me that" about a fact it simply was not shown.
+     *
+     * Optional so a digest journaled before recall existed reads back as the plain scoped read it was.
+     */
+    recalled?: boolean;
+}
+/** What a write asks the host to store. `id` and `updatedAt` are the host's to mint. */
+interface MemoryFact {
+    key: string;
+    text: string;
+    scope: string;
+    origin: MemoryOrigin;
+}
+/** Arguments to {@link MemoryProvider.list}. */
+interface ListMemoriesInput {
+    /** The scope tokens that apply to this turn, most specific first. */
+    scopes: readonly string[];
+    ctx: ScopeContext;
+}
+/**
+ * Arguments to {@link MemoryProvider.search}.
+ *
+ * `scopes` GATES, AND IT GATES FIRST. A search that ranks before it filters is a cross-tenant leak
+ * wearing a relevance score: the nearest neighbour to "what is our rollback policy" is another
+ * base's rollback policy. Filter in the query, not after it. Records returned outside `scopes` are
+ * dropped rather than trusted, so a mistake here costs throughput rather than privacy — but the
+ * drop is a backstop, not the boundary.
+ */
+interface SearchMemoriesInput {
+    /** The scope tokens that apply to this turn, most specific first. A HARD FILTER. */
+    scopes: readonly string[];
+    /** What this turn is about. Never blank — a blank query is served by `list` instead. */
+    query: string;
+    /**
+     * At most this many distinct KEYS may be ranked in, which is the block's own unit: precedence
+     * resolves a key to one line, so `limit` keys is `limit` lines. Pinned records are returned in
+     * addition and do not count against it.
+     */
+    limit: number;
+    ctx: ScopeContext;
+}
+/** Arguments to {@link MemoryProvider.forget}. */
+interface ForgetMemoryInput {
+    id: string;
+    ctx: ScopeContext;
+}
+/**
+ * Arguments to {@link MemoryProvider.write}. An object rather than positional arguments because
+ * `key`, `text` and `scope` are all strings: transposed, a positional call compiles clean and writes
+ * a fact whose key is its value, at a scope nobody meant.
+ */
+interface StoreMemoryInput extends MemoryFact {
+    ctx: ScopeContext;
+}
+/**
+ * Where memories live. The host owns the rows, for the same reason it owns skill rows: the axes a
+ * deployment scopes by, the console that edits them and the audit trail are all the host's, and a
+ * table this package created at boot would put a consumer's migrations in the path of the schema
+ * heal that manages the `agent_*` tables.
+ *
+ * `forget` is REQUIRED, unlike `write`. A deployment may reasonably populate memory from its own
+ * pipeline and offer the agent no write tool; no deployment may reasonably hold conclusions about a
+ * person that the person cannot have deleted. Making it optional would make forgetting a wiring
+ * choice, and it is not one.
+ */
+interface MemoryProvider {
+    /**
+     * Every memory visible at `scopes`, in any order — this library resolves precedence and the
+     * ceiling. Asked on EVERY turn, so keep it cheap. A provider MAY return records outside `scopes`;
+     * they are dropped rather than trusted, so a filter bug in a host cannot widen what an actor sees.
+     */
+    list(input: ListMemoriesInput): MemoryRecord[] | Promise<MemoryRecord[]>;
+    /** Delete one record by id. `false` where there was nothing by that id to delete. */
+    forget(input: ForgetMemoryInput): boolean | Promise<boolean>;
+    /**
+     * Upsert on (`scope`, `key`) and return the stored record. Omit to serve memory read-only — the
+     * `remember` tool is then never offered, and a turn's tool list is the same on every pod.
+     */
+    write?(input: StoreMemoryInput): MemoryRecord | Promise<MemoryRecord>;
+    /**
+     * The memories worth putting in front of a turn about `query`, MOST RELEVANT FIRST. Omit and every
+     * turn is served by {@link list} — a deployment with twenty memories must not have to stand up an
+     * index to keep working, and one with two thousand uses whatever it already runs (pgvector, a
+     * full-text index, a hybrid service). The host owns the index for the same reason it owns the
+     * rows.
+     *
+     * THREE CLAUSES, and the third is the one that is easy to miss:
+     *
+     * 1. Filter to `scopes` before ranking — see {@link SearchMemoriesInput}.
+     * 2. Rank the KEYS visible at those scopes and take the best `limit` of them.
+     * 3. Return EVERY record sharing a returned key, plus every `pinned` record at those scopes.
+     *
+     * Clause three is what keeps precedence intact. Precedence resolves a conflict between two records
+     * at one key, narrower winning and the beaten value riding along; a search that returned the
+     * `global` half of a conflict and not the `actor:` half would render the org default as the answer
+     * — the exact failure memory exists to prevent, and one nothing downstream can detect. It is one
+     * query either way:
+     *
+     * ```sql
+     * SELECT * FROM agent_memory
+     *  WHERE scope IN (:scopes)
+     *    AND (pinned OR key IN (SELECT key FROM agent_memory
+     *                            WHERE scope IN (:scopes)
+     *                         ORDER BY embedding <=> :queryVector
+     *                            LIMIT :limit))
+     * ```
+     */
+    search?(input: SearchMemoriesInput): MemoryRecord[] | Promise<MemoryRecord[]>;
+}
+/**
+ * How many memories the block carries. The same ceiling shape as `maxSkills`, and for the same
+ * reason: a prompt that grows with how much the agent has written down is a prompt whose cost nobody
+ * set. A budget on the PROMPT and never on the store — with a provider that can
+ * {@link MemoryProvider.search}, it is how many matter right now rather than how many a person may
+ * have.
+ */
+declare const DEFAULT_MAX_MEMORIES = 20;
+/**
+ * How long one memory may be, enforced when it is WRITTEN rather than when it is rendered. Enforcing
+ * it at render time would make the prompt disagree with the store; enforcing it at write time makes
+ * the block's whole ceiling a multiplication an operator can do — `maxMemories × maxFactChars` — and
+ * pushes back on the model at the moment it is writing an essay instead of a fact.
+ */
+declare const DEFAULT_MAX_FACT_CHARS = 240;
+/** How a turn reaches its memory. See `AgentLoopDeps.memory`. */
+interface MemoryConfig {
+    provider: MemoryProvider;
+    /** Undefined → `defaultScopeResolver`: the actor's own, their tenant's, the deployment's. */
+    scopes?: ScopeResolver;
+    /** Undefined → {@link DEFAULT_MAX_MEMORIES}. Always-on memories are taken from it first. */
+    maxMemories?: number;
+    /** Undefined → {@link DEFAULT_MAX_FACT_CHARS}. */
+    maxFactChars?: number;
+}
+/**
+ * Resolve a provider's records against an ordered scope list: most specific wins a key, and the
+ * losers' values are carried rather than discarded.
+ *
+ * Pure, and separately exported, because the loop and the read-back endpoint must reach the same
+ * answer — a person has to be shown what the model was shown, or "see what it believes about you"
+ * means nothing.
+ */
+/** Arguments to {@link resolveMemoryDigest}. */
+interface ResolveMemoryDigestInput {
+    records: readonly MemoryRecord[];
+    /** The scope tokens that apply, most specific first — the precedence order. */
+    scopes: readonly string[];
+    /** Undefined → {@link DEFAULT_MAX_MEMORIES}. */
+    maxMemories?: number;
+    /**
+     * Whether `records` arrived most-relevant-first, from {@link MemoryProvider.search}. A key's rank
+     * is its best-placed record's. Undefined/false → the ceiling selects by scope and recency, which
+     * is the right order only while nothing is being starved.
+     */
+    ranked?: boolean;
+}
+declare function resolveMemoryDigest({ records, scopes, maxMemories, ranked, }: ResolveMemoryDigestInput): Omit<MemoryDigest, 'scopes' | 'recalled'>;
+/** Arguments to {@link offerMemories}. */
+interface OfferMemoriesInput {
+    config: MemoryConfig;
+    ctx: ScopeContext;
+    /**
+     * What this turn is about — the loop passes the user's own message, and nothing else. Given, and
+     * with a provider that has an index, the block is filled by relevance to it. Absent, the scope is
+     * read whole: that is what the read-back endpoint wants, since a person must be shown every belief
+     * held about them rather than the slice one turn happened to need.
+     */
+    query?: string;
+}
+/**
+ * Resolve the scopes and the digest for one turn. Called INSIDE the loop's `memory:digest` step, and
+ * that placement is the whole of its determinism: a search is the most re-derivable thing in this
+ * library — the index moves, a neighbour is written, embeddings are recomputed — so its result has
+ * to be part of the checkpoint every replay reads back, never something a replaying process asks
+ * again.
+ */
+declare function offerMemories({ config, ctx, query, }: OfferMemoriesInput): Promise<MemoryDigest>;
+/**
+ * The block as the model reads it.
+ *
+ * THREE THINGS IT HAS TO DO THAT A SKILLS CATALOG DOES NOT.
+ *
+ * It must frame each note by WHO ASSERTED IT, which is why there are two sections rather than one
+ * sentence over the whole list. An unlabelled fact in a system prompt reads with the authority of an
+ * instruction, and the hazard of an agent's own inference is exactly that authority — so those are
+ * hedged. But a memory an administrator published for a whole organisation is not the agent's guess,
+ * and telling the model to "prefer what the user says now" about it hands any user an override of
+ * their organisation's policy by asserting the opposite. `MemoryOrigin.author` is the axis, and it
+ * is the only one that matters here: scope says who a fact applies to, not who decided it.
+ *
+ * Where a narrower scope won, it must print the value it beat, so the model can tell the user their
+ * setting differs from the org's instead of quietly applying one of them.
+ *
+ * And a block that is a SELECTION must say so. A model reading a partial set as a whole one turns an
+ * absence into evidence — "you never told me that" about a fact it simply was not shown.
+ */
+/** Arguments to {@link buildMemoryBlock}. */
+interface BuildMemoryBlockInput {
+    entries: readonly MemoryDigestEntry[];
+    /** Whether this deployment offers `remember` — the block names the tool only where it exists. */
+    writable: boolean;
+    /** Whether applicable memories are missing from `entries` — the ceiling bit, or recall selected. */
+    partial: boolean;
+}
+declare function buildMemoryBlock({ entries, writable, partial }: BuildMemoryBlockInput): string;
+/** The reserved name of the built-in memory-writing tool. */
+declare const REMEMBER_TOOL_NAME = "remember";
+/** What the model passes to the `remember` tool. */
+interface RememberToolInput {
+    key: string;
+    fact: string;
+}
+/**
+ * The `remember` tool's input schema. Hand-written for the same reason `askInputSchema` and
+ * `skillInputSchema` are: core depends on no validator and has to publish a JSON Schema a provider
+ * can constrain generation against.
+ *
+ * THERE IS NO SCOPE PARAMETER, and that is the enforcement rather than a simplification. An agent
+ * may only ever write the actor it is running for (see {@link memoryWriteVerdict}), so a scope
+ * argument could only ever be a request that gets refused — and a refusable request is one a model
+ * will keep making, and one a future reader will be tempted to make grantable.
+ */
+declare const rememberInputSchema: StandardSchemaV1<unknown, RememberToolInput>;
+declare const REMEMBER_TOOL_DESCRIPTION = "Record one durable fact about this user under a key, so later conversations start knowing it. For things that will still be true another day \u2014 how they work, what their organisation requires, a correction they made. Not for what this conversation is about, and not for anything you were not told or could not reasonably infer. The user can read and delete everything you record here.";
+/**
+ * The `remember` tool as the model sees it. NOT a `ToolSpec` and never registered, exactly like
+ * `ask` and `skill`: it has no handler, because the loop serves it against the digest the journal
+ * holds. Keeping it out of the `ToolRegistry` is also what keeps its kind off a process-local
+ * lookup — see `claimToolCall`.
+ */
+declare function rememberToolDefinition(): ToolDefinition;
+/**
+ * Append the built-in `remember` definition to a turn's tool list. Exported because the dispatched
+ * llm step re-derives the tool list on a worker and has to reach the same list the loop would have.
+ */
+/** Arguments to {@link withMemoryTool}. */
+interface WithMemoryToolInput {
+    tools: ToolDefinition[];
+    /** Whether this deployment's provider can write at all — module config, uniform across its pods. */
+    enabled: boolean;
+}
+declare function withMemoryTool({ tools, enabled }: WithMemoryToolInput): ToolDefinition[];
+/** Who is trying to write a memory. */
+interface MemoryAuthor {
+    /**
+     * `'human'` is a person acting through a UI; `'agent'` is anything else — a turn, a tool, a batch
+     * job. The distinction is the whole of rule three below, so it is not inferable and has to be
+     * stated by the caller.
+     */
+    kind: 'human' | 'agent';
+    actorRef?: string;
+}
+/** A request to write a memory at a scope. */
+interface MemoryWriteRequest {
+    scope: string;
+    actor: Actor;
+    /** The actor's resolved scopes, most specific first — the same list the turn drew its digest from. */
+    scopes: readonly string[];
+    author: MemoryAuthor;
+    /**
+     * The host's own answer to "may this person administer that scope". This library cannot know it,
+     * and inventing an answer would be a second, weaker authorization model next to the host's real
+     * one. Undefined/false → a wider scope is refused.
+     */
+    elevated?: boolean;
+}
+type MemoryVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * May this author write a memory at this scope?
+ *
+ * The same four rules as `skillWriteVerdict`, deliberately duplicated rather than shared: they are
+ * the same rules about two different things, and folding them into one function would mean a future
+ * change to how skills are authored silently changing who may edit what the assistant believes about
+ * a person. Rule three is the one that matters, and it bites harder here than it does for skills:
+ *
+ * 1. You may only write into a scope you are yourself in.
+ * 2. Your OWN scope is yours. A memory at `actor:<you>` affects exactly one prompt — your own.
+ * 3. NOTHING BUT A HUMAN MAY WRITE ABOVE ITS OWN SCOPE, whatever `elevated` says. A skill an agent
+ *    could publish at `tenant:` is a procedure anyone in the tenant can edit by talking to the
+ *    assistant; a MEMORY it could publish there is a fact everyone in the tenant is then answered
+ *    from, with no document to inspect and nobody aware it was written. An agent that has genuinely
+ *    learned something the organisation should know proposes it; a person publishes it.
+ * 4. A human writing above their own scope needs the host to say so (`elevated`).
+ */
+declare function memoryWriteVerdict(request: MemoryWriteRequest): MemoryVerdict;
+/**
+ * May this actor delete this memory?
+ *
+ * Narrower than the write rule on purpose, and it takes no `elevated` flag. Deleting what the
+ * assistant believes about YOU needs no permission from anyone — that is the point of the read-back
+ * — so the endpoint that serves it must not be able to ask a host a question it might answer no to.
+ * Deleting what it believes about a tenant is an administrative act on shared state, which belongs
+ * in the host's console with the same elevation a write there needs.
+ */
+/** A request to delete one memory. */
+interface MemoryForgetRequest {
+    record: Pick<MemoryRecord, 'scope'>;
+    actor: Actor;
+}
+declare function memoryForgetVerdict({ record, actor }: MemoryForgetRequest): MemoryVerdict;
+/** What a `remember` call resolved to — the stored record, or why nothing was stored. */
+type MemoryWriteOutcome = {
+    ok: true;
+    record: MemoryRecord;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Serve one `remember` call against the digest THIS TURN resolved.
+ *
+ * The digest's `scopes` are the authorization boundary, not the resolver: they came out of the
+ * `memory:digest` checkpoint, so a write is checked against the scopes the run recorded rather than
+ * the ones a replaying process's resolver would produce now. A membership table edited mid-run
+ * cannot retroactively widen — or narrow — what a turn already in flight is allowed to write.
+ */
+/** Arguments to {@link writeMemory}. */
+interface WriteMemoryInput {
+    config: MemoryConfig;
+    /** The digest THIS TURN journaled — the authorization boundary, never a fresh resolution. */
+    digest: MemoryDigest;
+    /** The `remember` call as the model made it. */
+    call: RememberToolInput;
+    ctx: ScopeContext;
+    runId: string;
+}
+declare function writeMemory({ config, digest, call, ctx, runId, }: WriteMemoryInput): Promise<MemoryWriteOutcome>;
+
 /** Holds the named agent definitions registered via `AgentModule.forFeature([...])`. */
 declare class AgentRegistry {
     private readonly definitions;
@@ -1485,6 +3315,121 @@ declare class AgentRegistry {
     list(): AgentDefinition[];
 }
 
+/**
+ * Is this the durable runtime refusing a checkpoint position, rather than anything the agent did?
+ *
+ * Matched by NAME because this package cannot import either class: the in-process engine throws
+ * `@dudousxd/nestjs-durable-core`'s `NonDeterminismError` and the thin BullMQ worker throws
+ * `@dudousxd/nestjs-durable-worker`'s `NondeterminismError` — the same contract under two spellings
+ * in two packages, neither of which core depends on. Same cross-runtime reasoning as the
+ * `isControlFlowError` hook, which exists for exactly this reason on the suspend path.
+ *
+ * Suffix rather than equality, because a runtime is free to qualify the name: the sibling Adonis
+ * stack raises a `WorkflowNondeterminismError` from its remote-replay path, which an equality check
+ * would wave through as an ordinary tool failure. `replay-integrity.contract.spec.ts` pins this
+ * against the real exported classes, so a rename upstream fails a test instead of quietly
+ * disarming the guard.
+ *
+ * Callers must let these through untouched. Every `catch` in a workflow body reacts by writing more
+ * checkpoints (a toolfail, a run-end, a deactivate), and on a journal that has already diverged each
+ * of those asks for a position the history cannot supply — so the recovery attempt raises its own
+ * refusal, and THAT is the error the operator reads: a message pointing at the wrong seq, naming
+ * checkpoints from the recovery path rather than the two that actually disagreed.
+ */
+declare function isReplayIntegrityError(error: unknown): boolean;
+
+/**
+ * Is this the runner unwinding the turn (a durable suspend / continue-as-new) rather than something
+ * the agent did? Callers must rethrow it untouched: every `catch` in the loop reacts by writing more
+ * checkpoints, and a suspend recorded as a tool failure leaves a journal the resumed replay cannot
+ * line up with.
+ *
+ * Detected from the error itself so a host that never wired `AgentLoopHooks.isControlFlowError` still
+ * gets its suspends through — that hook is an override for a runner whose signals carry no marker,
+ * not the only line of defence. Checked as a stamped property, NOT `instanceof`: the classes differ
+ * per runtime, which is why the marker exists.
+ */
+declare function isControlFlowSignal(error: unknown): boolean;
+
+/** An agent->agent edge with its awaited-or-not resolved, whichever form it was authored in. */
+interface ResolvedDelegation {
+    agent: string;
+    detached: boolean;
+}
+/** Read one {@link AgentDelegation} entry in either of its forms. */
+declare function normalizeDelegation(entry: AgentDelegation): ResolvedDelegation;
+/**
+ * What a detached delegation hands the model in place of an answer. Its `status` is the whole point:
+ * a model that is given an object shaped like a result will report one, and this run has none yet.
+ */
+interface DetachedDelegationReceipt {
+    detached: true;
+    status: 'started';
+    /** The agent now working on it. */
+    agent: string;
+    /** The run doing the work — what a client subscribes to, and what stamps the delivered message. */
+    runId: string;
+    /**
+     * The same fact in the only vocabulary the model reliably acts on: prose in a tool result. The
+     * structured fields above are for a client; this is for the turn that has to explain itself to a
+     * user without claiming a result it does not hold.
+     */
+    note: string;
+}
+/** How a detached delegation ended, written back onto its tool-call row once the run settles. */
+interface DetachedDelegationOutcome {
+    detached: true;
+    status: 'delivered' | 'failed' | 'cancelled';
+    agent: string;
+    runId: string;
+    /** The delivered answer. Present on `delivered` only. */
+    text?: string;
+    /** Why it did not deliver. Present on `failed` only. */
+    error?: string;
+}
+/** The receipt an `agent`-kind call returns the moment its delegate is under way. */
+declare function detachedStarted(args: {
+    agent: string;
+    runId: string;
+}): DetachedDelegationReceipt;
+/** The outcome written onto the delegating tool call when a detached run finishes its answer. */
+declare function detachedDelivered(args: {
+    agent: string;
+    runId: string;
+    text: string;
+}): DetachedDelegationOutcome;
+/**
+ * The outcome written onto the delegating tool call when a detached run never produced an answer.
+ * Written by the RUNNER, not the loop: a run that crashed or was stopped cannot record its own
+ * ending, and a delegation card that stays "started" for ever is the one state a reader cannot act
+ * on.
+ */
+declare function detachedUnsettled(args: {
+    agent: string;
+    runId: string;
+    status: 'failed' | 'cancelled';
+    error?: string;
+}): DetachedDelegationOutcome;
+/**
+ * Settle the delegation a detached run was started for when that run ends with no answer.
+ *
+ * Two writes, because a reader needs both: the tool-call row so a governance surface stops counting
+ * it as in flight, and a MESSAGE in the delegating thread so the person who asked finds out. A
+ * delivered answer already arrives as a message; without this, the failure is the one outcome that
+ * silently never does, and the conversation shows "started" for ever.
+ *
+ * Called by the RUNNER, never the loop — a run that crashed or was stopped cannot record its own
+ * ending. Skipped entirely when the thread is gone, for the same reason delivery is.
+ */
+declare function settleUnsettledDelegation(args: {
+    store: AgentStore;
+    delivery: DetachedDelivery;
+    agent: string;
+    runId: string;
+    status: 'failed' | 'cancelled';
+    error?: string;
+}): Promise<void>;
+
 /** Thrown when an actor invokes a tool their role is not allowed. */
 declare class ToolForbiddenError extends Error {
     readonly toolName: string;
@@ -1529,10 +3474,14 @@ declare class ToolRegistry {
     allSpecs(): ToolSpec[];
     /**
      * The tools to offer the model for this actor+agent, after the four filter layers: what this
-     * deployment has enabled, what this actor's role allows, what each tool's own `canUse` allows
-     * this actor, and finally what this agent pinned.
+     * agent pinned, what this deployment has enabled, what this actor's role allows, and what each
+     * tool's own `canUse` allows this actor.
      *
      * Every layer only ever removes tools, so no arrangement of them can widen what a turn reaches.
+     * The agent's allow-list therefore goes FIRST, even though it is the narrowest statement: it is a
+     * pure name-set match, while each of the three below it may be a round trip — an authz service, a
+     * feature-flag store, an MCP server — and this runs once per model step. Asking those about a
+     * tool the allow-list has already excluded is a call whose answer nothing reads.
      */
     definitionsFor(actor: Actor, policy: RolesPolicy, allowedTools?: string[]): Promise<ToolDefinition[]>;
     /**
@@ -1549,7 +3498,7 @@ declare class DefaultRolesPolicy implements RolesPolicy {
     can(actor: Actor, tool: ToolSpec): boolean;
 }
 
-interface AgentLoopDeps {
+interface AgentLoopDeps<TOutput = unknown> {
     model: ModelProvider;
     store: AgentStore;
     registry: ToolRegistry;
@@ -1571,6 +3520,26 @@ interface AgentLoopDeps {
      */
     promptContributors?: PromptContributor[];
     maxSteps?: number;
+    /**
+     * How deep agent→agent delegation may nest before the loop refuses further hops.
+     * Defaults to {@link MAX_DELEGATION_DEPTH}.
+     *
+     * It bounds NESTING, never fan-out: how many agents a turn delegates to is the model's, one tool
+     * call each, and nothing here caps that. What it guards is a hop the model cannot see — a
+     * `delegatesTo` cycle (A→B→A), where each agent is making one reasonable call and the recursion
+     * is a property of the wiring rather than of any decision.
+     */
+    maxDelegationDepth?: number;
+    /**
+     * How many times one agent may appear on a single delegation chain.
+     * Defaults to {@link DEFAULT_MAX_AGENT_APPEARANCES}.
+     *
+     * This is the guard the depth ceiling was a proxy for, made exact: the loop compares the target
+     * against {@link AgentRunInput.delegationPath} and knows whether the chain has been here before,
+     * and how often. A chain of eight DISTINCT agents is long, not looping, and no longer refused for
+     * resembling one.
+     */
+    maxAgentAppearances?: number;
     /** Optional host handle threaded to tool ctx (e.g. an ORM EntityManager). */
     host?: unknown;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
@@ -1611,13 +3580,174 @@ interface AgentLoopDeps {
      * message/step) and reused for every step's estimate. Undefined → `costUsd` is always `null`.
      */
     pricingStore?: AgentPricingStore;
+    /**
+     * Bounds how much of the thread rides into the turn. Undefined → the WHOLE thread, every message
+     * the store holds, which is unbounded: a long-lived thread eventually exceeds the provider's
+     * context limit, and pays for the full transcript on every turn up to that point. See
+     * `windowHistory` for the built-in.
+     */
+    historyPolicy?: HistoryPolicy;
+    /**
+     * Rewrites the prompt before EACH model call of the turn, in order (see {@link InputProcessor}).
+     * Transformation only — `historyPolicy` owns which messages are there in the first place. Adds
+     * one `process:input:<step>` checkpoint per step; empty/undefined adds none.
+     */
+    inputProcessors?: InputProcessor[];
+    /**
+     * Inspects each model step's answer before the stream, the store or the next step sees it, and
+     * may redact, replace or refuse it (see {@link OutputProcessor}).
+     *
+     * REGISTERING ONE TAKES THE MODEL CALL OFF THE RUN'S SINK for the turn — a gate cannot run after
+     * the answer has already reached the reader. What the chain costs the subscriber depends on what
+     * it declares:
+     *
+     * - Any processor WITHOUT `incremental` → the whole answer is buffered and released as one `text`
+     *   frame once the chain has passed. No token-by-token text, and (for a provider that writes bytes
+     *   outside the `AgentStreamEvent` vocabulary) no frame the gate cannot classify.
+     * - EVERY processor with `incremental` → the chain runs over the growing prefix and releases it as
+     *   it arrives, holding back the widest `lookbackChars` any of them asked for. The whole-answer
+     *   pass still runs and is still authoritative for the stream and the store.
+     *
+     * Both add one `process:output:<step>` checkpoint per step, in the same position, so a chain can
+     * change its declaration without moving a checkpoint. Empty/undefined adds none, and the turn
+     * streams exactly as it always did.
+     */
+    outputProcessors?: OutputProcessor[];
+    /**
+     * Constrain the turn's answer to a schema, returned validated as `object` on the loop's result and
+     * recorded on the assistant message as a synthetic `structured_output` tool call (the same shape
+     * inject-mode retrieval uses, so no store gains a column for it).
+     *
+     * HOW IT COMPOSES WITH TOOL CALLING: as a separate formatting pass, ALWAYS. The turn runs its
+     * model→tools iteration exactly as it would without a schema; once a step comes back with no tool
+     * calls, one extra non-streamed call (`structured:<step>`, `tools: []`, `outputSchema` set)
+     * restates that answer as the schema. Most providers cannot serve a response format and a tool set
+     * in one request, and skipping the pass for an agent that happens to have no tools would make the
+     * checkpoint sequence depend on a tool-registry lookup — the registry of whichever process is
+     * replaying — which is exactly how a run ends up asking for a position its history has no room
+     * for. So the pass is unconditional, and it costs one model call per turn (recorded as
+     * `structured_output` usage).
+     */
+    outputSchema?: StandardSchemaV1<unknown, TOutput>;
+    /** Overrides the formatting pass's system prompt. Undefined → `DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION`. */
+    outputInstruction?: string;
+    /**
+     * How many extra model calls may try to fix an answer that failed `outputSchema`, each shown the
+     * previous attempt's validation issues. Undefined → 1; `0` → fail on the first invalid reply.
+     * Bounded because a model that cannot satisfy a schema usually cannot satisfy it on the fourth
+     * try either, and every attempt is billed.
+     */
+    outputRepairAttempts?: number;
+    /**
+     * Show the formatting pass the turn's whole transcript instead of just the question and the
+     * answer. For an agent whose answer cannot be restated from its own words — one that reports on
+     * rows a tool returned and names only their total in the prose, say.
+     *
+     * OFF by default because the pass is a translation, and a translation needs the thing being
+     * translated. The transcript it would otherwise carry is the turn's entire prompt a second time,
+     * at no discount: the pass swaps the system block for the schema instruction, and the system block
+     * is the prompt cache's prefix, so nothing of the first call's cache survives into it.
+     */
+    outputFromTranscript?: boolean;
+    /**
+     * A question set the agent puts to the user BEFORE it starts working — collecting the scope, as
+     * against `awaitApproval`, which sanctions work already proposed. The questions are AUTHORED, so
+     * the turn spends no model call producing them and a client knows the total ("Question 1 of 3")
+     * the moment the form appears.
+     *
+     * The turn parks on the answers exactly as it parks on an approval, and the request persists as
+     * the same tool-call row the model's `ask` writes — see {@link ask}. Undefined → no intake, and a
+     * turn's checkpoint sequence is byte-identical to one that never had the option.
+     */
+    intake?: AgentIntake;
+    /**
+     * Offer the model the built-in `ask` tool, so it can put its own question set to the user when it
+     * judges the scope is missing — the same surface as {@link intake}, minus the "known in advance".
+     *
+     * `ask` is NOT a registered tool: it has no handler (the loop settles it against a human), and
+     * keeping it out of the `ToolRegistry` is what keeps its kind out of a process-local lookup. The
+     * loop appends its definition to the turn's tool list from THIS flag, which is module config and
+     * therefore uniform across a deployment. Undefined/false → the model never sees it.
+     */
+    ask?: boolean;
+    /**
+     * Authored procedures the model may pull in when a task calls for one, resolved per turn against
+     * the actor's scopes — see `skills.ts`. Undefined → no catalog block, no `skill` tool, and a
+     * turn's checkpoint sequence is byte-identical to one that never had the option.
+     *
+     * HOW IT COMPOSES WITH THE OTHER FOUR THINGS THAT WRITE THE PROMPT. The system block is assembled
+     * in one fixed order — the agent's base prompt, then each `promptContributors` section, then
+     * {@link memory}, then the injected retrieval block, then the skills CATALOG — and skills are the
+     * cheapest of the five by construction: the catalog is one line per skill and nothing else. The
+     * instructions themselves arrive as a tool RESULT, on the transcript, which means the budget they
+     * draw on is the one `historyPolicy` already governs rather than a private allowance of their own.
+     *
+     * A BODY IS NOT LIKE A MEMORY, which does ride the system block. A body is read BECAUSE the model
+     * went and asked for it, so the transcript — what this conversation happened to pull in — is where
+     * it belongs. A memory is worthless unless it is in front of the model on the turn nobody thought
+     * to look for it, and it is affordable there only because it has no body to carry.
+     */
+    skills?: SkillsConfig;
+    /**
+     * What the assistant has previously concluded about the actor and their organisation, resolved per
+     * turn against the same scope tokens skills use — see `memory.ts`. Undefined → no memory block, no
+     * `remember` tool, and a turn's checkpoint sequence is byte-identical to one that never had the
+     * option.
+     *
+     * WHERE IT SITS IN THE PROMPT. The system block is assembled most-durable-first: the agent's base
+     * prompt (the same for everyone, every turn), then `promptContributors`, then MEMORY (the same for
+     * this person, every turn), then the injected retrieval block (this question only), then the
+     * skills catalog (a menu rather than an instruction, so a reader meets instructions before
+     * options).
+     *
+     * WHY IT IS IN THE SYSTEM BLOCK AT ALL, when a skill's body deliberately is not. A body is read
+     * BECAUSE the model went and asked for it; a memory is worthless unless it is in front of the
+     * model on the turn nobody thought to look for it — "they report in nautical miles" only works
+     * unprompted. What makes that affordable is that a memory has no body: `maxMemories` lines, each
+     * capped at `maxFactChars` when it is written, so the block's ceiling is a product of two numbers
+     * an operator set rather than however much the model felt like writing down.
+     */
+    memory?: MemoryConfig;
 }
+/** One task's outcome under {@link AgentLoopHooks.parallel}, reported instead of thrown. */
+type SettledTask<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * The {@link AgentLoopHooks.parallel} implementation for a runner whose checkpoint positions are
+ * handed out on the CALL (both durable primitives are: `ctx.localStep` and `ctx.step` take their
+ * position before their first `await`). Every task is invoked here, synchronously and in list
+ * order, before any of them is awaited — which is what fixes the block of positions the tasks
+ * occupy, whatever order they then settle in. Nothing rejects: the caller decides what an
+ * individual failure means.
+ */
+declare function settleAll<T>(tasks: readonly (() => Promise<T>)[]): Promise<SettledTask<T>[]>;
 interface AgentLoopHooks {
     runId: string;
     /** A writer for this run's live token stream (data plane). */
     openSink(): SinkWriter | Promise<SinkWriter>;
     /** HITL gate for an action tool. Inline resolves a pending promise; durable awaits a signal. */
     awaitApproval(call: ToolCallRequest, ctx: AiToolCtx): Promise<Decision>;
+    /**
+     * Park the run on a question set and resolve with what the human sent back. The SAME wait
+     * `awaitApproval` is — the durable runner maps both to `ctx.waitForSignal` on
+     * `tool:<runId>:<callId>`, so an answer and an approval reach a parked run through one path.
+     *
+     * Optional, and its absence changes no checkpoint: the loop falls back to `awaitApproval` and
+     * reads the decision as "the user confirmed the pre-picked answers" (approved) or "the user
+     * skipped" (rejected). That is the honest reduction of a yes/no channel, and it means a host that
+     * only ever implemented approval still runs an elicitation to completion instead of hanging.
+     *
+     * Declared as `HumanReply` rather than `ElicitationReply` because that is what the channel really
+     * carries: a question set is parked as a `pending_approval` action, so a `Decision` can arrive on
+     * this wait from the approvals inbox even where the host implements it. The loop reduces one to
+     * the other — see {@link normalizeElicitationReply} — so an implementer never has to.
+     */
+    awaitAnswers?(request: ElicitationRequest, ctx: AiToolCtx): Promise<HumanReply>;
     /**
      * Run another named agent and return its answer. Provided only when the host wired multi-agent
      * support (durable → child workflow, inline → nested loop). Exposed to tools as `ctx.runAgent`.
@@ -1625,6 +3755,27 @@ interface AgentLoopHooks {
     runAgent?(agentName: string, task: string): Promise<{
         text: string;
     }>;
+    /**
+     * Start another named agent and return its run id WITHOUT waiting for it, so the calling turn can
+     * finish while the delegate is still working. The durable runner maps this to `ctx.startChild`
+     * (checkpointed as `spawn:<id>`; no suspend, unlike the `ctx.child` behind {@link runAgent}); the
+     * inline runner to a nested loop nobody awaits.
+     *
+     * `toolCallId` is the delegation's own call, which the started run carries as its delivery
+     * address: it posts its answer back into the calling thread against that row.
+     *
+     * Absent -> a delegation the journal declares detached is AWAITED instead. The loop writes the
+     * same checkpoint names either way (see {@link delegateToolCall}), so a runner that cannot detach
+     * still answers the user; only the runner's own positions differ, and a given runner always makes
+     * the same choice for the same call.
+     */
+    startAgent?(args: {
+        agentName: string;
+        task: string;
+        toolCallId: string;
+    }): Promise<{
+        runId: string;
+    }>;
     /**
      * Checkpoint wrapper. Inline = call fn directly; durable = ctx.localStep(name, fn) — the
      * in-process checkpointed primitive (`name` is a checkpoint identity, not a worker group).
@@ -1635,10 +3786,12 @@ interface AgentLoopHooks {
     /**
      * Dispatch the model turn as a routed remote step. When present the loop uses it INSTEAD of
      * running the model inline under hooks.step. Must resolve to exactly what deps.model.runTurn
-     * resolves. The durable runner enriches the envelope with sink routing (sinkRunId/childSink)
-     * on its side — core stays sink-topology-agnostic.
+     * resolves, plus `bufferedFrames` when (and only when) the envelope set `bufferOutput` — the
+     * handler streams to a worker-side sink the loop cannot wrap, so an output gate depends on it
+     * honouring that flag. The durable runner enriches the envelope with sink routing
+     * (sinkRunId/childSink) on its side — core stays sink-topology-agnostic.
      */
-    dispatchLlm?(index: number, envelope: LlmStepEnvelope): Promise<ModelTurnResult>;
+    dispatchLlm?(index: number, envelope: LlmStepEnvelope): Promise<BufferedModelTurnResult>;
     /**
      * Dispatch one tool execution as a routed remote step. Replaces ONLY the registry.invoke call
      * (+ its timeout, applied handler-side); all persist steps around it stay local.
@@ -1646,14 +3799,83 @@ interface AgentLoopHooks {
     dispatchTool?(call: ToolCallRequest, envelope: ToolStepEnvelope): Promise<unknown>;
     /**
      * Recognizes the runner's control-flow signals (durable suspend / continue-as-new) so the loop
-     * rethrows them untouched instead of recording a failure. Inline runners omit it — they have no
-     * control-flow exceptions.
+     * rethrows them untouched instead of recording a failure. An OVERRIDE, not the gate: the loop
+     * already recognizes any signal carrying the durable runtime's `Symbol.for` marker on its own (see
+     * {@link isControlFlowSignal}), so a host that omits this — an inline runner with no control-flow
+     * exceptions, or one that simply forgot — never turns a suspend into a persisted tool failure.
+     * Supply it for a runner whose signals carry no marker.
      */
     isControlFlowError?(error: unknown): boolean;
+    /**
+     * Run `tasks` concurrently, resolving once EVERY one has settled — one outcome per task, in INPUT
+     * order, never rejecting. Supplying it is a statement about the runner's checkpointing: each task
+     * MUST be invoked synchronously, in list order, before any is awaited, so a runner that hands out
+     * positions on the call assigns them in that order regardless of which task finishes first.
+     * {@link settleAll} is exactly that, and is what both bundled runners pass.
+     *
+     * Waiting for ALL of them is the other half of the contract. A durable runner unwinds a turn by
+     * THROWING (a dispatched step suspends), and a sibling abandoned part-way through its own dispatch
+     * is a tool nobody ever runs.
+     *
+     * Absent → the loop runs a turn's tool calls one at a time. That is the honest answer for a runner
+     * whose positions are assigned anywhere other than the call, and it is the only behaviour that
+     * existed before, so nothing gains concurrency without saying so.
+     */
+    parallel?<T>(tasks: readonly (() => Promise<T>)[]): Promise<SettledTask<T>[]>;
+    /**
+     * Has someone asked this run to stop?
+     *
+     * Answered at the points where stopping is safe and cheap — between steps, before the next model
+     * call, before the turn's tools are dispatched — and NEVER consulted anywhere else. Two properties
+     * make it safe to ask a live question inside a replayed loop body:
+     *
+     * 1. THE ANSWER IS JOURNALED. The loop only ever calls this inside a checkpoint, so the first
+     *    process to reach a given position writes the answer there and every later replay reads it
+     *    back. A cancel that arrives between two replays is therefore seen at the first position the
+     *    history does NOT yet hold, and cannot change the branch a replayed position already took.
+     * 2. THE POSITIONS ARE PATCHED IN. They exist only for a run that {@link patched} admits to the
+     *    `agent:cancellation` shape, so a run already in flight when a deployment gained this keeps
+     *    replaying against the sequence it recorded.
+     *
+     * Undefined → the run cannot be cancelled and takes not one extra checkpoint, which is the honest
+     * answer for a host with nowhere to record the request.
+     *
+     * WHAT IT CANNOT REACH: a turn parked on a human (`awaitApproval`/`awaitAnswers`) is suspended
+     * INSIDE a position the journal already holds, so no observation of any kind fires there. Stopping
+     * a parked run is the runner's job, through whatever hard cancel its runtime has.
+     */
+    cancelled?(): Promise<boolean>;
+    /**
+     * Does this run take the loop shape guarded by `id`? A runner replaying against recorded
+     * checkpoints answers `false` for a run that started before the shape changed, so that run keeps
+     * replaying the shape its history holds (the durable runtime's `ctx.patched`, which consumes a
+     * position for a new run and gives it back to an old one). Absent → `true`: a runner that records
+     * no positions has no older shape to preserve.
+     */
+    patched?(id: string): Promise<boolean>;
 }
 declare class QuotaExceededError extends Error {
     constructor();
 }
+/**
+ * Someone asked this run to stop, and it did. NOT a failure — it is the outcome a user pressing Stop
+ * is entitled to, and a consumer whose reliability numbers count `failed` runs must be able to leave
+ * it out. Thrown by the loop at the point it observed the cancel, and settled by the runner, which
+ * records the run `cancelled` and ends the stream with a `cancelled` frame rather than failing it.
+ *
+ * Carries no message detail on purpose: there is nothing to diagnose, and a cancel reads the same
+ * whether it came from a Stop button, an operator console, or a deployment draining.
+ */
+declare class RunCancelledError extends Error {
+    constructor();
+}
+/**
+ * The stream error code a failed run surfaces to its subscriber. A refusal by an output processor
+ * and an answer that never satisfied `outputSchema` are the CONTROLS working, not the model
+ * breaking: a client that retries on `run_failed` must not retry either of them, and neither should
+ * page whoever is on call for model failures.
+ */
+declare function agentFailureCode(error: unknown): string;
 /** Reject if `work` doesn't settle within `ms`. The underlying work is left to finish on its own. */
 declare function withToolTimeout<T>(work: Promise<T>, ms: number, toolName: string): Promise<T>;
 /**
@@ -1672,14 +3894,26 @@ declare function traceToolExecution<T>(runId: string, call: {
     toolName: string;
     toolType: 'read' | 'action';
 }, run: () => Promise<T>): Promise<T>;
+/**
+ * Append the built-in `ask` definition to a turn's tool list. Exported because the dispatched llm
+ * step re-derives the tool list on a worker and has to reach the same list the loop would have.
+ */
+declare function withAskTool({ tools, ask, }: {
+    tools: ToolDefinition[];
+    ask: boolean | undefined;
+}): ToolDefinition[];
+/** What a turn answered with: the assistant text, plus the validated `outputSchema` value if any. */
+interface AgentLoopResult<TOutput = unknown> {
+    text: string;
+    /** Present only when `AgentLoopDeps.outputSchema` was set — the validated structured answer. */
+    object?: TOutput;
+}
 /**
  * The provider-agnostic agent turn, reused by both the inline and durable runners.
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
  * hooks that make the same loop body either in-process or a replay-safe durable workflow.
  */
-declare function runAgentLoop(deps: AgentLoopDeps, input: AgentRunInput, hooks: AgentLoopHooks): Promise<{
-    text: string;
-}>;
+declare function runAgentLoop<TOutput = unknown>(deps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
 
 /** Payloads carried on each `aviary:agent:*` channel. */
 interface AgentRunStarted {
@@ -1724,6 +3958,8 @@ interface AgentDelegated {
     runId: string;
     fromAgent?: string;
     toAgent: string;
+    /** The delegate was STARTED, not awaited — this run's turn ended without its answer. */
+    detached?: boolean;
 }
 interface AgentRetrieved {
     runId: string;
@@ -1731,6 +3967,64 @@ interface AgentRetrieved {
     /** How many passages the retriever returned. */
     count: number;
 }
+/**
+ * The skills a turn was offered, published once per run at the `skills:catalog` checkpoint. Metadata
+ * only — counts and the block's size, never a skill's name or its body.
+ */
+interface AgentSkillsResolved {
+    runId: string;
+    /** How many scope tokens the resolver returned for this turn. */
+    scopes: number;
+    /** Skills in the catalog block the model was shown. */
+    offered: number;
+    /** Applicable skills the `maxSkills` ceiling left out — non-zero means the catalog is partial. */
+    omitted: number;
+    /**
+     * Characters the catalog block added to the system prompt. The WHOLE of what skills cost it: a
+     * skill's body never enters the system block, it arrives as a tool result on the transcript.
+     */
+    promptChars: number;
+}
+/**
+ * The memories a turn was shown, published once per run at the `memory:digest` checkpoint. Metadata
+ * only — counts and the block's size, never a memory's key or its text. A key is as revealing as a
+ * fact (`diagnosis`, `clearance`), so it does not travel on a diagnostics channel either.
+ */
+interface AgentMemoryResolved {
+    runId: string;
+    /** How many scope tokens the resolver returned for this turn. */
+    scopes: number;
+    /** Memories in the block the model was shown. */
+    offered: number;
+    /** Applicable memories the `maxMemories` ceiling left out — non-zero means the block is partial. */
+    omitted: number;
+    /**
+     * Of `omitted`, how many were ALWAYS-ON. The one to alert on: ordinary omission is the budget
+     * working, while a dropped always-on memory is a deployment's own standing policies having stopped
+     * reaching any prompt — more was pinned than the block holds.
+     */
+    pinnedOmitted: number;
+    /**
+     * Whether the block was selected by relevance to this turn rather than read whole. Distinguishes
+     * "this deployment holds few memories" from "this turn drew twenty out of two thousand", which
+     * `offered` alone reports identically.
+     */
+    recalled: boolean;
+    /** Characters the memory block added to the system prompt. The WHOLE of what memory cost it. */
+    promptChars: number;
+}
+/**
+ * A turn writing one memory — the event an operator watches to see the agent's own write volume,
+ * which is the risk surface memory has and retrieval does not. The scope token travels (it is what
+ * says whose prompt just changed, and `run.started` already carries an actor id); the key and the
+ * text do not.
+ */
+interface AgentMemoryWritten {
+    runId: string;
+    scope: string;
+    /** Length of the stored fact in characters — never the fact itself. */
+    chars: number;
+}
 /**
  * A transient-classified tool error being retried in place (no new checkpoint) — see
  * `invokeWithTransientRetry`. Emitted once per retry (not for the final, non-retried outcome).
@@ -1771,6 +4065,17 @@ interface AgentFollowUpsSpan {
     /** How many follow-up questions were requested. */
     count: number;
 }
+/**
+ * START payload of an `aviary:agent:structured-output:*` span — the formatting pass that restates a
+ * finished answer as `AgentLoopDeps.outputSchema`. `attempt` is 0 for the pass itself and counts up
+ * for each bounded repair, so a run that needed three tries is visible as three spans.
+ */
+interface AgentStructuredOutputSpan {
+    runId: string;
+    /** Zero-based model-call index of the final turn whose answer is being restated. */
+    step: number;
+    attempt: number;
+}
 /** Declaration-merge so `emit('agent', ...)`, `trace('agent', ...)` and telescope infer the agent payloads. */
 declare module '@dudousxd/nestjs-diagnostics' {
     interface ChannelRegistry {
@@ -1783,11 +4088,15 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'skills.resolved': AgentSkillsResolved;
+            'memory.resolved': AgentMemoryResolved;
+            'memory.written': AgentMemoryWritten;
             'tool.retry': AgentToolRetry;
             'llm.turn': AgentLlmTurnSpan;
             'tool.execution': AgentToolExecutionSpan;
             retrieval: AgentRetrievalSpan;
             'follow-ups': AgentFollowUpsSpan;
+            'structured-output': AgentStructuredOutputSpan;
         };
     }
 }
@@ -1800,6 +4109,9 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 declare function publishAgentToolRetry(payload: AgentToolRetry): void;
+declare function publishAgentSkillsResolved(payload: AgentSkillsResolved): void;
+declare function publishAgentMemoryResolved(payload: AgentMemoryResolved): void;
+declare function publishAgentMemoryWritten(payload: AgentMemoryWritten): void;
 /**
  * Events published ONLY as spans — via `trace('agent', ...)` on the five `:start`/`:end`/
  * `:asyncStart`/`:asyncEnd`/`:error` sub-channels — never as point events on the base channel.
@@ -1807,13 +4119,13 @@ declare function publishAgentToolRetry(payload: AgentToolRetry): void;
  * nothing to subscribe to on their base channels, and claiming their keys would be meaningless
  * (the generic bridge only records point traffic).
  */
-type AgentSpanEvent = 'llm.turn' | 'tool.execution' | 'retrieval' | 'follow-ups';
+type AgentSpanEvent = 'llm.turn' | 'tool.execution' | 'retrieval' | 'follow-ups' | 'structured-output';
 /** All span-only events, in a stable order — for a future span recorder to derive sub-channels from. */
 declare const AGENT_SPAN_EVENTS: readonly AgentSpanEvent[];
 /** Every POINT event key declared on `ChannelRegistry['agent']` above — derived, not hand-copied. */
 type AgentDiagnosticEvent = Exclude<keyof ChannelRegistry['agent'], AgentSpanEvent>;
 /**
- * All 9 point events on `ChannelRegistry['agent']`, in a stable order — handy for wiring
+ * All 12 point events on `ChannelRegistry['agent']`, in a stable order — handy for wiring
  * subscribers (mirrors nestjs-media's `MEDIA_DIAGNOSTIC_EVENTS`). Span-only events (see
  * {@link AgentSpanEvent}) are excluded. A drift between this list and the registry is a compile
  * error in both directions: an extra/misspelled entry fails this array's own
@@ -1835,4 +4147,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_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type DetailThreadRef, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, type InvokeWithTransientRetryOptions, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, type ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, type ToolDefinition, ToolDisabledError, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, 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, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, canActorUseTool, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, invokeWithTransientRetry, isToolEnabled, isTransientToolError, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, resolveToolTransientRetryNumbers, rollupThreadUsage, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, truncateDetailContent, withToolTimeout };
+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_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, 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, staticSkillProvider, summarizeWithModel, tenantScope, traceLlmTurn, traceToolExecution, truncateDetailContent, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, writeMemory };