@orkestrel/agent 0.0.10 → 0.0.12

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

@@ -11,6 +11,12 @@ import { RunnerInterface } from '@orkestrel/workflow';
 import { SchedulerInterface } from '@orkestrel/workflow';
 import { TableInterface } from '@orkestrel/database';
 import { TokenUsage } from '@orkestrel/budget';
+import { ToolCall } from '@orkestrel/tool';
+import { ToolDefinition } from '@orkestrel/tool';
+import { ToolInterface } from '@orkestrel/tool';
+import { ToolManagerInterface } from '@orkestrel/tool';
+import { ToolResult } from '@orkestrel/tool';
+import { WorkspaceManagerInterface } from '@orkestrel/workspace';
 
 /**
  * The agent loop — composes a {@link ProviderInterface}, an {@link AgentContext}, and
@@ -100,15 +106,17 @@ export declare type AgentChunk = {
  * 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}.
+ * the {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
+ * {@link AgentContextInterface.apply}.
  *
  * @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).
+ *   `undefined` (the default) ⇒ no filtering; change it through `apply(scope)`. The structural
+ *   `workspaces` / `conversations` registries are fixed at construction; switch their active
+ *   members through their own `switch(id)` methods.
  * - **The message source — the conversation registry's ACTIVE conversation.** `conversations` is a
  *   {@link ConversationManagerInterface}; the context ENSURES it always has an active conversation
  *   (at construction it `add`s a default when the manager has none), so the DYNAMIC `messages`
@@ -167,13 +175,11 @@ export declare class AgentContext implements AgentContextInterface {
     get system(): string | undefined;
     get instructions(): InstructionManagerInterface;
     get workspaces(): WorkspaceManagerInterface;
-    set workspaces(value: WorkspaceManagerInterface);
     get messages(): MessageManagerInterface;
     get conversations(): ConversationManagerInterface;
-    set conversations(value: ConversationManagerInterface);
     get tools(): ToolManagerInterface;
     get scope(): ScopeInterface | undefined;
-    set scope(value: ScopeInterface | undefined);
+    apply(scope: ScopeInterface | undefined): void;
     build(format?: ContextFormatInterface): readonly MessageInterface[];
 }
 
@@ -182,8 +188,8 @@ export declare class AgentContext implements AgentContextInterface {
  * the conversation, applying the active scope per category.
  *
  * @remarks
- * The richer context — `system` (the optional system prompt), the context managers
- * (`instructions` / `tools` / `workspaces` / `conversations`), `messages` (the active
+ * The richer context — `system` (the optional system prompt), the prompt context managers
+ * (`instructions` / `workspaces` / `conversations`), `messages` (the active
  * conversation's live tail, satisfying {@link MessageManagerInterface}), and the current `scope`
  * (the active {@link ScopeInterface} filter, or `undefined` for no filtering). `build()` folds the
  * scoped instructions into ONE leading `system` message (under the manager's `description`,
@@ -214,8 +220,8 @@ export declare interface AgentContextInterface {
      * construction). It IS the active {@link ConversationInterface} itself (which satisfies
      * {@link MessageManagerInterface} structurally), so appends through `messages` route to the
      * active conversation's tail and `build()` folds its `view()`. Computed dynamically (it follows
-     * a `conversations.switch(id)` or a `conversations` swap), the SAME reference the active
-     * conversation exposes — no duplication.
+     * `conversations.switch(id)`), the SAME reference the active conversation exposes — no
+     * duplication.
      */
     readonly messages: MessageManagerInterface;
     /**
@@ -225,12 +231,28 @@ export declare interface AgentContextInterface {
      * `messages` is always defined. Switch the active conversation through
      * `conversations.switch(id)` — so one agent can serve MANY conversations (set the active one per
      * request). Switch BETWEEN runs, not during one; for CONCURRENT threads use separate agents (see
-     * clause 25).
+     * clause 23).
      */
     readonly conversations: ConversationManagerInterface;
