@orkestrel/agent 0.0.8 → 0.0.10

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
@@ -1132,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
@@ -1140,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;
 }
 
 /**
@@ -3056,6 +3056,34 @@ 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.
@@ -4065,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
@@ -4082,13 +4110,21 @@ 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
@@ -4143,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;
 }

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

@@ -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
@@ -1132,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
@@ -1140,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;
 }
 
 /**
@@ -3056,6 +3056,34 @@ 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.
@@ -4065,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
@@ -4082,13 +4110,21 @@ 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
@@ -4143,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;
 }