@orkestrel/agent 0.0.6 → 0.0.8

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

@@ -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;
 }
 
 /**
@@ -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,18 @@ 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[];
 
+/**
+ * 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 +3300,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 +3728,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
@@ -3954,6 +4089,26 @@ export declare interface RunOutcome {
     exhausted: boolean;
 }
 
+/**
+ * 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