@orkestrel/agent 0.0.7 → 0.0.9

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

@@ -1,8 +1,10 @@
 import { BudgetInterface } from '@orkestrel/budget';
+import { ControllerInterface } from '@orkestrel/workflow';
 import { DriverInterface } from '@orkestrel/database';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { QueueExecution } from '@orkestrel/queue';
 import { QueueInterface } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
 import { RunnerInterface } from '@orkestrel/workflow';
@@ -182,7 +184,7 @@ export declare class AgentContext implements AgentContextInterface {
  * @remarks
  * The richer context — `system` (the optional system prompt), the context managers
  * (`instructions` / `tools` / `workspaces` / `conversations`), `messages` (the active
- * conversation's live tail, satisfying {@link MessageManagerInterface}), and a mutable `scope`
+ * conversation's live tail, satisfying {@link MessageManagerInterface}), and the current `scope`
  * (the active {@link ScopeInterface} filter, or `undefined` for no filtering). `build()` folds the
  * scoped instructions into ONE leading `system` message (under the manager's `description`,
  * each item via its `format`) — PLUS the ACTIVE workspace's scope-filtered text files
@@ -200,13 +202,12 @@ export declare interface AgentContextInterface {
      * The {@link WorkspaceManagerInterface} whose ACTIVE workspace `build()` renders by carrier —
      * its text files folded into the system block (fenced reference blocks) and its image files'
      * base64 `data` 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). A
-     * SETTABLE mutable property (a getter + setter, like {@link scope} / {@link conversations}, NOT a
-     * method): assign it to swap the whole workspace registry; `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.
+     * 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.
      */
-    workspaces: WorkspaceManagerInterface;
+    readonly workspaces: WorkspaceManagerInterface;
     /**
      * The active conversation's LIVE tail — the agent's message source, ALWAYS defined (the
      * {@link conversations} registry always has an active conversation; a default is added at
@@ -221,16 +222,15 @@ export declare interface AgentContextInterface {
      * The {@link ConversationManagerInterface} the message source flows from — `messages` IS its
      * ACTIVE conversation's live tail and `build()` folds that conversation's `view()`. ALWAYS holds
      * an active conversation (a default is added at construction when none was supplied), so
-     * `messages` is always defined. A SETTABLE mutable property (a getter + setter, like
-     * {@link scope} / {@link workspaces}, NOT a method): assign it to swap the whole conversation
-     * registry between runs; switch the active conversation through `conversations.switch(id)` — so
-     * one agent can serve MANY conversations (set the active one per request). Switch BETWEEN runs,
-     * not during one; for CONCURRENT threads use separate agents (see clause 25).
+     * `messages` is always defined. Switch the active conversation through
+     * `conversations.switch(id)` — so one agent can serve MANY conversations (set the active one per
+     * request). Switch BETWEEN runs, not during one; for CONCURRENT threads use separate agents (see
+     * clause 25).
      */
-    conversations: ConversationManagerInterface;
+    readonly conversations: ConversationManagerInterface;
     readonly tools: ToolManagerInterface;
-    /** The active scope applied at `build()` time + the loop's tool-advertise step; mutable (`undefined` ⇒ no filtering). */
-    scope: ScopeInterface | undefined;
+    /** The active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
+    readonly scope: ScopeInterface | undefined;
     /**
      * The provider input for the next turn: a leading `system` message folding the prompt
      * + the scoped instructions + the ACTIVE workspace's scoped-in TEXT files (rendered as
@@ -333,6 +333,24 @@ export declare interface AgentContextOptions {
     readonly conversations?: ConversationManagerInterface;
 }
 
+/**
+ * Thrown synchronously by an {@link AgentInterface}'s `stream()` when a concurrent run would
+ * corrupt SHARED per-agent accounting — carries a machine-readable `code`.
+ *
+ * @remarks
+ * A run already in flight on the same agent, PLUS a construction-level `window` (a shared
+ * context budget) or a construction-level `budget` with no per-run override (a shared cost
+ * budget), means a second concurrent `stream()` would race its charges against the same
+ * shared instance — corrupting the accounting. `code` is `'CONCURRENCY'` (the only condition
+ * so far). Use separate agents, or per-run `budget` overrides with no `window`, for genuinely
+ * concurrent runs. Narrow a caught value with {@link isAgentError} and branch on `error.code`.
+ */
+export declare class AgentError extends Error {
+    /** The machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent. */
+    readonly code: 'CONCURRENCY';
+    constructor(code: 'CONCURRENCY', message: string);
+}
+
 /**
  * The push observation surface of an {@link AgentInterface} (AGENTS §13) — the
  * lifecycle + usage/tool moments a fire-and-forget observer (logging, metrics,
@@ -407,16 +425,32 @@ export declare interface AgentInterface {
      * Run the turn to completion, discarding the live chunks — drains the shared
      * stream and resolves the settled outcome.
      *
+     * @remarks
+     * A concurrent run on a shared accounting agent throws an
+     * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) — and it throws
+     * SYNCHRONOUSLY, before any `Promise` is returned. A fire-and-forget
+     * `agent.generate().catch(...)` therefore will NOT catch it (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 `try`/`catch`.
+     *
      * @param options - Optional per-run {@link AgentRunOptions} (e.g. `think`); omitted ⇒ defaults
      * @returns The settled {@link AgentResult} (`partial: true` when cancelled)
+     * @throws {AgentError} Synchronously, with `code: 'CONCURRENCY'`, for a concurrent run
      */
     generate(options?: AgentRunOptions): Promise<AgentResult>;
     /**
      * Run the turn as a live stream — iterate `events` for {@link AgentChunk}s and
      * `await result` for the settled outcome.
      *
+     * @remarks
+     * Like `generate()`, a concurrent run on a shared accounting agent throws an
+     * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) 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`.
+     *
      * @param options - Optional per-run {@link AgentRunOptions} (e.g. `think`); omitted ⇒ defaults
      * @returns A live {@link AgentStreamInterface} handle (events + result + abort)
+     * @throws {AgentError} Synchronously, with `code: 'CONCURRENCY'`, for a concurrent run
      */
     stream(options?: AgentRunOptions): AgentStreamInterface;
     /**
@@ -525,6 +559,16 @@ export declare interface AgentJobInput {
  *   reaches the window AND the active conversation is summarizable, COMPACTS the active
  *   conversation + continues on the rebuilt smaller view — compact-and-continue, distinct from
  *   `budget`'s hard abort. Omitted ⇒ no auto-compaction.
+ * - `strict` — when `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run
+ *   (rethrown after the `compactError` event, propagating through `#run` to a genuine `error`
+ *   settle) instead of skipping compaction and continuing over-window. Defaults to `false`
+ *   (lenient — the prior, byte-for-byte behavior).
+ * - `instructions` — an optional pre-built {@link InstructionManagerInterface} forwarded to the
+ *   agent's context; an empty one is created when omitted (mirrors {@link AgentContextOptions.instructions}).
+ * - `workspaces` — an optional pre-built {@link WorkspaceManagerInterface} forwarded to the
+ *   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 build-time filter); `undefined` ⇒ no filtering (mirrors {@link AgentContextOptions.scope}).
  * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the agent's
  *   {@link AgentEventMap}, wired at construction (e.g. `{ finish: (r) => log(r) }`).
  */
@@ -535,6 +579,12 @@ export declare interface AgentOptions {
     readonly system?: string;
     /** A pre-built tool registry the loop dispatches calls through; an empty one is created when omitted. */
     readonly tools?: ToolManagerInterface;
+    /** A pre-built instruction registry forwarded to the agent's context; an empty one is created when omitted. */
+    readonly instructions?: InstructionManagerInterface;
+    /** A pre-built workspace registry forwarded to the agent's context; a fresh empty one is created when omitted. */
+    readonly workspaces?: WorkspaceManagerInterface;
+    /** The initial active scope forwarded to the agent's context (the build-time filter); `undefined` ⇒ no filtering. */
+    readonly scope?: ScopeInterface;
     /** Max tool-iteration turns before the loop stops; defaults to `DEFAULT_AGENT_LIMIT`. */
     readonly limit?: number;
     /** A wall-clock deadline (ms) for the whole turn; its abort commits a partial result. */
@@ -572,6 +622,13 @@ export declare interface AgentOptions {
      * as the cost `budget`, but compaction is the ceiling action instead of abort. Omit to disable.
      */
     readonly window?: BudgetInterface<readonly MessageInterface[]>;
+    /**
+     * When `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run — the
+     * `compactError` event still fires, then the caught error is RETHROWN so the run settles
+     * `error` instead of continuing over-window. Defaults to `false` (lenient — the run
+     * continues over-window, byte-for-byte the prior behavior).
+     */
+    readonly strict?: boolean;
 }
 
 /**
@@ -1075,7 +1132,7 @@ export declare function clampRange(text: string, range: Range): Range;
 
 /**
  * The PER-RUN auto-compaction state threaded through an {@link AgentInterface}'s loop —
- * a tiny mutable holder created fresh per run (so no state leaks across runs or a
+ * a tiny immutable value replaced within a holder created fresh per run (so no state leaks across runs or a
  * conversation switch), mirroring how {@link RunOutcome} is the per-run sink.
  *
  * @remarks
@@ -1083,10 +1140,10 @@ export declare function clampRange(text: string, range: Range): Range;
  * the prompt is still over the context window (the v1 single-level limit — the live tail
  * is at/below `keep` and the over-window is structural), so auto-compaction STOPS for the
  * rest of that run (no per-turn churn). Like {@link RunOutcome}, it is INTERNAL loop state
- * — the loop reads + flips it as it runs, not a caller-facing shape.
+ * — the loop reads + replaces it as it runs, not a caller-facing shape.
  */
 export declare interface CompactionState {
-    futile: boolean;
+    readonly futile: boolean;
 }
 
 /**
@@ -1096,11 +1153,16 @@ export declare interface CompactionState {
  * `keep` overrides the conversation's configured retained-tail size for THIS compaction only
  * (the older `count - keep` live messages fold; when `count <= keep` nothing folds and
  * `compact()` is a no-op returning `undefined`). Omitted ⇒ the conversation's own `keep`
- * (its option, or `DEFAULT_CONVERSATION_KEEP`) applies.
+ * (its option, or `DEFAULT_CONVERSATION_KEEP`) applies. `sections` overrides the conversation's
+ * configured `sections` cap for THIS compaction only — after the new section is pushed, an
+ * overflow past `sections` folds the oldest sections into one merged section. Omitted ⇒ the
+ * conversation's own `sections` cap (or unlimited) applies.
  */
 export declare interface CompactOptions {
     /** Override the retained-tail size for this compaction; omitted ⇒ the conversation's own `keep`. */
     readonly keep?: number;
+    /** Override the `sections` cap for this compaction; omitted ⇒ the conversation's own cap (or unlimited). */
+    readonly sections?: number;
 }
 
 /**
@@ -1274,20 +1336,23 @@ export declare const CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages]
 
 /**
  * Thrown by a {@link ConversationInterface}'s `compact()` when the conversation has no
- * {@link ConversationSummarizer} to fold its messages with — carries a machine-readable
- * `code`.
+ * {@link ConversationSummarizer} to fold its messages with, or when its `sections` cap is
+ * structurally invalid — carries a machine-readable `code`.
  *
  * @remarks
  * Compaction REQUIRES a summarizer (it digests the folded slice into a section summary and
  * regenerates the rollup); a conversation created without one can still store + `view()` its
- * live tail, but a `compact()` is a programmer error (§12) and throws this. `code` is
- * `'SUMMARIZER'` (the only condition so far). Narrow a caught value with
+ * live tail, but a `compact()` is a programmer error (§12) and throws this with `'SUMMARIZER'`.
+ * A `sections` cap (§F2, on {@link import('./types.js').ConversationOptions} /
+ * {@link import('./types.js').ConversationManagerOptions} /
+ * {@link import('./types.js').CompactOptions}) must be `>= 1` — a sub-1 cap is a programmer
+ * error and throws this with `'SECTIONS'`. Narrow a caught value with
  * {@link isConversationError} and branch on `error.code`.
  */
 export declare class ConversationError extends Error {
-    /** The machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer. */
-    readonly code: 'SUMMARIZER';
-    constructor(code: 'SUMMARIZER', message: string);
+    /** The machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a sub-1 `sections` cap. */
+    readonly code: 'SUMMARIZER' | 'SECTIONS';
+    constructor(code: 'SUMMARIZER' | 'SECTIONS', message: string);
 }
 
 /**
@@ -1295,9 +1360,11 @@ export declare class ConversationError extends Error {
  * moments a fire-and-forget observer subscribes to via `conversation.emitter.on`.
  *
  * @remarks
- * `compact` carries the newly-folded {@link SectionInterface}; `summary` carries the
- * regenerated conversation rollup (refreshed on each compaction); `rehydrate` carries the
- * `id` of a section whose originals were pulled back. Listener isolation is the emitter's
+ * `compact` carries the newly-folded {@link SectionInterface}; `collapse` carries a section
+ * created by folding multiple OLDER sections together (a bounded-`sections` cap enforcement,
+ * distinct from `compact`'s fresh live-tail fold); `summary` carries the regenerated
+ * conversation rollup (refreshed on each compaction); `rehydrate` carries the `id` of a
+ * section whose originals were pulled back. Listener isolation is the emitter's
  * (§13): every event is emitted directly and a listener throw is routed to the emitter's
  * `error` handler (the `error` option), never onto this map, so a buggy observer can never
  * corrupt a compaction. A `type` alias (not `interface extends EventMap`, §4.5) so the
@@ -1310,6 +1377,11 @@ export declare type ConversationEventMap = {
     readonly summary: readonly [summary: string];
     /** A section's original messages were pulled back — the section's `id`. */
     readonly rehydrate: readonly [id: string];
+    /**
+     * The bounded-`sections` cap folded the oldest sections into ONE merged section — the
+     * merged {@link SectionInterface} that replaced them.
+     */
+    readonly collapse: readonly [section: SectionInterface];
 };
 
 /**
@@ -1321,7 +1393,8 @@ export declare type ConversationEventMap = {
  * `id` is the conversation's identity (minted when omitted). `summarize` OVERRIDES the
  * manager's default {@link ConversationSummarizer} for this conversation (omitted ⇒ the
  * manager's default flows in). `keep` overrides the manager's default retained-tail size.
- * `on` is the §8 reserved key (initial {@link ConversationEventMap} listeners). `snapshot` is
+ * `sections` overrides the manager's default `sections` cap. `on` is the §8 reserved key
+ * (initial {@link ConversationEventMap} listeners). `snapshot` is
  * the construction-time hydration seam — a {@link ConversationSnapshot} whose `id` / `summary` /
  * `sections` / live tail are RESTORED into the new conversation (the live `summarize` / `keep` /
  * `on` re-supplied alongside it), the conversation analogue of {@link WorkspaceInput.seed} that a
@@ -1335,6 +1408,8 @@ export declare interface ConversationInput {
     readonly summarize?: ConversationSummarizer;
     /** Overrides the manager's default retained-tail size for this conversation. */
     readonly keep?: number;
+    /** Overrides the manager's default `sections` cap for this conversation. */
+    readonly sections?: number;
     readonly on?: EmitterHooks<ConversationEventMap>;
     /** A {@link ConversationSnapshot} to hydrate FROM (its `id` / `summary` / `sections` / live tail restored); the analogue of `WorkspaceInput.seed`. */
     readonly snapshot?: ConversationSnapshot;
@@ -1459,6 +1534,13 @@ export declare interface ConversationInterface {
      * resolves the new section. Requires a {@link ConversationSummarizer} — THROWS a
      * {@link import('./errors.js').ConversationError} when none was supplied.
      *
+     * @remarks
+     * When a `sections` cap is set and the fold pushes the section count over it, an overflow
+     * merge step folds the oldest sections into one — if THAT merge's `summarize` call throws,
+     * the merge is skipped (sections transiently sit at `cap + 1`, no loss) but the rollup still
+     * regenerates over the current unmerged sections (never left stale) before the error
+     * propagates; the next successful `compact()` self-heals the section count back to `cap`.
+     *
      * @param options - Optional {@link CompactOptions} (`keep` overrides the retained-tail size)
      * @returns The new {@link SectionInterface}, or `undefined` when nothing folded
      */
@@ -1651,13 +1733,17 @@ export declare interface ConversationManagerInterface {
  * (a per-`add` {@link ConversationInput.summarize} overrides it); a conversation created
  * with neither cannot `compact` (it throws a `ConversationError`). `keep` is the default
  * retained-tail size (a per-`add` {@link ConversationInput.keep} overrides it), defaulting
- * to {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP}.
+ * to {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP}. `sections` is the default cap
+ * on a created conversation's compacted `sections` list (a per-`add` {@link ConversationInput.sections}
+ * overrides it); omitted ⇒ unlimited.
  */
 export declare interface ConversationManagerOptions {
     /** The default summarizer for conversations this manager creates (a per-`add` override wins). */
     readonly summarize?: ConversationSummarizer;
     /** The default retained-tail size (a per-`add` override wins); defaults to `DEFAULT_CONVERSATION_KEEP`. */
     readonly keep?: number;
+    /** The default `sections` cap for conversations this manager creates (a per-`add` override wins); omitted ⇒ unlimited. */
+    readonly sections?: number;
     /**
      * The optional durable {@link ConversationStoreInterface} backing
      * {@link ConversationManagerInterface.open} / {@link ConversationManagerInterface.save} — a memory
@@ -1681,7 +1767,10 @@ export declare interface ConversationManagerOptions {
  * live tail, it just cannot fold). `keep` is how many recent live messages a `compact()`
  * retains VERBATIM (folding only the older ones); it defaults to
  * {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP} (`0` — a manual `compact()`
- * folds the WHOLE current live tail into one section).
+ * folds the WHOLE current live tail into one section). `sections` is an optional cap on the
+ * compacted `sections` list — when set (`>= 1`), a `compact()` that would leave more than
+ * `sections` sections FOLDS the oldest overflow into ONE merged section so the list never
+ * exceeds `sections`, emitting `collapse`; omitted ⇒ unlimited (the prior behavior).
  */
 export declare interface ConversationOptions {
     readonly id?: string;
@@ -1692,6 +1781,8 @@ export declare interface ConversationOptions {
     readonly summarize?: ConversationSummarizer;
     /** Recent live messages kept verbatim on `compact`; defaults to `DEFAULT_CONVERSATION_KEEP` (`0`). */
     readonly keep?: number;
+    /** A cap (`>= 1`) on the compacted `sections` list; overflow folds into one merged section. Omitted ⇒ unlimited. */
+    readonly sections?: number;
 }
 
 /**
@@ -2784,19 +2875,26 @@ export declare function escapeRegExp(value: string): string;
  * (the {@link import('./types.js').AgentOptions} `window`).
  *
  * @remarks
- * Sums {@link estimateTokens} over each message's `content` (the `ceil(length / 4)` char
- * heuristic), so it is deterministic and provider-free — the same messages always yield the
- * same estimate, with an empty batch `0`. It is the fully-swappable default an agent's
- * auto-compaction context budget charges each turn's new messages through; a caller wanting a
- * sharper count supplies its own `consume` to `createBudget` instead. Total — never throws.
+ * Sums, per message, {@link estimateTokens} over its `content` (the `ceil(length / 4)` char
+ * heuristic) PLUS {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (a fixed per-message
+ * role/framing overhead) PLUS, when present, {@link estimateTokens} over its JSON-stringified
+ * `calls` PLUS `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
+ * deliberately-approximate per-image cost — a base64 length is NOT a token proxy). Deterministic
+ * and provider-free — the same messages always yield the same estimate, with an empty batch `0`.
+ * It is the fully-swappable default an agent's auto-compaction context budget charges each
+ * turn's new messages through; a caller wanting a sharper count supplies its own `consume` to
+ * `createBudget` instead. Total — never throws: a `calls` `JSON.stringify` that throws (a
+ * circular `ToolCall.arguments`) is caught and replaced with a conservative fixed contribution of
+ * {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (the same per-message overhead scale)
+ * instead of estimating the (unreachable) serialized length.
  *
  * @param messages - The messages to estimate (a turn's appended assistant + tool messages)
- * @returns The summed estimated token count (`Σ estimateTokens(m.content)`; `0` when empty)
+ * @returns The summed estimated token count (`0` when empty)
  *
  * @example
  * ```ts
  * estimateMessages([]) // 0
- * estimateMessages([{ id: '1', role: 'user', content: 'hello' }]) // 2
+ * estimateMessages([{ id: '1', role: 'user', content: 'hello' }]) // 6  (2 content + 4 overhead)
  * ```
  */
 export declare function estimateMessages(messages: readonly MessageInterface[]): number;
@@ -2958,6 +3056,46 @@ export declare type FileState = 'created' | 'modified' | 'loaded' | 'deleted';
  */
 export declare function filterAllowList<T>(allow: readonly string[] | undefined, items: readonly T[], key: (item: T) => string): readonly T[];
 
+/**
+ * Handle one queued agent job by rehydrating it through a registry with the queue
+ * attempt's signal, then applying the shared partial-result policy.
+ *
+ * @param registry - The registry that rehydrates the serializable job
+ * @param allowPartial - Whether a partial result resolves instead of throwing
+ * @param input - The serializable agent job
+ * @param execution - The queue attempt whose signal bounds the agent
+ * @returns The settled agent result
+ */
+export declare function handleAgentQueueJob(registry: AgentRegistryInterface, allowPartial: boolean, input: AgentJobInput, execution: QueueExecution): Promise<AgentResult>;
+
+/**
+ * Handle one runner agent job by fanning out its declared children, rehydrating the
+ * parent through a registry with the controller signal, and applying the shared
+ * partial-result policy.
+ *
+ * @remarks
+ * Children are fired and tracked through the runner controller without awaiting them
+ * inline, preserving bounded-runner progress.
+ *
+ * @param registry - The registry that rehydrates serializable jobs
+ * @param allowPartial - Whether a partial result resolves instead of throwing
+ * @param controller - The runner controller for this parent job
+ * @returns The settled parent agent result
+ */
+export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, allowPartial: boolean, controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
+
+/**
+ * The coarse, deliberately-approximate per-image token cost {@link import('./helpers.js').estimateMessages}
+ * charges for each attached image.
+ *
+ * @remarks
+ * A base64 image payload's LENGTH is NOT a reliable token proxy (a vision model's actual image
+ * token cost depends on resolution / tiling, not byte size), so this is a fixed, coarse
+ * per-image estimate rather than a derivation from `image.length` — a planning heuristic, not an
+ * exact count.
+ */
+export declare const IMAGE_TOKEN_ESTIMATE = 512;
+
 /**
  * Infer a fenced-code language tag from a file path's extension — what a workspace text file
  * (or the {@link fencedFile} renderer) renders its content block as.
@@ -3190,6 +3328,23 @@ export declare interface InstructionManagerOptions {
     readonly format?: ContextSectionFormat<InstructionInterface>;
 }
 
+/**
+ * Narrow an unknown caught value to an {@link AgentError}.
+ *
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns `true` when `value` is an {@link AgentError}
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	agent.stream()
+ * } catch (error) {
+ * 	if (isAgentError(error) && error.code === 'CONCURRENCY') useSeparateAgents()
+ * }
+ * ```
+ */
+export declare function isAgentError(value: unknown): value is AgentError;
+
 /**
  * Narrow an unknown caught value to an {@link AgentJobError}.
  *
@@ -3601,6 +3756,14 @@ export declare class MemoryWorkspaceStore implements WorkspaceStoreInterface {
     delete(id: string): Promise<void>;
 }
 
+/**
+ * The estimated per-message role/framing overhead {@link import('./helpers.js').estimateMessages}
+ * adds on top of a message's content estimate — accounts for the fixed wire framing every
+ * conversation turn carries (its role tag, delimiters) that {@link import('./helpers.js').estimateTokens}'s
+ * content-only heuristic does not otherwise capture.
+ */
+export declare const MESSAGE_TOKEN_OVERHEAD = 4;
+
 /**
  * The minimal data needed to author a {@link MessageInterface} — the `id` is
  * assigned by the layer that stores it, so a caller supplies only role / content
@@ -3930,12 +4093,12 @@ export declare interface ReplaceResult {
 }
 
 /**
- * The mutable per-run sink an {@link AgentInterface}'s loop fills as it runs — the
- * assembled outcome its `stream`'s `result` promise resolves into a settled
+ * The immutable per-run outcome value an {@link AgentInterface}'s loop replaces as it runs — the
+ * assembled value its `stream`'s `result` promise resolves into a settled
  * {@link AgentResult} once the run completes.
  *
  * @remarks
- * Created fresh per run (so concurrent runs never share state) and threaded through
+ * Created fresh per run (so concurrent runs never share state) and replaced through
  * the loop: `content` accumulates the streamed assistant text, `thinking` the
  * reasoning the provider calls separated from it ({@link ProviderResult.thinking},
  * joined across calls — `undefined` until one surfaces it), `usage` the summed
@@ -3947,13 +4110,41 @@ export declare interface ReplaceResult {
  * loop reads it back to assemble the public result — not a caller-facing shape.
  */
 export declare interface RunOutcome {
-    content: string;
-    thinking: string | undefined;
-    usage: TokenUsage | undefined;
-    partial: boolean;
-    exhausted: boolean;
+    readonly content: string;
+    readonly thinking: string | undefined;
+    readonly usage: TokenUsage | undefined;
+    readonly partial: boolean;
+    readonly exhausted: boolean;
 }
 
+/**
+ * Sanitize one reported token count into a safe non-negative integer.
+ *
+ * @param value - The token count to sanitize
+ * @returns The floored count, or `0` when the value is non-finite or non-positive
+ */
+export declare function sanitizeToken(value: number): number;
+
+/**
+ * Sanitize a {@link TokenUsage} into safe, non-negative integers — the guard an agent's
+ * abort-usage path applies to a provider's partial usage before it is charged against a
+ * budget or folded into the run total.
+ *
+ * @remarks
+ * Per field (`prompt` / `completion` / `total`): a non-finite value (`NaN`, `+Infinity`,
+ * `-Infinity`) or a negative value floors to `0`; a fractional value floors to its
+ * non-negative integer part. No upper cap is applied. Total — never throws.
+ *
+ * @param usage - The token usage to sanitize (e.g. a provider's abort-partial usage)
+ * @returns A new {@link TokenUsage} with every field a safe non-negative integer
+ *
+ * @example
+ * ```ts
+ * sanitizeUsage({ prompt: -5, completion: NaN, total: 12.7 }) // { prompt: 0, completion: 0, total: 12 }
+ * ```
+ */
+export declare function sanitizeUsage(usage: TokenUsage): TokenUsage;
+
 /**
  * A named, immutable filter over a richer context's items — three optional allow-lists,
  * one per category (`instructions` / `tools` / `files`), each keyed by that category's
@@ -3988,9 +4179,9 @@ export declare class Scope implements ScopeInterface {
     #private;
     readonly id: string;
     readonly name: string;
-    readonly instructions: readonly string[] | undefined;
-    readonly tools: readonly string[] | undefined;
-    readonly files: readonly string[] | undefined;
+    readonly instructions?: readonly string[];
+    readonly tools?: readonly string[];
+    readonly files?: readonly string[];
     constructor(input: ScopeInput);
     narrow(config: ScopeConfiguration): ScopeInterface;
 }