@orkestrel/agent 0.0.41 → 0.0.43

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

@@ -25,18 +25,22 @@ import type { QueueContext } from '@orkestrel/queue';
 import type { QueueInterface } from '@orkestrel/queue';
 import type { QueueOptions } from '@orkestrel/queue';
 import type { QueueStoreInterface } from '@orkestrel/queue';
+import { RawShape } from '@orkestrel/contract';
 import type { Result } from '@orkestrel/contract';
 import type { RunnerInterface } from '@orkestrel/workflow';
 import type { SchedulerInterface } from '@orkestrel/workflow';
 import { StringShape } from '@orkestrel/contract';
 import type { TableInterface } from '@orkestrel/database';
 import type { TokenUsage } from '@orkestrel/budget';
+import type { ToolAnnotations } from '@orkestrel/tool';
 import type { ToolCall } from '@orkestrel/tool';
 import type { ToolDefinition } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
+import type { ToolOptions } from '@orkestrel/tool';
 import type { ToolResult } from '@orkestrel/tool';
 import { UnionShape } from '@orkestrel/contract';
+import type { WorkspaceInterface } from '@orkestrel/workspace';
 import type { WorkspaceManagerInterface } from '@orkestrel/workspace';
 
 /**
@@ -99,6 +103,25 @@ export declare class Agent implements AgentInterface {
     abort(reason?: unknown): void;
 }
 
+/**
+ * Lists the members `AgentOptions` declares, frozen — the keys the `Agent` constructor admits.
+ *
+ * @remarks
+ * The constructor passes the list to `refuseOptionKeys` of `@orkestrel/contract`, so an own
+ * enumerable member outside it refuses with a `ContractError` coded `'structure'`.
+ */
+export declare const AGENT_OPTION_KEYS: readonly ["on", "error", "system", "tools", "instructions", "skills", "memos", "workspaces", "scope", "limit", "timeout", "budget", "allowance", "scheduler", "signal", "authority", "conversations", "window", "strict", "select", "builtins", "workspace"];
+
+/**
+ * Lists the members `AgentRunOptions` declares, frozen — the keys the `stream` and `generate`
+ * methods admit.
+ *
+ * @remarks
+ * The `stream` method passes the list to `refuseOptionKeys` of `@orkestrel/contract`, so an own
+ * enumerable member outside it refuses with a `ContractError` coded `'structure'`.
+ */
+export declare const AGENT_RUN_KEYS: readonly ["think", "schema", "limit", "timeout", "budget", "allowance", "signal", "conversation", "prompt", "scope", "workspace"];
+
 /** Carries a page's answer to one `ask` frame; only `approved: true` approves. */
 export declare interface AgentAnswer {
     readonly id: string;
@@ -107,8 +130,8 @@ export declare interface AgentAnswer {
 
 /** Validates and projects a page's answers to `ask` frames at a JSON wire boundary. */
 export declare const agentAnswerContract: ContractInterface<Readonly<{
-id: string;
-approved: boolean;
+    id: string;
+    approved: boolean;
 } & {}>>;
 
 /**
@@ -123,6 +146,35 @@ id: StringShape;
 approved: BooleanShape;
 }, boolean | ContractShape>;
 
+/**
+ * Names a tool the agent serves itself: `load` and `unload` show and hide a skill, `memo` reads a
+ * memo, `remember` writes one, and `switch` selects a workspace.
+ *
+ * @remarks
+ * Each is enabled through {@link AgentOptions.builtins}, and each passes the turn's ceiling and the
+ * agent's authority as any tool does.
+ */
+export declare type AgentBuiltin = 'load' | 'unload' | 'memo' | 'remember' | 'switch';
+
+/**
+ * Carries what an agent run hands each tool call as `ToolContext.caller`: the workspace the run acts
+ * on and the paths it reaches there.
+ *
+ * @remarks
+ * The agent builds one for each call as the call starts, from the view of the request the model
+ * answered and the ceiling at that moment, the context scope intersected with the run scope. Both
+ * keys are always present, so a run that shows no workspace or states no `files` list says so with
+ * `undefined` rather than an omitted member. `ToolContext.caller` is unverified by contract and can
+ * reach a handler from a wire, so read it through {@link isAgentCaller} and accept its `workspace`
+ * only as the very instance your own registry holds under that id.
+ */
+export declare interface AgentCaller {
+    /** Holds the workspace the run acts on: the one the turn's request rendered, while the ceiling admits it at the call. */
+    readonly workspace: WorkspaceInterface | undefined;
+    /** Lists the paths the run reaches in that workspace: the live ceiling's `files` list at the call (`undefined` ⇒ every path, `[]` ⇒ none). */
+    readonly files: readonly string[] | undefined;
+}
+
 /**
  * Represents a streamed step of an agent turn — the union the loop yields as it runs, discriminated
  * by the `category` of step it carries, and the pull surface beside the push {@link AgentEventMap}.
@@ -191,8 +243,9 @@ export declare function agentChunkToFrame(chunk: AgentChunk): AgentFrame | undef
  * {@link ConversationManagerInterface} message source whose active conversation is `messages`, the
  * {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
  * {@link AgentContextInterface.apply}. `build()` folds the system prompt, the scoped instructions,
- * and the skills index into one system message, the memos index and the active workspace's text into
- * one `user` context message after it, then the conversation, and never reads `tools`.
+ * the skills index, and the shown skills' bodies into one system message, the memos index and the
+ * rendered workspace's text into one `user` context message after it, then the conversation, and
+ * never reads `tools`.
  *
  * @remarks
  * - **Composition.** `system` is the optional system prompt; `instructions` / `skills` / `memos` /
@@ -211,40 +264,43 @@ export declare function agentChunkToFrame(chunk: AgentChunk): AgentFrame | undef
  *   reference, no duplication), and `build()` with no selection folds that conversation's `view()`
  *   (its per-section summaries + live tail) as the authoritative message inclusion — the scope does
  *   not filter the conversation (it owns inclusion through compaction; scope filters only
- *   instructions / skills / memos / tools / workspace files). An agent run binds a conversation at
+ *   instructions / skills / memos / tools / workspace files / workspaces). An agent run binds a conversation at
  *   its call, the active one unless the run names another, and builds through a selection over that
  *   conversation, so `conversations.switch(id)` sets the next run's default at any moment and never
  *   moves a live run; `select(conversation, request, signal)` checks the conversation it is given.
  * - **`build()` — the scoped assembly + the format cascade.** It folds, in order,
  *   the system prompt, the scope-filtered instructions (a block: the section's `open` text,
  *   each item's rendering, then any `close` text), then the scope-filtered skills index (a block
- *   whose entries join with a single newline) into one leading `system` message (prepended only
- *   when at least one part exists), then the scope-filtered memos index (the same block) and the
- *   active workspace's text files into one `user` context message (present only when the memos or
- *   workspace section renders), then
+ *   whose entries join with a single newline), then the shown skills' bodies, into one leading
+ *   `system` message (prepended only when at least one part exists), then the scope-filtered memos
+ *   index (the same block), the listed workspace ids, and the rendered workspace's text files into
+ *   one `user` context message (present only when one of those sections renders), then
  *   appends the active conversation's `view()` (the conversation owns message inclusion through
  *   compaction — the scope does not filter the conversation). The instruction manager resolves
  *   each `open` / item / `close` most-specific-first: `open` = manager-options-override >
  *   built-in; per item = item-override > manager-options-override > built-in; `close` =
  *   manager-options-override (no built-in ⇒ no closing line when unset) (see
  *   {@link AgentContextInterface.build}). With no override set, each section is its built-in
- *   header + items, no closing line. The active workspace's scoped-in image files' `base64` payload is attached to
+ *   header + items, no closing line. The rendered workspace's scoped-in image files' `base64` payload is attached to
  *   the last user message (a vision provider reads images off a user turn); when no user message
  *   exists the attachment is skipped. Built fresh each call (recomputed, never cached), so it
- *   always reflects the current managers / messages / scope / active workspace; it never mutates a
+ *   always reflects the current managers / messages / scope / workspaces; it never mutates a
  *   manager or the stored messages. `build(selection)` adds at most one `system` message of its own
  *   and reads the selection's messages as conversation parts without a role check; the select path
  *   refuses a selected `system` role as a `'ROLE'` fault over `view()`; a host's direct
  *   `build(selection)` is host-trusted, and a conversation a host implements itself whose `view()`
  *   holds a `system` message is read as host-trusted too.
- * - **The active workspace, rendered by carrier — the sole document/image context.**
- *   `workspaces.active` (when set) has its {@link import('@orkestrel/workspace').FileInterface} values scope-filtered by `scope.files`,
+ * - **The rendered workspace, by carrier — the sole document/image context.**
+ *   The rendered workspace has its {@link import('@orkestrel/workspace').FileInterface} values scope-filtered by `scope.files`,
  *   then split: text files fold into a dedicated `## Workspace` section (fenced reference blocks)
  *   in the context message — a `user` message with a minted id, never stored — and image files'
  *   `base64` payload attaches to the last user message of the conversation, never to the context
  *   message. The `system` message holds host-authored text alone: the system prompt, the
- *   instructions, and the skills index. Active-only — never the other registered workspaces; with no
- *   active workspace nothing renders for workspaces. `build()` owns this render (a `Workspace` /
+ *   instructions, the skills index, and last the bodies of the skills `options.disclosure` shows.
+ *   One workspace renders: the one `options.disclosure` selects, else the active one, and only
+ *   while the scope's `workspaces` list admits it; with neither, nothing renders for workspaces.
+ *   `options.switchable` adds the admitted workspace ids to the context message, after the memos
+ *   index. `build()` never moves the active workspace, and it owns this render (a `Workspace` /
  *   `WorkspaceManager` stays file-focused).
  * - **Tools are structural, not in the prompt.** The registry is advertised to the provider
  *   through `tools.definitions()` (scope-filtered by the loop), never serialized into the
@@ -273,8 +329,8 @@ export declare class AgentContext implements AgentContextInterface {
     get tools(): ToolManagerInterface;
     get scope(): ScopeInterface | undefined;
     apply(scope: ScopeInterface | undefined): void;
-    select(conversation: ConversationInterface, request: Message, signal: AbortSignal): Promise<Selection> | undefined;
-    build(selection?: Selection): readonly Message[];
+    select(conversation: ConversationInterface, request: Message, signal: AbortSignal, scope?: ScopeInterface): Promise<Selection> | undefined;
+    build(options?: ContextBuildOptions): readonly Message[];
 }
 
 /**
@@ -286,12 +342,14 @@ export declare class AgentContext implements AgentContextInterface {
  * (`instructions` / `skills` / `memos` / `workspaces` / `conversations`), `messages` (the active
  * conversation's live tail, satisfying {@link import('../conversations/index.js').MessageManagerInterface}), and the current `scope`
  * (the active {@link ScopeInterface} filter, or `undefined` for no filtering). `build()` folds the
- * system prompt, the scoped instructions, and the scoped skills index into one leading `system`
- * message (under each manager's `open`, each item through its `render`), renders the scoped memos
- * index and the active workspace's scope-filtered text files (fenced reference blocks) into one
- * `user` context message after it, and appends the active conversation's `view()`, attaching the active workspace's scope-filtered image files'
- * `base64` payload to the last user message. The
- * active workspace is the sole document/image context. Tools are advertised to the provider
+ * system prompt, the scoped instructions, the scoped skills index, and the bodies of the skills
+ * its `disclosure` option shows into one leading `system` message (under each manager's `open`,
+ * each item through its `render`, the bodies last), renders the scoped memos index, the admitted
+ * workspace ids when `switchable` is `true`, and the rendered workspace's scope-filtered text files
+ * (fenced reference blocks) into one `user` context message after it, and appends the active
+ * conversation's `view()`, attaching the rendered workspace's scope-filtered image files' `base64`
+ * payload to the last user message. The rendered workspace is the one `disclosure` names, else
+ * the active one, and it is the sole document/image context. Tools are advertised to the provider
  * structurally (through `tools.definitions()`, scope-filtered by the loop), not serialized into
  * the prompt, so they never appear in the output of the `build()` method. The context managers are observable
  * (each through its own `emitter` property); the context itself is event-free.
@@ -304,13 +362,14 @@ export declare interface AgentContextInterface {
     /** Holds the always-present memo set whose index `build()` renders in the `user` context message. */
     readonly memos: MemoManagerInterface;
     /**
-     * Holds the {@link WorkspaceManagerInterface} whose active workspace `build()` renders by carrier —
-     * its text files folded into the `user` context message (fenced reference blocks) and its image files'
-     * `base64` payload attached to the last user message. The active workspace is the sole
-     * document/image context. Always present (a fresh empty manager when none was supplied).
-     * `build()` reads its `active` (and the active workspace's `files()`) fresh each call. With no
-     * active workspace, nothing is rendered for workspaces. Active-only — never the other registered
-     * workspaces.
+     * Holds the {@link WorkspaceManagerInterface} one of whose workspaces `build()` renders by
+     * carrier — its text files folded into the `user` context message (fenced reference blocks) and
+     * its image files' `base64` payload attached to the last user message. That workspace is the one
+     * the `disclosure` build option names, else the active one, and it renders only while the
+     * scope's `workspaces` list admits it; it is the sole document/image context. Always present (a
+     * fresh empty manager when none was supplied). `build()` reads the registry and the workspace's
+     * `files()` fresh each call, and never moves `active`. With no workspace to render, nothing is
+     * rendered for workspaces.
      */
     readonly workspaces: WorkspaceManagerInterface;
     /**
@@ -355,8 +414,8 @@ export declare interface AgentContextInterface {
      */
     apply(scope: ScopeInterface | undefined): void;
     /**
-     * Runs the selection handler for one request — the active scope's `select`, else the agent
-     * default — and checks that the conversation did not change under it.
+     * Runs the selection handler for one request — the run scope's `select`, else the active
+     * scope's, else the agent default — and checks that the conversation did not change under it.
      *
      * @remarks
      * Resolves the handler once per call. With no handler in either home it returns `undefined`
@@ -374,35 +433,44 @@ export declare interface AgentContextInterface {
      * @param conversation - The conversation the handler selects over and the check compares
      * @param request - The user message the run serves
      * @param signal - The run's abort signal, passed to the handler
+     * @param scope - The run's scope, whose `select` runs in place of the active scope's; omitted ⇒ none
      * @returns The pending {@link Selection}, or `undefined` when no handler is set
      *
      * @example
      * ```ts
      * const request = context.messages.add({ role: 'user', content: 'Summarize the ticket.' })
      * const selection = await context.select(context.messages, request, new AbortController().signal)
-     * context.build(selection)
+     * context.build({ selection })
      * ```
      */
-    select(conversation: ConversationInterface, request: Message, signal: AbortSignal): Promise<Selection> | undefined;
+    select(conversation: ConversationInterface, request: Message, signal: AbortSignal, scope?: ScopeInterface): Promise<Selection> | undefined;
     /**
      * Builds the provider input for the next turn: a leading `system` message folding the
-     * prompt, the scope-filtered instructions, and the scope-filtered skills index (each section's
-     * header and each item's rendering resolved through the format cascade), then one `user` context
-     * message holding the scope-filtered memos index before the active workspace's scope-filtered
-     * (`scope.files`) text files as fenced reference blocks in a
-     * `## Workspace` section, then the active conversation's `view()`, or the selection's
-     * `messages` when a selection is passed, with the active workspace's image files' `base64`
-     * payload attached to the last user message. With no override set, each section renders on its
-     * manager's built-in framing. The `system` message is prepended only when some part of it
-     * exists, the context message only when the memos or workspace section renders, the workspace render
-     * covers the active workspace alone, tools are advertised structurally rather than in the
-     * prompt, and the input is built fresh on each call.
+     * prompt, the scope-filtered instructions, the scope-filtered skills index (each section's
+     * header and each item's rendering resolved through the format cascade), and last the bodies of
+     * the skills `disclosure` shows under `## Loaded skills`, then one `user` context message holding
+     * the scope-filtered memos index, the admitted workspace ids under `## Workspaces` when
+     * `switchable` is `true`, and the rendered workspace's scope-filtered (`scope.files`) text files
+     * as fenced reference blocks in a `## Workspace` section, then the active conversation's
+     * `view()`, or the selection's `messages` when a selection is passed, with the rendered
+     * workspace's image files' `base64` payload attached to the last user message. With no override
+     * set, each section renders on its manager's built-in framing. The `system` message is prepended
+     * only when some part of it exists, the context message only when one of its sections renders,
+     * one workspace renders, tools are advertised structurally rather than in the prompt, and the
+     * input is built fresh on each call.
      *
      * @remarks
-     * **The active workspace (rendered by carrier) — the sole document/image context.** When
-     * `workspaces.active` is set, its
+     * **The shown bodies.** Each name `disclosure.skills` lists renders once, in the given order,
+     * as `### name` and the skill's `content`, when the skill registry holds it and the scope's
+     * `skills` list admits it; a blank body renders nothing, and an unregistered or excluded name
+     * renders nothing.
+     *
+     * **The rendered workspace (by carrier) — the sole document/image context.** It is the one
+     * `disclosure.workspace` names, else `workspaces.active`, and it renders only while the scope's
+     * `workspaces` list admits it; an unregistered `disclosure.workspace` renders none, and the build
+     * never moves `workspaces.active`. Its
      * {@link import('@orkestrel/workspace').WorkspaceInterface.files} are filtered by
-     * `scope.files` (a three-way allow-list; `undefined` ⇒ all active files), then split by
+     * `scope.files` (a three-way allow-list; `undefined` ⇒ all its files), then split by
      * carrier: text files ({@link import('@orkestrel/workspace').isTextContent}) render into a dedicated
      * `## Workspace` section in the context message — a `user` message with a minted id that
      * follows the system message and is never stored — each a fenced
@@ -410,8 +478,7 @@ export declare interface AgentContextInterface {
      * the longest backtick run in the text, and never shorter than three; binary files whose MIME
      * starts with `image/` have their `base64` payload
      * attached to the last user message (a vision provider reads images off a user turn).
-     * Active-only — never the other registered workspaces; with no active workspace nothing is
-     * rendered for workspaces.
+     * One workspace renders at most; with none to render, nothing is rendered for workspaces.
      *
      * **The format cascade.** Each manager section frames as `[open, ...items.map(render), close]`
      * (empty / absent slots dropped, the survivors `\n\n`-joined), reading the manager's `open`,
@@ -437,12 +504,15 @@ export declare interface AgentContextInterface {
      * handler that adds text for the model, such as a ledger's records, writes it into a message of
      * `selection.messages`.
      *
-     * @param selection - The selection whose `messages` replace `view()`; omitted ⇒ `view()`
-     * @returns The scoped conversation, prefixed by the context message when the scoped memos or the
-     *   active workspace's scoped text files are non-empty, and before it by the assembled `system`
-     *   message when the prompt, the scoped instructions, or the scoped skills are non-empty
+     * @param options - The selection whose `messages` replace `view()`, a run's scope intersected
+     *   with the active one, what the build shows, and whether it lists the workspace ids; omitted ⇒
+     *   `view()` under the active scope, with no body and the active workspace
+     * @returns The scoped conversation, prefixed by the context message when the scoped memos, the
+     *   listed workspace ids, or the rendered workspace's scoped text files are non-empty, and before
+     *   it by the assembled `system` message when the prompt, the scoped instructions, the scoped
+     *   skills, or the shown bodies are non-empty
      */
-    build(selection?: Selection): readonly Message[];
+    build(options?: ContextBuildOptions): readonly Message[];
 }
 
 /**
@@ -464,8 +534,8 @@ export declare interface AgentContextInterface {
  * {@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. `select` is the
- * agent's default {@link SelectionHandler}, which the active scope's `select` overrides; omitted,
- * `select()` returns `undefined` while the active scope holds no handler.
+ * agent's default {@link SelectionHandler}, which the active scope's `select` and a run scope's
+ * `select` override; omitted, `select()` returns `undefined` while neither scope holds a handler.
  */
 export declare interface AgentContextOptions {
     readonly system?: string;
@@ -482,11 +552,11 @@ export declare interface AgentContextOptions {
     readonly memos?: MemoManagerInterface;
     /**
      * Reuses a pre-built {@link WorkspaceManagerInterface}; a fresh empty one is created when
-     * omitted (so `context.workspaces` is always present). `build()` renders the active workspace's
-     * files by carrier — text files into the `user` context message after the system message
-     * (fenced), image files attached to the last user message. The registry is structural; change
-     * its active workspace through
-     * `workspaces.switch(id)`. The active workspace is the sole document/image context.
+     * omitted (so `context.workspaces` is always present). `build()` renders one workspace's files
+     * by carrier — the one its `disclosure` option names, else the active one — text files into the
+     * `user` context message after the system message (fenced), image files attached to the last user
+     * message. That one workspace is the sole document/image context. The registry is structural;
+     * change its active workspace through `workspaces.switch(id)`.
      */
     readonly workspaces?: WorkspaceManagerInterface;
     /** Sets the initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
@@ -498,20 +568,43 @@ export declare interface AgentContextOptions {
      * names no conversation — is always defined. `build()` folds the active conversation's
      * `view()` (the per-section summaries + the live tail), or a passed selection's `messages`.
      * The scope's filters never touch messages; message inclusion is the conversation's through
-     * compaction and, when a handler is set, the selection's. A scope change reaches the prompt at
-     * the next build or select site (run entry, the pre-first-turn compaction fold, or a compaction
-     * rebuild) and the tools at the next turn's snapshot. The registry is structural; change its
+     * compaction and, when a handler is set, the selection's. In an agent run, a scope change reaches
+     * the tools and the head at the next turn's snapshot, where a changed list rebuilds the head, and
+     * a `select` change waits for the next build or select site (run entry, the pre-first-turn
+     * compaction fold, or a compaction rebuild). The registry is structural; change its
      * active conversation through the manager's `switch(id)`, which sets the next run's default and
      * never moves a live run.
      */
     readonly conversations?: ConversationManagerInterface;
     /**
-     * Holds the agent's default selection handler; the active scope's `select` overrides it.
-     * Omitted ⇒ with no scope handler either, `build()` folds the active conversation's `view()`.
+     * Holds the agent's default selection handler; the active scope's `select` overrides it, and a
+     * run scope's `select` overrides both. Omitted ⇒ with no scope handler either, `build()` folds the
+     * active conversation's `view()`.
      */
     readonly select?: SelectionHandler;
 }
 
+/**
+ * Holds what one run shows within its ceiling: the loaded skills and the selected workspace.
+ *
+ * @remarks
+ * The agent loop derives one for each turn and passes it to `build`: the skills from the
+ * conversation's stored calls of the built-ins a run enables, and the workspace from the thread's
+ * last `switch`, else the `workspace` option of the run or the agent. Every read of it passes the
+ * ceiling and the registries, so a name that is not registered or not admitted shows nothing.
+ *
+ * @example
+ * ```ts
+ * const disclosure: AgentDisclosure = { skills: ['refunds'], workspace: 'orders' }
+ * ```
+ */
+export declare interface AgentDisclosure {
+    /** Names the loaded skills, in load order. */
+    readonly skills: readonly string[];
+    /** Names the selected workspace; omitted ⇒ the registry's active workspace. */
+    readonly workspace?: string;
+}
+
 /**
  * Reports an `ask` on an authority that has no approver or that its approver refuses, an authority missing its fallback or a rule's verdict, tools set with no authority, a run sharing accounting or a conversation with a live run, a `limit` that is not a positive safe integer, a name absent from a registry pool, a strict run's answer that fails its schema, or a strict run whose request exceeds its window. Agent construction, the `stream` and `generate` methods, and registry accessors throw synchronously, before returning a handle or promise; a `'WINDOW'` refusal rejects the run's `result` instead, and an `'APPROVER'` refusal rejects the promise the `ask` method of an `Authority` or the `ask` handler of an `Approver` returns. Await the call inside `try`/`catch` to catch it.
  *
@@ -523,6 +616,9 @@ export declare interface AgentContextOptions {
  * `'AUTHORITY'` reports an `Authority` built with no valid `fallback`, a rule with no valid `verdict`
  * (its `context` names the `rule` index), and an agent built with `tools` and no `authority`. Each
  * throws at construction, with the options a host passes to correct it in the message.
+ * `'BUILTIN'` reports a `builtins` entry that is not a built-in or repeats one, `unload` enabled
+ * without `load`, and a tool manager holding a tool under an enabled built-in's name, each thrown
+ * at construction.
  * `'CONCURRENCY'` reports a run started while another run on the same agent is live, when the
  * agent carries a `window` (a shared context budget) or when the run's effective `budget` or
  * `allowance` is an instance a live run holds — the second run's `start()` would replace that
@@ -531,18 +627,18 @@ export declare interface AgentContextOptions {
  * `agent` id, and the `conversation` id for a shared conversation. For concurrent runs, use
  * separate agents, or one agent with no `window`, distinct budget and allowance instances per
  * run, and a distinct conversation per run.
- * `'LIMIT'` reports a construction or per-run `limit` that is not a positive safe integer,
- * including one a rehydrated job carries into `build`. `'REGISTRY'` reports a rehydration name
- * absent from its registry pool, on `provider` / `tool` / `authority` / `scheduler` / `build`,
- * whose `context` names the `category` and the `name`, and a job that names `tools` and no
- * `authority` at `build`, whose `context` names the `tools`. `'WINDOW'` reports a `strict` run whose
+ * `'LIMIT'` reports a construction or per-run `limit` that is not a positive safe integer.
+ * `'REGISTRY'` reports a rehydration name absent from its registry pool, on `provider` / `tool` /
+ * `authority` / `scheduler` / `build`, whose `context` names the `category` and the `name`, and a
+ * job `build` refuses as a record, whose `context` holds the contract's `faults` or the
+ * `refusals` lines `collectJobRefusals` returns. `'WINDOW'` reports a `strict` run whose
  * complete provider request is still over the `window` budget, equal to its `max` included, after
  * the one permitted fold or with no fold possible; it settles the run `error` before the provider
  * is called, and its `context` holds the `agent` id, the measured `consumed`, and the window `max`.
  * Narrow a caught value with {@link isAgentError} and branch on `error.code`.
  */
 export declare class AgentError extends Error {
-    /** Names the machine-readable condition — `'APPROVER'`: an `ask` on an authority that has no approver, or one its approver refuses; `'AUTHORITY'`: an authority missing its fallback or a rule's verdict, or tools set with no authority; `'CONCURRENCY'`: a run sharing accounting or a conversation with a live run; `'LIMIT'`: a `limit` that is not a positive safe integer; `'REGISTRY'`: a rehydration name absent from its registry pool; `'WINDOW'`: a strict run whose complete request is still over its window budget. */
+    /** Names the machine-readable condition — `'APPROVER'`: an `ask` on an authority that has no approver, or one its approver refuses; `'AUTHORITY'`: an authority missing its fallback or a rule's verdict, or tools set with no authority; `'BUILTIN'`: a built-in list the agent cannot serve; `'CONCURRENCY'`: a run sharing accounting or a conversation with a live run; `'LIMIT'`: a `limit` that is not a positive safe integer; `'REGISTRY'`: a rehydration name absent from its registry pool; `'WINDOW'`: a strict run whose complete request is still over its window budget. */
     readonly code: AgentErrorCode;
     /** Holds the values that locate the failure, such as the `agent` id of a refused run, or `undefined` when none were supplied. */
     readonly context: Readonly<Record<string, unknown>> | undefined;
@@ -556,8 +652,8 @@ export declare class AgentError extends Error {
     constructor(code: AgentErrorCode, message: string, options?: CodedErrorOptions);
 }
 
-/** Names the machine-readable agent approver, authority, concurrency, limit, registry, schema, and window failures. */
-export declare type AgentErrorCode = 'APPROVER' | 'AUTHORITY' | 'CONCURRENCY' | 'LIMIT' | 'REGISTRY' | 'SCHEMA' | 'WINDOW';
+/** Names the machine-readable agent approver, authority, built-in, concurrency, limit, registry, schema, and window failures. */
+export declare type AgentErrorCode = 'APPROVER' | 'AUTHORITY' | 'BUILTIN' | 'CONCURRENCY' | 'LIMIT' | 'REGISTRY' | 'SCHEMA' | 'WINDOW';
 
 /**
  * Maps the push observation surface of an {@link AgentInterface} — the lifecycle, usage, and tool
@@ -663,6 +759,21 @@ export declare type AgentEventMap = {
      * fire none.
      */
     readonly select: readonly [selection: Selection];
+    /**
+     * Reports the exact request a turn dispatches, with the turn's `index` and the conversation its
+     * run is bound to, once a turn after the loop admits the request and before the provider receives
+     * it, so after a compaction fold it carries the rebuilt request. The request object and its
+     * `messages` and `tools` arrays are frozen; each message, `options`, and each definition is a
+     * shared object, so a listener is host code that reads the request and never writes to it. A
+     * request whose turn advertises no tool carries no `tools` member, and a turn cancelled before
+     * its request is composed emits none. A run aborted while a turn's `request` listeners run sends
+     * nothing for that turn: the provider receives no call for it, and the turn ends as a cancel.
+     */
+    readonly request: readonly [
+    index: number,
+    request: ProviderRequest,
+    conversation: ConversationInterface
+    ];
 };
 
 /**
@@ -677,6 +788,17 @@ export declare type AgentEventMap = {
  * awaited inline, so a bounded runner frees the parent's slot for them. `createAgentRunner`
  * creates one instance per runner and binds its `execute` method as the runner's handler.
  *
+ * A child job runs within its parent. Before a unit spawns or runs, on every attempt, the
+ * `execute` method walks the whole tree under it through the `scanJobTree` helper and refuses the
+ * unit when any job exceeds its own parent on `tools`, `builtins`, `scope`, `authority`,
+ * `provider`, `scheduler`, `limit`, `timeout`, or `budget`, or when a job is malformed or its build
+ * would refuse it (the lines `collectJobRefusals` returns), so nothing in a refused tree spawns, builds,
+ * or runs. A child's `workspace` is free, because it renders nothing its own `scope`
+ * omits. Each child is held within its parent alone, so the children of one parent can together
+ * spend more than it. A job that needs another provider, another authority, a skill, memo,
+ * workspace, or built-in its parent lacks, or more room than its parent is a root job the host
+ * enqueues.
+ *
  * @example
  * ```ts
  * import type { AgentJobInput, ProviderInterface } from '@orkestrel/agent'
@@ -701,11 +823,20 @@ export declare class AgentFanout {
      */
     constructor(registry: AgentRegistryInterface, partial: boolean);
     /**
-     * Executes one unit: spawns its declared children unless an earlier attempt of the unit already
-     * did, then runs the rehydrated agent and settles it under the partial policy.
+     * Executes one unit: refuses its tree when a job in it is malformed or exceeds its parent, spawns
+     * its declared children unless an earlier attempt of the unit already did, then runs the
+     * rehydrated agent and settles it under the partial policy.
+     *
+     * @remarks
+     * The check runs on every attempt, before the unit spawns or runs, and throws synchronously. The
+     * error's message opens with the rule each kind of finding breaks, a refused job's rule when a
+     * finding opens with `JOB_REFUSAL_PREFIX` and the within-parent rule when a finding names an
+     * exceeded member, then lists every finding, one a line. Its `context.findings` holds the same
+     * findings in walk order.
      *
      * @param controller - The runner controller for this unit's attempt
      * @returns The settled agent result of the unit
+     * @throws {AgentError} Thrown with code `'REGISTRY'` when a job in the unit's tree is malformed or exceeds its parent, or when the registry cannot rehydrate the unit
      * @throws {AgentJobError} Thrown when the run ended partial and the partial policy is `false`
      */
     execute(controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
@@ -761,45 +892,45 @@ export declare type AgentFrame = {
 
 /** Validates and projects agent frames at a JSON wire boundary. */
 export declare const agentFrameContract: ContractInterface<Readonly<{
-category: "token";
-content: string;
+    category: "token";
+    content: string;
 } & {}> | Readonly<{
-category: "think";
-content: string;
+    category: "think";
+    content: string;
 } & {}> | Readonly<{
-category: "tool";
-success: true;
-name: string;
+    category: "tool";
+    success: true;
+    name: string;
 } & {}> | Readonly<{
-category: "tool";
-success: false;
+    category: "tool";
+    success: false;
 } & {}> | Readonly<{
-category: "usage";
-usage: Readonly<{
-prompt: number;
-completion: number;
-total: number;
-} & {}>;
-estimate: number;
+    category: "usage";
+    usage: Readonly<{
+        prompt: number;
+        completion: number;
+        total: number;
+    } & {}>;
+    estimate: number;
 } & {}> | Readonly<{
-category: "ask";
-id: string;
-name: string;
-zone: string;
-arguments: string;
+    category: "ask";
+    id: string;
+    name: string;
+    zone: string;
+    arguments: string;
 } & {}> | Readonly<{
-category: "finish";
-content: string;
-partial: boolean;
+    category: "finish";
+    content: string;
+    partial: boolean;
 } & {
-usage?: Readonly<{
-prompt: number;
-completion: number;
-total: number;
-} & {}>;
-layer?: "budget" | "meter" | "model";
+    usage?: Readonly<{
+        prompt: number;
+        completion: number;
+        total: number;
+    } & {}>;
+    layer?: "budget" | "meter" | "model";
 }> | Readonly<{
-category: "error";
+    category: "error";
 } & {}>>;
 
 /**
@@ -877,7 +1008,7 @@ category: LiteralShape<readonly ["error"]>;
  *   judge, a tool handler, and a selection handler are awaited until they settle, because each can
  *   carry usage or finished work, so one that ignores its signal holds the run past a cancel or a
  *   timeout, and on a ledger its held scan, until it returns.
- *   The agent supplies no caller identity.
+ *   Each call's `ToolContext.caller` is an {@link AgentCaller}.
  * - **Paced + capped.** The `scheduler` (when given) yields between turns; tool
  *   iteration is capped at `limit` so the loop always terminates.
  * - **Two observation surfaces.** Pull: the {@link AgentChunk} stream (`stream().events`)
@@ -906,9 +1037,10 @@ export declare interface AgentInterface {
      * `budget` or `allowance` is an instance a live run holds, or when a live run is bound to the
      * run's conversation; a run whose `limit` is not a positive safe
      * integer throws one with `code: 'LIMIT'`. A `prompt` that `agentPromptContract` refuses, a
-     * `budget` or `allowance` that does not implement `BudgetInterface`, or a `conversation` that
-     * does not implement `ConversationInterface`, throws a `ContractError` with code `'placement'`
-     * before either bound starts. Each throws synchronously, before any `Promise` is returned, and
+     * `budget` or `allowance` that does not implement `BudgetInterface`, a `conversation` that does
+     * not implement `ConversationInterface`, a `scope` that does not implement `ScopeInterface`, or a
+     * `workspace` that is not a string throws a `ContractError` with code
+     * `'placement'` before either bound starts. Each throws synchronously, before any `Promise` is returned, and
      * leaves the run's conversation unchanged. A fire-and-forget `agent.generate().catch(...)`
      * therefore will not catch them (the throw happens on the call itself, ahead of the `.catch` ever
      * attaching) — await the call (inside a `try`/`catch`) or wrap the call expression itself in
@@ -917,7 +1049,7 @@ export declare interface AgentInterface {
      * @param options - Optional per-run {@link AgentRunOptions} (for example `think`); omitted ⇒ defaults
      * @returns The settled {@link AgentResult} (`partial: true` when cancelled)
      * @throws {AgentError} Thrown when a live run shares the `window`, a budget or allowance instance, or the run's conversation (`code: 'CONCURRENCY'`) or the `limit` is not a positive safe integer (`code: 'LIMIT'`), synchronously before a handle returns.
-     * @throws {ContractError} Thrown when the `prompt` is not an exact `AgentPrompt`, the `budget` or `allowance` does not implement `BudgetInterface`, or the `conversation` does not implement `ConversationInterface` (`code: 'placement'`), synchronously before a handle returns.
+     * @throws {ContractError} Thrown when the `prompt` is not an exact `AgentPrompt`, the `budget` or `allowance` does not implement `BudgetInterface`, the `conversation` does not implement `ConversationInterface`, the `scope` does not implement `ScopeInterface`, or the `workspace` is not a string (`code: 'placement'`), synchronously before a handle returns.
      */
     generate(options?: AgentRunOptions): Promise<AgentResult>;
     /**
@@ -930,7 +1062,8 @@ export declare interface AgentInterface {
      * instance, or a live run's conversation throws an {@link import('./errors.js').AgentError} with
      * `code: 'CONCURRENCY'`, a `limit` that is not a positive safe integer throws one with `code: 'LIMIT'`, and a `prompt` that
      * `agentPromptContract` refuses, a `budget` or `allowance` that does not implement
-     * `BudgetInterface`, or a `conversation` that does not implement `ConversationInterface` throws a
+     * `BudgetInterface`, a `conversation` that does not implement `ConversationInterface`, a `scope`
+     * that does not implement `ScopeInterface`, or a `workspace` that is not a string throws a
      * `ContractError` with code `'placement'`, synchronously — before the
      * {@link AgentStreamInterface} handle is even returned, so it cannot be caught by chaining
      * off the (never-produced) handle; wrap the call itself in `try`/`catch`. Each of those leaves
@@ -944,7 +1077,7 @@ export declare interface AgentInterface {
      * @param options - Optional per-run {@link AgentRunOptions} (for example `think`); omitted ⇒ defaults
      * @returns A live {@link AgentStreamInterface} handle (events + result + abort)
      * @throws {AgentError} Thrown when a live run shares the `window`, a budget or allowance instance, or the run's conversation (`code: 'CONCURRENCY'`) or the `limit` is not a positive safe integer (`code: 'LIMIT'`), synchronously before a handle returns.
-     * @throws {ContractError} Thrown when the `prompt` is not an exact `AgentPrompt`, the `budget` or `allowance` does not implement `BudgetInterface`, or the `conversation` does not implement `ConversationInterface` (`code: 'placement'`), synchronously before a handle returns.
+     * @throws {ContractError} Thrown when the `prompt` is not an exact `AgentPrompt`, the `budget` or `allowance` does not implement `BudgetInterface`, the `conversation` does not implement `ConversationInterface`, the `scope` does not implement `ScopeInterface`, or the `workspace` is not a string (`code: 'placement'`), synchronously before a handle returns.
      */
     stream(options?: AgentRunOptions): AgentStreamInterface;
     /**
@@ -958,33 +1091,40 @@ export declare interface AgentInterface {
 
 /** Checks a durable agent job exactly at `AgentRegistry.build`. */
 export declare const agentJobContract: ContractInterface<Readonly<{
-provider: string;
-} & {
-messages?: readonly Readonly<{
-role: "assistant" | "system" | "tool" | "user";
-content: string;
+    provider: string;
 } & {
-calls?: readonly Readonly<{
-id: string;
-name: string;
-arguments: {
-readonly [k: string]: JSONValue;
-};
-} & {}>[];
-call?: string;
-images?: readonly string[];
-thinking?: string;
-}>[];
-system?: string;
-tools?: readonly string[];
-authority?: string;
-scheduler?: string;
-limit?: number;
-timeout?: number;
-budget?: number;
-children?: readonly {
-readonly [k: string]: JSONValue;
-}[];
+    messages?: readonly Readonly<{
+        content: string;
+        role: "assistant" | "tool" | "user";
+    } & {
+        calls?: readonly Readonly<{
+            id: string;
+            name: string;
+            arguments: {
+                readonly [k: string]: JSONValue;
+            };
+        } & {}>[];
+        call?: string;
+        images?: readonly string[];
+        thinking?: string;
+    }>[];
+    system?: string;
+    tools?: readonly string[];
+    authority?: string;
+    scheduler?: string;
+    limit?: number;
+    timeout?: number;
+    budget?: number;
+    scope?: Readonly<{
+        skills: readonly string[];
+        memos: readonly string[];
+        workspaces: readonly string[];
+    } & {}>;
+    workspace?: string;
+    builtins?: readonly ("load" | "memo" | "remember" | "switch" | "unload")[];
+    children?: readonly {
+        readonly [k: string]: JSONValue;
+    }[];
 }>>;
 
 /**
@@ -1027,7 +1167,11 @@ export declare class AgentJobError extends Error {
  * to run); `messages` defaults to an empty seed. `tools` lists registry keys whose
  * resolved tools are loaded into the agent's manager; `authority` / `scheduler` are
  * single registry keys (their live objects carry functions, so they can't serialize).
- * `budget` is a token ceiling rebuilt into a `createTokenBudget({ max })`.
+ * `budget` is a token ceiling rebuilt into a `createTokenBudget({ max })`. A job holds what it
+ * names: `scope` lists the skills, memos, and workspaces it holds of the registry's managers, so a
+ * job with no `scope` holds none, as a job with no `tools` holds no tool; `workspace` renders within
+ * that scope; and `builtins` names the built-in tools it serves itself, which pass the authority
+ * `authority` names as its tools do.
  */
 export declare interface AgentJobInput {
     /** Names the registry key of the {@link ProviderInterface} the job runs against. */
@@ -1038,7 +1182,7 @@ export declare interface AgentJobInput {
     readonly system?: string;
     /** Names the registry keys of the values of {@link ToolInterface} loaded into the agent's tool manager; a non-empty list requires `authority`. */
     readonly tools?: readonly string[];
-    /** Names the registry key of the {@link AuthorityInterface} policy gate; required when `tools` names any. */
+    /** Names the registry key of the {@link AuthorityInterface} policy gate; required when `tools` or `builtins` names any. */
     readonly authority?: string;
     /** Names the registry key of an optional {@link SchedulerInterface} pacing the loop. */
     readonly scheduler?: string;
@@ -1048,6 +1192,15 @@ export declare interface AgentJobInput {
     readonly timeout?: number;
     /** Sets a token ceiling rebuilt into a `createTokenBudget({ max })` cost bound. */
     readonly budget?: number;
+    /**
+     * Holds the job's ceiling over the `skills`, `memos`, and `workspaces` managers of the registry,
+     * each list required, `[]` for none. Omitted ⇒ the job holds no skill, memo, or workspace.
+     */
+    readonly scope?: Required<Pick<ScopeFilter, 'skills' | 'memos' | 'workspaces'>>;
+    /** Names the workspace the job renders in place of the active one, within its `scope` (see {@link AgentOptions.workspace}). */
+    readonly workspace?: string;
+    /** Lists the built-in tools the job serves itself (see {@link AgentOptions.builtins}); a non-empty list requires `authority`. */
+    readonly builtins?: readonly AgentBuiltin[];
     /**
      * Lists the sub-agent jobs this job fans out — each a nested {@link AgentJobInput} (so the whole
      * tree stays serializable). On a `createAgentRunner`, the handler calls `controller.spawn` for
@@ -1063,14 +1216,16 @@ export declare interface AgentJobInput {
  * refuses instead of running an agent without it.
  *
  * @remarks
- * `children` holds JSON records, because each child crosses this shape at its own `build`. `limit`
- * reads as a number here and as a positive safe integer at the agent's construction, which owns that
- * refusal.
+ * `children` holds JSON records, because each child crosses this shape at its own `build`. Each
+ * bound states what the build reads: `limit` an integer from 1 through `Number.MAX_SAFE_INTEGER`,
+ * `timeout` an integer from 0 through `MAX_TIMEOUT_MS`, and `budget` a number of at least 0. A seed
+ * message plays a `ConversationRole`, so a `system` message refuses here. A `scope` holds the
+ * `skills`, `memos`, and `workspaces` lists, each required, and no other member; `builtins` admits
+ * only the names of `AgentBuiltin`, and `collectJobRefusals` reads what a list of them cannot state.
  */
 export declare const agentJobShape: ObjectShape<    {
 provider: StringShape;
 messages: OptionalShape<ArrayShape<ObjectShape<    {
-role: LiteralShape<readonly ["system", "user", "assistant", "tool"]>;
 content: StringShape;
 calls: OptionalShape<ArrayShape<ObjectShape<    {
 id: StringShape;
@@ -1080,6 +1235,7 @@ arguments: ObjectShape<Record<never, never>, JSONShape>;
 call: OptionalShape<StringShape>;
 images: OptionalShape<ArrayShape<StringShape>>;
 thinking: OptionalShape<StringShape>;
+role: LiteralShape<readonly ["user", "assistant", "tool"]>;
 }, boolean | ContractShape>>>;
 system: OptionalShape<StringShape>;
 tools: OptionalShape<ArrayShape<StringShape>>;
@@ -1088,6 +1244,13 @@ scheduler: OptionalShape<StringShape>;
 limit: OptionalShape<NumberShape>;
 timeout: OptionalShape<NumberShape>;
 budget: OptionalShape<NumberShape>;
+scope: OptionalShape<ObjectShape<    {
+skills: ArrayShape<StringShape>;
+memos: ArrayShape<StringShape>;
+workspaces: ArrayShape<StringShape>;
+}, boolean | ContractShape>>;
+workspace: OptionalShape<StringShape>;
+builtins: OptionalShape<ArrayShape<LiteralShape<readonly ["load", "unload", "memo", "remember", "switch"]>>>;
 children: OptionalShape<ArrayShape<ObjectShape<Record<never, never>, JSONShape>>>;
 }, boolean | ContractShape>;
 
@@ -1190,10 +1353,14 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  * Configures `createAgent` — the loop's bounds and pacing, the reserved `on` hooks, the
  * construction-time context wiring (`instructions` / `skills` / `memos` / `workspaces` / `scope`), the `conversations`
  * registry holding every run's default, the context `window` budget that opts into automatic
- * compaction of the run's conversation, and the `strict` switch that aborts the run on an
- * automatic-compaction summarizer failure instead of the lenient default.
+ * compaction of the run's conversation, the `builtins` each run serves and the `workspace` it
+ * renders, and the `strict` switch that settles the run `error` on
+ * an automatic-compaction summarizer failure, a selection fault, or a request still over the
+ * window, or continues past them when `false`.
  *
  * @remarks
+ * An own enumerable member this type does not declare refuses at construction with a
+ * `ContractError` coded `'structure'`, and a declared member holding `undefined` reads as omitted.
  * - `system` — an optional system prompt prepended to the turn (seeds the context).
  * - `tools` — an optional pre-built {@link ToolManagerInterface} the loop dispatches
  *   the model's calls through; an empty one is created when omitted.
@@ -1213,9 +1380,10 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  *   The loop races that yield against the run signal, so a scheduler that ignores its signal still ends on a cancel.
  * - `signal` — an optional external `AbortSignal` whose abort cancels the turn (a
  *   partial result).
- * - `authority` — an optional {@link AuthorityInterface} that decides each scope-admitted call;
- *   omitted ⇒ a default `Authority` that allows an unannotated call and asks for a
- *   `consequential` one, which no approver answers, so it is denied.
+ * - `authority` — an {@link AuthorityInterface} that decides each scope-admitted call; required
+ *   when `tools` is set or `builtins` lists a name, and construction throws an `AgentError` with
+ *   code `'AUTHORITY'` without it. Omitted with no `tools` ⇒ the agent holds no authority, and the
+ *   loop denies a call to a tool added later through `context.tools`.
  * - `conversations` — an optional {@link ConversationManagerInterface} forwarded to the agent's
  *   context (so `context.messages` is its active conversation's live tail); a run binds that
  *   active conversation when it names no `conversation` of its own. Omitted ⇒ a fresh registry
@@ -1234,11 +1402,11 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  *   thrown handler, a returned `fault`, a conversation changed under the handler, a selected
  *   message whose role is not a `ConversationRole`) settle the same way, and a request still over
  *   the `window` after the permitted fold, or one that cannot fold, settles `error` with an
- *   `AgentError` coded `'WINDOW'` before the provider is called.
- *   Default: `false`. The run continues over-window, or on `view()` after a selection fault.
+ *   `AgentError` coded `'WINDOW'` before the provider is called. When `false`, the run continues
+ *   over-window, or on `view()` after a selection fault. Default: `true`.
  * - `select` — an optional default {@link SelectionHandler} forwarded to the agent's context; the
- *   active scope's `select` overrides it. The loop runs it at run entry and after each automatic
- *   compaction rebuild, emits each {@link Selection} it builds from on `select`, and charges the
+ *   active scope's `select` overrides it, and a run scope's `select` overrides both for its run.
+ *   The loop runs it at run entry and after each automatic compaction rebuild, emits each {@link Selection} it builds from on `select`, and charges the
  *   selection's usage to `budget` and the result's `usage`.
  * - `instructions` — an optional pre-built {@link InstructionManagerInterface} forwarded to the
  *   agent's context; an empty one is created when omitted (mirrors {@link AgentContextOptions.instructions}).
@@ -1250,6 +1418,18 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  *   agent's context; a fresh empty one is created when omitted (mirrors {@link AgentContextOptions.workspaces}).
  * - `scope` — an optional initial active {@link ScopeInterface} forwarded to the agent's context
  *   (the context and tool-dispatch filter); `undefined` ⇒ every registered tool is admitted.
+ * - `builtins` — the {@link AgentBuiltin} tools each run serves itself, each advertised only where
+ *   the turn's ceiling admits its name and each call passing the authority. `remember` and `switch`
+ *   are advertised only while the ceiling's `memos` or `workspaces` list names a key, and `load` and
+ *   `unload` are not advertised under an empty `skills` list; construction throws an
+ *   `AgentError` with code `'BUILTIN'` for a name that is no built-in, a repeated name, `unload`
+ *   without `load`, or a name the tool manager already holds. Omitted ⇒ none.
+ * - `workspace` — the id of the workspace every run renders in place of the active one, from its
+ *   first request, until the thread's own `switch`, and only where the registry holds it and the
+ *   ceiling admits it; a run's own `workspace` replaces it. It selects for the run and never moves
+ *   the `workspaces` manager's active pointer, which every conversation of the agent reads.
+ *   Construction throws a `ContractError` with code `'placement'` for a value that is not a string.
+ *   Omitted ⇒ the active workspace.
  * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the agent's
  *   {@link AgentEventMap}, wired at construction (for example `{ finish: (r) => log(r) }`).
  */
@@ -1275,10 +1455,12 @@ export declare interface AgentOptions {
      * denied the same way, whatever the authority would decide.
      * Every scoped-out call, one in a turn advertising no tools included, produces a denial tool
      * result and message and a `deny` event, and the loop continues.
-     * A scope change through the context's `apply` method applies the tool allow-list at the next
-     * turn's snapshot, which a `turn` listener reaches for the same turn, and the instructions,
-     * skills, memos, files, and `select` at the next build or select site: run entry, the pre-first-turn
-     * compaction fold, or a compaction rebuild.
+     * A scope change through the context's `apply` method applies at the next turn's snapshot, which
+     * a `turn` listener reaches for the same turn: the snapshot decides the advertised tools, and a
+     * changed `instructions`, `skills`, `memos`, `files`, or `workspaces` list rebuilds the head for
+     * that turn over the same messages. A `select` change, and an instruction text edit with no list
+     * change, wait for the next build or select site: run entry, the pre-first-turn compaction fold,
+     * or a compaction rebuild.
      */
     readonly scope?: ScopeInterface;
     /**
@@ -1374,12 +1556,17 @@ export declare interface AgentOptions {
     readonly strict?: boolean;
     /**
      * Holds the default selection handler forwarded to the agent's context; the active scope's
-     * `select` overrides it while that scope is active. The loop runs it at run entry and after
+     * `select` overrides it while that scope is active, and a run scope's `select` overrides both for
+     * its run. The loop runs it at run entry and after
      * each automatic compaction rebuild, for the user message that ends the run's conversation, and
      * charges its usage to the cost `budget`. Omitted ⇒ with no scope handler either, the loop
      * builds from the run's conversation's `view()` and awaits nothing.
      */
     readonly select?: SelectionHandler;
+    /** Lists the built-in tools each run serves itself, each subject to the ceiling and the authority. Default: none. */
+    readonly builtins?: readonly AgentBuiltin[];
+    /** Names the workspace every run renders in place of the active one, until the thread's own `switch`. Default: the active workspace. */
+    readonly workspace?: string;
 }
 
 /**
@@ -1393,9 +1580,9 @@ export declare interface AgentPrompt {
 
 /** Validates and projects agent prompts at the run's `prompt` option and a page's request body. */
 export declare const agentPromptContract: ContractInterface<Readonly<{
-content: string;
+    content: string;
 } & {
-images?: readonly string[];
+    images?: readonly string[];
 }>>;
 
 /**
@@ -1584,16 +1771,22 @@ export declare interface AgentQueueOptions {
  *   the message `unknown <category>: <name>` when it is absent — an unknown name in a
  *   rehydrated job is a programmer / config error that must fail loudly at build time, never
  *   silently resolve to `undefined` and run an agent missing a dependency.
- * - **`build` rehydrates.** Resolve the job's `provider`; assemble a fresh
- *   {@link ToolManager} from the `tools` names, which refuses with `code: 'REGISTRY'` when the job
- *   names no `authority`; rebuild the token `budget` from its
- *   ceiling (`createTokenBudget({ max })`); resolve the optional `authority` /
+ * - **`build` rehydrates.** Refuse with `code: 'REGISTRY'` a job `agentJobContract` refuses,
+ *   its faults under `context.faults`, and a job `collectJobRefusals` refuses, its lines under
+ *   `context.refusals`: tools or built-ins with no `authority`, a `builtins` list an agent
+ *   refuses, and a built-in the job's `tools` also name. Then resolve the job's `provider`;
+ *   assemble a fresh {@link ToolManager} from the `tools` names; rebuild the token `budget` from
+ *   its ceiling (`createTokenBudget({ max })`); resolve the optional `authority` /
  *   `scheduler` names; construct the {@link Agent} with `system` / `limit` / `timeout` /
  *   the threaded `signal`; seed its context with the job's `messages`; return it. The
  *   `signal` is the queue attempt's / runner unit's cancel, so a bounded abort propagates
  *   into the agent (which commits a partial — the job's `partial` policy then
- *   decides success vs. retry). A job `limit` that is not a positive safe integer throws an
- *   {@link AgentError} carrying `code: 'LIMIT'` from the agent's construction.
+ *   decides success vs. retry). A job is a record, so a malformed `limit`, `timeout`, `budget`,
+ *   seed role, or `builtins` list refuses as one, with `code: 'REGISTRY'`.
+ * - **A job holds what it names.** A job with a `scope` gets the registry's `skills`, `memos`, and
+ *   `workspaces` managers, which every scoped job shares, and a scope named `job` built from its
+ *   three lists; a job with no `scope` gets none of them. Its `workspace` and `builtins` pass to
+ *   the agent.
  * - **Event-free.** A pure resolver — no Emitter, no events.
  *
  * @example
@@ -1675,8 +1868,7 @@ export declare interface AgentRegistryInterface {
      * @param input - The serializable {@link AgentJobInput} to rehydrate
      * @param signal - An optional cancel threaded into the agent (a queue / runner abort)
      * @returns The ready agent, its context seeded with the job's messages
-     * @throws {AgentError} Thrown when a referenced provider, tool, authority, or scheduler name is unregistered, or the job names `tools` and no `authority` (`code: 'REGISTRY'`), or when the job's `limit` is not a nonnegative safe integer (`code: 'LIMIT'`)
-     * @throws {ConversationError} Thrown when a seed message's role is not a `ConversationRole` (`code: 'ROLE'`), before the agent is returned
+     * @throws {AgentError} Thrown when the job holds a member `AgentJobInput` does not declare or a member of the wrong shape, a bound out of range or a seed role that is not a `ConversationRole` included, when the job names `tools` or `builtins` and no `authority`, when its `builtins` repeats a name, lists `unload` without `load`, or names a tool its `tools` hold, or when a referenced provider, tool, authority, or scheduler name is unregistered (`code: 'REGISTRY'`)
      */
     build(input: AgentJobInput, signal?: AbortSignal): AgentInterface;
 }
@@ -1694,7 +1886,10 @@ export declare interface AgentRegistryInterface {
  * build (minted by the seeded `add`), so concurrent builds never collide, and the store
  * accumulates one snapshot per built agent that later calls `save`. Persistence
  * stays caller-triggered (`open` / `save`) — `build` never hydrates, so `build` stays
- * synchronous. Omitted ⇒ every built agent gets a registry-only manager.
+ * synchronous. Omitted ⇒ every built agent gets a registry-only manager. `skills`, `memos`, and
+ * `workspaces` are pre-built managers every job with a `scope` shares, each read through that
+ * job's lists; a job with no `scope` is passed none of them. Omitted ⇒ a scoped job's agent
+ * creates an empty one.
  */
 export declare interface AgentRegistryOptions {
     readonly providers: Readonly<Record<string, ProviderInterface>>;
@@ -1702,6 +1897,12 @@ export declare interface AgentRegistryOptions {
     readonly authorities?: Readonly<Record<string, AuthorityInterface>>;
     readonly schedulers?: Readonly<Record<string, SchedulerInterface>>;
     readonly store?: ConversationStoreInterface;
+    /** Holds the skill registry every job with a `scope` shares, read through its `skills` list. */
+    readonly skills?: SkillManagerInterface;
+    /** Holds the memo set every job with a `scope` shares, read and written through its `memos` list. */
+    readonly memos?: MemoManagerInterface;
+    /** Holds the workspace registry every job with a `scope` shares, read through its `workspaces` list. */
+    readonly workspaces?: WorkspaceManagerInterface;
 }
 
 /**
@@ -1830,17 +2031,22 @@ export declare interface AgentRunnerOptions {
 }
 
 /**
- * Carries overrides for one call to the `generate` or `stream` method of an {@link AgentInterface}. Each member overrides the matching {@link AgentOptions} value, while `signal` composes with the construction signal, `conversation` binds the run to one conversation, and `prompt` adds the run's user turn to it.
+ * Carries overrides for one call to the `generate` or `stream` method of an {@link AgentInterface}. Each member overrides the matching {@link AgentOptions} value, while `signal` composes with the construction signal, `conversation` binds the run to one conversation, `prompt` adds the run's user turn to it, and `scope` narrows the context scope for the run.
  *
  * @remarks
+ * An own enumerable member this type does not declare refuses the call synchronously with a
+ * `ContractError` coded `'structure'`, before the run changes anything, and a declared member
+ * holding `undefined` reads as omitted.
  * Every member is optional and resolved independently, so an omitted member leaves the
  * agent's constructed value in force and a caller that passes no options runs exactly the
  * agent it configured. `think` / `schema` ride through to the provider as
  * {@link ProviderStreamOptions}; `limit` / `timeout` / `budget` / `allowance` replace their construction
  * defaults for this run only; `signal` composes with the constructed `signal` (both fold into
- * the run's bound abort) rather than replacing it. `conversation` and `prompt` have no construction
- * counterpart: `conversation` names the conversation the run binds in place of the one active at
- * the call, and `prompt` is the user turn the run appends to that conversation before it starts.
+ * the run's bound abort) rather than replacing it. `conversation`, `prompt`, and `scope` have no
+ * construction default: `conversation` names the conversation the run binds in place of the one
+ * active at the call, `prompt` is the user turn the run appends to that conversation before it
+ * starts, and the run `scope` narrows the construction `scope`, the context scope, at each turn of
+ * the run and never replaces it.
  * Nothing here mutates the agent — the next run reads the construction defaults again.
  */
 export declare interface AgentRunOptions {
@@ -1910,6 +2116,25 @@ export declare interface AgentRunOptions {
      * run reads its request from the conversation's tail.
      */
     readonly prompt?: AgentPrompt;
+    /**
+     * Narrows this run's ceiling: each turn reads the context scope intersected with it, list by
+     * list, one time, and each build site of the run filters instructions, skills, memos, files, and
+     * workspaces by the same intersection. Its `select` runs in place of the context scope's. A later
+     * `context.apply` still reaches the run at its next turn, and never past this scope, so a run
+     * that needs a wider scope than the context scope needs another agent. The `stream` or
+     * `generate` call throws a `ContractError` coded `'placement'` synchronously when the value does
+     * not implement {@link ScopeInterface}, before the run appends its prompt or starts. Omitted ⇒ the
+     * context scope alone.
+     */
+    readonly scope?: ScopeInterface;
+    /**
+     * Replaces {@link AgentOptions.workspace} for this run: the id of the workspace the run renders in
+     * place of the active one, from its first request, until the thread's own `switch`, within the
+     * ceiling. The `stream` or `generate` call throws a `ContractError` coded `'placement'`
+     * synchronously when the value is not a string, before the run appends its prompt or starts.
+     * Omitted ⇒ the agent's value.
+     */
+    readonly workspace?: string;
 }
 
 /**
@@ -2133,6 +2358,22 @@ export declare interface ApproverInterface {
     answer(answer: AgentAnswer): boolean;
 }
 
+/**
+ * Matches a text that is blank: empty after white space and default-ignorable code points, such
+ * as U+3164, are removed, frozen.
+ */
+export declare const ARGUMENT_BLANK_PATTERN: Readonly<RegExp>;
+
+/**
+ * Matches one control, format, line-separator, or paragraph-separator code point — the class
+ * `renderArguments` encodes and a memo's one-line name and description may not hold, frozen.
+ *
+ * @remarks
+ * Not global, so a `test` call keeps no state between calls; a global replace builds its own
+ * global copy from `source`.
+ */
+export declare const ARGUMENT_CONTROL_PATTERN: Readonly<RegExp>;
+
 /**
  * Arms signal propagation to a byte reader and returns the controller that removes the listener.
  *
@@ -2272,6 +2513,9 @@ export declare class Authority implements AuthorityInterface {
  */
 export declare const AUTHORITY_NOTES: AuthorityNote;
 
+/** Lists the members `AuthorityOptions` declares, frozen — the keys the `Authority` constructor admits. */
+export declare const AUTHORITY_OPTION_KEYS: readonly ["rules", "fallback", "ask"];
+
 /**
  * Carries what an {@link AuthorityInterface} evaluates for one tool call — the call under
  * consideration.
@@ -2377,6 +2621,9 @@ export declare interface AuthorityRule {
 /** Names an authority's verdict on one tool call. */
 export declare type AuthorityVerdict = 'allow' | 'ask' | 'deny';
 
+/** Lists the members `ContextBuildOptions` declares, frozen — the keys the `build` method of an `AgentContext` admits. */
+export declare const BUILD_OPTION_KEYS: readonly ["selection", "scope", "disclosure", "switchable"];
+
 /**
  * Merges the results of a judge request's calls into one result.
  *
@@ -2690,6 +2937,68 @@ export declare function buildRequestMessage(request: Message, records: string):
  */
 export declare function buildSummaryMessage(section: Section): Message;
 
+/**
+ * Caps each built-in argument in code points, as the built-in argument shapes count them — a `name`
+ * (a skill name, a memo name, or a workspace id), a memo `description`, and a memo `content` — and
+ * the `candidates` one refusal lists, frozen.
+ */
+export declare const BUILTIN_LIMITS: Readonly<{
+    name: number;
+    description: number;
+    content: number;
+    candidates: number;
+}>;
+
+/**
+ * Holds the texts the built-ins return on success — `loaded`, `unloaded`, `remembered`, and
+ * `switched` — frozen.
+ *
+ * @remarks
+ * `loaded`, `unloaded`, and `switched` are the texts the conversation's stored tool messages are
+ * matched against to derive what a run shows, so each is one fixed constant. A stored message
+ * counts only under a call to a built-in the run enables.
+ */
+export declare const BUILTIN_NOTES: BuiltinNote;
+
+/**
+ * Declares each built-in tool's model-facing description and annotations, keyed by its
+ * {@link AgentBuiltin} name, frozen.
+ *
+ * @remarks
+ * `memo` is `pure` and `untrusted`, because it returns memo text a model can have written;
+ * `remember` is `consequential`, so an `allow` verdict becomes an `ask`. A run's own tools and the
+ * definitions `collectBuiltinDefinitions` returns both read their text and annotations here.
+ */
+export declare const BUILTIN_TOOLS: Readonly<Record<AgentBuiltin, Readonly<{
+    description: string;
+    annotations?: ToolAnnotations;
+}>>>;
+
+/** Holds the model-facing texts the built-ins return on success. */
+export declare interface BuiltinNote {
+    readonly loaded: string;
+    readonly unloaded: string;
+    readonly remembered: string;
+    readonly switched: string;
+}
+
+/**
+ * Pairs each built-in's argument shape, which its tool's door compiles, with its compiled contract,
+ * keyed by its {@link AgentBuiltin} name, frozen.
+ *
+ * @remarks
+ * The one map from a built-in to its arguments: `createBuiltinTool` builds the door from `shape`,
+ * and `collectBuiltinDefinitions` and `collectDisclosure` read `contract`, so the advertised
+ * parameters, the door, and the derivation admit by one rule. The record declares no shape: each
+ * `shape` is a reference to the one `shapers.ts` declares, held beside the contract compiled from
+ * it, because the tool door takes a shape and the derivation takes a compiled contract. The record
+ * is data, as the rest of this file is.
+ */
+export declare const builtinToolContracts: Readonly<Record<AgentBuiltin, Readonly<{
+    shape: ContractShape;
+    contract: ContractInterface<Readonly<Record<string, unknown>>>;
+}>>>;
+
 /**
  * Buffers chunks in a minimal unbounded async channel — the eager pump writes them in (`push`)
  * and ends it (`close` / `fail`) regardless of consumption, while a consumer reads them back live
@@ -2875,6 +3184,9 @@ export declare class Classifier implements ClassifierInterface {
     classification(): LedgerClassification;
 }
 
+/** Lists the members `ClassifierOptions` declares, frozen — the keys the `Classifier` constructor admits. */
+export declare const CLASSIFIER_OPTION_KEYS: readonly ["strict", "conversation", "judge", "questions", "topics", "thresholds", "assign", "entities", "correction", "scheduler"];
+
 /**
  * Carries what became of one filing question: its judgment key, its phase, its outcome, and the time spent resolving it.
  *
@@ -3040,6 +3352,61 @@ export declare interface CodedErrorOptions {
  */
 export declare function collectAmendments(input: LedgerProjectionInput, byId: ReadonlyMap<string, Message>, live: readonly string[]): readonly LedgerAmendment[];
 
+/**
+ * Collects the definitions of the tools an agent serves itself, as a run advertises them.
+ *
+ * @remarks
+ * Each definition carries the name, description, and annotations `BUILTIN_TOOLS` declares and the
+ * parameters of the built-in's compiled contract in `builtinToolContracts`, in the order `builtins` lists them, so
+ * it equals the definition of the tool `createBuiltinTool` creates. A relay server lists these
+ * among its declared definitions to forward a page's built-ins. A name that is no built-in
+ * contributes nothing.
+ *
+ * @param options - The agent options whose `builtins` to project
+ * @returns The definitions, empty when `builtins` is absent
+ *
+ * @example
+ * ```ts
+ * collectBuiltinDefinitions({ builtins: ['load', 'unload'] }).map((definition) => definition.name) // ['load', 'unload']
+ * ```
+ */
+export declare function collectBuiltinDefinitions(options: Pick<AgentOptions, 'builtins'>): readonly ToolDefinition[];
+
+/**
+ * Collects the loaded skills and the selected workspace a conversation's stored built-in calls
+ * record, counting only the built-ins a run enables.
+ *
+ * @remarks
+ * Pure. It reads each section's retained originals, oldest first, then the live tail, and pairs
+ * each tool message with the call that owns it through {@link collectToolGroups} and
+ * {@link findToolCall}. It then folds the pairs in message order: a `load` whose message content
+ * equals `BUILTIN_NOTES.loaded` adds its `skill`, an `unload` with `BUILTIN_NOTES.unloaded` removes
+ * it, and a `switch` with `BUILTIN_NOTES.switched` selects its `workspace`. Each call's arguments
+ * are admitted through the built-in's contract in `builtinToolContracts`, lossless repairs
+ * included, as its tool's door admits them, so a `{ skill: 1 }` the door repaired to `'1'` counts
+ * as `'1'`; arguments the contract refuses change nothing. A skill loaded again while shown keeps
+ * its place, and one loaded again after its unload goes last. Any other message and a denied or
+ * refused call change nothing. The result holds `workspace` only when a switch succeeded.
+ *
+ * A record counts only while its built-in is in `builtins`, so a host tool that holds a built-in's
+ * name on a run that does not enable it shows nothing; with none of `load`, `unload`, and `switch`
+ * enabled, nothing is read. A stored record cannot tell its writer, so one a host tool wrote under a
+ * built-in's name while that built-in was off counts after a run enables it, bounded by the registry
+ * and the ceiling as every record is.
+ *
+ * @param conversation - The conversation whose stored messages record the calls
+ * @param builtins - The built-ins the run enables
+ * @returns The skills in load order and the last selected workspace
+ *
+ * @example
+ * ```ts
+ * import { collectDisclosure, createConversation } from '@orkestrel/agent'
+ *
+ * collectDisclosure(createConversation(), ['load', 'unload']) // { skills: [] }
+ * ```
+ */
+export declare function collectDisclosure(conversation: Pick<ConversationInterface, 'sections' | 'messages'>, builtins: readonly AgentBuiltin[]): AgentDisclosure;
+
 /**
  * Collects whole exchanges, joining every exchange spanned by a tool group.
  *
@@ -3079,6 +3446,28 @@ export declare function collectExchanges(messages: readonly Message[]): Readonly
  */
 export declare function collectImageData(files: readonly FileInterface[]): readonly string[];
 
+/**
+ * Collects the refusals a job the contract admitted would meet at its build: tools or built-ins with
+ * no authority, a `builtins` list `requireBuiltins` refuses, and a built-in its own `tools` name.
+ *
+ * @remarks
+ * Each line names the member first, then the refusal and its remedy. The `builtins` line of a list
+ * `requireBuiltins` refuses carries that error's message; a job's tool manager holds exactly its
+ * `tools`, so a built-in its `tools` list also names is the name a manager would already hold.
+ * `AgentRegistry.build` refuses a job with any line, and `scanJobTree` refuses each such job of a
+ * tree before anything spawns.
+ *
+ * @param job - The `tools`, `builtins`, and `authority` of a job `agentJobContract` admitted
+ * @returns One line a refusal, in member order; empty when the job builds
+ *
+ * @example
+ * ```ts
+ * collectJobRefusals({ provider: 'main', tools: ['search'] })
+ * // ["authority: a job that names tools or builtins and no authority cannot run them; add authority: 'NAME' to the job and register that NAME under authorities"]
+ * ```
+ */
+export declare function collectJobRefusals(job: Pick<AgentJobInput, 'tools' | 'builtins' | 'authority'>): readonly string[];
+
 /**
  * Captures source bytes and direct amendment edges for a held window.
  * @param messages - Current stored messages
@@ -3271,6 +3660,9 @@ export declare function collectToolGroups(messages: readonly Message[]): Readonl
  */
 export declare function collectWriteSupersessions(messages: readonly Message[], findings: readonly LedgerLookupFinding[]): ReadonlyMap<string, readonly string[]>;
 
+/** Lists the members `CompactOptions` declares, frozen — the keys the `compact` method of a `Conversation` admits. */
+export declare const COMPACT_OPTION_KEYS: readonly ["keep", "sections", "signal"];
+
 /**
  * Configures one {@link ConversationInterface.compact} call — the retained-tail size, the
  * `sections` cap, or both, overridden for one fold.
@@ -3316,6 +3708,26 @@ export declare interface CompactOptions {
  */
 export declare function computeLedgerChecksum(text: string): string;
 
+/**
+ * Computes the tokens loading a skill adds: its body, and the definitions it names beyond an advertised set.
+ *
+ * @remarks
+ * The body is the text `renderSkillBody` renders, priced at `scale`, and a blank `content` renders
+ * no body. The caller passes the definitions the skill names that the turn does not advertise,
+ * priced as {@link computeToolPrice} prices an addition.
+ *
+ * @param skill - The skill to load
+ * @param added - The definitions the skill names that the advertised set leaves out
+ * @param calibrated - The definitions the gauge's overhead priced
+ * @param gauge - The gauge's scale and overhead
+ * @returns The tokens the load adds
+ * @example
+ * ```ts
+ * computeSkillPrice({ name: 'refunds', content: 'Check the order first.' }, [], [], { scale: 1, overhead: 0 }) // 9
+ * ```
+ */
+export declare function computeSkillPrice(skill: Pick<Skill, 'name' | 'content'>, added: readonly ToolDefinition[], calibrated: readonly ToolDefinition[], gauge: LedgerGauge): number;
+
 /**
  * Computes the completion tokens attributable to a message's thinking.
  *
@@ -3336,6 +3748,78 @@ export declare function computeLedgerChecksum(text: string): string;
  */
 export declare function computeThinking(message: Pick<Message, 'thinking' | 'content' | 'calls'>, completion: number): number;
 
+/**
+ * Computes the tokens one estimate unit of a definition costs beyond the calibrated set.
+ *
+ * @remarks
+ * The larger of `scale` and the calibrated set's overhead per estimate unit, or `scale` for an
+ * empty set or one that estimates 0. A set's estimate is `estimateTokens` over its JSON text.
+ *
+ * @param calibrated - The definitions the gauge's overhead priced
+ * @param gauge - The gauge's scale and overhead
+ * @returns The tokens one estimate unit of a definition costs
+ * @example
+ * ```ts
+ * computeToolDensity([], { scale: 1.1, overhead: 400 }) // 1.1
+ * ```
+ */
+export declare function computeToolDensity(calibrated: readonly ToolDefinition[], gauge: LedgerGauge): number;
+
+/**
+ * Computes what a call's advertised set spares of the calibrated overhead and adds beyond it.
+ *
+ * @remarks
+ * Definitions compare by their JSON text, so a definition replaced under its name by another text
+ * is both left out and added. An empty advertised set spares the whole overhead. Otherwise the
+ * calibrated definitions the call leaves out spare the lower of `scale` and the calibrated set's
+ * overhead per estimate unit, times their estimate, so a credit never exceeds their proportional
+ * share of the overhead; the definitions it advertises beyond the calibrated set add
+ * {@link computeToolDensity}, the higher of the two, times theirs. A set's estimate is
+ * `estimateTokens` over its JSON text, 0 for an empty set. The call's price is
+ * `overhead - spared + added`.
+ *
+ * @param calibrated - The definitions the gauge's overhead priced
+ * @param advertised - The definitions the call advertises
+ * @param gauge - The gauge's scale and overhead
+ * @returns The tokens the call spares and adds
+ * @example
+ * ```ts
+ * computeToolPrice([], [], { scale: 1.1, overhead: 400 }) // { spared: 400, added: 0 }
+ * ```
+ */
+export declare function computeToolPrice(calibrated: readonly ToolDefinition[], advertised: readonly ToolDefinition[], gauge: LedgerGauge): Required<Pick<GaugeCall, 'spared' | 'added'>>;
+
+/** Lists the members `AgentContextOptions` declares, frozen — the keys the `AgentContext` constructor admits. */
+export declare const CONTEXT_OPTION_KEYS: readonly ["system", "tools", "instructions", "skills", "memos", "workspaces", "scope", "conversations", "select"];
+
+/**
+ * Selects what one `build` call renders.
+ *
+ * @remarks
+ * `selection` holds the conversation part in place of the active conversation's `view()`. `scope`
+ * holds a run's scope: the build filters by the context scope intersected with it, list by list,
+ * so a run scope narrows the context scope and never widens it. `disclosure` names the skills
+ * whose bodies close the `system` message and the workspace to render in place of the active one,
+ * each kept only where its registry holds it and that intersection admits it. `switchable` lists
+ * the admitted workspace ids in the context message, as an agent run does while it advertises
+ * `switch`.
+ *
+ * @example
+ * ```ts
+ * context.build({ selection: { messages: conversation.view(), judgments: [] }, scope })
+ * ```
+ */
+export declare interface ContextBuildOptions {
+    /** Holds the messages that replace `view()`; omitted ⇒ the active conversation's `view()`. */
+    readonly selection?: Selection;
+    /** Holds a run's scope; the build filters by the context scope intersected with it. */
+    readonly scope?: ScopeInterface;
+    /** Holds the skills whose bodies close the system message and the workspace to render. Default: no body, the active workspace. */
+    readonly disclosure?: AgentDisclosure;
+    /** If `true`, the context message lists the admitted workspace ids; if `false`, it lists none. Default: `false`. */
+    readonly switchable?: boolean;
+}
+
 /**
  * Reports a context snapshot that `isMemoSnapshot` refuses, thrown by the construction of a
  * {@link import('./memos/MemoManager.js').MemoManager} before it seats any state or by a memo store,
@@ -3505,6 +3989,15 @@ export declare class Conversation implements ConversationInterface {
     snapshot(): ConversationSnapshot;
 }
 
+/** Lists the members `ConversationInput` declares, frozen — the keys the `add` method of a `ConversationManager` admits. */
+export declare const CONVERSATION_INPUT_KEYS: readonly ["id", "summarize", "keep", "sections", "cumulative", "on", "error", "snapshot"];
+
+/** Lists the members `ConversationManagerOptions` declares, frozen — the keys the `ConversationManager` constructor admits. */
+export declare const CONVERSATION_MANAGER_KEYS: readonly ["summarize", "keep", "sections", "store"];
+
+/** Lists the members `ConversationOptions` declares, frozen — the keys the `Conversation` constructor admits. */
+export declare const CONVERSATION_OPTION_KEYS: readonly ["id", "on", "error", "summarize", "keep", "sections", "cumulative", "snapshot"];
+
 /**
  * Names the framing label the `view()` method of a {@link ConversationInterface} prefixes onto the
  * summary of each compacted section so a small model reads it as a condensed recap of earlier turns — the lean
@@ -3553,7 +4046,8 @@ export declare const CONVERSATION_ROLES: readonly ["user", "assistant", "tool"];
  * `'SUMMARY'`. A stored message plays a `ConversationRole`: `add` refuses any other role with
  * `'ROLE'` before it stores any message of the batch, a hydrating snapshot that holds one throws
  * `'ROLE'`, and an agent's selection that holds one becomes a `'ROLE'` fault. `add` refuses an input
- * whose other members fail `isMessageInput` with `'MESSAGE'`, its `context` holding the `faults`,
+ * that is not a plain record, before its role is read, or whose other members fail `isMessageInput`
+ * with `'MESSAGE'`, its `context` holding the `faults`,
  * before it stores any message of the batch. A hydrating snapshot that fails
  * `isConversationSnapshot` or repeats an id, and a store row or written snapshot that does, throw
  * `'SNAPSHOT'`; a judgment the guard admits but JSON cannot carry still throws `'JUDGMENT'`. A
@@ -3561,7 +4055,7 @@ export declare const CONVERSATION_ROLES: readonly ["user", "assistant", "tool"];
  * {@link isConversationError} and branch on `error.code`.
  */
 export declare class ConversationError extends Error {
-    /** Names the machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a `sections` cap that is not a positive safe integer, or a cap combined with `cumulative`; `'JUDGMENT'`: a judgment or judge request that is not JSON; `'KEEP'`: a `keep` that is not a nonnegative safe integer; `'SUMMARY'`: a summarizer digest whose trimmed text is empty; `'ROLE'`: a stored or selected message whose role is not a `ConversationRole`; `'MESSAGE'`: a message input whose other members fail `isMessageInput`; `'SNAPSHOT'`: a snapshot that fails `isConversationSnapshot` or repeats an id; `'ID'`: a manager's `add` of an id it already holds. */
+    /** Names the machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a `sections` cap that is not a positive safe integer, or a cap combined with `cumulative`; `'JUDGMENT'`: a judgment or judge request that is not JSON; `'KEEP'`: a `keep` that is not a nonnegative safe integer; `'SUMMARY'`: a summarizer digest whose trimmed text is empty; `'ROLE'`: a stored or selected message whose role is not a `ConversationRole`; `'MESSAGE'`: a message input that is not a plain record or whose other members fail `isMessageInput`; `'SNAPSHOT'`: a snapshot that fails `isConversationSnapshot` or repeats an id; `'ID'`: a manager's `add` of an id it already holds. */
     readonly code: ConversationErrorCode;
     /** Holds the values that locate the failure, such as the `question` id of a malformed question, or `undefined` when none were supplied. */
     readonly context: Readonly<Record<string, unknown>> | undefined;
@@ -4870,6 +5364,30 @@ export declare function createApprover(): ApproverInterface;
  */
 export declare function createAuthority(options: AuthorityOptions): AuthorityInterface;
 
+/**
+ * Creates the tool a run serves for one built-in: its description and annotations from
+ * `BUILTIN_TOOLS`, its argument shape from `builtinToolContracts`, and the given handler.
+ *
+ * @remarks
+ * The tool's door refuses a missing, empty, over-long, or extra argument before the handler runs,
+ * and repairs a value that converts to a string without loss, such as a number, so the handler
+ * reads only arguments the shape admits. Its definition equals the one `collectBuiltinDefinitions`
+ * returns for the same name.
+ *
+ * @param name - The built-in to create
+ * @param execute - The handler the door hands admitted arguments to
+ * @returns The tool
+ *
+ * @example
+ * ```ts
+ * import { createBuiltinTool } from '@orkestrel/agent'
+ *
+ * const memo = createBuiltinTool('memo', (args) => `read ${String(args.name)}`)
+ * memo.annotations // { pure: true, untrusted: true }
+ * ```
+ */
+export declare function createBuiltinTool(name: AgentBuiltin, execute: ToolOptions['execute']): ToolInterface;
+
 /**
  * Creates an empty unbounded async channel — a {@link ChannelInterface} a producer writes
  * values into (`push`) and ends (`close` / `fail`) regardless of consumption, while a
@@ -5433,6 +5951,34 @@ export declare function createThinkSplitter(): ThinkSplitterInterface;
  */
 export declare function cutListing(entries: readonly string[], room: number, kind?: 'older' | 'more', first?: boolean): string;
 
+/**
+ * Cuts the workspace text a calibration sample adds over its head to a number of characters, or
+ * returns `undefined` when the sample adds anything else.
+ *
+ * @remarks
+ * The head and the shown sample are what a context's `build` returns for an empty turn without and
+ * with the workspace: the shown sample holds the head's messages with the workspace section appended
+ * to the context message, or one context message added where the head holds none. The cut keeps the
+ * first `limit` characters of that added text and every other message as the sample holds it. A
+ * sample whose messages differ from the head's in any other way, or that adds no text, returns
+ * `undefined`.
+ *
+ * @param head - The head built with no workspace
+ * @param shown - The head built with the workspace a request renders
+ * @param limit - The characters of added text to keep
+ * @returns The cut sample, or `undefined` when the sample adds no trailing text to one message
+ *
+ * @example
+ * ```ts
+ * import { cutWorkspaceSample } from '@orkestrel/agent'
+ *
+ * const head = [{ id: 's', role: 'system', content: 'Serve the desk.' }] as const
+ * const shown = [...head, { id: 'c', role: 'user', content: '## Workspace\n\nFile: a.md' }] as const
+ * cutWorkspaceSample(head, shown, 12)?.[1]?.content // '## Workspace'
+ * ```
+ */
+export declare function cutWorkspaceSample(head: readonly Message[], shown: readonly Message[], limit: number): readonly Message[] | undefined;
+
 /**
  * Backs a {@link ConversationStoreInterface} with one table of the `databases` layer — a
  * conversation's durable state is a row holding the snapshot as one opaque JSON column, narrowed
@@ -5636,7 +6182,7 @@ export declare const DEFAULT_CONVERSATION_KEEP = 0;
 export declare const DEFAULT_LEDGER_LIMIT = 8;
 
 /**
- * Supplies the default prompt and tail shares.
+ * Supplies the default prompt, tail, and skills shares.
  */
 export declare const DEFAULT_LEDGER_SHARE: LedgerShare;
 
@@ -5681,6 +6227,28 @@ export declare const DEFAULT_RELAY_LIMIT = 1048576;
  */
 export declare function denyCall(call: ToolCall, reason: string | undefined): ToolResult;
 
+/**
+ * Returns the refusal that names a subject and at most `BUILTIN_LIMITS.candidates` of the names a
+ * caller can use.
+ *
+ * @remarks
+ * The subject reads after "No", so it names what the caller may use, such as `'skill you can load'`.
+ * The text echoes no argument, so an absent name and a name outside the ceiling read byte for byte
+ * the same. Each name is JSON-encoded and capped by `preview`, in the order given. Past the cap one
+ * fixed sentence sends the reader to the index in its prompt.
+ *
+ * @param subject - What the caller may name, such as `'skill you can load'`
+ * @param names - The names the caller can use, in registry order
+ * @returns The refusal text
+ *
+ * @example
+ * ```ts
+ * describeCandidates('skill you can load', ['refunds', 'billing'])
+ * // 'No skill you can load has that name. Use one of: "refunds", "billing".'
+ * ```
+ */
+export declare function describeCandidates(subject: string, names: readonly string[]): string;
+
 /**
  * Describes why a judge question refuses, in the text both of its doors throw.
  *
@@ -5748,9 +6316,10 @@ export declare const DETERMINISTIC_JUDGE_ERROR: RegExp;
  * Digests tool definitions as the JSON a provider request carries them, in order.
  *
  * @remarks
- * A ledger stores this digest with its gauge, so a hydrate reuses the gauge only for the same
- * definitions: an added, removed, reordered, or edited definition changes the digest. The digest is
- * a {@link computeLedgerChecksum} checksum and makes no security claim.
+ * A ledger stores this digest with its gauge and compares it at a hydrate and at each `respond`
+ * call, so it reuses the gauge only for the same definitions: an added, removed, reordered, or
+ * edited definition changes the digest. The digest is a {@link computeLedgerChecksum} checksum and
+ * makes no security claim.
  *
  * @param definitions - The tool definitions, as a tool manager's `definitions` method returns them
  * @returns The 16-digit hexadecimal digest, or undefined when JSON cannot render the definitions
@@ -5939,6 +6508,34 @@ export declare interface FailureRead {
     readonly cause?: unknown;
 }
 
+/**
+ * Returns the definitions a turn advertises from the allow-list, the registered skills, and the
+ * shown skills.
+ *
+ * @remarks
+ * The allow-list admits first, as `filterAllowList` does. When no skill is passed, or an allow-list
+ * admits no `load` definition, the admitted list returns as it is. Otherwise a tool any registered
+ * skill names is held back unless a shown skill names it too; `load` and `unload` are never held
+ * back. A caller passes the registered skills only while `load` is enabled, so with no allow-list a
+ * ceiling whose empty `skills` list withholds `load` from the candidates still holds the skills'
+ * tools back. Holding a tool back is presentation, never authority: a call to it is denied as
+ * outside the turn's scope.
+ *
+ * @param definitions - The candidate definitions, in advertisement order
+ * @param names - The turn's `tools` allow-list (`undefined` ⇒ all, `[]` ⇒ none)
+ * @param skills - The registered skills whose `tools` gate, or none while `load` is not enabled
+ * @param shown - The names of the skills the turn shows
+ * @returns The advertised definitions, in candidate order
+ *
+ * @example
+ * ```ts
+ * const skills = [{ id: '1', name: 'refunds', description: 'Refunds', content: '', tools: ['refund'], files: [] }]
+ * filterAdvertisedTools([{ name: 'load' }, { name: 'refund' }], undefined, skills, []) // [{ name: 'load' }]
+ * filterAdvertisedTools([{ name: 'load' }, { name: 'refund' }], undefined, skills, ['refunds']).length // 2
+ * ```
+ */
+export declare function filterAdvertisedTools(definitions: readonly ToolDefinition[], names: readonly string[] | undefined, skills: readonly Skill[], shown: readonly string[]): readonly ToolDefinition[];
+
 /**
  * Filters a list of members by a {@link import('./contexts/index.js').ScopeInterface} allow-list of keys —
  * `undefined` passes everything, `[]` passes nothing, and a non-empty list passes the listed keys
@@ -5971,16 +6568,27 @@ export declare interface FailureRead {
 export declare function filterAllowList<T>(allow: readonly string[] | undefined, members: readonly T[], key: (member: T) => string): readonly T[];
 
 /**
- * Finds the call that owns a tool message within a collected tool group.
- * @param group - The assistant leader followed by its tool results
- * @param message - The tool result to pair; distinct leader ids pair by result id when any result has one
- * @returns The call matching the result's call id, or its position when the leader repeats an id or every result lacks an id; undefined when unpaired
+ * Returns the definitions a run offers before the allow-list, without `remember` unless the
+ * ceiling's `memos` list names a memo, without `switch` unless its `workspaces` list names a
+ * workspace, and without `load` and `unload` while its `skills` list is empty.
+ *
+ * @remarks
+ * `remember` writes and `switch` selects only a name its list holds, so an absent list and an empty
+ * list each leave the built-in nothing to act on, and it is not advertised. An absent `skills` list
+ * admits every registered skill, so `load` and `unload` are withheld only when the list is empty.
+ * Every other definition keeps its place.
+ *
+ * @param definitions - The candidate definitions, in advertisement order
+ * @param ceiling - The turn's ceiling
+ * @returns The definitions, in candidate order
+ *
  * @example
  * ```ts
- * findLedgerCall(group, result)?.arguments
+ * filterBuiltinCandidates([{ name: 'memo' }, { name: 'remember' }], { memos: [] }) // [{ name: 'memo' }]
+ * filterBuiltinCandidates([{ name: 'memo' }, { name: 'remember' }], { memos: ['tone'] }).length // 2
  * ```
  */
-export declare function findLedgerCall(group: readonly Message[], message: Message): ToolCall | undefined;
+export declare function filterBuiltinCandidates(definitions: readonly ToolDefinition[], ceiling: ScopeFilter): readonly ToolDefinition[];
 
 /**
  * Finds the first cut in a range whose probe returns a value, by bisection.
@@ -6000,6 +6608,18 @@ export declare function findLedgerCall(group: readonly Message[], message: Messa
  */
 export declare function findLedgerCut<T>(low: number, high: number, probe: (cut: number) => T | undefined, found?: T): T | undefined;
 
+/**
+ * Finds the call that owns a tool message within a collected tool group.
+ * @param group - The assistant leader followed by its tool results, as {@link collectToolGroups} returns it
+ * @param message - The tool result to pair; distinct leader ids pair by result id when any result has one
+ * @returns The call matching the result's call id, or its position when the leader repeats an id or every result lacks an id; undefined when unpaired
+ * @example
+ * ```ts
+ * findToolCall(group, result)?.arguments
+ * ```
+ */
+export declare function findToolCall(group: readonly Message[], message: Message): ToolCall | undefined;
+
 /**
  * Fits the marginal tokens one estimate unit adds within a request.
  *
@@ -6082,6 +6702,9 @@ export declare class Gauge implements GaugeInterface {
     observe(calls: readonly GaugeCall[], reply?: GaugeCall): void;
 }
 
+/** Lists the members `GaugeOptions` declares, frozen — the keys the `Gauge` constructor admits. */
+export declare const GAUGE_OPTION_KEYS: readonly ["scale", "overhead", "capacity", "predict", "replay"];
+
 /**
  * Carries one agent call as the gauge reads it.
  *
@@ -6089,9 +6712,11 @@ export declare class Gauge implements GaugeInterface {
  * `estimate` is the `estimateMessages` estimate of the call's messages. `prompt` and `completion`
  * are the tokens the provider reported, absent when it reported none. `tools` is the count of tool
  * definitions the call advertised. `spared` is the tokens of definitions it did not advertise;
- * estimated use subtracts it from overhead, floored at 0. Omission means 0. Observation rescales
- * only with exact overhead: `spared` absent or zero retains all overhead, and `spared` at or above
- * overhead retains none. A partially spared first call keeps the prior scale.
+ * estimated use subtracts it from overhead, floored at 0. `added` is the tokens of definitions it
+ * advertised beyond the calibrated set; estimated use adds it. Omission means 0 for both.
+ * Observation rescales only with exact overhead: `spared` absent or zero retains all overhead, and
+ * `spared` at or above overhead retains none. A partially spared first call, and a first call with
+ * `added` above 0, keep the prior scale.
  * `thinking` estimates the completion tokens spent on thinking from its share of the generated
  * characters, rounded to the nearest integer and capped at `completion`. With replay `'none'`,
  * the measured call uses `prompt + completion - thinking`; other policies retain the whole
@@ -6101,6 +6726,8 @@ export declare interface GaugeCall {
     readonly estimate: number;
     /** Tokens spared by tool definitions this call did not advertise. Default: 0. */
     readonly spared?: number;
+    /** Tokens of definitions this call advertised beyond the calibrated set. Default: 0. */
+    readonly added?: number;
     readonly prompt?: number;
     readonly completion?: number;
     readonly thinking?: number;
@@ -6172,7 +6799,7 @@ export declare interface GaugeInterface extends LedgerGauge {
  * `'CAPACITY'` otherwise. `replay` names the thinking the next request carries. Default: `'none'`.
  * Measured use is `prompt + completion - (thinking ?? 0)` for `'none'`, and `prompt + completion`
  * otherwise; absent completion counts as 0. Without prompt usage, use is
- * `max(0, overhead - (spared ?? 0)) + scale * estimate`.
+ * `max(0, overhead - (spared ?? 0)) + (added ?? 0) + scale * estimate`.
  * Capacity left is `max(0, capacity - used)`. The reply reserve adds recall uniform at the marginal
  * rate to the largest observed reply's `completion - (thinking ?? 0)` for every policy.
  * Without a positive reply observation, it prices the longest reply text at that rate. The room formula
@@ -6321,8 +6948,10 @@ export declare function inferStop(reason: unknown, allowance: BudgetInterface<To
  * A thin immutable value object (mirroring {@link import('@orkestrel/tool').Tool}): the
  * constructor mints a fresh `id` (`crypto.randomUUID()`), copies the input's `name` /
  * `content`, resolves `priority` to the input's value or `0`, and carries the input's
- * per-item `override` value when supplied; otherwise that property is `undefined`.
- * Never mutated after construction. An
+ * per-item `override` value when supplied; otherwise the instance owns no `override` member, so
+ * its own keys and a JSON copy carry no member holding `undefined`. The input meets its exact
+ * contract first, so a missing required member, an undeclared member, and a declared member holding
+ * `undefined` refuse with a `ContractError` coded `'structure'`. Never mutated after construction. An
  * {@link import('./InstructionManager.js').InstructionManager} keys it by `name` and
  * renders it (highest `priority` first) under its section header.
  *
@@ -6341,6 +6970,9 @@ export declare class Instruction implements InstructionInterface {
     constructor(input: InstructionInput);
 }
 
+/** Lists the members `InstructionManagerOptions` declares, frozen — the keys the `InstructionManager` constructor admits. */
+export declare const INSTRUCTION_MANAGER_KEYS: readonly ["on", "error", "format"];
+
 /**
  * Carries the minimal data to author an {@link InstructionInterface} — the `id` is minted by
  * the {@link InstructionManagerInterface} that stores it, so a caller supplies only
@@ -6360,6 +6992,29 @@ export declare interface InstructionInput {
     readonly override?: string;
 }
 
+/** Admits an instruction input exactly, and reads the faults of a refused one. */
+export declare const instructionInputContract: ContractInterface<Readonly<{
+name: string;
+content: string;
+} & {
+priority?: number;
+override?: string;
+}>>;
+
+/**
+ * Describes an instruction input exactly: a string `name` and `content`, and an optional finite
+ * `priority` and string `override`.
+ *
+ * @remarks
+ * An unknown member, a missing required member, and a declared member holding `undefined` refuse.
+ */
+export declare const instructionInputShape: ObjectShape<    {
+name: StringShape;
+content: StringShape;
+priority: OptionalShape<NumberShape>;
+override: OptionalShape<StringShape>;
+}, boolean | ContractShape>;
+
 /**
  * Represents an immutable instruction — a named directive a richer context places between the
  * system prompt and the conversation, ordered by descending {@link priority}.
@@ -6496,6 +7151,7 @@ export declare interface InstructionManagerInterface {
      *
      * @param input - One {@link InstructionInput}, or a batch
      * @returns The stored instruction, or the stored batch in input order
+     * @throws {ContractError} Thrown when an input fails `instructionInputContract`: a missing required member, an undeclared member, or a declared member holding `undefined` (`code: 'structure'`); a refused batch stores nothing
      */
     add(input: InstructionInput): InstructionInterface;
     add(inputs: readonly InstructionInput[]): readonly InstructionInterface[];
@@ -6554,6 +7210,30 @@ export declare interface InstructionManagerOptions {
     readonly format?: ContextSectionFormat<InstructionInterface>;
 }
 
+/**
+ * Intersects two scope filters list by list; an absent side constrains nothing.
+ *
+ * @remarks
+ * Pure, and it can only tighten. Each list of the result is {@link intersectKeys} over the two
+ * sides' lists, each read one time, in the order `instructions`, `skills`, `memos`, `tools`,
+ * `files`, and `workspaces`. A list neither side constrains is omitted, and every returned list is
+ * a fresh copy.
+ * `Scope.narrow`, a run's build, and a ledger's answer-pass scope compose their layers through it.
+ *
+ * @param parent - The outer filter, such as the context scope (`undefined` ⇒ no constraint)
+ * @param child - The inner filter, such as a run scope (`undefined` ⇒ no constraint)
+ * @returns The intersected filter
+ *
+ * @example
+ * ```ts
+ * import { intersectFilters } from '@orkestrel/agent'
+ *
+ * intersectFilters({ tools: ['read', 'write'] }, { tools: ['write', 'admin'], files: [] })
+ * // { tools: ['write'], files: [] }
+ * ```
+ */
+export declare function intersectFilters(parent: ScopeFilter | undefined, child: ScopeFilter | undefined): ScopeFilter;
+
 /**
  * Intersects two scope category lists under the "`undefined` is the universal set" rule — a
  * fresh copy that can only tighten, and the primitive a scope narrows through.
@@ -6585,6 +7265,43 @@ export declare function intersectKeys(parent: readonly string[] | undefined, chi
  */
 export declare const INVALID_RELAY_STATUS = 400;
 
+/**
+ * Checks whether a value names a built-in: `load`, `unload`, `memo`, `remember`, or `switch`.
+ *
+ * @param value - The unknown name candidate
+ * @returns True if the value names a built-in; false otherwise
+ *
+ * @example
+ * ```ts
+ * isAgentBuiltin('load') // true
+ * isAgentBuiltin('open') // false
+ * ```
+ */
+export declare function isAgentBuiltin(value: unknown): value is AgentBuiltin;
+
+/**
+ * Checks whether a value is an agent caller: a plain record whose own keys are exactly `workspace`
+ * and `files`, whose `workspace` is `undefined` or an object, and whose `files` is `undefined` or an
+ * array of strings.
+ *
+ * @remarks
+ * Total: each member is read once, and an omitted, inherited, or undeclared member, a throwing
+ * accessor, and a revoked `Proxy` return false rather than throw. It checks the shape a caller
+ * carries, never that `workspace` is a live workspace: a value that crossed a wire passes when it
+ * holds that shape, so accept its `workspace` only as the very instance your own registry holds
+ * under that id.
+ *
+ * @param value - The unknown caller candidate, such as `ToolContext.caller`
+ * @returns True if the value satisfies the caller contract; false otherwise
+ *
+ * @example
+ * ```ts
+ * isAgentCaller({ workspace: undefined, files: undefined }) // true
+ * isAgentCaller({ workspace: 'returns' }) // false
+ * ```
+ */
+export declare function isAgentCaller(value: unknown): value is AgentCaller;
+
 /**
  * Narrows an unknown caught value to an {@link AgentError} through its identity brand and declared members, so a `catch`
  * can branch on its `code`.
@@ -7027,13 +7744,17 @@ export declare function isMemoSnapshot(value: unknown): value is MemoSnapshot;
 export declare function isMessage(value: unknown): value is Message;
 
 /**
- * Checks whether a value is a message input a conversation can store: a string `content`, and `calls`,
- * `call`, `images`, and `thinking` absent or of their declared types.
+ * Checks whether a value is a message input a conversation can store: a `ConversationRole`, a string
+ * `content`, and `calls`, `call`, `images`, and `thinking` absent or of their declared types.
  *
  * @remarks
- * A hand guard, because `add` checks every message: it reads the members once and composes no record
- * guard. The role is `requireRole`'s to refuse, so its text can name the role received. Unknown members
- * are left behind by the store. An unreadable member returns false.
+ * An exact record, because a stored message is one: a value that is not a plain record, such as a
+ * class instance or an object that inherits its `role`, returns false through `recordOf`'s own plain
+ * record check, as does a member `MessageInput` does not declare or a declared optional member holding
+ * `undefined`. Each tool call crosses `isToolCall` of
+ * `@orkestrel/tool`, whose interface admits more members, so the store keeps `id`, `name`, and
+ * `arguments` and leaves the rest. `add` reads the role through `requireRole` first, so its text can
+ * name the role received. An unreadable member returns false.
  *
  * @param value - The unknown input candidate
  * @returns True if the input's members are valid; false otherwise
@@ -7043,7 +7764,7 @@ export declare function isMessage(value: unknown): value is Message;
  * isMessageInput({ role: 'user' }) // false
  * ```
  */
-export declare function isMessageInput(value: unknown): value is MessageInput;
+export declare const isMessageInput: Guard<MessageInput>;
 
 /**
  * Checks whether a value is a non-negative safe integer, `-0` included.
@@ -7130,6 +7851,30 @@ export declare function isProviderError(value: unknown): value is ProviderError;
  */
 export declare const isProviderResult: Guard<ProviderResult>;
 
+/**
+ * Checks whether a value implements `ScopeInterface`; total, each member read one time, any
+ * implementation admitted.
+ *
+ * @remarks
+ * A scope is a string `id` and `name`, each of `instructions`, `skills`, `memos`, `tools`, `files`,
+ * and `workspaces` absent or a dense array of strings, `select` absent or a function, and a `narrow`
+ * function. The guard reads each of those members one time and never calls a method. It admits
+ * unknown members, a class instance, and a transparent proxy, and returns false for a throwing
+ * getter, a revoked proxy, and any other malformed input.
+ *
+ * @param value - The value to test
+ * @returns True if `value` carries the members of a {@link ScopeInterface}; false otherwise
+ *
+ * @example
+ * ```ts
+ * import { createScope, isScope } from '@orkestrel/agent'
+ *
+ * isScope(createScope({ name: 'reader', tools: ['search'] })) // true
+ * isScope({ id: 's1', name: 'reader' }) // false
+ * ```
+ */
+export declare function isScope(value: unknown): value is ScopeInterface;
+
 /**
  * Checks whether an `unknown` is structurally a {@link Section} record — a `string` `id` and
  * `summary` beside a `messages` array of valid {@link Message} records, the per-section step of
@@ -7193,6 +7938,18 @@ export declare function isSystemOneAnswer(value: unknown): value is SystemOneAns
  */
 export declare function isSystemOneResponse(value: unknown): value is SystemOneResponse;
 
+/**
+ * Opens a job tree finding that refuses a whole job, which sets it apart from a finding that names an exceeded member.
+ *
+ * @remarks
+ * The `scanJobTree` helper writes it before the path of a job the contract refuses or a member read
+ * makes unreadable, and the `AgentFanout` class reads it to open its refusal with the rule that
+ * finding breaks. An
+ * exceeded member's finding opens with `job`, so text later in a finding cannot pass for this
+ * prefix.
+ */
+export declare const JOB_REFUSAL_PREFIX = "refused ";
+
 /**
  * Joins the reasoning a run's provider calls separated from the answer — the first call
  * seeds the accumulation, a later call appends blank-line separated so each turn's reasoning
@@ -7218,6 +7975,9 @@ export declare function isSystemOneResponse(value: unknown): value is SystemOneR
  */
 export declare function joinThinking(prior: string | undefined, next: string): string;
 
+/** Lists the members `AgentJudgeInput` declares, frozen — the keys the `AgentJudge` constructor admits. */
+export declare const JUDGE_INPUT_KEYS: readonly ["url", "path", "model", "batch", "timeout", "fetch", "headers"];
+
 /**
  * Reports a judge call cancelled by the caller's signal or its deadline, carrying the
  * {@link JudgeResult} merged from the calls that completed before the cancel and the
@@ -7728,10 +8488,10 @@ export declare class Ledger implements LedgerInterface {
      */
     constructor(provider: ProviderInterface, options: LedgerOptions);
     /**
-     * Returns the owned request engine.
-     * @returns The engine serving this conversation
+     * Returns the record of the owned request engine, which starts no run.
+     * @returns The frozen record of the agent serving this conversation
      */
-    get agent(): AgentInterface;
+    get agent(): LedgerAgentInterface;
     /**
      * Returns the owned message history.
      * @returns The history filed and served by this ledger
@@ -7744,9 +8504,10 @@ export declare class Ledger implements LedgerInterface {
     get gauge(): LedgerGauge | undefined;
     /**
      * Measures message scale and tool overhead from provider prompt usage.
-     * @param signal - The signal bounding both calibration calls; an abort rejects with its reason
+     * @param signal - The signal bounding every calibration call; an abort rejects with its reason
      * @returns The stored scale and overhead cost
-     * @throws {LedgerError} Thrown when either call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
+     * @throws {LedgerError} Thrown when a calibration call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
+     * @throws {LedgerError} Thrown when a calibration call, with the tool definitions, without them, or with the workspace text, reports a prompt over `capacity`, the head included (code `'GAUGE'`)
      * @throws {AgentError} Thrown when a request or calibration is active (code `'CONCURRENCY'`)
      */
     calibrate(signal: AbortSignal): Promise<LedgerGauge>;
@@ -7759,18 +8520,31 @@ export declare class Ledger implements LedgerInterface {
     /**
      * Appends a request and serves it, recovering an unfinished or rejected first pass with one answer pass.
      * In either pass, a call the model makes in a turn that advertises no tools runs nothing and ends the pass after that generation, whatever the agent's `limit`, and when every call of that turn failed, the ledger stores the reply without its calls: a reply with text ends the pass complete, and one without text ends it partial with empty content.
-     * A calibration call that reports no prompt usage, or a prompt usage of 0 or less, rejects with `LedgerError` code `'GAUGE'`; a provider error during calibration rejects with that error.
+     * A calibration call that reports no prompt usage, or a prompt usage of 0 or less, rejects with `LedgerError` code `'GAUGE'`; a provider error during calibration rejects with that error. A calibration call, with the tool definitions, without them, or with the workspace text, that reports a prompt over `capacity`, the head included, rejects with the same code and stores no request.
      * When the answer pass rejects, `respond` rejects with that error, and under the default `strict` a judge failure or another selection failure rejects it too. A rejection belongs to its own call: the ledger stays free, and the next call asks the judge again about whatever is still unanswered.
      * @param content - The request text
      * @param signal - The caller's cancellation signal; an abort during calibration rejects with its reason
      * @returns The final pass, the usage of every pass, and the filing attempts of this request alone
      * @throws {AgentError} Thrown when a request or calibration is active (code `'CONCURRENCY'`)
      * @throws {LedgerError} Thrown when a calibration call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
+     * @throws {LedgerError} Thrown when a calibration call, with the tool definitions, without them, or with the workspace text, reports a prompt over `capacity`, the head included (code `'GAUGE'`)
+     * @throws {LedgerError} Thrown when the answer pass prices over `capacity - predict` with its note left out, or a host act after the note grows its request past that limit (code `'OVERFLOW'`)
      * @throws {ContractError} Thrown when `signal` is defined and is not a native `AbortSignal`
      */
     respond(content: string, signal?: AbortSignal): Promise<LedgerResult>;
 }
 
+/**
+ * Lists the members the `LedgerAgentOptions` pick declares, frozen — the keys a ledger's `agent`
+ * option admits.
+ *
+ * @remarks
+ * The `Ledger` constructor passes the list to `refuseOptionKeys` of `@orkestrel/contract`, so an
+ * own enumerable member outside it, an `AgentOptions` member the pick leaves out included, refuses
+ * with a `ContractError` coded `'structure'`.
+ */
+export declare const LEDGER_AGENT_KEYS: readonly ["limit", "timeout", "on", "scheduler", "instructions", "skills", "memos", "workspaces", "strict", "authority", "builtins", "workspace"];
+
 /**
  * Lists the categories the ledger files a message under, in the order the category question
  * names them — the one list the {@link LedgerCategory} union derives from.
@@ -7780,9 +8554,22 @@ export declare const LEDGER_CATEGORIES: readonly ["fact", "rule", "correction",
 /**
  * Supplies the text of each ledger note, worded for a model that answers in its final
  * message.
+ *
+ * @remarks
+ * `overflow` names `unload` because a skill the thread shows is the room a model can give back: a
+ * successful `unload` reopens every call the room denied in that request.
  */
 export declare const LEDGER_NOTES: LedgerNote;
 
+/**
+ * Lists the members `LedgerOptions` declares, frozen — the keys the `Ledger` constructor admits.
+ *
+ * @remarks
+ * The constructor passes the list to `refuseOptionKeys` of `@orkestrel/contract`, so an own
+ * enumerable member outside it refuses with a `ContractError` coded `'structure'`.
+ */
+export declare const LEDGER_OPTION_KEYS: readonly ["judge", "system", "topics", "questions", "thresholds", "capacity", "predict", "think", "gauge", "lookups", "writes", "share", "recall", "correction", "agent", "snapshot"];
+
 /** Prefixes the key of an owner's record, which the owner's id follows. */
 export declare const LEDGER_OWNER_PREFIX = "owner:";
 
@@ -7803,6 +8590,17 @@ export declare const LEDGER_RECALL_LABELS: Readonly<{
 /** Names the key of the record that holds the rules no owner claims. */
 export declare const LEDGER_RULES_KEY = "rules";
 
+/**
+ * Sets the 3 UTF-8 bytes one UTF-16 code unit encodes to at most, the divisor that sizes the
+ * workspace text a calibration's third call carries.
+ *
+ * @remarks
+ * A tokenizer that falls back to bytes charges at most one token a byte, so workspace text cut to the
+ * capacity the call without definitions left, divided by this figure, in characters, reports at most
+ * `capacity` apart from a template's few tokens for an added message.
+ */
+export declare const LEDGER_SAMPLE_BYTES = 3;
+
 /**
  * Holds back the share of the prompt budget the scale can rise by between calibration and a
  * request's first call.
@@ -7831,6 +8629,30 @@ export declare const LEDGER_SLICE = 5;
  */
 export declare const LEDGER_WORD: RegExp;
 
+/**
+ * Holds the members of a ledger's agent a host reads: its emitter, id, status, context, and abort.
+ *
+ * @remarks
+ * It is one frozen record the ledger builds at construction, and it holds no `generate` or `stream`
+ * member, own or inherited, so the ledger's `respond` method is the only caller that starts a run on
+ * the agent: every run is a pass of the active `respond` call, on the ledger's `conversation`. The
+ * `emitter`, `id`, and `context` members are the agent's own. The `status` member reads the agent's
+ * live status, and `abort` ends the active pass partial with the reason it takes; because the caller
+ * did not abort, the ledger then runs the answer pass. To serve another conversation, build another
+ * ledger or another agent for it.
+ *
+ * @example
+ * ```ts
+ * import { createLedger } from '@orkestrel/agent'
+ *
+ * const ledger = createLedger(provider, options) // `provider` and `options` come from the host
+ * ledger.agent.emitter.on('request', (_index, request) => log(request.tools?.length))
+ * ledger.agent.status // 'idle'
+ * 'generate' in ledger.agent // false
+ * ```
+ */
+export declare type LedgerAgentInterface = Pick<AgentInterface, 'emitter' | 'id' | 'status' | 'context' | 'abort'>;
+
 /**
  * Selects the agent bounds, hooks, scheduler, and context libraries a ledger passes through to the agent it builds.
  *
@@ -7854,9 +8676,14 @@ export declare const LEDGER_WORD: RegExp;
  * unanswered as a repeat, before its `evaluate` method and with no ask, and its `ask` refuses the
  * identical twin in the same batch of a declined or unanswered ask without calling this authority's
  * `ask`, so a person is asked about such a call once per request. The agent still reports that
- * twin's `ask` event.
+ * twin's `ask` event. `builtins` enables the built-in tools and `workspace` names the workspace
+ * every request renders, as `AgentOptions` describes them. A ledger with `builtins` requires `authority`:
+ * construction throws `AgentError` with code `'AUTHORITY'` without it. The ledger tests each
+ * built-in call for a repeat and for room before this authority reads it, and every call it admits
+ * reaches this authority's `evaluate` and, when asked, its `ask`. While `builtins` enables `load`,
+ * calibration measures every definition but the tools a registered skill holds back.
  */
-export declare type LedgerAgentOptions = Pick<AgentOptions, 'limit' | 'timeout' | 'on' | 'scheduler' | 'instructions' | 'skills' | 'memos' | 'workspaces' | 'strict' | 'authority'>;
+export declare type LedgerAgentOptions = Pick<AgentOptions, 'limit' | 'timeout' | 'on' | 'scheduler' | 'instructions' | 'skills' | 'memos' | 'workspaces' | 'strict' | 'authority' | 'builtins' | 'workspace'>;
 
 /** Identifies an accepted direct message amendment whose sentence scope remains unresolved. */
 export declare interface LedgerAmendment {
@@ -7891,6 +8718,13 @@ export declare interface LedgerClassification {
     readonly supersessions: ReadonlyMap<string, readonly string[]>;
 }
 
+/** Carries one price a request committed: the tokens, the count of calls observed when it was committed, and the skill a `load` names. */
+export declare interface LedgerCommit {
+    readonly price: number;
+    readonly turn: number;
+    readonly skill?: string;
+}
+
 /**
  * Narrows the pair questions the ledger asks about each correction.
  *
@@ -7928,7 +8762,9 @@ export declare type LedgerEntityHandler = (text: string, partial: boolean) => Re
  * @remarks
  * A threshold, share, capacity, limit, topic, lookup, write, question, or gauge outside its bounds is a
  * programmer error and throws this with the matching {@link LedgerErrorCode}. A calibration call that reports
- * no prompt usage throws this with `'GAUGE'`. A snapshot option that `isLedgerSnapshot` refuses
+ * no prompt usage, or a calibration call, with the tool definitions, without them, or with the workspace text, that reports a prompt
+ * over `capacity`, the head included, throws this with `'GAUGE'`; the second holds `capacity` and
+ * `prompt` in its `context`. A snapshot option that `isLedgerSnapshot` refuses
  * throws this with `'SNAPSHOT'`, its `context` holding the `faults`. Narrow a caught value with {@link isLedgerError} and
  * branch on `error.code`. A selection without an active `respond` call, for a conversation other
  * than the ledger's, or for a request other than that call's request or a ledger note, reports
@@ -7965,7 +8801,7 @@ export declare type LedgerErrorCode =
 | 'TOPIC'
 /** Reports a lookup tool named `recall` or a name another lookup tool carries. */
 | 'LOOKUP'
-/** Reports a supplied gauge outside its bounds, or a calibration call that reports no prompt usage, or a prompt usage of 0 or less. */
+/** Reports a supplied gauge outside its bounds, a calibration call that reports no prompt usage or a prompt usage of 0 or less, or a calibration call, with the tool definitions, without them, or with the workspace text, that prices a prompt over `capacity`, the head included. */
 | 'GAUGE'
 /** Reports a render context that holds no reference for a source it annotates. */
 | 'REFERENCE'
@@ -7974,7 +8810,9 @@ export declare type LedgerErrorCode =
 /** Reports filing wording that `isLedgerQuestion` refuses. */
 | 'QUESTION'
 /** Reports a write without the `consequential` annotation, writes without `agent.authority`, or a write named `recall` or with a name a lookup or another write carries. */
-| 'WRITE';
+| 'WRITE'
+/** Reports a request no pass can carry, because the context the thread shows and the request price over `capacity - predict` with every cut made, or a host act after the answer pass's note grew its request past that limit. */
+| 'OVERFLOW';
 
 /** Captures held message identities and the accepted edges used to validate their copies. */
 export declare interface LedgerEvidence {
@@ -8014,9 +8852,13 @@ export declare interface LedgerGauge {
  * Carries a stored gauge: its price and the digest of the tool definitions that price measured.
  *
  * @remarks
- * `digest` is what the `digestLedgerTools` helper returns for the definitions the calibration request
- * carried, or for the ledger's definitions at construction when the options supplied the gauge. A
- * hydrate reuses the price only when the hydrated ledger's definitions have the same digest.
+ * `digest` is what the `digestLedgerTools` helper returns for the calibrated definitions: those the
+ * calibration request carried, or, when the options supplied the gauge, the ledger's calibrated
+ * definitions at construction. The calibrated set is every definition a turn can advertise but the
+ * tools a registered skill holds back while `agent.builtins` enables `load`. A hydrate reuses the
+ * price only when the hydrated ledger's calibrated definitions have the same digest, and each
+ * `respond` call compares the digest again, so a calibrated definition added or removed since drops
+ * the gauge.
  */
 export declare interface LedgerGaugeSnapshot extends LedgerGauge {
     readonly digest: string;
@@ -8063,8 +8905,11 @@ export declare interface LedgerIndex {
  * selection handler.
  */
 export declare interface LedgerInterface {
-    /** Holds the agent the ledger drives, with the ledger's tools and selection handler. */
-    readonly agent: AgentInterface;
+    /**
+     * Holds the record of the agent the ledger drives, with the ledger's tools and selection handler;
+     * it starts no run, so the `respond` method runs every pass.
+     */
+    readonly agent: LedgerAgentInterface;
     /** Holds the one conversation the ledger files and serves. */
     readonly conversation: ConversationInterface;
     /** Holds the measured price of a prompt, or undefined until the ledger calibrates when neither the options nor a snapshot priced on the same tool definitions supplied one. */
@@ -8073,7 +8918,9 @@ export declare interface LedgerInterface {
      * Appends `content` as a user message and serves it through to its reply.
      *
      * @remarks
-     * The ledger calibrates first while `gauge` is undefined. When the first pass ends without final
+     * The ledger calibrates first while `gauge` is undefined, and again when the digest of its tool
+     * definitions at this call differs from the one its gauge priced. When the first pass ends
+     * without final
      * text and the caller did not abort, the ledger adds the results and cue notes and makes one
      * answer pass that advertises no tools. In either pass, a call the model makes in a turn that
      * advertises no tools runs nothing and ends the pass after that turn, so such a pass makes one
@@ -8082,23 +8929,25 @@ export declare interface LedgerInterface {
      * reply's text and `partial: false`, or partial with empty content when the reply carries no text. A rejected first pass counts as unfinished; when the
      * answer pass rejects as well, `respond` rejects with that pass's error. A `respond` or `calibrate` call while either is in flight
      * rejects with an `AgentError` whose `code` is `'CONCURRENCY'`. A calibration call that reports no prompt usage, or a prompt usage of 0 or less, rejects with
-     * `LedgerError` code `'GAUGE'`; a provider error during calibration rejects with that error.
-     * A direct agent run on `conversation` while a `respond` call's pass runs is refused with an
-     * `AgentError` whose `code` is `'CONCURRENCY'`. Under the default `strict`, any other run no active
-     * `respond` call owns rejects with a `LedgerError` whose `code` is `'REQUEST'`: a direct run between
-     * requests, one during calibration, and a run on another conversation during a call. Under
-     * `strict: false` that run goes on over the whole view with no ledger selection; a run on another
-     * conversation then adds its turns and usage to that call's gauge readings and shares its repeat
-     * stop, and it can still reach the `recall` and lookup tools, which read `conversation`. The
-     * ledger's own guard refuses only `respond`, `calibrate`, and `snapshot` calls.
-     * Under `strict: false`, a run no `respond` call owns, including a run during calibration, reads no
-     * request's state: its lookup and `recall` calls run with no repeat stop, recall limit, or close rule.
-     * Every rejection leaves the ledger free for a later call.
+     * `LedgerError` code `'GAUGE'`; a provider error during calibration rejects with that error. A calibration call, with the
+     * tool definitions, without them, or with the workspace text, that reports a prompt over `capacity`, the head included,
+     * rejects with the same code and stores no request.
+     * Every run on the ledger's agent is a pass of this method, because `agent` holds no `generate` or
+     * `stream` member. A direct call to `agent.context.select` for a message no active `respond` call
+     * owns returns a selection whose `fault` is a `LedgerError` with code `'REQUEST'`, on
+     * `conversation` or another one, and asks the judge nothing; over another conversation, that
+     * selection carries that conversation's view alone. Calibration owns no message, so a direct
+     * selection during it faults the same way. Host code that calls a ledger tool by hand through
+     * `agent.context.tools` while a request runs reaches that request's state: a lookup or a write
+     * meets its repeat stop, and a `recall` call spends its recall limit. Between requests, and during
+     * calibration, such a call reads no request's state and runs with no repeat stop, recall limit, or
+     * close rule. Every rejection leaves the ledger free for a later call.
      *
      * @param content - The request text
      * @param signal - An optional caller signal; an abort during calibration rejects with its reason; afterward it ends the request partial and skips the answer pass
      * @returns The reply, the passes the request took, and the filing attempts of this request alone
      * @throws {LedgerError} Thrown when a calibration call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
+     * @throws {LedgerError} Thrown when a calibration call, with the tool definitions, without them, or with the workspace text, reports a prompt over `capacity`, the head included (code `'GAUGE'`)
      * @throws {AgentError} Thrown when a request or calibration is active (code `'CONCURRENCY'`)
      * @throws {ContractError} Thrown when `signal` is defined and is not a native `AbortSignal`
      */
@@ -8107,16 +8956,25 @@ export declare interface LedgerInterface {
      * Measures the gauge, holds it as `gauge`, and returns it.
      *
      * @remarks
-     * The ledger sends the head its agent's context builds and its conversation's view to the provider twice, with
-     * and without the tool definitions. The call without tools prices the messages and the
-     * difference between the calls is the overhead cost. The ledger records the digest of the
+     * The ledger sends the head its agent's context builds for an empty turn, with no workspace text and
+     * no conversation message, to the provider with the calibrated tool definitions and then without
+     * them, and the difference between the calls is the overhead cost. When the workspace the next
+     * request renders adds text, a third call carries the head and that text with no definitions, cut
+     * to the capacity the second call left over `LEDGER_SAMPLE_BYTES`, in characters. The scale is the
+     * reported prompt of the head with the workspace over its estimate, a cut text's tokens scaled to the
+     * whole text's estimate, and never under the head's own rate; with no workspace text it is the
+     * second call's prompt over the head's estimate. When the call with the definitions reports a
+     * prompt over `capacity`, the head included, the ledger sends no second call, stores no gauge, and
+     * rejects with `LedgerError` code `'GAUGE'`, whose `context` holds `capacity` and `prompt`; the
+     * call without them and the call with the workspace text refuse the same way. The ledger records the digest of the
      * definitions the call with tools carried, and its snapshot stores that digest with the gauge.
      * An abort during calibration rejects with the abort reason. A call during `respond` or `calibrate` rejects
      * with `AgentError` code `'CONCURRENCY'`.
      *
-     * @param signal - The signal that aborts both calls
+     * @param signal - The signal that aborts every calibration call
      * @returns The measured gauge
      * @throws {LedgerError} Thrown when a call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
+     * @throws {LedgerError} Thrown when a calibration call, with the tool definitions, without them, or with the workspace text, reports a prompt over `capacity`, the head included (code `'GAUGE'`)
      * @throws {AgentError} Thrown when a request or calibration is active (code `'CONCURRENCY'`)
      */
     calibrate(signal: AbortSignal): Promise<LedgerGauge>;
@@ -8124,10 +8982,9 @@ export declare interface LedgerInterface {
      * Serializes the conversation, the marked ids, and the gauge into a snapshot a later ledger hydrates from.
      *
      * @remarks
-     * The ledger first files every tool result whose message is appended, so a failure a direct
-     * agent run left is marked; a result whose tool message is not yet appended is not captured. A
-     * call while a `respond` or `calibrate` call is in flight throws, because an entered, unanswered
-     * request would hydrate as a dangling request; a direct agent run is not refused. The `gauge`
+     * The ledger first files every tool result whose message is appended; a result whose tool message
+     * is not yet appended is not captured. A call while a `respond` or `calibrate` call is in flight
+     * throws, because an entered, unanswered request would hydrate as a dangling request. The `gauge`
      * member carries the digest of the tool definitions the gauge priced.
      *
      * @returns The snapshot, each id list in conversation order and `gauge` present after the ledger holds one whose definitions JSON renders
@@ -8248,12 +9105,17 @@ export declare type LedgerLookupState = 'failed' | 'empty' | 'shown' | 'hidden';
  * and the reason of the denial the ledger gives the identical retry of a call the authority denied;
  * the ledger reads a failure with exactly this text, or that denial, as a repeat. `closure` is the
  * failure a `recall` call returns after the request's recalls are spent, repeated, or out of room.
+ * `overflow` is the reason of the denial the ledger gives a `load`, a `remember`, or a `switch` the
+ * request or the thread has no room for. That denial stays out of the repeat stop, and a successful
+ * `unload` in the same request reopens the call.
  */
 export declare interface LedgerNote {
     readonly cue: string;
     readonly results: string;
     readonly repeat: string;
     readonly closure: string;
+    /** Holds the reason the ledger denies a `load`, a `remember`, or a `switch` the request or the thread has no room for. */
+    readonly overflow: string;
 }
 
 /** Carries a rendered sentence with its record placement. */
@@ -8270,11 +9132,20 @@ export declare interface LedgerOccurrence extends LedgerLine, LedgerReceipt {
  * sentence included; it opens the system message, which also holds the instructions and the skills index the `agent` option supplies. The memos index and the workspace text go into the context message after it, and the records go into a copy of each request turn. `topics` lists the desk
  * topics. `questions` and `thresholds` are required with no default; pass the `LEDGER_QUESTIONS`
  * constant for the measured wording, and fit `thresholds` on the wording and the judge you pass. `capacity` is the model's context window in tokens and must be a positive safe
- * integer. Without `gauge`, or a `snapshot` gauge priced on the same tool definitions, the ledger calibrates before its first pass. `share` defaults leaf by leaf to `DEFAULT_LEDGER_SHARE`. The ledger writes the `LEDGER_NOTES` text.
+ * integer. Without `gauge`, or a `snapshot` gauge priced on the same calibrated definitions, the ledger calibrates before its first pass. The ledger prices with a supplied `gauge` as stated and compares it with no reported usage. `share` defaults leaf by leaf to `DEFAULT_LEDGER_SHARE`. The ledger writes the `LEDGER_NOTES` text.
  * `predict` is the generation cap in tokens, including thinking. Default: 0. It must be a
  * nonnegative safe integer less than `capacity`; construction throws `LedgerError` with code
  * `'CAPACITY'` otherwise. The plan budgets
- * `max(0, (capacity - predict) * share.prompt - overhead) / (1 + LEDGER_SCALE_DRIFT)`.
+ * `max(0, (capacity - predict) * share.prompt - (overhead - spared + added) - holdback) / (1 + LEDGER_SCALE_DRIFT)`.
+ * `spared` and `added` are what `computeToolPrice` returns for the definitions the first pass
+ * advertises with the thread's shown skills, against the calibrated set. While that pass advertises
+ * `load`, `holdback` is the `computeSkillPrice` of the largest skill the ceiling admits and the
+ * thread does not show, plus the price of one result: the longer of the longest stored tool result
+ * and the gauge's reply reserve. Otherwise it is 0.
+ * The ledger sends no request it prices over `capacity - predict`. A first pass or a later turn that
+ * does not fit ends with the agent's `abort` reason `overflow`, and the answer pass answers; an
+ * answer pass that does not fit with its note left out rejects `respond` with `LedgerError` code
+ * `'OVERFLOW'`.
  * The plan retains its `remainder - predict < 2 * reserve` admission rule. Runtime recall fits whole
  * results to measured remaining capacity at the larger of the gauge rate and the request's measured
  * rate, allowing `LEDGER_SCALE_DRIFT` for new text. Lack of room omits results without closing recall.
@@ -8283,6 +9154,9 @@ export declare interface LedgerOccurrence extends LedgerLine, LedgerReceipt {
  * the marked ids a ledger's `snapshot()` returned; construction throws `LedgerError` with code
  * `'SNAPSHOT'` when `isLedgerSnapshot` refuses it, and `ConversationError` with code `'ROLE'` or
  * `'SNAPSHOT'` when its conversation holds a `system` message or repeats an id.
+ * An own enumerable member this type or the `agent` pick does not declare refuses at construction
+ * with a `ContractError` coded `'structure'`, an `AgentOptions` member the pick leaves out included,
+ * and a declared member holding `undefined` reads as omitted.
  */
 export declare interface LedgerOptions {
     readonly judge: JudgeInterface;
@@ -8569,6 +9443,9 @@ export declare class LedgerRequest implements LedgerRequestInterface {
     /** Returns recall results with their accepted whole groups and provider-turn positions. */
     get listings(): readonly LedgerListing[];
     lines(result: string): ReadonlyMap<string, string> | undefined;
+    commit(price: number, skill?: string): void;
+    get committed(): number;
+    get loads(): readonly string[];
 }
 
 /**
@@ -8578,7 +9455,7 @@ export declare class LedgerRequest implements LedgerRequestInterface {
  *
  * @remarks
  * A ledger creates one request per `respond` call and drops it when the call settles, so no request
- * state reaches a later call or a run no call owns. Each agent run the call makes is a pass: `open`
+ * state reaches a later call or a ledger tool a host calls by hand between requests. Each agent run the call makes is a pass: `open`
  * starts one, and `selection`, `boundary`, `usage`, `signal`, and `aborted` read the current pass,
  * the last one opened.
  * `calls` lists the gauge calls of every pass in order. A call stays in flight, taking its usage and
@@ -8743,6 +9620,17 @@ export declare interface LedgerRequestInterface {
      * @returns Each listed lookup line mapped to its stored first line, or undefined when no recall returned `result`
      */
     lines(result: string): ReadonlyMap<string, string> | undefined;
+    /**
+     * Records the tokens one cleared call commits to the next prompt.
+     *
+     * @param price - The tokens the call commits
+     * @param skill - The skill the call loads, for a `load`
+     */
+    commit(price: number, skill?: string): void;
+    /** Holds the tokens committed after the call in flight started. */
+    readonly committed: number;
+    /** Holds the skills the loads committed after the call in flight started name, in commit order. */
+    readonly loads: readonly string[];
 }
 
 /**
@@ -8773,11 +9661,17 @@ export declare interface LedgerResult extends AgentResult {
  * with a delta copy, then its newest plain exchange with a full copy, then no exchange are priced
  * in that order. Admission cannot close an otherwise open recall or displace a selected record
  * line or seed message. A seed stub reads visibility across the window and the copy together.
+ * `skills` is the share of the prompt budget, `(capacity - predict) * prompt`, that a thread's shown
+ * skills can take: their bodies and the definitions they add beyond the calibrated set. A `load`
+ * that would take the shown skills, the loads its batch already admitted, and its own skill past it
+ * is denied with the {@link LedgerNote} `overflow` text.
  * Each share must be finite, greater than 0, and at most 1.
  */
 export declare interface LedgerShare {
     readonly prompt: number;
     readonly tail: number;
+    /** Holds the share of the prompt budget a thread's shown skills can take, bodies and tools together. */
+    readonly skills: number;
 }
 
 /**
@@ -9314,6 +10208,30 @@ export declare interface LiteralSet {
     readonly numbers: ReadonlySet<number>;
 }
 
+/**
+ * Names the section header the loaded skills' bodies render under at the end of the system
+ * message — `'## Loaded skills'`.
+ */
+export declare const LOADED_SECTION_HEADER = "## Loaded skills";
+
+/** Checks the arguments of the `load` and `unload` built-ins; its schema is the parameters they advertise. */
+export declare const loadToolContract: ContractInterface<Readonly<{
+    skill: string;
+} & {}>>;
+
+/**
+ * Describes the arguments of the `load` and `unload` built-ins — one `skill` name, non-empty and
+ * at most `BUILTIN_LIMITS.name` code points.
+ *
+ * @remarks
+ * The tool's door refuses a missing, empty, over-long, or extra member before the handler runs,
+ * and repairs a value that converts to a string without loss, such as a number. A value of white
+ * space alone passes the door; the handler refuses it as it refuses any name it cannot use.
+ */
+export declare const loadToolShape: ObjectShape<    {
+skill: StringShape;
+}, boolean | ContractShape>;
+
 /**
  * Matches the registry ids and owners a text names.
  *
@@ -9358,6 +10276,27 @@ export declare function matchEntities(index: LedgerIndex, text: string, partial:
  */
 export declare function matchesCutLine(line: string): boolean;
 
+/**
+ * Checks whether two ceilings carry the same lists of what a head renders: `instructions`,
+ * `skills`, `memos`, `files`, and `workspaces`.
+ *
+ * @remarks
+ * Each list compares by its members in order, and an absent list equals only an absent list,
+ * because `undefined` admits everything and `[]` admits nothing. The `tools` list is not compared:
+ * it reaches the tools block, never the head.
+ *
+ * @param left - One ceiling's lists
+ * @param right - The other ceiling's lists
+ * @returns True if every compared list matches; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesHeadLists({ skills: ['refunds'] }, { skills: ['refunds'], tools: [] }) // true
+ * matchesHeadLists({ skills: [] }, {}) // false
+ * ```
+ */
+export declare function matchesHeadLists(left: ScopeFilter, right: ScopeFilter): boolean;
+
 /**
  * Matches two values of JSON data by JSON value, whatever their key order, and reads a value with no JSON text as no match.
  *
@@ -9411,6 +10350,27 @@ export declare function matchesJudgment(judgment: Judgment, question: JudgeQuest
  */
 export declare function matchesLookup(left: LedgerLookupFinding, right: LedgerLookupFinding): boolean;
 
+/**
+ * Checks whether a text is one nonblank line: it holds a code point other than white space and
+ * default-ignorable code points (`ARGUMENT_BLANK_PATTERN`), and no control, format, line-separator, or
+ * paragraph-separator code point (`ARGUMENT_CONTROL_PATTERN`).
+ *
+ * @remarks
+ * The class is the one `renderArguments` encodes. A memo's name and description render in the memos
+ * index one line each, so `remember` refuses a value outside this check.
+ *
+ * @param text - The text to check
+ * @returns True if the text is one nonblank line; false otherwise
+ *
+ * @example
+ * ```ts
+ * matchesPlainLine('Reply tone') // true
+ * matchesPlainLine('Reply\ntone') // false
+ * matchesPlainLine('   ') // false
+ * ```
+ */
+export declare function matchesPlainLine(text: string): boolean;
+
 /**
  * Bounds the decoded error excerpt's input in bytes — `2048`, the leading bytes of a non-OK
  * response body handed to the decoder before the read cancels the remainder, so a `ProviderError`
@@ -9520,6 +10480,9 @@ export declare interface Memo {
     readonly origin?: MemoOrigin;
 }
 
+/** Lists the members `MemoManagerOptions` declares, frozen — the keys the `MemoManager` constructor admits. */
+export declare const MEMO_MANAGER_KEYS: readonly ["id", "on", "error", "format", "snapshot"];
+
 /**
  * Names the built-in section header a {@link import('./types.js').MemoManagerInterface} renders
  * its index under — `'## Memos'`, the `open` value when no `format.open` overrides it.
@@ -9557,6 +10520,37 @@ export declare interface MemoInput {
     readonly origin?: MemoOrigin;
 }
 
+/** Admits a memo input exactly, and reads the faults of a refused one. */
+export declare const memoInputContract: ContractInterface<Readonly<{
+name: string;
+description: string;
+content: string;
+} & {
+origin?: Readonly<{
+conversation: string;
+} & {
+message?: string;
+}>;
+}>>;
+
+/**
+ * Describes a memo input exactly: the members of a stored revision less the `id` and `time` the
+ * manager mints, each taken from {@link memoShape}.
+ *
+ * @remarks
+ * An unknown member, a missing required member, and a declared member holding `undefined` refuse, so
+ * a revision `add` stores is one its own snapshot hydrates.
+ */
+export declare const memoInputShape: ObjectShape<    {
+name: StringShape;
+description: StringShape;
+content: StringShape;
+origin: OptionalShape<ObjectShape<    {
+conversation: StringShape;
+message: OptionalShape<StringShape>;
+}, boolean | ContractShape>>;
+}, boolean | ContractShape>;
+
 /**
  * Registers the revisions of a memo set — durable facts keyed by `name`, where a same-name `add`
  * with changed text appends a revision and the earlier ones stay readable — carrying the `open` /
@@ -9672,6 +10666,7 @@ export declare interface MemoManagerInterface {
      *
      * @param input - One {@link MemoInput}, or a batch
      * @returns The appended or unchanged current revision, or the batch's results in input order
+     * @throws {ContractError} Thrown when an input fails `memoInputContract`: a missing required member, an undeclared member, or a declared member holding `undefined` (`code: 'structure'`); a refused batch stores nothing
      */
     add(input: MemoInput): Memo;
     add(inputs: readonly MemoInput[]): readonly Memo[];
@@ -10003,6 +10998,24 @@ export declare interface MemoStoreInterface {
     delete(id: string): Promise<void>;
 }
 
+/** Checks the arguments of the `memo` built-in; its schema is the parameters it advertises. */
+export declare const memoToolContract: ContractInterface<Readonly<{
+    name: string;
+} & {}>>;
+
+/**
+ * Describes the arguments of the `memo` built-in — one memo `name`, non-empty and at most
+ * `BUILTIN_LIMITS.name` code points.
+ *
+ * @remarks
+ * The tool's door refuses a missing, empty, over-long, or extra member before the handler runs,
+ * and repairs a value that converts to a string without loss, such as a number. A value of white
+ * space alone passes the door; the handler refuses it as it refuses any name it cannot use.
+ */
+export declare const memoToolShape: ObjectShape<    {
+name: StringShape;
+}, boolean | ContractShape>;
+
 /**
  * Merges supersession edges into a classification, adding each edge to both its supersessions and its amendments.
  *
@@ -10364,6 +11377,9 @@ export declare const PLACED_CATEGORIES: readonly LedgerCategory[];
  */
 export declare function placeMember(input: LedgerProjectionInput, links: ReadonlyMap<string, string>, amended: ReadonlyMap<string, readonly string[]>, id: string, seen: ReadonlySet<string>, settled?: Map<string, ReadonlySet<string>>): ReadonlySet<string>;
 
+/** Lists the members `AgentProviderInput` declares, frozen — the keys the `AgentProvider` constructor admits. */
+export declare const PROVIDER_INPUT_KEYS: readonly ["url", "path", "split", "strict", "timeout", "replay", "fetch", "headers"];
+
 /**
  * Reports a provider stream cancelled mid-flight by its bound signal — thrown by the
  * `stream` method of a {@link ProviderInterface}, carrying the {@link ProviderResult} assembled from
@@ -10728,6 +11744,9 @@ export declare interface ProviderStreamOptions {
  */
 export declare function questionToSystemOne(question: JudgeQuestion): SystemOneQuestion;
 
+/** Lists the members `AgentQueueOptions` declares, frozen — the keys `createAgentQueue` admits. */
+export declare const QUEUE_OPTION_KEYS: readonly ["registry", "partial", "concurrency", "retries", "timeout", "store"];
+
 /** Lists the categories whose messages the projection leaves out as quiet. */
 export declare const QUIET_CATEGORIES: readonly LedgerCategory[];
 
@@ -10866,6 +11885,9 @@ export declare function readJudgeOutcome(result: JudgeResult, id: string): {
  */
 export declare function readProviderDelta(value: unknown): ProviderDelta | undefined;
 
+/** Lists the members `ConversationReferenceOptions` declares, frozen — the keys the `reference` method of a `Conversation` admits. */
+export declare const REFERENCE_OPTION_KEYS: readonly ["label", "messages"];
+
 /** Reports a question a wire could not read a candidate for; it lists the caller's keys and invents no probability. */
 export declare interface Refusal {
     readonly missing: readonly string[];
@@ -10884,12 +11906,21 @@ export declare const REFUSED_RELAY_CONTENT_TYPE = "text/plain; charset=utf-8";
  */
 export declare const REFUSED_RELAY_STATUS = 422;
 
+/** Lists the members `AgentRegistryOptions` declares, frozen — the keys the `AgentRegistry` constructor admits. */
+export declare const REGISTRY_OPTION_KEYS: readonly ["providers", "tools", "authorities", "schedulers", "store", "skills", "memos", "workspaces"];
+
 /**
  * Names the relay's newline-delimited JSON content type — `'application/x-ndjson; charset=utf-8'`,
  * the header a relay response carries beside `cache-control: no-store`.
  */
 export declare const RELAY_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
 
+/** Lists the members `RelayOptions` declares, frozen — the keys `createRelay` admits. */
+export declare const RELAY_OPTION_KEYS: readonly ["provider", "authorize", "limit", "system", "tools"];
+
+/** Lists the members `RelayProviderOptions` declares, frozen — the keys the `RelayProvider` constructor admits. */
+export declare const RELAY_PROVIDER_KEYS: readonly ["url", "parser", "timeout", "replay", "fetch", "headers"];
+
 /**
  * Names the public message for an unexpected upstream relay failure — `'relay provider failed'`,
  * the fixed text every `error` frame carries, so an upstream failure's own message never reaches
@@ -10897,6 +11928,9 @@ export declare const RELAY_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
  */
 export declare const RELAY_PROVIDER_MESSAGE = "relay provider failed";
 
+/** Lists the members `RelayStreamOptions` declares, frozen — the keys the `RelayStream` constructor admits. */
+export declare const RELAY_STREAM_KEYS: readonly ["provider", "request", "signal"];
+
 /** Carries a relay delta, settled result, remote abort, or remote failure. */
 export declare type RelayFrame = ProviderDelta | {
     readonly channel: 'result';
@@ -11221,6 +12255,28 @@ export declare interface RelayToolOptions {
  */
 export declare function releaseReader(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
 
+/** Checks the arguments of the `remember` built-in; its schema is the parameters it advertises. */
+export declare const rememberToolContract: ContractInterface<Readonly<{
+    name: string;
+    description: string;
+    content: string;
+} & {}>>;
+
+/**
+ * Describes the arguments of the `remember` built-in — a memo `name`, the one-line `description`
+ * the memos index shows, and the `content`, each non-empty and within its `BUILTIN_LIMITS` cap.
+ *
+ * @remarks
+ * The tool's door refuses a missing, empty, over-long, or extra member before the handler runs,
+ * and repairs a value that converts to a string without loss, such as a number. A value of white
+ * space alone passes the door; the handler refuses it as it refuses any name it cannot use.
+ */
+export declare const rememberToolShape: ObjectShape<    {
+name: StringShape;
+description: StringShape;
+content: StringShape;
+}, boolean | ContractShape>;
+
 /**
  * Removes each key through a single-key remover and folds the outcomes, so a batch `remove`
  * reports whether the whole batch applied.
@@ -11328,6 +12384,26 @@ export declare function renderFencedFile(path: string, language: string, content
  */
 export declare function renderIndexEntry(entry: Pick<Memo, 'name' | 'description'>): string;
 
+/**
+ * Renders one index line from its text as `- text`, with each run of line-break code points as one
+ * space.
+ *
+ * @remarks
+ * Pure and total. The memo and skill index lines and the workspace index lines render through it,
+ * so text in an index never opens another line or heading.
+ *
+ * @param text - The line's text
+ * @returns The index line
+ *
+ * @example
+ * ```ts
+ * import { renderIndexLine } from '@orkestrel/agent'
+ *
+ * renderIndexLine('orders') // '- orders'
+ * ```
+ */
+export declare function renderIndexLine(text: string): string;
+
 /**
  * Renders a value as the JSON text `JSON.stringify` produces, or `undefined` when JSON cannot
  * carry the value.
@@ -11441,22 +12517,52 @@ export declare function renderLookupCall(name: string, args: Readonly<Record<str
  */
 export declare function renderSection<T>(open: string, members: readonly T[], render: (member: T) => string, close: string | undefined): string | undefined;
 
+/**
+ * Renders one loaded skill's body: `### name`, a blank line, then its content.
+ *
+ * @remarks
+ * Pure and total. The context build renders each shown skill through it under the loaded skills
+ * header, last in the system message.
+ *
+ * @param skill - The skill whose name and content the body shows
+ * @returns The body
+ *
+ * @example
+ * ```ts
+ * import { renderSkillBody } from '@orkestrel/agent'
+ *
+ * renderSkillBody({ name: 'refunds', content: 'Check the order first.' })
+ * // '### refunds\n\nCheck the order first.'
+ * ```
+ */
+export declare function renderSkillBody(skill: Pick<Skill, 'name' | 'content'>): string;
+
 /**
  * Renders the tail stub of a lookup result from an earlier request.
  *
+ * @remarks
+ * A `hidden` stub names the `recall` call that finds its result, with the first string argument,
+ * trimmed, or `its id` when no argument is a string or that one is blank, only while `offered` is `true`. The ledger plans the
+ * tail with every stub naming `recall`, then renders the tail's stubs again after it admits a window
+ * rung, with `offered` set to whether that rung offers `recall` and the scope admits it, so the
+ * second render can only shorten a stub and raises no price. `offered` changes no other state.
+ *
  * @param name - The lookup tool name
  * @param args - The arguments the call carried; arguments JSON cannot carry leave the call as its bare tool name, per {@link renderLookupCall}
  * @param state - What became of the result: `failed`, `empty`, `shown` in the records, or `hidden` from them
  * @param write - If `true`, the call is a write's, whose `empty` state reads `changed nothing`; if `false`, a lookup's, whose `empty` state reads `no record`. Default: `false`
+ * @param offered - If `true`, a `hidden` result names the `recall` route; if `false`, because the admitted rung offers no `recall` or the scope excludes it, it reads `result not shown`. Default: `true`
  * @returns The stub text, which carries the call and its state
  *
  * @example
  * ```ts
  * renderStub('lookup_order', { id: 'BW-5512' }, 'hidden')
  * // 'lookup_order {"id":"BW-5512"}: result not shown; call recall with BW-5512'
+ * renderStub('lookup_order', { id: 'BW-5512' }, 'hidden', false, false)
+ * // 'lookup_order {"id":"BW-5512"}: result not shown'
  * ```
  */
-export declare function renderStub(name: string, args: Readonly<Record<string, unknown>>, state: LedgerLookupState, write?: boolean): string;
+export declare function renderStub(name: string, args: Readonly<Record<string, unknown>>, state: LedgerLookupState, write?: boolean, offered?: boolean): string;
 
 /**
  * Renders a tool's output as the string content of its tool message, or returns `undefined` when JSON
@@ -11575,6 +12681,28 @@ export declare function requireAnswer(content: string, schema: Readonly<Record<s
  */
 export declare function requireBudget(value: BudgetInterface<TokenUsage> | undefined, key: 'budget' | 'allowance'): BudgetInterface<TokenUsage> | undefined;
 
+/**
+ * Returns an agent's `builtins` option as an owned, frozen list, or throws a coded error before the
+ * agent is built.
+ *
+ * @remarks
+ * `undefined` returns an empty list. The option must be an array of distinct {@link AgentBuiltin}
+ * names; `unload` needs `load`, because only a loaded skill can be unloaded; and the host's tool
+ * manager may hold no tool under an enabled name, because the run serves that name itself.
+ *
+ * @param value - The `builtins` option
+ * @param tools - The host's tool manager
+ * @returns The enabled names, in the order given
+ * @throws {AgentError} Thrown when the option is not an array, names something that is no built-in, repeats a name, lists `unload` without `load`, or names a tool the manager holds (code `'BUILTIN'`)
+ *
+ * @example
+ * ```ts
+ * requireBuiltins(['load', 'unload'], createToolManager()) // ['load', 'unload']
+ * requireBuiltins(['unload'], createToolManager()) // throws AgentError ('BUILTIN')
+ * ```
+ */
+export declare function requireBuiltins(value: unknown, tools: Pick<ToolManagerInterface, 'tool'>): readonly AgentBuiltin[];
+
 /**
  * Returns a run's `conversation` option after checking it implements `ConversationInterface`, or
  * throws a coded error before the run starts.
@@ -11767,14 +12895,17 @@ export declare function requireLimit(limit: number): number;
  * Returns a message input after checking its role and its members, or throws a coded error.
  *
  * @remarks
- * The role goes first, through {@link requireRole}, so its refusal names what it received. The members
- * cross {@link isMessageInput}, and `audit` runs only after it refused, so a stored message costs one
- * guard read. Tool-call arguments must also be JSON values before a message is stored.
+ * A value that is not a plain record, such as a class instance or an object that inherits its
+ * `role`, refuses first, through `isRecord` of `@orkestrel/contract`, with a text saying so. The role
+ * goes next, through {@link requireRole}, so its refusal names what it received. The members
+ * cross {@link isMessageInput}, an exact record guard, so a member `MessageInput` does not declare or a
+ * declared member holding `undefined` refuses, and `audit` runs only after a refusal. Tool-call
+ * arguments must also be JSON values before a message is stored.
  *
  * @param input - The message input to check
  * @param contract - The message input contract, whose `audit` is read only on a refusal
  * @returns The input, narrowed
- * @throws ConversationError Thrown when the role is not a `ConversationRole` (code `'ROLE'`) or a member fails `isMessageInput` (code `'MESSAGE'`), with the faults under `context.faults`
+ * @throws ConversationError Thrown when the input is not a plain record (code `'MESSAGE'`), when the role is not a `ConversationRole` (code `'ROLE'`), or when a member fails `isMessageInput`, an undeclared member included (code `'MESSAGE'`), with the faults under `context.faults`
  *
  * @example
  * ```ts
@@ -11805,6 +12936,34 @@ export declare function requireMessageInput(input: unknown, contract: Pick<Contr
  */
 export declare function requireProviderResult(value: unknown): ProviderResult;
 
+/**
+ * Checks a stored record's input against its exact contract, and throws a `ContractError` coded
+ * `'structure'` when it fails.
+ *
+ * @remarks
+ * The input must pass the contract's `is` guard: a missing required member, a member the input type
+ * does not declare, a declared member holding `undefined`, and a member of another type each refuse,
+ * so nothing a refused input carries is stored. A class instance refuses, and the contract reads own
+ * enumerable string keys alone, as every option door does. The contract's `audit` runs only after a refusal, and
+ * the message names the owner, the input type, and every fault with the members to send. The
+ * `context` holds the first fault's `path` and the input type as its `shape`.
+ *
+ * @param input - The input to check
+ * @param contract - The input's compiled contract
+ * @param owner - The entity named at the head of the refusal
+ * @param shape - The input type named in the refusal and its `context`
+ * @throws ContractError Thrown when the input fails the contract (code `'structure'`)
+ *
+ * @example
+ * ```ts
+ * import { memoInputContract, requireRecordInput } from '@orkestrel/agent'
+ *
+ * requireRecordInput({ name: 'tone', description: 'Prefers short replies.', content: 'Answer briefly.' }, memoInputContract, 'MemoManager', 'MemoInput') // returns
+ * requireRecordInput({ name: 'tone', description: undefined, content: 'Answer briefly.' }, memoInputContract, 'MemoManager', 'MemoInput') // throws ContractError ('structure')
+ * ```
+ */
+export declare function requireRecordInput(input: unknown, contract: Pick<ContractInterface<unknown>, 'is' | 'audit' | 'schema'>, owner: string, shape: string): void;
+
 /**
  * Returns a stored message role after checking it is a conversation role, or throws a coded error.
  *
@@ -11845,6 +13004,28 @@ export declare function requireRole(role: unknown): ConversationRole;
  */
 export declare function requireRules(rules: readonly AuthorityRule[] | undefined): readonly AuthorityRule[];
 
+/**
+ * Returns a scope a run can bind, or throws a `ContractError` coded `'placement'`; `undefined`
+ * passes through.
+ *
+ * @remarks
+ * The check is {@link isScope}, a total guard that reads each member one time and admits any
+ * implementation of `ScopeInterface`. `undefined` passes, because an absent option leaves the
+ * context scope alone as the run's ceiling. The error's `context` carries the option path, the
+ * limit `'ScopeInterface'`, and a preview of the refused value.
+ *
+ * @param value - The run's `scope` option, or `undefined`
+ * @returns The value unchanged
+ * @throws {ContractError} Thrown when `value` is defined and does not implement `ScopeInterface` (code `'placement'`)
+ *
+ * @example
+ * ```ts
+ * requireScope(createScope({ name: 'reader', tools: ['search'] })) // the scope
+ * requireScope({ id: 's1', name: 'reader' }) // throws ContractError ('placement')
+ * ```
+ */
+export declare function requireScope(value: unknown): ScopeInterface | undefined;
+
 /**
  * Returns a `sections` cap after checking it is a positive safe integer, or throws a coded error.
  *
@@ -11885,6 +13066,27 @@ export declare function requireSectionsCap(cap: number | undefined): number | un
  */
 export declare function requireSummary(summary: string): string;
 
+/**
+ * Returns a `workspace` option unchanged, or throws a `ContractError` coded `'placement'`;
+ * `undefined` passes through.
+ *
+ * @remarks
+ * The check is `isString`. An id the workspace registry does not hold, or the ceiling does not
+ * admit, passes here and renders nothing. The error's `context` carries the option path, the limit
+ * `'string'`, and a preview of the refused value.
+ *
+ * @param value - The `workspace` option of an agent, a run, or a ledger's agent, or `undefined`
+ * @returns The value unchanged
+ * @throws {ContractError} Thrown when `value` is defined and is not a string (code `'placement'`)
+ *
+ * @example
+ * ```ts
+ * requireWorkspace('orders') // 'orders'
+ * requireWorkspace(7) // throws ContractError ('placement')
+ * ```
+ */
+export declare function requireWorkspace(value: unknown): string | undefined;
+
 /**
  * Applies the `consequential` floor to one {@link AuthorityDecision} — an `allow` for a tool
  * whose advertised definition is annotated `consequential` becomes an `ask`.
@@ -11906,6 +13108,32 @@ export declare function requireSummary(summary: string): string;
  */
 export declare function resolveDecision(decision: AuthorityDecision, definition: ToolDefinition | undefined): AuthorityDecision;
 
+/**
+ * Resolves what a turn shows: the conversation's record, and the given workspace, within the
+ * ceiling and the registries.
+ *
+ * @remarks
+ * The caller reads the ceiling, so a turn reads each scope list one time. The skills are those
+ * {@link collectDisclosure} reads from the conversation, in load order, keeping each that the skill
+ * registry holds and the ceiling's `skills` list admits; an unregistered or excluded name shows
+ * nothing. The workspace is the conversation's last switch, else the given one, kept only when the
+ * workspace registry holds it and the ceiling's `workspaces` list admits it. The record counts only
+ * the built-ins in `builtins`, as {@link collectDisclosure} states.
+ *
+ * @param context - The agent's context, whose scope, skills, and workspaces it reads
+ * @param conversation - The conversation whose record to read
+ * @param workspace - The `workspace` option of the run or the agent, or `undefined`
+ * @param ceiling - The ceiling the turn read: the context scope intersected with the run scope
+ * @param builtins - The built-ins the run enables
+ * @returns The shown skills, in order, and the shown workspace when one is
+ *
+ * @example
+ * ```ts
+ * resolveDisclosure(agent.context, agent.context.messages, 'orders', {}, []) // { skills: [], workspace: 'orders' } when orders is registered
+ * ```
+ */
+export declare function resolveDisclosure(context: AgentContextInterface, conversation: Pick<ConversationInterface, 'sections' | 'messages'>, workspace: string | undefined, ceiling: ScopeFilter, builtins: readonly AgentBuiltin[]): AgentDisclosure;
+
 /**
  * Resolves the generation cap and checks it against the context capacity.
  *
@@ -11920,6 +13148,33 @@ export declare function resolveDecision(decision: AuthorityDecision, definition:
  */
 export declare function resolvePredict(predict: number | undefined, capacity: number): number;
 
+/**
+ * Resolves the workspace a run renders and acts on: the one `selected` names, else the registry's
+ * active one, kept only while `allowed` admits its id.
+ *
+ * @remarks
+ * A selection the registry does not hold resolves to `undefined` and never falls back to the active
+ * workspace. `allowed` is three-way, as {@link import('../helpers.js').filterAllowList} reads it.
+ * `AgentContext.build`, the caller an agent run hands each tool call, and a ledger's calibration
+ * resolve through it, so what a request renders and what a call receives come from one rule.
+ *
+ * @param workspaces - The workspace registry to read
+ * @param selected - The id a `switch` call or the `workspace` option selected, or `undefined`
+ * @param allowed - The ceiling's `workspaces` list (`undefined` ⇒ every id, `[]` ⇒ none)
+ * @returns The workspace, or `undefined` when none resolves
+ *
+ * @example
+ * ```ts
+ * import { resolveWorkspace } from '@orkestrel/agent'
+ *
+ * resolveWorkspace(agent.context.workspaces, 'returns', ['returns']) // the registered returns workspace
+ * ```
+ */
+export declare function resolveWorkspace(workspaces: WorkspaceManagerInterface, selected: string | undefined, allowed: readonly string[] | undefined): WorkspaceInterface | undefined;
+
+/** Lists the members `AgentRunnerOptions` declares, frozen — the keys `createAgentRunner` admits. */
+export declare const RUNNER_OPTION_KEYS: readonly ["registry", "partial", "concurrency", "retries", "timeout"];
+
 /**
  * Sanitizes one reported token count into a non-negative integer — a non-finite or
  * non-positive value becomes `0`, and a positive fractional value floors down.
@@ -11969,6 +13224,39 @@ export declare function sanitizeUsage(usage: TokenUsage): TokenUsage;
  */
 export declare function scanAmendments(amendments: ReadonlyMap<string, readonly string[]>, start: string, admit: (id: string) => boolean): readonly string[];
 
+/**
+ * Scans every job under a root for a member that exceeds its own parent's; an empty result clears the tree.
+ *
+ * @remarks
+ * The walk audits each job, the root included, through `agentJobContract` before it reads a member,
+ * because a job's `children` cross that contract as JSON records, and then reads each job the
+ * contract admits through `collectJobRefusals`. A job the contract refuses yields one finding with its
+ * faults, or with an unreadable note when a member read throws; a job its build would refuse yields
+ * one finding a refusal, its path, a dot, and the line; and the walk reads nothing under either. A
+ * child is within its parent when each of
+ * its `tools` is one its parent names (a parent with no `tools` names none), each of its `builtins`
+ * is one its parent names (a parent with no `builtins` names none), each name in each list of its
+ * `scope` is in its parent's same list (a job with no `scope` holds the three lists empty), its
+ * `authority` and `scheduler` are absent or its parent's, its `provider` is its parent's, its `limit`
+ * is at most its parent's (an absent `limit` reads `DEFAULT_AGENT_LIMIT`), and, where its parent
+ * holds a `timeout` or a `budget`, it holds one no larger. `system`, `messages`, and `workspace` are
+ * free: a `workspace` renders nothing its own `scope` omits. A refused job's finding
+ * opens with `JOB_REFUSAL_PREFIX` and then the job's path from `job`; an exceeded member's opens
+ * with that path, a dot, and the member. The walk is total: an unreadable job yields a finding,
+ * never a throw. The `AgentFanout` class runs it on every attempt of a unit, before the unit spawns
+ * or runs.
+ *
+ * @param root - The root job of the tree
+ * @returns One finding per refused job and per exceeded member, in walk order
+ *
+ * @example
+ * ```ts
+ * scanJobTree({ provider: 'main', children: [{ provider: 'other' }] })
+ * // ['job.children[0].provider: "other" differs from its parent\'s, which is "main"']
+ * ```
+ */
+export declare function scanJobTree(root: AgentJobInput): readonly string[];
+
 /**
  * Scans what a judge's answer must hold to its question: the same form, every probability in
  * `[0, 1]`, a choice's keys equal to the criteria keys, and a score as long as its levels.
@@ -12004,9 +13292,9 @@ export declare function scanProbability(value: number | undefined, path: readonl
 
 /**
  * Represents a named, immutable filter over a richer context's items — an optional allow-list per
- * category (`instructions` / `skills` / `memos` / `tools` / `files`), each keyed by that category's
- * identity (an instruction's, a skill's, a memo's, or a tool's `name`, a workspace file's `path`)
- * and read as an allow-list:
+ * category (`instructions` / `skills` / `memos` / `tools` / `files` / `workspaces`), each keyed by
+ * that category's identity (an instruction's, a skill's, a memo's, or a tool's `name`, a workspace
+ * file's `path`, a workspace's `id`) and read as an allow-list:
  * `undefined` lets everything pass, `[]` lets nothing pass, and a non-empty list passes the listed
  * keys alone. `narrow` composes a tighter child by set intersection.
  *
@@ -12024,6 +13312,10 @@ export declare function scanProbability(value: number | undefined, path: readonl
  *   `undefined` with a list yields the list, and `undefined` with `undefined` stays
  *   `undefined`. Narrowing can only tighten, never widen — a key excluded by a parent
  *   can never be re-admitted by a child. The child keeps this scope's `name` and `select` handler.
+ * - **Exact.** The constructor refuses an own enumerable member of its input outside
+ *   `SCOPE_KEYS`, and `narrow` one of its filter outside `SCOPE_FILTER_KEYS`, with a
+ *   `ContractError` coded `'structure'`, so a misspelled list never builds an open scope. A
+ *   declared member holding `undefined` reads as omitted.
  *
  * @example
  * ```ts
@@ -12043,38 +13335,72 @@ export declare class Scope implements ScopeInterface {
     readonly memos?: readonly string[];
     readonly tools?: readonly string[];
     readonly files?: readonly string[];
+    readonly workspaces?: readonly string[];
     readonly select?: SelectionHandler;
     constructor(input: ScopeInput);
     narrow(config: ScopeFilter): ScopeInterface;
 }
 
+/**
+ * Lists the members `ScopeFilter` declares, frozen — the keys the `narrow` method of a scope admits.
+ *
+ * @remarks
+ * The `narrow` method passes the list to `refuseOptionKeys` of `@orkestrel/contract`, so an own
+ * enumerable member outside it refuses with a `ContractError` coded `'structure'`.
+ */
+export declare const SCOPE_FILTER_KEYS: readonly ["instructions", "skills", "memos", "tools", "files", "workspaces"];
+
+/**
+ * Lists the members `ScopeInput` declares, frozen — the keys a `Scope` is built from.
+ *
+ * @remarks
+ * The `Scope` constructor passes the list to `refuseOptionKeys` of `@orkestrel/contract`, so an
+ * own enumerable member outside it, a misspelled list included, refuses with a `ContractError`
+ * coded `'structure'` instead of building a scope with no constraint.
+ */
+export declare const SCOPE_KEYS: readonly ["name", "select", "instructions", "skills", "memos", "tools", "files", "workspaces"];
+
+/** Lists the members `ScopeManagerOptions` declares, frozen — the keys the `ScopeManager` constructor admits. */
+export declare const SCOPE_MANAGER_KEYS: readonly ["on", "error"];
+
 /**
  * Holds the model-facing text the loop writes after a tool name in the denial result of a call
- * outside the active scope's tool allow-list or whose name no definition advertises this turn.
+ * outside the turn's tool ceiling, the context scope's tool allow-list intersected with the run
+ * scope's, or whose name no definition advertises this turn.
  */
 export declare const SCOPE_NOTE = "it is not one of the listed tools. Use a listed tool or answer with what you have.";
 
 /**
  * Lists the per-category allow-lists a {@link ScopeInterface} carries — an optional `readonly
- * string[]` for `instructions`, for `skills`, for `memos`, for `tools`, and for `files`, each keyed
- * by that category's identity (an instruction's, a skill's, a memo's, or a tool's `name`, a workspace
- * file's `path`) and read as an allow-list: `undefined` lets everything pass, `[]` lets nothing pass,
- * and a non-empty list passes the listed keys alone.
+ * string[]` for `instructions`, for `skills`, for `memos`, for `tools`, for `files`, and for
+ * `workspaces`, each keyed by that category's identity (an instruction's, a skill's, a memo's, or a
+ * tool's `name`, a workspace file's `path`, a workspace's `id`) and read as an allow-list:
+ * `undefined` lets everything pass, `[]` lets nothing pass, and a non-empty list passes the listed
+ * keys alone.
  *
  * @remarks
  * Each list is three-way (see {@link import('../helpers.js').filterAllowList}): `undefined`
  * ⇒ no constraint on that category (all pass); `[]` ⇒ none pass; a non-empty list ⇒ only
  * the listed keys pass. It is the shape both a {@link ScopeInput} and `Scope.narrow`
- * accept (a `name`-less narrowing config). `files` filters the active workspace's rendered
- * files (by `path`) in {@link AgentContextInterface.build} — both the text files folded into
- * the context message and the image files attached to the last user message.
+ * accept (a `name`-less narrowing config). `files` filters the rendered workspace's files (by
+ * `path`) in {@link AgentContextInterface.build} — both the text files folded into the context
+ * message and the image files attached to the last user message — and `workspaces` decides
+ * whether that workspace renders at all. Two lists bound a write as well as a read: the
+ * `remember` built-in writes only a name a defined `memos` list holds, and the `switch` built-in
+ * selects only an id a defined `workspaces` list holds. The `files` list also bounds the workspace
+ * tool of `@orkestrel/toolbox`, which receives it as `caller.files`, an
+ * {@link import('../agents/types.js').AgentCaller} member.
  */
 export declare interface ScopeFilter {
     /** Lists the allowed instruction names matched against the `name` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly instructions?: readonly string[];
     /** Lists the allowed skill names matched against the `name` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly skills?: readonly string[];
-    /** Lists the allowed memo names matched against the `name` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
+    /**
+     * Lists the allowed memo names matched against the `name` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed).
+     * A write is the exception: the `remember` built-in writes only a name a defined list holds, so
+     * `undefined` lets it write none.
+     */
     readonly memos?: readonly string[];
     /**
      * Lists the allowed tool names matched against the `name` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed).
@@ -12084,11 +13410,18 @@ export declare interface ScopeFilter {
     readonly tools?: readonly string[];
     /**
      * Lists the allowed active-workspace file paths matched against the `path` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —
-     * the filter {@link AgentContextInterface.build} applies to the active workspace's
+     * the filter {@link AgentContextInterface.build} applies to the rendered workspace's
      * {@link import('@orkestrel/workspace').WorkspaceInterface.files} before rendering them (text → the context message, image →
-     * the last user message).
+     * the last user message). Each tool call receives the list as `caller.files`, and the workspace
+     * tool of `@orkestrel/toolbox` reaches the listed paths alone.
      */
     readonly files?: readonly string[];
+    /**
+     * Lists the allowed workspace ids matched against the `id` property (`undefined` ⇒ all, `[]` ⇒ none, else only-listed).
+     * A selection is the exception: the `switch` built-in selects only an id a defined list holds, so
+     * `undefined` lets it select none.
+     */
+    readonly workspaces?: readonly string[];
 }
 
 /**
@@ -12097,7 +13430,10 @@ export declare interface ScopeFilter {
  */
 export declare interface ScopeInput extends ScopeFilter {
     readonly name: string;
-    /** Holds the selection handler that overrides the agent default while this scope is active. */
+    /**
+     * Holds the selection handler that overrides the agent default while this scope is active, and
+     * overrides the active scope's too while this scope is a run's.
+     */
     readonly select?: SelectionHandler;
 }
 
@@ -12116,7 +13452,10 @@ export declare interface ScopeInput extends ScopeFilter {
 export declare interface ScopeInterface extends ScopeFilter {
     readonly id: string;
     readonly name: string;
-    /** Holds the selection handler that overrides the agent default while this scope is active. */
+    /**
+     * Holds the selection handler that overrides the agent default while this scope is active, and
+     * overrides the active scope's too while this scope is a run's.
+     */
     readonly select?: SelectionHandler;
     /**
      * Composes a tighter child scope — each category is the set intersection of this scope's
@@ -12454,8 +13793,8 @@ export declare function settleToolResult(result: ToolResult): {
 };
 
 /**
- * Holds one skill: a name and a description the index shows, the instructions loading adds, and
- * bundled files.
+ * Holds one skill: a name and a description the index shows, the body a run shows, the tools it
+ * holds back, and bundled files.
  *
  * @remarks
  * A {@link SkillManagerInterface} mints it from a {@link SkillInput} and never mutates it. Its
@@ -12468,12 +13807,23 @@ export declare interface Skill {
     readonly name: string;
     /** Holds the one-line entry the skill index shows. */
     readonly description: string;
-    /** Holds the instructions loading the skill adds. */
+    /**
+     * Holds the body a run renders while it shows the skill: last in the `system` message, under
+     * `## Loaded skills`, for the run's conversation alone. A blank body renders nothing.
+     */
     readonly content: string;
+    /**
+     * Names the tools the skill holds back: while a turn advertises `load`, each is advertised only
+     * while a shown skill names it, within the turn's ceiling.
+     */
+    readonly tools: readonly string[];
     /** Lists the bundled files. */
     readonly files: readonly FileInterface[];
 }
 
+/** Lists the members `SkillManagerOptions` declares, frozen — the keys the `SkillManager` constructor admits. */
+export declare const SKILL_MANAGER_KEYS: readonly ["on", "error", "format"];
+
 /**
  * Names the built-in section header a {@link import('./types.js').SkillManagerInterface} renders
  * its index under — `'## Skills'`, the `open` value when no `format.open` overrides it.
@@ -12492,10 +13842,43 @@ export declare interface SkillInput {
     readonly name: string;
     readonly description: string;
     readonly content: string;
+    /**
+     * Names the tools the skill holds back until it is shown. The manager copies the list, and
+     * refuses a value that is neither absent nor an array of strings with a `ContractError` coded
+     * `'placement'`. Default: none.
+     */
+    readonly tools?: readonly string[];
     /** Lists the bundled files to mint with `createFile`. Default: none. */
     readonly files?: readonly FileInput[];
 }
 
+/** Admits a skill input exactly, and reads the faults of a refused one. */
+export declare const skillInputContract: ContractInterface<Readonly<{
+name: string;
+description: string;
+content: string;
+} & {
+tools?: readonly string[];
+files?: readonly unknown[];
+}>>;
+
+/**
+ * Describes a skill input exactly: a string `name`, `description`, and `content`, optional `tools`
+ * names, and optional `files`.
+ *
+ * @remarks
+ * An unknown member, a missing required member, and a declared member holding `undefined` refuse.
+ * Each file is the `FileInput` interface of `@orkestrel/workspace`, which publishes no guard for it,
+ * so the shape admits any defined element and `createFile`, that package's own door, reads it.
+ */
+export declare const skillInputShape: ObjectShape<    {
+name: StringShape;
+description: StringShape;
+content: StringShape;
+tools: OptionalShape<ArrayShape<StringShape>>;
+files: OptionalShape<ArrayShape<RawShape>>;
+}, boolean | ContractShape>;
+
 /**
  * Registers the skills a host supplies — instruction bundles keyed by `name`, listed in insertion
  * order, where adding a skill whose name is already stored overwrites it, last write wins —
@@ -12586,11 +13969,17 @@ export declare interface SkillManagerInterface {
     /** Holds the line after the skills: the manager-options `close`, or `undefined` when none. */
     readonly close: string | undefined;
     /**
-     * Adds one {@link SkillInput}, or a batch: mints each `id` and file, and overwrites a
-     * same-name skill, last write wins.
+     * Adds one {@link SkillInput}, or a batch: mints each `id` and file, copies each `tools` list,
+     * and overwrites a same-name skill, last write wins.
+     *
+     * @remarks
+     * Each input is checked and minted before any skill is stored or emitted, so a refused batch
+     * stores nothing. A `tools` member is read first, then the input meets `skillInputContract`.
      *
      * @param input - One {@link SkillInput}, or a batch
      * @returns The stored skill, or the stored batch in input order
+     * @throws {ContractError} Thrown when a `tools` member is neither absent nor an array of strings (`code: 'placement'`)
+     * @throws {ContractError} Thrown when an input fails `skillInputContract`: a missing required member, an undeclared member, or a declared member holding `undefined` (`code: 'structure'`)
      */
     add(input: SkillInput): Skill;
     add(inputs: readonly SkillInput[]): readonly Skill[];
@@ -12699,6 +14088,9 @@ export declare function splitTopic(topic: string): readonly string[];
  */
 export declare function splitWords(part: string): readonly string[];
 
+/** Lists the members `ProviderStreamOptions` declares, frozen — the keys the `generate` and `stream` methods of an `AgentProvider` admits. */
+export declare const STREAM_OPTION_KEYS: readonly ["think", "schema"];
+
 /**
  * Pairs a live event stream with the eventual settled result and a cancel — the
  * generic pull/streaming handle a long-running operation hands back.
@@ -12772,6 +14164,27 @@ export declare function stripThinking(messages: readonly Message[], replay: Thin
  */
 export declare function sumUsage(prior: TokenUsage | undefined, next: TokenUsage): TokenUsage;
 
+/** Checks the arguments of the `switch` built-in; its schema is the parameters it advertises. */
+export declare const switchToolContract: ContractInterface<Readonly<{
+    workspace: string;
+} & {}>>;
+
+/**
+ * Describes the arguments of the `switch` built-in — one `workspace` id, non-empty and at most
+ * `BUILTIN_LIMITS.name` code points.
+ *
+ * @remarks
+ * The tool's door refuses a missing, empty, over-long, or extra member before the handler runs,
+ * and repairs a value that converts to a string without loss, such as a number. A value of white
+ * space alone passes the door; the handler refuses it as it refuses any name it cannot use.
+ */
+export declare const switchToolShape: ObjectShape<    {
+workspace: StringShape;
+}, boolean | ContractShape>;
+
+/** Lists the members `SystemOneJudgeOptions` declares, frozen — the keys the `SystemOneJudge` constructor admits. */
+export declare const SYSTEM_ONE_OPTION_KEYS: readonly ["url", "model", "timeout", "fetch", "headers"];
+
 /** Names the System One decision endpoint shared by compatible servers. */
 export declare const SYSTEM_ONE_PATH = "/v1/systemone";
 
@@ -13108,6 +14521,12 @@ export declare const UNAUTHORIZED_RELAY_STATUS = 401;
  */
 export declare const UPSTREAM_RELAY_STATUS = 502;
 
+/**
+ * Names the section header the admitted workspace ids render under in the user context message —
+ * `'## Workspaces'`, rendered only while a run can select a workspace.
+ */
+export declare const WORKSPACE_INDEX_HEADER = "## Workspaces";
+
 /**
  * Names the section header the `build()` method of {@link import('./AgentContext.js').AgentContext}
  * renders the active workspace's text files under — `'## Workspace'`, the line that opens the