@orkestrel/agent 0.0.20 → 0.0.21

package/dist/src/core/index.cjs

@@ -11,37 +11,37 @@ let _orkestrel_workspace = require("@orkestrel/workspace");
 let _orkestrel_budget = require("@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
@@ -51,43 +51,46 @@ 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.
@@ -97,8 +100,8 @@ var IMAGE_TOKEN_ESTIMATE = 512;
 //#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)
@@ -117,7 +120,8 @@ var ProviderAbortError = class extends Error {
 	}
 };
 /**
-* 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
@@ -137,13 +141,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
@@ -163,7 +167,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
@@ -181,12 +186,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} /
@@ -205,7 +211,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
@@ -223,13 +230,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`
@@ -247,7 +257,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
@@ -267,8 +278,11 @@ function isAgentError(value) {
 //#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
@@ -322,15 +336,16 @@ function agentResultToJSON(value) {
 	return captured.success ? (0, _orkestrel_contract.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
@@ -357,15 +372,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)
@@ -382,16 +397,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
@@ -423,15 +441,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
@@ -483,9 +503,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
@@ -511,7 +531,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
@@ -597,10 +618,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.
@@ -652,10 +674,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.
@@ -681,13 +703,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`)
@@ -704,13 +726,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)
@@ -727,14 +749,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`)
@@ -753,11 +775,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).
 *
@@ -787,13 +809,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)
@@ -817,11 +840,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.
 *
@@ -840,12 +863,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}.
 *
@@ -866,13 +889,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.
 *
@@ -893,12 +916,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.
@@ -923,36 +946,37 @@ function intersectKeys(parent, child) {
 //#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.
 *
@@ -1118,26 +1142,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`).
@@ -1237,15 +1262,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
@@ -1274,28 +1299,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.
 *
@@ -1374,58 +1400,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).
@@ -1504,10 +1531,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);
@@ -1568,8 +1596,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
@@ -1586,15 +1616,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.
@@ -1946,9 +1976,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
@@ -1957,9 +1988,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
@@ -2040,18 +2071,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
@@ -2094,14 +2127,15 @@ var Authority = class {
 //#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
+* the {@link isConversationSnapshot} and {@link isSection} read-boundary narrows, where a present
+* `calls` must be an array of valid {@link import('@orkestrel/tool').ToolCall}s. Total, never
+* throwing, and never an assertion; the conversation analogue of
 * {@link import('@orkestrel/workspace').isFile}.
 *
 * @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
+* 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
@@ -2109,7 +2143,7 @@ var Authority = class {
 * {@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.
+* 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
@@ -2129,15 +2163,16 @@ function isMessage(value) {
 	return value.images === void 0 || (0, _orkestrel_contract.isArray)(value.images);
 }
 /**
-* 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
@@ -2155,19 +2190,20 @@ function isSection(value) {
 	return (0, _orkestrel_contract.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
@@ -2196,37 +2232,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`).
@@ -2261,7 +2299,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,
@@ -2277,26 +2315,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`).
@@ -2315,13 +2354,32 @@ 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();
@@ -2330,23 +2388,25 @@ var MemoryConversationStore = class {
 //#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
@@ -2386,8 +2446,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`;
@@ -2396,11 +2457,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.
 *
@@ -2460,24 +2521,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.
@@ -2579,16 +2641,16 @@ var ThinkSplitter = class {
 //#region src/core/factories.ts
 /**
 * 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.
@@ -2596,20 +2658,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'
+* import type { ProviderInterface } 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) {
@@ -2617,21 +2698,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})
@@ -2652,7 +2734,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}.
 *
@@ -2660,10 +2742,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`).
@@ -2685,23 +2767,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
@@ -2756,7 +2839,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
@@ -2787,9 +2870,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`
@@ -2835,19 +2918,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`
@@ -2874,10 +2958,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
@@ -2913,18 +2997,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)
@@ -2951,7 +3036,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}
@@ -2977,11 +3062,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.
@@ -3011,7 +3096,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)`
@@ -3041,7 +3126,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.
 *
@@ -3054,9 +3139,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
@@ -3089,21 +3174,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.
 *