@orkestrel/agent 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,4314 @@
+import { booleanShape, createContract, integerShape, isArray, isNumber, isRecord, isString, literalShape, objectShape, optionalShape, rawShape, schemaToParameters, stringShape, unionShape } from "@orkestrel/contract";
+import { createDatabase, createMemoryDriver } from "@orkestrel/database";
+import { createQueue } from "@orkestrel/queue";
+import { createDeferred, createRunner } from "@orkestrel/workflow";
+import { createAbort } from "@orkestrel/abort";
+import { createTimeout } from "@orkestrel/timeout";
+import { Emitter } from "@orkestrel/emitter";
+import { createTokenBudget } from "@orkestrel/budget";
+//#region src/core/constants.ts
+/**
+* The default cap on an {@link AgentInterface} turn's tool iterations — 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 via
+* `AgentOptions.limit`.
+*/
+var DEFAULT_AGENT_LIMIT = 10;
+/**
+* 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`).
+*/
+var DEFAULT_AUTHORITY_ZONE = "default";
+/**
+* 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
+* via {@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;
+/**
+* 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.
+*
+* @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
+* {@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
+* (the `view()` recap framing is distinct from `reference()`'s cross-conversation provenance
+* marker, which is rendered inline since it interpolates the per-call provenance `label`).
+*/
+var CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages] ";
+/**
+* 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}.
+*/
+var THINK_OPEN = "<think>";
+/**
+* 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.
+*/
+var THINK_CLOSE = "</think>";
+/**
+* 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.
+*
+* @remarks
+* `build()` OWNS the workspace render (a `Workspace` / `WorkspaceManager` stays file-focused — no
+* `description` / `framing` 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
+* the documents section uses — placed just after the documents section in the system block.
+*/
+var WORKSPACE_SECTION_HEADER = "## Workspace";
+/**
+* The extension→language table {@link import('./helpers.js').inferLanguage} reads to
+* map a file path's extension to a fenced-code language tag. Covers the common source /
+* markup / data extensions; an unlisted extension falls back to `'text'`.
+*/
+var EXTENSION_TO_LANGUAGE = Object.freeze({
+	ts: "typescript",
+	tsx: "typescript",
+	js: "javascript",
+	jsx: "javascript",
+	mjs: "javascript",
+	cjs: "javascript",
+	json: "json",
+	md: "markdown",
+	html: "html",
+	htm: "html",
+	css: "css",
+	scss: "scss",
+	sass: "sass",
+	less: "less",
+	vue: "vue",
+	svelte: "svelte",
+	py: "python",
+	rb: "ruby",
+	rs: "rust",
+	go: "go",
+	java: "java",
+	kt: "kotlin",
+	swift: "swift",
+	c: "c",
+	cpp: "cpp",
+	h: "c",
+	hpp: "cpp",
+	cs: "csharp",
+	php: "php",
+	sql: "sql",
+	sh: "bash",
+	bash: "bash",
+	zsh: "bash",
+	ps1: "powershell",
+	yaml: "yaml",
+	yml: "yaml",
+	toml: "toml",
+	xml: "xml",
+	svg: "xml",
+	txt: "text"
+});
+/**
+* The name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
+* model calls and the {@link import('./types.js').ToolManagerInterface} registers under.
+*/
+var WORKSPACE_TOOL_NAME = "workspace";
+/**
+* A valid {@link WorkspaceOperation} object — the canonical example embedded VERBATIM in
+* {@link WORKSPACE_TOOL_DESCRIPTION} and pinned by a parity test (it must satisfy the compiled
+* contract's `is`), so the doc example can never drift from a real, contract-valid operation.
+*
+* @remarks
+* A `'write'` op (the most common authoring action): create or overwrite `notes.txt` with
+* `hello`. Frozen so it cannot be mutated in place.
+*/
+var WORKSPACE_TOOL_EXAMPLE = Object.freeze({
+	operation: "write",
+	path: "notes.txt",
+	content: "hello"
+});
+/**
+* The DESCRIPTION {@link import('./factories.js').createWorkspaceTool} advertises — a multi-line
+* guide that teaches a small model how to drive a workspace through the single `operation`-keyed
+* tool.
+*
+* @remarks
+* Mirrors the analogous `WORKFLOW_TOOL_DESCRIPTION` in `@orkestrel/workflow`'s teaching style:
+* names the `operation` discriminant field, enumerates all 13 operations with their FLAT fields,
+* gives a worked example for the common ones (read / write / search / replace / splice), and embeds
+* {@link WORKSPACE_TOOL_EXAMPLE} verbatim (pinned by a parity test). The range edit is the FLAT
+* `'splice'` op — four positive-integer caret components, NOT a nested range — the ergonomic lever
+* a 2B model can fill. The edit / read ops target the ACTIVE workspace (one is auto-created on the
+* first edit when none is active); the `workspaces` / `switch` ops let the model move between
+* workspaces.
+*/
+var WORKSPACE_TOOL_DESCRIPTION = [
+	"Read and edit files in a workspace. Every call is ONE operation, chosen by the \"operation\" field.",
+	"All file operations act on the ACTIVE workspace; use \"workspaces\" then \"switch\" to move between workspaces.",
+	"",
+	"Operations (each takes the fields listed):",
+	"- read     { \"operation\": \"read\", \"path\": \"<file>\" } — return the file's text.",
+	"- list     { \"operation\": \"list\" } — list every file in the active workspace (path, state, size, lines, kind).",
+	"- has      { \"operation\": \"has\", \"path\": \"<file>\" } — whether the file exists.",
+	"- search   { \"operation\": \"search\", \"query\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — find lines matching the query across all files.",
+	"- replace  { \"operation\": \"replace\", \"query\": \"<text>\", \"replacement\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — replace matches across all files.",
+	"- write    { \"operation\": \"write\", \"path\": \"<file>\", \"content\": \"<text>\" } — create or overwrite the whole file.",
+	"- splice   { \"operation\": \"splice\", \"path\": \"<file>\", \"content\": \"<text>\", \"fromLine\": int, \"fromColumn\": int, \"toLine\": int, \"toColumn\": int } — replace a 1-based range (from inclusive, to exclusive) with content.",
+	"- prepend  { \"operation\": \"prepend\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the start of the file.",
+	"- append   { \"operation\": \"append\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the end of the file.",
+	"- move     { \"operation\": \"move\", \"from\": \"<file>\", \"to\": \"<file>\" } — rename / move a file.",
+	"- remove   { \"operation\": \"remove\", \"path\": \"<file>\" } — delete a file.",
+	"- workspaces { \"operation\": \"workspaces\" } — list the workspaces you can switch between (each id, file count, active).",
+	"- switch   { \"operation\": \"switch\", \"id\": \"<id>\" } — make the workspace with that id active (ids come from \"workspaces\").",
+	"",
+	"Notes: lines and columns are 1-based (column 1 is the first character). \"regex\" defaults to false (a literal substring), \"exact\" defaults to true (case-sensitive). \"search\"/\"replace\"/\"splice\" act only on text files. Editing with no active workspace auto-creates one.",
+	"",
+	"Example — write a file:",
+	JSON.stringify(WORKSPACE_TOOL_EXAMPLE)
+].join("\n");
+//#endregion
+//#region src/core/errors.ts
+/**
+* Thrown by a {@link ProviderInterface}'s `stream` when its bound signal aborts
+* mid-flight — carries the {@link ProviderResult} assembled from whatever streamed
+* before the cancel.
+*
+* @remarks
+* Lets a caller recover the partial content (and any tool calls / usage seen so far)
+* on cancellation: `catch` the throw, narrow with {@link isProviderAbortError}, and
+* read `partial`.
+*/
+var ProviderAbortError = class extends Error {
+	partial;
+	constructor(partial) {
+		super("provider stream aborted");
+		this.name = "ProviderAbortError";
+		this.partial = partial;
+	}
+};
+/**
+* Narrow an unknown caught value to a {@link ProviderAbortError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is a {@link ProviderAbortError}
+*
+* @example
+* ```ts
+* try {
+* 	for await (const delta of provider.stream(messages, signal)) render(delta)
+* } catch (error) {
+* 	if (isProviderAbortError(error)) keep(error.partial.content) // recover partial
+* }
+* ```
+*/
+function isProviderAbortError(value) {
+	return value instanceof ProviderAbortError;
+}
+/**
+* Thrown by an agent-job handler (a `createAgentQueue` / `createAgentRunner` job) when
+* its {@link AgentInterface} run ended {@link AgentResult.partial} and the job's
+* `allowPartial` policy is `false` (the default) — carries the partial
+* {@link AgentResult} so the failure stays inspectable.
+*
+* @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
+* lets the Queue's retries re-run the job and a Runner's fail-fast abort its siblings.
+* Set `allowPartial: true` (see `AgentQueueOptions` / `AgentRunnerOptions`) to treat a
+* partial as success instead, in which case this is never thrown. Narrow a caught value
+* with {@link isAgentJobError} to read `partial`.
+*/
+var AgentJobError = class extends Error {
+	/** The partial {@link AgentResult} the cancelled job produced. */
+	partial;
+	constructor(message, partial) {
+		super(message);
+		this.name = "AgentJobError";
+		this.partial = partial;
+	}
+};
+/**
+* Narrow an unknown caught value to an {@link AgentJobError}.
+*
+* @param value - The value to test (typically a `catch` binding or a rejected enqueue)
+* @returns `true` when `value` is an {@link AgentJobError}
+*
+* @example
+* ```ts
+* try {
+* 	await queue.enqueue(job) // retries: 0 → a partial rejects with the error
+* } catch (error) {
+* 	if (isAgentJobError(error)) keep(error.partial.content) // recover the partial content
+* }
+* ```
+*/
+function isAgentJobError(value) {
+	return value instanceof AgentJobError;
+}
+/**
+* Thrown by a {@link ConversationInterface}'s `compact()` when the conversation has no
+* {@link ConversationSummarizer} to fold its messages with — carries a machine-readable
+* `code`.
+*
+* @remarks
+* 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 (§12) and throws this. `code` is
+* `'SUMMARIZER'` (the only condition so far). Narrow a caught value with
+* {@link isConversationError} and branch on `error.code`.
+*/
+var ConversationError = class extends Error {
+	/** The machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer. */
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ConversationError";
+		this.code = code;
+	}
+};
+/**
+* Narrow an unknown caught value to a {@link ConversationError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is a {@link ConversationError}
+*
+* @example
+* ```ts
+* try {
+* 	await conversation.compact()
+* } catch (error) {
+* 	if (isConversationError(error) && error.code === 'SUMMARIZER') addSummarizer()
+* }
+* ```
+*/
+function isConversationError(value) {
+	return value instanceof ConversationError;
+}
+/**
+* An error thrown by the in-memory {@link import('./workspaces/Workspace.js').Workspace} edit
+* surface.
+*
+* @remarks
+* Carries a {@link WorkspaceErrorCode} and an optional `context` bag naming the offending
+* path / range. Thrown for a text-only operation aimed at an image file (`MODALITY` — a
+* ranged read / write, `prepend`, or `append`), an invalid `search` / `replace` regular
+* expression (`PATTERN`), and a structurally invalid ranged-write {@link import('./types.js').Range}
+* (`RANGE` — inverted, or a sub-1 line / column).
+*/
+var WorkspaceError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "WorkspaceError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow an unknown caught value to a {@link WorkspaceError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is a {@link WorkspaceError}
+*
+* @example
+* ```ts
+* try {
+* 	workspace.prepend('icon.png', '// header')
+* } catch (error) {
+* 	if (isWorkspaceError(error) && error.code === 'MODALITY') skipBinary()
+* }
+* ```
+*/
+function isWorkspaceError(value) {
+	return value instanceof WorkspaceError;
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* The shape of a {@link import('./types.js').WorkspaceOperation} — a descriptive tagged union over
+* the 13 workspace edit / read / navigation operations, discriminated by the `operation` literal
+* (never a bare `kind`; AGENTS §4.8). Each variant leads with its `operation` discriminant then its
+* FLAT fields, every field via `stringShape` / `optionalShape` / `integerShape({ min: 1 })` /
+* `booleanShape`, each carrying a strong field-level `description`.
+*
+* @remarks
+* The union compiles to an `anyOf` JSON Schema + a `unionOf` guard + a first-match parser
+* automatically ({@link import('./factories.js').createWorkspaceTool} types the result to the
+* hand-written `WorkspaceOperation`). `limit` and the four `'splice'` caret components are POSITIVE
+* integers (`integerShape({ min: 1 })`); `regex` / `exact` are `optionalShape(booleanShape(...))`.
+* The two REGISTRY arms — `workspaces` (list the workspaces the model can move between) and `switch`
+* (re-point the active one by `id`) — let a model DISCOVER then CHOOSE which workspace the edit /
+* read arms target. The descriptions are the small-model ergonomic lever — they ride into the
+* advertised schema so a model authoring an operation gets per-field guidance.
+*/
+var workspaceToolShape = unionShape(objectShape({
+	operation: literalShape(["read"], { description: "Read a whole text file's text by path." }),
+	path: stringShape({ description: "The path of the file to read." })
+}), objectShape({ operation: literalShape(["list"], { description: "List every file in the workspace." }) }), objectShape({
+	operation: literalShape(["has"], { description: "Check whether a file exists at the path." }),
+	path: stringShape({ description: "The path to check for." })
+}), objectShape({
+	operation: literalShape(["search"], { description: "Search every text file for a query, returning each hit." }),
+	query: stringShape({ description: "The text (or regular-expression source) to search for." }),
+	regex: optionalShape(booleanShape({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
+	exact: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
+	limit: optionalShape(integerShape({
+		min: 1,
+		description: "Stop after this many matches across all files. Omitted means unlimited."
+	}))
+}), objectShape({
+	operation: literalShape(["replace"], { description: "Replace a query with a replacement across every text file." }),
+	query: stringShape({ description: "The text (or regular-expression source) to replace." }),
+	replacement: stringShape({ description: "The text to substitute for each match." }),
+	regex: optionalShape(booleanShape({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
+	exact: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
+	limit: optionalShape(integerShape({
+		min: 1,
+		description: "Stop after this many replacements across all files. Omitted means unlimited."
+	}))
+}), objectShape({
+	operation: literalShape(["write"], { description: "Create or overwrite a whole file with content." }),
+	path: stringShape({ description: "The path of the file to write." }),
+	content: stringShape({ description: "The full new contents of the file." })
+}), objectShape({
+	operation: literalShape(["splice"], { description: "Replace a 1-based range of an existing text file (from inclusive, to exclusive) with content." }),
+	path: stringShape({ description: "The path of the text file to edit." }),
+	content: stringShape({ description: "The text to splice in place of the range." }),
+	fromLine: integerShape({
+		min: 1,
+		description: "The 1-based start line of the range (inclusive)."
+	}),
+	fromColumn: integerShape({
+		min: 1,
+		description: "The 1-based start column of the range (inclusive; column 1 is the first character)."
+	}),
+	toLine: integerShape({
+		min: 1,
+		description: "The 1-based end line of the range (exclusive)."
+	}),
+	toColumn: integerShape({
+		min: 1,
+		description: "The 1-based end column of the range (exclusive)."
+	})
+}), objectShape({
+	operation: literalShape(["prepend"], { description: "Add content to the start of a file (creating it when absent)." }),
+	path: stringShape({ description: "The path of the file to prepend to." }),
+	content: stringShape({ description: "The text to add at the start of the file." })
+}), objectShape({
+	operation: literalShape(["append"], { description: "Add content to the end of a file (creating it when absent)." }),
+	path: stringShape({ description: "The path of the file to append to." }),
+	content: stringShape({ description: "The text to add at the end of the file." })
+}), objectShape({
+	operation: literalShape(["move"], { description: "Rename or move a file (overwriting an occupied target)." }),
+	from: stringShape({ description: "The current path of the file." }),
+	to: stringShape({ description: "The new path for the file." })
+}), objectShape({
+	operation: literalShape(["remove"], { description: "Delete a file from the workspace." }),
+	path: stringShape({ description: "The path of the file to remove." })
+}), objectShape({ operation: literalShape(["workspaces"], { description: "List the workspaces you can move between (each id, file count, and whether it is active), so you can pick an id to switch to." }) }), objectShape({
+	operation: literalShape(["switch"], { description: "Switch the active workspace to the one with this id (get ids from the \"workspaces\" operation). Edit and read operations then target it." }),
+	id: stringShape({ description: "The id of the workspace to make active (from the \"workspaces\" listing)." })
+}));
+//#endregion
+//#region src/core/conversations/Conversation.ts
+/**
+* A conversation grouping messages ABOVE a flat message store — a live uncompacted tail it
+* OWNS DIRECTLY plus compacted, summarized {@link SectionInterface}s and a regenerated rollup
+* `summary`, with on-demand `rehydrate` and substring `search`, driven by a provider-agnostic
+* {@link ConversationSummarizer} seam (so `core` never imports a provider).
+*
+* @remarks
+* - **Live tail + sections.** The conversation OWNS its live tail DIRECTLY — `#messages` is an
+*   insertion-ordered `Map` of immutable {@link MessageInterface}s keyed by their minted id
+*   (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
+*   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
+*   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.
+* - **`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
+*   `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.
+* - **`rehydrate(id)` / `search(query)`.** `rehydrate` returns a section's full original
+*   messages (`[]` for an unknown id) and emits `rehydrate` — a pure read (v1 never
+*   auto-reinserts). `search` is a case-insensitive substring scan of `content` across ALL
+*   messages (every section's originals + the live tail).
+* - **Observable (§13).** The owned {@link emitter} ({@link ConversationEventMap}) carries
+*   `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.
+*
+* @example
+* ```ts
+* const conversation = new Conversation({ summarize: async (m) => `recap of ${m.length}` })
+* conversation.add([
+* 	{ role: 'user', content: 'Hello' },
+* 	{ role: 'assistant', content: 'Hi there' },
+* ])
+* const section = await conversation.compact() // folds both into one summarized section
+* conversation.view() // [{ role: 'assistant', content: 'recap of 2' }] — the live tail is empty
+* conversation.summary // 'recap of 1' — the rollup over the one section
+* ```
+*/
+var Conversation = class {
+	#id;
+	#emitter;
+	#summarize;
+	#keep;
+	#sections = [];
+	#summary;
+	#messages = /* @__PURE__ */ new Map();
+	constructor(options, seed) {
+		this.#id = seed?.id ?? options?.id ?? crypto.randomUUID();
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#summarize = options?.summarize;
+		this.#keep = options?.keep ?? 0;
+		if (seed) {
+			this.#summary = seed.summary;
+			for (const section of seed.sections) this.#sections.push(section);
+			for (const message of seed.messages) this.#messages.set(message.id, message);
+		}
+	}
+	get id() {
+		return this.#id;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get summary() {
+		return this.#summary;
+	}
+	get sections() {
+		return [...this.#sections];
+	}
+	get summarizable() {
+		return this.#summarize !== void 0;
+	}
+	get count() {
+		return this.#messages.size;
+	}
+	add(input) {
+		if (isArray(input)) return input.map((one) => this.#create(one));
+		return this.#create(input);
+	}
+	message(id) {
+		return this.#messages.get(id);
+	}
+	messages() {
+		return [...this.#messages.values()];
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = false;
+			for (const id of ids) if (this.#messages.delete(id)) removed = true;
+			return removed;
+		}
+		return this.#messages.delete(ids);
+	}
+	clear() {
+		this.#messages.clear();
+	}
+	view() {
+		return [...this.#sections.map((section) => this.#recapMessage(section)), ...this.#messages.values()];
+	}
+	async compact(options) {
+		const summarize = this.#summarize;
+		if (summarize === void 0) throw new ConversationError("SUMMARIZER", "cannot compact a conversation without a summarizer");
+		const keep = options?.keep ?? this.#keep;
+		const live = [...this.#messages.values()];
+		const fold = keep <= 0 ? live.length : live.length - keep;
+		if (fold <= 0) return void 0;
+		const slice = live.slice(0, fold);
+		const summary = await summarize(slice);
+		const section = {
+			id: crypto.randomUUID(),
+			summary,
+			messages: slice
+		};
+		for (const message of slice) this.#messages.delete(message.id);
+		this.#sections.push(section);
+		this.#summary = await summarize(this.#sections.map((one) => this.#summaryMessage(one)));
+		this.#emitter.emit("summary", this.#summary);
+		this.#emitter.emit("compact", section);
+		return section;
+	}
+	rehydrate(id) {
+		const section = this.#sections.find((one) => one.id === id);
+		this.#emitter.emit("rehydrate", id);
+		return section === void 0 ? [] : section.messages;
+	}
+	search(query) {
+		const needle = query.toLowerCase();
+		return [...this.#sections.flatMap((section) => section.messages), ...this.#messages.values()].filter((message) => message.content.toLowerCase().includes(needle));
+	}
+	reference(options) {
+		const lines = [`[Reference — conversation "${options?.label ?? this.#id}" — NOT part of this conversation]`];
+		if (options?.summary !== false && this.#summary !== void 0) lines.push(`Summary: ${this.#summary}`);
+		const messages = options?.messages ?? [];
+		if (messages.length > 0) {
+			lines.push("Relevant messages:");
+			for (const message of messages) lines.push(`- ${message.role}: ${message.content}`);
+		}
+		return lines.join("\n");
+	}
+	snapshot() {
+		return {
+			id: this.#id,
+			...this.#summary === void 0 ? {} : { summary: this.#summary },
+			sections: this.sections,
+			messages: this.messages()
+		};
+	}
+	#summaryMessage(section) {
+		return {
+			id: section.id,
+			role: "assistant",
+			content: section.summary
+		};
+	}
+	#recapMessage(section) {
+		return {
+			id: section.id,
+			role: "assistant",
+			content: `${CONVERSATION_RECAP_PREFIX}${section.summary}`
+		};
+	}
+	#create(input) {
+		const message = {
+			id: crypto.randomUUID(),
+			role: input.role,
+			content: input.content,
+			...input.calls === void 0 ? {} : { calls: input.calls },
+			...input.images === void 0 ? {} : { images: input.images }
+		};
+		this.#messages.set(message.id, message);
+		return message;
+	}
+};
+//#endregion
+//#region src/core/conversations/ConversationManager.ts
+/**
+* The registry of {@link Conversation}s keyed by `id`, in insertion order, WITH an active pointer
+* — the §9 store over the conversation layer PLUS the `active` / `switch` seam the
+* {@link import('../AgentContext.js').AgentContext} renders. Event-free (a registry, like
+* {@link import('../workspaces/WorkspaceManager.js').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,
+*   `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
+*   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 (§9.2) — `true` when any 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`).
+*
+* @example
+* ```ts
+* const manager = new ConversationManager({ summarize: async (m) => `recap of ${m.length}` })
+* const conversation = manager.add() // auto-activates — active === conversation
+* manager.add({ id: 'scratch' }) // leaves active unchanged
+* manager.switch('scratch') // re-points active to the 'scratch' conversation
+* manager.count // 2
+* ```
+*/
+var ConversationManager = class {
+	#conversations = /* @__PURE__ */ new Map();
+	#active;
+	#summarize;
+	#keep;
+	#store;
+	constructor(options) {
+		this.#summarize = options?.summarize;
+		this.#keep = options?.keep ?? 0;
+		this.#store = options?.store;
+	}
+	get count() {
+		return this.#conversations.size;
+	}
+	get active() {
+		return this.#active === void 0 ? void 0 : this.#conversations.get(this.#active);
+	}
+	conversation(id) {
+		return this.#conversations.get(id);
+	}
+	conversations() {
+		return [...this.#conversations.values()];
+	}
+	add(input) {
+		const conversation = new Conversation({
+			...input?.id === void 0 ? {} : { id: input.id },
+			...input?.on === void 0 ? {} : { on: input.on },
+			summarize: input?.summarize ?? this.#summarize,
+			keep: input?.keep ?? this.#keep
+		}, input?.snapshot);
+		this.#conversations.set(conversation.id, conversation);
+		if (this.#active === void 0) this.#active = conversation.id;
+		return conversation;
+	}
+	switch(id) {
+		const conversation = this.#conversations.get(id);
+		if (conversation === void 0) return void 0;
+		this.#active = id;
+		return conversation;
+	}
+	async open(id) {
+		const existing = this.#conversations.get(id);
+		if (existing !== void 0) {
+			this.#active = id;
+			return existing;
+		}
+		if (this.#store === void 0) return void 0;
+		const snapshot = await this.#store.get(id);
+		if (snapshot === void 0) return void 0;
+		const conversation = this.add({ snapshot });
+		this.#active = conversation.id;
+		return conversation;
+	}
+	async save(id) {
+		const conversation = this.#conversations.get(id);
+		if (this.#store === void 0 || conversation === void 0) return false;
+		await this.#store.set(conversation.snapshot());
+		return true;
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = false;
+			for (const id of ids) if (this.#drop(id)) removed = true;
+			return removed;
+		}
+		return this.#drop(ids);
+	}
+	clear() {
+		this.#conversations.clear();
+		this.#active = void 0;
+	}
+	#drop(id) {
+		const removed = this.#conversations.delete(id);
+		if (removed && this.#active === id) this.#active = void 0;
+		return removed;
+	}
+};
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Infer a fenced-code language tag from a file path's extension — what a workspace text file
+* (or the {@link fencedFile} renderer) renders its content block as.
+*
+* @remarks
+* Reads the extension after the last `.` (case-insensitive) and maps it through a
+* fixed extension→language table. An unknown extension, or a path with no extension,
+* falls back to `'text'` (a safe, language-agnostic fence). Total — never throws.
+*
+* @param path - The document's file path (e.g. `'src/main.ts'`)
+* @returns The inferred language tag (e.g. `'typescript'`), or `'text'` when unknown
+*
+* @example
+* ```ts
+* inferLanguage('src/main.ts') // 'typescript'
+* inferLanguage('README.md') // 'markdown'
+* inferLanguage('LICENSE') // 'text'
+* ```
+*/
+function inferLanguage(path) {
+	const dot = path.lastIndexOf(".");
+	if (dot === -1) return "text";
+	return EXTENSION_TO_LANGUAGE[path.slice(dot + 1).toLowerCase()] ?? "text";
+}
+/**
+* Filter 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.
+*
+* @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).
+* - 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
+* throws. Keys are matched by a `Set` for O(1) membership, so a large list is cheap.
+*
+* @typeParam T - The item type being filtered
+* @param allow - The allow-list of keys (`undefined` ⇒ all, `[]` ⇒ none, else only-listed)
+* @param items - The items to filter (returned unchanged when `allow` is `undefined`)
+* @param key - Extracts the key an item is matched on (e.g. an instruction's `name`)
+* @returns The items that pass the allow-list, in their original order
+*
+* @example
+* ```ts
+* const items = [{ name: 'a' }, { name: 'b' }]
+* filterAllowList(undefined, items, (i) => i.name) // [{ name: 'a' }, { name: 'b' }] (all)
+* filterAllowList([], items, (i) => i.name) // [] (none)
+* filterAllowList(['b'], items, (i) => i.name) // [{ name: 'b' }] (only listed)
+* ```
+*/
+function filterAllowList(allow, items, key) {
+	if (allow === void 0) return items;
+	if (allow.length === 0) return [];
+	const set = new Set(allow);
+	return items.filter((item) => set.has(key(item)));
+}
+/**
+* Estimate 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).
+*
+* @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,
+* 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)
+* @returns The estimated token count (`ceil(text.length / 4)`; `0` for empty text)
+*
+* @example
+* ```ts
+* estimateTokens('') // 0
+* estimateTokens('hello') // 2  (ceil(5 / 4))
+* estimateTokens('a'.repeat(40)) // 10
+* ```
+*/
+function estimateTokens(text) {
+	return Math.ceil(text.length / 4);
+}
+/**
+* Estimate the context-token footprint of a batch of messages — the default `consume`
+* estimator for an agent's context `BudgetInterface` (a budgets surface's tracking contract)
+* (the {@link import('./types.js').AgentOptions} `window`).
+*
+* @remarks
+* Sums {@link estimateTokens} over each message's `content` (the `ceil(length / 4)` char
+* heuristic), so it is 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 `consume` to `createBudget` instead. Total — never throws.
+*
+* @param messages - The messages to estimate (a turn's appended assistant + tool messages)
+* @returns The summed estimated token count (`Σ estimateTokens(m.content)`; `0` when empty)
+*
+* @example
+* ```ts
+* estimateMessages([]) // 0
+* estimateMessages([{ id: '1', role: 'user', content: 'hello' }]) // 2
+* ```
+*/
+function estimateMessages(messages) {
+	return messages.reduce((sum, message) => sum + estimateTokens(message.content), 0);
+}
+/**
+* Run one rehydrated agent and apply 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.
+*
+* @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); with `allowPartial` it RESOLVES
+* the partial as success instead. A natural finish ALWAYS resolves with its result.
+*
+* @param agent - The rehydrated {@link AgentInterface} to run to its {@link AgentResult}
+* @param allowPartial - When `true`, a partial result resolves as success; when `false`
+*   (the default policy), a partial result throws an {@link AgentJobError}
+* @returns The agent's {@link AgentResult} (a natural finish, or a partial when `allowPartial`)
+* @throws {AgentJobError} When the run ended `partial` and `allowPartial` is `false`
+*
+* @example
+* ```ts
+* const result = await settleAgentJob(registry.build(input, signal), false)
+* ```
+*/
+async function settleAgentJob(agent, allowPartial) {
+	const result = await agent.generate();
+	if (result.partial && !allowPartial) throw new AgentJobError("agent job ended partial", result);
+	return result;
+}
+/**
+* Whether a {@link FileContent} is the TEXT arm — the narrowing guard for the text-vs-binary
+* union (AGENTS §14: narrow an untyped arm via a guard, never an `as`).
+*
+* @remarks
+* Tests `'text' in content` structurally — there is no `modality` discriminant. A `true`
+* narrows `content` to `{ text: string; language: string }`, unlocking `.text` / `.language`.
+* Total — never throws.
+*
+* @param content - The file content to test
+* @returns `true` when `content` is the text arm (carries `text` + `language`)
+*
+* @example
+* ```ts
+* if (isText(file.content)) file.content.text // the literal text + .language
+* ```
+*/
+function isText(content) {
+	return "text" in content;
+}
+/**
+* Whether a {@link FileContent} is the BINARY arm — the narrowing guard for the text-vs-binary
+* union (AGENTS §14: narrow an untyped arm via a guard, never an `as`).
+*
+* @remarks
+* Tests `'data' in content` structurally — there is no `modality` discriminant. A `true`
+* narrows `content` to `{ data: string; mime: BinaryMIME }`, unlocking `.data` / `.mime`. An
+* image is a binary whose `mime` starts with `image/` ({@link isImage}). Total — never throws.
+*
+* @param content - The file content to test
+* @returns `true` when `content` is the binary arm (carries base64 `data` + `mime`)
+*
+* @example
+* ```ts
+* if (isBinary(file.content)) file.content.data // the base64 payload + .mime
+* ```
+*/
+function isBinary(content) {
+	return "data" in content;
+}
+/**
+* Whether a {@link FileContent} is an IMAGE — a {@link isBinary} arm whose `mime` is an
+* `image/*` type (an image is just a binary with an image MIME).
+*
+* @remarks
+* Narrows to the binary arm first, then checks the `image/` MIME prefix — so a future
+* non-image binary (a PDF, `'application/pdf'`) is binary but NOT an image. Total — never
+* throws.
+*
+* @param content - The file content to test
+* @returns `true` when `content` is a binary arm with an `image/*` MIME
+*
+* @example
+* ```ts
+* isImage({ data: '<base64>', mime: 'image/png' }) // true
+* isImage({ text: 'hi', language: 'text' }) // false
+* ```
+*/
+function isImage(content) {
+	return isBinary(content) && content.mime.startsWith("image/");
+}
+/**
+* Whether an `unknown` is structurally a {@link FileInterface} record — the per-file step of the
+* {@link isWorkspaceSnapshot} read-boundary narrow (AGENTS §14: narrow an untrusted storage read
+* via a guard, never an `as`).
+*
+* @remarks
+* A total guard (it NEVER throws — adversarial input returns `false`). It checks the file's SHAPE:
+* a record with a `string` `path`, a `string` `state`, `number` `size` / `lines`, and a `content`
+* that is EITHER the TEXT arm (`{ text: string; language: string }`) OR the BINARY arm
+* (`{ data: string; mime: string }`) — the tagless {@link FileContent} union, told apart
+* structurally exactly as {@link isText} / {@link isBinary} do (no `modality` discriminant). Enough
+* to safely impose the {@link FileInterface} type at a storage boundary WITHOUT a cast; the `mime`
+* is left as a broad `string` here (an open {@link BinaryMIME}, so any storage-read MIME string is
+* accepted defensively rather than rejected against the current literal set).
+*
+* @param value - The value to test (one element of a snapshot's opaque `files` array)
+* @returns `true` when `value` has the structural shape of a {@link FileInterface}
+*
+* @example
+* ```ts
+* isFile({ path: 'a.ts', content: { text: 'x', language: 'typescript' }, state: 'created', size: 1, lines: 1 }) // true
+* isFile({ path: 'a.png', content: { data: 'AAAA', mime: 'image/png' }, state: 'created', size: 3, lines: 0 }) // true
+* isFile({ path: 'a.ts' }) // false (missing content / state / size / lines)
+* ```
+*/
+function isFile(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.path) || !isString(value.state)) return false;
+	if (!isNumber(value.size) || !isNumber(value.lines)) return false;
+	if (!isRecord(value.content)) return false;
+	const text = isString(value.content.text) && isString(value.content.language);
+	const binary = isString(value.content.data) && isString(value.content.mime);
+	return text || binary;
+}
+/**
+* Narrow an `unknown` to a {@link WorkspaceSnapshot} — the AGENTS §14 boundary guard for an
+* UNTRUSTED snapshot read (a storage row a
+* {@link import('./workspaces/stores/DatabaseWorkspaceStore.js').DatabaseWorkspaceStore} reads back
+* from its opaque JSON column, a snapshot loaded from disk).
+*
+* @remarks
+* A total guard (it NEVER throws — adversarial input returns `false`). It checks the snapshot's
+* SHAPE: a `string` `id` and a `files` array EVERY element of which is a valid {@link FileInterface}
+* record ({@link isFile}) — enough to safely impose the {@link WorkspaceSnapshot} type at a storage
+* boundary WITHOUT a cast. The structural twin of
+* the analogous `isWorkflowSnapshot` in `@orkestrel/workflow`. A malformed blob (a non-record, a
+* missing / non-string `id`, a non-array `files`, or any malformed file element) resolves `false`,
+* so a {@link import('./workspaces/stores/DatabaseWorkspaceStore.js').DatabaseWorkspaceStore} read
+* yields `undefined` rather than a broken workspace.
+*
+* @param value - The value to test (an opaque storage read)
+* @returns `true` when `value` has the structural shape of a {@link WorkspaceSnapshot}
+*
+* @example
+* ```ts
+* isWorkspaceSnapshot({ id: 'w1', files: [] }) // true
+* isWorkspaceSnapshot({ id: 'w1', files: 'nope' }) // false
+* isWorkspaceSnapshot({ files: [] }) // false (missing id)
+* ```
+*/
+function isWorkspaceSnapshot(value) {
+	return isRecord(value) && isString(value.id) && isArray(value.files) && value.files.every(isFile);
+}
+/**
+* Whether an `unknown` is structurally a {@link ToolCall} record — the per-call step of the
+* {@link isMessage} read-boundary narrow (AGENTS §14: narrow an untrusted storage read via a
+* guard, never an `as`).
+*
+* @remarks
+* A total guard (it NEVER throws — adversarial input returns `false`). It checks the call's
+* SHAPE: a record with a `string` `id`, a `string` `name`, and a record `arguments` — the real
+* {@link ToolCall} shape a restored assistant turn replays to a provider. This is the ASI06
+* fail-CLOSED element check: a tampered persisted call (`null`, a bare string, a non-record
+* `arguments`) fails the guard, so {@link isMessage} — and through it
+* {@link isConversationSnapshot} — rejects the whole snapshot and a poisoned store row reads
+* back as ABSENT instead of replaying a malformed call into a chat template.
+*
+* @param value - The value to test (one element of an assistant message's `calls`)
+* @returns `true` when `value` has the structural shape of a {@link ToolCall}
+*
+* @example
+* ```ts
+* isToolCall({ id: 'c1', name: 'search', arguments: { q: 'acme' } }) // true
+* isToolCall({ id: 'c1', name: 'search' }) // false (missing arguments)
+* isToolCall({ id: 'c1', name: 123, arguments: {} }) // false (non-string name)
+* ```
+*/
+function isToolCall(value) {
+	if (!isRecord(value)) return false;
+	return isString(value.id) && isString(value.name) && isRecord(value.arguments);
+}
+/**
+* Project a {@link ToolResult} into the MCP `CallToolResult` shape — a top-level `error`
+* maps to a single `isError: true` text block (the failure reason), otherwise the `value`
+* is JSON-stringified into a single text block with no `isError`.
+*
+* @param result - The {@link ToolResult} to project (as returned by {@link import('./tools/ToolManager.js').ToolManager.execute})
+* @returns The equivalent {@link ToolCallResult}
+*
+* @example
+* ```ts
+* buildToolResult({ id: 'c1', name: 'search', error: 'max depth' })
+* // { content: [{ type: 'text', text: 'max depth' }], isError: true }
+* buildToolResult({ id: 'c1', name: 'search', value: { count: 1 } })
+* // { content: [{ type: 'text', text: '{"count":1}' }] }
+* ```
+*/
+function buildToolResult(result) {
+	if (result.error !== void 0) return {
+		content: [{
+			type: "text",
+			text: result.error
+		}],
+		isError: true
+	};
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(result.value)
+	}] };
+}
+/**
+* Whether an `unknown` is structurally a {@link MessageInterface} record — the per-message step of
+* the {@link isConversationSnapshot} read-boundary narrow (AGENTS §14: narrow an untrusted storage
+* read via a guard, never an `as`). The conversation analogue of {@link 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 {@link ToolCall} ({@link isToolCall} — the
+* ASI06 fail-closed deepening: a tampered `calls` element rejects the message, so the snapshot
+* reads back as absent rather than replaying a malformed call) and an `images` that is an array
+* (an absent optional passes). The `role` is left as a broad `string` here (an open
+* {@link import('./types.js').MessageRole}, so any storage-read role string is accepted
+* defensively rather than rejected against the current literal set) — exactly as {@link isFile}
+* accepts a broad `state` / `mime`. Enough to safely impose the {@link MessageInterface} type at
+* a storage boundary WITHOUT a cast.
+*
+* @param value - The value to test (one element of a snapshot's `messages` / a section's `messages`)
+* @returns `true` when `value` has the structural shape of a {@link MessageInterface}
+*
+* @example
+* ```ts
+* isMessage({ id: '1', role: 'user', content: 'hi' }) // true
+* isMessage({ id: '1', role: 'assistant', content: '', calls: [] }) // true
+* isMessage({ id: '1', role: 'user' }) // false (missing content)
+* isMessage({ id: '1', role: 'assistant', content: '', calls: [null] }) // false (malformed call)
+* ```
+*/
+function isMessage(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.id) || !isString(value.role) || !isString(value.content)) return false;
+	if (value.calls !== void 0 && !(isArray(value.calls) && value.calls.every(isToolCall))) return false;
+	return value.images === void 0 || isArray(value.images);
+}
+/**
+* Whether an `unknown` is structurally a {@link SectionInterface} record — the per-section step of
+* the {@link isConversationSnapshot} read-boundary narrow (AGENTS §14: narrow an untrusted storage
+* read via a guard, never an `as`).
+*
+* @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
+* of which is a valid {@link MessageInterface} record ({@link isMessage}). Enough to safely impose
+* the {@link SectionInterface} type at a storage boundary WITHOUT a cast.
+*
+* @param value - The value to test (one element of a snapshot's `sections` array)
+* @returns `true` when `value` has the structural shape of a {@link SectionInterface}
+*
+* @example
+* ```ts
+* isSection({ id: 's', summary: 'recap', messages: [{ id: '1', role: 'user', content: 'hi' }] }) // true
+* isSection({ id: 's', summary: 'recap', messages: 'nope' }) // false
+* isSection({ id: 's', messages: [] }) // false (missing summary)
+* ```
+*/
+function isSection(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.id) || !isString(value.summary)) return false;
+	return isArray(value.messages) && value.messages.every(isMessage);
+}
+/**
+* Narrow an `unknown` to a {@link ConversationSnapshot} — the AGENTS §14 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 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 SectionInterface} ({@link isSection}), and a `messages` array EVERY element of which is a
+* valid {@link MessageInterface} ({@link isMessage}) — enough to safely impose the
+* {@link ConversationSnapshot} type at a storage boundary WITHOUT a cast. The structural twin of
+* {@link 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
+* {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
+* read yields `undefined` rather than a broken conversation.
+*
+* @param value - The value to test (an opaque storage read)
+* @returns `true` when `value` has the structural shape of a {@link ConversationSnapshot}
+*
+* @example
+* ```ts
+* isConversationSnapshot({ id: 'c1', sections: [], messages: [] }) // true
+* isConversationSnapshot({ id: 'c1', summary: 'recap', sections: [], messages: [] }) // true
+* isConversationSnapshot({ id: 'c1', sections: 'nope', messages: [] }) // false
+* isConversationSnapshot({ sections: [], messages: [] }) // false (missing id)
+* ```
+*/
+function isConversationSnapshot(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.id)) return false;
+	if (value.summary !== void 0 && !isString(value.summary)) return false;
+	if (!isArray(value.sections) || !value.sections.every(isSection)) return false;
+	return isArray(value.messages) && value.messages.every(isMessage);
+}
+/**
+* Compute the byte size of a {@link FileContent} — the `size` a {@link FileInterface} derives
+* once when built.
+*
+* @remarks
+* Dispatches on {@link isText}: a text arm is its UTF-8 byte length (via `new
+* TextEncoder().encode(text).length` — the standard Web/Node API, so a multi-byte
+* character like `'é'` or `'😀'` counts as its real encoded bytes, NOT its character
+* count); a binary arm is the decoded payload byte length of its base64 `data` (via
+* {@link decodedSize}, computed arithmetically — no `atob` / `Buffer`). Total — never throws.
+*
+* @param content - The file content to size
+* @returns The byte size (UTF-8 bytes for text; decoded payload bytes for binary)
+*
+* @example
+* ```ts
+* computeSize({ text: 'café', language: 'text' }) // 5 (é is two bytes)
+* computeSize({ data: 'AAAA', mime: 'image/png' }) // 3
+* ```
+*/
+function computeSize(content) {
+	if (isText(content)) return new TextEncoder().encode(content.text).length;
+	return decodedSize(content.data);
+}
+/**
+* Count the lines of a {@link FileContent} — the `lines` a {@link FileInterface} derives once
+* when built.
+*
+* @remarks
+* A text arm's line count is `0` for the empty string, otherwise one more than the
+* number of newline (`\n`) separators it contains — so `'a'` is one line, `'a\nb'` is two,
+* and a trailing newline `'a\n'` counts the empty final line as two. A binary arm has no
+* lines and returns `0`. Total — never throws.
+*
+* @param content - The file content to count lines for
+* @returns The line count (text line count; `0` for a binary arm or empty text)
+*
+* @example
+* ```ts
+* countLines({ text: '', language: 'text' }) // 0
+* countLines({ text: 'a\nb\nc', language: 'text' }) // 3
+* countLines({ data: 'AAAA', mime: 'image/png' }) // 0
+* ```
+*/
+function countLines(content) {
+	if (!isText(content)) return 0;
+	if (content.text.length === 0) return 0;
+	let count = 1;
+	for (const character of content.text) if (character === "\n") count += 1;
+	return count;
+}
+/**
+* Compute the decoded byte length of a base64 string ARITHMETICALLY — the image-payload
+* sizing primitive {@link computeSize} uses, with no `atob` / `Buffer` decode.
+*
+* @remarks
+* A base64 string encodes each group of 3 input bytes as 4 characters, so a well-formed
+* string's length is a multiple of 4 and its decoded length is `(length / 4) * 3` MINUS
+* the trailing `=` padding (one `=` ⇒ the last group held 2 bytes, two `==` ⇒ 1 byte).
+* The padding is counted from the trailing `=` characters, so both the `=` and `==` cases
+* are handled. The empty string decodes to `0`. Total — never throws (a malformed,
+* non-multiple-of-4 length still yields a defined non-negative estimate via `floor`).
+*
+* @param base64 - The base64-encoded string (e.g. an image's `data`)
+* @returns The decoded payload's byte length
+*
+* @example
+* ```ts
+* decodedSize('') // 0
+* decodedSize('AAAA') // 3  (no padding)
+* decodedSize('AAA=') // 2  (one '=')
+* decodedSize('AA==') // 1  (two '=')
+* ```
+*/
+function decodedSize(base64) {
+	if (base64.length === 0) return 0;
+	let padding = 0;
+	if (base64.endsWith("==")) padding = 2;
+	else if (base64.endsWith("=")) padding = 1;
+	return Math.floor(base64.length / 4) * 3 - padding;
+}
+/**
+* Whether a {@link Range} is STRUCTURALLY valid — the predicate a ranged `write` checks
+* before applying (a `false` here is the `RANGE` throw).
+*
+* @remarks
+* Structural validity is independent of any content: every component must be `>= 1`
+* (1-based lines and columns), and `start` must not come after `end` (an inverted range
+* is invalid). A range that is structurally valid but reaches PAST the end of a specific
+* text is still valid — it is {@link clampRange}d to the bounds when applied, not rejected.
+* Total — never throws.
+*
+* @param range - The range to validate
+* @returns `true` when every component is `>= 1` and `start` is at or before `end`
+*
+* @example
+* ```ts
+* isValidRange({ start: { line: 1, column: 1 }, end: { line: 2, column: 1 } }) // true
+* isValidRange({ start: { line: 2, column: 1 }, end: { line: 1, column: 1 } }) // false (inverted)
+* isValidRange({ start: { line: 0, column: 1 }, end: { line: 1, column: 1 } }) // false (sub-1 line)
+* ```
+*/
+function isValidRange(range) {
+	if (range.start.line < 1 || range.start.column < 1) return false;
+	if (range.end.line < 1 || range.end.column < 1) return false;
+	if (range.start.line > range.end.line) return false;
+	return !(range.start.line === range.end.line && range.start.column > range.end.column);
+}
+/**
+* Clamp a 1-based {@link Position} to the bounds of `text` — every component pinned into a
+* caret that actually exists in the content.
+*
+* @remarks
+* `line` is pinned to `[1, lineCount]` and `column` to `[1, lineLength + 1]` of the
+* resolved line (column `lineLength + 1` is the caret just past the line's last
+* character). So a position beyond the end of the text resolves to the end rather than
+* overflowing. Total — never throws.
+*
+* @param text - The text the position addresses
+* @param position - The 1-based position to clamp
+* @returns The clamped {@link Position}
+*
+* @example
+* ```ts
+* clampPosition('ab\ncd', { line: 9, column: 9 }) // { line: 2, column: 3 } (end of 'cd')
+* ```
+*/
+function clampPosition(text, position) {
+	const lines = text.split("\n");
+	const line = Math.max(1, Math.min(position.line, lines.length));
+	const lineText = lines[line - 1] ?? "";
+	return {
+		line,
+		column: Math.max(1, Math.min(position.column, lineText.length + 1))
+	};
+}
+/**
+* Clamp both ends of a {@link Range} to the bounds of `text` — the actual span a ranged
+* read / write applies (and the `range` a {@link import('./types.js').ReadResult} reports).
+*
+* @remarks
+* Clamps `start` and `end` independently via {@link clampPosition}, so a range reaching
+* past the end of the content is trimmed to the content's end. Total — never throws.
+*
+* @param text - The text the range addresses
+* @param range - The 1-based range to clamp
+* @returns The clamped {@link Range}
+*
+* @example
+* ```ts
+* clampRange('ab\ncd', { start: { line: 1, column: 1 }, end: { line: 9, column: 9 } })
+* // { start: { line: 1, column: 1 }, end: { line: 2, column: 3 } }
+* ```
+*/
+function clampRange(text, range) {
+	return {
+		start: clampPosition(text, range.start),
+		end: clampPosition(text, range.end)
+	};
+}
+/**
+* Convert a 1-based {@link Position} to a 0-based string offset into `text` — the indexing
+* primitive {@link sliceRange} / {@link spliceRange} use, clamped to `text.length`.
+*
+* @remarks
+* Sums each preceding line's length plus its `\n` separator, then adds the `column - 1`
+* within the target line, capped at `text.length`. Total — never throws (an out-of-bounds
+* position yields a defined in-range offset).
+*
+* @param text - The text to index into
+* @param position - The 1-based position to resolve
+* @returns The 0-based offset (in `[0, text.length]`)
+*
+* @example
+* ```ts
+* offsetAt('ab\ncd', { line: 2, column: 1 }) // 3 (just after 'ab\n')
+* ```
+*/
+function offsetAt(text, position) {
+	const lines = text.split("\n");
+	let offset = 0;
+	for (let index = 0; index < position.line - 1 && index < lines.length; index += 1) offset += (lines[index]?.length ?? 0) + 1;
+	offset += position.column - 1;
+	return Math.min(offset, text.length);
+}
+/**
+* Slice the substring of `text` spanned by a {@link Range} (start INCLUSIVE, end
+* EXCLUSIVE), clamping the range to the text's bounds first — the read half of the ranged
+* edit surface.
+*
+* @remarks
+* Clamps via {@link clampRange}, resolves each end to an offset via {@link offsetAt}, and
+* returns `text.slice(startOffset, endOffset)`. Total — never throws.
+*
+* @param text - The text to slice
+* @param range - The 1-based range to extract
+* @returns The spanned substring (empty when the clamped span is empty)
+*
+* @example
+* ```ts
+* sliceRange('hello\nworld', { start: { line: 1, column: 1 }, end: { line: 1, column: 6 } }) // 'hello'
+* ```
+*/
+function sliceRange(text, range) {
+	const clamped = clampRange(text, range);
+	return text.slice(offsetAt(text, clamped.start), offsetAt(text, clamped.end));
+}
+/**
+* Replace the span of `text` covered by a {@link Range} with `replacement` (start
+* INCLUSIVE, end EXCLUSIVE), clamping the range to the text's bounds first — the write
+* half of the ranged edit surface.
+*
+* @remarks
+* Clamps via {@link clampRange}, then stitches `before + replacement + after` around the
+* resolved offsets. An empty span (`start === end`) becomes a pure insertion. Total —
+* never throws.
+*
+* @param text - The original text
+* @param range - The 1-based range to overwrite
+* @param replacement - The text to splice in place of the spanned range
+* @returns The text with the spanned range replaced by `replacement`
+*
+* @example
+* ```ts
+* spliceRange('hello', { start: { line: 1, column: 1 }, end: { line: 1, column: 6 } }, 'bye') // 'bye'
+* ```
+*/
+function spliceRange(text, range, replacement) {
+	const clamped = clampRange(text, range);
+	const start = offsetAt(text, clamped.start);
+	const end = offsetAt(text, clamped.end);
+	return text.slice(0, start) + replacement + text.slice(end);
+}
+/**
+* Assemble a 1-based nested {@link Range} from the four FLAT caret integers of the workspace tool's
+* `'splice'` operation — the bridge from the small-model FLAT surface
+* ({@link import('./types.js').WorkspaceOperation}) back to the nested {@link Range} the
+* {@link import('./workspaces/Workspace.js').Workspace} edit surface speaks.
+*
+* @remarks
+* Pairs `(fromLine, fromColumn)` into `start` and `(toLine, toColumn)` into `end` verbatim — a pure
+* structural lift, no validation (a structurally invalid range is rejected downstream by the ranged
+* `write` it feeds, via {@link isValidRange}). Total — never throws. Zero-Node.
+*
+* @param fromLine - The 1-based start line
+* @param fromColumn - The 1-based start column
+* @param toLine - The 1-based end line
+* @param toColumn - The 1-based end column
+* @returns The `{ start, end }` {@link Range}
+*
+* @example
+* ```ts
+* rangeOf(1, 11, 1, 12) // { start: { line: 1, column: 11 }, end: { line: 1, column: 12 } }
+* ```
+*/
+function rangeOf(fromLine, fromColumn, toLine, toColumn) {
+	return {
+		start: {
+			line: fromLine,
+			column: fromColumn
+		},
+		end: {
+			line: toLine,
+			column: toColumn
+		}
+	};
+}
+/**
+* Render 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).
+*
+* @remarks
+* Produces `` File: <path>\n```<language>\n<content>\n``` `` — the `File:` label line, then a
+* fenced code block tagged with `language`, the `content` verbatim inside. Pure string assembly,
+* total — never throws. The one fenced-file format string for the whole module — `AgentContext.build()`
+* frames an active workspace's text files with it (each carries its own `language` on its
+* {@link FileContent} text arm).
+*
+* @param path - The file path shown on the `File:` label line
+* @param language - The fenced-code language tag (e.g. `'typescript'`)
+* @param content - The file body rendered verbatim inside the fence
+* @returns The fenced reference block
+*
+* @example
+* ```ts
+* import { fencedFile } from '@src/core'
+*
+* fencedFile('src/main.ts', 'typescript', 'const x = 1')
+* // 'File: src/main.ts\n```typescript\nconst x = 1\n```'
+* ```
+*/
+function fencedFile(path, language, content) {
+	return `File: ${path}\n\`\`\`${language}\n${content}\n\`\`\``;
+}
+/**
+* Escape a string's regex-special characters so it matches LITERALLY inside a `RegExp` — the
+* primitive a {@link import('./workspaces/Workspace.js').Workspace} search builds a literal-text
+* search pattern through (as opposed to a caller-supplied regex pattern).
+*
+* @remarks
+* Prefixes every character in the class `. * + ? ^ $ { } ( ) | [ ] \` with a backslash, so the
+* escaped string, when compiled into a `RegExp`, matches only its own literal characters — no
+* character acts as a quantifier, anchor, group, or class. Pure string assembly, total — never
+* throws.
+*
+* @param value - The text to escape for literal use inside a `RegExp` pattern
+* @returns `value` with every regex-special character backslash-escaped
+*
+* @example
+* ```ts
+* escapeRegExp('a.b*c') // 'a\\.b\\*c'
+* new RegExp(escapeRegExp('a.b*c')).test('a.b*c') // true
+* ```
+*/
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/core/instructions/Instruction.ts
+/**
+* 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.
+*
+* @remarks
+* A thin immutable value object (mirroring {@link import('../tools/Tool.js').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 `format` override ONLY when supplied (assigned just 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
+* renders it (highest `priority` first) under its section header.
+*
+* @example
+* ```ts
+* const instruction = new Instruction({ name: 'tone', content: 'Be concise.', priority: 5 })
+* instruction.priority // 5
+* ```
+*/
+var Instruction = class {
+	id;
+	name;
+	content;
+	priority;
+	format;
+	constructor(input) {
+		this.id = crypto.randomUUID();
+		this.name = input.name;
+		this.content = input.content;
+		this.priority = input.priority ?? 0;
+		if (input.format !== void 0) this.format = input.format;
+	}
+};
+//#endregion
+//#region src/core/instructions/InstructionManager.ts
+/**
+* The instruction registry a richer context assembles a directives block from —
+* immutable {@link Instruction}s keyed by `name`, listed by descending `priority`.
+*
+* @remarks
+* - **Registry.** Instructions live in an insertion-ordered `Map` keyed by `name`;
+*   `add` takes one {@link InstructionInput} or a batch (§9.2), 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).** `description` is the section
+*   header a context renders the instructions under; `format(instruction)` renders one
+*   instruction (its `content`). Each ENCAPSULATES the cascade's `[options-override →
+*   built-in]` half: when `InstructionManagerOptions.format` supplies an `open` /
+*   `render`, `description` / `format` 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.format} is round-tripped onto the stored instruction.
+* - **Removal.** `remove` drops one by name, or a batch (§9.2) — `true` when any was
+*   removed; `clear` empties the registry.
+* - **Observable (§13).** 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
+*   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.
+*
+* @example
+* ```ts
+* const manager = new InstructionManager()
+* manager.add([
+* 	{ name: 'tone', content: 'Be concise.', priority: 1 },
+* 	{ name: 'safety', content: 'Refuse unsafe requests.', priority: 10 },
+* ])
+* manager.instructions().map((one) => one.name) // ['safety', 'tone'] — highest priority first
+* ```
+*/
+var InstructionManager = class {
+	#instructions = /* @__PURE__ */ new Map();
+	#emitter;
+	#format;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#format = options?.format;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get count() {
+		return this.#instructions.size;
+	}
+	get description() {
+		return this.#format?.open ?? "## Instructions";
+	}
+	get framing() {
+		return this.#format;
+	}
+	add(input) {
+		if (isArray(input)) return input.map((one) => this.#create(one));
+		return this.#create(input);
+	}
+	instruction(name) {
+		return this.#instructions.get(name);
+	}
+	instructions() {
+		return [...this.#instructions.values()].sort((a, b) => b.priority - a.priority);
+	}
+	format(instruction) {
+		return this.#format?.render?.(instruction) ?? instruction.content;
+	}
+	remove(names) {
+		if (isArray(names)) {
+			let removed = false;
+			for (const name of names) if (this.#delete(name)) removed = true;
+			return removed;
+		}
+		return this.#delete(names);
+	}
+	clear() {
+		this.#instructions.clear();
+		this.#emitter.emit("clear");
+	}
+	#create(input) {
+		const instruction = new Instruction(input);
+		this.#instructions.set(instruction.name, instruction);
+		this.#emitter.emit("add", instruction);
+		return instruction;
+	}
+	#delete(name) {
+		const removed = this.#instructions.delete(name);
+		if (removed) this.#emitter.emit("remove", name);
+		return removed;
+	}
+};
+//#endregion
+//#region src/core/tools/ToolManager.ts
+/**
+* The tool registry the agent loop dispatches model tool-calls through — resolves
+* names, lists {@link ToolDefinition}s for the provider, and executes calls with
+* per-call error isolation.
+*
+* @remarks
+* - **Registry.** Tools live in an insertion-ordered `Map` keyed by `tool.name`;
+*   `add` takes one or a batch (§9.2) and a re-`add` of the same name OVERWRITES it
+*   (last write wins). `count` is the map size, `tool(name)` looks one up, `tools()`
+*   lists them in insertion order, and `definitions()` maps each to a plain
+*   {@link ToolDefinition} (`name` / `description?` / `parameters?`, the `execute`
+*   handler stripped) — exactly what a provider advertises to the model.
+* - **Per-call error isolation (the load-bearing part).** `execute` resolves a
+*   {@link ToolCall}'s tool by name and ALWAYS resolves a {@link ToolResult}: an
+*   unknown name → `{ id, name, error: 'tool not found: <name>' }`; a successful run →
+*   `{ id, name, value }`; a handler throw is CAUGHT into `{ id, name, error }` (an
+*   `Error`'s message, else the stringified throw). A tool throw never escapes — it
+*   becomes a result the model can react to.
+* - **Batch never fails as a whole.** `execute(calls)` runs every call via
+*   `Promise.all(calls.map(...))` and resolves the results correlated by `id` in the
+*   input order — a mix of success, throw, and not-found all resolve; one bad call
+*   does not reject the batch.
+* - **Event-free.** A purely functional registry — no Emitter, no events.
+*
+* @example
+* ```ts
+* const manager = new ToolManager()
+* manager.add(new Tool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
+* const result = await manager.execute({ id: '1', name: 'add', arguments: { x: 1, y: 2 } })
+* result.value // 3
+* ```
+*/
+var ToolManager = class {
+	#tools = /* @__PURE__ */ new Map();
+	get count() {
+		return this.#tools.size;
+	}
+	add(tools) {
+		if (isArray(tools)) {
+			for (const tool of tools) this.#tools.set(tool.name, tool);
+			return;
+		}
+		this.#tools.set(tools.name, tools);
+	}
+	tool(name) {
+		return this.#tools.get(name);
+	}
+	tools() {
+		return [...this.#tools.values()];
+	}
+	definitions() {
+		return [...this.#tools.values()].map((tool) => this.#definition(tool));
+	}
+	execute(call) {
+		if (isArray(call)) return Promise.all(call.map((one) => this.#run(one)));
+		return this.#run(call);
+	}
+	remove(names) {
+		if (isArray(names)) {
+			let removed = false;
+			for (const name of names) if (this.#tools.delete(name)) removed = true;
+			return removed;
+		}
+		return this.#tools.delete(names);
+	}
+	clear() {
+		this.#tools.clear();
+	}
+	async #run(call) {
+		const tool = this.#tools.get(call.name);
+		if (tool === void 0) return {
+			id: call.id,
+			name: call.name,
+			error: `tool not found: ${call.name}`
+		};
+		try {
+			const value = await tool.execute(call.arguments);
+			return {
+				id: call.id,
+				name: call.name,
+				value
+			};
+		} catch (error) {
+			return {
+				id: call.id,
+				name: call.name,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	#definition(tool) {
+		const definition = { name: tool.name };
+		if (tool.description !== void 0) definition.description = tool.description;
+		if (tool.parameters !== void 0) definition.parameters = tool.parameters;
+		return definition;
+	}
+};
+//#endregion
+//#region src/core/workspaces/Workspace.ts
+/**
+* A mutable, `path`-keyed working set of immutable {@link FileInterface}s — the
+* in-memory editing surface over the file primitive.
+*
+* @remarks
+* - **Registry.** Files live in an insertion-ordered `Map` keyed by `path`; `count` is the
+*   map size, `file(path)` looks one up, and `files()` lists them in insertion order.
+* - **Write replaces the File (§11 immutability).** Every edit MINTS a replacement
+*   {@link FileInterface} (via {@link import('../factories.js').createFile}) rather than
+*   mutating in place, transitioning `state` to `'created'` for a brand-new path or
+*   `'modified'` for an existing one. A whole-file string write preserves an existing text
+*   file's `language`, else infers it from the `path` (`inferLanguage`); writing a string
+*   onto an existing BINARY path replaces it with a text file (a deliberate retype). A
+*   ranged `write` splices a `Range` of an existing text file.
+* - **Modality rules.** Text-only ops on a binary file are rejected: a ranged `read` /
+*   `write`, `prepend`, and `append` throw `MODALITY`; a plain `read(path)` of a binary
+*   file returns `undefined`; `search` / `replace` skip binary files (0 matches).
+* - **In-memory removal.** `remove(path)` / `remove(paths)` drop files outright (no
+*   tombstone — the `'loaded'` / `'deleted'` states are reserved for a future FileStore);
+*   `remove()` and `clear()` both empty the registry and emit the single `clear` signal.
+*   The disk/sync lifecycle (`load` / `revert` / `accept` / `purge` / `dirty`) is NOT part
+*   of this surface.
+* - **Observable (§13).** The owned {@link emitter} ({@link WorkspaceEventMap}) carries
+*   `write` (the resulting file) / `remove` (the path) / `move` (`{ from, to }`) / `clear`.
+*   Every event is emitted directly, strictly AFTER the map mutation completes; the
+*   emitter isolates a listener throw and routes it to its `error` handler, so a buggy
+*   observer can never corrupt a mutation.
+*
+* @example
+* ```ts
+* const workspace = new Workspace()
+* workspace.write('src/main.ts', 'const x = 1')
+* workspace.file('src/main.ts')?.state // 'created'
+* workspace.append('src/main.ts', '\nconst y = 2')
+* workspace.file('src/main.ts')?.state // 'modified'
+* workspace.read('src/main.ts') // 'const x = 1\nconst y = 2'
+* ```
+*/
+var Workspace = class {
+	#id;
+	#files = /* @__PURE__ */ new Map();
+	#emitter;
+	constructor(options, seed) {
+		this.#id = options?.id ?? crypto.randomUUID();
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		if (seed) for (const [path, file] of seed) this.#files.set(path, file);
+	}
+	get id() {
+		return this.#id;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get count() {
+		return this.#files.size;
+	}
+	file(path) {
+		return this.#files.get(path);
+	}
+	files() {
+		return [...this.#files.values()];
+	}
+	read(path, range) {
+		if (isArray(path)) {
+			const result = {};
+			for (const one of path) {
+				const file = this.#files.get(one);
+				if (file && isText(file.content)) result[one] = file.content.text;
+			}
+			return result;
+		}
+		const file = this.#files.get(path);
+		if (!file) return void 0;
+		if (!range) return isText(file.content) ? file.content.text : void 0;
+		if (!isText(file.content)) throw new WorkspaceError("MODALITY", `Cannot read a range of a binary file: ${path}`, { path });
+		return {
+			content: sliceRange(file.content.text, range),
+			range: clampRange(file.content.text, range)
+		};
+	}
+	has(path) {
+		if (isArray(path)) return path.some((one) => this.#files.has(one));
+		return this.#files.has(path);
+	}
+	search(query, options) {
+		const pattern = this.#pattern(query, options);
+		const limit = options?.limit;
+		const matches = [];
+		for (const file of this.#files.values()) {
+			if (limit !== void 0 && matches.length >= limit) break;
+			if (!isText(file.content)) continue;
+			const lines = file.content.text.split("\n");
+			for (let index = 0; index < lines.length; index += 1) {
+				if (limit !== void 0 && matches.length >= limit) break;
+				const lineText = lines[index] ?? "";
+				pattern.lastIndex = 0;
+				let hit = pattern.exec(lineText);
+				while (hit !== null) {
+					if (limit !== void 0 && matches.length >= limit) break;
+					matches.push({
+						path: file.path,
+						line: index + 1,
+						column: hit.index + 1,
+						length: hit[0].length,
+						content: lineText
+					});
+					if (hit[0].length === 0) pattern.lastIndex += 1;
+					hit = pattern.exec(lineText);
+				}
+			}
+		}
+		return matches;
+	}
+	replace(query, replacement, options) {
+		const pattern = this.#pattern(query, options);
+		const limit = options?.limit;
+		let replaced = 0;
+		let files = 0;
+		for (const [path, file] of this.#files) {
+			if (limit !== void 0 && replaced >= limit) break;
+			if (!isText(file.content)) continue;
+			const remaining = limit === void 0 ? void 0 : limit - replaced;
+			let count = 0;
+			pattern.lastIndex = 0;
+			const next = file.content.text.replace(pattern, (match) => {
+				if (remaining !== void 0 && count >= remaining) return match;
+				count += 1;
+				return replacement;
+			});
+			if (count > 0) {
+				replaced += count;
+				files += 1;
+				this.write(path, next);
+			}
+		}
+		return {
+			query,
+			replaced,
+			files
+		};
+	}
+	write(path, content, range) {
+		if (isRecord(path)) {
+			for (const [one, text] of Object.entries(path)) this.#write(one, text);
+			return;
+		}
+		const text = content ?? "";
+		if (!range) {
+			this.#write(path, text);
+			return;
+		}
+		this.#splice(path, text, range);
+	}
+	prepend(path, content) {
+		if (isRecord(path)) {
+			for (const [one, text] of Object.entries(path)) this.#prepend(one, text);
+			return;
+		}
+		this.#prepend(path, content ?? "");
+	}
+	append(path, content) {
+		if (isRecord(path)) {
+			for (const [one, text] of Object.entries(path)) this.#append(one, text);
+			return;
+		}
+		this.#append(path, content ?? "");
+	}
+	move(from, to) {
+		if (isRecord(from)) {
+			let moved = false;
+			for (const [one, target] of Object.entries(from)) if (this.#move(one, target)) moved = true;
+			return moved;
+		}
+		return this.#move(from, to ?? "");
+	}
+	remove(path) {
+		if (path === void 0) {
+			this.#files.clear();
+			this.#emitter.emit("clear");
+			return;
+		}
+		if (isArray(path)) {
+			let removed = false;
+			for (const one of path) if (this.#remove(one)) removed = true;
+			return removed;
+		}
+		return this.#remove(path);
+	}
+	clear() {
+		this.#files.clear();
+		this.#emitter.emit("clear");
+	}
+	snapshot() {
+		return {
+			id: this.#id,
+			files: this.files()
+		};
+	}
+	#write(path, content) {
+		const existing = this.#files.get(path);
+		const file = createFile({
+			path,
+			content: {
+				text: content,
+				language: existing && isText(existing.content) ? existing.content.language : inferLanguage(path)
+			},
+			state: existing ? "modified" : "created"
+		});
+		this.#files.set(path, file);
+		this.#emitter.emit("write", file);
+	}
+	#splice(path, content, range) {
+		const existing = this.#files.get(path);
+		if (!existing || !isText(existing.content)) throw new WorkspaceError("MODALITY", `Cannot splice a range of a non-text file: ${path}`, { path });
+		if (!isValidRange(range)) throw new WorkspaceError("RANGE", `Invalid range for file: ${path}`, {
+			path,
+			range
+		});
+		const file = createFile({
+			path,
+			content: {
+				text: spliceRange(existing.content.text, range, content),
+				language: existing.content.language
+			},
+			state: "modified"
+		});
+		this.#files.set(path, file);
+		this.#emitter.emit("write", file);
+	}
+	#prepend(path, content) {
+		this.#write(path, content + this.#text(path, "prepend"));
+	}
+	#append(path, content) {
+		this.#write(path, this.#text(path, "append") + content);
+	}
+	#text(path, operation) {
+		const existing = this.#files.get(path);
+		if (!existing) return "";
+		if (!isText(existing.content)) throw new WorkspaceError("MODALITY", `Cannot ${operation} text to a binary file: ${path}`, { path });
+		return existing.content.text;
+	}
+	#move(from, to) {
+		const file = this.#files.get(from);
+		if (!file) return false;
+		const moved = createFile({
+			path: to,
+			content: file.content,
+			state: "modified"
+		});
+		this.#files.delete(from);
+		this.#files.set(to, moved);
+		this.#emitter.emit("move", {
+			from,
+			to
+		});
+		return true;
+	}
+	#remove(path) {
+		const removed = this.#files.delete(path);
+		if (removed) this.#emitter.emit("remove", path);
+		return removed;
+	}
+	#pattern(query, options) {
+		const source = options?.regex === true ? query : escapeRegExp(query);
+		const flags = options?.exact === false ? "gi" : "g";
+		try {
+			return new RegExp(source, flags);
+		} catch {
+			throw new WorkspaceError("PATTERN", `Invalid search pattern: ${query}`, { query });
+		}
+	}
+};
+//#endregion
+//#region src/core/workspaces/WorkspaceManager.ts
+/**
+* The registry of {@link Workspace}s keyed by `id`, in insertion order, WITH an active pointer
+* — the §9 store over the workspace layer PLUS the `active` / `switch` seam the context renders.
+* Event-free (a registry, like {@link ConversationManager}); the observability lives on each
+* {@link Workspace}.
+*
+* @remarks
+* - **Registry.** Workspaces live in an insertion-ordered `Map` keyed by `id`. `add(input?)`
+*   mints a {@link Workspace} (its `id` from `input` or `crypto.randomUUID()`), flowing the
+*   manager's default `on` / `error` in unless the `input` OVERRIDES them, and stores it (an
+*   already-present `id` OVERWRITES — last write wins). `count` is the map size, `workspace(id)`
+*   looks one up, `workspaces()` lists them in insertion order.
+* - **Active pointer.** `active` is the active workspace (what the context renders), `undefined`
+*   until the FIRST `add` (which auto-activates it — a registry with workspaces always has one
+*   active). A subsequent `add` leaves `active` unchanged. `switch(id)` re-points `active` to the
+*   workspace 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 (§9.2) — `true` when any was removed;
+*   removing the ACTIVE workspace sets `active` to `undefined`. `clear` empties the registry and
+*   sets `active` to `undefined`.
+* - **Durable open / save (the optional `store`).** With a {@link WorkspaceStoreInterface} supplied
+*   (the `store` option), `open(id)` HYDRATES a workspace on a registry miss — it `store.get(id)`s
+*   the snapshot and rebuilds a fresh {@link Workspace} through the constructor `seed`
+*   (`snapshot.files` → path → File), then activates it — and `save(id)` PERSISTS a registered
+*   workspace's `snapshot()`. Both are LENIENT without a store (open resolves only registered ids,
+*   save is a no-op `false`), consistent with the lenient `switch`.
+* - **Event-free.** A purely registry store — no Emitter, no events (each workspace owns its own
+*   observable `emitter`).
+*
+* @example
+* ```ts
+* const manager = new WorkspaceManager()
+* const first = manager.add() // auto-activates — active === first
+* manager.add({ id: 'scratch' }) // leaves active unchanged
+* manager.switch('scratch') // re-points active to the 'scratch' workspace
+* manager.count // 2
+* ```
+*/
+var WorkspaceManager = class {
+	#workspaces = /* @__PURE__ */ new Map();
+	#active;
+	#on;
+	#error;
+	#store;
+	constructor(options) {
+		this.#on = options?.on;
+		this.#error = options?.error;
+		this.#store = options?.store;
+	}
+	get count() {
+		return this.#workspaces.size;
+	}
+	get active() {
+		return this.#active === void 0 ? void 0 : this.#workspaces.get(this.#active);
+	}
+	workspace(id) {
+		return this.#workspaces.get(id);
+	}
+	workspaces() {
+		return [...this.#workspaces.values()];
+	}
+	add(input) {
+		const workspace = new Workspace({
+			...input?.id === void 0 ? {} : { id: input.id },
+			on: input?.on ?? this.#on,
+			error: input?.error ?? this.#error
+		}, input?.seed);
+		this.#workspaces.set(workspace.id, workspace);
+		if (this.#active === void 0) this.#active = workspace.id;
+		return workspace;
+	}
+	switch(id) {
+		const workspace = this.#workspaces.get(id);
+		if (workspace === void 0) return void 0;
+		this.#active = id;
+		return workspace;
+	}
+	async open(id) {
+		const existing = this.#workspaces.get(id);
+		if (existing !== void 0) {
+			this.#active = id;
+			return existing;
+		}
+		if (this.#store === void 0) return void 0;
+		const snapshot = await this.#store.get(id);
+		if (snapshot === void 0) return void 0;
+		const workspace = this.add({
+			id,
+			seed: snapshot.files.map((file) => [file.path, file])
+		});
+		this.#active = workspace.id;
+		return workspace;
+	}
+	async save(id) {
+		const workspace = this.#workspaces.get(id);
+		if (this.#store === void 0 || workspace === void 0) return false;
+		await this.#store.set(workspace.snapshot());
+		return true;
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = false;
+			for (const id of ids) if (this.#drop(id)) removed = true;
+			return removed;
+		}
+		return this.#drop(ids);
+	}
+	clear() {
+		this.#workspaces.clear();
+		this.#active = void 0;
+	}
+	#drop(id) {
+		const removed = this.#workspaces.delete(id);
+		if (removed && this.#active === id) this.#active = void 0;
+		return removed;
+	}
+};
+//#endregion
+//#region src/core/AgentContext.ts
+/**
+* The richer turn context the agent loop assembles a provider request from — 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 a mutable active {@link ScopeInterface}.
+*
+* @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 —
+*   `undefined` (the default) ⇒ no filtering; settable afterwards. `workspaces` / `conversations`
+*   are likewise SETTABLE (swap the whole registry between runs).
+* - **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
+*   via 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
+*   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
+*   (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 via 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 >
+*   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
+*   format) 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' `data` is attached to
+*   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.**
+*   `workspaces.active` (when set) has its {@link 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 `data` 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
+*   via `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 §13 observation surface).
+*
+* @example
+* ```ts
+* const context = new AgentContext({ system: 'You are concise.' })
+* context.instructions.add({ name: 'tone', content: 'Be terse.' })
+* context.messages.add({ role: 'user', content: 'Hi' })
+* context.build() // [{ role: 'system', content: 'You are concise.\n\n## Instructions\n\nBe terse.' }, { role: 'user', content: 'Hi' }]
+* ```
+*/
+var AgentContext = class {
+	#system;
+	#instructions;
+	#workspaces;
+	#conversations;
+	#tools;
+	#scope;
+	constructor(options) {
+		this.#system = options?.system;
+		this.#instructions = options?.instructions ?? new InstructionManager();
+		this.#workspaces = options?.workspaces ?? new WorkspaceManager();
+		this.#conversations = options?.conversations ?? new ConversationManager();
+		if (this.#conversations.active === void 0) this.#conversations.add();
+		this.#tools = options?.tools ?? new ToolManager();
+		this.#scope = options?.scope;
+	}
+	get system() {
+		return this.#system;
+	}
+	get instructions() {
+		return this.#instructions;
+	}
+	get workspaces() {
+		return this.#workspaces;
+	}
+	set workspaces(value) {
+		this.#workspaces = value;
+	}
+	get messages() {
+		return this.#conversations.active ?? this.#ensure();
+	}
+	get conversations() {
+		return this.#conversations;
+	}
+	set conversations(value) {
+		this.#conversations = value;
+		if (this.#conversations.active === void 0) this.#conversations.add();
+	}
+	get tools() {
+		return this.#tools;
+	}
+	get scope() {
+		return this.#scope;
+	}
+	set scope(value) {
+		this.#scope = value;
+	}
+	build(format) {
+		const scope = this.#scope;
+		const parts = [];
+		if (this.#system !== void 0) parts.push(this.#system);
+		const instructions = filterAllowList(scope?.instructions, this.#instructions.instructions(), (one) => one.name);
+		this.#section(parts, this.#header(this.#instructions, format?.instructions), instructions, (one) => this.#render(this.#instructions, format?.instructions, one), this.#footer(this.#instructions, format?.instructions));
+		const files = filterAllowList(scope?.files, this.#workspaces.active?.files() ?? [], (one) => one.path);
+		const workspaceTexts = files.filter((file) => isText(file.content));
+		this.#section(parts, WORKSPACE_SECTION_HEADER, workspaceTexts, (file) => this.#fenced(file), void 0);
+		const conversation = (this.#conversations.active ?? this.#ensure()).view();
+		const tail = this.#attach(conversation, this.#workspaceImages(files));
+		if (parts.length === 0) return tail;
+		return [{
+			id: crypto.randomUUID(),
+			role: "system",
+			content: parts.join("\n\n")
+		}, ...tail];
+	}
+	#section(parts, open, items, format, close) {
+		if (items.length === 0) return;
+		const lines = [open, ...items.map(format)];
+		if (close !== void 0) lines.push(close);
+		parts.push(lines.join("\n\n"));
+	}
+	#header(manager, provider) {
+		return manager.framing?.open ?? provider?.open ?? manager.description;
+	}
+	#footer(manager, provider) {
+		return manager.framing?.close ?? provider?.close;
+	}
+	#render(manager, provider, item) {
+		return item.format ?? manager.framing?.render?.(item) ?? provider?.render?.(item) ?? manager.format(item);
+	}
+	#attach(conversation, data) {
+		if (data.length === 0) return conversation;
+		let target = -1;
+		for (let index = conversation.length - 1; index >= 0; index -= 1) if (conversation[index]?.role === "user") {
+			target = index;
+			break;
+		}
+		if (target === -1) return conversation;
+		return conversation.map((message, index) => index === target ? this.#withImages(message, data) : message);
+	}
+	#withImages(message, data) {
+		const images = [...message.images ?? [], ...data];
+		return message.calls === void 0 ? {
+			id: message.id,
+			role: message.role,
+			content: message.content,
+			images
+		} : {
+			id: message.id,
+			role: message.role,
+			content: message.content,
+			calls: message.calls,
+			images
+		};
+	}
+	#fenced(file) {
+		if (isText(file.content)) return fencedFile(file.path, file.content.language, file.content.text);
+		return fencedFile(file.path, "text", "");
+	}
+	#workspaceImages(files) {
+		const data = [];
+		for (const file of files) if (isBinary(file.content) && isImage(file.content)) data.push(file.content.data);
+		return data;
+	}
+	#ensure() {
+		const conversation = this.#conversations.add();
+		return this.#conversations.active ?? conversation;
+	}
+};
+//#endregion
+//#region src/core/Channel.ts
+/**
+* A minimal unbounded async channel — the eager pump WRITES chunks into it (`push`)
+* and ends it (`close` / `fail`) regardless of consumption; a consumer READS them back
+* live via the `drain` async-iterator. Decoupling write from read is what lets a
+* producer make progress without a consumer pulling.
+*
+* @remarks
+* The standard resolver-swap: a waiting `drain` parks on `#wake` (a void resolver);
+* `push` / `close` / `fail` enqueue/flag, then fire `#wake` so the parked reader wakes,
+* re-reads the buffer, and either yields the next chunk, returns (on `close`), or throws
+* (on `fail`). Event-free, no `!` / `as` / `any`.
+*/
+var Channel = class {
+	#buffer = [];
+	#wake;
+	#closed = false;
+	#failure;
+	push(value) {
+		this.#buffer.push(value);
+		this.#signal();
+	}
+	close() {
+		this.#closed = true;
+		this.#signal();
+	}
+	fail(error) {
+		if (this.#failure === void 0) this.#failure = { error };
+		this.#closed = true;
+		this.#signal();
+	}
+	async *drain() {
+		for (;;) {
+			while (this.#buffer.length > 0) {
+				const next = this.#buffer.shift();
+				if (next !== void 0) yield next;
+			}
+			if (this.#failure !== void 0) throw this.#failure.error;
+			if (this.#closed) return;
+			await this.#parked();
+		}
+	}
+	#signal() {
+		const wake = this.#wake;
+		this.#wake = void 0;
+		wake?.();
+	}
+	#parked() {
+		return new Promise((resolve) => {
+			this.#wake = resolve;
+		});
+	}
+};
+//#endregion
+//#region src/core/Agent.ts
+/**
+* The agent loop — 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`.
+*
+* @remarks
+* - **One loop, two faces.** A single private async generator (`#run`) drives the
+*   whole turn. `stream` kicks off an eager pump that iterates `#run` into a private
+*   {@link Channel}, settling `result` from the run's outcome — so `result` settles
+*   whether or not the live `events` are drained; `generate` simply awaits that same
+*   settled `result` — so the two can never diverge.
+* - **The turn.** `#run` builds the provider input once (`context.build()` into a
+*   working array) then loops up to `limit`: drive `provider.stream(...)` accumulating
+*   + yielding each content delta as a `token` chunk; fold the turn's usage into the
+*   running total + the `budget` and yield a `usage` chunk; if the model requested
+*   tools, append the assistant turn, `execute` them, yield a `tool` chunk per call,
+*   append each tool result message, and continue; otherwise append the final
+*   assistant message and stop.
+* - **Bounded.** Each run arms one cancel via `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
+*   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
+*   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
+*   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.
+*
+* @example
+* ```ts
+* const agent = new Agent(provider, { system: 'You are concise.' })
+* agent.context.messages.add({ role: 'user', content: 'Say hi.' })
+* const result = await agent.generate()
+* ```
+*/
+var Agent = class {
+	#provider;
+	#context;
+	#limit;
+	#timeoutMs;
+	#budget;
+	#scheduler;
+	#signal;
+	#authority;
+	#window;
+	#emitter;
+	id = crypto.randomUUID();
+	#status = "idle";
+	#runs = /* @__PURE__ */ new Set();
+	constructor(provider, options) {
+		this.#provider = provider;
+		this.#context = new AgentContext({
+			system: options?.system,
+			tools: options?.tools,
+			conversations: options?.conversations
+		});
+		this.#limit = options?.limit ?? 10;
+		this.#timeoutMs = options?.timeout;
+		this.#budget = options?.budget;
+		this.#scheduler = options?.scheduler;
+		this.#signal = options?.signal;
+		this.#authority = options?.authority;
+		this.#window = options?.window;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get status() {
+		return this.#status;
+	}
+	get context() {
+		return this.#context;
+	}
+	generate(options) {
+		return this.stream(options).result;
+	}
+	stream(options) {
+		const timeout = this.#timeoutMs === void 0 ? void 0 : createTimeout({ ms: this.#timeoutMs });
+		timeout?.start();
+		this.#budget?.start();
+		const abort = createAbort({ signal: this.#parents(timeout) });
+		this.#runs.add(abort);
+		this.#status = "running";
+		this.#emitter.emit("start", this.id);
+		const outcome = {
+			content: "",
+			thinking: void 0,
+			usage: void 0,
+			partial: false
+		};
+		const channel = new Channel();
+		const settled = createDeferred();
+		this.#pump(abort, outcome, timeout, channel, settled, options?.think);
+		settled.promise.catch(() => {});
+		return {
+			events: this.#events(channel, abort),
+			result: settled.promise,
+			abort: (reason) => {
+				abort.abort(reason);
+			}
+		};
+	}
+	abort(reason) {
+		for (const abort of [...this.#runs]) abort.abort(reason);
+	}
+	async #pump(abort, outcome, timeout, channel, settled, think) {
+		let failure;
+		try {
+			for await (const chunk of this.#run(abort, outcome, think)) channel.push(chunk);
+		} catch (error) {
+			failure = { error };
+		} finally {
+			timeout?.clear();
+			this.#runs.delete(abort);
+			if (failure === void 0) {
+				this.#status = "done";
+				channel.close();
+				const result = this.#result(outcome);
+				settled.resolve(result);
+				if (outcome.partial) this.#emitter.emit("abort", abort.signal.reason);
+				this.#emitter.emit("finish", result);
+			} else {
+				this.#status = "error";
+				channel.fail(failure.error);
+				settled.reject(failure.error);
+				this.#emitter.emit("error", failure.error);
+			}
+		}
+	}
+	async *#events(channel, abort) {
+		try {
+			yield* channel.drain();
+		} finally {
+			abort.abort();
+		}
+	}
+	async *#run(abort, outcome, think) {
+		const messages = [...this.#context.build(this.#provider.format)];
+		const tools = this.#context.tools;
+		let content = "";
+		let thinking;
+		let usage;
+		const compaction = { futile: false };
+		const compacting = this.#window !== void 0 && this.#context.conversations.active?.summarizable === true;
+		if (compacting) {
+			this.#window?.clear();
+			if (!abort.signal.aborted) await this.#trim(messages, compaction, false);
+		}
+		for (let turn = 0; turn < this.#limit; turn += 1) {
+			this.#emitter.emit("turn", turn);
+			if (turn > 0) try {
+				await this.#scheduler?.yield({ signal: abort.signal });
+			} catch (error) {
+				if (abort.signal.aborted) {
+					outcome.partial = true;
+					break;
+				}
+				throw error;
+			}
+			if (abort.signal.aborted) {
+				outcome.partial = true;
+				break;
+			}
+			const advertised = filterAllowList(this.#context.scope?.tools, tools.definitions(), (definition) => definition.name);
+			const definitions = advertised.length > 0 ? advertised : void 0;
+			let result;
+			try {
+				result = yield* this.#provide(messages, abort.signal, definitions, think, (delta) => {
+					content += delta;
+				});
+			} catch (error) {
+				if (abort.signal.aborted) {
+					if (isProviderAbortError(error) && error.partial.thinking !== void 0) thinking = this.#thought(thinking, error.partial.thinking);
+					outcome.partial = true;
+					break;
+				}
+				throw error;
+			}
+			if (result.thinking !== void 0 && result.thinking.length > 0) thinking = this.#thought(thinking, result.thinking);
+			if (result.usage !== void 0) {
+				this.#budget?.consume(result.usage);
+				usage = this.#sum(usage, result.usage);
+				this.#emitter.emit("usage", result.usage);
+				yield {
+					type: "usage",
+					usage: result.usage
+				};
+			}
+			if (result.tools !== void 0 && result.tools.length > 0) {
+				const assistant = this.#context.messages.add({
+					role: "assistant",
+					content: result.content,
+					calls: result.tools
+				});
+				messages.push(assistant);
+				const results = await this.#authorize(tools, result.tools);
+				for (let index = 0; index < result.tools.length; index += 1) {
+					const call = result.tools[index];
+					const outcomeResult = results[index];
+					if (call === void 0 || outcomeResult === void 0) continue;
+					this.#emitter.emit("tool", call, outcomeResult);
+					yield {
+						type: "tool",
+						call,
+						result: outcomeResult
+					};
+					const toolMessage = this.#context.messages.add({
+						role: "tool",
+						content: JSON.stringify(outcomeResult.value ?? outcomeResult.error)
+					});
+					messages.push(toolMessage);
+				}
+				if (compacting) await this.#trim(messages, compaction, true);
+				continue;
+			}
+			messages.push(this.#context.messages.add({
+				role: "assistant",
+				content: result.content
+			}));
+			content = result.content;
+			break;
+		}
+		outcome.content = content;
+		outcome.thinking = thinking;
+		outcome.usage = usage;
+	}
+	async #trim(messages, compaction, latchFutile) {
+		const conversation = this.#context.conversations.active;
+		if (this.#window === void 0 || conversation?.summarizable !== true || compaction.futile) return;
+		this.#window.clear();
+		this.#window.consume(messages);
+		if (!this.#window.exhausted) return;
+		let section;
+		try {
+			section = await conversation.compact();
+		} catch (error) {
+			this.#emitter.emit("compactError", error);
+			return;
+		}
+		if (section === void 0) {
+			if (latchFutile) compaction.futile = true;
+			return;
+		}
+		messages.splice(0, messages.length, ...this.#context.build(this.#provider.format));
+	}
+	async #authorize(tools, calls) {
+		if (this.#authority === void 0) return tools.execute(calls);
+		const authority = this.#authority;
+		const allowed = [];
+		const denials = /* @__PURE__ */ new Map();
+		for (const call of calls) {
+			let decision;
+			try {
+				decision = authority.evaluate({ call });
+			} catch (error) {
+				const reason = this.#reason(error);
+				denials.set(call.id, this.#denial(call, reason));
+				this.#emitter.emit("deny", call, reason);
+				continue;
+			}
+			if (decision.allowed) allowed.push(call);
+			else {
+				denials.set(call.id, this.#denial(call, decision.reason));
+				this.#emitter.emit("deny", call, decision.reason);
+			}
+		}
+		const executed = allowed.length > 0 ? await tools.execute(allowed) : [];
+		const byId = new Map(denials);
+		for (const result of executed) byId.set(result.id, result);
+		return calls.map((call) => byId.get(call.id) ?? this.#denial(call, void 0));
+	}
+	#denial(call, reason) {
+		return {
+			id: call.id,
+			name: call.name,
+			error: reason !== void 0 ? `denied: ${reason}` : "denied by authority"
+		};
+	}
+	#reason(error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+	async *#provide(messages, signal, definitions, think, onDelta) {
+		const generator = this.#provider.stream(messages, signal, definitions, think === void 0 ? void 0 : { think });
+		let next = await generator.next();
+		while (!next.done) {
+			const delta = next.value;
+			if (delta.type === "content") {
+				onDelta(delta.text);
+				yield {
+					type: "token",
+					content: delta.text
+				};
+			} else yield {
+				type: "think",
+				content: delta.text
+			};
+			next = await generator.next();
+		}
+		return next.value;
+	}
+	#parents(timeout) {
+		const signals = [];
+		if (this.#signal !== void 0) signals.push(this.#signal);
+		if (timeout !== void 0) signals.push(timeout.signal);
+		if (this.#budget !== void 0) signals.push(this.#budget.signal);
+		if (signals.length === 0) return void 0;
+		if (signals.length === 1) return signals[0];
+		return AbortSignal.any(signals);
+	}
+	#thought(running, next) {
+		return running === void 0 ? next : `${running}\n\n${next}`;
+	}
+	#sum(running, next) {
+		if (running === void 0) return next;
+		return {
+			prompt: running.prompt + next.prompt,
+			completion: running.completion + next.completion,
+			total: running.total + next.total
+		};
+	}
+	#result(outcome) {
+		const result = {
+			content: outcome.content,
+			partial: outcome.partial
+		};
+		if (outcome.thinking !== void 0) result.thinking = outcome.thinking;
+		if (outcome.usage !== void 0) result.usage = outcome.usage;
+		return result;
+	}
+};
+//#endregion
+//#region src/core/AgentRegistry.ts
+/**
+* The bridge that makes a durable, JSON-serializable {@link AgentJobInput} runnable —
+* it 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.
+*
+* @remarks
+* - **Why it exists.** An `AgentJobInput` is serializable so it can survive a crash in a
+*   Queue's store; the live objects it needs (a provider with sockets, tools / rules /
+*   schedulers carrying functions) cannot serialize. The registry closes that gap:
+*   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 (§9.1 + §12).** `provider` / `tool` / `authority` /
+*   `scheduler` resolve a name against their pool and THROW `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 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
+*   ceiling (`createTokenBudget({ max })`); resolve the optional `authority` /
+*   `scheduler` names; construct the {@link Agent} with `system` / `limit` / `timeout` /
+*   the threaded `signal`; seed its context with the job's `messages`; return it. The
+*   `signal` is the queue attempt's / runner unit's cancel, so a bounded abort propagates
+*   into the agent (which commits a partial — the job's `allowPartial` policy then
+*   decides success vs. retry).
+* - **Event-free.** A pure resolver — no Emitter, no events.
+*
+* @example
+* ```ts
+* declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+* const registry = new AgentRegistry({ providers: { main: provider } })
+* const agent = registry.build({ provider: 'main', messages: [{ role: 'user', content: 'Say ok.' }] })
+* const result = await agent.generate()
+* ```
+*/
+var AgentRegistry = class {
+	#providers;
+	#tools;
+	#authorities;
+	#schedulers;
+	constructor(options) {
+		this.#providers = new Map(Object.entries(options.providers));
+		this.#tools = new Map(Object.entries(options.tools ?? {}));
+		this.#authorities = new Map(Object.entries(options.authorities ?? {}));
+		this.#schedulers = new Map(Object.entries(options.schedulers ?? {}));
+	}
+	provider(name) {
+		return this.#resolve(this.#providers, "provider", name);
+	}
+	tool(name) {
+		return this.#resolve(this.#tools, "tool", name);
+	}
+	authority(name) {
+		return this.#resolve(this.#authorities, "authority", name);
+	}
+	scheduler(name) {
+		return this.#resolve(this.#schedulers, "scheduler", name);
+	}
+	build(input, signal) {
+		const agent = new Agent(this.provider(input.provider), this.#options(input, signal));
+		for (const message of input.messages) agent.context.messages.add(message);
+		return agent;
+	}
+	#options(input, signal) {
+		return {
+			system: input.system,
+			tools: this.#manager(input.tools),
+			limit: input.limit,
+			timeout: input.timeout,
+			budget: this.#budget(input.budget),
+			authority: input.authority === void 0 ? void 0 : this.authority(input.authority),
+			scheduler: input.scheduler === void 0 ? void 0 : this.scheduler(input.scheduler),
+			signal
+		};
+	}
+	#manager(names) {
+		const manager = new ToolManager();
+		if (names !== void 0) for (const name of names) manager.add(this.tool(name));
+		return manager;
+	}
+	#budget(max) {
+		return max === void 0 ? void 0 : createTokenBudget({ max });
+	}
+	#resolve(pool, category, name) {
+		const value = pool.get(name);
+		if (value === void 0) throw new Error(`unknown ${category}: ${name}`);
+		return value;
+	}
+};
+//#endregion
+//#region src/core/Authority.ts
+/**
+* The synchronous policy gate the agent loop consults before each tool call runs —
+* it turns one {@link AuthorityContextInterface} into an {@link AuthorityDecision}.
+*
+* @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`.
+* - **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`
+*   `fallback`.
+* - **Consulted before each tool call.** The agent loop calls `evaluate({ call })` for
+*   every {@link import('./types.js').ToolCall} the model emits; a denied call is fed
+*   back to the model as a denial {@link import('./types.js').ToolResult} (a `tool`
+*   chunk + a tool message) instead of being executed — no tool run, no budget cost —
+*   so the model sees the denial and can react.
+* - **Synchronous now.** The async human-approval handshake (request / grant / deny) is
+*   deferred to a later chunk; `evaluate` returns a verdict directly.
+* - **Event-free.** A purely functional gate — no Emitter, no events.
+*
+* @example
+* ```ts
+* // A denylist: deny the `delete` tool, allow everything else (default fallback).
+* const authority = new Authority({
+* 	rules: [{ match: (c) => c.call.name === 'delete', zone: 'restricted', allowed: false }],
+* })
+* authority.evaluate({ call: { id: '1', name: 'delete', arguments: {} } }) // { zone: 'restricted', allowed: false }
+* authority.evaluate({ call: { id: '2', name: 'add', arguments: {} } }) // { zone: 'default', allowed: true }
+* ```
+*/
+var Authority = class {
+	#rules;
+	#fallback;
+	constructor(options) {
+		this.#rules = options?.rules ?? [];
+		this.#fallback = options?.fallback ?? {
+			zone: "default",
+			allowed: true
+		};
+	}
+	evaluate(context) {
+		for (const rule of this.#rules) if (rule.match(context)) return {
+			zone: rule.zone,
+			allowed: rule.allowed ?? true,
+			reason: rule.reason
+		};
+		return this.#fallback;
+	}
+};
+//#endregion
+//#region src/core/conversations/stores/DatabaseConversationStore.ts
+/**
+* A {@link ConversationStoreInterface} backed by 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
+* {@link import('../../workspaces/stores/DatabaseWorkspaceStore.js').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
+* {@link import('../ConversationManager.js').ConversationManager} or the
+* {@link import('../Conversation.js').Conversation} — the same seam as
+* {@link import('../../workspaces/stores/DatabaseWorkspaceStore.js').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
+* 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
+* `{ 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`).
+*
+* - **`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('../../helpers.js').isConversationSnapshot} — the
+*   AGENTS §14 boundary narrow 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
+* §22 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 constructor `seed` (its `open` / `save`).
+*
+* @example
+* ```ts
+* import { createConversation, createDatabaseConversationStore, createMemoryDriver } from '@src/core'
+*
+* const store = createDatabaseConversationStore(createMemoryDriver()) // a durable driver swaps in here
+* const conversation = createConversation()
+* conversation.add({ role: 'user', content: 'hello' })
+* await store.set(conversation.snapshot())        // persist the conversation (one JSON column)
+* const snapshot = await store.get(conversation.id)
+* await store.delete(conversation.id)             // drop it
+* ```
+*/
+var DatabaseConversationStore = class {
+	#table;
+	/**
+	* Wrap a table as a conversation store.
+	*
+	* @param table - The {@link TableInterface} holding the snapshots — its row is the
+	*   {@link ConversationSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
+	*/
+	constructor(table) {
+		this.#table = table;
+	}
+	/** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `ConversationSnapshot`. */
+	async get(id) {
+		const row = await this.#table.get(id);
+		if (row === void 0) return void 0;
+		return isConversationSnapshot(row.snapshot) ? row.snapshot : void 0;
+	}
+	/** Insert or replace 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,
+			snapshot
+		});
+	}
+	/** Drop a snapshot by id; an absent id is a no-op (no throw). */
+	async delete(id) {
+		await this.#table.remove(id);
+	}
+};
+//#endregion
+//#region src/core/conversations/stores/MemoryConversationStore.ts
+/**
+* The in-memory {@link ConversationStoreInterface} — 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 import('../../workspaces/stores/MemoryWorkspaceStore.js').MemoryWorkspaceStore}.
+*
+* @remarks
+* A plain `Map<string, ConversationSnapshot>` (AGENTS §21 — the snapshot is already pure,
+* self-contained JSON, so no encoding is needed for the memory tier). Like the
+* {@link import('../../workspaces/stores/MemoryWorkspaceStore.js').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
+* 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).
+* - **`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 §22 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 constructor `seed` (its `open` / `save`).
+*
+* @example
+* ```ts
+* import { createConversation, createMemoryConversationStore } from '@src/core'
+*
+* const store = createMemoryConversationStore()
+* const conversation = createConversation()
+* conversation.add({ role: 'user', content: 'hello' })
+* await store.set(conversation.snapshot())   // persist the conversation
+* const snapshot = await store.get(conversation.id)
+* await store.delete(conversation.id)        // drop it
+* ```
+*/
+var MemoryConversationStore = class {
+	#snapshots = /* @__PURE__ */ new Map();
+	get(id) {
+		return Promise.resolve(this.#snapshots.get(id));
+	}
+	set(snapshot) {
+		this.#snapshots.set(snapshot.id, snapshot);
+		return Promise.resolve();
+	}
+	delete(id) {
+		this.#snapshots.delete(id);
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/core/scopes/Scope.ts
+/**
+* A named, immutable filter over a richer context's items — three optional allow-lists,
+* one 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`).
+*
+* @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
+*   step / loop apply this via `filterAllowList`.
+* - **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
+*   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
+*   `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
+*   can never be re-admitted by a child.
+*
+* @example
+* ```ts
+* const scope = new Scope({ name: 'reader', tools: ['search', 'read'] })
+* // narrow intersects: tools ∩ ['read', 'write'] = ['read'] (write was never in the parent).
+* const tighter = scope.narrow({ tools: ['read', 'write'] })
+* tighter.tools // ['read']
+* // instructions had no parent constraint (undefined) → the child's list passes through.
+* tighter.narrow({ instructions: ['safety'] }).instructions // ['safety']
+* ```
+*/
+var Scope = class Scope {
+	id = crypto.randomUUID();
+	name;
+	instructions;
+	tools;
+	files;
+	constructor(input) {
+		this.name = input.name;
+		this.instructions = input.instructions === void 0 ? void 0 : [...input.instructions];
+		this.tools = input.tools === void 0 ? void 0 : [...input.tools];
+		this.files = input.files === void 0 ? void 0 : [...input.files];
+	}
+	narrow(config) {
+		return new Scope({
+			name: this.name,
+			instructions: Scope.#intersect(this.instructions, config.instructions),
+			tools: Scope.#intersect(this.tools, config.tools),
+			files: Scope.#intersect(this.files, config.files)
+		});
+	}
+	static #intersect(parent, child) {
+		if (parent === void 0) return child === void 0 ? void 0 : [...child];
+		if (child === void 0) return [...parent];
+		const allowed = new Set(parent);
+		return child.filter((key) => allowed.has(key));
+	}
+};
+//#endregion
+//#region src/core/scopes/ScopeManager.ts
+/**
+* The scope registry a richer context reuses named filters from — immutable {@link Scope}s
+* keyed by their minted `id`, in insertion order.
+*
+* @remarks
+* - **Registry.** Scopes live in an insertion-ordered `Map` keyed by their minted `id`;
+*   `create` mints a {@link Scope} from a {@link ScopeInput} (an `id` plus the three
+*   allow-lists), stores it, and returns it. `count` is the map size, `scope(id)` looks
+*   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 (§9.2) — `true` when any was
+*   removed; `clear` empties the registry.
+* - **Observable (§13).** 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
+*   throw and routes it to its `error` handler (the `error` option), so a buggy observer can
+*   never corrupt a mutation.
+*
+* @example
+* ```ts
+* const manager = new ScopeManager()
+* const reader = manager.create({ name: 'reader', tools: ['search', 'read'] })
+* manager.scope(reader.id) // the same scope
+* manager.count // 1
+* ```
+*/
+var ScopeManager = class {
+	#scopes = /* @__PURE__ */ new Map();
+	#emitter;
+	constructor(on, error) {
+		this.#emitter = new Emitter({
+			on,
+			error
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get count() {
+		return this.#scopes.size;
+	}
+	create(input) {
+		const scope = new Scope(input);
+		this.#scopes.set(scope.id, scope);
+		this.#emitter.emit("create", scope);
+		return scope;
+	}
+	scope(id) {
+		return this.#scopes.get(id);
+	}
+	scopes() {
+		return [...this.#scopes.values()];
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = false;
+			for (const id of ids) if (this.#delete(id)) removed = true;
+			return removed;
+		}
+		return this.#delete(ids);
+	}
+	clear() {
+		this.#scopes.clear();
+		this.#emitter.emit("clear");
+	}
+	#delete(id) {
+		const removed = this.#scopes.delete(id);
+		if (removed) this.#emitter.emit("remove", id);
+		return removed;
+	}
+};
+//#endregion
+//#region src/core/ThinkSplitter.ts
+/**
+* The stream-stateful `<think>` separator — feeds raw content deltas through a tiny
+* 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}.
+*
+* @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
+*   `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
+*   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.
+* - **Multiple spans** accumulate onto `thinking` in stream order. A nested-looking
+*   `<think>` inside an open span is just thinking text (no nesting is tracked — the
+*   first `</think>` closes the span), matching how the models emit it.
+* - **Unclosed span at stream end.** `flush()` routes the open span's tail (including
+*   any held partial close tag) to `thinking` — a cut-off model was still reasoning.
+* - **One splitter, one stream.** State is per-stream; create a fresh instance per
+*   provider call ({@link import('./factories.js').createThinkSplitter}).
+*
+* @example
+* ```ts
+* const splitter = new ThinkSplitter()
+* splitter.split('<thi') // '' (held — ambiguous)
+* splitter.split('nk>plan</think>ok') // 'ok'
+* splitter.thinking // 'plan'
+* splitter.content // 'ok'
+* splitter.flush() // '' (nothing held)
+* ```
+*/
+var ThinkSplitter = class {
+	#pending = "";
+	#inside = false;
+	#opened = false;
+	#content = "";
+	#thinking = "";
+	get content() {
+		return this.#content;
+	}
+	get thinking() {
+		return this.#thinking;
+	}
+	split(delta) {
+		const out = this.#scan(delta);
+		this.#content += out;
+		return out;
+	}
+	flush() {
+		const pending = this.#pending;
+		this.#pending = "";
+		if (this.#inside) {
+			this.#thinking += pending;
+			this.#inside = false;
+			return "";
+		}
+		this.#content += pending;
+		return pending;
+	}
+	#scan(delta) {
+		this.#pending += delta;
+		let content = "";
+		for (;;) {
+			if (this.#inside) {
+				const close = this.#pending.indexOf(THINK_CLOSE);
+				if (close === -1) {
+					this.#thinking += this.#hold([THINK_CLOSE]);
+					return content;
+				}
+				this.#thinking += this.#pending.slice(0, close);
+				this.#pending = this.#pending.slice(close + THINK_CLOSE.length);
+				this.#inside = false;
+				continue;
+			}
+			const open = this.#pending.indexOf(THINK_OPEN);
+			if (!this.#opened) {
+				const close = this.#pending.indexOf(THINK_CLOSE);
+				if (close !== -1 && (open === -1 || close < open)) {
+					this.#thinking += this.#content + content + this.#pending.slice(0, close);
+					this.#content = "";
+					content = "";
+					this.#pending = this.#pending.slice(close + THINK_CLOSE.length);
+					this.#opened = true;
+					continue;
+				}
+			}
+			if (open === -1) {
+				const tags = this.#opened ? [THINK_OPEN] : [THINK_OPEN, THINK_CLOSE];
+				content += this.#hold(tags);
+				return content;
+			}
+			this.#opened = true;
+			content += this.#pending.slice(0, open);
+			this.#pending = this.#pending.slice(open + THINK_OPEN.length);
+			this.#inside = true;
+		}
+	}
+	#hold(tags) {
+		const keep = Math.max(...tags.map((tag) => this.#overlap(tag)));
+		const cut = this.#pending.length - keep;
+		const settled = this.#pending.slice(0, cut);
+		this.#pending = this.#pending.slice(cut);
+		return settled;
+	}
+	#overlap(tag) {
+		const max = Math.min(this.#pending.length, tag.length - 1);
+		for (let length = max; length > 0; length -= 1) if (this.#pending.endsWith(tag.slice(0, length))) return length;
+		return 0;
+	}
+};
+//#endregion
+//#region src/core/tools/Tool.ts
+/**
+* A registered tool — its {@link import('../types.js').ToolDefinition} schema (the
+* `name` / `description` / `parameters` the model sees) bound to the `execute`
+* handler that runs a call.
+*
+* @remarks
+* A thin value object: the constructor stores the schema fields and the handler, and
+* `execute` delegates to the handler verbatim. `parameters` is kept by reference (the
+* open JSON-Schema the provider forwards as-is) — not cloned. The handler's `args` is
+* the model-supplied `unknown` arguments record, narrowed inside the handler (§14);
+* isolating a throw is the {@link ToolManager}'s job, not this class's. Event-free —
+* no Emitter, no events.
+*
+* @example
+* ```ts
+* const tool = new Tool({
+* 	name: 'add',
+* 	description: 'Add two numbers',
+* 	parameters: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } } },
+* 	execute: (args) => Number(args.a) + Number(args.b),
+* })
+* ```
+*/
+var Tool = class {
+	name;
+	description;
+	parameters;
+	#execute;
+	constructor(options) {
+		this.name = options.name;
+		this.description = options.description;
+		this.parameters = options.parameters;
+		this.#execute = options.execute;
+	}
+	execute(args) {
+		return this.#execute(args);
+	}
+};
+//#endregion
+//#region src/core/workspaces/stores/DatabaseWorkspaceStore.ts
+/**
+* A {@link WorkspaceStoreInterface} backed by one table of the `databases` layer — a workspace'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('./MemoryWorkspaceStore.js').MemoryWorkspaceStore}.
+*
+* @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
+* {@link import('../WorkspaceManager.js').WorkspaceManager} or the
+* {@link import('../Workspace.js').Workspace} — the same seam as
+* the analogous `DatabaseWorkflowStore` in `@orkestrel/workflow`. The
+* driver defaults to memory ({@link import('../../factories.js').createDatabaseWorkspaceStore}
+* 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 WorkspaceSnapshot} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+* `{ id; snapshot }` ({@link WorkspaceSnapshotRow}), the snapshot the whole JSON blob (a `rawShape`
+* column the factory builds) — exactly as `DatabaseWorkflowStore` 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`).
+*
+* - **`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 WorkspaceSnapshot} ({@link import('../../helpers.js').isWorkspaceSnapshot} — the AGENTS
+*   §14 boundary narrow 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 workspace lives until an
+* explicit `delete`. The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the
+* §22 method bijection with {@link WorkspaceStoreInterface}). Hydration stays a caller concern: a
+* {@link import('../WorkspaceManager.js').WorkspaceManager} reads a snapshot back and rebuilds the
+* live workspace through the constructor `seed` (its `open` / `save`).
+*
+* @example
+* ```ts
+* import { createDatabaseWorkspaceStore, createMemoryDriver, createWorkspace } from '@src/core'
+*
+* const store = createDatabaseWorkspaceStore(createMemoryDriver()) // a durable driver swaps in here
+* const workspace = createWorkspace()
+* workspace.write('notes.txt', 'hello')
+* await store.set(workspace.snapshot())          // persist the workspace (one JSON column)
+* const snapshot = await store.get(workspace.id)
+* await store.delete(workspace.id)               // drop it
+* ```
+*/
+var DatabaseWorkspaceStore = class {
+	#table;
+	/**
+	* Wrap a table as a workspace store.
+	*
+	* @param table - The {@link TableInterface} holding the snapshots — its row is the
+	*   {@link WorkspaceSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
+	*/
+	constructor(table) {
+		this.#table = table;
+	}
+	/** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `WorkspaceSnapshot`. */
+	async get(id) {
+		const row = await this.#table.get(id);
+		if (row === void 0) return void 0;
+		return isWorkspaceSnapshot(row.snapshot) ? row.snapshot : void 0;
+	}
+	/** Insert or replace 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,
+			snapshot
+		});
+	}
+	/** Drop a snapshot by id; an absent id is a no-op (no throw). */
+	async delete(id) {
+		await this.#table.remove(id);
+	}
+};
+//#endregion
+//#region src/core/workspaces/stores/MemoryWorkspaceStore.ts
+/**
+* The in-memory {@link WorkspaceStoreInterface} — a process-lifetime `Map` of
+* {@link WorkspaceSnapshot}s keyed by workspace id, the DEFAULT store
+* {@link import('../../factories.js').createMemoryWorkspaceStore} builds.
+*
+* @remarks
+* A plain `Map<string, WorkspaceSnapshot>` (AGENTS §21 — the snapshot is already pure,
+* self-contained JSON, so no encoding is needed for the memory tier). Like the
+* the analogous `MemoryWorkflowStore` in `@orkestrel/workflow` it twins,
+* there is NO idle-TTL and NO eviction: a persisted workspace lives until an explicit `delete`. A
+* durable backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching
+* the {@link import('../WorkspaceManager.js').WorkspaceManager} or the
+* {@link import('../Workspace.js').Workspace} — its driver-pluggable twin is
+* {@link import('./DatabaseWorkspaceStore.js').DatabaseWorkspaceStore} (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).
+* - **`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 §22 method
+* bijection with {@link WorkspaceStoreInterface}). Hydration is a caller concern: a
+* {@link import('../WorkspaceManager.js').WorkspaceManager} reads a snapshot back and rebuilds the
+* live workspace through the constructor `seed` (its `open` / `save`).
+*
+* @example
+* ```ts
+* import { createMemoryWorkspaceStore, createWorkspace } from '@src/core'
+*
+* const store = createMemoryWorkspaceStore()
+* const workspace = createWorkspace()
+* workspace.write('notes.txt', 'hello')
+* await store.set(workspace.snapshot())     // persist the workspace
+* const snapshot = await store.get(workspace.id)
+* await store.delete(workspace.id)          // drop it
+* ```
+*/
+var MemoryWorkspaceStore = class {
+	#snapshots = /* @__PURE__ */ new Map();
+	get(id) {
+		return Promise.resolve(this.#snapshots.get(id));
+	}
+	set(snapshot) {
+		this.#snapshots.set(snapshot.id, snapshot);
+		return Promise.resolve();
+	}
+	delete(id) {
+		this.#snapshots.delete(id);
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a tool — a {@link ToolInterface} binding a {@link ToolDefinition} schema
+* (the `name` / `description` / `parameters` the model sees) to the `execute` handler
+* that runs a call.
+*
+* @remarks
+* Only `name` is required (it keys the tool in a {@link ToolManagerInterface} and is
+* what the model calls); `description` / `parameters` are the optional JSON-Schema the
+* provider advertises (forwarded verbatim). The handler's `args` is the model-supplied
+* `unknown` arguments record — narrow it inside (§14); a `createToolManager` registry
+* isolates a throw into a `ToolResult.error`.
+*
+* @param options - `name` (required), optional `description` / `parameters`, and the
+*   `execute` handler (see {@link ToolOptions})
+* @returns A working {@link ToolInterface}
+*
+* @example
+* ```ts
+* import { createTool } from '@src/core'
+*
+* const add = createTool({
+* 	name: 'add',
+* 	description: 'Add two numbers',
+* 	execute: (args) => Number(args.a) + Number(args.b),
+* })
+* ```
+*/
+function createTool(options) {
+	return new Tool(options);
+}
+/**
+* Create a tool registry — a {@link ToolManagerInterface} that resolves tool names,
+* lists {@link ToolDefinition}s for the provider, and executes calls with per-call
+* error isolation.
+*
+* @remarks
+* Starts empty; `add` registers one tool or a batch (§9.2), `definitions()` yields the
+* schemas to hand a provider, and `execute` runs a {@link ToolCall} (or a batch),
+* ALWAYS resolving a {@link ToolResult} — a handler throw becomes an `error` result and
+* an unknown name a not-found `error`, so a tool throw never escapes and a batch never
+* fails as a whole.
+*
+* @returns An empty {@link ToolManagerInterface}
+*
+* @example
+* ```ts
+* import { createTool, createToolManager } from '@src/core'
+*
+* const tools = createToolManager()
+* tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
+* const result = await tools.execute({ id: '1', name: 'add', arguments: { x: 1, y: 2 } })
+* ```
+*/
+function createToolManager() {
+	return new ToolManager();
+}
+/**
+* Create a conversation — a {@link ConversationInterface} grouping messages above a flat
+* 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 ConversationSummarizer} 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 SectionInterface} 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
+* the retained originals. Observable (`emitter` — `compact` / `summary` / `rehydrate`), wired
+* via the reserved `on` option (§8); the emitter isolates a listener throw and routes it to
+* its `error` handler (the `error` option, §13), so it can never corrupt a compaction.
+*
+* @param options - Optional `id` / `on` hooks + the `summarize` seam + `keep` (see {@link ConversationOptions})
+* @returns A working {@link ConversationInterface}
+*
+* @example
+* ```ts
+* import type { ProviderInterface } from '@src/core'
+* import { createConversation } from '@src/core'
+*
+* declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+* 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,
+* })
+* conversation.add({ role: 'user', content: 'Hello' })
+* await conversation.compact() // folds the live tail into a summarized section
+* ```
+*/
+function createConversation(options) {
+	return new Conversation(options);
+}
+/**
+* Create a conversation registry — a {@link ConversationManagerInterface} holding
+* {@link ConversationInterface}s keyed by their `id` (in insertion order) WITH an active pointer:
+* the §9 store over the conversation layer plus the `active` / `switch` seam the context renders.
+*
+* @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
+* `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, §9.2) reports whether any was removed AND
+* clears `active` if it was the removed one; `clear` empties it and clears `active`. Event-free
+* (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})
+* @returns An empty {@link ConversationManagerInterface}
+*
+* @example
+* ```ts
+* import { createConversationManager } from '@src/core'
+*
+* const conversations = createConversationManager({ summarize: async (m) => `recap of ${m.length}` })
+* const chat = conversations.add() // auto-activates — conversations.active === chat
+* chat.add({ role: 'user', content: 'Hello' })
+* ```
+*/
+function createConversationManager(options) {
+	return new ConversationManager(options);
+}
+/**
+* Create 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} /
+* {@link ConversationManagerInterface.save} seam. The EXACT twin of {@link createMemoryWorkspaceStore}.
+*
+* @remarks
+* A plain `Map` (the snapshot is already pure JSON, so no encoding is needed for the memory tier),
+* the structural twin of {@link createMemoryWorkspaceStore}. `get` / `set` / `delete` are async (the
+* 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
+* touching the manager or the conversation. Hydration stays a manager concern: read a snapshot back
+* and rebuild the live conversation through the constructor `seed` (re-supplying the live
+* `summarize` / `keep`).
+*
+* @returns A memory-backed {@link ConversationStoreInterface}
+*
+* @example
+* ```ts
+* import { createConversationManager, createMemoryConversationStore } from '@src/core'
+*
+* const store = createMemoryConversationStore()
+* const manager = createConversationManager({ store })
+* const conversation = manager.add()
+* conversation.add({ role: 'user', content: 'hello' })
+* await manager.save(conversation.id)            // persist the conversation
+* ```
+*/
+function createMemoryConversationStore() {
+	return new MemoryConversationStore();
+}
+/**
+* Create a {@link DatabaseConversationStore} over any {@link DriverInterface} — the durable,
+* driver-pluggable backing for the conversation persistence seam, the opt-in twin of
+* {@link createMemoryConversationStore}. The EXACT twin of {@link 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
+* `rawShape` (a JSON blob), exactly as {@link 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('./helpers.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.
+*
+* @param driver - The storage backend the snapshots persist to (defaults to {@link createMemoryDriver})
+* @returns A {@link ConversationStoreInterface} over the driver
+*
+* @example
+* ```ts
+* import { createConversationManager, createDatabaseConversationStore, createMemoryDriver } from '@src/core'
+*
+* const store = createDatabaseConversationStore(createMemoryDriver()) // a durable driver swaps in here
+* const manager = createConversationManager({ store })
+* const conversation = manager.add()
+* conversation.add({ role: 'user', content: 'hello' })
+* await manager.save(conversation.id)            // persist the conversation (one JSON column)
+* ```
+*/
+function createDatabaseConversationStore(driver = createMemoryDriver()) {
+	return new DatabaseConversationStore(createDatabase({
+		driver,
+		tables: { conversations: {
+			id: stringShape(),
+			snapshot: rawShape({})
+		} }
+	}).table("conversations"));
+}
+/**
+* Create an instruction — an immutable {@link InstructionInterface} (a named directive)
+* from its `name` / `content` and optional `priority`, the `id` minted at construction.
+*
+* @remarks
+* Only `name` / `content` are required; `priority` orders the instruction in an
+* {@link InstructionManagerInterface}'s rendered list (higher first) and defaults to `0`.
+* Stored immutable — never mutated after creation.
+*
+* @param input - `name` / `content` (required) and an optional `priority` (see
+*   {@link InstructionInput})
+* @returns A working {@link InstructionInterface}
+*
+* @example
+* ```ts
+* import { createInstruction } from '@src/core'
+*
+* const instruction = createInstruction({ name: 'tone', content: 'Be concise.', priority: 5 })
+* ```
+*/
+function createInstruction(input) {
+	return new Instruction(input);
+}
+/**
+* Create an instruction registry — an {@link InstructionManagerInterface} holding
+* immutable instructions keyed by `name`, listed by descending `priority`.
+*
+* @remarks
+* Starts empty; `add` (one or a batch, §9.2) MINTS each `id` and OVERWRITES a same-name
+* instruction (last write wins); `instructions()` lists them sorted by descending
+* `priority` (stable for ties); `format` / `description` are the build contract a richer
+* context renders an instructions block with; `remove` (one or a batch) reports whether
+* any was removed; `clear` empties it. Carries an observable `emitter`
+* ({@link import('./types.js').InstructionManagerEventMap}) wired via the reserved `on`
+* option (§8); the emitter isolates a listener throw and routes it to its `error` handler
+* (the `error` option, §13), so it can never corrupt a mutation. An optional `format`
+* override is the manager-options level of the `AgentContext` build cascade (consulted by
+* `description` / `format`, beating the provider default + built-in; a per-item
+* `InstructionInput.format` still beats it).
+*
+* @param options - Optional `on` hooks + a `format` override (see {@link InstructionManagerOptions})
+* @returns An empty {@link InstructionManagerInterface}
+*
+* @example
+* ```ts
+* import { createInstructionManager } from '@src/core'
+*
+* const instructions = createInstructionManager()
+* instructions.add({ name: 'tone', content: 'Be concise.', priority: 5 })
+* ```
+*/
+function createInstructionManager(options) {
+	return new InstructionManager(options);
+}
+/**
+* Create a named scope — an immutable {@link ScopeInterface} from its `name` and the four
+* optional 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
+* immutable — never mutated after creation (`narrow` returns a new scope).
+*
+* @param input - `name` (required) and the optional `instructions` / `tools` / `messages` /
+*   `files` allow-lists (see {@link ScopeInput})
+* @returns A working {@link ScopeInterface}
+*
+* @example
+* ```ts
+* import { createScope } from '@src/core'
+*
+* const reader = createScope({ name: 'reader', tools: ['search', 'read'] })
+* reader.narrow({ tools: ['read', 'write'] }).tools // ['read'] — intersection tightens
+* ```
+*/
+function createScope(input) {
+	return new Scope(input);
+}
+/**
+* Create a scope registry — a {@link ScopeManagerInterface} holding immutable scopes keyed
+* by their minted `id`, in insertion order.
+*
+* @remarks
+* Starts empty; `create` mints each scope's `id` and stores it (keyed by `id`, so it
+* always adds — two scopes may share a `name`); `scopes()` lists them in insertion order;
+* `remove` (one or a batch, §9.2) reports whether any was removed; `clear` empties it.
+* Carries an observable `emitter` ({@link import('./types.js').ScopeManagerEventMap}) wired
+* via the reserved `on` option (§8); the emitter isolates a listener throw and routes it to
+* its `error` handler (the `error` option, §13), so it can never corrupt a mutation.
+*
+* @param options - Optional `on` hooks (see {@link ScopeManagerOptions})
+* @returns An empty {@link ScopeManagerInterface}
+*
+* @example
+* ```ts
+* import { createScopeManager } from '@src/core'
+*
+* const scopes = createScopeManager()
+* const reader = scopes.create({ name: 'reader', tools: ['search'] })
+* ```
+*/
+function createScopeManager(options) {
+	return new ScopeManager(options?.on, options?.error);
+}
+/**
+* Create 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.
+*
+* @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
+* present); `scope` is the initial active filter (`undefined` ⇒ no filtering, mutable afterwards
+* via `context.scope`). The `messages` store is always fresh. `build()` folds the scoped
+* 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' `data` to the last user message), built fresh each call; the active
+* workspace is the SOLE document/image context. Tools are advertised STRUCTURALLY (via
+* `tools.definitions()`, scope-filtered by the loop), never serialized into the prompt.
+*
+* @param options - Optional `system` / `tools` / `instructions` / `workspaces` / `scope`
+*   (see {@link AgentContextOptions})
+* @returns A working {@link AgentContextInterface}
+*
+* @example
+* ```ts
+* import { createAgentContext } from '@src/core'
+*
+* const context = createAgentContext({ system: 'You are concise.' })
+* context.instructions.add({ name: 'tone', content: 'Be terse.' })
+* context.messages.add({ role: 'user', content: 'Hi' })
+* context.build() // [{ role: 'system', content: 'You are concise.\n\n## Instructions\n\nBe terse.' }, { role: 'user', content: 'Hi' }]
+* ```
+*/
+function createAgentContext(options) {
+	return new AgentContext(options);
+}
+/**
+* Create an agent loop — an {@link AgentInterface} composing a
+* {@link ProviderInterface}, its {@link AgentContextInterface}, and a tool registry
+* into a bounded context → provider → tools → repeat turn, exposed as a one-shot
+* `generate` and a live `stream`.
+*
+* @remarks
+* 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` (via `AbortSignal.any`) — any trip (or `abort()`)
+* 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 via `context.tools.definitions()`. Two observation surfaces: the
+* {@link AgentChunk} stream (pull — per-token content) and a typed `emitter` (push —
+* lifecycle + `usage` / `tool` / `deny` for fire-and-forget observers).
+*
+* @param provider - The {@link ProviderInterface} the loop drives each turn
+* @param options - Optional `system` / `tools` / `limit` / `timeout` / `budget` /
+*   `scheduler` / `signal` (see {@link AgentOptions})
+* @returns A working {@link AgentInterface}
+*
+* @example
+* ```ts
+* import type { ProviderInterface } from '@src/core'
+* import { createAgent, createTokenBudget } from '@src/core'
+*
+* declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+* const agent = createAgent(provider, {
+* 	system: 'You are concise.',
+* 	budget: createTokenBudget({ max: 50_000, scope: 'total' }),
+* })
+* agent.context.messages.add({ role: 'user', content: 'Say hi.' })
+*
+* const stream = agent.stream()
+* for await (const chunk of stream.events) {
+* 	if (chunk.type === 'token') process.stdout.write(chunk.content)
+* }
+* const result = await stream.result // { content, usage?, partial }
+* ```
+*/
+function createAgent(provider, options) {
+	return new Agent(provider, options);
+}
+/**
+* Create 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}.
+*
+* @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
+* disambiguated, multiple spans accumulate in order, and a nested-looking `<think>`
+* inside an open span is just thinking text. One splitter serves ONE stream — create
+* a fresh one per provider call.
+*
+* @returns A fresh {@link ThinkSplitterInterface} (state empty, outside any span)
+*
+* @example
+* ```ts
+* import { createThinkSplitter } from '@src/core'
+*
+* const splitter = createThinkSplitter()
+* const clean = splitter.split('<think>plan the answer</think>Here it is.')
+* clean // 'Here it is.'
+* splitter.thinking // 'plan the answer'
+* ```
+*/
+function createThinkSplitter() {
+	return new ThinkSplitter();
+}
+/**
+* Create a policy gate — an {@link AuthorityInterface} the agent loop consults before
+* each tool call runs, evaluating the ordered rules first-match-wins and falling back
+* 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
+* `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
+* the result into `createAgent` via `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 now — the async human-approval handshake is deferred.
+*
+* @param options - Optional `rules` (ordered) and `fallback` (see {@link AuthorityOptions})
+* @returns A working {@link AuthorityInterface}
+*
+* @example
+* ```ts
+* import { createAgent, createAuthority } from '@src/core'
+*
+* // Deny the `delete` tool, allow everything else.
+* const authority = createAuthority({
+* 	rules: [{ match: (c) => c.call.name === 'delete', zone: 'restricted', allowed: false }],
+* })
+* const agent = createAgent(provider, { tools, authority })
+* ```
+*/
+function createAuthority(options) {
+	return new Authority(options);
+}
+/**
+* Create an agent registry — an {@link AgentRegistryInterface} holding the named pools of
+* live, non-serializable pieces (providers, tools, authorities, schedulers) that a
+* serializable {@link AgentJobInput}'s names resolve against, and `build`ing a seeded,
+* signal-wired {@link AgentInterface} from a job.
+*
+* @remarks
+* `providers` is required; `tools` / `authorities` / `schedulers` are optional pools.
+* The accessors (`provider` / `tool` / `authority` / `scheduler`) THROW `unknown <category>:
+* <name>` on an unregistered name (§9.1 + §12) — a misconfigured or crash-restored job
+* fails loudly rather than running with a missing dependency. `build(input, signal)`
+* resolves the names, rebuilds the token budget from its ceiling, seeds the agent's
+* context with the job's messages, and threads `signal` so a queue / runner abort
+* propagates. This is the bridge that makes durable, serializable agent jobs runnable.
+*
+* @param options - The named pools (see {@link AgentRegistryOptions})
+* @returns A working {@link AgentRegistryInterface}
+*
+* @example
+* ```ts
+* import type { ProviderInterface } from '@src/core'
+* import { createAgentRegistry, createTool } from '@src/core'
+*
+* declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+* const registry = createAgentRegistry({
+* 	providers: { main: provider },
+* 	tools: { add: createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }) },
+* })
+* const agent = registry.build({ provider: 'main', messages: [{ role: 'user', content: 'Hi.' }] })
+* ```
+*/
+function createAgentRegistry(options) {
+	return new AgentRegistry(options);
+}
+/**
+* Create a durable, bounded-concurrency agent-job queue — a {@link QueueInterface} over
+* 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.
+*
+* @remarks
+* - **Composes the substrate (no new engine).** The handler is the only new logic;
+*   bounded `concurrency`, `retries`, the per-attempt `timeout`, and durable persistence
+*   via `store` (+ `restore()` after a crash) are all the backing Queue's. `enqueue`
+*   returns a per-job promise.
+* - **Durable + serializable.** Because `AgentJobInput` is JSON-serializable, a `store`
+*   (e.g. `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
+*   {@link import('./errors.js').AgentJobError} by default, so a job cancelled by its
+*   attempt deadline / a queue abort RETRIES while attempts remain; `allowPartial: true`
+*   resolves the partial as success instead.
+* - **Cancellation threads through.** The handler passes `execution.signal` into
+*   `registry.build`, so a queue `abort()` or a per-attempt timeout cancels the in-flight
+*   agent (which commits a partial → throws → retries / fails per policy).
+*
+* @param options - The `registry`, the `allowPartial` policy, and the substrate knobs
+*   (`concurrency` / `retries` / `timeout` / `store`) (see {@link AgentQueueOptions})
+* @returns A {@link QueueInterface} of {@link AgentJobInput} → {@link AgentResult}
+*
+* @example
+* ```ts
+* import { createAgentQueue, createAgentRegistry, createMemoryQueueStore } from '@src/core'
+*
+* const registry = createAgentRegistry({ providers: { main: provider } })
+* const store = createMemoryQueueStore(agentJobShape) // survives a restart via restore()
+* const queue = createAgentQueue({ registry, concurrency: 2, retries: 1, store })
+* const result = await queue.enqueue({ provider: 'main', messages: [{ role: 'user', content: 'ok?' }] })
+* ```
+*/
+function createAgentQueue(options) {
+	const { registry, allowPartial = false, concurrency, retries, timeout, store } = options;
+	return createQueue({
+		concurrency,
+		retries,
+		timeout,
+		store,
+		handler: (input, execution) => settleAgentJob(registry.build(input, execution.signal), allowPartial)
+	});
+}
+/**
+* Create 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)`.
+*
+* @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
+*   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
+*   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), `allowPartial: true` resolves it; the
+*   handler threads `controller.signal` into `registry.build`, so a runner abort / a
+*   per-attempt timeout cancels the agent.
+*
+* @param options - The `registry`, the `allowPartial` policy, and the substrate knobs
+*   (`concurrency` / `retries` / `timeout`) (see {@link AgentRunnerOptions})
+* @returns A {@link RunnerInterface} of {@link AgentJobInput} → {@link AgentResult}
+*
+* @example
+* ```ts
+* import { createAgentRunner, createAgentRegistry } from '@src/core'
+*
+* const registry = createAgentRegistry({ providers: { main: provider } })
+* const runner = createAgentRunner({ registry, concurrency: 2 })
+* // Run two jobs; the first fans out a child sub-agent then returns.
+* const child = { provider: 'main', messages: [{ role: 'user', content: 'child' }] }
+* const parent = { provider: 'main', messages: [{ role: 'user', content: 'parent' }] }
+* const results = await runner.execute([parent, child]) // declared first, then any spawns
+* ```
+*/
+function createAgentRunner(options) {
+	const { registry, allowPartial = false, concurrency, retries, timeout } = options;
+	return createRunner({
+		concurrency,
+		retries,
+		timeout,
+		handler: (controller) => {
+			const children = controller.input.children;
+			if (children !== void 0) for (const child of children) controller.spawn(child);
+			return settleAgentJob(registry.build(controller.input, controller.signal), allowPartial);
+		}
+	});
+}
+/**
+* Create a file — an immutable {@link FileInterface} from its `path` + {@link FileContent}
+* and optional {@link import('./types.js').FileState}, with `size` / `lines` DERIVED from the
+* content.
+*
+* @remarks
+* Returns a PLAIN `Object.freeze`d record (NOT a class instance) — the `path` IS its identity
+* (there is no `id`). Only `path` / `content` are required; `state` defaults to `'created'`
+* when omitted. `size` (via {@link computeSize}) and `lines` (via {@link countLines}) are
+* computed from the content here (so they never drift from it). Frozen + plain, so it
+* `structuredClone`s losslessly and is never mutated after creation.
+*
+* @param input - `path` / `content` (required) and an optional `state` (see {@link FileInput})
+* @returns A frozen {@link FileInterface} record
+*
+* @example
+* ```ts
+* import { createFile, createTextContent } from '@src/core'
+*
+* const file = createFile({ path: 'src/main.ts', content: createTextContent('const x = 1', 'typescript') })
+* file.lines // 1
+* ```
+*/
+function createFile(input) {
+	return Object.freeze({
+		path: input.path,
+		content: input.content,
+		state: input.state ?? "created",
+		size: computeSize(input.content),
+		lines: countLines(input.content)
+	});
+}
+/**
+* Build the TEXT {@link FileContent} arm — the §4.2.3 split constructor for text (a separate
+* function per arm, not one constructor dispatching on a discriminator parameter).
+*
+* @param text - The literal text body
+* @param language - The fenced-code language the text renders as (e.g. `'typescript'`)
+* @returns A `{ text; language }` content arm
+*
+* @example
+* ```ts
+* import { createTextContent } from '@src/core'
+*
+* createTextContent('const x = 1', 'typescript') // { text: 'const x = 1', language: 'typescript' }
+* ```
+*/
+function createTextContent(text, language) {
+	return {
+		text,
+		language
+	};
+}
+/**
+* Build the BINARY {@link FileContent} arm — the §4.2.3 split constructor for binary (a
+* separate function per arm, not one constructor dispatching on a discriminator parameter).
+* An image is just a binary with an image {@link BinaryMIME}.
+*
+* @param data - The base64-encoded binary payload
+* @param mime - The {@link BinaryMIME} that labels the payload
+* @returns A `{ data; mime }` content arm
+*
+* @example
+* ```ts
+* import { createBinaryContent } from '@src/core'
+*
+* createBinaryContent('<base64>', 'image/png') // { data: '<base64>', mime: 'image/png' }
+* ```
+*/
+function createBinaryContent(data, mime) {
+	return {
+		data,
+		mime
+	};
+}
+/**
+* Create a workspace — a mutable, `path`-keyed working set of immutable
+* {@link FileInterface}s with the in-memory edit surface (read / write / search / replace /
+* move / remove), observable through its `EmitterInterface` (from `@orkestrel/emitter`).
+*
+* @param options - Optional initial {@link import('./types.js').WorkspaceEventMap} listeners (`on`) and the emitter's `error` handler (see {@link WorkspaceOptions})
+* @returns A working {@link WorkspaceInterface}
+*
+* @example
+* ```ts
+* import { createWorkspace } from '@src/core'
+*
+* const workspace = createWorkspace({ on: { write: (file) => console.log(file.path) } })
+* workspace.write('src/main.ts', 'const x = 1')
+* workspace.file('src/main.ts')?.state // 'created'
+* ```
+*/
+function createWorkspace(options) {
+	return new Workspace(options);
+}
+/**
+* Create the in-memory workspace store — a {@link WorkspaceStoreInterface} backed by a
+* process-lifetime `Map` of {@link import('./types.js').WorkspaceSnapshot}s keyed by workspace id,
+* the DEFAULT backing for the durable {@link WorkspaceManagerInterface.open} /
+* {@link WorkspaceManagerInterface.save} seam.
+*
+* @remarks
+* A plain `Map` (the snapshot is already pure JSON, so no encoding is needed for the memory tier),
+* the structural twin of the analogous `createMemoryWorkflowStore` in `@orkestrel/workflow`.
+* `get` / `set` / `delete` are async (the same shape a durable backend fits); UNLIKE a session
+* store there is NO idle-TTL / eviction — a persisted workspace lives until an explicit `delete`.
+* Its driver-pluggable twin is {@link createDatabaseWorkspaceStore} (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 touching the manager or the workspace. Hydration stays a manager
+* concern: read a snapshot back and rebuild the live workspace through the constructor `seed`.
+*
+* @returns A memory-backed {@link WorkspaceStoreInterface}
+*
+* @example
+* ```ts
+* import { createMemoryWorkspaceStore, createWorkspaceManager } from '@src/core'
+*
+* const store = createMemoryWorkspaceStore()
+* const manager = createWorkspaceManager({ store })
+* const workspace = manager.add()
+* workspace.write('notes.txt', 'hello')
+* await manager.save(workspace.id)               // persist the workspace
+* ```
+*/
+function createMemoryWorkspaceStore() {
+	return new MemoryWorkspaceStore();
+}
+/**
+* Create a {@link DatabaseWorkspaceStore} over any {@link DriverInterface} — the durable,
+* driver-pluggable backing for the workspace persistence seam, the opt-in twin of
+* {@link createMemoryWorkspaceStore}.
+*
+* @remarks
+* Builds a one-table database (`workspaces`, 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
+* `rawShape` (a JSON blob), exactly as
+* the analogous `createDatabaseWorkflowStore` in `@orkestrel/workflow` 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('./helpers.js').isWorkspaceSnapshot}). 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 WorkspaceStoreInterface} WITHOUT touching the manager or the workspace.
+*
+* @param driver - The storage backend the snapshots persist to (defaults to {@link createMemoryDriver})
+* @returns A {@link WorkspaceStoreInterface} over the driver
+*
+* @example
+* ```ts
+* import { createDatabaseWorkspaceStore, createMemoryDriver, createWorkspaceManager } from '@src/core'
+*
+* const store = createDatabaseWorkspaceStore(createMemoryDriver()) // a durable driver swaps in here
+* const manager = createWorkspaceManager({ store })
+* const workspace = manager.add()
+* workspace.write('notes.txt', 'hello')
+* await manager.save(workspace.id)               // persist the workspace (one JSON column)
+* ```
+*/
+function createDatabaseWorkspaceStore(driver = createMemoryDriver()) {
+	return new DatabaseWorkspaceStore(createDatabase({
+		driver,
+		tables: { workspaces: {
+			id: stringShape(),
+			snapshot: rawShape({})
+		} }
+	}).table("workspaces"));
+}
+/**
+* Create a workspace registry — a {@link WorkspaceManagerInterface} holding
+* {@link WorkspaceInterface}s keyed by their `id` (in insertion order) WITH an active pointer:
+* the §9 store over the workspace layer plus the `active` / `switch` seam the context renders.
+*
+* @remarks
+* Starts empty; `add(input?)` mints a {@link WorkspaceInterface} (its `id` from the input or a
+* random UUID), flowing the manager's default `on` / `error` 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 workspaces 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); `workspace(id)` / `workspaces()` look up;
+* `remove` (one or a batch, §9.2) reports whether any was removed AND clears `active` if it was
+* the removed one; `clear` empties it and clears `active`. Event-free (each workspace owns its
+* own observable `emitter`).
+*
+* With the optional `store` ({@link WorkspaceStoreInterface}, e.g. `createMemoryWorkspaceStore` /
+* `createDatabaseWorkspaceStore`), `open(id)` HYDRATES a workspace on a registry miss (rebuilding it
+* through the constructor `seed` from the snapshot's `files`, then activating it) and `save(id)`
+* PERSISTS a registered workspace's `snapshot()`. Both are LENIENT without a store (open resolves
+* only registered ids, save is a no-op `false`).
+*
+* @param options - Optional default `on` / `error` for created workspaces + the durable `store`
+*   (see {@link WorkspaceManagerOptions})
+* @returns An empty {@link WorkspaceManagerInterface}
+*
+* @example
+* ```ts
+* import { createWorkspaceManager } from '@src/core'
+*
+* const workspaces = createWorkspaceManager()
+* const scratch = workspaces.add() // auto-activates — workspaces.active === scratch
+* scratch.write('notes.txt', 'hello')
+* ```
+*/
+function createWorkspaceManager(options) {
+	return new WorkspaceManager(options);
+}
+/**
+* Wrap a {@link WorkspaceManagerInterface} as an LLM-callable {@link ToolInterface} — it ADVERTISES
+* the `operation`-discriminated 13-op union ({@link import('./shapers.js').workspaceToolShape}) as
+* its `parameters`, and its handler PARSES the model-supplied args against that contract and
+* DISPATCHES the matched operation against the manager's ACTIVE workspace (the registry ops drive
+* the manager itself), returning the plain result (throwing a typed {@link WorkspaceError} on
+* failure).
+*
+* @remarks
+* MANAGER-DRIVEN: every edit / read op (read / list / has / search / replace / write / splice /
+* prepend / append / move / remove) targets `manager.active`, so the model edits whichever workspace
+* is active and a host can re-point it ({@link WorkspaceManagerInterface.switch}) between turns —
+* wire the agent's registry in via `createWorkspaceTool(agent.context.workspaces)`. Two REGISTRY ops
+* make the model self-sufficient: `workspaces` LISTS the registered workspaces (each
+* `{ id, files, active }`) so it can discover an id, and `switch` re-points the active workspace by
+* id (lenient — an unknown id is a no-op reporting `switched: false`, never a throw).
+*
+* NO-ACTIVE RULE (the ergonomic seam): a WRITING op (write / splice / prepend / append / move /
+* remove / replace) run when `manager.active` is `undefined` AUTO-CREATES + activates a default
+* workspace (`manager.add()`) so the model can just start writing; a pure-READ op (read / list / has
+* / search) against no active workspace returns the EMPTY result (`undefined` / `[]` / `false`),
+* never creating one and never throwing.
+*
+* A plain {@link ToolManagerInterface}-compatible tool (so `createMCPServer` / `createMCPRoutes`
+* expose it over MCP for free — nothing MCP is wired here), built as a factory + dispatch closure
+* exactly like the analogous `createWorkflowTool` in `@orkestrel/workflow` (NOT a class). The
+* contract is compiled ONCE and its JSON Schema is narrowed to the open
+* `Readonly<Record<string, unknown>>` a tool advertises via the shared
+* {@link schemaToParameters} contracts helper, never an assertion
+* (§14) — a compiled contract schema is always a record, so it passes; the `undefined` fallback only
+* satisfies the type's optionality.
+*
+* The handler conforms to the universal tool-handler contract (AGENTS §14): it `contract.parse`s the
+* args, THROWS a `TOOL` {@link WorkspaceError} when no operation arm matched (a malformed / unknown
+* operation), else `switch`es on `op.operation` and RETURNS the plain result — letting a
+* `WorkspaceError` raised by the live workspace (`MODALITY` / `PATTERN` / `RANGE`) PROPAGATE
+* unCAUGHT. The {@link import('./tools/ToolManager.js').ToolManager} performs the ONE
+* canonical wrap (`{ id, name, value }` on a return; `{ id, name, error }` on a throw, ISOLATED so
+* nothing escapes the run), so the outcome appears EXACTLY ONCE over BOTH the agent loop and MCP (a
+* throw → MCP `isError: true`). There is no `{ ok, output, duration }` envelope. The range edit is
+* the FLAT `'splice'` op: its four flat caret integers are reassembled into a {@link import('./types.js').Range}
+* by {@link rangeOf} and fed to the workspace's ranged `write`.
+*
+* @param manager - The workspace registry the tool reads + edits (its ACTIVE workspace; closed over by the handler)
+* @param options - Optional advertised `name` / `description` overrides (see {@link WorkspaceToolOptions})
+* @returns A {@link ToolInterface} (named {@link import('./constants.js').WORKSPACE_TOOL_NAME} by
+*   default) whose `parameters` advertise the `operation`-discriminated union schema
+*
+* @example
+* ```ts
+* import { createWorkspaceManager, createWorkspaceTool, createToolManager } from '@src/core'
+*
+* const manager = createWorkspaceManager()
+* const tool = createWorkspaceTool(manager) // edits the manager's ACTIVE workspace
+* const tools = createToolManager()
+* tools.add(tool) // a model can now read + edit the active workspace by calling `workspace`
+* ```
+*/
+function createWorkspaceTool(manager, options) {
+	const contract = createContract(workspaceToolShape);
+	const parameters = schemaToParameters(contract.schema);
+	return createTool({
+		name: options?.name ?? "workspace",
+		description: options?.description ?? WORKSPACE_TOOL_DESCRIPTION,
+		parameters,
+		execute: (args) => {
+			const op = contract.parse(args);
+			if (op === void 0) throw new WorkspaceError("TOOL", `unknown or malformed operation`, { args });
+			if (op.operation === "workspaces") {
+				const activeId = manager.active?.id;
+				return manager.workspaces().map((workspace) => ({
+					id: workspace.id,
+					files: workspace.count,
+					active: workspace.id === activeId
+				}));
+			}
+			if (op.operation === "switch") {
+				const switched = manager.switch(op.id);
+				return switched === void 0 ? {
+					id: op.id,
+					switched: false
+				} : {
+					id: switched.id,
+					switched: true,
+					files: switched.count
+				};
+			}
+			const active = manager.active;
+			switch (op.operation) {
+				case "read": return active?.read(op.path);
+				case "list": return (active?.files() ?? []).map((file) => ({
+					path: file.path,
+					state: file.state,
+					size: file.size,
+					lines: file.lines,
+					kind: isText(file.content) ? "text" : "binary"
+				}));
+				case "has": return active?.has(op.path) ?? false;
+				case "search": return active?.search(op.query, {
+					regex: op.regex,
+					exact: op.exact,
+					limit: op.limit
+				}) ?? [];
+				case "replace": return (active ?? manager.add()).replace(op.query, op.replacement, {
+					regex: op.regex,
+					exact: op.exact,
+					limit: op.limit
+				});
+				case "write": {
+					const workspace = active ?? manager.add();
+					workspace.write(op.path, op.content);
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "splice": {
+					const workspace = active ?? manager.add();
+					workspace.write(op.path, op.content, rangeOf(op.fromLine, op.fromColumn, op.toLine, op.toColumn));
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "prepend": {
+					const workspace = active ?? manager.add();
+					workspace.prepend(op.path, op.content);
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "append": {
+					const workspace = active ?? manager.add();
+					workspace.append(op.path, op.content);
+					return {
+						path: op.path,
+						state: workspace.file(op.path)?.state
+					};
+				}
+				case "move": {
+					const workspace = active ?? manager.add();
+					return {
+						from: op.from,
+						to: op.to,
+						moved: workspace.move(op.from, op.to)
+					};
+				}
+				case "remove": {
+					const workspace = active ?? manager.add();
+					return {
+						path: op.path,
+						removed: workspace.remove(op.path)
+					};
+				}
+			}
+		}
+	});
+}
+//#endregion
+export { Agent, AgentContext, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, DatabaseWorkspaceStore, EXTENSION_TO_LANGUAGE, Instruction, InstructionManager, MemoryConversationStore, MemoryWorkspaceStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, Tool, ToolManager, WORKSPACE_SECTION_HEADER, WORKSPACE_TOOL_DESCRIPTION, WORKSPACE_TOOL_EXAMPLE, WORKSPACE_TOOL_NAME, Workspace, WorkspaceError, WorkspaceManager, buildToolResult, clampPosition, clampRange, computeSize, countLines, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createBinaryContent, createConversation, createConversationManager, createDatabaseConversationStore, createDatabaseWorkspaceStore, createFile, createInstruction, createInstructionManager, createMemoryConversationStore, createMemoryWorkspaceStore, createScope, createScopeManager, createTextContent, createThinkSplitter, createTool, createToolManager, createWorkspace, createWorkspaceManager, createWorkspaceTool, decodedSize, escapeRegExp, estimateMessages, estimateTokens, fencedFile, filterAllowList, inferLanguage, isAgentJobError, isBinary, isConversationError, isConversationSnapshot, isFile, isImage, isMessage, isProviderAbortError, isSection, isText, isToolCall, isValidRange, isWorkspaceError, isWorkspaceSnapshot, offsetAt, rangeOf, settleAgentJob, sliceRange, spliceRange, workspaceToolShape };
+
+//# sourceMappingURL=index.js.map