@dudousxd/nestjs-agent-core 0.33.0 → 0.35.0

package/dist/{tool-CMTuoJ2v.d.cts → stream-events-CgWqAI-1.d.cts}

@@ -70,600 +70,200 @@ declare function readElicitationInput(raw: unknown): ElicitationInput | undefine
 declare function readElicitationQuestions(input: unknown): ElicitationQuestion[];
 
 /**
- * Asking the USER a structured question, and waiting for the answer.
+ * What a store knows about a tool call, read back when its message carries no result for it — see
+ * {@link import('./spi/agent-store.js').AgentStore.toolCallOutcomes}.
+ */
+interface ToolCallOutcome {
+    id: string;
+    status: ToolCallStatus;
+    output?: unknown;
+    error?: string;
+}
+/** What the model is told about a call whose turn died before the call was settled. */
+declare const UNFINISHED_TOOL_CALL: string;
+/** What is written on the row of a call whose run ended without settling it. */
+declare const RUN_ENDED_BEFORE_TOOL_CALL = "the run ended before this tool call was settled";
+/** The ids of every tool call in `messages` that the message asking for it holds no result for. */
+declare function danglingToolCallIds(messages: readonly ModelMessage[]): string[];
+/**
+ * Give every tool call in a thread's history a result.
  *
- * `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.
+ * A turn writes its results onto the assistant message once the step's LAST tool has settled. A turn
+ * that dies before that — its run failed, its worker was killed, an approval was never answered and
+ * the run was abandoned — leaves an assistant message that asks for tools and is answered by
+ * nothing. A provider refuses a prompt shaped like that (a tool call must be followed by its
+ * result), so every LATER turn on the thread fails too, with an error about the stream rather than
+ * about the history: one dead turn makes the whole conversation unusable.
+ *
+ * Here each such call is settled from what is actually known: the call's own row where the store
+ * can read it (`outcomes` — a tool that DID run hands the model its real output, so it is not run a
+ * second time), and otherwise a result saying the call was never completed. Pure: the same messages
+ * and outcomes always produce the same prompt, so a replay composes what the first attempt did.
+ * Messages with nothing dangling are returned as they are.
  */
+declare function settleDanglingToolCalls(messages: ModelMessage[], outcomes?: readonly ToolCallOutcome[]): ModelMessage[];
 
