@orkestrel/agent 0.0.20 → 0.0.22

package/dist/src/core/index.js

@@ -1,46 +1,46 @@
-import { attempt, isArray, isBoolean, isFiniteNumber, isObject, isRecord, isString, parseJSONValue, rawShape, stringShape } from "@orkestrel/contract";
+import { arrayOf, arrayShape, attempt, booleanShape, cloneJSONValue, createContract, isArray, isBoolean, isFiniteNumber, isObject, isRecord, isString, jsonShape, literalShape, numberShape, objectShape, optionalShape, parseJSONAs, parseJSONValue, rawShape, recordShape, stringShape, unionShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { createQueue } from "@orkestrel/queue";
 import { createRunner, errorToMessage } from "@orkestrel/workflow";
 import { createAbort } from "@orkestrel/abort";
-import { createTimeout } from "@orkestrel/timeout";
+import { Timeout, createTimeout } from "@orkestrel/timeout";
 import { Emitter } from "@orkestrel/emitter";
 import { ToolManager, isToolCall } from "@orkestrel/tool";
 import { WorkspaceManager, isBinary, isText } from "@orkestrel/workspace";
 import { createTokenBudget } from "@orkestrel/budget";
 //#region src/core/constants.ts
 /**
-* 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`.
 */
 var 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`).
 */
 var 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.
 */
 var DEFAULT_CONVERSATION_KEEP = 0;
 /**
 * 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
@@ -50,73 +50,129 @@ var DEFAULT_CONVERSATION_KEEP = 0;
 var CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages] ";
 /**
 * 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}.
 */
 var THINK_OPEN = "<think>";
 /**
-* 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.
 */
 var THINK_CLOSE = "</think>";
 /**
 * 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.
 */
 var WORKSPACE_SECTION_HEADER = "## Workspace";
 /**
-* 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.
 */
 var MESSAGE_TOKEN_OVERHEAD = 4;
 /**
-* 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.
 */
 var IMAGE_TOKEN_ESTIMATE = 512;
+/**
+* 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.
+*/
+var DEFAULT_PROVIDER_TIMEOUT = 12e4;
+/**
+* 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.
+*/
+var MAX_ERROR_BODY_LENGTH = 2048;
+/**
+* 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.
+*/
+var DEFAULT_RELAY_LIMIT = 1048576;
+/**
+* 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`.
+*/
+var 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.
+*/
+var RELAY_PROVIDER_MESSAGE = "relay provider failed";
+/**
+* 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.
+*/
+var 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.
+*/
+var UPSTREAM_RELAY_STATUS = 502;
+/**
+* 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.
+*/
+var INVALID_RELAY_STATUS = 400;
+/**
+* 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.
+*/
+var OVERSIZED_RELAY_STATUS = 413;
 //#endregion
 //#region src/core/errors.ts
 /**
 * 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.
 */
 var ProviderAbortError = class extends Error {
 	/** Names the machine-readable condition — `'ABORT'`: a stream cancelled mid-flight. */
 	code = "ABORT";
 	partial;
-	constructor(partial) {
-		super("provider stream aborted");
+	constructor(partial, options) {
+		super("provider stream aborted", options);
 		this.name = "ProviderAbortError";
 		this.partial = partial;
 	}
 };
 /**
-* 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
@@ -136,13 +192,13 @@ function isProviderAbortError(value) {
 /**
 * 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
@@ -162,7 +218,8 @@ var AgentJobError = class extends Error {
 	}
 };
 /**
-* 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
@@ -180,12 +237,13 @@ function isAgentJobError(value) {
 	return value instanceof AgentJobError;
 }
 /**
-* 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} /
@@ -204,7 +262,8 @@ var ConversationError = class extends Error {
 	}
 };
 /**
-* 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
@@ -222,13 +281,16 @@ function isConversationError(value) {
 	return value instanceof ConversationError;
 }
 /**
-* 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`
@@ -246,7 +308,8 @@ var AgentError = class extends Error {
 	}
 };
 /**
-* Narrows an unknown caught value to an {@link AgentError}.
+* 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
@@ -263,11 +326,148 @@ var AgentError = class extends Error {
 function isAgentError(value) {
 	return value instanceof AgentError;
 }
+/**
+* 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.
+*/
+var ProviderError = class 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. */
+	code;
+	/** Holds the response status for an HTTP failure, or undefined for other codes. */
+	status;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "ProviderError";
+		this.code = code;
+		this.status = options?.status;
+	}
+};
+/**
+* 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
+* ```
+*/
+function isProviderError(value) {
+	return value instanceof ProviderError;
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* 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.
+*/
+var toolCallShape = objectShape({
+	id: stringShape(),
+	name: stringShape(),
+	arguments: recordShape(jsonShape())
+});
+/**
+* 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.
+*/
+var messageShape = objectShape({
+	id: stringShape(),
+	role: literalShape([
+		"system",
+		"user",
+		"assistant",
+		"tool"
+	]),
+	content: stringShape(),
+	calls: optionalShape(arrayShape(toolCallShape)),
+	images: optionalShape(arrayShape(stringShape()))
+});
+/**
+* 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.
+*/
+var providerRequestShape = objectShape({
+	messages: arrayShape(messageShape),
+	tools: optionalShape(arrayShape(objectShape({
+		name: stringShape(),
+		description: optionalShape(stringShape()),
+		parameters: optionalShape(recordShape(jsonShape()))
+	}))),
+	options: optionalShape(objectShape({
+		think: optionalShape(booleanShape()),
+		schema: optionalShape(recordShape(jsonShape()))
+	}))
+});
+/**
+* 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.
+*/
+var providerResultShape = objectShape({
+	content: stringShape(),
+	thinking: optionalShape(stringShape()),
+	tools: optionalShape(arrayShape(toolCallShape)),
+	usage: optionalShape(objectShape({
+		prompt: numberShape(),
+		completion: numberShape(),
+		total: numberShape()
+	}))
+});
+/**
+* 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.
+*/
+var relayFrameShape = unionShape(objectShape({
+	channel: literalShape(["content", "thinking"]),
+	text: stringShape()
+}), objectShape({
+	channel: literalShape(["result"]),
+	result: providerResultShape
+}), objectShape({
+	channel: literalShape(["abort"]),
+	partial: providerResultShape
+}), objectShape({
+	channel: literalShape(["error"]),
+	message: stringShape()
+}));
+//#endregion
+//#region src/core/contracts.ts
+/** Validates and projects conversation messages at a JSON wire boundary. */
+var messageContract = createContract(messageShape);
+/** Validates and projects provider requests at a JSON wire boundary. */
+var providerRequestContract = createContract(providerRequestShape);
+/** Validates and projects provider results at a JSON wire boundary. */
+var providerResultContract = createContract(providerResultShape);
+/** Validates and projects channel-discriminated relay frames at a JSON wire boundary. */
+var relayFrameContract = createContract(relayFrameShape);
 //#endregion
 //#region src/core/helpers.ts
 /**
-* 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
@@ -321,15 +521,16 @@ function agentResultToJSON(value) {
 	return captured.success ? parseJSONValue(captured.value) : void 0;
 }
 /**
-* 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
@@ -356,15 +557,15 @@ function filterAllowList(allow, items, key) {
 	return items.filter((item) => set.has(key(item)));
 }
 /**
-* 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)
@@ -381,16 +582,19 @@ function estimateTokens(text) {
 	return Math.ceil(text.length / 4);
 }
 /**
-* 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
@@ -422,15 +626,17 @@ function estimateMessages(messages) {
 	}, 0);
 }
 /**
-* 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
@@ -482,9 +688,9 @@ function handleAgentRunnerJob(registry, partial, controller) {
 	return settleAgentJob(registry.build(controller.input, controller.signal), partial);
 }
 /**
-* 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).
+* 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
@@ -510,7 +716,8 @@ function renderFencedFile(path, language, content) {
 	return `File: ${path}\n\`\`\`${language}\n${content}\n\`\`\``;
 }
 /**
-* 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
@@ -560,11 +767,13 @@ function sanitizeUsage(usage) {
 * @example
 * ```ts
 * joinThinking(undefined, 'first') // 'first'
+* joinThinking('', 'x') // 'x'
 * joinThinking('first', 'second') // 'first\n\nsecond'
 * ```
 */
 function joinThinking(running, next) {
-	return running === void 0 ? next : `${running}\n\n${next}`;
+	if (running === void 0 || running.length === 0) return next;
+	return next.length === 0 ? running : `${running}\n\n${next}`;
 }
 /**
 * Adds two {@link TokenUsage} values field by field — the running total an agent run keeps
@@ -596,10 +805,11 @@ function sumUsage(running, next) {
 }
 /**
 * 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.
@@ -651,10 +861,10 @@ function denyCall(call, reason) {
 }
 /**
 * 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.
@@ -680,13 +890,13 @@ function renderSection(open, items, render, close) {
 	return lines.join("\n\n");
 }
 /**
-* 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`)
@@ -703,13 +913,13 @@ function resolveOpen(manager, provider) {
 	return manager.format?.open ?? provider?.open ?? manager.open;
 }
 /**
-* 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)
@@ -726,14 +936,14 @@ function resolveClose(manager, provider) {
 	return manager.format?.close ?? provider?.close;
 }
 /**
-* 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`)
@@ -752,11 +962,11 @@ function resolveItem(manager, provider, item) {
 	return item.override ?? manager.format?.render?.(item) ?? provider?.render?.(item) ?? manager.render(item);
 }
 /**
-* 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).
 *
@@ -786,13 +996,14 @@ function attachImages(message, data) {
 	};
 }
 /**
-* 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)
@@ -816,11 +1027,11 @@ function attachUserImages(conversation, data) {
 	return conversation.map((message, index) => index === target ? attachImages(message, data) : 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.
+* 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.
 *
@@ -839,12 +1050,12 @@ function collectImageData(files) {
 	return data;
 }
 /**
-* 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}.
 *
@@ -865,13 +1076,13 @@ function buildSummaryMessage(section) {
 	};
 }
 /**
-* 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}.
+* 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.
 *
@@ -892,12 +1103,12 @@ function buildRecapMessage(section) {
 	};
 }
 /**
-* 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.
@@ -919,39 +1130,167 @@ function intersectKeys(parent, child) {
 	const allowed = new Set(parent);
 	return child.filter((key) => allowed.has(key));
 }
+/**
+* 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' }
+* ```
+*/
+function buildProviderResult(content, thinking, tools, usage) {
+	return {
+		content,
+		...thinking.length === 0 ? {} : { thinking },
+		...tools.length === 0 ? {} : { tools },
+		...usage === void 0 ? {} : { usage }
+	};
+}
+/**
+* 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 }
+* ```
+*/
+async function readText(body, limit, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const cleanup = new AbortController();
+	let remaining = limit ?? Infinity;
+	let text = "";
+	let complete = false;
+	try {
+		signal?.addEventListener("abort", () => {
+			reader.cancel(signal.reason).catch(() => {});
+		}, {
+			once: true,
+			signal: cleanup.signal
+		});
+		if (signal?.aborted) await reader.cancel(signal.reason).catch(() => {});
+		while (remaining > 0) {
+			if (signal?.aborted) break;
+			const step = await reader.read();
+			if (signal?.aborted) break;
+			if (step.done) {
+				complete = true;
+				break;
+			}
+			const bytes = step.value.subarray(0, remaining);
+			text += decoder.decode(bytes, { stream: true });
+			remaining -= bytes.byteLength;
+		}
+		return {
+			text: text + decoder.decode(),
+			complete
+		};
+	} finally {
+		cleanup.abort();
+		try {
+			await reader.cancel();
+		} catch {} finally {
+			reader.releaseLock();
+		}
+	}
+}
+/**
+* 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)
+* ```
+*/
+async function* readChunks(body, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const cleanup = new AbortController();
+	try {
+		signal?.addEventListener("abort", () => {
+			reader.cancel(signal.reason).catch(() => {});
+		}, {
+			once: true,
+			signal: cleanup.signal
+		});
+		if (signal?.aborted) {
+			await reader.cancel(signal.reason).catch(() => {});
+			return;
+		}
+		for (;;) {
+			const step = await reader.read();
+			if (signal?.aborted) return;
+			if (step.done) break;
+			const chunk = decoder.decode(step.value, { stream: true });
+			if (chunk.length > 0) yield chunk;
+		}
+		const tail = decoder.decode();
+		if (tail.length > 0) yield tail;
+	} finally {
+		cleanup.abort();
+		try {
+			await reader.cancel();
+		} catch {} finally {
+			reader.releaseLock();
+		}
+	}
+}
 //#endregion
 //#region src/core/conversations/Conversation.ts
 /**
-* 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.
 *
@@ -1117,26 +1456,27 @@ var Conversation = class {
 //#endregion
 //#region src/core/conversations/ConversationManager.ts
 /**
-* 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`).
@@ -1236,15 +1576,15 @@ var ConversationManager = class {
 //#endregion
 //#region src/core/instructions/Instruction.ts
 /**
-* 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
@@ -1273,28 +1613,29 @@ var Instruction = class {
 //#endregion
 //#region src/core/instructions/InstructionManager.ts
 /**
-* 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.
 *
@@ -1373,58 +1714,59 @@ var InstructionManager = class {
 /**
 * 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).
@@ -1503,10 +1845,11 @@ var AgentContext = class {
 //#endregion
 //#region src/core/Channel.ts
 /**
-* 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);
@@ -1567,8 +1910,10 @@ var Channel = class {
 //#region src/core/Agent.ts
 /**
 * 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
@@ -1585,15 +1930,15 @@ var Channel = class {
 *   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.
@@ -1784,7 +2129,7 @@ var Agent = class {
 			} catch (error) {
 				if (abort.signal.aborted) {
 					if (isProviderAbortError(error)) {
-						if (error.partial.thinking !== void 0) thinking = joinThinking(thinking, error.partial.thinking);
+						if (error.partial.thinking !== void 0 && error.partial.thinking.length > 0) thinking = joinThinking(thinking, error.partial.thinking);
 						if (error.partial.usage !== void 0) {
 							const abortUsage = sanitizeUsage(error.partial.usage);
 							budget?.consume({
@@ -1945,9 +2290,10 @@ var Agent = class {
 //#endregion
 //#region src/core/AgentRegistry.ts
 /**
-* 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
@@ -1956,9 +2302,9 @@ var Agent = class {
 *   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
@@ -2039,18 +2385,20 @@ var AgentRegistry = class {
 //#endregion
 //#region src/core/Authority.ts
 /**
-* 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
@@ -2092,51 +2440,44 @@ var Authority = class {
 //#endregion
 //#region src/core/validators.ts
 /**
-* 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
 * ```
 */
 function isMessage(value) {
-	if (!isRecord(value)) return false;
-	if (!isString(value.id) || !isString(value.role) || !isString(value.content)) return false;
-	if (value.calls !== void 0 && !(isArray(value.calls) && value.calls.every(isToolCall))) return false;
-	return value.images === void 0 || isArray(value.images);
+	const checked = attempt(() => {
+		if (!isRecord(value)) return false;
+		const { id, role, content, calls, images } = value;
+		if (!isString(id) || !isString(content)) return false;
+		if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") return false;
+		if (calls !== void 0 && !arrayOf(isToolCall)(calls)) return false;
+		return images === void 0 || arrayOf(isString)(images);
+	});
+	return checked.success && checked.value;
 }
 /**
-* 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).
+* 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
@@ -2154,19 +2495,20 @@ function isSection(value) {
 	return isArray(value.messages) && value.messages.every(isMessage);
 }
 /**
-* 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
@@ -2195,37 +2537,39 @@ function isConversationSnapshot(value) {
 //#region src/core/conversations/stores/DatabaseConversationStore.ts
 /**
 * 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`).
@@ -2260,7 +2604,7 @@ var DatabaseConversationStore = class {
 		if (row === void 0) return void 0;
 		return isConversationSnapshot(row.snapshot) ? row.snapshot : void 0;
 	}
-	/** 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 }`. */
 	async set(snapshot) {
 		await this.#table.set({
 			id: snapshot.id,
@@ -2276,26 +2620,27 @@ var DatabaseConversationStore = class {
 //#region src/core/conversations/stores/MemoryConversationStore.ts
 /**
 * 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`).
@@ -2314,38 +2659,546 @@ var DatabaseConversationStore = class {
 */
 var MemoryConversationStore = class {
 	#snapshots = /* @__PURE__ */ new Map();
+	/**
+	* 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) {
 		return Promise.resolve(this.#snapshots.get(id));
 	}
+	/**
+	* 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) {
 		this.#snapshots.set(snapshot.id, snapshot);
 		return Promise.resolve();
 	}
+	/**
+	* 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) {
 		this.#snapshots.delete(id);
 		return Promise.resolve();
 	}
 };
 //#endregion
+//#region src/core/AgentProvider.ts
+/**
+* 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.
+* 	}
+* }
+* ```
+*/
+var AgentProvider = class {
+	#id;
+	#url;
+	#path;
+	#timeout;
+	#transport;
+	#headers;
+	#format;
+	#split;
+	#strict;
+	constructor(input) {
+		this.#id = crypto.randomUUID();
+		this.#url = input.url;
+		this.#path = input.path ?? "";
+		this.#timeout = input.timeout ?? 12e4;
+		this.#transport = input.fetch ?? globalThis.fetch.bind(globalThis);
+		this.#headers = input.headers;
+		this.#format = input.format;
+		this.#split = input.split ?? true;
+		this.#strict = input.strict ?? false;
+	}
+	/** Exposes the instance's minted UUID. */
+	get id() {
+		return this.#id;
+	}
+	/** Exposes the context framing exactly as supplied. */
+	get format() {
+		return this.#format;
+	}
+	/**
+	* 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
+	*/
+	async generate(messages, signal, tools, options) {
+		const stream = this.stream(messages, signal, tools, options);
+		let step = await stream.next();
+		while (!step.done) step = await stream.next();
+		return step.value;
+	}
+	/**
+	* 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
+	*/
+	async *stream(messages, signal, tools, options) {
+		if (signal.aborted) throw new ProviderAbortError({ content: "" });
+		const timeout = new Timeout({ ms: this.#timeout });
+		timeout.start();
+		const combined = AbortSignal.any([timeout.signal, signal]);
+		let parser;
+		let splitter;
+		let state = {
+			content: "",
+			thinking: "",
+			tools: []
+		};
+		try {
+			parser = this.frame();
+			splitter = this.#split ? createThinkSplitter() : void 0;
+			const response = await this.#request({
+				messages,
+				...tools === void 0 ? {} : { tools },
+				...options === void 0 ? {} : { options }
+			}, combined);
+			if (response.body === null) throw new ProviderError("PROTOCOL", "provider error: no response body");
+			for await (const chunk of readChunks(response.body, combined)) {
+				combined.throwIfAborted();
+				for (const record of parser.parse(chunk)) {
+					yield* this.#fold(record, state, splitter, combined, (increment) => {
+						state = increment;
+					});
+					combined.throwIfAborted();
+					if (state.result !== void 0) return state.result;
+				}
+			}
+			combined.throwIfAborted();
+			for (const record of this.finish(parser)) {
+				yield* this.#fold(record, state, splitter, combined, (increment) => {
+					state = increment;
+				});
+				combined.throwIfAborted();
+				if (state.result !== void 0) return state.result;
+			}
+			const tail = splitter?.flush() ?? "";
+			if (tail.length > 0) yield {
+				channel: "content",
+				text: tail
+			};
+			combined.throwIfAborted();
+			if (this.#strict) throw new ProviderError("PROTOCOL", "provider error: missing settled result");
+			return buildProviderResult(splitter?.content ?? state.content, joinThinking(splitter?.thinking, state.thinking), state.tools, state.usage);
+		} catch (error) {
+			if (combined.aborted) {
+				splitter?.flush();
+				throw new ProviderAbortError(buildProviderResult(splitter?.content ?? state.content, joinThinking(splitter?.thinking, state.thinking), state.tools, state.usage), error === combined.reason ? void 0 : { cause: error });
+			}
+			throw error;
+		} finally {
+			try {
+				parser?.clear();
+			} finally {
+				timeout.clear();
+			}
+		}
+	}
+	*#fold(record, previous, splitter, signal, commit) {
+		const increment = this.read(record);
+		if (increment.result !== void 0) {
+			commit(increment);
+			return;
+		}
+		const content = splitter?.split(increment.content) ?? increment.content;
+		const usage = increment.usage ?? previous.usage;
+		commit({
+			content: previous.content + increment.content,
+			thinking: previous.thinking + increment.thinking,
+			tools: [...previous.tools, ...increment.tools],
+			...usage === void 0 ? {} : { usage }
+		});
+		if (content.length > 0) yield {
+			channel: "content",
+			text: content
+		};
+		signal.throwIfAborted();
+		if (increment.thinking.length > 0) yield {
+			channel: "thinking",
+			text: increment.thinking
+		};
+	}
+	async #request(request, signal) {
+		const headers = await this.#requestHeaders(signal);
+		signal.throwIfAborted();
+		const response = await this.#transport(this.#url + this.#path, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(this.body(request)),
+			signal
+		});
+		if (!response.ok) {
+			let detail;
+			try {
+				detail = response.body === null ? "" : (await readText(response.body, MAX_ERROR_BODY_LENGTH, signal)).text;
+			} catch (cause) {
+				throw new ProviderError("HTTP", `provider error: ${response.status} - (error body unavailable)`, {
+					status: response.status,
+					cause
+				});
+			}
+			signal.throwIfAborted();
+			throw new ProviderError("HTTP", `provider error: ${response.status}${detail === "" ? "" : ` - ${detail}`}`, { status: response.status });
+		}
+		return response;
+	}
+	async #requestHeaders(signal) {
+		const headers = new Headers({ "Content-Type": "application/json" });
+		if (this.#headers === void 0) return headers;
+		const cleanup = new AbortController();
+		const aborted = Promise.withResolvers();
+		signal.addEventListener("abort", () => aborted.reject(signal.reason), {
+			once: true,
+			signal: cleanup.signal
+		});
+		try {
+			signal.throwIfAborted();
+			const hook = this.#headers;
+			const entries = await Promise.race([Promise.resolve().then(() => hook(signal)), aborted.promise]);
+			for (const [key, value] of Object.entries(entries)) headers.set(key, value);
+			return headers;
+		} finally {
+			cleanup.abort();
+		}
+	}
+};
+//#endregion
+//#region src/core/providers/RelayProvider.ts
+/**
+* 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)
+* }
+* ```
+*/
+var RelayProvider = class extends AgentProvider {
+	#parser;
+	constructor(options) {
+		const { url, timeout, fetch, headers, format } = options;
+		super({
+			url,
+			split: false,
+			strict: true,
+			...timeout === void 0 ? {} : { timeout },
+			...fetch === void 0 ? {} : { fetch },
+			...headers === void 0 ? {} : { headers },
+			...format === void 0 ? {} : { format }
+		});
+		this.#parser = options.parser;
+	}
+	/** Identifies the relay backend. */
+	name = "relay";
+	/** Creates fresh framing state for each response. */
+	frame() {
+		return this.#parser();
+	}
+	/**
+	* 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) {
+		let snapshot;
+		try {
+			const projected = {
+				messages: request.messages.map((message) => ({
+					id: message.id,
+					role: message.role,
+					content: message.content,
+					...message.calls === void 0 ? {} : { calls: message.calls.map((call) => ({
+						id: call.id,
+						name: call.name,
+						arguments: call.arguments
+					})) },
+					...message.images === void 0 ? {} : { images: message.images }
+				})),
+				...request.tools === void 0 ? {} : { tools: request.tools.map((tool) => ({
+					name: tool.name,
+					...tool.description === void 0 ? {} : { description: tool.description },
+					...tool.parameters === void 0 ? {} : { parameters: tool.parameters }
+				})) },
+				...request.options === void 0 ? {} : { options: {
+					...request.options.think === void 0 ? {} : { think: request.options.think },
+					...request.options.schema === void 0 ? {} : { schema: request.options.schema }
+				} }
+			};
+			snapshot = cloneJSONValue(projected);
+		} catch (cause) {
+			throw new ProviderError("PROTOCOL", "relay request is not JSON", { cause });
+		}
+		if (!providerRequestContract.is(snapshot)) throw new ProviderError("PROTOCOL", "relay request is not JSON");
+		return snapshot;
+	}
+	/**
+	* 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) {
+		if (!relayFrameContract.is(record)) throw new ProviderError("PROTOCOL", "invalid relay frame");
+		switch (record.channel) {
+			case "content": return {
+				content: record.text,
+				thinking: "",
+				tools: []
+			};
+			case "thinking": return {
+				content: "",
+				thinking: record.text,
+				tools: []
+			};
+			case "result": return {
+				content: "",
+				thinking: "",
+				tools: [],
+				result: record.result
+			};
+			case "abort": throw new ProviderAbortError(record.partial);
+			case "error": throw new ProviderError("PROVIDER", record.message);
+		}
+	}
+	/**
+	* 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) {
+		return parser.parse("\n");
+	}
+};
+//#endregion
+//#region src/core/RelayStream.ts
+/**
+* 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
+* }
+* ```
+*/
+var RelayStream = class {
+	#upstream = new AbortController();
+	#encoder = new TextEncoder();
+	#iterator;
+	#signal;
+	#listener;
+	#response;
+	#settled = false;
+	constructor(options) {
+		this.#signal = options.signal;
+		this.#listener = this.#cancel.bind(this);
+		if (this.#signal.aborted) this.#abortProvider();
+		this.#iterator = options.provider.stream(options.request.messages, this.#upstream.signal, options.request.tools, options.request.options);
+		this.#signal.addEventListener("abort", this.#listener, { once: true });
+		this.#response = new Response(new ReadableStream({
+			pull: this.#pull.bind(this),
+			cancel: this.#cancel.bind(this)
+		}), { headers: {
+			"content-type": RELAY_CONTENT_TYPE,
+			"cache-control": "no-store"
+		} });
+	}
+	/** Exposes the pull-driven response for the provider call. */
+	get response() {
+		return this.#response;
+	}
+	async #pull(controller) {
+		if (this.#settled) return;
+		try {
+			const step = await this.#iterator.next();
+			if (this.#settled) return;
+			this.#write(controller, step.done ? {
+				channel: "result",
+				result: step.value
+			} : step.value);
+			if (step.done) this.#finish(controller);
+		} catch (error) {
+			if (this.#settled) return;
+			const frame = error instanceof ProviderAbortError ? {
+				channel: "abort",
+				partial: error.partial
+			} : {
+				channel: "error",
+				message: RELAY_PROVIDER_MESSAGE
+			};
+			this.#write(controller, relayFrameContract.is(frame) ? frame : {
+				channel: "error",
+				message: RELAY_PROVIDER_MESSAGE
+			});
+			this.#finish(controller);
+			this.#abortProvider();
+			await this.#return();
+		}
+	}
+	async #cancel() {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#abortProvider();
+		try {
+			await this.#return();
+		} finally {
+			this.#release();
+		}
+	}
+	async #return() {
+		try {
+			await this.#iterator.return({ content: "" });
+		} catch {}
+	}
+	#write(controller, frame) {
+		if (!relayFrameContract.is(frame)) throw new ProviderError("PROTOCOL", "invalid relay frame");
+		controller.enqueue(this.#encoder.encode(`${JSON.stringify(frame)}\n`));
+	}
+	#finish(controller) {
+		this.#settled = true;
+		this.#release();
+		controller.close();
+	}
+	#abortProvider() {
+		this.#upstream.abort(this.#signal.reason);
+	}
+	#release() {
+		this.#signal.removeEventListener("abort", this.#listener);
+	}
+};
+//#endregion
 //#region src/core/scopes/Scope.ts
 /**
-* 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
@@ -2385,8 +3238,9 @@ var Scope = class Scope {
 //#endregion
 //#region src/core/scopes/ScopeManager.ts
 /**
-* 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`;
@@ -2395,11 +3249,11 @@ var Scope = class Scope {
 *   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.
 *
@@ -2459,24 +3313,25 @@ var ScopeManager = class {
 //#endregion
 //#region src/core/ThinkSplitter.ts
 /**
-* 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.
@@ -2577,17 +3432,116 @@ var ThinkSplitter = class {
 //#endregion
 //#region src/core/factories.ts
 /**
+* 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
+* ```
+*/
+function createRelay(options) {
+	const { provider, authorize, limit } = options;
+	return async (request) => {
+		try {
+			if (await authorize(request) !== true) return new Response(void 0, { status: 401 });
+		} catch {
+			return new Response(void 0, { status: 401 });
+		}
+		if (request.body === null) return new Response(void 0, { status: 400 });
+		let read;
+		try {
+			read = await readText(request.body, limit ?? 1048576, request.signal);
+		} catch {
+			return new Response(void 0, { status: request.signal.aborted ? 413 : 400 });
+		}
+		if (!read.complete) return new Response(void 0, { status: 413 });
+		const parsed = parseJSONAs(read.text, providerRequestContract.is);
+		if (parsed === void 0) return new Response(void 0, { status: 400 });
+		try {
+			return new RelayStream({
+				provider,
+				request: parsed,
+				signal: request.signal
+			}).response;
+		} catch {
+			return new Response(void 0, { status: 502 });
+		}
+	};
+}
+/**
+* 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
+* ```
+*/
+function createRelayProvider(options) {
+	return new RelayProvider(options);
+}
+/**
 * 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.
@@ -2595,20 +3549,39 @@ var ThinkSplitter = class {
 * @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)
 * ```
 */
 function createConversation(options) {
@@ -2616,21 +3589,22 @@ function createConversation(options) {
 }
 /**
 * 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})
@@ -2651,7 +3625,7 @@ function createConversationManager(options) {
 /**
 * 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}.
 *
@@ -2659,10 +3633,10 @@ function createConversationManager(options) {
 * 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`).
@@ -2684,23 +3658,24 @@ function createMemoryConversationStore() {
 	return new MemoryConversationStore();
 }
 /**
-* 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
@@ -2755,7 +3730,7 @@ function createInstruction(input) {
 * 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
@@ -2786,9 +3761,9 @@ function createInstructionManager(options) {
 * 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`
@@ -2834,19 +3809,20 @@ function createScopeManager(options) {
 	return new ScopeManager(options);
 }
 /**
-* 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`
@@ -2873,10 +3849,10 @@ function createAgentContext(options) {
 * `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
@@ -2912,18 +3888,19 @@ function createAgent(provider, options) {
 	return new Agent(provider, options);
 }
 /**
-* 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)
@@ -2950,7 +3927,7 @@ function createThinkSplitter() {
 * 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}
@@ -2976,11 +3953,11 @@ function createChannel() {
 * 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.
@@ -3010,7 +3987,7 @@ function createAuthority(options) {
 *
 * @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)`
@@ -3040,7 +4017,7 @@ function createAgentRegistry(options) {
 }
 /**
 * 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.
 *
@@ -3053,9 +4030,9 @@ function createAgentRegistry(options) {
 *   (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
@@ -3088,21 +4065,21 @@ function createAgentQueue(options) {
 }
 /**
 * 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.
 *
@@ -3132,6 +4109,6 @@ function createAgentRunner(options) {
 	});
 }
 //#endregion
-export { Agent, AgentContext, AgentError, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, IMAGE_TOKEN_ESTIMATE, Instruction, InstructionManager, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, WORKSPACE_SECTION_HEADER, agentResultToJSON, assembleResult, attachImages, attachUserImages, buildRecapMessage, buildSummaryMessage, collectImageData, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createChannel, createConversation, createConversationManager, createDatabaseConversationStore, createInstruction, createInstructionManager, createMemoryConversationStore, createScope, createScopeManager, createThinkSplitter, denyCall, estimateMessages, estimateTokens, filterAllowList, handleAgentQueueJob, handleAgentRunnerJob, intersectKeys, isAgentError, isAgentJobError, isConversationError, isConversationSnapshot, isMessage, isProviderAbortError, isSection, joinThinking, renderFencedFile, renderSection, resolveClose, resolveItem, resolveOpen, sanitizeToken, sanitizeUsage, settleAgentJob, sumUsage };
+export { Agent, AgentContext, AgentError, AgentJobError, AgentProvider, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DEFAULT_PROVIDER_TIMEOUT, DEFAULT_RELAY_LIMIT, DatabaseConversationStore, IMAGE_TOKEN_ESTIMATE, INVALID_RELAY_STATUS, Instruction, InstructionManager, MAX_ERROR_BODY_LENGTH, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, OVERSIZED_RELAY_STATUS, ProviderAbortError, ProviderError, RELAY_CONTENT_TYPE, RELAY_PROVIDER_MESSAGE, RelayProvider, RelayStream, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, UNAUTHORIZED_RELAY_STATUS, UPSTREAM_RELAY_STATUS, WORKSPACE_SECTION_HEADER, agentResultToJSON, assembleResult, attachImages, attachUserImages, buildProviderResult, buildRecapMessage, buildSummaryMessage, collectImageData, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createChannel, createConversation, createConversationManager, createDatabaseConversationStore, createInstruction, createInstructionManager, createMemoryConversationStore, createRelay, createRelayProvider, createScope, createScopeManager, createThinkSplitter, denyCall, estimateMessages, estimateTokens, filterAllowList, handleAgentQueueJob, handleAgentRunnerJob, intersectKeys, isAgentError, isAgentJobError, isConversationError, isConversationSnapshot, isMessage, isProviderAbortError, isProviderError, isSection, joinThinking, messageContract, messageShape, providerRequestContract, providerRequestShape, providerResultContract, providerResultShape, readChunks, readText, relayFrameContract, relayFrameShape, renderFencedFile, renderSection, resolveClose, resolveItem, resolveOpen, sanitizeToken, sanitizeUsage, settleAgentJob, sumUsage, toolCallShape };
 
 //# sourceMappingURL=index.js.map