+    /**
+     * The loop's tool registry for provider advertising and call dispatch. Tools are structural
+     * loop machinery and never render into `build()`'s prompt.
+     */
     readonly tools: ToolManagerInterface;
     /** The active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
     readonly scope: ScopeInterface | undefined;
+    /**
+     * Apply the active per-turn scope filter. Passing `undefined` removes filtering.
+     *
+     * @param scope - The scope to apply, or `undefined` to remove the active filter
+     *
+     * @example
+     * ```ts
+     * context.apply(scope)
+     * context.apply(undefined)
+     * ```
+     */
+    apply(scope: ScopeInterface | undefined): void;
     /**
      * The provider input for the next turn: a leading `system` message folding the prompt
      * + the scoped instructions + the ACTIVE workspace's scoped-in TEXT files (rendered as
@@ -240,12 +262,13 @@ export declare interface AgentContextInterface {
      *
      * @remarks
      * **The active workspace (rendered by carrier) — the SOLE document/image context.** When
-     * `workspaces.active` is set, its {@link WorkspaceInterface.files} are filtered by
+     * `workspaces.active` is set, its
+     * {@link import('@orkestrel/workspace').WorkspaceInterface.files} are filtered by
      * `scope.files` (a three-way allow-list; `undefined` ⇒ all active files), then split by
-     * carrier: TEXT files ({@link import('./helpers.js').isText}) render into a dedicated
+     * carrier: TEXT files ({@link import('@orkestrel/workspace').isText}) render into a dedicated
      * `## Workspace` section in the system block — each a fenced
      * `` File: <path>\n```<language>\n<text>\n``` `` block — placed just after the instructions
-     * section; IMAGE files ({@link import('./helpers.js').isImage}) have their base64 `data`
+     * section; binary files whose MIME starts with `image/` have their base64 `data`
      * attached to the LAST user message (a vision provider reads images off a user turn).
      * ACTIVE-ONLY — never the other registered workspaces; with NO active workspace nothing is
      * rendered for workspaces.
@@ -291,21 +314,25 @@ export declare interface AgentContextInterface {
  * Options for `createAgentContext` — the richer context's configuration.
  *
  * @remarks
- * `system` is the optional system prompt prepended to the turn's input. `tools` /
- * `instructions` / `workspaces` are optional pre-built managers to reuse (bring your own
- * registry); when one is omitted, the context creates a fresh empty one. `scope` is the
+ * `system` is the optional system prompt prepended to the turn's input. `instructions` /
+ * `workspaces` are optional pre-built context managers to reuse (bring your own registry);
+ * when one is omitted, the context creates a fresh empty one. `tools` supplies the loop's
+ * call-dispatch and provider-advertising registry; it never renders into the prompt. `scope` is the
  * initial active filter applied at `build()` time (and at the loop's tool-advertise step); it
- * defaults to `undefined` — no filtering — and is mutable through the context's `scope` setter
- * afterwards. `conversations` is the {@link ConversationManagerInterface} the context's message
- * source flows from: `messages` IS the manager's ACTIVE conversation's live tail and `build()`
- * folds that conversation's `view()` (section summaries + live). When omitted, a fresh
+ * defaults to `undefined` — no filtering — and can be changed through the context's `apply`
+ * method afterwards. `conversations` is the structural {@link ConversationManagerInterface} the
+ * context's message source flows from: `messages` IS the manager's ACTIVE conversation's live tail
+ * and `build()` folds that conversation's `view()` (section summaries + live). When omitted, a fresh
  * {@link ConversationManagerInterface} is created and a default conversation is added (so
  * `messages` is ALWAYS defined). All default to a context with no system prompt, empty registries,
  * no scope, and a fresh conversation registry holding one default conversation.
  */
 export declare interface AgentContextOptions {
     readonly system?: string;
-    /** A pre-built tool registry to reuse; an empty one is created when omitted. */
+    /**
+     * The loop's pre-built tool registry for provider advertising and call dispatch; an empty one is
+     * created when omitted. Tools never render into `build()`'s prompt.
+     */
     readonly tools?: ToolManagerInterface;
     /** A pre-built instruction registry to reuse; an empty one is created when omitted. */
     readonly instructions?: InstructionManagerInterface;
@@ -313,8 +340,8 @@ export declare interface AgentContextOptions {
      * A pre-built {@link WorkspaceManagerInterface} to reuse; a fresh empty one is created when
      * omitted (so `context.workspaces` is ALWAYS present). `build()` renders the ACTIVE workspace's
      * files by carrier — text files into the system block (fenced), image files attached to the last
-     * user message — and is mutable through the context's `workspaces` setter afterwards. The active
-     * workspace is the SOLE document/image context.
+     * user message. The registry is structural; change its active workspace through
+     * `workspaces.switch(id)`. The active workspace is the SOLE document/image context.
      */
     readonly workspaces?: WorkspaceManagerInterface;
     /** The initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
@@ -326,9 +353,8 @@ export declare interface AgentContextOptions {
      * conversation's LIVE tail — is ALWAYS defined. `build()` folds the active conversation's
      * `view()` (the per-section summaries + the live tail) as its AUTHORITATIVE message inclusion —
      * the scope does NOT filter the conversation (it owns inclusion via compaction; scope filters
-     * only instructions / tools / workspace files). A SETTABLE mutable
-     * property afterwards (the context's `conversations` setter — swap the whole registry between
-     * runs), and the active conversation is switchable through the manager's `switch(id)`.
+     * only instructions / tools / workspace files). The registry is structural; change its active
+     * conversation through the manager's `switch(id)`.
      */
     readonly conversations?: ConversationManagerInterface;
 }
@@ -932,8 +958,8 @@ export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResu
  *   (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`
+ *   every {@link import('@orkestrel/tool').ToolCall} the model emits; a denied call is fed
+ *   back to the model as a denial {@link import('@orkestrel/tool').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
@@ -1038,37 +1064,6 @@ export declare interface AuthorityRule {
     readonly reason?: string;
 }
 
-/**
- * The binary MIME types a {@link FileContent} binary arm carries — the labels for a
- * base64-encoded payload.
- *
- * @remarks
- * Initialized to the four image MIMEs a vision-capable provider accepts; the union is OPEN
- * by design — a future binary MIME (e.g. `'application/pdf'`) slots in purely additively (a
- * new member), with nothing above it changed. {@link import('./helpers.js').isImage}
- * narrows a binary arm to an image by the `image/` prefix, so an image is just a binary with
- * an image MIME.
- */
-export declare type BinaryMIME = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
-
-/**
- * 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}' }] }
- * ```
- */
-export declare function buildToolResult(result: ToolResult): ToolCallResult;
-
 /**
  * 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
@@ -1089,47 +1084,6 @@ export declare class Channel<T> {
     drain(): AsyncGenerator<T, void>;
 }
 
-/**
- * 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')
- * ```
- */
-export declare function clampPosition(text: string, position: Position): Position;
-
-/**
- * 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 } }
- * ```
- */
-export declare function clampRange(text: string, range: Range): Range;
-
 /**
  * The PER-RUN auto-compaction state threaded through an {@link AgentInterface}'s loop —
  * a tiny immutable value replaced within a holder created fresh per run (so no state leaks across runs or a
@@ -1165,28 +1119,6 @@ export declare interface CompactOptions {
     readonly sections?: number;
 }
 
-/**
- * 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
- * ```
- */
-export declare function computeSize(content: FileContent): number;
-
 /**
  * A provider's OPTIONAL context-framing default, keyed by section kind — the framing a
  * model prefers (e.g. XML tags vs. Markdown headers), declared by a
@@ -1397,7 +1329,8 @@ export declare type ConversationEventMap = {
  * (initial {@link ConversationEventMap} listeners). `snapshot` is
  * the construction-time hydration seam — a {@link ConversationSnapshot} whose `id` / `summary` /
  * `sections` / live tail are RESTORED into the new conversation (the live `summarize` / `keep` /
- * `on` re-supplied alongside it), the conversation analogue of {@link WorkspaceInput.seed} that a
+ * `on` re-supplied alongside it), the conversation analogue of
+ * {@link import('@orkestrel/workspace').WorkspaceOptions}'s `seed` that a
  * {@link ConversationManagerInterface.open} reads a stored snapshot back through; hydration is
  * silent (no events). When both `snapshot.id` and `id` are given, `snapshot.id` wins (the snapshot
  * IS the conversation's identity).
@@ -1411,7 +1344,7 @@ export declare interface ConversationInput {
     /** Overrides the manager's default `sections` cap for this conversation. */
     readonly sections?: number;
     readonly on?: EmitterHooks<ConversationEventMap>;
-    /** A {@link ConversationSnapshot} to hydrate FROM (its `id` / `summary` / `sections` / live tail restored); the analogue of `WorkspaceInput.seed`. */
+    /** A {@link ConversationSnapshot} to hydrate from, analogous to the workspace package's seed input. */
     readonly snapshot?: ConversationSnapshot;
 }
 
@@ -1587,8 +1520,9 @@ export declare interface ConversationInterface {
      *
      * @remarks
      * The container serializes ITSELF (`{ id, summary, sections, messages: this.messages() }`) — the
-     * {@link ConversationStoreInterface} persistence seam's payload, the EXACT analogue of
-     * {@link WorkspaceInterface.snapshot}. The summarizer / `keep` are NOT serialized — they are live
+     * {@link ConversationStoreInterface} persistence seam's payload, the exact analogue of
+     * {@link import('@orkestrel/workspace').WorkspaceInterface}'s `snapshot`. The summarizer /
+     * `keep` are NOT serialized — they are live
      * CONFIG re-supplied on hydrate (a `ConversationSummarizer` is a function, not data). The snapshot
      * is the durable analogue of the constructor `seed`: a {@link ConversationManagerInterface}
      * HYDRATES a conversation from it through that seam (see {@link ConversationManagerInterface.open}).
@@ -1604,7 +1538,7 @@ export declare interface ConversationInterface {
  * 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
+ * {@link import('@orkestrel/workspace').WorkspaceManager}); the observability lives
  * on each {@link Conversation}.
  *
  * @remarks
@@ -1654,7 +1588,7 @@ export declare class ConversationManager implements ConversationManagerInterface
  * A registry of {@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
  * {@link AgentContextInterface} renders. Event-free (a registry, like
- * {@link WorkspaceManagerInterface}); the observability lives on each
+ * {@link import('@orkestrel/workspace').WorkspaceManagerInterface}); the observability lives on each
  * {@link ConversationInterface}.
  *
  * @remarks
@@ -1677,8 +1611,8 @@ export declare class ConversationManager implements ConversationManagerInterface
  *   miss (rebuilding it through the constructor `seed` from the snapshot, flowing the manager's
  *   default `summarize` / `keep` in) and `save(id)` PERSISTS a registered conversation's
  *   {@link ConversationInterface.snapshot}. Both are LENIENT without a store — `open` resolves only
- *   registered ids, `save` is a no-op (`false`) — consistent with the lenient `switch`. The EXACT
- *   analogue of {@link WorkspaceManagerInterface.open} / {@link WorkspaceManagerInterface.save}.
+ *   registered ids, `save` is a no-op (`false`) — consistent with the lenient `switch`. It mirrors
+ *   the workspace package manager's `open` / `save` seam.
  * - **Event-free.** A purely registry store — no Emitter, no events (each conversation owns
  *   its own).
  */
@@ -1749,8 +1683,8 @@ export declare interface ConversationManagerOptions {
      * {@link ConversationManagerInterface.open} / {@link ConversationManagerInterface.save} — a memory
      * / JSON / SQLite / IndexedDB store a conversation is HYDRATED from (`open` a registry-miss) and
      * PERSISTED to (`save`). Omitted ⇒ the manager is registry-only: `open` resolves only what is
-     * already registered, and `save` is a no-op (`false`). The EXACT analogue of
-     * {@link WorkspaceManagerOptions.store}.
+     * already registered, and `save` is a no-op (`false`). The exact analogue of
+     * {@link import('@orkestrel/workspace').WorkspaceManagerOptions}'s `store`.
      */
     readonly store?: ConversationStoreInterface;
 }
@@ -1816,7 +1750,8 @@ export declare interface ConversationReferenceOptions {
 /**
  * A JSON-serializable snapshot of a conversation's state — its `id`, the rollup `summary`, the
  * compacted `sections`, and the live tail `messages` — the durable payload the
- * {@link ConversationStoreInterface} persists. The EXACT analogue of {@link WorkspaceSnapshot}.
+ * {@link ConversationStoreInterface} persists. The exact analogue of
+ * {@link import('@orkestrel/workspace').WorkspaceSnapshot}.
  *
  * @remarks
  * Pure JSON DATA (no class instances, no functions): each {@link SectionInterface} and
@@ -1845,12 +1780,13 @@ export declare interface ConversationSnapshot {
  * One row of the table a
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
  * persists — a conversation `id` plus its {@link ConversationSnapshot} held as ONE OPAQUE JSON
- * column. The EXACT analogue of {@link WorkspaceSnapshotRow}.
+ * column. The exact analogue of {@link import('@orkestrel/workspace').WorkspaceSnapshotRow}.
  *
  * @remarks
  * The Database twin of {@link ConversationStoreInterface} stores the snapshot whole (the `snapshot`
- * column is a `rawShape`, an opaque JSON blob — exactly as {@link WorkspaceSnapshotRow} stores a
- * workspace snapshot), so the row type stays FLAT and the sections/messages snapshot shape never
+ * column is a `rawShape`, an opaque JSON blob — exactly as
+ * {@link import('@orkestrel/workspace').WorkspaceSnapshotRow} stores a workspace snapshot), so the
+ * row type stays FLAT and the sections/messages snapshot shape never
  * forces the contract to `Infer` it. The column therefore reads back as the broad `unknown`; the
  * store narrows it to a {@link ConversationSnapshot} on `get`
  * ({@link import('./helpers.js').isConversationSnapshot}, the AGENTS §14 boundary narrow). `id`
@@ -1865,8 +1801,8 @@ export declare interface ConversationSnapshotRow {
 
 /**
  * The durable persistence seam for a {@link ConversationSnapshot} — three async primitives
- * (`get` / `set` / `delete`) keyed by a conversation id, the EXACT analogue of
- * {@link WorkspaceStoreInterface}.
+ * (`get` / `set` / `delete`) keyed by a conversation id, the exact analogue of
+ * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}.
  *
  * @remarks
  * The store persists the {@link ConversationSnapshot} — the self-contained, pure-JSON conversation
@@ -1882,7 +1818,9 @@ export declare interface ConversationSnapshotRow {
  *
  * Every primitive is async (a `Promise`), so a durable backend (a database round-trip) fits the
  * same shape as the memory one. The snapshot carries its OWN id, so `set` takes no separate id
- * param (mirroring {@link WorkspaceStoreInterface.set}). UNLIKE a session store there is NO idle-TTL
+ * param (mirroring
+ * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`). UNLIKE a session store
+ * there is NO idle-TTL
  * / eviction — a persisted conversation lives until an explicit `delete`. It is concrete over
  * {@link ConversationSnapshot} — no generic parameter (AGENTS §21 minimal-interface), since the
  * snapshot is the ONE payload a conversation store persists.
@@ -1897,7 +1835,7 @@ export declare interface ConversationStoreInterface {
     get(id: string): Promise<ConversationSnapshot | undefined>;
     /**
      * Insert or replace a snapshot under its own `snapshot.id` (no separate id param —
-     * mirroring {@link WorkspaceStoreInterface.set}).
+     * mirroring {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`).
      *
      * @param snapshot - The snapshot to store (keyed by its `id`)
      */
@@ -1928,28 +1866,6 @@ export declare interface ConversationStoreInterface {
  */
 export declare type ConversationSummarizer = (messages: readonly MessageInterface[]) => Promise<string>;
 
-/**
- * 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
- * ```
- */
-export declare function countLines(content: FileContent): number;
-
 /**
  * Create an agent loop — an {@link AgentInterface} composing a
  * {@link ProviderInterface}, its {@link AgentContextInterface}, and a tool registry
@@ -2001,8 +1917,8 @@ export declare function createAgent(provider: ProviderInterface, options?: Agent
  * @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
+ * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, changeable afterwards
+ * via `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
  * instructions — PLUS the ACTIVE workspace's scope-filtered text files (fenced) — into ONE leading
  * `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
@@ -2084,8 +2000,9 @@ export declare function createAgentQueue(options: AgentQueueOptions): QueueInter
  *
  * @example
  * ```ts
+ * import { createAgentRegistry } from '@src/core'
  * import type { ProviderInterface } from '@src/core'
- * import { createAgentRegistry, createTool } from '@src/core'
+ * import { createTool } from '@orkestrel/tool'
  *
  * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
  * const registry = createAgentRegistry({
@@ -2166,24 +2083,6 @@ export declare function createAgentRunner(options: AgentRunnerOptions): RunnerIn
  */
 export declare function createAuthority(options?: AuthorityOptions): AuthorityInterface;
 
-/**
- * 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' }
- * ```
- */
-export declare function createBinaryContent(data: string, mime: BinaryMIME): FileContent;
-
 /**
  * Create a conversation — a {@link ConversationInterface} grouping messages above a flat
  * message store it OWNS DIRECTLY, with compaction into summarized sections, a regenerated
@@ -2255,12 +2154,14 @@ export declare function createConversationManager(options?: ConversationManagerO
 /**
  * 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}.
+ * {@link createMemoryConversationStore}. The exact twin of
+ * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore}.
  *
  * @remarks
  * Builds a one-table database (`conversations`, keyed by `id`) over the supplied driver, the snapshot
  * held as ONE OPAQUE JSON COLUMN — the column map is `{ id; snapshot }` where `snapshot` is a
- * `rawShape` (a JSON blob), exactly as {@link createDatabaseWorkspaceStore} stores its snapshot. The
+ * `rawShape` (a JSON blob), exactly as
+ * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore} stores its snapshot. The
  * snapshot is already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is lossless
  * AND keeps the row type FLAT (the column reads back as `unknown`, narrowed on `get` by
  * {@link import('./helpers.js').isConversationSnapshot}). The `driver` DEFAULTS to
@@ -2285,65 +2186,6 @@ export declare function createConversationManager(options?: ConversationManagerO
  */
 export declare function createDatabaseConversationStore(driver?: DriverInterface): ConversationStoreInterface;
 
-/**
- * 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)
- * ```
- */
-export declare function createDatabaseWorkspaceStore(driver?: DriverInterface): WorkspaceStoreInterface;
-
-/**
- * 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
- * ```
- */
-export declare function createFile(input: FileInput): FileInterface;
-
 /**
  * Create an instruction — an immutable {@link InstructionInterface} (a named directive)
  * from its `name` / `content` and optional `priority`, the `id` minted at construction.
@@ -2400,11 +2242,13 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
  * 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}.
+ * {@link ConversationManagerInterface.save} seam. The exact twin of
+ * {@link import('@orkestrel/workspace').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
+ * the structural twin of {@link import('@orkestrel/workspace').createMemoryWorkspaceStore}.
+ * `get` / `set` / `delete` are async (the
  * same shape a durable backend fits); UNLIKE a session store there is NO idle-TTL / eviction — a
  * persisted conversation lives until an explicit `delete`. Its driver-pluggable twin is
  * {@link createDatabaseConversationStore} (the snapshot as one opaque JSON column over a `databases`
@@ -2428,37 +2272,6 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
  */
 export declare function createMemoryConversationStore(): ConversationStoreInterface;
 
-/**
- * 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
- * ```
- */
-export declare function createMemoryWorkspaceStore(): WorkspaceStoreInterface;
-
 /**
  * Create a named scope — an immutable {@link ScopeInterface} from its `name` and the four
  * optional per-category allow-lists, the `id` minted at construction.
@@ -2508,23 +2321,6 @@ export declare function createScope(input: ScopeInput): ScopeInterface;
  */
 export declare function createScopeManager(options?: ScopeManagerOptions): ScopeManagerInterface;
 
-/**
- * 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' }
- * ```
- */
-export declare function createTextContent(text: string, language: string): FileContent;
-
 /**
  * Create a stream-stateful `<think>` separator — a {@link ThinkSplitterInterface} that
  * splits a thinking model's in-content `<think>…</think>` reasoning spans away from
@@ -2554,122 +2350,12 @@ export declare function createTextContent(text: string, language: string): FileC
  */
 export declare function createThinkSplitter(): ThinkSplitterInterface;
 
-/**
- * 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),
- * })
- * ```
- */
-export declare function createTool(options: ToolOptions): ToolInterface;
-
-/**
- * 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 } })
- * ```
- */
-export declare function createToolManager(): ToolManagerInterface;
-
-/**
- * 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'
- * ```
- */
-export declare function createWorkspace(options?: WorkspaceOptions): WorkspaceInterface;
-
-/**
- * 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')
- * ```
- */
-export declare function createWorkspaceManager(options?: WorkspaceManagerOptions): WorkspaceManagerInterface;
-
 /**
  * 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}.
+ * {@link import('@orkestrel/workspace').DatabaseWorkspaceStore}.
  *
  * @remarks
  * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
@@ -2677,7 +2363,7 @@ export declare function createWorkspaceManager(options?: WorkspaceManagerOptions
  * 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
+ * {@link import('@orkestrel/workspace').DatabaseWorkspaceStore}. The
  * driver defaults to memory ({@link import('../../factories.js').createDatabaseConversationStore}
  * passes `createMemoryDriver()`), so it ALSO works in memory out of the box; you opt into the
  * durable plumbing by passing a JSON / SQLite / IndexedDB driver.
@@ -2730,96 +2416,6 @@ export declare class DatabaseConversationStore implements ConversationStoreInter
     delete(id: string): Promise<void>;
 }
 
-/**
- * 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
- * ```
- */
-export declare class DatabaseWorkspaceStore implements WorkspaceStoreInterface {
-    #private;
-    /**
-     * 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: TableInterface<WorkspaceSnapshotRow>);
-    /** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `WorkspaceSnapshot`. */
-    get(id: string): Promise<WorkspaceSnapshot | undefined>;
-    /** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
-    set(snapshot: WorkspaceSnapshot): Promise<void>;
-    /** Drop a snapshot by id; an absent id is a no-op (no throw). */
-    delete(id: string): Promise<void>;
-}
-
-/**
- * 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 '=')
- * ```
- */
-export declare function decodedSize(base64: string): number;
-
 /**
  * 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
@@ -2847,28 +2443,6 @@ export declare const DEFAULT_AUTHORITY_ZONE = "default";
  */
 export declare const DEFAULT_CONVERSATION_KEEP = 0;
 
-/**
- * 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
- * ```
- */
-export declare function escapeRegExp(value: string): string;
-
 /**
  * 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)
@@ -2923,13 +2497,6 @@ export declare function estimateMessages(messages: readonly MessageInterface[]):
  */
 export declare function estimateTokens(text: string): number;
 
-/**
- * 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'`.
- */
-export declare const EXTENSION_TO_LANGUAGE: Readonly<Record<string, string>>;
-
 /**
  * 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
@@ -2940,7 +2507,7 @@ export declare const EXTENSION_TO_LANGUAGE: Readonly<Record<string, string>>;
  * 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).
+ * {@link import('@orkestrel/workspace').FileContent} text arm).
  *
  * @param path - The file path shown on the `File:` label line
  * @param language - The fenced-code language tag (e.g. `'typescript'`)
@@ -2957,74 +2524,6 @@ export declare const EXTENSION_TO_LANGUAGE: Readonly<Record<string, string>>;
  */
 export declare function fencedFile(path: string, language: string, content: string): string;
 
-/**
- * A {@link FileInterface}'s content — a TAGLESS union of a TEXT arm and a BINARY arm, narrowed
- * by the {@link import('./helpers.js').isText} / {@link import('./helpers.js').isBinary}
- * guards (AGENTS §14: an untyped arm is narrowed via a guard, never an `as`).
- *
- * @remarks
- * - The TEXT arm carries the literal `text` plus the fenced-code `language` it renders as.
- * - The BINARY arm carries the base64-encoded `data` plus the {@link BinaryMIME} that labels it.
- *
- * There is no `modality` discriminant — the arms are told apart structurally
- * (`'text' in content` vs `'data' in content`) by the guards. A binary arm whose `mime`
- * starts with `image/` IS an image ({@link import('./helpers.js').isImage}). A future
- * non-image binary (a PDF) is the same binary arm with a new {@link BinaryMIME} — additive,
- * with nothing above it changed.
- */
-export declare type FileContent = {
-    readonly text: string;
-    readonly language: string;
-} | {
-    readonly data: string;
-    readonly mime: BinaryMIME;
-};
-
-/**
- * The minimal data to author a {@link FileInterface} — `size` / `lines` are DERIVED from the
- * `content`, so a caller supplies only `path` / `content` (and an optional `state`, defaulting
- * to `'created'`).
- */
-export declare interface FileInput {
-    readonly path: string;
-    readonly content: FileContent;
-    /** The lifecycle state; defaults to `'created'` when omitted. */
-    readonly state?: FileState;
-}
-
-/**
- * An immutable file value object — a `path`-addressed {@link FileContent} carrying a
- * lifecycle {@link FileState}, with `size` / `lines` DERIVED once when built.
- *
- * @remarks
- * A PLAIN frozen record (not a class instance) produced by
- * {@link import('./factories.js').createFile} — the `path` IS its identity (there is no
- * `id`). `size` and `lines` are computed from `content` when built (so they can never drift
- * from it) and re-read for free thereafter. Never mutated — a Workspace REPLACES a file
- * rather than editing it in place. A DATA-ONLY value object — no methods, plus it
- * `structuredClone`s losslessly (every field is a plain primitive / record).
- */
-export declare interface FileInterface {
-    readonly path: string;
-    readonly content: FileContent;
-    readonly state: FileState;
-    /** Derived byte size: UTF-8 byte length (text) / decoded payload bytes (binary). */
-    readonly size: number;
-    /** Derived line count: the text line count; `0` for a binary arm. */
-    readonly lines: number;
-}
-
-/**
- * The lifecycle state of a {@link FileInterface} relative to its (future) durable backing
- * — a multi-value lifecycle union (AGENTS §10), not a boolean.
- *
- * @remarks
- * `'created'` is a brand-new file not yet persisted; `'modified'` has unsaved edits over a
- * persisted original; `'loaded'` was read from the backing and is unchanged; `'deleted'`
- * is tombstoned. A `File` authored without a `state` defaults to `'created'`.
- */
-export declare type FileState = 'created' | 'modified' | 'loaded' | 'deleted';
-
 /**
  * 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
@@ -3096,34 +2595,13 @@ export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, a
  */
 export declare const IMAGE_TOKEN_ESTIMATE = 512;
 
-/**
- * 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'
- * ```
- */
-export declare function inferLanguage(path: string): string;
-
 /**
  * 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
+ * A thin immutable value object (mirroring {@link import('@orkestrel/tool').Tool}): the
  * constructor mints a fresh `id` (`crypto.randomUUID()`), copies the input's `name` /
  * `content`, resolves `priority` to the input's value or `0`, and carries the input's
  * per-item `format` override ONLY when supplied (assigned just when present, mirroring a
@@ -3363,32 +2841,10 @@ export declare function isAgentError(value: unknown): value is AgentError;
 export declare function isAgentJobError(value: unknown): value is AgentJobError;
 
 /**
- * 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.
+ * Narrow an unknown caught value to a {@link ConversationError}.
  *
- * @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
- * ```
- */
-export declare function isBinary(content: FileContent): content is {
-    readonly data: string;
-    readonly mime: BinaryMIME;
-};
-
-/**
- * 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}
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns `true` when `value` is a {@link ConversationError}
  *
  * @example
  * ```ts
@@ -3406,7 +2862,7 @@ export declare function isConversationError(value: unknown): value is Conversati
  * 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}.
+ * {@link import('@orkestrel/workspace').isWorkspaceSnapshot}.
  *
  * @remarks
  * A total guard (it NEVER throws — adversarial input returns `false`). It checks the snapshot's
@@ -3415,7 +2871,7 @@ export declare function isConversationError(value: unknown): value is Conversati
  * {@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
+ * {@link import('@orkestrel/workspace').isWorkspaceSnapshot}. A malformed blob (a non-record, a missing / non-string `id`, a
  * non-string `summary` when present, a non-array `sections` / `messages`, or any malformed
  * element) resolves `false`, so a
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
@@ -3434,68 +2890,23 @@ export declare function isConversationError(value: unknown): value is Conversati
  */
 export declare function isConversationSnapshot(value: unknown): value is ConversationSnapshot;
 
-/**
- * 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)
- * ```
- */
-export declare function isFile(value: unknown): value is FileInterface;
-
-/**
- * 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
- * ```
- */
-export declare function isImage(content: FileContent): boolean;
-
 /**
  * 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}.
+ * read via a guard, never an `as`). The conversation analogue of
+ * {@link import('@orkestrel/workspace').isFile}.
  *
  * @remarks
  * A total guard (it NEVER throws — adversarial input returns `false`). It checks the message's
  * SHAPE: a record with a `string` `id`, a `string` `role`, a `string` `content`, and — WHEN present
- * — a `calls` array EVERY element of which is a valid {@link ToolCall} ({@link isToolCall} — the
+ * — a `calls` array EVERY element of which is a valid
+ * {@link import('@orkestrel/tool').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
+ * defensively rather than rejected against the current literal set). 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`)
@@ -3551,132 +2962,16 @@ export declare function isProviderAbortError(value: unknown): value is ProviderA
  */
 export declare function isSection(value: unknown): value is SectionInterface;
 
-/**
- * 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
- * ```
- */
-export declare function isText(content: FileContent): content is {
-    readonly text: string;
-    readonly language: string;
-};
-
-/**
- * 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)
- * ```
- */
-export declare function isToolCall(value: unknown): value is ToolCall;
-
-/**
- * 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)
- * ```
- */
-export declare function isValidRange(range: Range): boolean;
-
-/**
- * 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()
- * }
- * ```
- */
-export declare function isWorkspaceError(value: unknown): value is WorkspaceError;
-
-/**
- * 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)
- * ```
- */
-export declare function isWorkspaceSnapshot(value: unknown): value is WorkspaceSnapshot;
-
 /**
  * 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}.
+ * {@link import('@orkestrel/workspace').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,
+ * {@link import('@orkestrel/workspace').MemoryWorkspaceStore} it twins,
  * there is NO idle-TTL and NO eviction: a persisted conversation lives until an explicit `delete`. A
  * durable backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching
  * the {@link import('../ConversationManager.js').ConversationManager} or the
@@ -3712,50 +3007,6 @@ export declare class MemoryConversationStore implements ConversationStoreInterfa
     delete(id: string): Promise<void>;
 }
 
-/**
- * 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
- * ```
- */
-export declare class MemoryWorkspaceStore implements WorkspaceStoreInterface {
-    #private;
-    get(id: string): Promise<WorkspaceSnapshot | undefined>;
-    set(snapshot: WorkspaceSnapshot): Promise<void>;
-    delete(id: string): Promise<void>;
-}
-
 /**
  * The estimated per-message role/framing overhead {@link import('./helpers.js').estimateMessages}
  * adds on top of a message's content estimate — accounts for the fixed wire framing every
@@ -3833,42 +3084,6 @@ export declare interface MessageManagerInterface {
 /** The role a {@link MessageInterface} plays in a conversation turn. */
 export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 
-/**
- * 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')
- * ```
- */
-export declare function offsetAt(text: string, position: Position): number;
-
-/**
- * A 1-based caret position inside a text file — `line` and `column` both count from `1`
- * (column `1` is the first character of the line), matching an editor's gutter.
- *
- * @remarks
- * The {@link import('./workspaces/Workspace.js').Workspace} edit surface speaks 1-based
- * positions end to end ({@link Range}, {@link ReadResult}, {@link SearchMatch}). A
- * structurally invalid component (`line < 1` or `column < 1`) is rejected by a range op
- * (`RANGE`); an in-bounds-but-past-the-end one is CLAMPED to the nearest valid caret rather
- * than rejected.
- */
-export declare interface Position {
-    readonly line: number;
-    readonly column: number;
-}
-
 /**
  * Thrown by a {@link ProviderInterface}'s `stream` when its bound signal aborts
  * mid-flight — carries the {@link ProviderResult} assembled from whatever streamed
@@ -3933,7 +3148,7 @@ export declare interface ProviderInterface {
      * built-in framing, beaten by a manager-options or per-item override). Omitted ⇒ the
      * provider is framing-agnostic and the managers' built-in defaults apply unchanged.
      */
-    readonly format?: ContextFormatInterface;
+    readonly format?: ContextFormatInterface | undefined;
     /**
      * Generate one complete turn — resolves the assembled {@link ProviderResult}.
      *
@@ -4011,87 +3226,6 @@ export declare interface ProviderStreamOptions {
     readonly schema?: Readonly<Record<string, unknown>>;
 }
 
-/**
- * A half-open span of text between two {@link Position}s — `start` INCLUSIVE, `end`
- * EXCLUSIVE (the character at `end` is not part of the span).
- *
- * @remarks
- * A range whose `start` is at or before its `end` is valid; an inverted range
- * (`start` after `end`) or one with a sub-1 component is structurally invalid and a range
- * op throws `RANGE`. Each in-bounds component is clamped to the text before it is applied,
- * so a range reaching past the end of the content reads / splices up to the end.
- */
-export declare interface Range {
-    readonly start: Position;
-    readonly end: Position;
-}
-
-/**
- * Assemble a 1-based nested {@link Range} from four FLAT caret integers — the bridge a
- * workspace-editing tool (see `@orkestrel/tool`) uses from its small-model FLAT surface back to the
- * nested {@link Range} the {@link import('./workspaces/Workspace.js').Workspace} edit surface
- * speaks. Published as a public helper for that consumer.
- *
- * @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 } }
- * ```
- */
-export declare function rangeOf(fromLine: number, fromColumn: number, toLine: number, toColumn: number): Range;
-
-/**
- * The outcome of a ranged {@link WorkspaceInterface.read} — the sliced `content` plus the
- * `range` actually applied after clamping (so a caller learns the real span it got).
- *
- * @remarks
- * `range` is the input {@link Range} CLAMPED to the file's bounds — when the requested
- * span reached past the end of the text, `range` reflects the trimmed span that was read,
- * never the original out-of-bounds request.
- */
-export declare interface ReadResult {
-    readonly content: string;
-    /** The actual (clamped) range applied to produce `content`. */
-    readonly range: Range;
-}
-
-/**
- * Options for {@link WorkspaceInterface.replace} — how the `query` matches (the same axes
- * as {@link SearchOptions}).
- *
- * @param options - The replace options
- *
- * @remarks
- * - `regex` — treat `query` as a regular expression source rather than a literal substring; defaults to `false`.
- * - `exact` — match case-sensitively; defaults to `true`.
- * - `limit` — stop after this many replacements across all files; defaults to unlimited.
- */
-export declare interface ReplaceOptions {
-    readonly regex?: boolean;
-    readonly exact?: boolean;
-    readonly limit?: number;
-}
-
-/**
- * The tally returned by {@link WorkspaceInterface.replace} — the `query` that ran, how
- * many occurrences were `replaced`, and the number of `files` changed.
- */
-export declare interface ReplaceResult {
-    readonly query: string;
-    readonly replaced: number;
-    readonly files: number;
-}
-
 /**
  * The immutable per-run outcome value an {@link AgentInterface}'s loop replaces as it runs — the
  * assembled value its `stream`'s `result` promise resolves into a settled
@@ -4208,7 +3342,7 @@ export declare interface ScopeConfiguration {
     /**
      * Allowed ACTIVE-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —
      * the filter {@link AgentContextInterface.build} applies to the active workspace's
-     * {@link WorkspaceInterface.files} before rendering them (text → the system block, image →
+     * {@link import('@orkestrel/workspace').WorkspaceInterface.files} before rendering them (text → the system block, image →
      * the last user message).
      */
     readonly files?: readonly string[];
@@ -4223,7 +3357,7 @@ export declare interface ScopeInput extends ScopeConfiguration {
 }
 
 /**
- * A named, immutable filter over a richer context's items — the four per-category
+ * A named, immutable filter over a richer context's items — the three per-category
  * allow-lists ({@link ScopeConfiguration}) plus an `id` / `name`, and a `narrow` that
  * composes a tighter child by set-INTERSECTION.
  *
@@ -4311,7 +3445,7 @@ export declare type ScopeManagerEventMap = {
  * mints + stores one (never overwrites), `scopes()` lists them in insertion order.
  *
  * @remarks
- * - **Registry.** `create(input)` mints a scope (an `id` + the four allow-lists) and
+ * - **Registry.** `create(input)` mints a scope (an `id` + the three allow-lists) and
  *   stores it; `count` is how many are stored. `scope(id)` looks one up; `scopes()` lists
  *   them in insertion order. (Keyed by minted `id`, not `name`, so two scopes may share a
  *   `name` and `create` always adds.)
@@ -4341,40 +3475,6 @@ export declare interface ScopeManagerOptions {
     readonly error?: EmitterErrorHandler;
 }
 
-/**
- * One hit from {@link WorkspaceInterface.search} — where the match was found and the line
- * that carried it.
- *
- * @remarks
- * `line` / `column` are 1-based (column `1` is the first character of the line); `length`
- * is the matched substring's length; `content` is the FULL line the match sits on (not
- * just the matched fragment), so a caller can render the hit in context.
- */
-export declare interface SearchMatch {
-    readonly path: string;
-    readonly line: number;
-    readonly column: number;
-    readonly length: number;
-    /** The full text of the line the match was found on. */
-    readonly content: string;
-}
-
-/**
- * Options for {@link WorkspaceInterface.search} — how the `query` matches.
- *
- * @param options - The search options
- *
- * @remarks
- * - `regex` — treat `query` as a regular expression source rather than a literal substring; defaults to `false`.
- * - `exact` — match case-sensitively; defaults to `true` (set `false` for a case-insensitive scan).
- * - `limit` — stop after this many matches across all files; defaults to unlimited.
- */
-export declare interface SearchOptions {
-    readonly regex?: boolean;
-    readonly exact?: boolean;
-    readonly limit?: number;
-}
-
 /**
  * A slice of folded messages digested into a summary — the unit of compaction a
  * {@link ConversationInterface} produces when it `compact`s its live tail.
@@ -4417,48 +3517,6 @@ export declare interface SectionInterface {
  */
 export declare function settleAgentJob(agent: AgentInterface, allowPartial: boolean): Promise<AgentResult>;
 
-/**
- * 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'
- * ```
- */
-export declare function sliceRange(text: string, range: Range): string;
-
-/**
- * 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'
- * ```
- */
-export declare function spliceRange(text: string, range: Range, replacement: string): string;
-
 /**
  * A live event stream paired with the eventual settled result and a cancel — the
  * generic pull/streaming handle a long-running operation hands back.
@@ -4588,299 +3646,6 @@ export declare interface ThinkSplitterInterface {
     flush(): string;
 }
 
-/**
- * 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),
- * })
- * ```
- */
-export declare class Tool implements ToolInterface {
-    #private;
-    readonly name: string;
-    readonly description?: string;
-    readonly summary?: string;
-    readonly parameters?: Readonly<Record<string, unknown>>;
-    constructor(options: ToolOptions);
-    execute(args: Readonly<Record<string, unknown>>): Promise<unknown> | unknown;
-}
-
-/**
- * A tool call the model emitted — the tool `name` and its parsed `arguments`.
- *
- * @remarks
- * `id` correlates the call with its later {@link ToolResult}; when the wire omits an
- * id the provider mints one (a random UUID) so every call is addressable. `arguments`
- * is always a record — the provider narrows the wire value (an object, or a JSON
- * string it parses) to one, defaulting to `{}` when neither.
- */
-export declare interface ToolCall {
-    readonly id: string;
-    readonly name: string;
-    readonly arguments: Readonly<Record<string, unknown>>;
-}
-
-/**
- * The MCP `CallToolResult` shape a {@link ToolResult} maps to via {@link buildToolResult} —
- * `content` blocks plus an `isError` flag set ONLY on failure (never `false`).
- */
-export declare interface ToolCallResult {
-    readonly content: readonly ToolResultContent[];
-    readonly isError?: true;
-}
-
-/**
- * A tool the model may call — its name, an optional description, and an optional
- * JSON-Schema `parameters` object describing its arguments.
- *
- * @remarks
- * Passed to a {@link ProviderInterface}'s `generate` / `stream`; the provider maps
- * each into the wire's function-tool shape. `parameters` is an open JSON-Schema
- * record (the provider forwards it verbatim).
- */
-export declare interface ToolDefinition {
-    readonly name: string;
-    readonly description?: string;
-    readonly parameters?: Readonly<Record<string, unknown>>;
-}
-
-/**
- * A registered tool: its {@link ToolDefinition} (the schema the model sees) plus the
- * handler that runs a call.
- *
- * @remarks
- * The definition fields (`name` / `description` / `parameters`) are what a
- * {@link ProviderInterface} advertises to the model; `execute` is the local handler a
- * {@link ToolManagerInterface} invokes when the model calls the tool. The handler's
- * `args` is the model-supplied `unknown` JSON object — narrow it inside the handler
- * (§14), never assert; the manager isolates a throw into a {@link ToolResult} `error`.
- */
-export declare interface ToolInterface extends ToolDefinition {
-    /**
-     * A one-or-two-sentence concise description advertised to the model IN PLACE of the
-     * full `description` (which stays on the tool for on-demand retrieval, e.g. a
-     * describe tool); absent ⇒ the full `description` is advertised exactly as today.
-     */
-    readonly summary?: string;
-    /**
-     * Run the tool. `args` is the model-supplied `unknown` JSON object — narrow it
-     * inside (§14); the manager isolates a throw into a {@link ToolResult} `error`.
-     *
-     * @param args - The model-supplied arguments record (an open `unknown` object)
-     * @returns The tool's result (sync or async) — folded into a `ToolResult.value`
-     */
-    execute(args: Readonly<Record<string, unknown>>): Promise<unknown> | unknown;
-}
-
-/**
- * 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, with
- *   `tool.summary ?? tool.description` advertised as `description` (a lean `summary`
- *   stands in for the full text when set).
- * - **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
- * ```
- */
-export declare class ToolManager implements ToolManagerInterface {
-    #private;
-    get count(): number;
-    add(tool: ToolInterface): void;
-    add(tools: readonly ToolInterface[]): void;
-    tool(name: string): ToolInterface | undefined;
-    tools(): readonly ToolInterface[];
-    definitions(): readonly ToolDefinition[];
-    execute(call: ToolCall): Promise<ToolResult>;
-    execute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
-    remove(name: string): boolean;
-    remove(names: readonly string[]): boolean;
-    clear(): void;
-}
-
-/**
- * A registry of tools — resolves names, lists definitions for the provider, and
- * executes calls with per-call error isolation.
- *
- * @remarks
- * - **Registry.** `add` registers one tool or a batch (§9.2), keyed by `tool.name`
- *   (a re-`add` of the same name overwrites — last write wins); `count` is the number
- *   registered. `tool(name)` looks one up; `tools()` lists them in insertion order;
- *   `definitions()` strips each to a plain {@link ToolDefinition} for the provider,
- *   advertising `tool.summary ?? tool.description` in the definition's `description`
- *   field — a lean `summary` stands in for the full `description` when set.
- * - **Per-call error isolation.** `execute` resolves a {@link ToolCall}'s tool by name
- *   and runs it, ALWAYS resolving a {@link ToolResult}: a success carries `value`, a
- *   handler throw is caught into `error`, and an unknown name becomes a not-found
- *   `error`. A tool throw NEVER escapes — it becomes a result the model can react to.
- * - **Batch never fails as a whole.** The array `execute` runs every call (via
- *   `Promise.all`) and resolves results correlated by `id` in order — one bad call
- *   (throw or not-found) does not fail the batch.
- * - **Event-free.** A purely functional registry — no Emitter, no events.
- */
-export declare interface ToolManagerInterface {
-    readonly count: number;
-    add(tool: ToolInterface): void;
-    add(tools: readonly ToolInterface[]): void;
-    tool(name: string): ToolInterface | undefined;
-    tools(): readonly ToolInterface[];
-    definitions(): readonly ToolDefinition[];
-    execute(call: ToolCall): Promise<ToolResult>;
-    execute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
-    remove(name: string): boolean;
-    remove(names: readonly string[]): boolean;
-    clear(): void;
-}
-
-/**
- * Options for `createTool` — the schema the model sees (`name` / `description` /
- * `parameters`) plus the `execute` handler that runs a call.
- *
- * @remarks
- * `name` is required (it keys the tool in a {@link ToolManagerInterface} and is what
- * the model calls); `description` and `parameters` are the optional JSON-Schema the
- * provider advertises (forwarded verbatim). `summary`, when set, is a lean
- * one-or-two-sentence advertisement used IN PLACE of `description` in a
- * {@link ToolManagerInterface.definitions} listing — `description` stays available on
- * the tool for on-demand retrieval. `execute` receives the model-supplied arguments
- * record and returns the tool's result (sync or async).
- */
-export declare interface ToolOptions {
-    readonly name: string;
-    readonly description?: string;
-    readonly summary?: string;
-    readonly parameters?: Readonly<Record<string, unknown>>;
-    readonly execute: (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
-}
-
-/**
- * The outcome of executing a {@link ToolCall} — keyed back to the call by `id` and
- * `name`, carrying either a `value` (the result) or an `error` string (the failure).
- */
-export declare interface ToolResult {
-    readonly id: string;
-    readonly name: string;
-    readonly value?: unknown;
-    readonly error?: string;
-}
-
-/**
- * One block of an MCP-shaped tool call response — plain text, the only content kind
- * {@link buildToolResult} emits.
- */
-export declare interface ToolResultContent {
-    readonly type: 'text';
-    readonly text: string;
-}
-
-/**
- * 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'
- * ```
- */
-export declare class Workspace implements WorkspaceInterface {
-    #private;
-    constructor(options?: WorkspaceOptions, seed?: Iterable<readonly [string, FileInterface]>);
-    get id(): string;
-    get emitter(): EmitterInterface<WorkspaceEventMap>;
-    get count(): number;
-    file(path: string): FileInterface | undefined;
-    files(): readonly FileInterface[];
-    read(path: string): string | undefined;
-    read(path: string, range: Range): ReadResult | undefined;
-    read(paths: readonly string[]): Readonly<Record<string, string>>;
-    has(path: string): boolean;
-    has(paths: readonly string[]): boolean;
-    search(query: string, options?: SearchOptions): readonly SearchMatch[];
-    replace(query: string, replacement: string, options?: ReplaceOptions): ReplaceResult;
-    write(path: string, content: string): void;
-    write(path: string, content: string, range: Range): void;
-    write(files: Readonly<Record<string, string>>): void;
-    prepend(path: string, content: string): void;
-    prepend(files: Readonly<Record<string, string>>): void;
-    append(path: string, content: string): void;
-    append(files: Readonly<Record<string, string>>): void;
-    move(from: string, to: string): boolean;
-    move(mapping: Readonly<Record<string, string>>): boolean;
-    remove(): void;
-    remove(path: string): boolean;
-    remove(paths: readonly string[]): boolean;
-    clear(): void;
-    snapshot(): WorkspaceSnapshot;
-}
-
 /**
  * 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
@@ -4895,393 +3660,4 @@ export declare class Workspace implements WorkspaceInterface {
  */
 export declare const WORKSPACE_SECTION_HEADER = "## Workspace";
 
-/**
- * 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).
- */
-export declare class WorkspaceError extends Error {
-    readonly code: WorkspaceErrorCode;
-    readonly context?: Readonly<Record<string, unknown>>;
-    constructor(code: WorkspaceErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
-}
-
-/**
- * The machine-readable code a {@link import('./errors.js').WorkspaceError} carries
- * (AGENTS §12) — a `catch` branches on `error.code` instead of parsing the message.
- *
- * @remarks
- * - `MODALITY` — a text-only op (ranged read/write, `prepend`, `append`) was aimed at a binary file.
- * - `PATTERN` — a `search` / `replace` `query` was an invalid regular expression (with `regex: true`).
- * - `RANGE` — a ranged `write` got a structurally invalid {@link Range} (inverted, or a sub-1 line/column).
- * - `TOOL` — a handler-level validation fault raised by a workspace-editing tool boundary (see
- *   `@orkestrel/tool`) when the agent-supplied args were malformed / unknown. Distinct from the
- *   surface faults above (which the live workspace raises) — this is the tool boundary rejecting an
- *   un-parseable operation before any workspace call.
- */
-export declare type WorkspaceErrorCode = 'MODALITY' | 'PATTERN' | 'RANGE' | 'TOOL';
-
-/**
- * The observable events a {@link import('./workspaces/Workspace.js').Workspace} emits
- * (AGENTS §13) — each fired AFTER the corresponding mutation completes.
- *
- * @remarks
- * - `write` — a file was written / edited, carrying the resulting {@link FileInterface}.
- * - `remove` — a single file was dropped, carrying its `path`.
- * - `move` — a file was re-keyed, carrying `{ from, to }`.
- * - `clear` — the workspace was emptied (the canonical "emptied" signal, fired by both `remove()` and `clear()`).
- */
-export declare type WorkspaceEventMap = {
-    readonly write: readonly [file: FileInterface];
-    readonly remove: readonly [path: string];
-    readonly move: readonly [move: {
-        readonly from: string;
-        readonly to: string;
-    }];
-    readonly clear: readonly [];
-};
-
-/**
- * The data to author a {@link WorkspaceInterface} through a
- * {@link WorkspaceManagerInterface} — the optional `id`, the reserved `on` hooks + `error`
- * handler (§13), and an optional `seed` of initial files.
- *
- * @remarks
- * `id` is the workspace's identity (minted when omitted). `on` / `error` are the §8/§13
- * keys (initial {@link WorkspaceEventMap} listeners + the listener-error handler), flowing
- * the manager's defaults in unless overridden. `seed` is the construction-time hydration
- * seam (path → {@link FileInterface}) — the only way to seat a non-text (binary) file, and
- * what a future FileStore reads a snapshot into; seeding is silent (no `write` events).
- */
-export declare interface WorkspaceInput {
-    readonly id?: string;
-    readonly on?: EmitterHooks<WorkspaceEventMap>;
-    readonly error?: EmitterErrorHandler;
-    /** Pre-seeded initial files (path → File), placed silently at construction. */
-    readonly seed?: Iterable<readonly [string, FileInterface]>;
-}
-
-/**
- * A mutable, `path`-keyed working set of immutable {@link FileInterface}s — the in-memory
- * editing surface over the file primitive.
- *
- * @remarks
- * Files live in an insertion-ordered map keyed by `path`. Every edit REPLACES the
- * immutable {@link FileInterface} at a path with a new one (transitioning its `state` to
- * `'created'` for a fresh path or `'modified'` for an existing one) rather than mutating in
- * place. The disk/sync lifecycle (`load` / `revert` / `accept` / `purge` / `dirty`) is
- * deliberately NOT part of this surface — it is deferred to a future FileStore. Text-only
- * operations on a binary file are governed by the modality rules (a ranged read/write,
- * `prepend`, and `append` throw `MODALITY`; a plain `read` returns `undefined`; `search` /
- * `replace` skip the file). Observe mutations through the owned {@link emitter} (AGENTS §13).
- */
-export declare interface WorkspaceInterface {
-    /** The workspace's identity — its key in a {@link WorkspaceManagerInterface}; minted when not supplied. */
-    readonly id: string;
-    /** The push observation surface (AGENTS §13) — `write` / `remove` / `move` / `clear`. */
-    readonly emitter: EmitterInterface<WorkspaceEventMap>;
-    /** The number of files currently held. */
-    readonly count: number;
-    /** Look up one file by path, or `undefined` when absent. */
-    file(path: string): FileInterface | undefined;
-    /** List every file in insertion order. */
-    files(): readonly FileInterface[];
-    read(path: string): string | undefined;
-    read(path: string, range: Range): ReadResult | undefined;
-    read(paths: readonly string[]): Readonly<Record<string, string>>;
-    has(path: string): boolean;
-    has(paths: readonly string[]): boolean;
-    /** Scan every text file's lines for `query`, returning each hit in insertion order. */
-    search(query: string, options?: SearchOptions): readonly SearchMatch[];
-    /** Replace `query` with `replacement` across every text file, returning the tally. */
-    replace(query: string, replacement: string, options?: ReplaceOptions): ReplaceResult;
-    write(path: string, content: string): void;
-    write(path: string, content: string, range: Range): void;
-    write(files: Readonly<Record<string, string>>): void;
-    prepend(path: string, content: string): void;
-    prepend(files: Readonly<Record<string, string>>): void;
-    append(path: string, content: string): void;
-    append(files: Readonly<Record<string, string>>): void;
-    move(from: string, to: string): boolean;
-    move(mapping: Readonly<Record<string, string>>): boolean;
-    remove(): void;
-    remove(path: string): boolean;
-    remove(paths: readonly string[]): boolean;
-    /** Empty the workspace (emits `clear`). */
-    clear(): void;
-    /**
-     * Serialize this workspace to a plain, JSON-serializable {@link WorkspaceSnapshot} — its
-     * `id` plus a flat list of its {@link FileInterface}s (each already carries its `path`).
-     *
-     * @remarks
-     * The container serializes ITSELF (`{ id: this.id, files: this.files() }`) — the
-     * {@link WorkspaceStoreInterface} persistence seam's payload, paralleling the
-     * {@link ConversationInterface}'s own snapshot a later track adds. The snapshot is the
-     * durable analogue of the constructor `seed`: a {@link WorkspaceManagerInterface} HYDRATES a
-     * workspace from `snapshot.files` through that seam (see {@link WorkspaceManagerInterface.open}).
-     * Pure — the `File`s are already frozen plain records (so the snapshot `structuredClone`s /
-     * JSON-round-trips losslessly), and snapshotting mutates nothing.
-     *
-     * @returns The {@link WorkspaceSnapshot} (`{ id, files }`)
-     */
-    snapshot(): WorkspaceSnapshot;
-}
-
-/**
- * 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
- * ```
- */
-export declare class WorkspaceManager implements WorkspaceManagerInterface {
-    #private;
-    constructor(options?: WorkspaceManagerOptions);
-    get count(): number;
-    get active(): WorkspaceInterface | undefined;
-    workspace(id: string): WorkspaceInterface | undefined;
-    workspaces(): readonly WorkspaceInterface[];
-    add(input?: WorkspaceInput): WorkspaceInterface;
-    switch(id: string): WorkspaceInterface | undefined;
-    open(id: string): Promise<WorkspaceInterface | undefined>;
-    save(id: string): Promise<boolean>;
-    remove(ids: readonly string[]): boolean;
-    remove(id: string): boolean;
-    clear(): void;
-}
-
-/**
- * A registry of {@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. Event-free (each {@link WorkspaceInterface} owns its own `emitter`).
- *
- * @remarks
- * - **Registry.** `count` is how many are stored. `add(input?)` mints a
- *   {@link WorkspaceInterface} (its `id` from `input` or a random UUID), flowing the manager's
- *   default `on` / `error` in unless the `input` overrides them; `add` of an already-present
- *   `id` OVERWRITES it (last write wins). `workspace(id)` looks one up (`undefined` when
- *   absent); `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 later `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).
- * - **Removal.** `remove` drops one by id, or a batch (§9.2, array overload FIRST) — `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` seam).** When a {@link WorkspaceStoreInterface}
- *   is supplied (the `store` option), `open(id)` HYDRATES a workspace from the store on a registry
- *   miss (rebuilding it through the constructor `seed` from `snapshot.files`) and `save(id)`
- *   PERSISTS a registered workspace's {@link WorkspaceInterface.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).
- */
-export declare interface WorkspaceManagerInterface {
-    readonly count: number;
-    /** The active workspace — what the context renders; `undefined` until the first `add`. */
-    readonly active: WorkspaceInterface | undefined;
-    workspace(id: string): WorkspaceInterface | undefined;
-    workspaces(): readonly WorkspaceInterface[];
-    add(input?: WorkspaceInput): WorkspaceInterface;
-    switch(id: string): WorkspaceInterface | undefined;
-    /**
-     * Resolve a workspace by id, ACTIVATING it — from the registry if present, else HYDRATED from
-     * the optional {@link WorkspaceStoreInterface} (`store`).
-     *
-     * @remarks
-     * - If `id` is ALREADY registered, it is ACTIVATED (`switch`ed to) and returned — no store hit.
-     * - Else if a `store` is set, `store.get(id)` is awaited; on a HIT the snapshot is rehydrated
-     *   into a fresh {@link WorkspaceInterface} through the constructor `seed`
-     *   (`add({ id, seed: snapshot.files.map((file) => [file.path, file]) })`), which registers AND
-     *   auto-activates it (or activates it explicitly), and it is returned.
-     * - Else (no store, or a store MISS) ⇒ `undefined` (lenient — no throw).
-     *
-     * @param id - The workspace id to open
-     * @returns The activated {@link WorkspaceInterface}, or `undefined` when neither registered nor stored
-     */
-    open(id: string): Promise<WorkspaceInterface | undefined>;
-    /**
-     * Persist a REGISTERED workspace's {@link WorkspaceInterface.snapshot} to the optional
-     * {@link WorkspaceStoreInterface} (`store`).
-     *
-     * @remarks
-     * Lenient: when a `store` is set AND `id` is registered, `store.set(workspace.snapshot())` is
-     * awaited and `true` is returned; otherwise (no store, OR an unknown id) it is a NO-OP returning
-     * `false` — never a throw, consistent with the lenient `switch`.
-     *
-     * @param id - The id of the registered workspace to persist
-     * @returns `true` when the snapshot was persisted; `false` when no store / unknown id
-     */
-    save(id: string): Promise<boolean>;
-    remove(ids: readonly string[]): boolean;
-    remove(id: string): boolean;
-    clear(): void;
-}
-
-/**
- * Options for `createWorkspaceManager` — the per-workspace `on` / `error` defaults the
- * workspaces it creates inherit.
- *
- * @remarks
- * `on` / `error` are the default {@link WorkspaceEventMap} listeners + the emitter's
- * listener-error handler (§13) flowed into every workspace the manager `add`s (a per-`add`
- * {@link WorkspaceInput.on} / `.error` overrides them). Kept minimal (AGENTS §21) — a
- * registry needs no more.
- */
-export declare interface WorkspaceManagerOptions {
-    /** The default event listeners for workspaces this manager creates (a per-`add` override wins). */
-    readonly on?: EmitterHooks<WorkspaceEventMap>;
-    /** The default listener-error handler (a per-`add` override wins). */
-    readonly error?: EmitterErrorHandler;
-    /**
-     * The optional durable {@link WorkspaceStoreInterface} backing {@link WorkspaceManagerInterface.open}
-     * / {@link WorkspaceManagerInterface.save} — a memory / JSON / SQLite / IndexedDB store a workspace
-     * is HYDRATED from (`open` a registry-miss) and PERSISTED to (`save`). Omitted ⇒ the manager is
-     * registry-only: `open` resolves only what is already registered, and `save` is a no-op (`false`).
-     */
-    readonly store?: WorkspaceStoreInterface;
-}
-
-/**
- * Options for {@link import('./factories.js').createWorkspace} / the
- * {@link import('./workspaces/Workspace.js').Workspace} constructor.
- *
- * @param options - The workspace options
- *
- * @remarks
- * - `id` — the workspace's identity (its key in a {@link WorkspaceManagerInterface}); MINTED via `crypto.randomUUID()` when omitted.
- * - `on` — initial {@link WorkspaceEventMap} listeners (AGENTS §8), wired at construction.
- * - `error` — the emitter's listener-error handler (AGENTS §13); a throw from any listener is routed here instead of rethrown.
- */
-export declare interface WorkspaceOptions {
-    readonly id?: string;
-    readonly on?: EmitterHooks<WorkspaceEventMap>;
-    readonly error?: EmitterErrorHandler;
-}
-
-/**
- * A JSON-serializable snapshot of a workspace's state — its `id` plus a FLAT list of its
- * {@link FileInterface}s — the durable payload the {@link WorkspaceStoreInterface} persists.
- *
- * @remarks
- * Pure JSON DATA (no class instances, no functions): each {@link FileInterface} is already a
- * PLAIN frozen record that `structuredClone`s / JSON-round-trips losslessly, and a `File` carries
- * its OWN `path`, so a flat `files` list is enough to reconstruct the path-keyed map (no nested
- * `path → File` object needed for serialization). The snapshot the container produces from itself
- * ({@link WorkspaceInterface.snapshot}); the durable analogue of the constructor `seed`. A
- * {@link WorkspaceManagerInterface} hydrates a workspace from `snapshot.files` through the seed
- * seam (see {@link WorkspaceManagerInterface.open}). It is narrowed back from an untrusted storage
- * read by {@link import('./helpers.js').isWorkspaceSnapshot} (the AGENTS §14 boundary narrow).
- */
-export declare interface WorkspaceSnapshot {
-    readonly id: string;
-    readonly files: readonly FileInterface[];
-}
-
-/**
- * One row of the table a
- * {@link import('./workspaces/stores/DatabaseWorkspaceStore.js').DatabaseWorkspaceStore} persists
- * — a workspace `id` plus its {@link WorkspaceSnapshot} held as ONE OPAQUE JSON column.
- *
- * @remarks
- * The Database twin of {@link WorkspaceStoreInterface} stores the snapshot whole (the `snapshot`
- * column is a `rawShape`, an opaque JSON blob — exactly as the analogous
- * `WorkflowSnapshotRow` in `@orkestrel/workflow` stores a workflow snapshot), so the
- * row type stays FLAT and the `File`-list snapshot shape never forces the contract to `Infer` it.
- * The column therefore reads back as the broad `unknown`; the store narrows it to a
- * {@link WorkspaceSnapshot} on `get` ({@link import('./helpers.js').isWorkspaceSnapshot}, the
- * AGENTS §14 boundary narrow). `id` mirrors {@link WorkspaceSnapshot.id} (the primary key), so a
- * `set` writes `{ id: snapshot.id, snapshot }`.
- */
-export declare interface WorkspaceSnapshotRow {
-    readonly id: string;
-    /** The whole {@link WorkspaceSnapshot} as one opaque JSON blob — read back as `unknown`, narrowed on `get`. */
-    readonly snapshot: unknown;
-}
-
-/**
- * The durable persistence seam for a {@link WorkspaceSnapshot} — three async primitives
- * (`get` / `set` / `delete`) keyed by a workspace id, mirroring the analogous
- * `WorkflowStoreInterface` in `@orkestrel/workflow` (and the driver-swap pattern a server
- * surface's session store would follow).
- *
- * @remarks
- * The store persists the {@link WorkspaceSnapshot} — the self-contained, pure-JSON workspace
- * state — so a JSON / SQLite / IndexedDB backend swaps in WITHOUT touching the manager or the
- * workspace: the in-memory default
- * {@link import('./workspaces/stores/MemoryWorkspaceStore.js').MemoryWorkspaceStore} and its
- * driver-pluggable twin
- * {@link import('./workspaces/stores/DatabaseWorkspaceStore.js').DatabaseWorkspaceStore} (the
- * snapshot as one opaque JSON column) share THIS one interface. Hydration is NOT a store concern
- * — a {@link WorkspaceManagerInterface} reads a snapshot back and rebuilds the live workspace
- * through the constructor `seed` (see {@link WorkspaceManagerInterface.open} /
- * {@link WorkspaceManagerInterface.save}).
- *
- * Every primitive is async (a `Promise`), so a durable backend (a database round-trip) fits the
- * same shape as the memory one. The snapshot carries its OWN id, so `set` takes no separate id
- * param (mirroring the analogous `WorkflowStoreInterface.set` in `@orkestrel/workflow`). UNLIKE a
- * session store there is NO idle-TTL / eviction — a persisted workspace lives until an explicit
- * `delete`. It is concrete over {@link WorkspaceSnapshot} — no generic parameter (AGENTS §21
- * minimal-interface), since the snapshot is the ONE payload a workspace store persists.
- */
-export declare interface WorkspaceStoreInterface {
-    /**
-     * Resolve the persisted snapshot for `id`, or `undefined` if none is stored.
-     *
-     * @param id - The workspace id to resolve (a {@link WorkspaceSnapshot.id})
-     * @returns The persisted snapshot, or `undefined` if absent
-     */
-    get(id: string): Promise<WorkspaceSnapshot | undefined>;
-    /**
-     * Insert or replace a snapshot under its own `snapshot.id` (no separate id param —
-     * mirroring the analogous `WorkflowStoreInterface.set` in `@orkestrel/workflow`).
-     *
-     * @param snapshot - The snapshot to store (keyed by its `id`)
-     */
-    set(snapshot: WorkspaceSnapshot): Promise<void>;
-    /**
-     * Drop a snapshot by id; an absent id is a no-op (no throw).
-     *
-     * @param id - The workspace id to drop
-     */
-    delete(id: string): Promise<void>;
-}
-
 export { }