-/** One choice a question offers. */
-interface ElicitationOption {
-    /** Stable identifier submitted back. Never shown to the user. */
-    value: string;
-    /** What the user reads. */
-    label: string;
+interface CreateThreadInput {
+    actor: Actor;
+    transient?: boolean;
+    title?: 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.
+     * Create the thread under THIS id instead of a generated one — for a caller whose protocol names
+     * the conversation itself (AG-UI's `threadId`, at most 255 characters). OPTIONAL to honour: a
+     * store that ignores it still creates a thread, under an id of its own, and the caller reads the
+     * id off the result. A store that honours it rejects an id already taken (soft-deleted threads
+     * included).
      */
-    hotkey?: string;
+    id?: string;
 }
-/** One question in a set. */
-interface ElicitationQuestion {
-    /** Unique within its request; the key answers come back under. */
-    id: string;
-    prompt: string;
-    /** A line of help under the prompt. */
-    description?: string;
+interface AppendMessageInput {
+    threadId: string;
+    role: StoredMessage['role'];
+    content: string;
+    /** Which agent produced this message (assistant messages) — provenance. */
+    agentName?: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
+    attachments?: MessageAttachment[];
+    followUps?: string[];
+    usage?: MessageUsage;
     /**
-     * The choices. Required unless {@link input} asks for a typed value — then optional, and a UI may
-     * offer them as suggestions. An `input` of type `select` still picks from these.
+     * 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.
      */
-    options?: ElicitationOption[];
+    runId?: string;
+    /** The step's streamed thinking. See {@link StoredMessage.reasoning}. */
+    reasoning?: string;
+    /** Time spent thinking in this step, in ms. See {@link StoredMessage.reasoningMs}. */
+    reasoningMs?: number;
+    /** Components pushed during this step. See {@link StoredMessage.ui}. */
+    ui?: AgentUiComponent[];
+}
+interface RecordToolCallInput {
+    toolCallId: string;
+    messageId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+    input: unknown;
+    status: ToolCallStatus;
     /**
-     * Ask for a typed value (a number, a date, a sentence…) instead of — or, for `select`, on top of —
-     * a pick from `options`. The answer is still a `string[]`, in the type's canonical form; see
-     * `elicitation-input.ts`.
+     * The run (turn) this tool call belongs to — enables a governance surface to deep-link a tool
+     * call out to its trace waterfall. Optional so a caller predating this (or a store's own
+     * synthetic tool calls) can omit it; the store persists it as `null` when absent.
      */
-    input?: ElicitationInput;
-    /** More than one option may be chosen. Omit → single choice. */
-    multiple?: boolean;
+    runId?: string;
     /**
-     * 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.
+     * Who has to approve this call (`'requester'` or a role), from the turn's `ApprovalPolicy`. Set on
+     * an action call that was put to a person — or approved by a remembered decision — and never
+     * otherwise; persisted as `null` when absent.
      */
-    defaults?: string[];
-    /** Accept values that are not among `options` (a typed-in answer). Omit → options only. */
-    allowFreeText?: boolean;
+    approver?: string;
+    /** ISO-8601 instant the approval request lapses. Absent → it never does. */
+    expiresAt?: string;
 }
-/**
- * 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[];
+interface UpdateToolCallInput {
+    toolCallId: string;
+    status: ToolCallStatus;
+    output?: unknown;
+    error?: string;
+    executionMs?: number;
+    executedByRef?: string;
+    /** The approval asked for later calls of this tool in this thread to run without asking. */
+    remember?: boolean;
+    /** The surface the decision came through. See {@link import('../types.js').Decision.decidedVia}. */
+    decidedVia?: string;
 }
-/** 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;
+/** What the approve/reject routes need to know about a call before they signal a decision on it. */
+interface ToolCallApprovalState {
+    status: ToolCallStatus;
+    /** `null` for a call no policy put to anyone (an `ask`, or a row written before approvers existed). */
+    approver: string | null;
+    expiresAt: string | null;
+}
+/** Patch applied by {@link AgentStore.updateThread}. An omitted key leaves that field untouched. */
+interface UpdateThreadInput {
+    title?: string;
+    /** `null` clears the thread's default agent (falls back to the module default). */
+    defaultAgent?: string | null;
+    /** `null` unpins the thread's model (turns run on the provider default). */
+    model?: string | null;
+}
+interface RecordUsageInput {
+    threadId: string;
+    actorRef: string;
+    messageId?: string;
+    modelId: string;
+    purpose: UsagePurpose;
+    usage: MessageUsage;
+    /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
+    costUsd?: number;
+}
+interface RecordRunStartInput {
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    agentName?: string;
     /**
-     * The surface the answer came through — `'web'`, `'slack'`, `'console'`, … — the counterpart of
-     * an approval's `decidedVia`.
+     * 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.
      */
-    answeredVia?: string;
+    parentRunId?: string;
+    /** sha256 hex of the run's resolved (pre-RAG) system prompt — identifies the prompt VERSION. */
+    promptHash?: 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[];
+interface RecordRunEndInput {
+    runId: string;
     /**
-     * Who answered (or skipped) — the reply's `answeredByRef`, which a host may make a display name.
-     * The counterpart of an approval's `decidedBy`. Absent when the reply did not say.
+     * `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.
      */
-    answeredBy?: string;
-    /** The surface it came through (`'web'`, `'slack'`, …) — an approval's `decidedVia`. */
-    answeredVia?: string;
+    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[];
 }
 /**
- * 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.
+ * A store that can hand a turn the WINDOW it is about to send, instead of the thread's transcript.
  *
- * 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.
+ * {@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.
  *
- * 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.
+ * `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`.
  *
- * 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 structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
- *
- * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
- * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
- * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
- * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
- * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
- * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
- *
- * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
- * the adapter owns model-parts → event, the transport owns event → UI-chunk.
- *
- * The vocabulary is also a CONTRACT for runners that are not this library's loop: anything that
- * writes these frames (one JSON object per SSE `data:` line) gets the React transport, transcript
- * model and hooks for free. Two rules keep it evolvable:
- *  - every frame is a JSON object with a string `kind`; a reader MUST tolerate kinds it does not
- *    know (the React transport forwards them as `data-<kind>` parts rather than dropping them);
- *  - fields are only ever added, and new fields are optional.
- */
-
-/**
- * A component the server pushed into the conversation: generative UI that is NOT a tool call's
- * rendering. It is addressed by `component` (a key in the client's own component registry), never
- * by a tool name, so a runner can emit one from anywhere — a tool body, a post-processing step, a
- * sandboxed agent that renders through its own protocol.
- *
- * `id` is the component's identity within the message: a second frame with the same `id` REPLACES
- * the first (streaming props into a chart, flipping a card from "loading" to "ready"), it never
- * adds a second component.
- */
-interface AgentUiComponent {
-    id: string;
-    /** Registry key the client resolves to its own renderer, e.g. `data-table`. */
-    component: string;
-    props: Record<string, unknown>;
-    /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
-    version?: number;
-    /**
-     * The tool call that pushed the component (`ctx.emitUi`), when one did. Lets a client place it
-     * with that call — a reloaded message puts it right after the call's tool part, where the live
-     * stream showed it. Absent for a component pushed outside a tool.
-     */
-    toolCallId?: string;
-}
-/**
- * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
- * settled through the tool-call approve/reject routes, by its `toolCallId`.
- */
-interface AgentApprovalRequest {
-    /** The tool call awaiting the decision — the `id` of a call already announced on this stream. */
-    id: string;
-    /**
-     * Who may decide. Open vocabulary the host defines — `'requester'` (the person chatting),
-     * `'admin'`, a role name, a team. A client uses it to say "waiting on an admin" instead of
-     * offering buttons the viewer cannot use.
-     */
-    approver: string;
-    /** ISO-8601 instant after which the request lapses. Absent → it never expires. */
-    expiresAt?: string;
-    /** Why this call needs a person, in words for that person. */
-    reason?: string;
-}
-/**
- * How an approval settled — the other half of {@link AgentApprovalRequest}, under the same `id`.
- * Metadata again: the call's own outcome still arrives as `tool-output` (approved and ran),
- * `tool-output-error` (approved and failed) or `tool-output-denied` (rejected or expired).
- */
-interface AgentApprovalSettlement {
-    id: string;
-    status: 'approved' | 'rejected' | 'expired';
-    /** Repeated from the request, for a call approved without one being streamed (a remembered approval). */
-    approver?: string;
-    /** Opaque ref of who decided. Absent on an expiry. */
-    decidedBy?: string;
-    /** The surface the decision came through: `'web'`, `'slack'`, `'remembered'`, … */
-    decidedVia?: string;
-    /** The approval also covers later calls of this tool in this thread. */
-    remember?: boolean;
-    /** What the person said when declining. */
-    reason?: string;
-}
-type AgentStreamEvent = {
-    kind: 'step-start';
-}
-/**
- * Closes the step opened by the matching `step-start`. Carries the model call's token usage and
- * `costUsd` (an estimate from the bound pricing store, or `null` when unpriced/unbound — never a
- * fabricated `0`) so a live client can render running cost without waiting for a thread re-fetch.
- */
- | {
-    kind: 'step-finish';
-    usage?: MessageUsage;
-    costUsd?: number | null;
-    /**
-     * How long the model spent thinking in this step, in ms — the same number persisted as
-     * `StoredMessage.reasoningMs`, so a live thread and a reloaded one read the same duration.
-     * Absent when the step had no reasoning.
-     */
-    reasoningMs?: number;
-} | {
-    kind: 'text';
-    text: string;
-} | {
-    kind: 'reasoning';
-    text: string;
-}
-/**
- * `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool.
- *
- * `parentId` nests this call under another call on the same stream: the inner calls a code-mode
- * `execute` makes, the tools a delegated sub-agent runs. The parent must be announced first. A
- * call's parent is fixed by its first frame that names one; later frames may omit it.
- */
- | {
-    kind: 'tool-input-start';
-    id: string;
-    name: string;
-    toolKind: 'read' | 'action';
-    parentId?: string;
-} | {
-    kind: 'tool-input-delta';
-    id: string;
-    delta: string;
-} | {
-    kind: 'tool-input-available';
-    id: string;
-    name: string;
-    input: unknown;
-    toolKind: 'read' | 'action';
-    /** Same as on `tool-input-start`, for a runner that announces a call without streaming its input. */
-    parentId?: string;
-} | {
-    kind: 'tool-output';
-    id: string;
-    output: unknown;
-} | {
-    kind: 'tool-output-error';
-    id: string;
-    error: string;
-}
-/**
- * A person was asked to approve an action tool and declined it. Its own frame, NOT
- * `tool-output-error`: a refusal is a decision with a known outcome — nothing ran — while a
- * failure is an outcome nobody chose and whose effects are unknown. Rendering them the same way
- * tells an operator their own "no" was a malfunction. Maps onto the SDK's `output-denied` tool
- * part state, which a client reads without knowing any tool's name.
- */
- | {
-    kind: 'tool-output-denied';
-    id: string;
-    reason?: 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;
-}
-/**
- * An action tool call (already announced by `tool-input-start`/`tool-input-available` under the
- * same `id`) is parked on a person. Optional: a client still treats an `action` call stuck at
- * its input as pending — this frame adds WHO has to decide and UNTIL WHEN, and moves the call
- * into the AI SDK's native `approval-requested` state.
- */
- | ({
-    kind: 'approval-requested';
-} & AgentApprovalRequest)
-/**
- * A parked action call was decided (or lapsed). Optional, like `approval-requested`: it adds WHO
- * decided, THROUGH WHAT and whether the approval is REMEMBERED; the outcome itself rides the
- * call's own output frame. See {@link AgentApprovalSettlement}.
- */
- | ({
-    kind: 'approval-settled';
-} & AgentApprovalSettlement)
-/**
- * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
- * call. See {@link AgentUiComponent}.
- */
- | ({
-    kind: 'ui';
-} & AgentUiComponent)
-/**
- * The thread's title was set or changed while this run streamed (typically derived from the
- * first exchange). Thread-level, not message content: a client updates its header/sidebar and
- * does not render it in the transcript.
- */
- | {
-    kind: 'title';
-    title: string;
-}
-/**
- * Host-defined facts about the message being streamed (the model that answered, how long it took,
- * the error it ended with), merged into the client message's `metadata`. The persisted
- * counterpart is `StoredMessage.metadata`, so a reload reads the same values. The library's own
- * loop never writes it; a runner that is not this library's loop uses it for what its store keeps
- * per message.
- */
- | {
-    kind: 'message-metadata';
-    metadata: Record<string, unknown>;
-}
-/**
- * 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';
-}
-/**
- * The thread's message queue changed — a snapshot of the whole queue, never a delta, so a client
- * that missed one frame is corrected by the next. Written into the stream of the run that is
- * holding the thread: when someone queues, edits, reorders or removes a waiting message, and, just
- * before this run's own terminal frame, with what happens next — `started` names the queued
- * message that became the next turn and that turn's run id (attach to it with
- * `GET <base>/chat/:runId/stream`), `queue.paused` says why nothing starts.
- */
- | {
-    kind: 'queue';
-    queue: ChatQueueState;
-    started?: {
-        messageId: string;
-        runId: string;
-    };
-};
-/** 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;
-    transient?: boolean;
-    title?: string;
-}
-interface AppendMessageInput {
-    threadId: string;
-    role: StoredMessage['role'];
-    content: string;
-    /** Which agent produced this message (assistant messages) — provenance. */
-    agentName?: string;
-    toolCalls?: ToolCallRequest[];
-    toolResults?: ToolResult[];
-    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
-    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;
-    /** The step's streamed thinking. See {@link StoredMessage.reasoning}. */
-    reasoning?: string;
-    /** Time spent thinking in this step, in ms. See {@link StoredMessage.reasoningMs}. */
-    reasoningMs?: number;
-    /** Components pushed during this step. See {@link StoredMessage.ui}. */
-    ui?: AgentUiComponent[];
-}
-interface RecordToolCallInput {
-    toolCallId: string;
-    messageId: string;
-    toolName: string;
-    toolType: 'read' | 'action';
-    input: unknown;
-    status: ToolCallStatus;
-    /**
-     * The run (turn) this tool call belongs to — enables a governance surface to deep-link a tool
-     * call out to its trace waterfall. Optional so a caller predating this (or a store's own
-     * synthetic tool calls) can omit it; the store persists it as `null` when absent.
-     */
-    runId?: string;
-    /**
-     * Who has to approve this call (`'requester'` or a role), from the turn's `ApprovalPolicy`. Set on
-     * an action call that was put to a person — or approved by a remembered decision — and never
-     * otherwise; persisted as `null` when absent.
-     */
-    approver?: string;
-    /** ISO-8601 instant the approval request lapses. Absent → it never does. */
-    expiresAt?: string;
-}
-interface UpdateToolCallInput {
-    toolCallId: string;
-    status: ToolCallStatus;
-    output?: unknown;
-    error?: string;
-    executionMs?: number;
-    executedByRef?: string;
-    /** The approval asked for later calls of this tool in this thread to run without asking. */
-    remember?: boolean;
-    /** The surface the decision came through. See {@link import('../types.js').Decision.decidedVia}. */
-    decidedVia?: string;
-}
-/** What the approve/reject routes need to know about a call before they signal a decision on it. */
-interface ToolCallApprovalState {
-    status: ToolCallStatus;
-    /** `null` for a call no policy put to anyone (an `ask`, or a row written before approvers existed). */
-    approver: string | null;
-    expiresAt: string | null;
-}
-/** Patch applied by {@link AgentStore.updateThread}. An omitted key leaves that field untouched. */
-interface UpdateThreadInput {
-    title?: string;
-    /** `null` clears the thread's default agent (falls back to the module default). */
-    defaultAgent?: string | null;
-    /** `null` unpins the thread's model (turns run on the provider default). */
-    model?: string | null;
-}
-interface RecordUsageInput {
-    threadId: string;
-    actorRef: string;
-    messageId?: string;
-    modelId: string;
-    purpose: UsagePurpose;
-    usage: MessageUsage;
-    /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
-    costUsd?: number;
-}
-interface RecordRunStartInput {
-    runId: string;
-    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;
-    /**
-     * `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.
+ * 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>;
@@ -773,6 +373,21 @@ interface AgentStore {
     setMessageFeedback?(messageId: string, feedback: MessageFeedback | null): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
+    /**
+     * OPTIONAL: what is recorded about each of these calls — its status, and the output or error it
+     * settled with. Read when a thread's history holds a tool call its message has no result for (the
+     * turn died mid-step), so the next turn can be told what actually happened instead of being
+     * handed a call answered by nothing. Unknown ids are left out. Absent → such a call is put to the
+     * model as never completed.
+     */
+    toolCallOutcomes?(toolCallIds: readonly string[]): Promise<ToolCallOutcome[]>;
+    /**
+     * OPTIONAL: settle every call of `runId` still awaiting a decision (`pending_approval`) as
+     * `failed` with `error`, and answer how many there were. Called when the run ends without
+     * settling them — it failed, or it was found dead — so an approval card never waits on a run that
+     * will not come back. Calls already settled are left alone, so a repeat changes nothing.
+     */
+    failUnsettledToolCalls?(runId: string, error: string): Promise<number>;
     /**
      * OPTIONAL: the names of the tools whose approval someone asked to REMEMBER in this thread — an
      * approved call persisted with `remember: true`. The loop approves a later call of one of them
@@ -1695,281 +1310,646 @@ interface ThreadSummary {
      */
     model?: string | null;
 }
-interface StoredMessage {
-    id: string;
-    role: MessageRole;
-    content: string;
-    /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
-    agentName?: string;
-    toolCalls?: ToolCallRequest[];
-    toolResults?: ToolResult[];
-    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
-    attachments?: MessageAttachment[];
-    followUps?: string[];
-    usage?: MessageUsage;
-    /** The run (turn) that produced this message; absent on a row written before this was recorded. */
-    runId?: string;
+interface StoredMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
+    agentName?: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
+    attachments?: MessageAttachment[];
+    followUps?: string[];
+    usage?: MessageUsage;
+    /** The run (turn) that produced this message; absent on a row written before this was recorded. */
+    runId?: string;
+    /**
+     * The model's thinking for this step, as it streamed (`reasoning` frames), so a reloaded thread
+     * shows it where the live one did. Absent when the model produced none, or on a row written
+     * before this was recorded.
+     */
+    reasoning?: string;
+    /** How long the model spent thinking in this step, in ms — what a "Thought for 4s" label reads. */
+    reasoningMs?: number;
+    /**
+     * Components the server pushed into this step (`ui` frames), in first-seen order with the last
+     * props for each `id` — a reloaded thread replays them as `data-ui` parts.
+     */
+    ui?: AgentUiComponent[];
+    /**
+     * The approval record of every call on this message that was put to a person under an
+     * {@link import('./spi/approval-policy.js').ApprovalPolicy} — who had to decide, until when, and how
+     * it settled. Read off the tool-call rows by the store; absent when no call on the message asked
+     * for one, or on a store that does not record approvals.
+     */
+    approvals?: ToolCallApproval[];
+    /**
+     * The thread owner's rating of this message (`POST <base>/messages/:id/feedback`). Absent when
+     * nobody rated it, or on a store that does not record feedback.
+     */
+    feedback?: MessageFeedback;
+    /**
+     * Host-defined facts about the message (which model answered, how long it took, the error a turn
+     * ended with, …) — what a runner that is not this library's loop streamed as a
+     * `message-metadata` frame. Replayed into the client message's `metadata`, under the library's
+     * own keys (`usage`, `feedback`, `createdAt` win on a clash). Never read by the library itself.
+     */
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+/** A thumbs-up/down on one message, with an optional free-text comment. */
+type MessageFeedbackValue = 'up' | 'down';
+/** What {@link StoredMessage.feedback} holds. Not copied when a thread is forked. */
+interface MessageFeedback {
+    value: MessageFeedbackValue;
+    comment?: string;
+    /** ISO-8601 instant the rating was last set. */
+    updatedAt: string;
+}
+/**
+ * How one approval stands. `pending` → still parked; `approved` → someone said yes (or a remembered
+ * approval did); `rejected` → someone said no; `expired` → nobody answered before `expiresAt`.
+ */
+type ToolCallApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+/** The persisted approval metadata of one action tool call. See {@link StoredMessage.approvals}. */
+interface ToolCallApproval {
+    toolCallId: string;
+    /** Who may decide: `'requester'` (the thread's own actor) or a role name. */
+    approver: string;
+    /** ISO-8601 instant the request lapses; absent → it never does. */
+    expiresAt?: string;
+    status: ToolCallApprovalStatus;
+    /** The decision asked for later calls of this tool in this thread to be approved automatically. */
+    remember?: boolean;
+    /** Opaque ref of who decided. Absent while pending and on an expiry. */
+    decidedBy?: string;
+    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    decidedVia?: string;
+    /** What the person said when declining. */
+    reason?: string;
+}
+interface ThreadDetail extends ThreadSummary {
+    messages: StoredMessage[];
+    /**
+     * Messages sent while a turn was running, waiting to run after it, and whether the queue is
+     * draining. Present when the store supports a queue (`ChatQueueStore`); the REST read-model
+     * omits it otherwise.
+     */
+    queue?: ChatQueueState;
+}
+type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
+/** An approval request lapsed before anyone decided; the tool never ran. */
+ | 'expired';
+/**
+ * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
+ * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
+ */
+interface LlmStepEnvelope {
+    /** Undefined = default agent (same semantics as {@link AgentRunInput.agentName}). */
+    agentName?: string;
+    system: string;
+    messages: ModelMessage[];
+    /** The turn's actor — the handler re-derives tool definitions from it (definitionsFor). */
+    actor: Actor;
+    /**
+     * The turn's thread — with {@link actor}, what a tool's per-turn `describe` is scoped on. Optional
+     * so an envelope from a loop that predates it still parses.
+     */
+    threadId?: string;
+    /**
+     * 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 turn's selected model ({@link AgentRunInput.model}), for the worker's provider call. */
+    model?: string;
+}
+/**
+ * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
+ * from DI).
+ */
+interface ToolStepCtx {
+    actor: Actor;
+    threadId: string;
+    runId: string;
+    requestId: string;
+    agentName?: string;
+    pageContext?: PageContext;
+}
+/** Serializable input for a dispatched tool-execution step. */
+interface ToolStepEnvelope {
+    toolName: string;
+    input: unknown;
+    ctx: ToolStepCtx;
+    /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
+    timeoutMs?: number;
+    /**
+     * The numeric half of `toolTransientRetry` (resolved by the loop from `AgentLoopDeps`, always a
+     * definite value — `false` when disabled, else concrete `{ attempts, backoffMs }` with defaults
+     * already filled in) — never `undefined`, so the dispatched handler gets the SAME policy the
+     * loop would have used locally. The `classify` function is deliberately absent: it isn't
+     * wire-safe, so the handler resolves its own from its local module options (see
+     * `AgentRunSteps.tool`) instead of trying to serialize a function.
+     */
+    transientRetry: ToolTransientRetryNumbers | false;
+    /**
+     * The dispatching loop reads the components the tool pushed (`ctx.emitUi`) off the step's result.
+     * A handler that sees it returns {@link wrapToolStepOutput}'s envelope when the tool pushed any —
+     * and ONLY then, so a loop that predates this (and never sets it) always gets the bare output.
+     */
+    collectUi?: boolean;
+}
+/**
+ * What `GET <base>/config` answers — server-side facts a client would otherwise repeat in its own
+ * configuration (and let drift).
+ */
+interface AgentClientConfig {
+    attachments: AgentAttachmentConfig;
+    /** A model catalog is bound, so `GET <base>/models` lists something to pick. */
+    models: {
+        enabled: boolean;
+    };
+    /** Sends are refused with `429` once `GET <base>/quota` reports `blocked`. */
+    quota: {
+        enforced: boolean;
+    };
+    /** No `actorResolver`: every browser is its own anonymous actor. */
+    identity: {
+        anonymous: boolean;
+    };
+}
+/** The attachment rules in force — what the upload route enforces. */
+interface AgentAttachmentConfig {
+    /** A staging store is bound, so uploads work at all. */
+    enabled: boolean;
+    /** How a client uploads (`null` when `enabled` is false). */
+    upload: 'multipart' | 'resumable' | null;
+    maxBytes: number;
+    allowedContentTypes: readonly string[];
+    /** How many attachments one message may name. */
+    maxPerMessage: number;
+}
+
+/**
+ * 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;
+    /** A line of help under the prompt. */
+    description?: string;
+    /**
+     * The choices. Required unless {@link input} asks for a typed value — then optional, and a UI may
+     * offer them as suggestions. An `input` of type `select` still picks from these.
+     */
+    options?: ElicitationOption[];
+    /**
+     * Ask for a typed value (a number, a date, a sentence…) instead of — or, for `select`, on top of —
+     * a pick from `options`. The answer is still a `string[]`, in the type's canonical form; see
+     * `elicitation-input.ts`.
+     */
+    input?: ElicitationInput;
+    /** 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 {
     /**
-     * The model's thinking for this step, as it streamed (`reasoning` frames), so a reloaded thread
-     * shows it where the live one did. Absent when the model produced none, or on a row written
-     * before this was recorded.
+     * 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.
      */
-    reasoning?: string;
-    /** How long the model spent thinking in this step, in ms — what a "Thought for 4s" label reads. */
-    reasoningMs?: number;
+    answers: Record<string, string[]>;
     /**
-     * Components the server pushed into this step (`ui` frames), in first-seen order with the last
-     * props for each `id` — a reloaded thread replays them as `data-ui` parts.
+     * 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.
      */
-    ui?: AgentUiComponent[];
+    skipped?: boolean;
+    /** Opaque ref of WHO answered, when it wasn't the run's own actor. */
+    answeredByRef?: string;
     /**
-     * The approval record of every call on this message that was put to a person under an
-     * {@link import('./spi/approval-policy.js').ApprovalPolicy} — who had to decide, until when, and how
-     * it settled. Read off the tool-call rows by the store; absent when no call on the message asked
-     * for one, or on a store that does not record approvals.
+     * The surface the answer came through — `'web'`, `'slack'`, `'console'`, … — the counterpart of
+     * an approval's `decidedVia`.
      */
-    approvals?: ToolCallApproval[];
+    answeredVia?: 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[];
     /**
-     * The thread owner's rating of this message (`POST <base>/messages/:id/feedback`). Absent when
-     * nobody rated it, or on a store that does not record feedback.
+     * Who answered (or skipped) — the reply's `answeredByRef`, which a host may make a display name.
+     * The counterpart of an approval's `decidedBy`. Absent when the reply did not say.
      */
-    feedback?: MessageFeedback;
+    answeredBy?: string;
+    /** The surface it came through (`'web'`, `'slack'`, …) — an approval's `decidedVia`. */
+    answeredVia?: 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;
     /**
-     * Host-defined facts about the message (which model answered, how long it took, the error a turn
-     * ended with, …) — what a runner that is not this library's loop streamed as a
-     * `message-metadata` frame. Replayed into the client message's `metadata`, under the library's
-     * own keys (`usage`, `feedback`, `createdAt` win on a clash). Never read by the library itself.
+     * `'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.
      */
-    metadata?: Record<string, unknown>;
-    createdAt: string;
+    when?: 'thread-start' | 'every-turn';
 }
-/** A thumbs-up/down on one message, with an optional free-text comment. */
-type MessageFeedbackValue = 'up' | 'down';
-/** What {@link StoredMessage.feedback} holds. Not copied when a thread is forked. */
-interface MessageFeedback {
-    value: MessageFeedbackValue;
-    comment?: string;
-    /** ISO-8601 instant the rating was last set. */
-    updatedAt: string;
+declare const DEFAULT_INTAKE_PREAMBLE = "A few questions before I start. I have pre-picked what I would choose, so confirming is enough.";
+
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ *
+ * The vocabulary is also a CONTRACT for runners that are not this library's loop: anything that
+ * writes these frames (one JSON object per SSE `data:` line) gets the React transport, transcript
+ * model and hooks for free. Two rules keep it evolvable:
+ *  - every frame is a JSON object with a string `kind`; a reader MUST tolerate kinds it does not
+ *    know (the React transport forwards them as `data-<kind>` parts rather than dropping them);
+ *  - fields are only ever added, and new fields are optional.
+ */
+
+/**
+ * A component the server pushed into the conversation: generative UI that is NOT a tool call's
+ * rendering. It is addressed by `component` (a key in the client's own component registry), never
+ * by a tool name, so a runner can emit one from anywhere — a tool body, a post-processing step, a
+ * sandboxed agent that renders through its own protocol.
+ *
+ * `id` is the component's identity within the message: a second frame with the same `id` REPLACES
+ * the first (streaming props into a chart, flipping a card from "loading" to "ready"), it never
+ * adds a second component.
+ */
+interface AgentUiComponent {
+    id: string;
+    /** Registry key the client resolves to its own renderer, e.g. `data-table`. */
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
+    version?: number;
+    /**
+     * The tool call that pushed the component (`ctx.emitUi`), when one did. Lets a client place it
+     * with that call — a reloaded message puts it right after the call's tool part, where the live
+     * stream showed it. Absent for a component pushed outside a tool.
+     */
+    toolCallId?: string;
 }
 /**
- * How one approval stands. `pending` → still parked; `approved` → someone said yes (or a remembered
- * approval did); `rejected` → someone said no; `expired` → nobody answered before `expiresAt`.
+ * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
+ * settled through the tool-call approve/reject routes, by its `toolCallId`.
  */
-type ToolCallApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
-/** The persisted approval metadata of one action tool call. See {@link StoredMessage.approvals}. */
-interface ToolCallApproval {
-    toolCallId: string;
-    /** Who may decide: `'requester'` (the thread's own actor) or a role name. */
+interface AgentApprovalRequest {
+    /** The tool call awaiting the decision — the `id` of a call already announced on this stream. */
+    id: string;
+    /**
+     * Who may decide. Open vocabulary the host defines — `'requester'` (the person chatting),
+     * `'admin'`, a role name, a team. A client uses it to say "waiting on an admin" instead of
+     * offering buttons the viewer cannot use.
+     */
     approver: string;
-    /** ISO-8601 instant the request lapses; absent → it never does. */
+    /** ISO-8601 instant after which the request lapses. Absent → it never expires. */
     expiresAt?: string;
-    status: ToolCallApprovalStatus;
-    /** The decision asked for later calls of this tool in this thread to be approved automatically. */
-    remember?: boolean;
-    /** Opaque ref of who decided. Absent while pending and on an expiry. */
+    /** Why this call needs a person, in words for that person. */
+    reason?: string;
+}
+/**
+ * How an approval settled — the other half of {@link AgentApprovalRequest}, under the same `id`.
+ * Metadata again: the call's own outcome still arrives as `tool-output` (approved and ran),
+ * `tool-output-error` (approved and failed) or `tool-output-denied` (rejected or expired).
+ */
+interface AgentApprovalSettlement {
+    id: string;
+    status: 'approved' | 'rejected' | 'expired';
+    /** Repeated from the request, for a call approved without one being streamed (a remembered approval). */
+    approver?: string;
+    /** Opaque ref of who decided. Absent on an expiry. */
     decidedBy?: string;
-    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    /** The surface the decision came through: `'web'`, `'slack'`, `'remembered'`, … */
     decidedVia?: string;
+    /** The approval also covers later calls of this tool in this thread. */
+    remember?: boolean;
     /** What the person said when declining. */
-    reason?: string;
-}
-interface ThreadDetail extends ThreadSummary {
-    messages: StoredMessage[];
-    /**
-     * Messages sent while a turn was running, waiting to run after it, and whether the queue is
-     * draining. Present when the store supports a queue (`ChatQueueStore`); the REST read-model
-     * omits it otherwise.
-     */
-    queue?: ChatQueueState;
+    reason?: string;
+}
+type AgentStreamEvent = {
+    kind: 'step-start';
 }
-type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
-/** An approval request lapsed before anyone decided; the tool never ran. */
- | 'expired';
 /**
- * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
- * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
+ * Closes the step opened by the matching `step-start`. Carries the model call's token usage and
+ * `costUsd` (an estimate from the bound pricing store, or `null` when unpriced/unbound — never a
+ * fabricated `0`) so a live client can render running cost without waiting for a thread re-fetch.
  */
-interface LlmStepEnvelope {
-    /** Undefined = default agent (same semantics as {@link AgentRunInput.agentName}). */
-    agentName?: string;
-    system: string;
-    messages: ModelMessage[];
-    /** The turn's actor — the handler re-derives tool definitions from it (definitionsFor). */
-    actor: Actor;
+ | {
+    kind: 'step-finish';
+    usage?: MessageUsage;
+    costUsd?: number | null;
     /**
-     * The turn's thread — with {@link actor}, what a tool's per-turn `describe` is scoped on. Optional
-     * so an envelope from a loop that predates it still parses.
+     * How long the model spent thinking in this step, in ms — the same number persisted as
+     * `StoredMessage.reasoningMs`, so a live thread and a reloaded one read the same duration.
+     * Absent when the step had no reasoning.
      */
-    threadId?: string;
+    reasoningMs?: number;
     /**
-     * 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.
+     * The model the step ran on: the one the provider reported, else the configured `modelId`.
+     * What a per-model usage report keys on (the AG-UI producer's `RUN_FINISHED.usage`). Absent
+     * when neither is known; a reader that does not know the field ignores it.
      */
-    bufferOutput?: boolean;
-    /** The turn's selected model ({@link AgentRunInput.model}), for the worker's provider call. */
     model?: string;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
 }
 /**
- * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
- * from DI).
+ * `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool.
+ *
+ * `parentId` nests this call under another call on the same stream: the inner calls a code-mode
+ * `execute` makes, the tools a delegated sub-agent runs. The parent must be announced first. A
+ * call's parent is fixed by its first frame that names one; later frames may omit it.
  */
-interface ToolStepCtx {
-    actor: Actor;
-    threadId: string;
-    runId: string;
-    requestId: string;
-    agentName?: string;
-    pageContext?: PageContext;
-}
-/** Serializable input for a dispatched tool-execution step. */
-interface ToolStepEnvelope {
-    toolName: string;
+ | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+    toolKind: 'read' | 'action';
+    parentId?: string;
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
     input: unknown;
-    ctx: ToolStepCtx;
-    /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
-    timeoutMs?: number;
-    /**
-     * The numeric half of `toolTransientRetry` (resolved by the loop from `AgentLoopDeps`, always a
-     * definite value — `false` when disabled, else concrete `{ attempts, backoffMs }` with defaults
-     * already filled in) — never `undefined`, so the dispatched handler gets the SAME policy the
-     * loop would have used locally. The `classify` function is deliberately absent: it isn't
-     * wire-safe, so the handler resolves its own from its local module options (see
-     * `AgentRunSteps.tool`) instead of trying to serialize a function.
-     */
-    transientRetry: ToolTransientRetryNumbers | false;
-    /**
-     * The dispatching loop reads the components the tool pushed (`ctx.emitUi`) off the step's result.
-     * A handler that sees it returns {@link wrapToolStepOutput}'s envelope when the tool pushed any —
-     * and ONLY then, so a loop that predates this (and never sets it) always gets the bare output.
-     */
-    collectUi?: boolean;
+    toolKind: 'read' | 'action';
+    /** Same as on `tool-input-start`, for a runner that announces a call without streaming its input. */
+    parentId?: string;
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
 }
 /**
- * What `GET <base>/config` answers — server-side facts a client would otherwise repeat in its own
- * configuration (and let drift).
+ * A person was asked to approve an action tool and declined it. Its own frame, NOT
+ * `tool-output-error`: a refusal is a decision with a known outcome — nothing ran — while a
+ * failure is an outcome nobody chose and whose effects are unknown. Rendering them the same way
+ * tells an operator their own "no" was a malfunction. Maps onto the SDK's `output-denied` tool
+ * part state, which a client reads without knowing any tool's name.
  */
-interface AgentClientConfig {
-    attachments: AgentAttachmentConfig;
-    /** A model catalog is bound, so `GET <base>/models` lists something to pick. */
-    models: {
-        enabled: boolean;
-    };
-    /** Sends are refused with `429` once `GET <base>/quota` reports `blocked`. */
-    quota: {
-        enforced: boolean;
-    };
-    /** No `actorResolver`: every browser is its own anonymous actor. */
-    identity: {
-        anonymous: boolean;
-    };
-}
-/** The attachment rules in force — what the upload route enforces. */
-interface AgentAttachmentConfig {
-    /** A staging store is bound, so uploads work at all. */
-    enabled: boolean;
-    /** How a client uploads (`null` when `enabled` is false). */
-    upload: 'multipart' | 'resumable' | null;
-    maxBytes: number;
-    allowedContentTypes: readonly string[];
-    /** How many attachments one message may name. */
-    maxPerMessage: number;
+ | {
+    kind: 'tool-output-denied';
+    id: string;
+    reason?: string;
 }
-
 /**
- * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
- * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
- * no denormalized copies).
+ * 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.
  */
-interface AiToolCtx {
-    actor: Actor;
-    threadId: string;
-    runId: string;
-    requestId: string;
-    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
-    agentName?: string;
-    pageContext?: PageContext;
-    /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
-    host?: unknown;
-    /**
-     * Push a component into the assistant message: streamed live as a `ui` frame and persisted on
-     * the message, so a reload shows it where the live stream did. Resolves to the component's id.
-     *
-     * `id` defaults to `<toolCallId>:ui:<n>` (the n-th push without an `id` in this invocation), so a retried or
-     * re-executed call REPLACES what it pushed before instead of adding a second copy; pass your own
-     * `id` to update one component across pushes (streaming rows into a table). `props` must be
-     * JSON; it is snapshotted when pushed.
-     *
-     * Replay-safe under the durable runner: the pushed components ride the tool step's journaled
-     * result, so a replay neither streams nor persists them again.
-     *
-     * Always present. On a surface with no conversation to push into (the MCP server, a direct
-     * `registry.invoke` without one) it is a no-op that still resolves to an id, so a tool calls
-     * `ctx.emitUi(…)` unconditionally.
-     */
-    emitUi(component: string, props: Record<string, unknown>, options?: {
-        id?: string;
-        version?: number;
-    }): Promise<{
-        id: string;
-    }>;
+ | {
+    kind: 'elicitation';
+    id: string;
+    request: ElicitationRequest;
 }
-/** A tool implementation. `I` is the parsed (Zod-validated) input. */
-interface ToolHandler<I = unknown> {
-    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
-    /**
-     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
-     * policy, so a `false` here means the model is never shown the tool rather than being shown one
-     * it will be refused. Omit → always enabled.
-     *
-     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
-     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
-     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
-     * separate question "may THIS actor use it?", and both still run.
-     *
-     * Prefer this over conditionally registering the provider: registration happens while the
-     * `@Module` metadata is built, which in most apps is before configuration is loaded.
-     */
-    isEnabled?(): boolean | Promise<boolean>;
-    /**
-     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
-     *
-     * The three existing gates all answer the question somewhere else: `roles` is static data,
-     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
-     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
-     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
-     * this actor own the base being queried, is the per-user override in the DB set today.
-     *
-     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
-     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
-     */
-    canUse?(actor: Actor): boolean | Promise<boolean>;
-    /**
-     * What the model is told about this tool for THIS turn — a description and/or input schema that
-     * depend on who is asking (a per-tenant component catalog, a per-plan list of options). Called
-     * when the turn's tool list is built, after every gate has passed; whatever it returns replaces
-     * the registered spec's `description` / `inputSchema` in the definition the model sees. Omit, or
-     * return `undefined`, to use the registered spec as is.
-     *
-     * It shapes what the model is SHOWN only: the registry still validates a call against the
-     * registered `inputSchema`, so a tool whose accepted input varies per turn registers a permissive
-     * schema and validates in `execute`.
-     */
-    describe?(scope: ToolDescribeScope): ToolDescription | undefined | Promise<ToolDescription | undefined>;
+/**
+ * An action tool call (already announced by `tool-input-start`/`tool-input-available` under the
+ * same `id`) is parked on a person. Optional: a client still treats an `action` call stuck at
+ * its input as pending — this frame adds WHO has to decide and UNTIL WHEN, and moves the call
+ * into the AI SDK's native `approval-requested` state.
+ */
+ | ({
+    kind: 'approval-requested';
+} & AgentApprovalRequest)
+/**
+ * A parked action call was decided (or lapsed). Optional, like `approval-requested`: it adds WHO
+ * decided, THROUGH WHAT and whether the approval is REMEMBERED; the outcome itself rides the
+ * call's own output frame. See {@link AgentApprovalSettlement}.
+ */
+ | ({
+    kind: 'approval-settled';
+} & AgentApprovalSettlement)
+/**
+ * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
+ * call. See {@link AgentUiComponent}.
+ */
+ | ({
+    kind: 'ui';
+} & AgentUiComponent)
+/**
+ * The thread's title was set or changed while this run streamed (typically derived from the
+ * first exchange). Thread-level, not message content: a client updates its header/sidebar and
+ * does not render it in the transcript.
+ */
+ | {
+    kind: 'title';
+    title: string;
 }
-/** Who a turn's tool list is being built for — what {@link ToolHandler.describe} can vary on. */
-interface ToolDescribeScope {
-    actor: Actor;
-    /** Absent where the list is built outside a conversation (the MCP server's `tools/list`). */
-    threadId?: string;
-    agentName?: string;
+/**
+ * Host-defined facts about the message being streamed (the model that answered, how long it took,
+ * the error it ended with), merged into the client message's `metadata`. The persisted
+ * counterpart is `StoredMessage.metadata`, so a reload reads the same values. The library's own
+ * loop never writes it; a runner that is not this library's loop uses it for what its store keeps
+ * per message.
+ */
+ | {
+    kind: 'message-metadata';
+    metadata: Record<string, unknown>;
 }
-/** A per-turn override of a tool's model-facing definition ({@link ToolHandler.describe}). */
-interface ToolDescription {
-    description?: string;
-    inputSchema?: StandardSchemaV1;
+/**
+ * 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';
 }
+/**
+ * The thread's message queue changed — a snapshot of the whole queue, never a delta, so a client
+ * that missed one frame is corrected by the next. Written into the stream of the run that is
+ * holding the thread: when someone queues, edits, reorders or removes a waiting message, and, just
+ * before this run's own terminal frame, with what happens next — `started` names the queued
+ * message that became the next turn and that turn's run id (attach to it with
+ * `GET <base>/chat/:runId/stream`), `queue.paused` says why nothing starts.
+ */
+ | {
+    kind: 'queue';
+    queue: ChatQueueState;
+    started?: {
+        messageId: string;
+        runId: string;
+    };
+};
+/** 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;
+/**
+ * The `code` of a failed run's `event: error` frame — what a client branches on, and translates.
+ * `quota_exceeded`, `output_rejected` and `structured_output_invalid` are outcomes the library words
+ * itself (their `message` is safe to show as it is); the rest are crashes, whose `message` is a
+ * generic sentence in production. Open-ended on purpose: a host's own runner may send other codes.
+ */
+type AgentStreamErrorCode = 'quota_exceeded' | 'output_rejected' | 'structured_output_invalid'
+/** The durable runtime refused a checkpoint position: the run's journal and its code disagree. */
+ | 'replay_diverged'
+/** A model call ended without producing anything. */
+ | 'model_no_output' | 'run_failed';
 
-export { ASK_TOOL_NAME as $, type Actor as A, type ThreadDetail as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type ToolCallApprovalState as F, type EnqueueMessageInput as G, type HumanReply as H, type QueuedMessage as I, type QueuedMessagePatch as J, type QueuePause as K, type LlmStepEnvelope as L, type ModelMessage as M, type AppendMessageInput as N, type ToolResult as O, type PageContext as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type MessageFeedback as V, type RecordToolCallInput as W, type UpdateToolCallInput as X, type RecordUsageInput as Y, ALL_AGENTS as Z, ASK_TOOL_DESCRIPTION as _, type ToolHandler as a, validateElicitationAnswer as a$, type AgentApprovalRequest as a0, type AgentApprovalSettlement as a1, type AgentAttachmentConfig as a2, type AgentCatalogEntry as a3, type AgentClientConfig as a4, type AgentHistoryWindow as a5, type AskToolInput as a6, type ChatQueueState as a7, DEFAULT_INTAKE_PREAMBLE as a8, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as a9, type ToolConfirmation as aA, type ToolDescription as aB, type ToolPresentationTone as aC, type ToolResultField as aD, type ToolResultView as aE, type ToolStepCtx as aF, type ToolTransientRetryNumbers as aG, type ToolTransientRetryOptions as aH, type UsagePurpose as aI, askInputSchema as aJ, askToolDefinition as aK, decodeStreamEvent as aL, encodeStreamEvent as aM, invokeWithTransientRetry as aN, isChatQueueStore as aO, isTransientToolError as aP, isTypedQuestion as aQ, normalizeElicitationReply as aR, questionOptions as aS, queuedMessageView as aT, readElicitationInput as aU, readElicitationQuestions as aV, releaseThreadRun as aW, renderElicitationAnswers as aX, resolveElicitation as aY, resolveToolTransientRetryNumbers as aZ, settleElicitation as a_, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as aa, ELICITATION_INPUT_TYPES as ab, type ElicitationInput as ac, type ElicitationInputType as ad, type ElicitationOption as ae, type ElicitationOutcome as af, type ElicitationQuestion as ag, type ElicitationReply as ah, type ElicitationResult as ai, type HistoryPolicyContext as aj, type HistorySelection as ak, type HistorySummary as al, type InvokeWithTransientRetryOptions as am, MAX_ASK_QUESTIONS as an, type MessageFeedbackValue as ao, type MessageRole as ap, type PromptContext as aq, type QueuePauseReason as ar, type QueuedMessageView as as, type QuotaView as at, type RecordRunEndInput as au, type ThreadTurnPage as av, type ThreadTurnQuery as aw, type ThreadTurnReader as ax, type ToolCallApprovalStatus as ay, type ToolCatalogEntry as az, type ToolPresentation as b, validateElicitationValue as b0, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AiToolCtx as g, type AgentStreamEvent as h, type AgentRunInput as i, type MessageAttachment as j, type ToolKind as k, type ToolCallStatus as l, type ToolCallApproval as m, type HistoryPolicy as n, type AgentDefinition as o, type AgentDelegation as p, type AgentStore as q, type ToolDescribeScope as r, type PromptBuilder as s, type PromptContributor as t, type ToolTransientRetrySetting as u, type AgentIntake as v, type Decision as w, type ToolStepEnvelope as x, type CreateThreadInput as y, type ThreadSummary as z };
+export { type AgentApprovalSettlement as $, type AgentStreamEvent as A, type QueuedMessage as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type QueuedMessagePatch as F, type QueuePause as G, type HumanReply as H, type AppendMessageInput as I, type ToolResult as J, type MessageFeedback as K, type LlmStepEnvelope as L, type ModelMessage as M, type RecordToolCallInput as N, type ToolCallOutcome as O, type PageContext as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type UpdateToolCallInput as V, type RecordUsageInput as W, ALL_AGENTS as X, ASK_TOOL_DESCRIPTION as Y, ASK_TOOL_NAME as Z, type AgentApprovalRequest as _, type Actor as a, settleDanglingToolCalls as a$, type AgentAttachmentConfig as a0, type AgentCatalogEntry as a1, type AgentClientConfig as a2, type AgentHistoryWindow as a3, type AgentStreamErrorCode as a4, type AskToolInput as a5, type ChatQueueState as a6, DEFAULT_INTAKE_PREAMBLE as a7, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as a8, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as a9, type ToolConfirmation as aA, type ToolPresentationTone as aB, type ToolResultField as aC, type ToolResultView as aD, type ToolStepCtx as aE, type ToolTransientRetryNumbers as aF, type ToolTransientRetryOptions as aG, UNFINISHED_TOOL_CALL as aH, type UsagePurpose as aI, askInputSchema as aJ, askToolDefinition as aK, danglingToolCallIds as aL, decodeStreamEvent as aM, encodeStreamEvent as aN, invokeWithTransientRetry as aO, isChatQueueStore as aP, isTransientToolError as aQ, isTypedQuestion as aR, normalizeElicitationReply as aS, questionOptions as aT, queuedMessageView as aU, readElicitationInput as aV, readElicitationQuestions as aW, releaseThreadRun as aX, renderElicitationAnswers as aY, resolveElicitation as aZ, resolveToolTransientRetryNumbers as a_, ELICITATION_INPUT_TYPES as aa, type ElicitationInput as ab, type ElicitationInputType as ac, type ElicitationOption as ad, type ElicitationOutcome as ae, type ElicitationQuestion as af, type ElicitationReply as ag, type ElicitationResult as ah, type HistoryPolicyContext as ai, type HistorySelection as aj, type HistorySummary as ak, type InvokeWithTransientRetryOptions as al, MAX_ASK_QUESTIONS as am, type MessageFeedbackValue as an, type MessageRole as ao, type PromptContext as ap, type QueuePauseReason as aq, type QueuedMessageView as ar, type QuotaView as as, RUN_ENDED_BEFORE_TOOL_CALL as at, type RecordRunEndInput as au, type ThreadTurnPage as av, type ThreadTurnQuery as aw, type ThreadTurnReader as ax, type ToolCallApprovalStatus as ay, type ToolCatalogEntry as az, type ToolPresentation as b, settleElicitation as b0, validateElicitationAnswer as b1, validateElicitationValue as b2, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AgentRunInput as g, type MessageAttachment as h, type ToolKind as i, type ToolCallStatus as j, type ToolCallApproval as k, type HistoryPolicy as l, type AgentDefinition as m, type AgentStore as n, type AgentDelegation as o, type PromptBuilder as p, type PromptContributor as q, type ToolTransientRetrySetting as r, type AgentIntake as s, type Decision as t, type ToolStepEnvelope as u, type CreateThreadInput as v, type ThreadSummary as w, type ThreadDetail as x, type ToolCallApprovalState as y, type EnqueueMessageInput as z };