@orkestrel/agent 0.0.20 → 0.0.22

package/dist/src/core/index.d.cts

@@ -1,29 +1,42 @@
-import { BudgetInterface } from '@orkestrel/budget';
-import { ControllerInterface } from '@orkestrel/workflow';
-import { DriverInterface } from '@orkestrel/database';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FileInterface } from '@orkestrel/workspace';
+import { ArrayShape } from '@orkestrel/contract';
+import { BooleanShape } from '@orkestrel/contract';
+import type { BudgetInterface } from '@orkestrel/budget';
+import { ContractInterface } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
+import type { ControllerInterface } from '@orkestrel/workflow';
+import type { DriverInterface } from '@orkestrel/database';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { FileInterface } from '@orkestrel/workspace';
+import { JSONShape } from '@orkestrel/contract';
 import { JSONValue } from '@orkestrel/contract';
-import { QueueContext } from '@orkestrel/queue';
-import { QueueInterface } from '@orkestrel/queue';
-import { QueueStoreInterface } from '@orkestrel/queue';
-import { RunnerInterface } from '@orkestrel/workflow';
-import { SchedulerInterface } from '@orkestrel/workflow';
-import { TableInterface } from '@orkestrel/database';
-import { TokenUsage } from '@orkestrel/budget';
-import { ToolCall } from '@orkestrel/tool';
-import { ToolDefinition } from '@orkestrel/tool';
-import { ToolInterface } from '@orkestrel/tool';
-import { ToolManagerInterface } from '@orkestrel/tool';
-import { ToolResult } from '@orkestrel/tool';
-import { WorkspaceManagerInterface } from '@orkestrel/workspace';
+import { LiteralShape } from '@orkestrel/contract';
+import { NumberShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { OptionalShape } from '@orkestrel/contract';
+import type { QueueContext } from '@orkestrel/queue';
+import type { QueueInterface } from '@orkestrel/queue';
+import type { QueueStoreInterface } from '@orkestrel/queue';
+import type { RunnerInterface } from '@orkestrel/workflow';
+import type { SchedulerInterface } from '@orkestrel/workflow';
+import { StringShape } from '@orkestrel/contract';
+import type { TableInterface } from '@orkestrel/database';
+import type { TokenUsage } from '@orkestrel/budget';
+import type { ToolCall } from '@orkestrel/tool';
+import type { ToolDefinition } from '@orkestrel/tool';
+import type { ToolInterface } from '@orkestrel/tool';
+import type { ToolManagerInterface } from '@orkestrel/tool';
+import type { ToolResult } from '@orkestrel/tool';
+import { UnionShape } from '@orkestrel/contract';
+import type { WorkspaceManagerInterface } from '@orkestrel/workspace';
 
 /**
  * Composes a {@link ProviderInterface}, an {@link AgentContext}, and a
- * {@link ToolManagerInterface} into a bounded context → provider → tools → repeat
- * turn, exposed as both a one-shot `generate` and a live `stream`.
+ * {@link ToolManagerInterface} into a bounded context → provider → tools → repeat turn, exposed
+ * as both a one-shot `generate` and a live `stream` that share one private run — bounded by the
+ * run `signal`, the `timeout`, and the `budget` folded through `AbortSignal.any`, paced by
+ * `scheduler`, with tool iteration capped at `limit`.
  *
  * @remarks
  * - **One loop, two faces.** A single private async generator (`#run`) drives the
@@ -40,15 +53,15 @@ import { WorkspaceManagerInterface } from '@orkestrel/workspace';
  *   assistant message and stop.
  * - **Bounded.** Each run arms one cancel through `createAbort({ signal: AbortSignal.any([
  *   …]) })` folding the external `signal`, the `timeout` deadline, and the `budget`
- *   signal; `abort()` fires it. Any trip stops the loop and commits a PARTIAL result
- *   (the `result` promise RESOLVES, never rejects, on a cancel) — only a genuine
+ *   signal; `abort()` fires it. Any trip stops the loop and commits a partial result
+ *   (the `result` promise resolves, never rejects, on a cancel) — only a genuine
  *   provider / tool error rejects.
  * - **Paced + capped.** The `scheduler` (when given) `yield`s between turns; tool
  *   iteration is capped at `limit`.
- * - **Two observation surfaces.** The PULL {@link AgentChunk} stream carries per-token
- *   deltas (+ usage/tool chunks); the PUSH {@link emitter} ({@link AgentEventMap}) carries
+ * - **Two observation surfaces.** The pull {@link AgentChunk} stream carries per-token
+ *   deltas (+ usage/tool chunks); the push {@link emitter} ({@link AgentEventMap}) carries
  *   lifecycle + usage/tool/deny moments for fire-and-forget observers. Every event is
- *   emitted directly, AFTER the relevant state transition / settle; the emitter isolates a
+ *   emitted directly, after the relevant state transition / settle; the emitter isolates a
  *   listener throw and routes it to its `error` handler (the `error` option), so a buggy
  *   observer can never escape into / reorder / corrupt the settle-once loop — observation is
  *   purely a side-channel.
@@ -74,15 +87,15 @@ export declare class Agent implements AgentInterface {
 
 /**
  * Represents a streamed step of an agent turn — the union the loop yields as it runs, discriminated
- * by the `category` of step it carries.
+ * by the `category` of step it carries, and the pull surface beside the push {@link AgentEventMap}.
  *
  * @remarks
  * - `token` — a content delta the provider streamed (the `'content'`
  *   {@link ProviderDelta}s a {@link ProviderInterface}'s `stream` yields), re-surfaced for
- *   live rendering of the assistant ANSWER.
+ *   live rendering of the assistant answer.
  * - `think` — a reasoning delta the provider streamed (the `'thinking'`
  *   {@link ProviderDelta}s, the daemon's native `message.thinking` channel), surfaced so a
- *   consumer can stream the model's reasoning LIVE into a collapsible; NEVER answer content
+ *   consumer can stream the model's reasoning live into a collapsible; never answer content
  *   (it is never fed into the accumulated `content`).
  * - `tool` — a {@link ToolCall} the loop dispatched paired with its {@link ToolResult},
  *   emitted once the tool ran (so a consumer sees what was called and what came back).
@@ -107,58 +120,59 @@ export declare type AgentChunk = {
 /**
  * Assembles a provider request from the richer turn context — the optional system prompt, the
  * observable context managers (instructions / workspaces), the
- * {@link ConversationManagerInterface} message source (whose active conversation IS `messages`),
- * the {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
- * {@link AgentContextInterface.apply}.
+ * {@link ConversationManagerInterface} message source whose active conversation is `messages`, the
+ * {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
+ * {@link AgentContextInterface.apply}. `build()` folds the scoped managers and the active
+ * workspace into one system block, then the conversation, and never reads `tools`.
  *
  * @remarks
  * - **Composition.** `system` is the optional system prompt; `instructions` / `tools` /
  *   `workspaces` / `conversations` are the registries passed in `options` (bring your own), or
- *   fresh empty ones when omitted (so `workspaces` is ALWAYS present); `messages` is the ACTIVE
- *   conversation's live tail (ALWAYS defined — see below). `scope` is the active filter —
+ *   fresh empty ones when omitted (so `workspaces` is always present); `messages` is the active
+ *   conversation's live tail (always defined — see the following item). `scope` is the active filter —
  *   `undefined` (the default) ⇒ no filtering; change it through `apply(scope)`. The structural
  *   `workspaces` / `conversations` registries are fixed at construction; switch their active
  *   members through their own `switch(id)` methods.
- * - **The message source — the conversation registry's ACTIVE conversation.** `conversations` is a
- *   {@link ConversationManagerInterface}; the context ENSURES it always has an active conversation
- *   (at construction it `add`s a default when the manager has none), so the DYNAMIC `messages`
- *   getter — `this.#conversations.active` — is ALWAYS defined. `messages` returns the active
- *   conversation ITSELF (it owns the live tail + the message verbs directly, satisfying
+ * - **The message source — the conversation registry's active conversation.** `conversations` is a
+ *   {@link ConversationManagerInterface}; the context ensures it always has an active conversation
+ *   (at construction it `add`s a default when the manager has none), so the dynamic `messages`
+ *   getter — `this.#conversations.active` — is always defined. `messages` returns the active
+ *   conversation itself (it owns the live tail + the message verbs directly, satisfying
  *   {@link MessageManagerInterface} structurally — the same reference, no duplication), and
  *   `build()` folds that conversation's `view()` (its per-section summaries + live tail) as the
- *   AUTHORITATIVE message inclusion — the scope does NOT filter the conversation (it owns inclusion
+ *   authoritative message inclusion — the scope does not filter the conversation (it owns inclusion
  *   through compaction; scope filters only instructions / tools / workspace files). Because `messages`
- *   is read dynamically, an agent SWITCHES the active
- *   conversation BETWEEN runs (`conversations.switch(id)`) to serve MANY threads (the real
+ *   is read dynamically, an agent switches the active
+ *   conversation between runs (`conversations.switch(id)`) to serve many threads (the real
  *   multi-conversation pattern); switch between runs, not during a run, and use separate agents
  *   for concurrent threads.
  * - **`build(format?)` — the scoped assembly + the format cascade.** It folds, in order,
- *   the system prompt then the scope-filtered instructions → the ACTIVE workspace's text files
+ *   the system prompt then the scope-filtered instructions → the active workspace's text files
  *   (each as a block: the section's resolved `open` text, each item's resolved rendering, then
- *   any resolved `close` text) into ONE leading `system` message (prepended only when at least
- *   one part exists), then appends the ACTIVE conversation's `view()` (the conversation owns
- *   message inclusion through compaction — the scope does NOT filter the conversation). Each
+ *   any resolved `close` text) into one leading `system` message (prepended only when at least
+ *   one part exists), then appends the active conversation's `view()` (the conversation owns
+ *   message inclusion through compaction — the scope does not filter the conversation). Each
  *   `open` / item / `close`
- *   resolves INDEPENDENTLY, MOST-SPECIFIC-FIRST — `build()`'s optional `format` (a provider's
- *   per-section default) is the PROVIDER level: `open` = manager-options-override > provider >
+ *   resolves independently, most-specific-first — `build()`'s optional `format` (a provider's
+ *   per-section default) is the provider level: `open` = manager-options-override > provider >
  *   built-in; per item = item-override > manager-options-override > provider > built-in; `close` =
- *   manager-options-override > provider (NO built-in ⇒ no closing line when unset) (see
- *   {@link AgentContextInterface.build}). Passing NO `format` (and with no overrides / no per-item
+ *   manager-options-override > provider (no built-in ⇒ no closing line when unset) (see
+ *   {@link AgentContextInterface.build}). Passing no `format` (and with no overrides / no per-item
  *   override) reproduces the built-in framing byte-for-byte (each section is its built-in header +
  *   items, no closing line). The active workspace's scoped-in image files' `base64` payload is attached to
- *   the LAST user message (a vision provider reads images off a user turn); when no user message
+ *   the last user message (a vision provider reads images off a user turn); when no user message
  *   exists the attachment is skipped. Built fresh each call (recomputed, never cached), so it
  *   always reflects the current managers / messages / scope / active workspace; it never mutates a
  *   manager or the stored messages.
- * - **The ACTIVE workspace, rendered BY CARRIER — the SOLE document/image context.**
+ * - **The active workspace, rendered by carrier — the sole document/image context.**
  *   `workspaces.active` (when set) has its {@link import('@orkestrel/workspace').FileInterface}s scope-filtered by `scope.files`,
- *   then split: TEXT files fold into a dedicated `## Workspace` system section (fenced reference
- *   blocks — placed right after the instructions section), and IMAGE files' `base64` payload attaches
- *   to the last user message. ACTIVE-ONLY — never the other registered workspaces; with no active
- *   workspace nothing renders for workspaces. `build()` OWNS this render (a `Workspace` /
+ *   then split: text files fold into a dedicated `## Workspace` system section (fenced reference
+ *   blocks — placed right after the instructions section), and image files' `base64` payload attaches
+ *   to the last user message. Active-only — never the other registered workspaces; with no active
+ *   workspace nothing renders for workspaces. `build()` owns this render (a `Workspace` /
  *   `WorkspaceManager` stays file-focused).
  * - **Tools are structural, not in the prompt.** The registry is advertised to the provider
- *   through `tools.definitions()` (scope-filtered by the loop), NEVER serialized into the
+ *   through `tools.definitions()` (scope-filtered by the loop), never serialized into the
  *   message array — so `build()`'s output carries no tool content, scoped or not.
  * - **Event-free context; observable managers.** The context itself owns no Emitter; the
  *   context managers each carry their own (the push observation surface).
@@ -194,12 +208,12 @@ export declare class AgentContext implements AgentContextInterface {
  * (`instructions` / `workspaces` / `conversations`), `messages` (the active
  * conversation's live tail, satisfying {@link MessageManagerInterface}), and the current `scope`
  * (the active {@link ScopeInterface} filter, or `undefined` for no filtering). `build()` folds the
- * scoped instructions into ONE leading `system` message (under the manager's `open`,
- * each item through its `render`) — PLUS the ACTIVE workspace's scope-filtered text files
- * (rendered as fenced reference blocks) — and appends the ACTIVE conversation's `view()`, attaching
- * the active workspace's scope-filtered image files' `base64` payload to the LAST user message. The
- * active workspace is the SOLE document/image context. Tools are advertised to the provider
- * STRUCTURALLY (through `tools.definitions()`, scope-filtered by the loop), NOT serialized into
+ * scoped instructions into one leading `system` message (under the manager's `open`,
+ * each item through its `render`) — plus the active workspace's scope-filtered text files
+ * (rendered as fenced reference blocks) — and appends the active conversation's `view()`, attaching
+ * the active workspace's scope-filtered image files' `base64` payload to the last user message. The
+ * active workspace is the sole document/image context. Tools are advertised to the provider
+ * structurally (through `tools.definitions()`, scope-filtered by the loop), not serialized into
  * the prompt, so they never appear in `build()`'s output. The context managers are observable
  * (their own `emitter`s); the context itself is event-free.
  */
@@ -207,32 +221,32 @@ export declare interface AgentContextInterface {
     readonly system: string | undefined;
     readonly instructions: InstructionManagerInterface;
     /**
-     * Holds the {@link WorkspaceManagerInterface} whose ACTIVE workspace `build()` renders by carrier —
+     * Holds the {@link WorkspaceManagerInterface} whose active workspace `build()` renders by carrier —
      * its text files folded into the system block (fenced reference blocks) and its image files'
-     * `base64` payload attached to the LAST user message. The active workspace is the SOLE
-     * document/image context. ALWAYS present (a fresh empty manager when none was supplied).
-     * `build()` reads its `active` (and the active workspace's `files()`) FRESH each call. With NO
+     * `base64` payload attached to the last user message. The active workspace is the sole
+     * document/image context. Always present (a fresh empty manager when none was supplied).
+     * `build()` reads its `active` (and the active workspace's `files()`) fresh each call. With no
      * active workspace, nothing is rendered for workspaces. Active-only — never the other registered
      * workspaces.
      */
     readonly workspaces: WorkspaceManagerInterface;
     /**
-     * Holds the active conversation's LIVE tail — the agent's message source, ALWAYS defined (the
+     * Holds the active conversation's live tail — the agent's message source, always defined (the
      * {@link conversations} registry always has an active conversation; a default is added at
-     * construction). It IS the active {@link ConversationInterface} itself (which satisfies
+     * construction). It is the active {@link ConversationInterface} itself (which satisfies
      * {@link MessageManagerInterface} structurally), so appends through `messages` route to the
      * active conversation's tail and `build()` folds its `view()`. Computed dynamically (it follows
-     * `conversations.switch(id)`), the SAME reference the active conversation exposes — no
+     * `conversations.switch(id)`), the same reference the active conversation exposes — no
      * duplication.
      */
     readonly messages: MessageManagerInterface;
     /**
-     * Holds the {@link ConversationManagerInterface} the message source flows from — `messages` IS its
-     * ACTIVE conversation's live tail and `build()` folds that conversation's `view()`. ALWAYS holds
+     * Holds the {@link ConversationManagerInterface} the message source flows from — `messages` is its
+     * active conversation's live tail and `build()` folds that conversation's `view()`. Always holds
      * an active conversation (a default is added at construction when none was supplied), so
      * `messages` is always defined. Switch the active conversation through
-     * `conversations.switch(id)` — so one agent can serve MANY conversations (set the active one per
-     * request). Switch BETWEEN runs, not during one; for CONCURRENT threads use separate agents.
+     * `conversations.switch(id)` — so one agent can serve many conversations (set the active one per
+     * request). Switch between runs, not during one; for concurrent threads use separate agents.
      */
     readonly conversations: ConversationManagerInterface;
     /**
@@ -243,7 +257,8 @@ export declare interface AgentContextInterface {
     /** Holds the active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
     readonly scope: ScopeInterface | undefined;
     /**
-     * Applies the active per-turn scope filter. Passing `undefined` removes filtering.
+     * Applies the given scope as the active per-turn filter; passing `undefined` explicitly
+     * removes filtering.
      *
      * @param scope - The scope to apply, or `undefined` to remove the active filter
      *
@@ -255,51 +270,57 @@ export declare interface AgentContextInterface {
      */
     apply(scope: ScopeInterface | undefined): void;
     /**
-     * Builds the provider input for the next turn: a leading `system` message folding the prompt
-     * + the scoped instructions + the ACTIVE workspace's scoped-in TEXT files (rendered as
-     * fenced reference blocks), then the ACTIVE conversation's `view()` (with the active workspace's
-     * scoped-in IMAGE files' `base64` payload attached to the last user message). Tools are advertised
-     * structurally, not in the prompt. Built fresh on each call.
+     * Builds the provider input for the next turn: a leading `system` message folding the
+     * prompt, the scope-filtered instructions (each section's header and each item's rendering
+     * resolved through the format cascade), and the active workspace's scope-filtered
+     * (`scope.files`) text files as fenced reference blocks in a `## Workspace` section, then
+     * the active conversation's `view()`, with the active workspace's image files' `base64`
+     * payload attached to the last user message. Takes an optional `format` — typically
+     * `provider.format`, the provider level of the cascade — and omitting it with no overrides
+     * set renders each section on its manager's built-in framing. The `system` message is
+     * prepended only when some part of it exists, the workspace render covers the active
+     * workspace alone, tools are advertised structurally rather than in the prompt, and the
+     * input is built fresh on each call.
      *
      * @remarks
-     * **The active workspace (rendered by carrier) — the SOLE document/image context.** When
+     * **The active workspace (rendered by carrier) — the sole document/image context.** When
      * `workspaces.active` is set, its
      * {@link import('@orkestrel/workspace').WorkspaceInterface.files} are filtered by
      * `scope.files` (a three-way allow-list; `undefined` ⇒ all active files), then split by
-     * carrier: TEXT files ({@link import('@orkestrel/workspace').isText}) render into a dedicated
+     * carrier: text files ({@link import('@orkestrel/workspace').isText}) render into a dedicated
      * `## Workspace` section in the system block — each a fenced
      * `` File: <path>\n```<language>\n<text>\n``` `` block — placed immediately after the instructions
      * section; binary files whose MIME starts with `image/` have their `base64` payload
-     * attached to the LAST user message (a vision provider reads images off a user turn).
-     * ACTIVE-ONLY — never the other registered workspaces; with NO active workspace nothing is
+     * attached to the last user message (a vision provider reads images off a user turn).
+     * Active-only — never the other registered workspaces; with no active workspace nothing is
      * rendered for workspaces.
      *
      * **The format cascade.** Each manager section frames as `[open, ...items.map(render), close]`
      * (empty / absent slots dropped, the survivors `\n\n`-joined). The `open` (the section's
      * leading text), each item's `render`, and the `close` (the section's trailing text)
-     * resolve INDEPENDENTLY, MOST-SPECIFIC-FIRST, from a {@link ContextSectionFormat} at each
+     * resolve independently, most-specific-first, from a {@link ContextSectionFormat} at each
      * level — an item override, a manager-options override, the provider `format` default,
      * and the manager's built-in. For the `instructions` section kind `K`, manager
      * `M`, and the supplied `format` `F`:
      * - **open** = `M.format?.open ?? F?.[K]?.open ?? M.open` — that is,
      *   **manager-options override > provider default > built-in** (the leading text has no
-     *   per-item level). The manager ENCAPSULATES the `[options-override → built-in]` half:
+     *   per-item level). The manager encapsulates the `[options-override → built-in]` half:
      *   `M.open` already returns the options override's `open` when one is set, else
-     *   the built-in header — so `build()` only layers the provider default BETWEEN them.
+     *   the built-in header — so `build()` only layers the provider default between them.
      * - **item** `I` = `I.override ?? M.format?.render?.(I) ?? F?.[K]?.render?.(I) ?? M.render(I)`
      *   — that is, **item override > manager-options override > provider default > built-in**.
      *   Again `M.render(I)` already returns the options override when set, else the
-     *   built-in, so `build()` layers the per-item `I.override` ON TOP and the provider
-     *   default BETWEEN.
+     *   built-in, so `build()` layers the per-item `I.override` on top and the provider
+     *   default between.
      * - **close** = `M.format?.close ?? F?.[K]?.close` — that is, **manager-options
-     *   override > provider default**, with NO built-in floor (the trailing text has no
+     *   override > provider default**, with no built-in floor (the trailing text has no
      *   per-item level): unset at both levels ⇒ `undefined` ⇒ no closing line. Paired with
-     *   `open`, it lets a level WRAP the group (`open: '<instructions>'` … `close: '</instructions>'`).
+     *   `open`, it lets a level wrap the group (`open: '<instructions>'` … `close: '</instructions>'`).
      *
-     * Passing NO `format` (the default) leaves the provider-default level empty, so the
-     * output is BYTE-FOR-BYTE the managers' built-in framing — every section is its
+     * Passing no `format` (the default) leaves the provider-default level empty, so the
+     * output is byte-for-byte the managers' built-in framing — every section is its
      * built-in header + items, with no closing line (the regression contract). Scope
-     * filtering runs BEFORE formatting (unchanged); the workspace image-data attachment to the
+     * filtering runs before formatting (unchanged); the workspace image-data attachment to the
      * last user message is unchanged.
      *
      * @param format - The provider's optional {@link ContextFormat} default
@@ -312,7 +333,10 @@ export declare interface AgentContextInterface {
 }
 
 /**
- * Configures `createAgentContext` — the richer context's configuration.
+ * Configures `createAgentContext` — the optional system prompt plus the pre-built managers to
+ * reuse: an `instructions` registry, a `workspaces` registry (the only document channel), a
+ * `conversations` registry (the message source), a `tools` registry (the loop's advertise and
+ * dispatch surface), and an initial `scope`.
  *
  * @remarks
  * `system` is the optional system prompt prepended to the turn's input. `instructions` /
@@ -322,10 +346,10 @@ export declare interface AgentContextInterface {
  * initial active filter applied at `build()` time (and at the loop's tool-advertise step); it
  * defaults to `undefined` — no filtering — and can be changed through the context's `apply`
  * method afterwards. `conversations` is the structural {@link ConversationManagerInterface} the
- * context's message source flows from: `messages` IS the manager's ACTIVE conversation's live tail
+ * context's message source flows from: `messages` is the manager's active conversation's live tail
  * and `build()` folds that conversation's `view()` (section summaries + live). When omitted, a fresh
  * {@link ConversationManagerInterface} is created and a default conversation is added (so
- * `messages` is ALWAYS defined). All default to a context with no system prompt, empty registries,
+ * `messages` is always defined). All default to a context with no system prompt, empty registries,
  * no scope, and a fresh conversation registry holding one default conversation.
  */
 export declare interface AgentContextOptions {
@@ -339,21 +363,21 @@ export declare interface AgentContextOptions {
     readonly instructions?: InstructionManagerInterface;
     /**
      * Reuses a pre-built {@link WorkspaceManagerInterface}; a fresh empty one is created when
-     * omitted (so `context.workspaces` is ALWAYS present). `build()` renders the ACTIVE workspace's
+     * omitted (so `context.workspaces` is always present). `build()` renders the active workspace's
      * files by carrier — text files into the system block (fenced), image files attached to the last
      * user message. The registry is structural; change its active workspace through
-     * `workspaces.switch(id)`. The active workspace is the SOLE document/image context.
+     * `workspaces.switch(id)`. The active workspace is the sole document/image context.
      */
     readonly workspaces?: WorkspaceManagerInterface;
     /** Sets the initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
     readonly scope?: ScopeInterface;
     /**
      * Reuses a pre-built {@link ConversationManagerInterface} as the message source; a fresh
-     * empty one is created when omitted. The context ENSURES an active conversation at construction
-     * (it `add`s a default when the manager has none), so `messages` — the manager's ACTIVE
-     * conversation's LIVE tail — is ALWAYS defined. `build()` folds the active conversation's
-     * `view()` (the per-section summaries + the live tail) as its AUTHORITATIVE message inclusion —
-     * the scope does NOT filter the conversation (it owns inclusion through compaction; scope filters
+     * empty one is created when omitted. The context ensures an active conversation at construction
+     * (it `add`s a default when the manager has none), so `messages` — the manager's active
+     * conversation's live tail — is always defined. `build()` folds the active conversation's
+     * `view()` (the per-section summaries + the live tail) as its authoritative message inclusion —
+     * the scope does not filter the conversation (it owns inclusion through compaction; scope filters
      * only instructions / tools / workspace files). The registry is structural; change its active
      * conversation through the manager's `switch(id)`.
      */
@@ -361,13 +385,16 @@ export declare interface AgentContextOptions {
 }
 
 /**
- * Reports a concurrent run that would corrupt SHARED per-agent accounting, or a rehydration
+ * Reports a concurrent run that would corrupt shared per-agent accounting, or a rehydration
  * name absent from its registry pool — thrown synchronously by an {@link AgentInterface}'s
- * `stream()` and by an {@link AgentRegistryInterface}'s accessors, carrying a machine-readable
- * `code`.
+ * `stream()` (and so by `generate()`, which calls it) and by an
+ * {@link AgentRegistryInterface}'s accessors, carrying the machine-readable `code`
+ * `'CONCURRENCY' | 'REGISTRY'`. Synchronous means a fire-and-forget
+ * `agent.generate().catch(…)` never catches it: `await` the call inside `try`/`catch`, or wrap
+ * the call expression itself.
  *
  * @remarks
- * `'CONCURRENCY'` reports a run already in flight on the same agent, PLUS a construction-level
+ * `'CONCURRENCY'` reports a run already in flight on the same agent, plus a construction-level
  * `window` (a shared context budget) or a construction-level `budget` with no per-run override
  * (a shared cost budget) — a second concurrent `stream()` would race its charges against the
  * same shared instance, corrupting the accounting. Use separate agents, or per-run `budget`
@@ -382,26 +409,26 @@ export declare class AgentError extends Error {
 }
 
 /**
- * Maps the push observation surface of an {@link AgentInterface} — the
- * lifecycle + usage/tool moments a fire-and-forget observer (logging, metrics,
- * tracing) subscribes to, ALONGSIDE the pull {@link AgentChunk} stream.
+ * Maps the push observation surface of an {@link AgentInterface} — the lifecycle, usage, and tool
+ * moments a fire-and-forget observer (logging, metrics, tracing) subscribes to, beside the pull
+ * {@link AgentChunk} stream.
  *
  * @remarks
- * Push vs. pull: the Emitter carries the loop's LIFECYCLE moments (a run begins /
+ * Push vs. pull: the Emitter carries the loop's lifecycle moments (a run begins /
  * each turn / a settle / a cancel) plus usage and dispatched-tool events — the things
  * the chunk stream can't express (a `deny` never reaches the stream) or that a
- * fire-and-forget observer wants without draining the stream. PER-TOKEN deltas stay
- * EXCLUSIVELY the {@link AgentChunk} stream's job (the pull surface) — there is
- * deliberately NO `token` event here. Subscribe through `agent.emitter.on(...)`.
+ * fire-and-forget observer wants without draining the stream. Per-token deltas stay
+ * exclusively the {@link AgentChunk} stream's job (the pull surface) — there is
+ * deliberately no `token` event here. Subscribe through `agent.emitter.on(...)`.
  *
  * Observation is side-effect-free on the loop: listener isolation is the emitter's
- * — every event is emitted directly and a listener throw is routed to the emitter's OWN
+ * — every event is emitted directly and a listener throw is routed to the emitter's own
  * `error` handler (the `error` option), never onto this domain map and never into the
  * settle-once / wake-park engine — so a buggy observer can never reorder, throw into, or
  * corrupt the run.
  *
- * A cancelled run emits `abort` (the cancel signal) AND then `finish` (the settled
- * PARTIAL result) — so an observer sees both that the run was cancelled and the partial
+ * A cancelled run emits `abort` (the cancel signal) and then `finish` (the settled
+ * partial result) — so an observer sees both that the run was cancelled and the partial
  * outcome it committed; a genuine error emits `error` instead of `finish`.
  *
  * Declared as a `type` alias (not `interface extends EventMap` — `EventMap` is a
@@ -418,9 +445,9 @@ export declare type AgentEventMap = {
     readonly tool: readonly [call: ToolCall, result: ToolResult];
     /** Reports a turn's {@link TokenUsage} — emitted after a usage-bearing provider call. */
     readonly usage: readonly [usage: TokenUsage];
-    /** Reports a call the authority DENIED — the call + the optional reason (NOT in the chunk stream). */
+    /** Reports a call the authority denied — the call + the optional reason (not in the chunk stream). */
     readonly deny: readonly [call: ToolCall, reason: string | undefined];
-    /** Reports the run settled successfully (a natural finish OR a cancel's partial) — the {@link AgentResult}. */
+    /** Reports the run settled successfully (a natural finish or a cancel's partial) — the {@link AgentResult}. */
     readonly finish: readonly [result: AgentResult];
     /** Reports the run settled with a genuine (non-cancel) error — the thrown value (always `unknown`). */
     readonly error: readonly [error: unknown];
@@ -429,20 +456,20 @@ export declare type AgentEventMap = {
     /**
      * Reports the loop exhausting its `limit` while still holding unresolved tool intent (the model
      * requested tools on the very last allowed turn) — the turn count reached. Distinct from
-     * `abort`: exhaustion is NOT a cancel (no external signal / timeout / budget tripped), so
-     * this fires INSTEAD of `abort`, still followed by `finish` carrying the partial result.
+     * `abort`: exhaustion is not a cancel (no external signal / timeout / budget tripped), so
+     * this fires instead of `abort`, still followed by `finish` carrying the partial result.
      */
     readonly exhaust: readonly [turns: number];
     /**
-     * Reports AUTOMATIC compaction's summarizer THROWING — a NON-FATAL warn channel (the run continues; see
+     * Reports automatic compaction's summarizer throwing — a non-fatal warn channel (the run continues; see
      * {@link AgentOptions.window}). When the loop's between-turns / pre-first-turn auto-compaction
-     * (`conversation.compact()`) rejects, the run does NOT crash: the loop skips compaction that
+     * (`conversation.compact()`) rejects, the run does not crash: the loop skips compaction that
      * turn and surfaces the caught error here so the failure is observable, never silently lost.
-     * The run still SETTLES through the other events — `finish` for the lenient default, and
+     * The run still settles through the other events — `finish` for the lenient default, and
      * `error` when {@link AgentOptions.strict} rethrows the same caught value — so `fault` reports
-     * the best-effort optimization that failed and never the run's own outcome. A MANUAL
-     * `conversation.compact()` still propagates its own error; only the agent's AUTO path is
-     * resilient. A DOMAIN event (the emitter isolates a listener throw separately, routing it to
+     * the best-effort optimization that failed and never the run's own outcome. A manual
+     * `conversation.compact()` still propagates its own error; only the agent's auto path is
+     * resilient. A domain event (the emitter isolates a listener throw separately, routing it to
      * its `error` handler).
      */
     readonly fault: readonly [error: unknown];
@@ -453,7 +480,7 @@ export declare type AgentEventMap = {
  * {@link ToolManagerInterface} into a bounded context → provider → tools → repeat turn.
  *
  * @remarks
- * - **One loop, two faces.** `generate` and `stream` share ONE private run, so they
+ * - **One loop, two faces.** `generate` and `stream` share one private run, so they
  *   can never diverge: `generate` drains the same stream `stream` exposes, then
  *   resolves its settled {@link AgentResult}.
  * - **Bounded.** Each turn arms a single cancel folded from the external `signal`, the
@@ -461,11 +488,11 @@ export declare type AgentEventMap = {
  *   or `abort()` — stops the loop and settles the result `partial: true`.
  * - **Paced + capped.** The `scheduler` (when given) yields between turns; tool
  *   iteration is capped at `limit` so the loop always terminates.
- * - **Two observation surfaces.** PULL: the {@link AgentChunk} stream (`stream().events`)
- *   carries per-token answer deltas, per-think reasoning deltas, and usage/tool chunks for a live consumer. PUSH: the
+ * - **Two observation surfaces.** Pull: the {@link AgentChunk} stream (`stream().events`)
+ *   carries per-token answer deltas, per-think reasoning deltas, and usage/tool chunks for a live consumer. Push: the
  *   {@link emitter} ({@link AgentEventMap}) carries lifecycle + usage/tool/deny moments
  *   for fire-and-forget observers — the emitter isolates a listener throw and routes it to
- *   its `error` handler (the `error` option), so a buggy observer can NEVER corrupt the
+ *   its `error` handler (the `error` option), so a buggy observer can never corrupt the
  *   loop. Per-token / per-thinking deltas are the stream's job exclusively; there is no
  *   `token` or `think` event.
  * - **Per-run overrides.** Both faces accept an optional {@link AgentRunOptions} bag whose
@@ -477,14 +504,14 @@ export declare interface AgentInterface {
     readonly status: AgentStatus;
     readonly context: AgentContextInterface;
     /**
-     * Runs the turn to completion, discarding the live chunks — drains the shared
-     * stream and resolves the settled outcome.
+     * Runs the turn to completion, discarding the live chunks — drains the shared stream and
+     * resolves the settled {@link AgentResult} (`partial: true` when cancelled).
      *
      * @remarks
      * A concurrent run on a shared accounting agent throws an
      * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) — and it throws
-     * SYNCHRONOUSLY, before any `Promise` is returned. A fire-and-forget
-     * `agent.generate().catch(...)` therefore will NOT catch it (the throw happens on the call
+     * synchronously, before any `Promise` is returned. A fire-and-forget
+     * `agent.generate().catch(...)` therefore will not catch it (the throw happens on the call
      * itself, ahead of the `.catch` ever attaching) — `await` the call (inside a `try`/`catch`)
      * or wrap the call expression itself in `try`/`catch`.
      *
@@ -495,11 +522,12 @@ export declare interface AgentInterface {
     generate(options?: AgentRunOptions): Promise<AgentResult>;
     /**
      * Runs the turn as a live stream — iterate `events` for {@link AgentChunk}s and
-     * `await result` for the settled outcome.
+     * `await result` for the settled outcome; `result` resolves partial on a cancel and rejects
+     * on a genuine error.
      *
      * @remarks
      * Like `generate()`, a concurrent run on a shared accounting agent throws an
-     * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) SYNCHRONOUSLY — before the
+     * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) synchronously — before the
      * {@link AgentStreamInterface} handle is even returned, so it cannot be caught by chaining
      * off the (never-produced) handle; wrap the call itself in `try`/`catch`.
      *
@@ -520,13 +548,13 @@ export declare interface AgentInterface {
 /**
  * Reports an {@link AgentInterface} run that ended {@link AgentResult.partial} under a
  * `partial` policy of `false` (the default) — thrown by an agent-job handler (a
- * `createAgentQueue` / `createAgentRunner` job), carrying the partial
- * {@link AgentResult} so the failure stays inspectable.
+ * `createAgentQueue` / `createAgentRunner` job), carrying the partial {@link AgentResult} so
+ * the failure stays inspectable, and the machine-readable `code` `'PARTIAL'`.
  *
  * @remarks
  * A partial result means the agent was cancelled (an external `signal` abort, a queue /
  * runner abort threaded in, a `timeout` deadline, or an exhausted token `budget`) rather
- * than finishing naturally. For a durable JOB that is a failure by default: throwing this
+ * than finishing naturally. For a durable job that is a failure by default: throwing this
  * lets the Queue's retries re-run the job and a Runner's fail-fast abort its siblings.
  * Set `partial: true` (see `AgentQueueOptions` / `AgentRunnerOptions`) to treat a
  * partial as success instead, in which case this is never thrown. Narrow a caught value
@@ -543,11 +571,11 @@ export declare class AgentJobError extends Error {
 }
 
 /**
- * Represents a JSON-serializable agent job — the descriptor a durable queue / runner runs. Its
- * non-serializable pieces (the provider, tools, authority, scheduler) are referenced by
- * NAME and resolved to live objects through an {@link AgentRegistryInterface} at handler
- * time; its data fields (the seed `messages`, `system`, `limit`, `timeout`, and a token
- * `budget` ceiling) carry directly.
+ * Represents a JSON-serializable agent job — the descriptor a durable queue or runner runs. Its
+ * non-serializable pieces (the provider, tools, authority, scheduler) are referenced by name and
+ * resolved to live objects through an {@link AgentRegistryInterface} at handler time, while its
+ * data fields (the seed `messages`, `system`, `limit`, `timeout`, and a token `budget` ceiling)
+ * carry directly.
  *
  * @remarks
  * Because every field is JSON-serializable, a job survives a crash through the Queue's
@@ -581,7 +609,7 @@ export declare interface AgentJobInput {
     /**
      * Lists the sub-agent jobs this job fans out — each a nested {@link AgentJobInput} (so the whole
      * tree stays serializable). On a `createAgentRunner`, the handler `controller.spawn`s
-     * each child through the same bounded queue BEFORE running this (parent) job, so the
+     * each child through the same bounded queue before running this (parent) job, so the
      * children run as sibling sub-agents and their results join the run after the declared
      * jobs (in spawn order). Ignored by `createAgentQueue` (a queue has no fan-out).
      */
@@ -589,7 +617,11 @@ export declare interface AgentJobInput {
 }
 
 /**
- * Configures `createAgent` — bounds and pacing for the agent loop.
+ * Configures `createAgent` — the loop's bounds and pacing, the reserved `on` hooks, the
+ * construction-time context wiring (`instructions` / `workspaces` / `scope`), the `conversations`
+ * registry that is the message source, the context `window` budget that opts into automatic
+ * compaction of the active conversation, and the `strict` switch that aborts the run on an
+ * automatic-compaction summarizer failure instead of the lenient default.
  *
  * @remarks
  * - `system` — an optional system prompt prepended to the turn (seeds the context).
@@ -609,16 +641,16 @@ export declare interface AgentJobInput {
  * - `signal` — an optional external `AbortSignal` whose abort cancels the turn (a
  *   partial result).
  * - `conversations` — an optional {@link ConversationManagerInterface} forwarded to the agent's
- *   context as the message source (so `context.messages` is its ACTIVE conversation's live tail);
+ *   context as the message source (so `context.messages` is its active conversation's live tail);
  *   omitted ⇒ a fresh registry holding one default conversation. Auto-compaction (`window`) folds
- *   the ACTIVE conversation when it is summarizable.
- * - `window` — an optional CONTEXT {@link BudgetInterface} for AUTOMATIC conversation
- *   compaction: when set, the loop measures the CURRENT FULL prompt against this budget each turn
+ *   the active conversation when it is summarizable.
+ * - `window` — an optional context {@link BudgetInterface} for automatic conversation
+ *   compaction: when set, the loop measures the current full prompt against this budget each turn
  *   (its `consumer` is a token estimator, its `max` the context window) and, when the prompt
- *   reaches the window AND the active conversation is summarizable, COMPACTS the active
+ *   reaches the window and the active conversation is summarizable, compacts the active
  *   conversation + continues on the rebuilt smaller view — compact-and-continue, distinct from
  *   `budget`'s hard abort. Omitted ⇒ no auto-compaction.
- * - `strict` — when `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run
+ * - `strict` — when `true`, a summarizer failure during automatic compaction aborts the run
  *   (rethrown after the `fault` event, propagating through `#run` to a genuine `error`
  *   settle) instead of skipping compaction and continuing over-window. Defaults to `false`
  *   (lenient — the prior, byte-for-byte behavior).
@@ -663,33 +695,153 @@ export declare interface AgentOptions {
      */
     readonly authority?: AuthorityInterface;
     /**
-     * Holds an optional {@link ConversationManagerInterface} that becomes the agent context's MESSAGE
-     * SOURCE — forwarded to the {@link AgentContextInterface} the agent builds, so
-     * `agent.context.messages` IS its ACTIVE conversation's live tail and `build()` folds that
+     * Holds an optional {@link ConversationManagerInterface} that becomes the agent context's message
+     * source — forwarded to the {@link AgentContextInterface} the agent builds, so
+     * `agent.context.messages` is its active conversation's live tail and `build()` folds that
      * conversation's `view()` (the per-section summaries + the live tail). Omitted ⇒ a fresh
-     * registry holding one default conversation. With `window` set, AUTOMATIC compaction folds the
-     * ACTIVE conversation between turns (when it is summarizable).
+     * registry holding one default conversation. With `window` set, automatic compaction folds the
+     * active conversation between turns (when it is summarizable).
      */
     readonly conversations?: ConversationManagerInterface;
     /**
-     * Holds an optional CONTEXT {@link BudgetInterface} for AUTOMATIC compaction. Its `consumer` is a
+     * Holds an optional context {@link BudgetInterface} for automatic compaction. Its `consumer` is a
      * token estimator (for example the exported {@link import('./helpers.js').estimateMessages}) and
-     * its `max` is the context window. When set, the loop measures the CURRENT FULL prompt (the
-     * next provider request) against this budget each turn; when that prompt reaches the window AND
+     * its `max` is the context window. When set, the loop measures the current full prompt (the
+     * next provider request) against this budget each turn; when that prompt reaches the window and
      * the active conversation is summarizable, it **compacts the active conversation + continues on
      * the rebuilt smaller view** (compact-and-continue) — the same consume-to-a-ceiling primitive
      * as the cost `budget`, but compaction is the ceiling action instead of abort. Omit to disable.
      */
     readonly window?: BudgetInterface<readonly Message[]>;
     /**
-     * If `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run — the
-     * `fault` event still fires, then the caught error is RETHROWN so the run settles
+     * If `true`, a summarizer failure during automatic compaction aborts the run — the
+     * `fault` event still fires, then the caught error is rethrown so the run settles
      * `error` instead of continuing over-window. Defaults to `false` (lenient — the run
      * continues over-window, byte-for-byte the prior behavior).
      */
     readonly strict?: boolean;
 }
 
+/**
+ * Implements bounded HTTP streaming and result assembly behind concrete wire seams.
+ *
+ * @remarks
+ * Every call owns its parser, splitter, deadline, and accumulation. Success bodies
+ * have no size limit. A qwen3 implicit-open reclassification corrects the final
+ * content while content deltas already yielded cannot be recalled. A subclass fills
+ * `name`, `frame`, `body`, `read`, and `finish`; the constructor takes the `split`
+ * and `strict` switches to control reasoning separation and settled-result requirements.
+ *
+ * @example Writing a provider for a new wire
+ * ```ts
+ * import type {
+ * 	ProviderIncrement,
+ * 	ProviderOptions,
+ * 	ProviderParserInterface,
+ * 	ProviderRequest,
+ * } from '@orkestrel/agent'
+ * import { AgentProvider } from '@orkestrel/agent'
+ *
+ * class TextFrame implements ProviderParserInterface<string> {
+ * 	parse(chunk: string): readonly string[] {
+ * 		return [chunk]
+ * 	}
+ * 	clear(): void {} // Raw text retains no framing state.
+ * }
+ *
+ * interface TextOptions extends ProviderOptions {
+ * 	readonly url: string
+ * }
+ *
+ * class TextProvider extends AgentProvider<string> {
+ * 	readonly name = 'text'
+ * 	constructor(options: TextOptions) {
+ * 		super({ ...options, path: '/generate' })
+ * 	}
+ * 	frame(): ProviderParserInterface<string> {
+ * 		return new TextFrame()
+ * 	}
+ * 	body(request: ProviderRequest): object {
+ * 		return { messages: request.messages }
+ * 	}
+ * 	read(record: string): ProviderIncrement {
+ * 		return { content: record, thinking: '', tools: [] }
+ * 	}
+ * 	finish(_parser: ProviderParserInterface<string>): readonly string[] {
+ * 		return [] // Raw text retains no records at end of input.
+ * 	}
+ * }
+ * ```
+ */
+export declare abstract class AgentProvider<TRecord = Readonly<Record<string, unknown>>> implements AgentProviderInterface<TRecord> {
+    #private;
+    constructor(input: AgentProviderInput);
+    /** Identifies the concrete backend. */
+    abstract readonly name: string;
+    /** Exposes the instance's minted UUID. */
+    get id(): string;
+    /** Exposes the context framing exactly as supplied. */
+    get format(): ContextFormat | undefined;
+    /** Creates fresh framing state for the call. */
+    abstract frame(): ProviderParserInterface<TRecord>;
+    /** Projects a domain request onto the concrete protocol's wire body. */
+    abstract body(request: ProviderRequest): object;
+    /** Decodes a framed record into a turn increment. */
+    abstract read(record: TRecord): ProviderIncrement;
+    /** Returns any records retained at end of input. */
+    abstract finish(parser: ProviderParserInterface<TRecord>): readonly TRecord[];
+    /**
+     * Generates a complete turn by draining the shared stream engine.
+     *
+     * @param messages - The conversation turns
+     * @param signal - The caller's cancellation bound
+     * @param tools - The advertised tool definitions
+     * @param options - The per-call generation configuration
+     * @returns The terminal stream result
+     */
+    generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
+    /**
+     * Streams decoded deltas and returns the authoritative or assembled turn result.
+     *
+     * @param messages - The conversation turns
+     * @param signal - The caller's cancellation bound
+     * @param tools - The advertised tool definitions
+     * @param options - The per-call generation configuration
+     * @returns Content and native thinking deltas followed by the settled result
+     * @throws ProviderAbortError Thrown when the combined cancellation bound fires
+     * @throws ProviderError Thrown for an HTTP or protocol failure
+     */
+    stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
+}
+
+/**
+ * Configures the HTTP destination and stream assembly of a provider base.
+ *
+ * @remarks
+ * `path` appends to `url`. If `split` is true, separates in-content reasoning;
+ * if false, preserves content verbatim. Default: true.
+ * If `strict` is true, requires a settled result record; if false, assembles at end of input.
+ * Default: false.
+ */
+export declare interface AgentProviderInput extends ProviderOptions {
+    readonly url: string;
+    readonly path?: string;
+    readonly split?: boolean;
+    readonly strict?: boolean;
+}
+
+/** Defines the wire-specific seams of the shared HTTP provider engine. */
+export declare interface AgentProviderInterface<TRecord = Readonly<Record<string, unknown>>> extends ProviderInterface {
+    /** Creates fresh framing state for a call. */
+    frame(): ProviderParserInterface<TRecord>;
+    /** Projects a request to the concrete protocol's serializable body. */
+    body(request: ProviderRequest): object;
+    /** Decodes a framed record into its contribution to the turn. */
+    read(record: TRecord): ProviderIncrement;
+    /** Returns records retained at end of input before the parser is cleared. */
+    finish(parser: ProviderParserInterface<TRecord>): readonly TRecord[];
+}
+
 /**
  * Configures `createAgentQueue` — the registry that rehydrates jobs, the partial-result
  * policy, and the substrate knobs threaded into the backing `createQueue`.
@@ -698,9 +850,9 @@ export declare interface AgentOptions {
  * - `registry` — the {@link AgentRegistryInterface} the handler rehydrates each job
  *   through (required).
  * - `partial` — the partial policy. A partial {@link AgentResult} (a job committed
- *   early from an abort / budget / timeout) is by DEFAULT a FAILURE: the handler THROWS
+ *   early from an abort / budget / timeout) is by default a failure: the handler throws
  *   an {@link import('./errors.js').AgentJobError}, so the Queue's retries (and a
- *   Runner's fail-fast) engage. Set `true` to treat a partial as SUCCESS instead — the
+ *   Runner's fail-fast) engage. Set `true` to treat a partial as success instead — the
  *   handler resolves the partial result rather than throwing.
  * - `concurrency` / `retries` / `timeout` / `store` — passed straight to the backing
  *   `QueueInterface` (see `QueueOptions`): bounded concurrency, the retry budget, the
@@ -708,7 +860,7 @@ export declare interface AgentOptions {
  */
 export declare interface AgentQueueOptions {
     readonly registry: AgentRegistryInterface;
-    /** If `true`, a partial `AgentResult` resolves as success; if `false` (the default), it THROWS and retries engage. */
+    /** If `true`, a partial `AgentResult` resolves as success; if `false` (the default), it throws and retries engage. */
     readonly partial?: boolean;
     readonly concurrency?: number;
     readonly retries?: number;
@@ -717,9 +869,10 @@ export declare interface AgentQueueOptions {
 }
 
 /**
- * Makes a durable, JSON-serializable {@link AgentJobInput} runnable — holds the named
- * pools of live, non-serializable pieces (providers, tools, authorities, schedulers) and
- * rehydrates a seeded, signal-wired {@link Agent} from a job's names + data.
+ * Makes a durable, JSON-serializable {@link AgentJobInput} runnable — holds the named pools of
+ * live, non-serializable pieces (providers, tools, authorities, schedulers), throws on a name
+ * absent from its pool, and `build`s a seeded, signal-wired {@link Agent} from a job's names and
+ * data.
  *
  * @remarks
  * - **Why it exists.** An `AgentJobInput` is serializable so it can survive a crash in a
@@ -728,9 +881,9 @@ export declare interface AgentQueueOptions {
  *   construct it once with the live pools, then a queue / runner handler calls `build`
  *   on each (possibly restored) job to get a ready agent.
  * - **Accessors throw on a miss.** `provider` / `tool` / `authority` / `scheduler` resolve a
- *   name against their pool and THROW an {@link AgentError} carrying `code: 'REGISTRY'` and
+ *   name against their pool and throw an {@link AgentError} carrying `code: 'REGISTRY'` and
  *   the message `unknown <category>: <name>` when it is absent — an unknown name in a
- *   rehydrated job is a programmer / config error that must fail LOUDLY at build time, never
+ *   rehydrated job is a programmer / config error that must fail loudly at build time, never
  *   silently resolve to `undefined` and run an agent missing a dependency.
  * - **`build` rehydrates.** Resolve the job's `provider`; assemble a fresh
  *   {@link ToolManager} from the `tools` names; rebuild the token `budget` from its
@@ -767,7 +920,7 @@ export declare class AgentRegistry implements AgentRegistryInterface {
  *
  * @remarks
  * - **Accessors throw on a miss.** `provider` / `tool` / `authority` / `scheduler` look one
- *   up by name and THROW an {@link AgentError} carrying `code: 'REGISTRY'` and the message
+ *   up by name and throw an {@link AgentError} carrying `code: 'REGISTRY'` and the message
  *   `unknown <category>: <name>` when the name is unregistered — an unknown name in a
  *   rehydrated job must fail loudly, never silently resolve to `undefined`, so a
  *   misconfigured job surfaces at once rather than running with a missing dependency.
@@ -780,7 +933,8 @@ export declare class AgentRegistry implements AgentRegistryInterface {
  */
 export declare interface AgentRegistryInterface {
     /**
-     * Resolves a registered {@link ProviderInterface} by name.
+     * Resolves a registered {@link ProviderInterface} by name — throws `unknown provider: <name>` when
+     * absent.
      *
      * @param name - The provider's registry key
      * @returns The live provider
@@ -788,7 +942,8 @@ export declare interface AgentRegistryInterface {
      */
     provider(name: string): ProviderInterface;
     /**
-     * Resolves a registered {@link ToolInterface} by name.
+     * Resolves a registered {@link ToolInterface} by name — throws `unknown tool: <name>` when
+     * absent.
      *
      * @param name - The tool's registry key
      * @returns The live tool
@@ -796,7 +951,8 @@ export declare interface AgentRegistryInterface {
      */
     tool(name: string): ToolInterface;
     /**
-     * Resolves a registered {@link AuthorityInterface} by name.
+     * Resolves a registered {@link AuthorityInterface} by name — throws `unknown authority: <name>` when
+     * absent.
      *
      * @param name - The authority's registry key
      * @returns The live authority
@@ -804,7 +960,8 @@ export declare interface AgentRegistryInterface {
      */
     authority(name: string): AuthorityInterface;
     /**
-     * Resolves a registered {@link SchedulerInterface} by name.
+     * Resolves a registered {@link SchedulerInterface} by name — throws `unknown scheduler: <name>` when
+     * absent.
      *
      * @param name - The scheduler's registry key
      * @returns The live scheduler
@@ -812,8 +969,9 @@ export declare interface AgentRegistryInterface {
      */
     scheduler(name: string): SchedulerInterface;
     /**
-     * Rehydrates a live, seeded {@link AgentInterface} from a serializable job — resolving
-     * its names, rebuilding its budget, seeding its conversation, and wiring `signal`.
+     * Rehydrates a live, seeded {@link AgentInterface} from a serializable {@link AgentJobInput}
+     * — resolving its names, rebuilding its token budget, seeding its conversation, and wiring
+     * `signal`; a name absent from its pool throws.
      *
      * @param input - The serializable {@link AgentJobInput} to rehydrate
      * @param signal - An optional cancel threaded into the agent (a queue / runner abort)
@@ -824,20 +982,21 @@ export declare interface AgentRegistryInterface {
 }
 
 /**
- * Configures `createAgentRegistry` — the named pools of live, non-serializable pieces
- * a {@link AgentJobInput}'s names resolve against.
+ * Configures `createAgentRegistry` — the named pools of live, non-serializable pieces an {@link
+ * AgentJobInput}'s names resolve against, plus the optional durable `store` every built agent's
+ * conversation manager shares.
  *
  * @remarks
  * `providers` is required (a job always names a provider); `tools` / `authorities` /
  * `schedulers` are optional pools, each an entity-keyed record mapping a registry
  * name to its live object. A name absent from its pool throws when resolved (see
  * {@link AgentRegistryInterface}). `store` is the durable {@link ConversationStoreInterface}
- * every agent this registry builds carries: each built agent gets its OWN store-backed
- * {@link ConversationManagerInterface} over THIS shared store — a fresh conversation id per
+ * every agent this registry builds carries: each built agent gets its own store-backed
+ * {@link ConversationManagerInterface} over this shared store — a fresh conversation id per
  * build (minted by the seeded `add`), so concurrent builds never collide, and the store
  * accumulates one snapshot per built agent that later calls `save`. Persistence
  * stays caller-triggered (`open` / `save`) — `build` never hydrates, so `build` stays
- * SYNCHRONOUS. Omitted ⇒ every built agent gets a registry-only manager, byte-identical
+ * synchronous. Omitted ⇒ every built agent gets a registry-only manager, byte-identical
  * to today.
  */
 export declare interface AgentRegistryOptions {
@@ -857,13 +1016,13 @@ export declare interface AgentRegistryOptions {
  * `partial` is `true` when the turn was committed early from a cancel — an external
  * `signal` abort, the turn's own `abort()`, a `timeout` deadline, or an exhausted
  * `budget` — in which case `content` is whatever had accumulated when the cancel
- * landed. `partial` is ALSO `true` when the loop exhausted its `limit` while still
+ * landed. `partial` is also `true` when the loop exhausted its `limit` while still
  * holding unresolved tool intent (the model requested tools on the very last allowed
  * turn) — a distinct, non-cancel cause covered by {@link RunOutcome.exhausted} (see
  * the `exhaust` {@link AgentEventMap} event). It is `false` for a turn that ran to a
  * natural finish (including a `limit: 0` run, which never enters the loop). `usage` is
  * present only when at least one provider call reported usage — an aborted run's `usage`
- * INCLUDES the cancelled turn's tokens when the provider reports partial usage on the
+ * includes the cancelled turn's tokens when the provider reports partial usage on the
  * abort (folded in exactly like a completed turn's); a provider that cannot observe
  * usage mid-stream (for example a daemon whose final counts never arrive before the cancel)
  * reports none for that turn, and none is fabricated. `thinking` is present
@@ -881,8 +1040,11 @@ export declare interface AgentResult {
 }
 
 /**
- * Projects an unknown value onto the canonical JSON representation of an
- * {@link AgentResult}.
+ * Projects an unknown value onto a fresh, exact `JSONValue` representation of an
+ * {@link AgentResult} — capturing each structural field once through a total boundary,
+ * accepting conforming accessors and inherited properties, preserving finite negative and
+ * fractional usage counts, dropping extras, and resolving `undefined` for a malformed field, a
+ * non-finite usage number, a throwing getter, or a hostile or revoked proxy.
  *
  * @remarks
  * This is a total hostile-boundary projection. Each structural field is captured once
@@ -912,7 +1074,7 @@ export declare function agentResultToJSON(value: unknown): JSONValue | undefined
  *
  * @remarks
  * Identical partial policy to {@link AgentQueueOptions} (`partial` — a partial
- * `AgentResult` THROWS by default so the run's fail-fast engages, `true` resolves it as
+ * `AgentResult` throws by default so the run's fail-fast engages, `true` resolves it as
  * success). `concurrency` / `retries` / `timeout` pass straight to the backing
  * `RunnerInterface` (see `RunnerOptions`). The runner enables sub-agent fan-out: a
  * parent job's handler can `controller.spawn(childJob)` to launch a child agent job
@@ -920,7 +1082,7 @@ export declare function agentResultToJSON(value: unknown): JSONValue | undefined
  */
 export declare interface AgentRunnerOptions {
     readonly registry: AgentRegistryInterface;
-    /** If `true`, a partial `AgentResult` resolves as success; if `false` (the default), it THROWS and fail-fast engages. */
+    /** If `true`, a partial `AgentResult` resolves as success; if `false` (the default), it throws and fail-fast engages. */
     readonly partial?: boolean;
     readonly concurrency?: number;
     readonly retries?: number;
@@ -929,14 +1091,15 @@ export declare interface AgentRunnerOptions {
 
 /**
  * Carries the per-run override bag an {@link AgentInterface}'s `generate` / `stream` accepts — each
- * member overrides the matching {@link AgentOptions} value for ONE run.
+ * member overrides the matching {@link AgentOptions} value for one run, where `think` and `schema`
+ * forward to the provider call and `signal` composes with the constructed one.
  *
  * @remarks
  * Every member is optional and resolved independently, so an omitted member leaves the
  * agent's constructed value in force and a caller that passes no options runs exactly the
  * agent it configured. `think` / `schema` ride through to the provider as
  * {@link ProviderStreamOptions}; `limit` / `timeout` / `budget` replace their construction
- * defaults for this run only; `signal` COMPOSES with the constructed `signal` (both fold into
+ * defaults for this run only; `signal` composes with the constructed `signal` (both fold into
  * the run's bound abort) rather than replacing it. Nothing here mutates the agent — the next
  * run reads the construction defaults again.
  */
@@ -956,23 +1119,23 @@ export declare interface AgentRunOptions {
      */
     readonly schema?: Readonly<Record<string, unknown>>;
     /**
-     * Overrides {@link AgentOptions.limit} for THIS run only — the max tool-iteration turns
+     * Overrides {@link AgentOptions.limit} for this run only — the max tool-iteration turns
      * before the loop stops. Omitted ⇒ the agent's constructed `limit` applies.
      */
     readonly limit?: number;
     /**
-     * Overrides {@link AgentOptions.timeout} for THIS run only — a wall-clock deadline (ms)
+     * Overrides {@link AgentOptions.timeout} for this run only — a wall-clock deadline (ms)
      * whose abort commits a partial result. Omitted ⇒ the agent's constructed `timeout` applies.
      */
     readonly timeout?: number;
     /**
-     * Overrides {@link AgentOptions.budget} for THIS run only — a token cost bound whose abort
+     * Overrides {@link AgentOptions.budget} for this run only — a token cost bound whose abort
      * commits a partial result; `start()`ed for this run exactly as the constructed budget is.
      * Omitted ⇒ the agent's constructed `budget` applies.
      */
     readonly budget?: BudgetInterface<TokenUsage>;
     /**
-     * Carries an additional per-run external cancel, COMPOSED with {@link AgentOptions.signal} (both
+     * Carries an additional per-run external cancel, composed with {@link AgentOptions.signal} (both
      * fold into the run's bound abort through `AbortSignal.any` — neither is dropped). Omitted ⇒
      * only the agent's constructed `signal` (if any) applies.
      */
@@ -994,10 +1157,11 @@ export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResu
 
 /**
  * Assembles the settled {@link AgentResult} from a run's {@link RunOutcome} — `thinking` and
- * `usage` are carried only when the run surfaced them.
+ * `usage` are carried only when the run surfaced them, and the loop-internal `exhausted` flag is
+ * left out.
  *
  * @remarks
- * Pure and total. An absent optional is OMITTED rather than stored as `undefined` (the
+ * Pure and total. An absent optional is omitted rather than stored as `undefined` (the
  * present-when-given convention the message store follows), so a settled result JSON
  * round-trips without an explicit `undefined` field. `exhausted` is loop bookkeeping and does
  * not reach the public result — the `exhaust` event carries it instead.
@@ -1014,11 +1178,11 @@ export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResu
 export declare function assembleResult(outcome: RunOutcome): AgentResult;
 
 /**
- * Copies a message with image data merged onto its `images` — the message's own images
- * first, then the attached data.
+ * Copies a message with image data merged onto its `images` — the message's own images first,
+ * then the attached data, carrying `calls` only when present and never mutating the original.
  *
  * @remarks
- * Pure and total: the original message is NEVER mutated. `calls` is carried only when the
+ * Pure and total: the original message is never mutated. `calls` is carried only when the
  * source message has one (kept omitted otherwise, mirroring the store's present-when-given
  * convention).
  *
@@ -1035,13 +1199,14 @@ export declare function assembleResult(outcome: RunOutcome): AgentResult;
 export declare function attachImages(message: Message, data: readonly string[]): Message;
 
 /**
- * Attaches image data to a conversation's LAST user message — the turn a vision provider
- * reads images off.
+ * Attaches image data to a conversation's last user message — the turn a vision provider reads
+ * images off — as a new array with that one message replaced by its carrying copy, and unchanged
+ * when there is no data or no user turn.
  *
  * @remarks
- * Pure and total: the conversation and its messages are NEVER mutated, and the returned array
+ * Pure and total: the conversation and its messages are never mutated, and the returned array
  * replaces exactly the one target message with the copy {@link attachImages} builds. Empty
- * data returns the conversation unchanged; a conversation with NO user message returns it
+ * data returns the conversation unchanged; a conversation with no user message returns it
  * unchanged too (there is nowhere to attach, and the images already rode the system block).
  *
  * @param conversation - The messages to attach into (left unchanged)
@@ -1057,18 +1222,20 @@ export declare function attachImages(message: Message, data: readonly string[]):
 export declare function attachUserImages(conversation: readonly Message[], data: readonly string[]): readonly Message[];
 
 /**
- * Gates the agent loop's tool calls — the synchronous policy consulted before each call
- * runs, turning one {@link AuthorityContext} into an {@link AuthorityDecision}.
+ * Gates the agent loop's tool calls — the synchronous policy consulted before each call runs,
+ * turning one {@link AuthorityContext} into an {@link AuthorityDecision} by walking the ordered
+ * rules first-match-wins and falling back to a configurable default, which allows an unmatched
+ * call unless its `fallback` denies.
  *
  * @remarks
  * - **Ordered, first-match-wins.** `evaluate` walks the configured rules in order and
- *   returns the FIRST whose `match(context)` is true as
- *   `{ zone, allowed: rule.allowed ?? true, reason }` — a matched rule ALLOWS by
- *   default and DENIES only when its `allowed` is explicitly `false`.
+ *   returns the first whose `match(context)` is true as
+ *   `{ zone, allowed: rule.allowed ?? true, reason }` — a matched rule allows by
+ *   default and denies only when its `allowed` is explicitly `false`.
  * - **Fallback.** When no rule matches, `evaluate` returns the configured `fallback`.
  *   It defaults to `{ zone: DEFAULT_AUTHORITY_ZONE, allowed: true }` (allow-unmatched),
- *   so a rules list of denials behaves as a DENYLIST. To make the gate deny-by-default
- *   (an ALLOWLIST — only matched rules that allow get through), pass an `allowed: false`
+ *   so a rules list of denials behaves as a denylist. To make the gate deny-by-default
+ *   (an allowlist — only matched rules that allow get through), pass an `allowed: false`
  *   `fallback`.
  * - **Consulted before each tool call.** The agent loop calls `evaluate({ call })` for
  *   every {@link import('@orkestrel/tool').ToolCall} the model emits; a denied call is fed
@@ -1133,7 +1300,8 @@ export declare interface AuthorityDecision {
  */
 export declare interface AuthorityInterface {
     /**
-     * Evaluates one tool call against the ordered rules.
+     * Evaluates one tool call against the ordered rules — returns the first matching rule's
+     * verdict, which allows unless `allowed: false`, or the fallback when none match.
      *
      * @param context - The call under consideration (see {@link AuthorityContext})
      * @returns The first matching rule's verdict, or the fallback when none match
@@ -1146,7 +1314,7 @@ export declare interface AuthorityInterface {
  *
  * @remarks
  * `rules` are evaluated in order, first match wins (see {@link AuthorityRule}).
- * `fallback` is the {@link AuthorityDecision} returned when NO rule matches; it
+ * `fallback` is the {@link AuthorityDecision} returned when no rule matches; it
  * defaults to `{ zone: DEFAULT_AUTHORITY_ZONE, allowed: true }` (allow-unmatched — a
  * rules list of denials acts as a denylist). Set `fallback` to an `allowed: false`
  * decision to flip the gate to deny-by-default (an allowlist — only matched rules
@@ -1161,8 +1329,8 @@ export declare interface AuthorityOptions {
  * Represents one ordered policy rule an {@link AuthorityInterface} evaluates.
  *
  * @remarks
- * The FIRST rule whose `match` returns true decides; if none match, the authority's
- * `fallback` decides. A matched rule ALLOWS by default and DENIES only when its
+ * The first rule whose `match` returns true decides; if none match, the authority's
+ * `fallback` decides. A matched rule allows by default and denies only when its
  * `allowed` is explicitly `false`. `zone` classifies the matched call; `reason` is the
  * optional explanation carried into the {@link AuthorityDecision} (and, on a denial,
  * into the denial {@link ToolResult}).
@@ -1175,13 +1343,28 @@ export declare interface AuthorityRule {
 }
 
 /**
- * Builds the FRAMED recap message for one compacted section — the same role and stable `id`
- * as {@link buildSummaryMessage}, with the content prefixed by
- * {@link import('./constants.js').CONVERSATION_RECAP_PREFIX}.
+ * Assembles a provider result with only populated optional fields.
+ *
+ * @param content - The authoritative answer
+ * @param thinking - The joined reasoning
+ * @param tools - The accumulated calls
+ * @param usage - The reported token usage
+ * @returns The assembled result
+ * @example
+ * ```ts
+ * buildProviderResult('ok', '', [], undefined) // { content: 'ok' }
+ * ```
+ */
+export declare function buildProviderResult(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage | undefined): ProviderResult;
+
+/**
+ * Builds the framed recap message for one compacted section — the same role and stable `id` as
+ * {@link buildSummaryMessage}, with the content prefixed by {@link
+ * import('./constants.js').CONVERSATION_RECAP_PREFIX}.
  *
  * @remarks
- * Pure and total. The prefix is what makes a small model read the message as a CONDENSED
- * RECAP of earlier turns rather than a literal assistant turn to echo or answer from. It is a
+ * Pure and total. The prefix is what makes a small model read the message as a condensed
+ * recap of earlier turns rather than a literal assistant turn to echo or answer from. It is a
  * fixed handful of tokens, so a conversation's `view()` stays lean however many sections it
  * carries.
  *
@@ -1197,12 +1380,12 @@ export declare interface AuthorityRule {
 export declare function buildRecapMessage(section: Section): Message;
 
 /**
- * Builds the RAW synthetic summary message for one compacted section — role `'assistant'`,
- * the section's stable `id`, its `summary` VERBATIM as content.
+ * Builds the raw synthetic summary message for one compacted section — role `'assistant'`, the
+ * section's stable `id`, and its `summary` verbatim as content.
  *
  * @remarks
  * Pure and total. This is the unframed form the rollup regeneration digests (a
- * summary-of-summaries over the section summaries); the recap LABEL is a `view()`
+ * summary-of-summaries over the section summaries); the recap label is a `view()`
  * presentation concern kept out of what the summarizer re-reads — see
  * {@link buildRecapMessage}.
  *
@@ -1218,10 +1401,11 @@ export declare function buildRecapMessage(section: Section): Message;
 export declare function buildSummaryMessage(section: Section): Message;
 
 /**
- * Buffers chunks in a minimal unbounded async channel — the eager pump WRITES them in
- * (`push`) and ends it (`close` / `fail`) regardless of consumption; a consumer READS them back
- * live through the `drain` async-iterator. Decoupling write from read is what lets a
- * producer make progress without a consumer pulling.
+ * Buffers chunks in a minimal unbounded async channel — the eager pump writes them in (`push`)
+ * and ends it (`close` / `fail`) regardless of consumption, while a consumer reads them back live
+ * through the `drain` async-iterator. Decoupling write from read is what lets a producer make
+ * progress without a consumer pulling, and it is why an agent's `result` settles whether or not
+ * its `events` are drained.
  *
  * @remarks
  * The standard resolver-swap: a waiting `drain` parks on `#wake` (a void resolver);
@@ -1250,24 +1434,25 @@ export declare class Channel<T> implements ChannelInterface<T> {
 }
 
 /**
- * Buffers values in an unbounded async channel — a producer WRITES them in (`push`) and
- * ends it (`close` / `fail`) regardless of consumption, while a consumer READS them back
- * live through `drain`.
+ * Buffers values in an unbounded async channel — a producer writes them in (`push`) and ends it
+ * (`close` / `fail`) regardless of consumption, while a consumer reads them back live through
+ * `drain`.
  *
  * @remarks
  * Decoupling the write from the read is what lets a producer make progress with nobody
  * pulling: an agent's eager pump writes each {@link AgentChunk} into one, so the run's
  * `result` settles whether or not `events` is ever drained. A waiting `drain` parks on a
  * resolver the next `push` / `close` / `fail` fires, so a value pushed at a parked reader is
- * delivered rather than dropped. Buffered values are always yielded BEFORE the end is
- * reported, so a `close` arriving alongside the last values still delivers them. The FIRST
+ * delivered rather than dropped. Buffered values are always yielded before the end is
+ * reported, so a `close` arriving alongside the last values still delivers them. The first
  * failure wins — a later `close` / `fail` cannot override a recorded error. Event-free.
  *
  * @typeParam T - The value type the channel carries
  */
 export declare interface ChannelInterface<T> {
     /**
-     * Writes one value — buffered, then handed to a parked consumer.
+     * Writes one value — buffered, then handed to a parked consumer; a value pushed at an
+     * already-parked reader is delivered, never dropped.
      *
      * @param value - The value to enqueue
      */
@@ -1275,13 +1460,14 @@ export declare interface ChannelInterface<T> {
     /** Ends the channel normally — a draining consumer returns once the buffer is empty. */
     close(): void;
     /**
-     * Ends the channel with a failure — a draining consumer throws it once the buffer is empty.
+     * Ends the channel with a failure — a draining consumer throws it once the buffer is empty;
+     * the first failure wins.
      *
      * @param error - The failure to surface (the first one recorded wins)
      */
     fail(error: unknown): void;
     /**
-     * Reads the values back live, in write order.
+     * Reads the values back live, in write order — returning on `close` and throwing on `fail`.
      *
      * @returns A generator yielding each pushed value, returning on `close` and throwing on `fail`
      */
@@ -1289,11 +1475,11 @@ export declare interface ChannelInterface<T> {
 }
 
 /**
- * Collects the `base64` payload of the IMAGE files in a workspace file list — the data an
- * agent context attaches to the last user message.
+ * Collects the `base64` payload of the image files in a workspace file list — the data an agent
+ * context attaches to the last user message.
  *
  * @remarks
- * Pure and total. `isBinary` NARROWS the tagless content to its binary arm (a total guard,
+ * Pure and total. `isBinary` narrows the tagless content to its binary arm (a total guard,
  * never an assertion), then the MIME prefix gates it to an image, so a text file and a non-image
  * binary (a PDF) are both skipped. Order follows the file list.
  *
@@ -1309,14 +1495,15 @@ export declare interface ChannelInterface<T> {
 export declare function collectImageData(files: readonly FileInterface[]): readonly string[];
 
 /**
- * Configures one {@link ConversationInterface.compact} call — overrides for ONE fold.
+ * Configures one {@link ConversationInterface.compact} call — the retained-tail size, the
+ * `sections` cap, or both, overridden for one fold.
  *
  * @remarks
- * `keep` overrides the conversation's configured retained-tail size for THIS compaction only
+ * `keep` overrides the conversation's configured retained-tail size for this compaction only
  * (the older `count - keep` live messages fold; when `count <= keep` nothing folds and
  * `compact()` is a no-op returning `undefined`). Omitted ⇒ the conversation's own `keep`
  * (its option, or `DEFAULT_CONVERSATION_KEEP`) applies. `sections` overrides the conversation's
- * configured `sections` cap for THIS compaction only — after the new section is pushed, an
+ * configured `sections` cap for this compaction only — after the new section is pushed, an
  * overflow past `sections` folds the oldest sections into one merged section. Omitted ⇒ the
  * conversation's own `sections` cap (or unlimited) applies.
  */
@@ -1328,17 +1515,17 @@ export declare interface CompactOptions {
 }
 
 /**
- * Holds a provider's OPTIONAL context-framing default, keyed by section kind — the framing a
- * model prefers (for example XML tags against Markdown headers), declared by a
- * {@link ProviderInterface} that opts in.
+ * Holds a provider's optional context-framing default, keyed by section kind — the framing a model
+ * prefers (for example XML tags against Markdown headers), declared by a {@link ProviderInterface}
+ * that opts in.
  *
  * @remarks
  * Each key is a {@link ContextSectionFormat} for one of the observable context sections
  * (the `instructions` section), so a provider can frame each section independently — and any
- * it omits falls through to that manager's built-in default. It is the PROVIDER-DEFAULT
- * level of the {@link import('./AgentContext.js').AgentContext} build cascade: it BEATS a
- * manager's built-in default but is BEATEN by a manager-options override and by a per-item
- * override (see {@link AgentContextInterface.build}). It references the ABSTRACT core
+ * it omits falls through to that manager's built-in default. It is the provider-default
+ * level of the {@link import('./AgentContext.js').AgentContext} build cascade: it beats a
+ * manager's built-in default but is beaten by a manager-options override and by a per-item
+ * override (see {@link AgentContextInterface.build}). It references the abstract core
  * item interface ({@link InstructionInterface}), so a provider opting in imports it from
  * `@orkestrel/agent` — the type is provider-agnostic, with no backend coupling. Omitting it
  * entirely (the default for an agnostic provider) leaves every section on its manager's
@@ -1356,17 +1543,17 @@ export declare interface ContextFormat {
  * line rendered once after the items.
  *
  * @remarks
- * `open`, `render`, and `close` are OPTIONAL and resolved INDEPENDENTLY (so an override may set only
+ * `open`, `render`, and `close` are optional and resolved independently (so an override may set only
  * the top, only the per-item rendering, only the bottom, or any mix). A section assembles
  * as `[open, ...items.map(render), close]` with empty / absent slots dropped, the survivors
- * blank-line (`\n\n`) joined — so `open` + `close` together let a developer WRAP the whole
+ * blank-line (`\n\n`) joined — so `open` + `close` together let a developer wrap the whole
  * group (for example `open: '<instructions>'` … `close: '</instructions>'`). `open` is the
  * section's leading text (the header, or a group's opening tag); `render` turns one section
  * item (an {@link InstructionInterface}) into its prompt text; `close` is the trailing text.
  * `open` and `render` cascade through the
  * built-in floor (`open` ⇒ the manager's built-in header, `render` ⇒ the manager's built-in
- * rendering); `close` has NO built-in, so an unset `close` yields no closing line.
- * It is the unit BOTH a provider's {@link ContextFormat} (a per-section-kind
+ * rendering); `close` has no built-in, so an unset `close` yields no closing line.
+ * It is the unit both a provider's {@link ContextFormat} (a per-section-kind
  * default) and a manager's `Options` carry — see {@link AgentContextInterface.build} for
  * the full precedence.
  *
@@ -1374,7 +1561,7 @@ export declare interface ContextFormat {
  */
 export declare interface ContextSectionFormat<T> {
     /**
-     * Holds text rendered ONCE before the section's items — the section header or a group's
+     * Holds text rendered once before the section's items — the section header or a group's
      * opening wrapper, for example `'<instructions>'`; omitted ⇒ the next cascade level decides
      * (defaulting to the built-in header).
      */
@@ -1382,25 +1569,25 @@ export declare interface ContextSectionFormat<T> {
     /** Overrides one item's rendering; omitted ⇒ the next cascade level decides. */
     readonly render?: (item: T) => string;
     /**
-     * Holds text rendered ONCE after the section's items — a group's closing wrapper, for
+     * Holds text rendered once after the section's items — a group's closing wrapper, for
      * example `'</instructions>'`; omitted ⇒ no closing line (there is no built-in close).
      */
     readonly close?: string;
 }
 
 /**
- * Exposes the manager surface one context section's format cascade reads — its built-in
- * `open` / `render`, plus the raw options override the cascade layers a provider
- * default beneath.
+ * Exposes the manager surface one context section's format cascade reads — its built-in `open` /
+ * `render`, plus the raw options override the cascade layers a provider default beneath; {@link
+ * InstructionManagerInterface} satisfies it structurally.
  *
  * @remarks
  * The narrow contract the cascade resolvers
  * ({@link import('./helpers.js').resolveOpen} / {@link import('./helpers.js').resolveClose} /
- * {@link import('./helpers.js').resolveItem}) take, so they stay independent of WHICH manager
+ * {@link import('./helpers.js').resolveItem}) take, so they stay independent of which manager
  * supplies the section: an {@link InstructionManagerInterface} satisfies it structurally.
  * `open` and `render` already encapsulate `[options-override → built-in]` (so a manager
  * used standalone renders correctly), and `format` exposes the raw override so `build()` can
- * interleave the provider default BENEATH it.
+ * interleave the provider default beneath it.
  *
  * @typeParam T - The section item this source renders
  */
@@ -1409,41 +1596,45 @@ export declare interface ContextSectionSourceInterface<T> {
     readonly open: string;
     /** Holds the raw manager-options override, or `undefined` when none was supplied. */
     readonly format: ContextSectionFormat<T> | undefined;
-    /** Renders one item (already resolved against the manager-options override). */
+    /**
+     * Renders one section item, already resolved against the manager-options override and
+     * otherwise on the built-in rendering.
+     */
     render(item: T): string;
 }
 
 /**
- * Represents a conversation — a live uncompacted tail of messages it OWNS DIRECTLY ABOVE a
- * flat message store, plus compacted, summarized {@link Section}s and a regenerated rollup
- * `summary`, with on-demand `rehydrate` and substring `search`, driven by a provider-agnostic
- * {@link ConversationSummaryHandler} seam (so `core` never imports a provider).
+ * Represents a conversation — a live uncompacted tail of messages it owns directly above a flat
+ * message store, plus compacted, summarized {@link Section}s, a regenerated rollup `summary`, and
+ * a `summarizable` flag, with on-demand `rehydrate` and substring `search`, driven by a
+ * provider-agnostic {@link ConversationSummaryHandler} seam so `core` never imports a provider.
+ * Observable through its own `emitter`.
  *
  * @remarks
- * - **Live tail + sections.** The conversation OWNS its live tail DIRECTLY — `#messages` is an
+ * - **Live tail + sections.** The conversation owns its live tail directly — `#messages` is an
  *   insertion-ordered `Map` of immutable {@link Message}s keyed by their minted id
- *   (the SAME store mechanics a flat manager had, folded in: `add` / `message` / `messages` /
+ *   (the same store mechanics a flat manager had, folded in: `add` / `message` / `messages` /
  *   `remove` / `clear` / `count`), exactly as a `Workspace` owns its files (no separate
  *   per-value manager). `#sections` are the compacted history (oldest → newest), each a
- *   summarized slice that RETAINS its originals. `#summary` is the rollup (a
+ *   summarized slice that retains its originals. `#summary` is the rollup (a
  *   summary-of-summaries over all sections), regenerated on each compaction (`undefined`
  *   until the first).
- * - **`view()`.** Each section folds to ONE synthetic summary message (role `'assistant'` — a
+ * - **`view()`.** Each section folds to one synthetic summary message (role `'assistant'` — a
  *   prior-context recap — keyed by the section's stable `id`), then the live messages
- *   verbatim. The rollup `summary` is NOT injected (it is separately pull-able); `view()`
- *   carries the per-section summaries, which ARE the compaction benefit.
+ *   verbatim. The rollup `summary` is not injected (it is separately pull-able); `view()`
+ *   carries the per-section summaries, which are the compaction benefit.
  * - **`compact()`.** Folds the oldest `count - keep` live messages into a new section
  *   (its `summary` from `#summarize`), removes them from the live tail by id, regenerates the
- *   rollup (a SECOND `#summarize` over all section summaries), and emits `summary` then
+ *   rollup (a second `#summarize` over all section summaries), and emits `summary` then
  *   `compact`. Returns the section, or `undefined` when nothing folds (`count <= keep`).
- *   THROWS a {@link ConversationError} when no `#summarize` was supplied. Two summarizer calls
- *   per compaction.
+ *   Throws a {@link ConversationError} when no `#summarize` was supplied. A compaction calls
+ *   the summarizer for the section digest and again for the rollup.
  * - **`rehydrate(id)` / `search(query)`.** `rehydrate` returns a section's full original
  *   messages (`[]` for an unknown id) and emits `rehydrate` — a pure read (the caller decides
  *   whether to re-add them; `rehydrate` never reinserts). `search` is a case-insensitive
- *   substring scan of `content` across ALL messages (every section's originals + the live tail).
+ *   substring scan of `content` across all messages (every section's originals + the live tail).
  * - **Observable.** The owned {@link emitter} ({@link ConversationEventMap}) carries
- *   `compact` / `summary` / `rehydrate`, emitted directly, strictly AFTER the state change;
+ *   `compact` / `summary` / `rehydrate`, emitted directly, strictly after the state change;
  *   the emitter isolates a listener throw and routes it to its `error` handler (the `error`
  *   option), so a buggy observer can never corrupt a compaction.
  *
@@ -1485,12 +1676,13 @@ export declare class Conversation implements ConversationInterface {
 
 /**
  * Names the framing label a {@link ConversationInterface}'s `view()` prefixes onto each compacted
- * section's summary so a small model reads it as a CONDENSED RECAP of earlier turns — not a
- * literal assistant turn to echo or treat as the live answer.
+ * section's summary so a small model reads it as a condensed recap of earlier turns — the lean
+ * `'[Summary of earlier messages] '` marker, never a literal assistant turn to echo or treat as
+ * the live answer.
  *
  * @remarks
- * Deliberately a FIXED, lean handful of tokens (a short bracketed marker) so the framing adds a
- * bounded `prefix × sections` overhead and NEVER an open-ended blow-up — the
+ * Deliberately a fixed, lean handful of tokens (a short bracketed marker) so the framing adds a
+ * bounded `prefix × sections` overhead and never an open-ended blow-up — the
  * {@link ConversationInterface} no-bloat test guard pins exactly that. Kept here (beside
  * {@link DEFAULT_CONVERSATION_KEEP}) as the conversation layer's one tunable framing constant, so
  * the wording has a single source of truth as it is optimized against real small-model behavior
@@ -1500,12 +1692,13 @@ export declare class Conversation implements ConversationInterface {
 export declare const CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages] ";
 
 /**
- * Reports a conversation with no {@link ConversationSummaryHandler} to fold its messages
- * with, or with a structurally invalid `sections` cap — thrown by a
- * {@link ConversationInterface}'s `compact()`, carrying a machine-readable `code`.
+ * Reports a conversation with no {@link ConversationSummaryHandler} to fold its messages with,
+ * or with a `sections` cap below `1` — thrown by a {@link ConversationInterface}'s `compact()`
+ * or its construction, carrying the machine-readable `code`
+ * `'SUMMARIZER' | 'SECTIONS'`.
  *
  * @remarks
- * Compaction REQUIRES a summarizer (it digests the folded slice into a section summary and
+ * Compaction requires a summarizer (it digests the folded slice into a section summary and
  * regenerates the rollup); a conversation created without one can still store + `view()` its
  * live tail, but a `compact()` is a programmer error and throws this with `'SUMMARIZER'`.
  * A `sections` cap (on {@link import('./types.js').ConversationOptions} /
@@ -1526,7 +1719,7 @@ export declare class ConversationError extends Error {
  *
  * @remarks
  * `compact` carries the newly-folded {@link Section}; `collapse` carries a section
- * created by folding multiple OLDER sections together (a bounded-`sections` cap enforcement,
+ * created by folding multiple older sections together (a bounded-`sections` cap enforcement,
  * distinct from `compact`'s fresh live-tail fold); `summary` carries the regenerated
  * conversation rollup (refreshed on each compaction); `rehydrate` carries the `id` of a
  * section whose originals were pulled back. Listener isolation is the emitter's:
@@ -1543,31 +1736,32 @@ export declare type ConversationEventMap = {
     /** Reports a section's original messages pulled back — the section's `id`. */
     readonly rehydrate: readonly [id: string];
     /**
-     * Reports the bounded-`sections` cap folding the oldest sections into ONE merged section — the
+     * Reports the bounded-`sections` cap folding the oldest sections into one merged section — the
      * merged {@link Section} that replaced them.
      */
     readonly collapse: readonly [section: Section];
 };
 
 /**
- * Carries the data to author a {@link ConversationInterface} through a
- * {@link ConversationManagerInterface} — the optional `id`, a `summarize` override, a `keep`
- * override, and the reserved `on` hooks.
+ * Carries the data to author a {@link ConversationInterface} through a {@link
+ * ConversationManagerInterface} — the optional `id`, a `summarize` override, a `keep` override, a
+ * `sections` cap override, the reserved `on` hooks, and a {@link ConversationSnapshot} to hydrate
+ * from.
  *
  * @remarks
- * `id` is the conversation's identity (minted when omitted). `summarize` OVERRIDES the
+ * `id` is the conversation's identity (minted when omitted). `summarize` overrides the
  * manager's default {@link ConversationSummaryHandler} for this conversation (omitted ⇒ the
  * manager's default flows in). `keep` overrides the manager's default retained-tail size.
  * `sections` overrides the manager's default `sections` cap. `on` is the reserved listener key
  * (initial {@link ConversationEventMap} listeners). `snapshot` is
  * the construction-time hydration seam — a {@link ConversationSnapshot} whose `id` / `summary` /
- * `sections` / live tail are RESTORED into the new conversation (the live `summarize` / `keep` /
+ * `sections` / live tail are restored into the new conversation (the live `summarize` / `keep` /
  * `on` re-supplied alongside it), the conversation analogue of
  * {@link import('@orkestrel/workspace').WorkspaceOptions}'s `seed`, carried onto
  * {@link ConversationOptions.snapshot}, that a
  * {@link ConversationManagerInterface.open} reads a stored snapshot back through; hydration is
  * silent (no events). When both `snapshot.id` and `id` are given, `snapshot.id` wins (the snapshot
- * IS the conversation's identity).
+ * is the conversation's identity).
  */
 export declare interface ConversationInput {
     readonly id?: string;
@@ -1583,52 +1777,53 @@ export declare interface ConversationInput {
 }
 
 /**
- * Groups messages ABOVE the flat {@link MessageManagerInterface} — a live
- * uncompacted tail plus compacted, summarized {@link Section}s and a conversation
- * rollup `summary`, with on-demand `rehydrate` and substring `search`, driven by a
- * provider-agnostic {@link ConversationSummaryHandler} seam.
+ * Groups messages above the flat {@link MessageManagerInterface} — a live uncompacted tail plus
+ * compacted, summarized {@link Section}s and a conversation rollup `summary`, with on-demand
+ * `rehydrate`, substring `search`, a cross-conversation `reference`, and a JSON `snapshot`, driven
+ * by a provider-agnostic {@link ConversationSummaryHandler} seam; `summarizable` reports whether
+ * that seam was supplied, and the agent loop gates automatic compaction on it.
  *
  * @remarks
- * - **Live tail + sections.** The conversation OWNS its LIVE uncompacted tail DIRECTLY — a
+ * - **Live tail + sections.** The conversation owns its live uncompacted tail directly — a
  *   caller appends turns through its own message verbs (`add` mints each `id`, `message` /
  *   `messages` look up, `remove` / `clear` drop, `count` tallies), exactly as a `Workspace`
  *   owns its files (no separate per-value manager). `sections` are the compacted history
- *   (oldest → newest), each a summarized slice that RETAINS its originals. `summary` is the
+ *   (oldest → newest), each a summarized slice that retains its originals. `summary` is the
  *   conversation rollup (a summary-of-summaries over all sections), regenerated on each
  *   compaction (`undefined` until the first compaction).
  * - **Message verbs (the inlined store).** `add` takes one {@link MessageInput} or a batch,
- *   MINTS each message's `id` (a random UUID), stores it, and returns the created
+ *   mints each message's `id` (a random UUID), stores it, and returns the created
  *   message(s); a stored message is immutable. `message(id)` resolves one (`undefined` when
  *   absent); `messages()` lists the live tail in insertion order; `remove` drops one by id or
- *   a batch (`true` only when EVERY supplied id was removed); `clear` empties the tail;
+ *   a batch (`true` only when every supplied id was removed); `clear` empties the tail;
  *   `count` is how many live messages are stored.
- * - **`view()` — the model input.** Each section folds to ONE synthetic summary message,
+ * - **`view()` — the model input.** Each section folds to one synthetic summary message,
  *   followed by the live messages verbatim: `[...sections-as-summary-messages, ...live]`. The
- *   rollup `summary` is NOT injected (it is a separately pull-able digest for a
- *   cross-conversation case); `view()` carries the per-section summaries, which ARE the
+ *   rollup `summary` is not injected (it is a separately pull-able digest for a
+ *   cross-conversation case); `view()` carries the per-section summaries, which are the
  *   compaction benefit.
  * - **`compact()` — fold older live → a section.** Folds the oldest `count - keep` live
  *   messages into a new {@link Section} (its `summary` from `summarize`), removes
- *   them from the live tail, REGENERATES the rollup (a second `summarize` over all section
+ *   them from the live tail, regenerates the rollup (a second `summarize` over all section
  *   summaries), and emits `summary` then `compact` — returning the new section (or
- *   `undefined` when nothing folds). TWO summarizer calls per compaction (the section digest
- *   + the rollup). Throws a {@link import('./errors.js').ConversationError} when no
- *   `summarize` was supplied.
- * - **`summarizable` — whether a `compact()` CAN fold.** `true` when a
- *   {@link ConversationSummaryHandler} was supplied, `false` otherwise. The agent loop's AUTOMATIC
+ *   `undefined` when nothing folds). A compaction calls the summarizer for the section
+ *   digest and again for the rollup. Throws a
+ *   {@link import('./errors.js').ConversationError} when no `summarize` was supplied.
+ * - **`summarizable` — whether a `compact()` can fold.** `true` when a
+ *   {@link ConversationSummaryHandler} was supplied, `false` otherwise. The agent loop's automatic
  *   compaction (`AgentOptions.window`) gates on it so a conversation that has no summarizer is
  *   never auto-compacted (and the loop never throws the `compact()` `SUMMARIZER` error from the
- *   auto path). A MANUAL `compact()` still throws without a summarizer — only the auto path is
+ *   auto path). A manual `compact()` still throws without a summarizer — only the auto path is
  *   guarded.
  * - **`rehydrate(id)` / `search(query)` — read the retained originals.** `rehydrate` returns
  *   a section's full original messages (`[]` for an unknown id) and emits `rehydrate` — a
- *   pure READ (the caller decides whether to re-add them; `rehydrate` never reinserts).
- *   `search` is a case-insensitive substring scan of `content` across ALL messages (every
+ *   pure read (the caller decides whether to re-add them; `rehydrate` never reinserts).
+ *   `search` is a case-insensitive substring scan of `content` across all messages (every
  *   section's originals + the live tail).
- * - **`reference(options?)` — pull THIS conversation into ANOTHER with provenance.** A PURE
+ * - **`reference(options?)` — pull this conversation into another with provenance.** A pure
  *   string render (no model call) of a self-labeled, fenced cross-conversation block — the
  *   rollup `summary` (when included + present) plus cherry-picked excerpts — framed so a small
- *   model reads it as FOREIGN material. Written into the ACTIVE conversation's context through
+ *   model reads it as foreign material. Written into the active conversation's context through
  *   the active workspace (`context.workspaces.active?.write(path, block)`); the cherry-pick
  *   comes from this conversation's own `search` / `rehydrate`, never its whole history.
  * - **Observable.** The owned `emitter` ({@link ConversationEventMap}) carries
@@ -1643,17 +1838,18 @@ export declare interface ConversationInterface {
     /** Lists the compacted history, oldest → newest. */
     readonly sections: readonly Section[];
     /**
-     * Reports whether a `compact()` CAN fold — `true` when a {@link ConversationSummaryHandler} was supplied.
-     * The agent loop's AUTOMATIC compaction (`AgentOptions.window`) gates on it (a non-summarizable
+     * Reports whether a `compact()` can fold — `true` when a {@link ConversationSummaryHandler} was supplied.
+     * The agent loop's automatic compaction (`AgentOptions.window`) gates on it (a non-summarizable
      * conversation is never auto-compacted, so the auto path never throws the `SUMMARIZER` error);
-     * a MANUAL `compact()` still throws without a summarizer.
+     * a manual `compact()` still throws without a summarizer.
      */
     readonly summarizable: boolean;
-    /** Counts the LIVE (uncompacted) messages stored in the tail. */
+    /** Counts the live (uncompacted) messages stored in the tail. */
     readonly count: number;
     /**
-     * Appends one message to the live tail (or a batch) — MINTS each message's `id`
-     * (a random UUID) and returns the created message(s); a stored message is immutable.
+     * Appends one {@link MessageInput} to the live tail, or a batch — mints each message's `id`
+     * (a random UUID) and returns the created message or messages; a stored message is
+     * immutable.
      *
      * @param input - One {@link MessageInput}, or a batch
      * @returns The created {@link Message}(s), with their minted `id`s
@@ -1661,50 +1857,52 @@ export declare interface ConversationInterface {
     add(input: MessageInput): Message;
     add(inputs: readonly MessageInput[]): readonly Message[];
     /**
-     * Looks up one LIVE message by id.
+     * Looks up one live message by id (`undefined` when absent).
      *
      * @param id - The message id to resolve
      * @returns The {@link Message}, or `undefined` when absent
      */
     message(id: string): Message | undefined;
     /**
-     * Lists every LIVE (uncompacted) message in the tail, in insertion order.
+     * Lists every live, uncompacted message in the tail, in insertion order.
      *
      * @returns The live tail, in insertion order
      */
     messages(): readonly Message[];
     /**
-     * Removes one LIVE message by id (or a batch) from the tail.
+     * Removes one live message by id, or a batch, from the tail — `true` only when every
+     * supplied id was removed.
      *
      * @param id - One message id, or a batch
      * @returns True when every supplied id was present and removed; false otherwise
      */
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
-    /** Empties the live tail (the compacted `sections` are untouched). */
+    /** Empties the live tail, leaving the compacted `sections` untouched. */
     clear(): void;
     /**
-     * Builds the model input for the next turn — each section as ONE synthetic summary message,
-     * then the live messages verbatim (the rollup `summary` is NOT injected).
+     * Builds the model input for the next turn — each section as one synthetic recap message,
+     * its summary prefixed with `CONVERSATION_RECAP_PREFIX` so a small model reads it as a
+     * recap rather than a literal turn, then the live tail verbatim; the rollup `summary` is
+     * not injected.
      *
      * @returns `[...sections-as-summary-messages, ...live messages]`
      */
     view(): readonly Message[];
     /**
-     * Folds the older live messages into a summarized {@link Section}, regenerates the
-     * rollup, and emits `summary` then `compact`.
+     * Folds the oldest `count - keep` live messages into a summarized {@link Section} through
+     * the {@link ConversationSummaryHandler}, removes them from the live tail, regenerates the
+     * rollup, and emits `summary` then `compact` — resolving `undefined` when nothing folds
+     * (`count <= keep`). Throws a {@link import('./errors.js').ConversationError} when no
+     * summarizer was supplied.
      *
      * @remarks
-     * Folds the oldest `count - keep` live messages (`keep` from `options`, else the
-     * conversation's own); when `count <= keep` NOTHING folds and this is a no-op resolving
-     * `undefined`. Otherwise it summarizes the slice into the section, removes those messages
-     * from the live tail, regenerates the rollup (a second `summarize` over all sections), and
-     * resolves the new section. Requires a {@link ConversationSummaryHandler} — THROWS a
-     * {@link import('./errors.js').ConversationError} when none was supplied.
+     * The effective `keep` comes from `options`, else the conversation's own. Regenerating the
+     * rollup runs `summarize` again, over all sections.
      *
      * @remarks
      * When a `sections` cap is set and the fold pushes the section count over it, an overflow
-     * merge step folds the oldest sections into one — if THAT merge's `summarize` call throws,
+     * merge step folds the oldest sections into one — if that merge's `summarize` call throws,
      * the merge is skipped (sections transiently sit at `cap + 1`, no loss) but the rollup still
      * regenerates over the current unmerged sections (never left stale) before the error
      * propagates; the next successful `compact()` self-heals the section count back to `cap`.
@@ -1714,35 +1912,38 @@ export declare interface ConversationInterface {
      */
     compact(options?: CompactOptions): Promise<Section | undefined>;
     /**
-     * Returns a section's full original messages — a pure READ that emits `rehydrate`.
+     * Returns a section's full original messages — a pure read that emits `rehydrate`, empty for
+     * an unknown id and never reinserting.
      *
      * @param id - The {@link Section} `id` to pull back
      * @returns The section's retained original messages (empty when no such section)
      */
     rehydrate(id: string): readonly Message[];
     /**
-     * Searches `content` for a case-insensitive substring across ALL messages — every section's
-     * retained originals plus the live tail.
+     * Searches `content` for a case-insensitive substring across every message — each section's
+     * retained originals, then the live tail.
      *
      * @param query - The substring to match (case-insensitive)
      * @returns The matching messages, sections' originals first then the live tail
      */
     search(query: string): readonly Message[];
     /**
-     * Renders THIS conversation as a self-labeled, fenced PROVENANCE block to pull INTO another
-     * conversation — a pure string (NO model call), framed so a small model reads it as FOREIGN
-     * material, not as part of the live thread.
+     * Renders this conversation as a self-labeled, fenced provenance block to pull into another
+     * conversation — a pure string with no model call: a leading
+     * `[Reference — conversation "<label>" — NOT part of this conversation]` marker, the rollup
+     * `Summary:` when `summary` is not `false` and a rollup exists, and the cherry-picked
+     * excerpts (`- role: content`) when `messages` is supplied. `label` defaults to the `id`.
      *
      * @remarks
      * The block leads with an unmistakable provenance marker
      * (`[Reference — conversation "<label>" — NOT part of this conversation]`), then optionally
-     * the rollup `Summary:` (when `options.summary !== false` AND a rollup exists), then the
+     * the rollup `Summary:` (when `options.summary !== false` and a rollup exists), then the
      * cherry-picked `Relevant messages:` (each `- role: content`) when `options.messages` is
      * supplied. The intended flow is to pull another conversation B into the active conversation
      * A's active workspace: decide relevance from `B.summary`, select the few right turns with
      * `B.search(query)` / `B.rehydrate(id)`, frame them here, then
      * `A.context.workspaces.active?.write(\`conversation:${B.id}.md\`, B.reference({ label, messages }))`.
-     * Keep the excerpts CHERRY-PICKED, never B's whole history — this content enters another
+     * Keep the excerpts cherry-picked, never B's whole history — this content enters another
      * context a small model must read.
      *
      * @param options - The {@link ConversationReferenceOptions} (label / summary / cherry-picked messages)
@@ -1750,17 +1951,18 @@ export declare interface ConversationInterface {
      */
     reference(options?: ConversationReferenceOptions): string;
     /**
-     * Serializes this conversation to a plain, JSON-serializable {@link ConversationSnapshot} — its
-     * `id`, the rollup `summary`, the compacted `sections`, and the live tail (its `messages()`).
+     * Serializes this conversation to a plain, JSON-serializable {@link ConversationSnapshot} —
+     * its `id`, the rollup `summary`, the compacted `sections`, and the live tail; the live
+     * `summarize` / `keep` are configuration re-supplied on hydrate rather than serialized.
      *
      * @remarks
-     * The container serializes ITSELF (`{ id, summary, sections, messages: this.messages() }`) — the
+     * The container serializes itself (`{ id, summary, sections, messages: this.messages() }`) — the
      * {@link ConversationStoreInterface} persistence seam's payload, the exact analogue of
      * {@link import('@orkestrel/workspace').WorkspaceInterface}'s `snapshot`. The summarizer /
-     * `keep` are NOT serialized — they are live
-     * CONFIG re-supplied on hydrate (a `ConversationSummaryHandler` is a function, not data). The snapshot
+     * `keep` are not serialized — they are live
+     * config re-supplied on hydrate (a `ConversationSummaryHandler` is a function, not data). The snapshot
      * is the durable analogue of the `snapshot` option: a {@link ConversationManagerInterface}
-     * HYDRATES a conversation from it through that seam (see {@link ConversationManagerInterface.open}).
+     * hydrates a conversation from it through that seam (see {@link ConversationManagerInterface.open}).
      * Pure — the sections + messages are already plain immutable records (so the snapshot
      * `structuredClone`s / JSON-round-trips losslessly), and snapshotting mutates nothing.
      *
@@ -1770,26 +1972,27 @@ export declare interface ConversationInterface {
 }
 
 /**
- * Registers {@link Conversation}s keyed by `id`, in insertion order, WITH an active pointer
- * — the id-keyed store over the conversation layer PLUS the `active` / `switch` seam the
- * {@link import('../AgentContext.js').AgentContext} renders. Event-free (a registry, like
- * {@link import('@orkestrel/workspace').WorkspaceManager}); the observability lives
- * on each {@link Conversation}.
+ * Registers {@link Conversation}s keyed by `id`, in insertion order, with an active pointer —
+ * the id-keyed store over the conversation layer, the `active` / `switch` seam the
+ * {@link import('../AgentContext.js').AgentContext} renders, and the durable `open` / `save`
+ * store seam. Event-free (a registry, like
+ * {@link import('@orkestrel/workspace').WorkspaceManager}); the observability lives on each
+ * {@link Conversation}.
  *
  * @remarks
  * - **Registry.** Conversations live in an insertion-ordered `Map` keyed by `id`. `add(input?)`
  *   mints a {@link Conversation} (its `id` from `input` or `crypto.randomUUID()`), flowing the
- *   manager's default `#summarize` / `#keep` in unless the `input` OVERRIDES them, and stores
- *   it (an already-present `id` OVERWRITES — last write wins). `count` is the map size,
+ *   manager's default `#summarize` / `#keep` in unless the `input` overrides them, and stores
+ *   it (an already-present `id` overwrites — last write wins). `count` is the map size,
  *   `conversation(id)` looks one up, `conversations()` lists them in insertion order.
  * - **Active pointer.** `active` is the active conversation (the agent's message source the
- *   context renders), `undefined` until the FIRST `add` (which auto-activates it — a registry
+ *   context renders), `undefined` until the first `add` (which auto-activates it — a registry
  *   with conversations always has one active). A subsequent `add` leaves `active` unchanged.
  *   `switch(id)` re-points `active` to the conversation with `id` and returns it; an unknown `id`
  *   returns `undefined` and leaves `active` unchanged (the lenient lookup style — never throws,
  *   no new error code).
- * - **Removal.** `remove` drops one by id, or a batch — `true` only when EVERY supplied id was
- *   removed; removing the ACTIVE conversation sets `active` to `undefined`. `clear` empties the registry
+ * - **Removal.** `remove` drops one by id, or a batch — `true` only when every supplied id was
+ *   removed; removing the active conversation sets `active` to `undefined`. `clear` empties the registry
  *   and sets `active` to `undefined`.
  * - **Event-free.** A purely registry store — no Emitter, no events (each conversation owns
  *   its own observable `emitter`).
@@ -1820,32 +2023,32 @@ export declare class ConversationManager implements ConversationManagerInterface
 }
 
 /**
- * Registers {@link ConversationInterface}s keyed by their `id`, in insertion order, WITH an
- * active pointer — the id-keyed store over the conversation layer PLUS the `active` / `switch` seam the
- * {@link AgentContextInterface} renders. Event-free (a registry, like
- * {@link import('@orkestrel/workspace').WorkspaceManagerInterface}); the observability lives on each
- * {@link ConversationInterface}.
+ * Registers {@link ConversationInterface}s keyed by their `id`, in insertion order, with an active
+ * pointer — the id-keyed store over the conversation layer, the `active` / `switch` seam the {@link
+ * AgentContextInterface} renders, and the durable `open` / `save` store seam. Event-free (a
+ * registry, like {@link import('@orkestrel/workspace').WorkspaceManagerInterface}); the
+ * observability lives on each {@link ConversationInterface}.
  *
  * @remarks
  * - **Registry.** `count` is how many are stored. `add(input?)` mints a
  *   {@link ConversationInterface} (its `id` from `input` or a random UUID), flowing the
  *   manager's default `summarize` / `keep` in unless the `input` overrides them; `add` of an
- *   already-present `id` OVERWRITES it (last write wins). `conversation(id)` looks one up
+ *   already-present `id` overwrites it (last write wins). `conversation(id)` looks one up
  *   (`undefined` when absent); `conversations()` lists them in insertion order.
  * - **Active pointer.** `active` is the active conversation (the agent's message source the
- *   context renders), `undefined` until the FIRST `add` (which auto-activates it — a registry
+ *   context renders), `undefined` until the first `add` (which auto-activates it — a registry
  *   with conversations always has one active). A subsequent `add` leaves `active` unchanged.
  *   `switch(id)` re-points `active` to the conversation with `id` and returns it; an unknown
  *   `id` returns `undefined` and leaves `active` unchanged (the lenient lookup style — never
  *   throws, no new error code).
- * - **Removal.** `remove` drops one by id, or a batch (array overload FIRST) — `true`
- *   only when EVERY supplied id was removed; removing the ACTIVE conversation sets `active` to `undefined`. `clear`
+ * - **Removal.** `remove` drops one by id, or a batch (the array overload declared first) — `true`
+ *   only when every supplied id was removed; removing the active conversation sets `active` to `undefined`. `clear`
  *   empties the registry and sets `active` to `undefined`.
  * - **Durable open / save (the optional `store` seam).** When a {@link ConversationStoreInterface}
- *   is supplied (the `store` option), `open(id)` HYDRATES a conversation from the store on a registry
+ *   is supplied (the `store` option), `open(id)` hydrates a conversation from the store on a registry
  *   miss (rebuilding it through the `snapshot` option, flowing the manager's
- *   default `summarize` / `keep` in) and `save(id)` PERSISTS a registered conversation's
- *   {@link ConversationInterface.snapshot}. Both are LENIENT without a store — `open` resolves only
+ *   default `summarize` / `keep` in) and `save(id)` persists a registered conversation's
+ *   {@link ConversationInterface.snapshot}. Both are lenient without a store — `open` resolves only
  *   registered ids, `save` is a no-op (`false`) — consistent with the lenient `switch`. It mirrors
  *   the workspace package manager's `open` / `save` seam.
  * - **Event-free.** A purely registry store — no Emitter, no events (each conversation owns
@@ -1855,47 +2058,66 @@ export declare interface ConversationManagerInterface {
     readonly count: number;
     /** Holds the active conversation — the agent's message source the context renders; `undefined` until the first `add`. */
     readonly active: ConversationInterface | undefined;
+    /** Looks up one conversation by id (`undefined` when absent). */
     conversation(id: string): ConversationInterface | undefined;
+    /** Lists every conversation, in insertion order. */
     conversations(): readonly ConversationInterface[];
+    /**
+     * Mints a conversation, taking its `id` from the input or a fresh UUID and flowing the
+     * manager's default `summarize` / `keep` in unless the input overrides them — auto-activates
+     * the first, and an already-present `id` overwrites, last write wins.
+     */
     add(input?: ConversationInput): ConversationInterface;
+    /**
+     * Re-points `active` at the conversation with `id` and returns it; an unknown `id` returns
+     * `undefined` and leaves `active` unchanged, never throwing.
+     */
     switch(id: string): ConversationInterface | undefined;
     /**
-     * Resolves a conversation by id, ACTIVATING it — from the registry if present, else HYDRATED from
-     * the optional {@link ConversationStoreInterface} (`store`).
+     * Resolves a conversation by id and activates it — from the registry when present, else
+     * hydrated from the optional {@link ConversationStoreInterface} (`store`); `undefined` when
+     * it is neither registered nor stored.
      *
      * @remarks
-     * - If `id` is ALREADY registered, it is ACTIVATED (`switch`ed to) and returned — no store hit.
-     * - Else if a `store` is set, `store.get(id)` is awaited; on a HIT the snapshot is rehydrated
+     * - If `id` is already registered, it is activated (`switch`ed to) and returned — no store hit.
+     * - Else if a `store` is set, `store.get(id)` is awaited; on a hit the snapshot is rehydrated
      *   into a fresh {@link ConversationInterface} through the `snapshot` option
      *   (`add({ snapshot, ... })`, flowing the manager's default `summarize` / `keep` in), which
-     *   registers AND activates it, and it is returned.
-     * - Else (no store, or a store MISS) ⇒ `undefined` (lenient — no throw).
+     *   registers and activates it, and it is returned.
+     * - Else (no store, or a store miss) ⇒ `undefined` (lenient — no throw).
      *
      * @param id - The conversation id to open
      * @returns The activated {@link ConversationInterface}, or `undefined` when neither registered nor stored
      */
     open(id: string): Promise<ConversationInterface | undefined>;
     /**
-     * Persists a REGISTERED conversation's {@link ConversationInterface.snapshot} to the optional
-     * {@link ConversationStoreInterface} (`store`).
+     * Persists a registered conversation's {@link ConversationInterface.snapshot} to the optional
+     * {@link ConversationStoreInterface} (`store`) — `true` when persisted, `false` when there is
+     * no store or the id is unknown, and never throwing.
      *
      * @remarks
-     * Lenient: when a `store` is set AND `id` is registered, `store.set(conversation.snapshot())` is
-     * awaited and `true` is returned; otherwise (no store, OR an unknown id) it is a NO-OP returning
+     * Lenient: when a `store` is set and `id` is registered, `store.set(conversation.snapshot())` is
+     * awaited and `true` is returned; otherwise (no store, or an unknown id) it is a no-op returning
      * `false` — never a throw, consistent with the lenient `switch`.
      *
      * @param id - The id of the registered conversation to persist
      * @returns True if the snapshot was persisted; false otherwise (no store, or an unknown id)
      */
     save(id: string): Promise<boolean>;
+    /**
+     * Removes one conversation by id, or a batch — `true` only when every supplied id was
+     * removed; clears `active` when a removed conversation was the active one.
+     */
     remove(ids: readonly string[]): boolean;
     remove(id: string): boolean;
+    /** Removes every conversation and clears `active`. */
     clear(): void;
 }
 
 /**
- * Configures `createConversationManager` — the default {@link ConversationSummaryHandler} and
- * retained-tail size the conversations it creates inherit.
+ * Configures `createConversationManager` — the default `ConversationSummaryHandler`, retained-tail
+ * size, and `sections` cap the conversations it creates inherit, plus the optional durable `store`
+ * backing `open` / `save`.
  *
  * @remarks
  * `summarize` is the default summarizer flowed into every conversation the manager `add`s
@@ -1916,8 +2138,8 @@ export declare interface ConversationManagerOptions {
     /**
      * Holds the optional durable {@link ConversationStoreInterface} backing
      * {@link ConversationManagerInterface.open} / {@link ConversationManagerInterface.save} — a memory
-     * / JSON / SQLite / IndexedDB store a conversation is HYDRATED from (`open` a registry-miss) and
-     * PERSISTED to (`save`). Omitted ⇒ the manager is registry-only: `open` resolves only what is
+     * / JSON / SQLite / IndexedDB store a conversation is hydrated from (`open` a registry-miss) and
+     * persisted to (`save`). Omitted ⇒ the manager is registry-only: `open` resolves only what is
      * already registered, and `save` is a no-op (`false`). The exact analogue of
      * {@link import('@orkestrel/workspace').WorkspaceManagerOptions}'s `store`.
      */
@@ -1926,25 +2148,26 @@ export declare interface ConversationManagerOptions {
 
 /**
  * Configures `createConversation` — the optional `id`, the reserved `on` hooks, the
- * provider-agnostic `summarize` seam, and the retained-tail size.
+ * provider-agnostic `summarize` seam, the retained-tail size, an optional cap on the compacted
+ * `sections` list, and a {@link ConversationSnapshot} to hydrate from.
  *
  * @remarks
  * `id` is the conversation's identity (a random UUID when omitted). `on` is the reserved
  * listener key (initial {@link ConversationEventMap} listeners). `summarize` is the
- * {@link ConversationSummaryHandler} compaction needs — ABSENT ⇒ `compact()` throws a
+ * {@link ConversationSummaryHandler} compaction needs — absent ⇒ `compact()` throws a
  * {@link import('./errors.js').ConversationError} (a conversation can still store + view a
  * live tail; it cannot fold). `keep` is how many recent live messages a `compact()`
- * retains VERBATIM (folding only the older ones); it defaults to
+ * retains verbatim (folding only the older ones); it defaults to
  * {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP} (`0` — a manual `compact()`
- * folds the WHOLE current live tail into one section). `sections` is an optional cap on the
+ * folds the whole current live tail into one section). `sections` is an optional cap on the
  * compacted `sections` list — when set (`>= 1`), a `compact()` that would leave more than
- * `sections` sections FOLDS the oldest overflow into ONE merged section so the list never
+ * `sections` sections folds the oldest overflow into one merged section so the list never
  * exceeds `sections`, emitting `collapse`; omitted ⇒ unlimited (the prior behavior).
- * `snapshot` is the HYDRATION seam — a {@link ConversationSnapshot} whose `id`, rollup
- * `summary`, compacted `sections`, and live tail are RESTORED into the new conversation, with
+ * `snapshot` is the hydration seam — a {@link ConversationSnapshot} whose `id`, rollup
+ * `summary`, compacted `sections`, and live tail are restored into the new conversation, with
  * the live `summarize` / `keep` / `on` supplied alongside it (a summarizer is a function, not
- * serialized data). Restoring is SILENT (no events — nothing was edited), and a `snapshot.id`
- * WINS over `id` (the snapshot IS the conversation's identity). It is what lets
+ * serialized data). Restoring is silent (no events — nothing was edited), and a `snapshot.id`
+ * wins over `id` (the snapshot is the conversation's identity). It is what lets
  * `createConversation` hydrate, and what a {@link ConversationManagerInterface.open} reads a
  * stored snapshot back through.
  */
@@ -1953,7 +2176,7 @@ export declare interface ConversationOptions {
     readonly on?: EmitterHooks<ConversationEventMap>;
     /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
-    /** Supplies the summarizer compaction needs; ABSENT ⇒ `compact()` throws a `ConversationError`. */
+    /** Supplies the summarizer compaction needs; absent ⇒ `compact()` throws a `ConversationError`. */
     readonly summarize?: ConversationSummaryHandler;
     /** Keeps this many recent live messages verbatim on `compact`; defaults to `DEFAULT_CONVERSATION_KEEP` (`0`). */
     readonly keep?: number;
@@ -1964,22 +2187,23 @@ export declare interface ConversationOptions {
 }
 
 /**
- * Configures {@link ConversationInterface.reference} — how to render ONE conversation as a
- * self-labeled, fenced PROVENANCE block to pull INTO another conversation (by writing it to
- * the active context's active workspace).
+ * Configures {@link ConversationInterface.reference} — how to render one conversation as a
+ * self-labeled, fenced provenance block to pull into another conversation by writing it to the
+ * active context's active workspace: `label` defaults to the `id`, `summary` defaults to `true`,
+ * and `messages` are cherry-picked excerpts defaulting to none.
  *
  * @remarks
- * The rendered block is a cross-conversation reference a SMALL model must read as foreign
- * material, NOT as part of the live thread — so every member keeps it CONCISE and unmistakably
+ * The rendered block is a cross-conversation reference a small model must read as foreign
+ * material, not as part of the live thread — so every member keeps it concise and unmistakably
  * attributed:
- * - `label` — the human PROVENANCE name shown in the block's leading marker (for example `'planning'`);
+ * - `label` — the human provenance name shown in the block's leading marker (for example `'planning'`);
  *   defaults to the conversation's own `id`. It is what the model attributes the content to.
  * - `summary` — whether to include the conversation's rollup `summary` (its summary-of-summaries)
- *   in the block; defaults to `true` (the rollup is included WHEN one exists — `undefined` until
+ *   in the block; defaults to `true` (the rollup is included when one exists — `undefined` until
  *   the first compaction omits the `Summary:` line). Pass `false` to exclude it.
- * - `messages` — the CHERRY-PICKED excerpts to include (each rendered `role: content`), default
- *   NONE. The intended source is the conversation's OWN `search(query)` / `rehydrate(id)` output
- *   (select the few relevant turns), NOT its whole history — dumping every message defeats the
+ * - `messages` — the cherry-picked excerpts to include (each rendered `role: content`), default
+ *   none. The intended source is the conversation's own `search(query)` / `rehydrate(id)` output
+ *   (select the few relevant turns), not its whole history — dumping every message defeats the
  *   point (it re-bloats the destination context a small model then has to wade through).
  */
 export declare interface ConversationReferenceOptions {
@@ -1998,11 +2222,11 @@ export declare interface ConversationReferenceOptions {
  * {@link import('@orkestrel/workspace').WorkspaceSnapshot}.
  *
  * @remarks
- * Pure JSON DATA (no class instances, no functions): each {@link Section} and
- * {@link Message} is already a PLAIN record that `structuredClone`s / JSON-round-trips
+ * Pure JSON data (no class instances, no functions): each {@link Section} and
+ * {@link Message} is already a plain record that `structuredClone`s / JSON-round-trips
  * losslessly. The snapshot carries the rollup `summary` (a summary-of-summaries; `undefined` until
- * the first compaction), the compacted `sections` (each RETAINING its folded originals), and the
- * live uncompacted tail `messages` — but NOT the `summarize` / `keep`, which are live CONFIG
+ * the first compaction), the compacted `sections` (each retaining its folded originals), and the
+ * live uncompacted tail `messages` — but not the `summarize` / `keep`, which are live config
  * re-supplied on hydrate (a summarizer is a function, not serializable data). The snapshot the
  * container produces from itself ({@link ConversationInterface.snapshot}); the durable analogue of
  * the {@link ConversationOptions.snapshot} hydration seam. A {@link ConversationManagerInterface}
@@ -2014,23 +2238,24 @@ export declare interface ConversationSnapshot {
     readonly id: string;
     /** Holds the rollup (a summary-of-summaries); `undefined` until the first compaction. */
     readonly summary?: string;
-    /** Lists the compacted history, oldest → newest (each section RETAINS its folded originals). */
+    /** Lists the compacted history, oldest → newest (each section retains its folded originals). */
     readonly sections: readonly Section[];
     /** Lists the live uncompacted tail, in insertion order. */
     readonly messages: readonly Message[];
 }
 
 /**
- * Represents one row of the table a
- * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
- * persists — a conversation `id` plus its {@link ConversationSnapshot} held as ONE OPAQUE JSON
- * column. The exact analogue of {@link import('@orkestrel/workspace').WorkspaceSnapshotRow}.
+ * Represents one row of the table a {@link
+ * import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore} persists
+ * — a conversation `id` plus its {@link ConversationSnapshot} held as one opaque JSON column, read
+ * back as `unknown` and narrowed on `get`. The exact analogue of {@link
+ * import('@orkestrel/workspace').WorkspaceSnapshotRow}.
  *
  * @remarks
  * The Database twin of {@link ConversationStoreInterface} stores the snapshot whole (the `snapshot`
  * column is a `rawShape`, an opaque JSON blob — exactly as
  * {@link import('@orkestrel/workspace').WorkspaceSnapshotRow} stores a workspace snapshot), so the
- * row type stays FLAT and the sections/messages snapshot shape never
+ * row type stays flat and the sections/messages snapshot shape never
  * forces the contract to `Infer` it. The column therefore reads back as the broad `unknown`; the
  * store narrows it to a {@link ConversationSnapshot} on `get`
  * ({@link import('./validators.js').isConversationSnapshot}, the total boundary guard). `id`
@@ -2044,30 +2269,30 @@ export declare interface ConversationSnapshotRow {
 }
 
 /**
- * Persists a {@link ConversationSnapshot} durably — three async primitives
- * (`get` / `set` / `delete`) keyed by a conversation id, the exact analogue of
- * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}.
+ * Persists a {@link ConversationSnapshot} durably — the async `get` / `set` / `delete` primitives,
+ * keyed by a conversation id and holding no expiry, the exact analogue of {@link
+ * import('@orkestrel/workspace').WorkspaceStoreInterface}.
  *
  * @remarks
  * The store persists the {@link ConversationSnapshot} — the self-contained, pure-JSON conversation
- * state — so a JSON / SQLite / IndexedDB backend swaps in WITHOUT touching the manager or the
+ * state — so a JSON / SQLite / IndexedDB backend swaps in without touching the manager or the
  * conversation: the in-memory default
  * {@link import('./conversations/stores/MemoryConversationStore.js').MemoryConversationStore} and its
  * driver-pluggable twin
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore} (the
- * snapshot as one opaque JSON column) share THIS one interface. Hydration is NOT a store concern
+ * snapshot as one opaque JSON column) share this one interface. Hydration is not a store concern
  * — a {@link ConversationManagerInterface} reads a snapshot back and rebuilds the live conversation
  * through the {@link ConversationOptions.snapshot} seam (re-supplying the live `summarize` / `keep`; see
  * {@link ConversationManagerInterface.open} / {@link ConversationManagerInterface.save}).
  *
  * Every primitive is async (a `Promise`), so a durable backend (a database round-trip) fits the
- * same shape as the memory one. The snapshot carries its OWN id, so `set` takes no separate id
+ * same shape as the memory one. The snapshot carries its own id, so `set` takes no separate id
  * param (mirroring
- * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`). UNLIKE a session store
- * there is NO idle-TTL
+ * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`). Unlike a session store
+ * there is no idle-TTL
  * / eviction — a persisted conversation lives until an explicit `delete`. It is concrete over
  * {@link ConversationSnapshot} — no generic parameter, because the
- * snapshot is the ONE payload a conversation store persists.
+ * snapshot is the one payload a conversation store persists.
  */
 export declare interface ConversationStoreInterface {
     /**
@@ -2093,10 +2318,10 @@ export declare interface ConversationStoreInterface {
 }
 
 /**
- * Summarizes a conversation, provider-agnostically — the seam the agent RUNTIME supplies so
- * core never imports a provider. Given the folded messages, it resolves their digest (the
- * model-written summary), used both to summarize a compacted {@link Section} and
- * to regenerate a {@link ConversationInterface}'s rollup `summary`.
+ * Summarizes a conversation, provider-agnostically — the seam the agent runtime supplies so core
+ * never imports a provider. Given the folded messages, it resolves their digest, the model-written
+ * summary used to summarize a compacted {@link Section} and to regenerate a {@link
+ * ConversationInterface}'s rollup `summary`.
  *
  * @remarks
  * The agent runtime builds one from its `ProviderInterface` (for example
@@ -2117,10 +2342,10 @@ export declare type ConversationSummaryHandler = (messages: readonly Message[])
  * `generate` and a live `stream`.
  *
  * @remarks
- * One private loop drives the turn; `generate` DRAINS the same stream `stream`
+ * One private loop drives the turn; `generate` drains the same stream `stream`
  * exposes, so they can never diverge. Each turn is bounded by one cancel folded from
  * `signal` + `timeout` + `budget` (through `AbortSignal.any`) — any trip (or `abort()`)
- * commits a PARTIAL result (the stream's `result` RESOLVES on a cancel, rejects only
+ * commits a partial result (the stream's `result` resolves on a cancel, rejects only
  * on a genuine provider / tool error). The `scheduler` paces between turns; tool
  * iteration is capped at `limit` (default `DEFAULT_AGENT_LIMIT`). Tools are advertised
  * structurally through `context.tools.definitions()`. Two observation surfaces: the
@@ -2155,19 +2380,20 @@ export declare type ConversationSummaryHandler = (messages: readonly Message[])
 export declare function createAgent(provider: ProviderInterface, options?: AgentOptions): AgentInterface;
 
 /**
- * Creates a richer turn context — an {@link AgentContextInterface} assembling a provider
- * request from the optional system prompt, the instruction registry, the workspace registry,
- * the conversation store, the tool registry, and the active scope.
+ * Creates a richer turn context — an {@link AgentContextInterface} assembling a provider request
+ * from the optional system prompt, the instruction registry, the workspace registry (the only
+ * document channel), the conversation registry that is its `messages` source, the tool registry,
+ * and the active scope, which `build()` folds into the next turn's input.
  *
  * @remarks
  * `system` is the optional system prompt; `tools` / `instructions` / `workspaces` are pre-built
- * managers to reuse (empty ones are created when omitted, so `context.workspaces` is ALWAYS
+ * managers to reuse (empty ones are created when omitted, so `context.workspaces` is always
  * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, changeable afterwards
  * through `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
- * instructions — PLUS the ACTIVE workspace's scope-filtered text files (fenced) — into ONE leading
+ * instructions — plus the active workspace's scope-filtered text files (fenced) — into one leading
  * `system` message and appends the scoped conversation (attaching the active workspace's
  * scope-filtered image files' `base64` payload to the last user message), built fresh each call; the active
- * workspace is the SOLE document/image context. Tools are advertised STRUCTURALLY (through
+ * workspace is the sole document/image context. Tools are advertised structurally (through
  * `tools.definitions()`, scope-filtered by the loop), never serialized into the prompt.
  *
  * @param options - Optional `system` / `tools` / `instructions` / `workspaces` / `scope`
@@ -2188,7 +2414,7 @@ export declare function createAgentContext(options?: AgentContextOptions): Agent
 
 /**
  * Creates a durable, bounded-concurrency agent-job queue — a {@link QueueInterface} over
- * serializable {@link AgentJobInput}s that COMPOSES `createQueue`: each job is rehydrated
+ * serializable {@link AgentJobInput}s that composes `createQueue`: each job is rehydrated
  * through the `registry` into a live {@link AgentInterface}, run to its {@link AgentResult},
  * and subjected to the partial-as-configurable-failure policy.
  *
@@ -2201,9 +2427,9 @@ export declare function createAgentContext(options?: AgentContextOptions): Agent
  *   (for example `createMemoryQueueStore` / `createDatabaseQueueStore`) persists outstanding
  *   jobs; `restore()` re-enqueues them after a restart and the `registry` rehydrates the
  *   live pieces from the names — so a job survives a crash.
- * - **Partial policy.** A partial result THROWS an
+ * - **Partial policy.** A partial result throws an
  *   {@link import('./errors.js').AgentJobError} by default, so a job cancelled by its
- *   attempt deadline / a queue abort RETRIES while attempts remain; `partial: true`
+ *   attempt deadline / a queue abort retries while attempts remain; `partial: true`
  *   resolves the partial as success instead.
  * - **Cancellation threads through.** The handler passes `context.signal` into
  *   `registry.build`, so a queue `abort()` or a per-attempt timeout cancels the in-flight
@@ -2234,7 +2460,7 @@ export declare function createAgentQueue(options: AgentQueueOptions): QueueInter
  *
  * @remarks
  * `providers` is required; `tools` / `authorities` / `schedulers` are optional pools.
- * The accessors (`provider` / `tool` / `authority` / `scheduler`) THROW an
+ * The accessors (`provider` / `tool` / `authority` / `scheduler`) throw an
  * {@link import('./errors.js').AgentError} carrying `code: 'REGISTRY'` and the message
  * `unknown <category>: <name>` on an unregistered name — a misconfigured or crash-restored
  * job fails loudly rather than running with a missing dependency. `build(input, signal)`
@@ -2263,21 +2489,21 @@ export declare function createAgentRegistry(options: AgentRegistryOptions): Agen
 
 /**
  * Creates an agent-job runner — a {@link RunnerInterface} over serializable
- * {@link AgentJobInput}s that COMPOSES `createRunner` (one-shot, ordered, fail-fast), each
- * unit rehydrated through the `registry` and subjected to the partial policy. The runner
- * enables **sub-agent fan-out**: a parent job's handler can `controller.spawn(childJob)`.
+ * {@link AgentJobInput}s that composes `createRunner` (one-shot, ordered, fail-fast), each unit
+ * rehydrated through the `registry` and subjected to the partial policy. The runner also carries
+ * sub-agent fan-out: a parent job's handler can `controller.spawn(childJob)`.
  *
  * @remarks
  * - **Composes the substrate (no new engine).** Bounded `concurrency`, `retries`, the
  *   per-attempt `timeout`, ordered results, and fail-fast are all the backing Runner's;
  *   the handler adds only rehydration + the partial policy.
  * - **Sub-agent fan-out.** Each unit's handler receives a `ControllerInterface` whose
- *   `spawn(childJob)` launches a CHILD agent job through the same bounded queue (the
+ *   `spawn(childJob)` launches a child agent job through the same bounded queue (the
  *   child's result joins the run after the declared units, in spawn order). On a bounded
- *   runner, FAN OUT and return — do NOT inline-`await` a spawn from within the handler (a
+ *   runner, fan out and return — do not inline-`await` a spawn from within the handler (a
  *   slot-holding handler awaiting its own spawn can deadlock; see `ControllerInterface`).
  * - **Partial policy + cancellation.** Same as `createAgentQueue`: a partial result
- *   THROWS by default (the run's fail-fast engages), `partial: true` resolves it; the
+ *   throws by default (the run's fail-fast engages), `partial: true` resolves it; the
  *   handler threads `controller.signal` into `registry.build`, so a runner abort / a
  *   per-attempt timeout cancels the agent.
  *
@@ -2305,11 +2531,11 @@ export declare function createAgentRunner(options: AgentRunnerOptions): RunnerIn
  * to the configured default when none match.
  *
  * @remarks
- * `rules` are evaluated in order — the FIRST whose `match` is true decides (a matched
- * rule ALLOWS unless its `allowed` is explicitly `false`). When no rule matches, the
+ * `rules` are evaluated in order — the first whose `match` is true decides (a matched
+ * rule allows unless its `allowed` is explicitly `false`). When no rule matches, the
  * `fallback` decides; it defaults to `{ zone: DEFAULT_AUTHORITY_ZONE, allowed: true }`
- * (allow-unmatched — a rules list of denials acts as a DENYLIST). Pass an
- * `allowed: false` `fallback` to flip the gate to deny-by-default (an ALLOWLIST). Wire
+ * (allow-unmatched — a rules list of denials acts as a denylist). Pass an
+ * `allowed: false` `fallback` to flip the gate to deny-by-default (an allowlist). Wire
  * the result into `createAgent` through `AgentOptions.authority`: a denied call is fed back
  * to the model as a denial `ToolResult` (not executed, no budget cost), so the model
  * can react. Synchronous — `evaluate` returns the verdict directly.
@@ -2339,7 +2565,7 @@ export declare function createAuthority(options?: AuthorityOptions): AuthorityIn
  * Write and read are decoupled, so the producer never waits for a consumer: an agent's eager
  * pump writes each chunk into one, which is why a run's `result` settles whether or not the
  * live events are drained. A value pushed at an already-parked consumer is delivered, buffered
- * values are yielded before the end is reported, and the FIRST failure wins.
+ * values are yielded before the end is reported, and the first failure wins.
  *
  * @typeParam T - The value type the channel carries
  * @returns A fresh, empty {@link ChannelInterface}
@@ -2360,16 +2586,16 @@ export declare function createChannel<T>(): ChannelInterface<T>;
 
 /**
  * Creates a conversation — a {@link ConversationInterface} grouping messages above a flat
- * message store it OWNS DIRECTLY, with compaction into summarized sections, a regenerated
+ * message store it owns directly, with compaction into summarized sections, a regenerated
  * rollup `summary`, on-demand `rehydrate`, and substring `search`, driven by a
  * provider-agnostic {@link ConversationSummaryHandler} seam.
  *
  * @remarks
  * Append turns through the conversation's own `add` (the live tail it owns); `view()` is the model input
  * (each section as a summary message, then the live tail). `compact()` folds the older live
- * messages into a summarized {@link Section} and regenerates the rollup — it REQUIRES
+ * messages into a summarized {@link Section} and regenerates the rollup — it requires
  * a `summarize` (omitted ⇒ `compact()` throws a `ConversationError`); `keep` retains a recent
- * tail (default `DEFAULT_CONVERSATION_KEEP` — fold ALL). `rehydrate(id)` / `search(query)` read
+ * tail (default `DEFAULT_CONVERSATION_KEEP` — fold all). `rehydrate(id)` / `search(query)` read
  * the retained originals. Observable (`emitter` — `compact` / `summary` / `rehydrate`), wired
  * through the reserved `on` option; the emitter isolates a listener throw and routes it to
  * its `error` handler (the `error` option), so it can never corrupt a compaction.
@@ -2377,41 +2603,61 @@ export declare function createChannel<T>(): ChannelInterface<T>;
  * @param options - Optional `id` / `on` hooks + the `summarize` seam + `keep` (see {@link ConversationOptions})
  * @returns A working {@link ConversationInterface}
  *
- * @example
+ * @example Conversations & compaction
  * ```ts
  * import type { ProviderInterface } from '@orkestrel/agent'
  * import { createConversation } from '@orkestrel/agent'
  *
  * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+ * // The summarizer seam — built from the provider by the runtime; core stays provider-agnostic.
+ * // Append the instruction as the FINAL user turn: a chat model emits nothing when the prompt
+ * // ends on an assistant turn, so a leading-system instruction is unreliable.
  * const conversation = createConversation({
- * 	// Append the instruction as the FINAL user turn — a chat model emits nothing when the
- * 	// prompt ends on an assistant turn, so a leading-system instruction is unreliable.
  * 	summarize: async (messages) =>
- * 		(await provider.generate([...messages, { id: 's', role: 'user', content: 'Summarize the conversation so far concisely.' }], AbortSignal.timeout(30_000))).content,
+ * 		(
+ * 			await provider.generate(
+ * 				[
+ * 					...messages,
+ * 					{ id: 's', role: 'user', content: 'Summarize the conversation so far concisely.' },
+ * 				],
+ * 				AbortSignal.timeout(30_000),
+ * 			)
+ * 		).content,
+ * 	keep: 2, // retain the two most recent turns verbatim on each compaction
  * })
- * conversation.add({ role: 'user', content: 'Hello' })
- * await conversation.compact() // folds the live tail into a summarized section
+ * conversation.add([
+ * 	{ role: 'user', content: 'My name is Ada.' },
+ * 	{ role: 'assistant', content: 'Nice to meet you, Ada.' },
+ * 	{ role: 'user', content: 'What did I say my name was?' },
+ * ])
+ *
+ * const section = await conversation.compact() // folds the older turns → a summarized section
+ * conversation.view() // [<section summary message>, ...the retained recent tail] — the model input
+ * conversation.summary // the regenerated rollup (a summary-of-summaries over all sections)
+ * conversation.search('ada') // case-insensitive across sections' originals + the live tail
+ * section && conversation.rehydrate(section.id) // the section's full original messages (a pure read)
  * ```
  */
 export declare function createConversation(options?: ConversationOptions): ConversationInterface;
 
 /**
  * Creates a conversation registry — a {@link ConversationManagerInterface} holding
- * {@link ConversationInterface}s keyed by their `id` (in insertion order) WITH an active pointer:
+ * {@link ConversationInterface}s keyed by their `id`, in insertion order, with an active pointer:
  * the id-keyed store over the conversation layer plus the `active` / `switch` seam the context
- * renders.
+ * renders. `add` auto-activates the first conversation and flows the registry's default
+ * `summarize` / `keep` into every conversation it creates.
  *
  * @remarks
  * Starts empty; `add(input?)` mints a {@link ConversationInterface} (its `id` from the input
  * or a random UUID), flowing the manager's default `summarize` / `keep` in unless the input
  * overrides them, and stores it (an already-present `id` overwrites — last write wins) — and
- * AUTO-ACTIVATES the FIRST one (a registry with conversations always has one `active`); a later
+ * auto-activates the first one (a registry with conversations always has one `active`); a later
  * `add` leaves `active` unchanged. `switch(id)` re-points `active` (an unknown `id` returns
  * `undefined`, leaving `active` unchanged — lenient, never throws); `conversation(id)` /
  * `conversations()` look up; `remove` (one or a batch) reports `true` only when every supplied id
- * was removed AND clears `active` if it was a removed one; `clear` empties it and clears `active`.
+ * was removed and clears `active` if it was a removed one; `clear` empties it and clears `active`.
  * Event-free
- * (each conversation owns its own observable `emitter`). A conversation created with NEITHER a
+ * (each conversation owns its own observable `emitter`). A conversation created with neither a
  * manager default nor a per-`add` `summarize` cannot `compact` (it throws a `ConversationError`).
  *
  * @param options - Optional default `summarize` / `keep` (see {@link ConversationManagerOptions})
@@ -2429,23 +2675,24 @@ export declare function createConversation(options?: ConversationOptions): Conve
 export declare function createConversationManager(options?: ConversationManagerOptions): ConversationManagerInterface;
 
 /**
- * Creates a {@link DatabaseConversationStore} over any {@link DriverInterface} — the durable,
- * driver-pluggable backing for the conversation persistence seam, the opt-in twin of
+ * Creates a {@link DatabaseConversationStore} over any {@link DriverInterface}, defaulting to
+ * `createMemoryDriver()` — the durable, driver-pluggable backing for the conversation persistence
+ * seam, holding each snapshot as one opaque JSON column and standing as the opt-in twin of
  * {@link createMemoryConversationStore}. The exact twin of
  * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore}.
  *
  * @remarks
  * Builds a one-table database (`conversations`, keyed by `id`) over the supplied driver, the snapshot
- * held as ONE OPAQUE JSON COLUMN — the column map is `{ id; snapshot }` where `snapshot` is a
+ * held as one opaque JSON column — the column map is `{ id; snapshot }` where `snapshot` is a
  * `rawShape` (a JSON blob), exactly as
  * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore} stores its snapshot. The
- * snapshot is already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is lossless
- * AND keeps the row type FLAT (the column reads back as `unknown`, narrowed on `get` by
- * {@link import('./validators.js').isConversationSnapshot}). The `driver` DEFAULTS to
- * {@link createMemoryDriver}, so the store ALSO works in memory out of the box; pass a server
+ * snapshot is already a complete, self-contained, pure-JSON payload, so storing it whole is lossless
+ * and keeps the row type flat (the column reads back as `unknown`, narrowed on `get` by
+ * {@link import('./validators.js').isConversationSnapshot}). The `driver` defaults to
+ * {@link createMemoryDriver}, so the store also works in memory out of the box; pass a server
  * `createJSONDriver` / `createSQLiteDriver` (or a browser IndexedDB driver) for a persistent one —
  * the durability is the driver's job, the store engine is shared. It swaps in behind
- * {@link ConversationStoreInterface} WITHOUT touching the manager or the conversation.
+ * {@link ConversationStoreInterface} without touching the manager or the conversation.
  *
  * @param driver - The storage backend the snapshots persist to (defaults to {@link createMemoryDriver})
  * @returns A {@link ConversationStoreInterface} over the driver
@@ -2491,7 +2738,7 @@ export declare function createInstruction(input: InstructionInput): InstructionI
  * immutable instructions keyed by `name`, listed by descending `priority`.
  *
  * @remarks
- * Starts empty; `add` (one or a batch) MINTS each `id` and OVERWRITES a same-name
+ * Starts empty; `add` (one or a batch) mints each `id` and overwrites a same-name
  * instruction (last write wins); `instructions()` lists them sorted by descending
  * `priority` (stable for ties); `open` / `render` are the build contract a richer
  * context renders an instructions block with; `remove` (one or a batch) reports `true` only
@@ -2519,7 +2766,7 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
 /**
  * Creates the in-memory conversation store — a {@link ConversationStoreInterface} backed by a
  * process-lifetime `Map` of {@link import('./types.js').ConversationSnapshot}s keyed by conversation
- * id, the DEFAULT backing for the durable {@link ConversationManagerInterface.open} /
+ * id, the default backing for the durable {@link ConversationManagerInterface.open} /
  * {@link ConversationManagerInterface.save} seam. The exact twin of
  * {@link import('@orkestrel/workspace').createMemoryWorkspaceStore}.
  *
@@ -2527,10 +2774,10 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
  * A plain `Map` (the snapshot is already pure JSON, so no encoding is needed for the memory tier),
  * the structural twin of {@link import('@orkestrel/workspace').createMemoryWorkspaceStore}.
  * `get` / `set` / `delete` are async (the
- * same shape a durable backend fits); UNLIKE a session store there is NO idle-TTL / eviction — a
+ * same shape a durable backend fits); unlike a session store there is no idle-TTL / eviction — a
  * persisted conversation lives until an explicit `delete`. Its driver-pluggable twin is
  * {@link createDatabaseConversationStore} (the snapshot as one opaque JSON column over a `databases`
- * table) — for a DURABLE store pass it a JSON / SQLite / IndexedDB driver, and it swaps in WITHOUT
+ * table) — for a durable store pass it a JSON / SQLite / IndexedDB driver, and it swaps in without
  * touching the manager or the conversation. Hydration stays a manager concern: read a snapshot back
  * and rebuild the live conversation through the `snapshot` option (re-supplying the live
  * `summarize` / `keep`).
@@ -2550,14 +2797,85 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
  */
 export declare function createMemoryConversationStore(): ConversationStoreInterface;
 
+/**
+ * Creates an authorized relay handler that validates a bounded JSON request before streaming.
+ *
+ * @remarks
+ * Answers with the `401` status when authorization refuses or throws, the `400`
+ * status when the body is missing, unreadable, or invalid, the `413` status when
+ * the body fills its byte budget or the inbound read is aborted, and the `502`
+ * status when the upstream provider call cannot be constructed. Refusals carry no body.
+ *
+ * @param options - The upstream provider, authorization decision, and optional byte budget
+ * @returns A fetch-standard handler suitable for a router
+ * @example Mounting the relay on your server
+ * ```ts
+ * import type { ProviderInterface } from '@orkestrel/agent'
+ * import { createRelay } from '@orkestrel/agent'
+ * import { createDispatcher } from '@orkestrel/router'
+ * import { createServer } from '@orkestrel/server'
+ *
+ * declare const upstream: ProviderInterface // the server-side provider holding the credential
+ * declare const bearer: string
+ *
+ * const handler = createRelay({
+ * 	provider: upstream,
+ * 	authorize: (request) => request.headers.get('authorization') === `Bearer ${bearer}`,
+ * })
+ * const dispatcher = createDispatcher({
+ * 	routes: [{ method: 'POST', path: '/relay', handler }],
+ * })
+ *
+ * export function serve(request: Request): Promise<Response> {
+ * 	return dispatcher.handle(request, undefined)
+ * }
+ *
+ * const server = createServer({ dispatcher, state: () => undefined })
+ * await server.start()
+ * process.on('SIGTERM', () => server.stop()) // signal cancellation, drain, then close the listener
+ * ```
+ */
+export declare function createRelay(options: RelayOptions): RelayHandler;
+
+/**
+ * Creates a provider that carries calls through a relay endpoint.
+ *
+ * @remarks
+ * This is the browser end alone. {@link createRelay} mounts the server end, and its example
+ * is the server half this one pairs with.
+ *
+ * @param options - The endpoint, parser factory, and HTTP call configuration
+ * @returns The concrete relay provider
+ * @example Reaching the relay from the browser
+ * ```ts
+ * import type { ProviderInterface } from '@orkestrel/agent'
+ * import { createRelayProvider } from '@orkestrel/agent'
+ * import { createAbort } from '@orkestrel/abort'
+ * // The browser application supplies this parser dependency.
+ * import { createNDJSONParser } from '@orkestrel/ndjson'
+ *
+ * declare const bearer: string
+ * const abort = createAbort()
+ * const messages = [{ id: '1', role: 'user', content: 'Say hello.' }] as const
+ *
+ * const browser: ProviderInterface = createRelayProvider({
+ * 	url: 'https://app.example/relay',
+ * 	parser: createNDJSONParser,
+ * 	headers: () => ({ authorization: `Bearer ${bearer}` }),
+ * })
+ * const result = await browser.generate(messages, abort.signal) // a ProviderResult like a local provider's
+ * ```
+ */
+export declare function createRelayProvider(options: RelayProviderOptions): RelayProvider;
+
 /**
  * Creates a named scope — an immutable {@link ScopeInterface} from its `name` and its
  * per-category allow-lists, the `id` minted at construction.
  *
  * @remarks
- * Each list is THREE-WAY: `undefined` ⇒ NO constraint on that category (all pass), `[]` ⇒
- * NONE pass, a non-empty list ⇒ only the listed keys pass. `narrow(config)` composes a
- * tighter child by set-INTERSECTION (an `undefined` side imposing no constraint). Stored
+ * Each list is three-way: `undefined` ⇒ no constraint on that category (all pass), `[]` ⇒
+ * none pass, a non-empty list ⇒ only the listed keys pass. `narrow(config)` composes a
+ * tighter child by set-intersection (an `undefined` side imposing no constraint). Stored
  * immutable — never mutated after creation (`narrow` returns a new scope).
  *
  * @param input - `name` (required) and the optional `instructions` / `tools` / `files`
@@ -2601,18 +2919,19 @@ export declare function createScope(input: ScopeInput): ScopeInterface;
 export declare function createScopeManager(options?: ScopeManagerOptions): ScopeManagerInterface;
 
 /**
- * Creates a stream-stateful `<think>` separator — a {@link ThinkSplitterInterface} that
- * splits a thinking model's in-content `<think>…</think>` reasoning spans away from
- * the answer, delta by delta, so a provider yields ONLY clean content and surfaces the
- * accumulated reasoning as {@link import('./types.js').ProviderResult.thinking}.
+ * Creates a fresh stream-stateful `<think>` separator — a {@link ThinkSplitterInterface} that
+ * splits a thinking model's in-content `<think>…</think>` reasoning spans away from the answer,
+ * delta by delta, so a provider yields clean content alone and surfaces the accumulated
+ * reasoning as {@link import('./types.js').ProviderResult.thinking}. One splitter serves one
+ * stream.
  *
  * @remarks
  * Feed each raw wire delta through `split(delta)` (it returns the clean content to
  * surface — possibly `''` mid-think) and settle the stream end with `flush()` (a held
- * partial open tag that never completed returns as final content; an UNCLOSED think
- * span lands on `thinking`). Tags split ACROSS deltas are held back until
+ * partial open tag that never completed returns as final content; an unclosed think
+ * span lands on `thinking`). Tags split across deltas are held back until
  * disambiguated, multiple spans accumulate in order, and a nested-looking `<think>`
- * inside an open span is thinking text. One splitter serves ONE stream — create
+ * inside an open span is thinking text. One splitter serves one stream — create
  * a fresh one per provider call.
  *
  * @returns A fresh {@link ThinkSplitterInterface} (state empty, outside any span)
@@ -2631,37 +2950,39 @@ export declare function createThinkSplitter(): ThinkSplitterInterface;
 
 /**
  * Backs a {@link ConversationStoreInterface} with one table of the `databases` layer — a
- * conversation's durable state IS a row, so persistence reduces to keyed point-access (`get` / `set`
- * / `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
- * {@link import('./MemoryConversationStore.js').MemoryConversationStore}. The EXACT twin of
+ * conversation's durable state is a row holding the snapshot as one opaque JSON column, narrowed
+ * back on `get` by {@link import('../../validators.js').isConversationSnapshot}, so persistence
+ * reduces to keyed point-access (`get` / `set` / `delete`) over a {@link TableInterface}. The
+ * driver-pluggable twin of the plain-`Map`
+ * {@link import('./MemoryConversationStore.js').MemoryConversationStore}, and the exact twin of
  * {@link import('@orkestrel/workspace').DatabaseWorkspaceStore}.
  *
  * @remarks
  * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
  * JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
- * IndexedDB backend swaps in WITHOUT touching the
+ * IndexedDB backend swaps in without touching the
  * {@link import('../ConversationManager.js').ConversationManager} or the
  * {@link import('../Conversation.js').Conversation} — the same seam as
  * {@link import('@orkestrel/workspace').DatabaseWorkspaceStore}. The
  * driver defaults to memory ({@link import('../../factories.js').createDatabaseConversationStore}
- * passes `createMemoryDriver()`), so it ALSO works in memory out of the box; you opt into the
+ * passes `createMemoryDriver()`), so it also works in memory out of the box; you opt into the
  * durable plumbing by passing a JSON / SQLite / IndexedDB driver.
  *
- * The {@link ConversationSnapshot} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+ * The {@link ConversationSnapshot} is stored as one opaque JSON column — the table is a row of
  * `{ id; snapshot }` ({@link ConversationSnapshotRow}), the snapshot the whole JSON blob (a
  * `rawShape` column the factory builds) — exactly as `DatabaseWorkspaceStore` stores its snapshot.
- * The snapshot is already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is
- * lossless AND keeps the row type flat (`snapshot` reads back as `unknown`).
+ * The snapshot is already a complete, self-contained, pure-JSON payload, so storing it whole is
+ * lossless and keeps the row type flat (`snapshot` reads back as `unknown`).
  *
- * - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
+ * - **`set(snapshot)` upserts under the snapshot's own `id`** (no separate id param) — it writes
  *   the row `{ id: snapshot.id, snapshot }`.
  * - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
  *   a {@link ConversationSnapshot} ({@link import('../../validators.js').isConversationSnapshot} — the
  *   total guard for an untrusted storage read), or `undefined` if none is stored.
  * - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
  *
- * UNLIKE a session store there is NO idle-TTL / eviction — a persisted conversation lives until an
- * explicit `delete`. The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the
+ * Unlike a session store there is no idle-TTL / eviction — a persisted conversation lives until an
+ * explicit `delete`. The public surface is exactly `get` / `set` / `delete` — no extra members (the
  * method bijection with {@link ConversationStoreInterface}). Hydration stays a caller concern: a
  * {@link import('../ConversationManager.js').ConversationManager} reads a snapshot back and rebuilds
  * the live conversation through the `snapshot` option (its `open` / `save`).
@@ -2690,39 +3011,51 @@ export declare class DatabaseConversationStore implements ConversationStoreInter
     constructor(table: TableInterface<ConversationSnapshotRow>);
     /** Resolves the persisted snapshot for `id`, narrowing the opaque JSON column back to a `ConversationSnapshot`. */
     get(id: string): Promise<ConversationSnapshot | undefined>;
-    /** Inserts or replaces under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
+    /** Inserts or replaces under the snapshot's own `id` (no separate id param) — the row is `{ id, snapshot }`. */
     set(snapshot: ConversationSnapshot): Promise<void>;
     /** Drops a snapshot by id; an absent id is a no-op (no throw). */
     delete(id: string): Promise<void>;
 }
 
 /**
- * Caps an {@link AgentInterface} turn's tool iterations by default — the maximum
- * number of context → provider → tools cycles before the loop stops, so a model that
- * keeps requesting tools can never loop forever. Overridable per agent through
- * `AgentOptions.limit`.
+ * Caps an {@link AgentInterface} turn's tool iterations by default — `10` context → provider →
+ * tools cycles before the loop stops, so a model that keeps requesting tools can never loop
+ * forever. Overridable per agent through `AgentOptions.limit`.
  */
 export declare const DEFAULT_AGENT_LIMIT = 10;
 
 /**
  * Names the zone an {@link AuthorityInterface}'s default fallback {@link AuthorityDecision}
- * carries — the classification for a tool call that matched no rule. Paired with the
- * default `allowed: true` fallback, an unmatched call is allowed under this zone, so a
- * rules list of denials acts as a denylist; a caller wanting deny-by-default supplies
- * an `allowed: false` `fallback` of their own (see `AuthorityOptions`).
+ * carries — `'default'`, the classification for a tool call that matched no rule. Paired with
+ * the default `allowed: true` fallback, an unmatched call is allowed under this zone, so a
+ * rules list of denials acts as a denylist; a caller wanting deny-by-default supplies an
+ * `allowed: false` `fallback` of their own (see `AuthorityOptions`).
  */
 export declare const DEFAULT_AUTHORITY_ZONE = "default";
 
 /**
  * Sets the default number of recent live messages a {@link ConversationInterface}'s `compact()`
- * RETAINS verbatim — `0`, so a manual `compact()` folds ALL of the current live messages
- * into one summarized section (no tail kept). A caller retains a recent tail by passing
- * `keep` (on {@link ConversationOptions}, {@link ConversationManagerOptions}, or per-fold
- * through {@link CompactOptions}), folding only the older `count - keep` messages and leaving
- * the most recent `keep` live for the next turn. Overridable everywhere `keep` is accepted.
+ * retains verbatim — `0`, so a manual `compact()` folds every current live message into one
+ * summarized section and keeps no tail. A caller retains a recent tail by passing `keep` (on
+ * {@link ConversationOptions}, {@link ConversationManagerOptions}, or per-fold through
+ * {@link CompactOptions}), folding only the older `count - keep` messages and leaving the most
+ * recent `keep` live for the next turn. Overridable everywhere `keep` is accepted.
  */
 export declare const DEFAULT_CONVERSATION_KEEP = 0;
 
+/**
+ * Holds the default provider deadline in milliseconds — `120_000`, the wall-clock bound a call
+ * runs under when `AgentProviderInput.timeout` is omitted, folded with the caller's signal so
+ * whichever trips first cancels the call.
+ */
+export declare const DEFAULT_PROVIDER_TIMEOUT = 120000;
+
+/**
+ * Holds the default relay request limit in bytes — `1_048_576`, the byte budget a relay applies
+ * to an inbound body when `RelayOptions.limit` is omitted, refusing a body that reaches it.
+ */
+export declare const DEFAULT_RELAY_LIMIT = 1048576;
+
 /**
  * Synthesizes the denial {@link ToolResult} an authority-blocked call is fed back with — the
  * call's `id` / `name` keyed back, carrying a denial `error` instead of a value.
@@ -2745,16 +3078,19 @@ export declare const DEFAULT_CONVERSATION_KEEP = 0;
 export declare function denyCall(call: ToolCall, reason: string | undefined): ToolResult;
 
 /**
- * Estimates the context-token footprint of a batch of messages — the default `consumer`
- * estimator for an agent's context `BudgetInterface` (a budgets surface's tracking contract)
- * (the {@link import('./types.js').AgentOptions} `window`).
+ * Estimates the context-token footprint of a batch of messages — each message's content plus
+ * {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD}, a tool-call JSON estimate, and
+ * {@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} for each attached image. The default
+ * `consumer` estimator for an agent's context budget (the
+ * {@link import('./types.js').AgentOptions} `window`), total and never throwing, and a
+ * deliberate provider-agnostic approximation rather than an exact tokenizer count.
  *
  * @remarks
  * Sums, per message, {@link estimateTokens} over its `content` (the `ceil(length / 4)` char
- * heuristic) PLUS {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (a fixed per-message
- * role/framing overhead) PLUS, when present, {@link estimateTokens} over its JSON-stringified
- * `calls` PLUS `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
- * deliberately-approximate per-image cost — a base64 length is NOT a token proxy). Deterministic
+ * heuristic) plus {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (a fixed per-message
+ * role/framing overhead) plus, when present, {@link estimateTokens} over its JSON-stringified
+ * `calls` plus `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
+ * deliberately-approximate per-image cost — a base64 length is not a token proxy). Deterministic
  * and provider-free — the same messages always yield the same estimate, with an empty batch `0`.
  * It is the fully-swappable default an agent's auto-compaction context budget charges each
  * turn's new messages through; a caller wanting a sharper count supplies its own `consumer` to
@@ -2775,15 +3111,15 @@ export declare function denyCall(call: ToolCall, reason: string | undefined): To
 export declare function estimateMessages(messages: readonly Message[]): number;
 
 /**
- * Estimates the context-token footprint of a string — the deterministic char-based heuristic
- * {@link estimateMessages} sums over a conversation's messages (the default context-budget
- * estimator).
+ * Estimates the context-token footprint of a string — the deterministic `ceil(length / 4)`
+ * character heuristic {@link estimateMessages} sums over a conversation's messages (the default
+ * context-budget estimator).
  *
  * @remarks
  * Approximates `ceil(length / 4)` (≈ four characters per token — the rough average for
  * English text), so the same input always yields the same estimate (no model round-trip).
  * Empty text is `0`. This is a planning heuristic for reasoning about how much a turn's
- * messages cost the next request, NOT an exact tokenizer count — it never calls a provider,
+ * messages cost the next request, not an exact tokenizer count — it never calls a provider,
  * so the agent layer stays provider-agnostic and synchronous where it can be.
  *
  * @param text - The text to estimate (a section summary, a message's content)
@@ -2799,15 +3135,16 @@ export declare function estimateMessages(messages: readonly Message[]): number;
 export declare function estimateTokens(text: string): number;
 
 /**
- * Filters a list of items by a {@link import('./types.js').ScopeInterface} allow-list of
- * keys — the pure, total set-membership primitive the context's build step and the agent
- * loop's tool-advertise step apply a scope through.
+ * Filters a list of items by a {@link import('./types.js').ScopeInterface} allow-list of keys —
+ * `undefined` passes everything, `[]` passes nothing, and a non-empty list passes the listed keys
+ * alone, order preserved. The pure, total set-membership primitive the context's build step and
+ * the agent loop's tool-advertise step apply a scope through.
  *
  * @remarks
  * Three-way by the allow-list's shape, so a `Scope` category cleanly expresses "all /
  * none / only these":
- * - `undefined` ⇒ NO constraint — every item passes (returned unchanged).
- * - `[]` (empty) ⇒ NONE pass (no key is in an empty set).
+ * - `undefined` ⇒ no constraint — every item passes (returned unchanged).
+ * - `[]` (empty) ⇒ none pass (no key is in an empty set).
  * - a non-empty list ⇒ only items whose `key(item)` is in the list pass.
  *
  * Order-preserving (it filters `items` in place order, never reorders) and total — never
@@ -2858,11 +3195,12 @@ export declare function handleAgentQueueJob(registry: AgentRegistryInterface, pa
 export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, partial: boolean, controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
 
 /**
- * Names the coarse, deliberately-approximate per-image token cost {@link import('./helpers.js').estimateMessages}
- * charges for each attached image.
+ * Names the coarse, deliberately approximate per-image token cost
+ * {@link import('./helpers.js').estimateMessages} charges for each attached image — `512`, because
+ * a base64 payload's length is no reliable token proxy.
  *
  * @remarks
- * A base64 image payload's LENGTH is NOT a reliable token proxy (a vision model's actual image
+ * A base64 image payload's length is not a reliable token proxy (a vision model's actual image
  * token cost depends on resolution / tiling, not byte size), so this is a fixed, coarse
  * per-image estimate rather than a derivation from `image.length` — a planning heuristic, not an
  * exact count.
@@ -2870,15 +3208,15 @@ export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, p
 export declare const IMAGE_TOKEN_ESTIMATE = 512;
 
 /**
- * Represents an immutable named directive — a {@link InstructionInterface} assembled once
- * from its input (`name` / `content`, an optional `priority` defaulting to `0`), the `id`
- * minted at construction.
+ * Represents an immutable named directive — an {@link InstructionInterface} assembled once from
+ * its input (`name` / `content`, an optional `priority` defaulting to `0`), the `id` minted at
+ * construction.
  *
  * @remarks
  * A thin immutable value object (mirroring {@link import('@orkestrel/tool').Tool}): the
  * constructor mints a fresh `id` (`crypto.randomUUID()`), copies the input's `name` /
  * `content`, resolves `priority` to the input's value or `0`, and carries the input's
- * per-item `override` ONLY when supplied (assigned when present, mirroring a
+ * per-item `override` only when supplied (assigned when present, mirroring a
  * message's `images` / `calls` present-when-given convention — kept absent otherwise).
  * Never mutated after construction. An
  * {@link import('./InstructionManager.js').InstructionManager} keys it by `name` and
@@ -2910,7 +3248,7 @@ export declare interface InstructionInput {
     /** Weights the ordering (higher renders first); defaults to `0` when omitted. */
     readonly priority?: number;
     /**
-     * Holds a fully-rendered override of THIS instruction's prompt text — the most-specific
+     * Holds a fully-rendered override of this instruction's prompt text — the most-specific
      * level of the {@link import('./AgentContext.js').AgentContext} build cascade (beats a
      * manager-options / provider / built-in format for this item). Round-tripped onto the
      * stored {@link InstructionInterface} when given (present-when-supplied, like `images`).
@@ -2937,8 +3275,8 @@ export declare interface InstructionInterface {
     readonly priority: number;
     /**
      * Holds a fully-rendered per-item override of this instruction's prompt text — the
-     * MOST-SPECIFIC level of the {@link import('./AgentContext.js').AgentContext} build
-     * cascade, beating every format level for THIS item. Present only when supplied on the
+     * most-specific level of the {@link import('./AgentContext.js').AgentContext} build
+     * cascade, beating every format level for this item. Present only when supplied on the
      * {@link InstructionInput} (round-tripped through the manager, like a message's
      * `images`); absent ⇒ the cascade decides.
      */
@@ -2946,28 +3284,29 @@ export declare interface InstructionInterface {
 }
 
 /**
- * Registers the immutable {@link Instruction}s a richer context assembles a directives
- * block from — keyed by `name`, listed by descending `priority`.
+ * Registers the immutable {@link Instruction}s a richer context assembles a directives block
+ * from — keyed by `name` so a re-`add` overwrites, last write wins, and listed by descending
+ * `priority`, carrying the `open` / `render` build contract and an observable `emitter`.
  *
  * @remarks
  * - **Registry.** Instructions live in an insertion-ordered `Map` keyed by `name`;
- *   `add` takes one {@link InstructionInput} or a batch, MINTS each instruction's
- *   `id`, and a re-`add` of the same name OVERWRITES it (last write wins). `count` is the
- *   map size, `instruction(name)` looks one up, and `instructions()` lists them SORTED by
+ *   `add` takes one {@link InstructionInput} or a batch, mints each instruction's
+ *   `id`, and a re-`add` of the same name overwrites it (last write wins). `count` is the
+ *   map size, `instruction(name)` looks one up, and `instructions()` lists them sorted by
  *   descending `priority` (a stable sort, so equal priorities keep insertion order).
  * - **Build contract (with the manager-options override).** `open` is the section
  *   header a context renders the instructions under; `render(instruction)` renders one
- *   instruction (its `content`). Each ENCAPSULATES the cascade's `[options-override →
+ *   instruction (its `content`). Each encapsulates the cascade's `[options-override →
  *   built-in]` half: when `InstructionManagerOptions.format` supplies an `open` /
- *   `render`, `open` / `render` return IT, else the built-in — so a richer context
+ *   `render`, `open` / `render` return it, else the built-in — so a richer context
  *   reads one consistent pair and layers the provider default + per-item override on top
  *   (see {@link import('../AgentContext.js').AgentContext}). The per-item
  *   {@link InstructionInput.override} is round-tripped onto the stored instruction.
- * - **Removal.** `remove` drops one by name, or a batch — `true` only when EVERY supplied
+ * - **Removal.** `remove` drops one by name, or a batch — `true` only when every supplied
  *   name was removed; `clear` empties the registry.
  * - **Observable.** The owned {@link emitter} ({@link InstructionManagerEventMap})
  *   carries `add` (the created instruction) / `remove` (the name) / `clear` for
- *   fire-and-forget observers. Every event is emitted directly, strictly AFTER the map
+ *   fire-and-forget observers. Every event is emitted directly, strictly after the map
  *   mutation completes; the emitter isolates a listener throw and routes it to its `error`
  *   handler (the `error` option), so a buggy observer can never corrupt a mutation.
  *
@@ -3020,9 +3359,9 @@ export declare type InstructionManagerEventMap = {
 };
 
 /**
- * Registers {@link InstructionInterface}s keyed by `name` — `add` (one or a batch)
- * mints each `id` and OVERWRITES a same-name instruction (last write wins);
- * `instructions()` lists them SORTED by descending `priority` (stable for ties).
+ * Registers {@link InstructionInterface}s keyed by `name` — `add` (one or a batch) mints each `id`
+ * and overwrites a same-name instruction, last write wins, while `instructions()` lists them sorted
+ * by descending `priority` and stable for ties.
  *
  * @remarks
  * - **Build contract.** `open` is the section header a richer context renders
@@ -3040,22 +3379,32 @@ export declare interface InstructionManagerInterface {
     readonly open: string;
     /**
      * Holds the manager-options format override (the {@link InstructionManagerOptions.format}
-     * supplied at construction), or `undefined` when none — the MANAGER-OPTIONS level of the
+     * supplied at construction), or `undefined` when none — the manager-options level of the
      * {@link import('./AgentContext.js').AgentContext} build cascade, exposed so `build()`
-     * can interleave the provider default BENEATH it (`open` / `render` already
+     * can interleave the provider default beneath it (`open` / `render` already
      * encapsulate the `[override → built-in]` half for standalone use). A `readonly` data
      * member, not a method.
      */
     readonly format: ContextSectionFormat<InstructionInterface> | undefined;
+    /**
+     * Adds one {@link InstructionInput}, or a batch — mints each `id`; a re-`add` of the same
+     * name overwrites it, last write wins.
+     */
     add(input: InstructionInput): InstructionInterface;
     add(inputs: readonly InstructionInput[]): readonly InstructionInterface[];
+    /** Looks up one instruction by name (`undefined` when absent). */
     instruction(name: string): InstructionInterface | undefined;
     /** Lists every instruction, sorted by descending `priority` (stable for equal priorities). */
     instructions(): readonly InstructionInterface[];
     /** Renders one instruction for the prompt — its `content`. */
     render(instruction: InstructionInterface): string;
+    /**
+     * Removes one instruction by name, or a batch — `true` only when every supplied name was
+     * removed.
+     */
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
+    /** Removes every instruction. */
     clear(): void;
 }
 
@@ -3066,10 +3415,10 @@ export declare interface InstructionManagerInterface {
  * @remarks
  * `on` is the reserved listener key: initial listeners for the manager's
  * {@link InstructionManagerEventMap}, wired at construction. `format` is the
- * MANAGER-OPTIONS level of the {@link import('./AgentContext.js').AgentContext} build
- * cascade — a {@link ContextSectionFormat} the manager consults FIRST in its own
+ * manager-options level of the {@link import('./AgentContext.js').AgentContext} build
+ * cascade — a {@link ContextSectionFormat} the manager consults first in its own
  * `open` / `render` (falling back to the built-in when a member is omitted), so it
- * BEATS the provider default and the built-in, while a per-item
+ * beats the provider default and the built-in, while a per-item
  * {@link InstructionInput.override} still beats it. Omitted ⇒ the built-in framing applies.
  */
 export declare interface InstructionManagerOptions {
@@ -3081,12 +3430,12 @@ export declare interface InstructionManagerOptions {
 }
 
 /**
- * Intersects two scope category lists under the "`undefined` is the universal set" rule — the
- * primitive a scope narrows through.
+ * Intersects two scope category lists under the "`undefined` is the universal set" rule — a
+ * fresh copy that can only tighten, and the primitive a scope narrows through.
  *
  * @remarks
- * Pure and total, and it can only TIGHTEN: `undefined` ∩ `undefined` is `undefined` (still no
- * constraint); `undefined` ∩ a list is a COPY of that list (the `undefined` side imposes
+ * Pure and total, and it can only tighten: `undefined` ∩ `undefined` is `undefined` (still no
+ * constraint); `undefined` ∩ a list is a copy of that list (the `undefined` side imposes
  * nothing); a list ∩ a list keeps the child keys the parent also allows, so a parent-excluded
  * key can never be re-admitted. Every returned list is a fresh copy, so a later mutation of
  * either input cannot leak into the result.
@@ -3105,7 +3454,15 @@ export declare interface InstructionManagerOptions {
 export declare function intersectKeys(parent: readonly string[] | undefined, child: readonly string[] | undefined): readonly string[] | undefined;
 
 /**
- * Narrows an unknown caught value to an {@link AgentError}.
+ * Names the status a relay answers for a body that is missing, unreadable, or rejected by
+ * `providerRequestContract` — `400`, carried with no body and reaching the browser as a
+ * `ProviderError` with the `HTTP` code.
+ */
+export declare const INVALID_RELAY_STATUS = 400;
+
+/**
+ * Narrows an unknown caught value to an {@link AgentError} through `instanceof`, so a `catch`
+ * can branch on its `code`.
  *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is an {@link AgentError}; false otherwise
@@ -3122,7 +3479,8 @@ export declare function intersectKeys(parent: readonly string[] | undefined, chi
 export declare function isAgentError(value: unknown): value is AgentError;
 
 /**
- * Narrows an unknown caught value to an {@link AgentJobError}.
+ * Narrows an unknown caught value to an {@link AgentJobError} through `instanceof`, so a
+ * `catch` can recover its `partial` result.
  *
  * @param value - The value to test (typically a `catch` binding or a rejected enqueue)
  * @returns True if `value` is an {@link AgentJobError}; false otherwise
@@ -3139,7 +3497,8 @@ export declare function isAgentError(value: unknown): value is AgentError;
 export declare function isAgentJobError(value: unknown): value is AgentJobError;
 
 /**
- * Narrows an unknown caught value to a {@link ConversationError}.
+ * Narrows an unknown caught value to a {@link ConversationError} through `instanceof`, so a
+ * `catch` can branch on its `code`.
  *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is a {@link ConversationError}; false otherwise
@@ -3156,19 +3515,20 @@ export declare function isAgentJobError(value: unknown): value is AgentJobError;
 export declare function isConversationError(value: unknown): value is ConversationError;
 
 /**
- * Narrows an `unknown` to a {@link ConversationSnapshot} — the total boundary guard for an
- * UNTRUSTED snapshot read (a storage row a
+ * Narrows an `unknown` to a {@link ConversationSnapshot} — a `string` `id`, an optional `string`
+ * `summary`, and valid `sections` and `messages` arrays; the total boundary guard for an
+ * untrusted snapshot read (a storage row a
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
- * reads back from its opaque JSON column, a snapshot loaded from disk). The EXACT analogue of
- * {@link import('@orkestrel/workspace').isWorkspaceSnapshot}.
+ * reads back from its opaque JSON column, a snapshot loaded from disk), never throwing. The exact
+ * analogue of {@link import('@orkestrel/workspace').isWorkspaceSnapshot}.
  *
  * @remarks
- * A total guard (it NEVER throws — adversarial input returns `false`). It checks the snapshot's
- * SHAPE: a `string` `id`, an OPTIONAL `string` `summary` (present-or-absent — the rollup is
- * `undefined` until the first compaction), a `sections` array EVERY element of which is a valid
- * {@link Section} ({@link isSection}), and a `messages` array EVERY element of which is a
+ * A total guard (it never throws — adversarial input returns `false`). It checks the snapshot's
+ * shape: a `string` `id`, an optional `string` `summary` (present-or-absent — the rollup is
+ * `undefined` until the first compaction), a `sections` array every element of which is a valid
+ * {@link Section} ({@link isSection}), and a `messages` array every element of which is a
  * valid {@link Message} ({@link isMessage}) — enough to safely impose the
- * {@link ConversationSnapshot} type at a storage boundary WITHOUT a cast. The structural twin of
+ * {@link ConversationSnapshot} type at a storage boundary without a cast. The structural twin of
  * {@link import('@orkestrel/workspace').isWorkspaceSnapshot}. A malformed blob (a non-record, a missing / non-string `id`, a
  * non-string `summary` when present, a non-array `sections` / `messages`, or any malformed
  * element) resolves `false`, so a
@@ -3189,39 +3549,27 @@ export declare function isConversationError(value: unknown): value is Conversati
 export declare function isConversationSnapshot(value: unknown): value is ConversationSnapshot;
 
 /**
- * Checks whether an `unknown` is structurally a {@link Message} record — the per-message step of
- * the {@link isConversationSnapshot} read-boundary narrow (a total guard over an untrusted storage
- * read, never an assertion). The conversation analogue of
- * {@link import('@orkestrel/workspace').isFile}.
+ * Checks whether a value satisfies the domain conversation-message contract.
  *
  * @remarks
- * A total guard (it NEVER throws — adversarial input returns `false`). It checks the message's
- * SHAPE: a record with a `string` `id`, a `string` `role`, a `string` `content`, and — WHEN present
- * — a `calls` array EVERY element of which is a valid
- * {@link import('@orkestrel/tool').ToolCall} ({@link isToolCall} — the
- * fail-closed deepening: a tampered `calls` element rejects the message, so the snapshot
- * reads back as absent rather than replaying a malformed call) and an `images` that is an array
- * (an absent optional passes). The `role` is left as a broad `string` here (an open
- * {@link import('./types.js').MessageRole}, so any storage-read role string is accepted
- * defensively rather than rejected against the current literal set). Enough to safely impose the
- * {@link Message} type at
- * a storage boundary WITHOUT a cast.
- *
- * @param value - The value to test (one element of a snapshot's `messages` / a section's `messages`)
- * @returns True if `value` has the structural shape of a {@link Message}; false otherwise
+ * Roles belong to MessageRole and image elements are strings. Tool arguments may
+ * carry non-JSON values, as the domain type permits; the message wire contract is
+ * narrower. Unreadable fields and hostile inputs return false.
  *
+ * @param value - The unknown message candidate
+ * @returns True if the domain message fields are valid; false otherwise
  * @example
  * ```ts
  * isMessage({ id: '1', role: 'user', content: 'hi' }) // true
- * isMessage({ id: '1', role: 'assistant', content: '', calls: [] }) // true
- * isMessage({ id: '1', role: 'user' }) // false (missing content)
- * isMessage({ id: '1', role: 'assistant', content: '', calls: [null] }) // false (malformed call)
+ * isMessage({ id: '1', role: 'other', content: '' }) // false
+ * isMessage({ id: '1', role: 'user', content: '', images: [1] }) // false
  * ```
  */
 export declare function isMessage(value: unknown): value is Message;
 
 /**
- * Narrows an unknown caught value to a {@link ProviderAbortError}.
+ * Narrows an unknown caught value to a {@link ProviderAbortError} through `instanceof`, so a
+ * `catch` can recover its `partial` result.
  *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is a {@link ProviderAbortError}; false otherwise
@@ -3238,15 +3586,28 @@ export declare function isMessage(value: unknown): value is Message;
 export declare function isProviderAbortError(value: unknown): value is ProviderAbortError;
 
 /**
- * Checks whether an `unknown` is structurally a {@link Section} record — the per-section step of
- * the {@link isConversationSnapshot} read-boundary narrow (a total guard over an untrusted storage
- * read, never an assertion).
+ * Narrows a caught value to the provider failure class through instanceof.
+ *
+ * @param value - The caught value
+ * @returns True if the value is a provider failure; false otherwise
+ * @example
+ * ```ts
+ * isProviderError(new ProviderError('HTTP', 'unavailable', { status: 503 })) // true
+ * ```
+ */
+export declare function isProviderError(value: unknown): value is ProviderError;
+
+/**
+ * Checks whether an `unknown` is structurally a {@link Section} record — a `string` `id` and
+ * `summary` beside a `messages` array of valid {@link Message}s, the per-section step of the
+ * {@link isConversationSnapshot} read-boundary narrow. Total, never throwing, and never an
+ * assertion.
  *
  * @remarks
- * A total guard (it NEVER throws — adversarial input returns `false`). It checks the section's
- * SHAPE: a record with a `string` `id`, a `string` `summary`, and a `messages` array EVERY element
+ * A total guard (it never throws — adversarial input returns `false`). It checks the section's
+ * shape: a record with a `string` `id`, a `string` `summary`, and a `messages` array every element
  * of which is a valid {@link Message} record ({@link isMessage}). Enough to safely impose
- * the {@link Section} type at a storage boundary WITHOUT a cast.
+ * the {@link Section} type at a storage boundary without a cast.
  *
  * @param value - The value to test (one element of a snapshot's `sections` array)
  * @returns True if `value` has the structural shape of a {@link Section}; false otherwise
@@ -3277,33 +3638,42 @@ export declare function isSection(value: unknown): value is Section;
  * @example
  * ```ts
  * joinThinking(undefined, 'first') // 'first'
+ * joinThinking('', 'x') // 'x'
  * joinThinking('first', 'second') // 'first\n\nsecond'
  * ```
  */
 export declare function joinThinking(running: string | undefined, next: string): string;
 
+/**
+ * Bounds the decoded error excerpt's input in bytes — `2048`, the leading bytes of a non-OK
+ * response body handed to the decoder before the read cancels the remainder, so a `ProviderError`
+ * message never carries a longer excerpt.
+ */
+export declare const MAX_ERROR_BODY_LENGTH = 2048;
+
 /**
  * Implements the {@link ConversationStoreInterface} in memory — a process-lifetime `Map` of
- * {@link ConversationSnapshot}s keyed by conversation id, the DEFAULT store
- * {@link import('../../factories.js').createMemoryConversationStore} builds. The EXACT twin of
+ * {@link ConversationSnapshot}s keyed by conversation id, the default store
+ * {@link import('../../factories.js').createMemoryConversationStore} builds and the default
+ * backing for `open` / `save`. The exact twin of
  * {@link import('@orkestrel/workspace').MemoryWorkspaceStore}.
  *
  * @remarks
  * A plain `Map<string, ConversationSnapshot>` — the snapshot is already pure,
  * self-contained JSON, so no encoding is needed for the memory tier. Like the
  * {@link import('@orkestrel/workspace').MemoryWorkspaceStore} it twins,
- * there is NO idle-TTL and NO eviction: a persisted conversation lives until an explicit `delete`. A
- * durable backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching
+ * there is no idle-TTL and no eviction: a persisted conversation lives until an explicit `delete`. A
+ * durable backend (JSON / SQLite / IndexedDB) swaps in through the same interface without touching
  * the {@link import('../ConversationManager.js').ConversationManager} or the
  * {@link import('../Conversation.js').Conversation} — its driver-pluggable twin is
  * {@link import('./DatabaseConversationStore.js').DatabaseConversationStore} (the snapshot as one
  * opaque JSON column).
  *
  * - **`get` resolves the persisted snapshot for an id**, or `undefined` if none is stored.
- * - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
+ * - **`set` inserts / replaces under the snapshot's own `id`** (no separate id param).
  * - **`delete` drops a snapshot by id**; an absent id is a no-op (no throw).
  *
- * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the method
+ * The public surface is exactly `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link ConversationStoreInterface}). Hydration is a caller concern: a
  * {@link import('../ConversationManager.js').ConversationManager} reads a snapshot back and rebuilds
  * the live conversation through the `snapshot` option (its `open` / `save`).
@@ -3322,8 +3692,27 @@ export declare function joinThinking(running: string | undefined, next: string):
  */
 export declare class MemoryConversationStore implements ConversationStoreInterface {
     #private;
+    /**
+     * Resolves the persisted snapshot for `id`, or `undefined` if none is stored.
+     *
+     * @param id - The conversation id to resolve (a {@link ConversationSnapshot.id})
+     * @returns The persisted snapshot, or `undefined` if absent
+     */
     get(id: string): Promise<ConversationSnapshot | undefined>;
+    /**
+     * Inserts or replaces a snapshot under its own `snapshot.id` (no separate id param —
+     * mirroring {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`).
+     *
+     * @param snapshot - The snapshot to store (keyed by its `id`)
+     * @returns A promise that resolves after the snapshot is stored
+     */
     set(snapshot: ConversationSnapshot): Promise<void>;
+    /**
+     * Drops a snapshot by id; an absent id is a no-op (no throw).
+     *
+     * @param id - The conversation id to drop
+     * @returns A promise that resolves after the snapshot is dropped
+     */
     delete(id: string): Promise<void>;
 }
 
@@ -3352,13 +3741,30 @@ export declare interface Message {
 }
 
 /**
- * Estimates the per-message role/framing overhead {@link import('./helpers.js').estimateMessages}
- * adds on top of a message's content estimate — accounts for the fixed wire framing every
- * conversation turn carries (its role tag, delimiters) that {@link import('./helpers.js').estimateTokens}'s
- * content-only heuristic does not otherwise capture.
+ * Estimates the per-message role and framing overhead {@link import('./helpers.js').estimateMessages}
+ * adds on top of a message's content estimate — `4` tokens for the fixed wire framing every
+ * conversation turn carries (its role tag, its delimiters) that
+ * {@link import('./helpers.js').estimateTokens}'s content-only heuristic does not otherwise
+ * capture.
  */
 export declare const MESSAGE_TOKEN_OVERHEAD = 4;
 
+/** Validates and projects conversation messages at a JSON wire boundary. */
+export declare const messageContract: ContractInterface<Readonly<{
+id: string;
+role: "system" | "user" | "assistant" | "tool";
+content: string;
+} & {
+calls?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+images?: readonly string[];
+}>>;
+
 /**
  * Carries the minimal data needed to author a {@link Message} — the `id` is
  * assigned by the layer that stores it, so a caller supplies only role / content
@@ -3376,64 +3782,103 @@ export declare interface MessageInput {
 }
 
 /**
- * Stores immutable {@link Message}s in insertion order; `add` mints the `id`.
+ * Stores immutable {@link Message}s in insertion order and mints each `id` on `add` — the
+ * message-store contract {@link AgentContextInterface.messages} is typed to, which the active
+ * {@link ConversationInterface} satisfies structurally.
  *
  * @remarks
  * - **Store.** Messages live in insertion order; `count` is how many are stored.
- *   `add` takes one {@link MessageInput} or a batch and MINTS each message's
+ *   `add` takes one {@link MessageInput} or a batch and mints each message's
  *   `id` (a random UUID), returning the created message(s). A stored message is
  *   immutable — created once from its input, never mutated.
  * - **Lookup.** `message(id)` resolves one by id (`undefined` when absent);
  *   `messages()` lists every message in insertion order.
- * - **Removal.** `remove` drops one by id, or a batch — `true` only when EVERY supplied id
+ * - **Removal.** `remove` drops one by id, or a batch — `true` only when every supplied id
  *   was removed; `clear` empties the store.
  * - **Event-free.** A purely data store — no Emitter, no events.
  */
 export declare interface MessageManagerInterface {
     readonly count: number;
+    /**
+     * Stores one {@link MessageInput}, or a batch — mints each message's `id` and returns the
+     * created message or messages; a stored message is immutable.
+     */
     add(input: MessageInput): Message;
     add(inputs: readonly MessageInput[]): readonly Message[];
+    /** Looks up one stored message by id (`undefined` when absent). */
     message(id: string): Message | undefined;
+    /** Lists every stored message, in insertion order. */
     messages(): readonly Message[];
+    /**
+     * Removes one message by id, or a batch — `true` only when every supplied id was removed.
+     */
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
+    /** Removes every stored message. */
     clear(): void;
 }
 
 /** Names the role a {@link Message} plays in a conversation turn. */
 export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 
+/**
+ * Describes a conversation message's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than Message: non-JSON call arguments are refused,
+ * and caller context is refused by the guard or dropped by the parser.
+ */
+export declare const messageShape: ObjectShape<    {
+id: StringShape;
+role: LiteralShape<readonly ["system", "user", "assistant", "tool"]>;
+content: StringShape;
+calls: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+images: OptionalShape<ArrayShape<StringShape>>;
+}, boolean | ContractShape>;
+
+/**
+ * Names the status a relay answers for a request body at or above its byte budget — `413`,
+ * carried with no body and answered for an aborted inbound read as well.
+ */
+export declare const OVERSIZED_RELAY_STATUS = 413;
+
 /**
  * Reports a provider stream cancelled mid-flight by its bound signal — thrown by a
- * {@link ProviderInterface}'s `stream`, carrying the {@link ProviderResult} assembled
- * from whatever streamed before the cancel.
+ * {@link ProviderInterface}'s `stream`, carrying the {@link ProviderResult} assembled from
+ * whatever streamed before the cancel and the machine-readable `code` `'ABORT'`.
  *
  * @remarks
  * Lets a caller recover the partial content (and any tool calls / usage seen so far)
  * on cancellation: `catch` the throw, narrow with {@link isProviderAbortError}, and
  * read `partial`. `code` is the machine-readable condition (`'ABORT'` — the only one this
- * error reports), so a `catch` branches on it rather than on the message string.
+ * error reports), so a `catch` branches on it rather than on the message string. `cause`
+ * holds the failure the cancel superseded when a throw raced the abort — the wire decoder's
+ * {@link ProviderError}, say — and is undefined when the cancel was the only failure.
  */
 export declare class ProviderAbortError extends Error {
     /** Names the machine-readable condition — `'ABORT'`: a stream cancelled mid-flight. */
     readonly code: "ABORT";
     readonly partial: ProviderResult;
-    constructor(partial: ProviderResult);
+    constructor(partial: ProviderResult, options?: ErrorOptions);
 }
 
 /**
- * Represents one streamed delta a {@link ProviderInterface}'s `stream` yields — a TAGGED unit
- * discriminated by the channel it belongs to, so the agent loop can re-surface the two
- * channels separately (answer content vs. live reasoning) as it pumps.
+ * Represents one streamed delta a {@link ProviderInterface}'s `stream` yields — a unit tagged by
+ * the channel it belongs to, so the agent loop can re-surface answer content and live reasoning
+ * separately as it pumps.
  *
  * @remarks
  * The discriminant `channel` names the axis that varies: a
- * `'content'` delta is a chunk of the assistant ANSWER (the deltas that accumulate into
+ * `'content'` delta is a chunk of the assistant answer (the deltas that accumulate into
  * {@link ProviderResult.content}); a `'thinking'` delta is a chunk of the model's
- * REASONING the provider separated from the answer (the daemon's native
- * `message.thinking` wire channel), surfaced LIVE so a consumer can stream it into a
+ * reasoning the provider separated from the answer (the daemon's native
+ * `message.thinking` wire channel), surfaced live so a consumer can stream it into a
  * collapsible without waiting for the assembled result. `text` is the delta's literal
- * text. Thinking NEVER re-enters the conversation — it is display/audit metadata, exactly
+ * text. Thinking never re-enters the conversation — it is display/audit metadata, exactly
  * as {@link ProviderResult.thinking} (the authoritative final accumulation) is.
  */
 export declare type ProviderDelta = {
@@ -3445,10 +3890,51 @@ export declare type ProviderDelta = {
 };
 
 /**
- * Defines the pluggable LLM inference boundary — the one contract every agent chunk depends
- * on. A provider turns a conversation (plus optional tools) into either a single
- * assembled {@link ProviderResult} (`generate`) or a stream of {@link ProviderDelta}s that
- * RETURNS the assembled result (`stream`).
+ * Reports a coded provider failure with its HTTP status and underlying cause when available.
+ *
+ * @remarks
+ * The provider base throws this error for a non-OK HTTP response, a missing response
+ * body, or a missing settled result when strict assembly is enabled. Concrete wire
+ * decoders also use it for malformed records and relayed provider failures.
+ * `status` is present only for an `HTTP` failure; other codes leave it undefined.
+ */
+export declare class ProviderError extends Error {
+    /** Names the machine-readable condition — `'HTTP'`: a non-OK response, including a relay refusing an oversized request with 413; `'PROTOCOL'`: a missing response body, a malformed wire record, or a strict stream with no settled result; `'PROVIDER'`: an upstream failure carried by a relay error record. */
+    readonly code: ProviderErrorCode;
+    /** Holds the response status for an HTTP failure, or undefined for other codes. */
+    readonly status: number | undefined;
+    constructor(code: ProviderErrorCode, message: string, options?: ProviderErrorOptions);
+}
+
+/** Names the machine-readable provider failure conditions. */
+export declare type ProviderErrorCode = 
+/** Reports a non-OK HTTP response, including a relay request rejected with status 413. */
+'HTTP'
+/** Reports a missing body, malformed wire record, or missing required settled result. */
+| 'PROTOCOL'
+/** Reports an upstream provider failure carried by a relay error record. */
+| 'PROVIDER';
+
+/** Carries a provider failure's HTTP status and underlying cause. */
+export declare interface ProviderErrorOptions {
+    readonly status?: number;
+    readonly cause?: unknown;
+}
+
+/** Holds the decoded contribution of a wire record to a provider turn. */
+export declare interface ProviderIncrement {
+    readonly content: string;
+    readonly thinking: string;
+    readonly tools: readonly ToolCall[];
+    readonly usage?: TokenUsage;
+    readonly result?: ProviderResult;
+}
+
+/**
+ * Defines the pluggable LLM inference boundary — the one contract every agent chunk depends on. A
+ * provider turns a conversation (plus optional tools) into either a single assembled {@link
+ * ProviderResult} (`generate`) or a stream of {@link ProviderDelta}s that returns the assembled
+ * result (`stream`).
  *
  * @remarks
  * - `id` is a stable per-instance trace label; `name` identifies the backend
@@ -3464,9 +3950,9 @@ export declare interface ProviderInterface {
     readonly id: string;
     readonly name: string;
     /**
-     * Holds the model's preferred context framing, by section kind — an OPTIONAL
+     * Holds the model's preferred context framing, by section kind — an optional
      * {@link ContextFormat} an {@link import('./AgentContext.js').AgentContext}
-     * applies as the PROVIDER-DEFAULT level of its build cascade (beating the managers'
+     * applies as the provider-default level of its build cascade (beating the managers'
      * built-in framing, beaten by a manager-options or per-item override). Omitted ⇒ the
      * provider is framing-agnostic and the managers' built-in defaults apply unchanged.
      */
@@ -3482,14 +3968,14 @@ export declare interface ProviderInterface {
      */
     generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
     /**
-     * Streams one turn — yields {@link ProviderDelta}s (channel-tagged `content` / `thinking`
-     * chunks) as they arrive and RETURNS the assembled {@link ProviderResult} (the
-     * concatenated content + any separated reasoning + any tool calls + any usage) when the
-     * stream completes.
+     * Streams one turn — yields channel-tagged `content` / `thinking` {@link ProviderDelta}s as
+     * they arrive and returns the assembled {@link ProviderResult} (the concatenated content,
+     * any separated reasoning, any tool calls, and any usage) when the stream completes. A
+     * mid-stream abort throws a `ProviderAbortError` carrying the partial result.
      *
      * @remarks
-     * An abort mid-stream throws a `ProviderAbortError` whose `partial` holds whatever
-     * streamed before the cancel, so a caller can recover the partial content.
+     * The `partial` holds whatever streamed before the cancel, so a caller can recover the
+     * partial content.
      *
      * @param messages - The conversation so far
      * @param signal - Bounds the request; an abort throws `ProviderAbortError`
@@ -3500,15 +3986,110 @@ export declare interface ProviderInterface {
     stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
 }
 
+/**
+ * Configures a provider's deadline, transport, headers, and context framing.
+ *
+ * @remarks
+ * `timeout` is an integer duration in milliseconds. Default: 120_000.
+ * `fetch` defaults to the global transport bound to its global receiver.
+ * `headers` runs for each request inside its deadline and receives the combined caller
+ * and deadline signal so token requests can share that bound. It overrides the JSON
+ * content type only when it returns that header. `format` is exposed to context assembly.
+ */
+export declare interface ProviderOptions {
+    readonly timeout?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly headers?: (signal: AbortSignal) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+    readonly format?: ContextFormat;
+}
+
+/** Defines the structural framing seam supplied by a concrete provider. */
+export declare interface ProviderParserInterface<TRecord = Readonly<Record<string, unknown>>> {
+    /** Parses a decoded chunk into complete records. */
+    parse(chunk: string): readonly TRecord[];
+    /** Clears retained framing state. */
+    clear(): void;
+}
+
+/** Carries the conversation and per-call configuration sent to a provider. */
+export declare interface ProviderRequest {
+    readonly messages: readonly Message[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly options?: ProviderStreamOptions;
+}
+
+/** Validates and projects provider requests at a JSON wire boundary. */
+export declare const providerRequestContract: ContractInterface<Readonly<{
+messages: readonly Readonly<{
+id: string;
+role: "system" | "user" | "assistant" | "tool";
+content: string;
+} & {
+calls?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+images?: readonly string[];
+}>[];
+} & {
+tools?: readonly Readonly<{
+name: string;
+} & {
+description?: string;
+parameters?: {
+readonly [k: string]: JSONValue;
+};
+}>[];
+options?: Readonly<{} & {
+think?: boolean;
+schema?: {
+readonly [k: string]: JSONValue;
+};
+}>;
+}>>;
+
+/**
+ * Describes a provider request's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than ProviderRequest: non-JSON arguments, parameters,
+ * or schema members are refused, and caller context is refused or dropped.
+ */
+export declare const providerRequestShape: ObjectShape<    {
+messages: ArrayShape<ObjectShape<    {
+id: StringShape;
+role: LiteralShape<readonly ["system", "user", "assistant", "tool"]>;
+content: StringShape;
+calls: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+images: OptionalShape<ArrayShape<StringShape>>;
+}, boolean | ContractShape>>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+name: StringShape;
+description: OptionalShape<StringShape>;
+parameters: OptionalShape<ObjectShape<Record<never, never>, JSONShape>>;
+}, boolean | ContractShape>>>;
+options: OptionalShape<ObjectShape<    {
+think: OptionalShape<BooleanShape>;
+schema: OptionalShape<ObjectShape<Record<never, never>, JSONShape>>;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+
 /**
  * Holds a single inference turn's structured outcome — the assembled assistant content,
  * any reasoning the provider separated from it, any tool calls the model requested,
  * and the token usage it reported.
  *
  * @remarks
- * `thinking` is present only when the turn produced reasoning the provider SPLIT
- * AWAY from the answer (an in-content `<think>…</think>` span a thinking model
- * emitted, or a wire-side reasoning field) — `content` is always the CLEAN answer,
+ * `thinking` is present only when the turn produced reasoning the provider split
+ * away from the answer (an in-content `<think>…</think>` span a thinking model
+ * emitted, or a wire-side reasoning field) — `content` is always the clean answer,
  * and the thinking never re-enters the conversation (it is display/audit metadata,
  * not prompt text). `tools` is present only when the model wants tool calls (an
  * empty array is never surfaced — its absence means "no calls"). `usage` is present
@@ -3525,19 +4106,60 @@ export declare interface ProviderResult {
     readonly usage?: TokenUsage;
 }
 
+/** Validates and projects provider results at a JSON wire boundary. */
+export declare const providerResultContract: ContractInterface<Readonly<{
+content: string;
+} & {
+thinking?: string;
+tools?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+usage?: Readonly<{
+prompt: number;
+completion: number;
+total: number;
+} & {}>;
+}>>;
+
+/**
+ * Describes a provider result's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than ProviderResult: non-JSON call arguments are
+ * refused, and caller context is refused or dropped.
+ */
+export declare const providerResultShape: ObjectShape<    {
+content: StringShape;
+thinking: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+usage: OptionalShape<ObjectShape<    {
+prompt: NumberShape;
+completion: NumberShape;
+total: NumberShape;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+
 /**
  * Carries the per-call options threaded into a {@link ProviderInterface}'s `generate` / `stream` —
- * the bag a caller passes to influence ONE inference call without reconfiguring the
- * provider instance.
+ * the bag a caller passes to influence one inference call without reconfiguring the provider
+ * instance.
  *
  * @remarks
- * `think` OVERRIDES the provider's constructed reasoning preference for THIS call: `true`
+ * `think` overrides the provider's constructed reasoning preference for this call: `true`
  * asks the backend to separate reasoning natively (a thinking model returns it on its
  * `message.thinking` channel, surfaced as `'thinking'` {@link ProviderDelta}s + the final
  * {@link ProviderResult.thinking}); `false` suppresses it. `schema`, when given, asks the
  * backend to constrain its response to the given JSON-Schema shape (the same open
  * JSON-Schema record {@link ToolDefinition.parameters} already carries) — a structured-output
- * request for THIS call only. Both omitted ⇒ the provider's own defaults apply (the
+ * request for this call only. Both omitted ⇒ the provider's own defaults apply (the
  * constructor value / no schema constraint), so the contract stays backward-safe — a caller
  * that passes no options behaves exactly as before.
  */
@@ -3549,9 +4171,302 @@ export declare interface ProviderStreamOptions {
 }
 
 /**
- * Renders a path-addressed text body as a fenced reference block — the framing an
- * {@link import('./AgentContext.js').AgentContext}'s ACTIVE-workspace text-file render emits (the
- * active workspace is the SOLE document/image context).
+ * Decodes UTF-8 chunks with a final flush and releases the stream on every exit.
+ *
+ * @param body - The readable byte stream
+ * @param signal - The optional cancellation bound; abort ends iteration without further chunks
+ * @returns Decoded text chunks, including a held decoder tail
+ * @example
+ * ```ts
+ * const body = new Response('answer').body
+ * if (body !== null) for await (const chunk of readChunks(body)) render(chunk)
+ * ```
+ */
+export declare function readChunks(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<string>;
+
+/**
+ * Reads a UTF-8 prefix of a byte stream and cancels its remainder.
+ *
+ * @remarks
+ * The `limit` parameter bounds bytes passed to the decoder, including a partial final
+ * character. An omitted limit reads to completion. A source may deliver a chunk larger
+ * than the remaining limit; its unused bytes are discarded without decoding.
+ * The read can overshoot by one source chunk. An abort leaves completion false.
+ *
+ * @param body - The readable byte stream
+ * @param limit - The maximum byte prefix, or undefined for the complete stream
+ * @param signal - The optional cancellation bound; abort returns the decoded prefix
+ * @returns The decoded prefix and whether EOF occurred within the byte budget
+ * @example
+ * ```ts
+ * import { readText } from '@orkestrel/agent'
+ *
+ * const body = new Response('answer').body
+ * if (body !== null) await readText(body, 3) // { text: 'ans', complete: false }
+ * ```
+ */
+export declare function readText(body: ReadableStream<Uint8Array>, limit?: number, signal?: AbortSignal): Promise<TextRead>;
+
+/**
+ * Names the relay's newline-delimited JSON content type — `'application/x-ndjson; charset=utf-8'`,
+ * the header a relay response carries beside `cache-control: no-store`.
+ */
+export declare const RELAY_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+
+/**
+ * Names the public message for an unexpected upstream relay failure — `'relay provider failed'`,
+ * the fixed text every `error` frame carries, so an upstream failure's own message never reaches
+ * the browser.
+ */
+export declare const RELAY_PROVIDER_MESSAGE = "relay provider failed";
+
+/** Carries a relay delta, settled result, remote abort, or remote failure. */
+export declare type RelayFrame = ProviderDelta | {
+    readonly channel: 'result';
+    readonly result: ProviderResult;
+} | {
+    readonly channel: 'abort';
+    readonly partial: ProviderResult;
+} | {
+    readonly channel: 'error';
+    readonly message: string;
+};
+
+/** Validates and projects channel-discriminated relay frames at a JSON wire boundary. */
+export declare const relayFrameContract: ContractInterface<Readonly<{
+channel: "content" | "thinking";
+text: string;
+} & {}> | Readonly<{
+channel: "result";
+result: Readonly<{
+content: string;
+} & {
+thinking?: string;
+tools?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+usage?: Readonly<{
+prompt: number;
+completion: number;
+total: number;
+} & {}>;
+}>;
+} & {}> | Readonly<{
+channel: "abort";
+partial: Readonly<{
+content: string;
+} & {
+thinking?: string;
+tools?: readonly Readonly<{
+id: string;
+name: string;
+arguments: {
+readonly [k: string]: JSONValue;
+};
+} & {}>[];
+usage?: Readonly<{
+prompt: number;
+completion: number;
+total: number;
+} & {}>;
+}>;
+} & {}> | Readonly<{
+channel: "error";
+message: string;
+} & {}>>;
+
+/**
+ * Describes the channel-discriminated JSON relay wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than RelayFrame through its result and partial
+ * fields: non-JSON arguments are refused, and caller context is refused or dropped.
+ */
+export declare const relayFrameShape: UnionShape<readonly [ObjectShape<    {
+channel: LiteralShape<readonly ["content", "thinking"]>;
+text: StringShape;
+}, boolean | ContractShape>, ObjectShape<    {
+channel: LiteralShape<readonly ["result"]>;
+result: ObjectShape<    {
+content: StringShape;
+thinking: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+usage: OptionalShape<ObjectShape<    {
+prompt: NumberShape;
+completion: NumberShape;
+total: NumberShape;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+}, boolean | ContractShape>, ObjectShape<    {
+channel: LiteralShape<readonly ["abort"]>;
+partial: ObjectShape<    {
+content: StringShape;
+thinking: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>>>;
+usage: OptionalShape<ObjectShape<    {
+prompt: NumberShape;
+completion: NumberShape;
+total: NumberShape;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+}, boolean | ContractShape>, ObjectShape<    {
+channel: LiteralShape<readonly ["error"]>;
+message: StringShape;
+}, boolean | ContractShape>]>;
+
+/** Defines a host-independent relay request handler. */
+export declare type RelayHandler = (request: Request) => Promise<Response>;
+
+/** Configures the upstream provider, mandatory authorization, and request byte limit. */
+export declare interface RelayOptions {
+    readonly provider: ProviderInterface;
+    /**
+     * Authorizes the request before its body is read.
+     *
+     * @remarks
+     * The hook must not consume the request body; a body-reading hook locks the stream
+     * and the handler answers with the `400` status. The relay performs no origin or
+     * method check. An application trusting an ambient credential such as a cookie
+     * must compose origin and CSRF middleware before the handler to prevent cross-site calls.
+     */
+    readonly authorize: (request: Request) => boolean | Promise<boolean>;
+    /**
+     * Bounds the request body in bytes; the handler answers with the `413` status
+     * for a body at or above the limit.
+     */
+    readonly limit?: number;
+}
+
+/**
+ * Carries provider calls over an authenticated NDJSON relay endpoint.
+ *
+ * @remarks
+ * The `ToolCall.caller` member never crosses the hop. The wire body is an owned snapshot of
+ * the projection read through property descriptors, so a serializer reachable only through a
+ * `get` trap or a prototype is never consulted; an own function-valued property such as a
+ * `toJSON` method is a value outside JSON and is refused before fetching, with the clone's
+ * failure as the refusal's `cause`. A remote abort reconstructs a `ProviderAbortError` instance
+ * without aborting the
+ * local signal; the `Agent` runtime treats that instance as an error unless its own bound
+ * signal is aborted.
+ * Content is preserved verbatim, including literal thinking tags.
+ * A refusal reaches the browser as a `ProviderError` instance with the `HTTP` code and status.
+ * This is the browser end alone; {@link createRelay} mounts the server end, and
+ * {@link createRelayProvider}'s example is the browser half of that pair.
+ *
+ * @example
+ * ```ts
+ * import type { ProviderResult } from '@orkestrel/agent'
+ * import { RelayProvider } from '@orkestrel/agent'
+ * // The browser application supplies this parser dependency.
+ * import { createNDJSONParser } from '@orkestrel/ndjson'
+ *
+ * export function ask(bearer: string, signal: AbortSignal): Promise<ProviderResult> {
+ * 	const browser = new RelayProvider({
+ * 		url: 'https://relay.example/relay',
+ * 		parser: createNDJSONParser,
+ * 		headers: () => ({ authorization: `Bearer ${bearer}` }),
+ * 	})
+ * 	return browser.generate([{ id: 'ask', role: 'user', content: 'ping' }], signal)
+ * }
+ * ```
+ */
+export declare class RelayProvider extends AgentProvider {
+    #private;
+    constructor(options: RelayProviderOptions);
+    /** Identifies the relay backend. */
+    readonly name = "relay";
+    /** Creates fresh framing state for each response. */
+    frame(): ProviderParserInterface;
+    /**
+     * Projects declared request fields and refuses values the JSON wire cannot carry.
+     *
+     * @remarks
+     * The snapshot is taken from property descriptors, so a custom serializer a projected
+     * value carries is ignored rather than consulted and cannot reach the wire.
+     *
+     * @param request - The domain conversation and call configuration
+     * @returns The validated wire request with caller context omitted
+     * @throws {ProviderError} Thrown when the snapshot cannot be taken — a hostile read or a
+     * value outside JSON — carrying that failure as its `cause`, and when the snapshot the
+     * projection produced is not a valid wire request
+     */
+    body(request: ProviderRequest): object;
+    /**
+     * Validates a relay frame and translates its channel into the shared stream engine.
+     *
+     * @param record - The framed wire record
+     * @returns A delta contribution or authoritative result
+     * @throws {ProviderAbortError} Thrown for a remote abort carrying its partial
+     * @throws {ProviderError} Thrown for a malformed frame or remote provider failure
+     */
+    read(record: Readonly<Record<string, unknown>>): ProviderIncrement;
+    /**
+     * Recovers an unterminated final frame by completing its NDJSON line.
+     *
+     * @param parser - The call's retained framing state
+     * @returns Records completed by the final newline
+     */
+    finish(parser: ProviderParserInterface): ReadonlyArray<Readonly<Record<string, unknown>>>;
+}
+
+/** Configures a relay destination and its fresh structural parser factory. */
+export declare interface RelayProviderOptions extends ProviderOptions {
+    readonly url: string;
+    /** Creates a fresh parser for each relay response stream. */
+    readonly parser: () => ProviderParserInterface;
+}
+
+/**
+ * Streams a provider call as validated NDJSON frames under response backpressure.
+ *
+ * @remarks
+ * Cancellation aborts upstream before returning its iterator. Request listeners are
+ * released on settlement. Unexpected provider failures carry a fixed public message.
+ * An inbound abort leaves the response body neither closed nor errored — a server runtime
+ * cancels that body when the client disconnects — so a consumer that aborts the inbound
+ * signal itself must cancel the body rather than keep reading it.
+ *
+ * @example
+ * ```ts
+ * import type { ProviderInterface } from '@orkestrel/agent'
+ * import { RelayStream } from '@orkestrel/agent'
+ *
+ * export function respond(provider: ProviderInterface, signal: AbortSignal): Response {
+ * 	return new RelayStream({ provider, request: { messages: [] }, signal }).response
+ * }
+ * ```
+ */
+export declare class RelayStream {
+    #private;
+    constructor(options: RelayStreamOptions);
+    /** Exposes the pull-driven response for the provider call. */
+    get response(): Response;
+}
+
+/** Carries the upstream call and cancellation bound of a relay response stream. */
+export declare interface RelayStreamOptions {
+    readonly provider: ProviderInterface;
+    readonly request: ProviderRequest;
+    readonly signal: AbortSignal;
+}
+
+/**
+ * Renders a path-addressed text body as a fenced reference block — a `File: <path>` label line
+ * over a language-tagged fence, the framing an
+ * {@link import('./AgentContext.js').AgentContext}'s active-workspace text-file render emits.
  *
  * @remarks
  * Produces `` File: <path>\n```<language>\n<content>\n``` `` — the `File:` label line, then a
@@ -3577,10 +4492,10 @@ export declare function renderFencedFile(path: string, language: string, content
 
 /**
  * Renders one context section — the resolved `open`, each item's rendering, and the resolved
- * `close` when one exists, blank-line joined.
+ * `close` when one exists, blank-line joined; `undefined` when the section has no items.
  *
  * @remarks
- * Pure and total. A section with NO items renders nothing (`undefined`), so an empty or fully
+ * Pure and total. A section with no items renders nothing (`undefined`), so an empty or fully
  * scoped-out manager stays silent — its `open` / `close` never appear without items. `close`
  * is the only optional slot: an unset one (there is no built-in close) drops the
  * trailing line.
@@ -3602,13 +4517,13 @@ export declare function renderFencedFile(path: string, language: string, content
 export declare function renderSection<T>(open: string, items: readonly T[], render: (item: T) => string, close: string | undefined): string | undefined;
 
 /**
- * Resolves one section's CLOSE text through the format cascade — manager-options override >
- * provider default.
+ * Resolves one section's close text through the format cascade — manager-options override >
+ * provider default; `undefined` when neither sets one, because there is no built-in close.
  *
  * @remarks
- * Pure and total. There is NO built-in close, so a section with neither level set returns
+ * Pure and total. There is no built-in close, so a section with neither level set returns
  * `undefined` and {@link renderSection} appends no closing line. Paired with
- * {@link resolveOpen}, one level can WRAP the whole group.
+ * {@link resolveOpen}, one level can wrap the whole group.
  *
  * @typeParam T - The section item the manager renders
  * @param manager - The section source (its `format` override)
@@ -3624,14 +4539,14 @@ export declare function renderSection<T>(open: string, items: readonly T[], rend
 export declare function resolveClose<T>(manager: ContextSectionSourceInterface<T>, provider: ContextSectionFormat<T> | undefined): string | undefined;
 
 /**
- * Resolves ONE item's rendering through the format cascade — item override >
- * manager-options override > provider default > built-in rendering.
+ * Resolves one item's rendering through the format cascade — item override > manager-options
+ * override > provider default > built-in rendering.
  *
  * @remarks
  * Pure and total. The item's own `override` is the most-specific level (a fully-rendered
  * string for that item alone). A manager's `render(item)` already encapsulates
  * `[options-override → built-in]`, so it is reached only when no higher level applies — and
- * there it IS the built-in rendering.
+ * there it is the built-in rendering.
  *
  * @typeParam T - The section item being rendered (it may carry its own `override`)
  * @param manager - The section source (its `format` override + its built-in `render`)
@@ -3651,13 +4566,13 @@ export declare function resolveItem<T extends {
 }>(manager: ContextSectionSourceInterface<T>, provider: ContextSectionFormat<T> | undefined, item: T): string;
 
 /**
- * Resolves one section's OPEN text through the format cascade — manager-options override >
+ * Resolves one section's open text through the format cascade — manager-options override >
  * provider default > built-in header.
  *
  * @remarks
- * Pure and total. The leading text has NO per-item level. A manager's `open` already
+ * Pure and total. The leading text has no per-item level. A manager's `open` already
  * encapsulates `[options-override → built-in]`, so it is reached only when neither the
- * override's `open` nor the provider's `open` applies — and there it IS the built-in header.
+ * override's `open` nor the provider's `open` applies — and there it is the built-in header.
  *
  * @typeParam T - The section item the manager renders
  * @param manager - The section source (its `format` override + its built-in `open`)
@@ -3674,15 +4589,15 @@ export declare function resolveOpen<T>(manager: ContextSectionSourceInterface<T>
 
 /**
  * Holds the immutable per-run outcome an {@link AgentInterface}'s loop settles on — the value its
- * run RETURNS, assembled from there into the {@link AgentResult} its `stream`'s `result`
- * promise resolves.
+ * run returns, assembled from there into the {@link AgentResult} its `stream`'s `result` promise
+ * resolves.
  *
  * @remarks
  * Computed inside one run (so concurrent runs never share state) and returned once, when the
  * loop settles: `content` is the streamed assistant text, `thinking` the reasoning the
  * provider calls separated from it ({@link ProviderResult.thinking}, joined across calls —
  * `undefined` when none surfaced), `usage` the summed {@link TokenUsage} (present only when
- * a provider call reported it), `partial` is `true` when a cancel committed the run early OR
+ * a provider call reported it), `partial` is `true` when a cancel committed the run early or
  * when the loop exhausted its `limit` with unresolved tool intent, and `exhausted` is `true`
  * in that second case specifically (a distinct, non-cancel cause the {@link AgentEventMap}
  * `exhaust` event observes). It is the settled outcome one run returns, before the agent folds
@@ -3697,7 +4612,8 @@ export declare interface RunOutcome {
 }
 
 /**
- * Sanitizes one reported token count into a safe non-negative integer.
+ * Sanitizes one reported token count into a safe non-negative integer — a non-finite or
+ * non-positive value becomes `0`, and a positive fractional value floors down.
  *
  * @param value - The token count to sanitize
  * @returns The floored count, or `0` when the value is non-finite or non-positive
@@ -3725,23 +4641,25 @@ export declare function sanitizeToken(value: number): number;
 export declare function sanitizeUsage(usage: TokenUsage): TokenUsage;
 
 /**
- * Represents a named, immutable filter over a richer context's items — an optional
- * allow-list per category (`instructions` / `tools` / `files`), each keyed by that
- * category's identity (an instruction's `name`, a tool's `name`, a workspace file's `path`).
+ * Represents a named, immutable filter over a richer context's items — an optional allow-list per
+ * category (`instructions` / `tools` / `files`), each keyed by that category's identity (an
+ * instruction's `name`, a tool's `name`, a workspace file's `path`) and read as an allow-list:
+ * `undefined` lets everything pass, `[]` lets nothing pass, and a non-empty list passes the listed
+ * keys alone. `narrow` composes a tighter child by set intersection.
  *
  * @remarks
- * - **A category list is three-way.** `undefined` ⇒ NO constraint on that category (all
- *   pass); `[]` ⇒ NONE pass; a non-empty list ⇒ only the listed keys pass. The build
+ * - **A category list is three-way.** `undefined` ⇒ no constraint on that category (all
+ *   pass); `[]` ⇒ none pass; a non-empty list ⇒ only the listed keys pass. The build
  *   step / loop apply this through `filterAllowList`.
- * - **Immutable.** The `id` is minted at construction; every supplied list is COPIED in
+ * - **Immutable.** The `id` is minted at construction; every supplied list is copied in
  *   (so a later mutation of the caller's array can't leak in), and the lists are
- *   `readonly`. A `Scope` is never mutated after construction — `narrow` returns a NEW
+ *   `readonly`. A `Scope` is never mutated after construction — `narrow` returns a new
  *   one rather than altering this one.
- * - **`narrow` is set-INTERSECTION (immutable composition).** A child scope's visible set
- *   per category is the intersection of THIS scope's list and the config's list — but
+ * - **`narrow` is set-intersection (immutable composition).** A child scope's visible set
+ *   per category is the intersection of this scope's list and the config's list — but
  *   `undefined` means "no constraint", so it acts as the universal set: intersecting
  *   `undefined` with a list yields the list, and `undefined` with `undefined` stays
- *   `undefined`. Narrowing can only TIGHTEN, never widen — a key excluded by a parent
+ *   `undefined`. Narrowing can only tighten, never widen — a key excluded by a parent
  *   can never be re-admitted by a child.
  *
  * @example
@@ -3765,16 +4683,17 @@ export declare class Scope implements ScopeInterface {
 }
 
 /**
- * Lists the per-category allow-lists a {@link ScopeInterface} carries — an optional
- * `readonly string[]` for `instructions`, for `tools`, and for `files`, each keyed by that
- * category's identity (an instruction's `name`, a tool's `name`, a workspace file's
- * `path`).
+ * Lists the per-category allow-lists a {@link ScopeInterface} carries — an optional `readonly
+ * string[]` for `instructions`, for `tools`, and for `files`, each keyed by that category's
+ * identity (an instruction's `name`, a tool's `name`, a workspace file's `path`) and read as an
+ * allow-list: `undefined` lets everything pass, `[]` lets nothing pass, and a non-empty list passes
+ * the listed keys alone.
  *
  * @remarks
- * Each list is THREE-WAY (see {@link import('./helpers.js').filterAllowList}): `undefined`
- * ⇒ NO constraint on that category (all pass); `[]` ⇒ NONE pass; a non-empty list ⇒ only
+ * Each list is three-way (see {@link import('./helpers.js').filterAllowList}): `undefined`
+ * ⇒ no constraint on that category (all pass); `[]` ⇒ none pass; a non-empty list ⇒ only
  * the listed keys pass. It is the shape both a {@link ScopeInput} and `Scope.narrow`
- * accept (a `name`-less narrowing config). `files` filters the ACTIVE workspace's rendered
+ * accept (a `name`-less narrowing config). `files` filters the active workspace's rendered
  * files (by `path`) in {@link AgentContextInterface.build} — both the text files folded into
  * the system block and the image files attached to the last user message.
  */
@@ -3784,7 +4703,7 @@ export declare interface ScopeFilter {
     /** Lists the allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly tools?: readonly string[];
     /**
-     * Lists the allowed ACTIVE-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —
+     * Lists the allowed active-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —
      * the filter {@link AgentContextInterface.build} applies to the active workspace's
      * {@link import('@orkestrel/workspace').WorkspaceInterface.files} before rendering them (text → the system block, image →
      * the last user message).
@@ -3801,33 +4720,35 @@ export declare interface ScopeInput extends ScopeFilter {
 }
 
 /**
- * Represents a named, immutable filter over a richer context's items — the per-category
- * allow-lists ({@link ScopeFilter}) plus an `id` / `name`, and a `narrow` that
- * composes a tighter child by set-INTERSECTION.
+ * Represents a named, immutable filter over a richer context's items — the per-category allow-lists
+ * ({@link ScopeFilter}) plus an `id` / `name`, and a `narrow` that composes a tighter child by set
+ * intersection.
  *
  * @remarks
  * Each list is three-way (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). `narrow`
- * returns a NEW scope whose per-category visible set is the intersection of this scope's
+ * returns a new scope whose per-category visible set is the intersection of this scope's
  * list and the config's — with `undefined` treated as the universal set (no constraint),
  * so `undefined ∩ list = list` and `undefined ∩ undefined = undefined`. Narrowing can
- * only TIGHTEN (a parent-excluded key never returns); the scope itself is never mutated.
+ * only tighten (a parent-excluded key never returns); the scope itself is never mutated.
  */
 export declare interface ScopeInterface extends ScopeFilter {
     readonly id: string;
     readonly name: string;
     /**
-     * Composes a tighter child scope — its per-category set is the intersection of this
-     * scope's list and `config`'s (an `undefined` side imposing no constraint).
+     * Composes a tighter child scope — each category is the set intersection of this scope's
+     * list and `config`'s (an `undefined` side imposing no constraint), returned as a new
+     * scope that leaves this one unchanged.
      *
      * @param config - The narrowing allow-lists (a `name`-less {@link ScopeFilter})
-     * @returns A NEW, tighter {@link ScopeInterface} (this one is left unchanged)
+     * @returns A new, tighter {@link ScopeInterface} (this one is left unchanged)
      */
     narrow(config: ScopeFilter): ScopeInterface;
 }
 
 /**
- * Registers the named filters a richer context reuses — immutable {@link Scope}s keyed by
- * their minted `id`, in insertion order.
+ * Registers the named filters a richer context reuses — immutable {@link Scope}s keyed by their
+ * minted `id`, in insertion order, where `create` always mints and stores rather than overwriting,
+ * and an observable `emitter` reports each change.
  *
  * @remarks
  * - **Registry.** Scopes live in an insertion-ordered `Map` keyed by their minted `id`;
@@ -3836,11 +4757,11 @@ export declare interface ScopeInterface extends ScopeFilter {
  *   one up, and `scopes()` lists them in insertion order. (Unlike the name-keyed
  *   instruction registry, a scope's key is its minted `id`, so two scopes may share a
  *   `name`; `create` therefore always adds — it never overwrites.)
- * - **Removal.** `remove` drops one by id, or a batch — `true` only when EVERY supplied id
+ * - **Removal.** `remove` drops one by id, or a batch — `true` only when every supplied id
  *   was removed; `clear` empties the registry.
  * - **Observable.** The owned {@link emitter} ({@link ScopeManagerEventMap}) carries
  *   `create` (the created scope) / `remove` (the id) / `clear`. Every event is emitted
- *   directly, strictly AFTER the map mutation completes; the emitter isolates a listener
+ *   directly, strictly after the map mutation completes; the emitter isolates a listener
  *   throw and routes it to its `error` handler (the `error` option), so a buggy observer can
  *   never corrupt a mutation.
  *
@@ -3900,12 +4821,19 @@ export declare type ScopeManagerEventMap = {
 export declare interface ScopeManagerInterface {
     readonly emitter: EmitterInterface<ScopeManagerEventMap>;
     readonly count: number;
+    /**
+     * Mints a scope from a {@link ScopeInput} (an `id` plus the per-category allow-lists) and
+     * stores it — always adds, never overwrites.
+     */
     create(input: ScopeInput): ScopeInterface;
+    /** Looks up one scope by id (`undefined` when absent). */
     scope(id: string): ScopeInterface | undefined;
     /** Lists every scope, in insertion order. */
     scopes(): readonly ScopeInterface[];
+    /** Removes one scope by id, or a batch — `true` only when every supplied id was removed. */
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
+    /** Removes every scope. */
     clear(): void;
 }
 
@@ -3925,9 +4853,9 @@ export declare interface ScopeManagerOptions {
  *
  * @remarks
  * `summary` is the model-written digest of this slice (through the
- * {@link ConversationSummaryHandler}); `messages` are the folded ORIGINALS, RETAINED in full so
+ * {@link ConversationSummaryHandler}); `messages` are the folded originals, retained in full so
  * `rehydrate` can pull them back and `search` can scan them (compaction shrinks the model
- * INPUT, never discards history).
+ * input, never discards history).
  */
 export declare interface Section {
     readonly id: string;
@@ -3938,15 +4866,17 @@ export declare interface Section {
 }
 
 /**
- * Runs one rehydrated agent and applies the partial-as-configurable-failure policy — the
- * shared job-handler step BOTH `createAgentQueue` and `createAgentRunner` settle each job
- * through, so the policy can never diverge between them.
+ * Runs one rehydrated agent and applies the partial-as-configurable-failure policy — a partial
+ * run throws an {@link import('./errors.js').AgentJobError} unless the `partial` policy allows
+ * it, and a natural finish resolves. The shared job-handler step `createAgentQueue` and
+ * `createAgentRunner` both settle each job through, so the policy can never diverge between
+ * them.
  *
  * @remarks
- * A turn that committed PARTIAL (a cancel — abort / budget / timeout) is by default a
- * FAILURE, so it THROWS an {@link import('./errors.js').AgentJobError} carrying the partial
- * (the Queue's retries + a Runner's fail-fast then engage); the `partial` policy RESOLVES
- * it as success instead. A natural finish ALWAYS resolves with its result.
+ * A turn that committed partial (a cancel — abort / budget / timeout) is by default a
+ * failure, so it throws an {@link import('./errors.js').AgentJobError} carrying the partial
+ * (the Queue's retries + a Runner's fail-fast then engage); the `partial` policy resolves
+ * it as success instead. A natural finish always resolves with its result.
  *
  * @param agent - The rehydrated {@link AgentInterface} to run to its {@link AgentResult}
  * @param partial - The partial policy. If `true`, a partial result resolves as success; if
@@ -3969,7 +4899,7 @@ export declare function settleAgentJob(agent: AgentInterface, partial: boolean):
  * @remarks
  * Iterate `events` to consume the live `T` chunks as they arrive; `await result` for
  * the eventual `R` outcome (it resolves once `events` completes). `abort(reason)`
- * cancels the in-flight operation — for an agent turn the `result` then RESOLVES
+ * cancels the in-flight operation — for an agent turn the `result` then resolves
  * (with a partial outcome), since a cancel is not an error.
  *
  * @typeParam T - The live event type the stream yields
@@ -4008,40 +4938,51 @@ export declare interface StreamInterface<T, R> {
  */
 export declare function sumUsage(running: TokenUsage | undefined, next: TokenUsage): TokenUsage;
 
+/** Carries a decoded stream prefix and whether the stream ended within its byte budget. */
+export declare interface TextRead {
+    readonly text: string;
+    /**
+     * Reports true only when a read observes the `done` flag before exhausting the
+     * byte budget; an abort reports false.
+     */
+    readonly complete: boolean;
+}
+
 /**
- * Names the closing tag that ends a {@link THINK_OPEN} reasoning span. A span the stream never closes
- * (the model was cut off mid-reasoning) is treated as thinking to its end —
- * {@link import('./types.js').ThinkSplitterInterface.flush} settles it.
+ * Names the closing tag that ends a {@link THINK_OPEN} reasoning span — `'</think>'`. A span the
+ * stream never closes (the model was cut off mid-reasoning) is treated as thinking to its end,
+ * and {@link import('./types.js').ThinkSplitterInterface.flush} settles it.
  */
 export declare const THINK_CLOSE = "</think>";
 
 /**
  * Names the opening tag a {@link import('./ThinkSplitter.js').ThinkSplitter} recognizes as the start of
- * an in-content reasoning span — the de-facto wire convention thinking models (qwen3, DeepSeek-R1
- * family) emit their chain-of-thought under when a daemon renders it inline instead of on a
- * separate wire field. Paired with {@link THINK_CLOSE}.
+ * an in-content reasoning span — `'<think>'`, the de-facto wire convention thinking models
+ * (qwen3, DeepSeek-R1 family) emit their chain-of-thought under when a daemon renders it inline
+ * instead of on a separate wire field. Paired with {@link THINK_CLOSE}.
  */
 export declare const THINK_OPEN = "<think>";
 
 /**
- * Feeds raw content deltas through a tiny stream-stateful state machine that routes
- * everything inside a `<think>…</think>` span to `thinking` and returns everything outside
- * it as clean content, so a provider yields ONLY the answer and surfaces the reasoning as
- * {@link import('./types.js').ProviderResult.thinking}.
+ * Feeds raw content deltas through a tiny stream-stateful state machine that routes everything
+ * inside a `<think>…</think>` span to `thinking` and returns everything outside it as clean
+ * content, so a provider yields the answer alone and surfaces the reasoning as
+ * {@link import('./types.js').ProviderResult.thinking}. A tag split across deltas is held until
+ * disambiguated, `flush()` settles the stream end, and one splitter serves one stream.
  *
  * @remarks
  * - **Cross-chunk tags.** A tag may arrive split across wire deltas (`'<thi'` then
- *   `'nk>'`): any suffix of the pending text that is a strict PREFIX of a tag being
- *   scanned for is HELD BACK (neither surfaced nor routed) until the next delta — or
+ *   `'nk>'`): any suffix of the pending text that is a strict prefix of a tag being
+ *   scanned for is held back (neither surfaced nor routed) until the next delta — or
  *   `flush()` — disambiguates it. A held tag prefix that never completes is real
  *   content; a held close-tag prefix inside a span is thinking.
- * - **The IMPLICIT leading open (the qwen3-template shape).** Some chat templates
- *   PRE-SEED `<think>` into the prompt scaffold, so the wire stream begins
- *   MID-REASONING and only a bare `</think>` appears. Before any tag event, a bare
- *   close therefore RECLASSIFIES everything surfaced so far (plus the pre-close
+ * - **The implicit leading open (the qwen3-template shape).** Some chat templates
+ *   pre-seed `<think>` into the prompt scaffold, so the wire stream begins
+ *   mid-reasoning and only a bare `</think>` appears. Before any tag event, a bare
+ *   close therefore reclassifies everything surfaced so far (plus the pre-close
  *   pending) as thinking — `content` is corrected retroactively (the already-returned
  *   prefix cannot be recalled, so `content` is the authoritative accumulation). The
- *   rule is ONE-SHOT: after any tag event a bare `</think>` is plain text.
+ *   rule is one-shot: after any tag event a bare `</think>` is plain text.
  * - **Multiple spans** accumulate onto `thinking` in stream order. A nested-looking
  *   `<think>` inside an open span is thinking text (no nesting is tracked — the
  *   first `</think>` closes the span), matching how the models emit it.
@@ -4069,59 +5010,94 @@ export declare class ThinkSplitter implements ThinkSplitterInterface {
 }
 
 /**
- * Splits a thinking model's in-content `<think>…</think>` reasoning spans away from the
- * answer, delta by delta with per-stream state, so a provider yields ONLY clean content
- * and surfaces the reasoning as {@link ProviderResult.thinking}.
+ * Splits a thinking model's in-content `<think>…</think>` reasoning spans away from the answer,
+ * delta by delta with per-stream state, so a provider yields clean content alone and surfaces the
+ * reasoning as {@link ProviderResult.thinking}.
  *
  * @remarks
- * - **Stateful across deltas.** A tag may arrive SPLIT across wire chunks (`'<thi'`
+ * - **Stateful across deltas.** A tag may arrive split across wire chunks (`'<thi'`
  *   ending one delta, `'nk>'` opening the next) — `split` holds any ambiguous tail
  *   back until the next delta (or `flush`) disambiguates it, so a partial tag is
  *   never leaked as content and never mis-eaten as thinking.
- * - **`split(delta)`** feeds one raw content delta and returns the CLEAN content to
+ * - **`split(delta)`** feeds one raw content delta and returns the clean content to
  *   surface for it (possibly `''` — for example mid-think). Text inside a
  *   `<think>…</think>` span accumulates on `thinking`; multiple spans accumulate in
  *   order; a nested-looking `<think>` inside an open span is thinking text (no
  *   nesting — the first `</think>` closes).
- * - **The IMPLICIT leading open (the qwen3-template shape).** Some chat templates
- *   PRE-SEED `<think>` into the prompt scaffold, so the wire stream begins
- *   MID-REASONING and only a bare `</think>` ever appears. Before any tag event, a
- *   bare close therefore RECLASSIFIES everything surfaced so far (plus the pre-close
+ * - **The implicit leading open (the qwen3-template shape).** Some chat templates
+ *   pre-seed `<think>` into the prompt scaffold, so the wire stream begins
+ *   mid-reasoning and only a bare `</think>` ever appears. Before any tag event, a
+ *   bare close therefore reclassifies everything surfaced so far (plus the pre-close
  *   pending) as thinking — `content` is corrected retroactively, while the already
  *   `split`-returned prefix cannot be recalled (the one shape where the per-delta
- *   returns over-report; `content` stays authoritative). The rule is ONE-SHOT: after
+ *   returns over-report; `content` stays authoritative). The rule is one-shot: after
  *   any tag event a bare `</think>` is plain text (prose quoting the tag stays text).
- * - **`flush()`** settles the stream end: an UNCLOSED `<think>` tail (the model was
+ * - **`flush()`** settles the stream end: an unclosed `<think>` tail (the model was
  *   cut off mid-reasoning) lands on `thinking`; a held partial tag that never
  *   completed (`'<thi'` then EOF) is returned as the final clean-content delta —
  *   it was real text after all.
  * - **`content` / `thinking`** are the authoritative accumulations so far (read them
- *   after the stream — or mid-stream for a cancel's partial); `content` is the ONE
+ *   after the stream — or mid-stream for a cancel's partial); `content` is the one
  *   exact clean-content source (the per-delta returns match it except across an
- *   implicit-open reclassification). One splitter serves ONE stream; create a fresh
+ *   implicit-open reclassification). One splitter serves one stream; create a fresh
  *   one per call ({@link import('./factories.js').createThinkSplitter}).
  */
 export declare interface ThinkSplitterInterface {
-    /** Holds the AUTHORITATIVE clean content accumulated so far (corrected across an implicit-open reclassification). */
+    /** Holds the authoritative clean content accumulated so far (corrected across an implicit-open reclassification). */
     readonly content: string;
     /** Holds the reasoning text accumulated from every `<think>…</think>` span so far. */
     readonly thinking: string;
-    /** Feeds one raw delta; returns the clean (non-think) content to surface for it. */
+    /**
+     * Feeds one raw delta and returns the clean, non-think content to surface for it (possibly
+     * `''`) — a tag split across deltas is held until disambiguated, never leaked as content
+     * and never mis-eaten as thinking.
+     */
     split(delta: string): string;
-    /** Settles the stream end — returns any held clean tail; an unclosed think span lands on `thinking`. */
+    /**
+     * Settles the stream end — a held partial tag that never completed returns as the final
+     * content delta, and an unclosed think span's tail lands on `thinking`.
+     */
     flush(): string;
 }
 
+/**
+ * Describes a tool call's JSON wire projection.
+ *
+ * @remarks
+ * The wire is strictly narrower than the domain: non-JSON arguments are refused.
+ * ToolCall.caller is not in this shape and never crosses a wire. The guard refuses
+ * that extra member; the contract parser drops it.
+ */
+export declare const toolCallShape: ObjectShape<    {
+id: StringShape;
+name: StringShape;
+arguments: ObjectShape<Record<never, never>, JSONShape>;
+}, boolean | ContractShape>;
+
+/**
+ * Names the status a relay answers when the `authorize` callback returns anything but `true` or throws —
+ * `401`, carried with no body and reaching the browser as a `ProviderError` with the `HTTP` code.
+ */
+export declare const UNAUTHORIZED_RELAY_STATUS = 401;
+
+/**
+ * Names the status a relay answers when the upstream provider call cannot be constructed — `502`,
+ * carried with no body after `provider.stream` was entered and threw before returning its
+ * iterator.
+ */
+export declare const UPSTREAM_RELAY_STATUS = 502;
+
 /**
  * Names the section header {@link import('./AgentContext.js').AgentContext}'s `build()` renders the
- * ACTIVE workspace's TEXT files under — the leading line of the dedicated workspace block in the
- * system message, the carrier-split counterpart to the documents / images section headers.
+ * active workspace's text files under — `'## Workspace'`, the leading line of the dedicated
+ * workspace block in the system message and the carrier-split counterpart to the documents and
+ * images section headers.
  *
  * @remarks
- * `build()` OWNS the workspace render (a `Workspace` / `WorkspaceManager` stays file-focused — no
+ * `build()` owns the workspace render (a `Workspace` / `WorkspaceManager` stays file-focused — no
  * `open` / `format` getters), so this header lives here as the agents module's one
  * workspace-section framing constant rather than on a manager. Each workspace text file renders
- * beneath it as a fenced `` File: <path>\n```<language>\n<text>\n``` `` block — the SAME framing
+ * beneath it as a fenced `` File: <path>\n```<language>\n<text>\n``` `` block — the same framing
  * the documents section uses — placed immediately after the documents section in the system block.
  */
 export declare const WORKSPACE_SECTION_HEADER = "## Workspace";