agent-bober 0.17.1 → 0.19.0

package/dist/orchestrator/agentic-loop.d.ts

@@ -1,5 +1,11 @@
-import type { LLMClient, ToolDef } from "../providers/types.js";
+import type { LLMClient, ToolDef, Message } from "../providers/types.js";
 import type { ToolHandler } from "./tools/index.js";
+import type { Effort } from "../config/schema.js";
+import type { Budget } from "./workflow/budget.js";
+import type { LoopEvent, LoopHooks } from "./loop-events.js";
+import type { SessionStore } from "./session-store.js";
+import { type SubagentDef } from "./subagents.js";
+export type { SubagentDef } from "./subagents.js";
 export interface AgenticLoopParams {
     /** Provider-agnostic LLM client. */
     client: LLMClient;
@@ -17,6 +23,23 @@ export interface AgenticLoopParams {
     maxTurns: number;
     /** Per-message max_tokens. Defaults to 16384. */
     maxTokens?: number;
+    /** Reasoning/output effort forwarded to ChatParams.effort (Anthropic only). */
+    effort?: Effort;
+    /**
+     * Optional per-run spend ceiling. Charged per turn (tokens + costUsd); a hit
+     * ceiling ends the run gracefully (stopReason 'budget_exceeded') rather than
+     * throwing — see ADR-4. `assertWithinBudget()` is never called from the loop.
+     */
+    budget?: Budget;
+    /**
+     * When true, contiguous runs of read-only-annotated tool calls (per-tool
+     * `ToolDef.readOnly === true`, derived once from `tools`) execute
+     * concurrently within a turn; everything else stays strictly serial
+     * (ADR-2). Absent/false (the default) is byte-identical to the pre-change
+     * serial for-await loop — order, error shapes, and `onToolUse` behavior
+     * are unchanged.
+     */
+    parallelReadOnlyTools?: boolean;
     /** Called when the model invokes a tool (for logging/progress). */
     onToolUse?: (name: string, input: unknown) => void;
     /** Called after each completed turn (for progress tracking). */
@@ -37,6 +60,92 @@ export interface AgenticLoopParams {
     maxNudges?: number;
     /** The nudge text appended when `completionCheck` fails. A sensible default is used if omitted. */
     nudgeMessage?: string;
+    /**
+     * Optional streaming text callback (sprint 8). Threaded into every chat call
+     * as ChatParams.onTextDelta; the Anthropic adapter invokes it per text delta.
+     * When onEvent is ALSO present, each delta additionally emits a
+     * { type:"text-delta", turn, delta } LoopEvent. Absent (and no onEvent) => no
+     * onTextDelta reaches chat, the adapter uses non-streaming create, byte-identical.
+     */
+    onTextDelta?: (delta: string) => void;
+    /**
+     * Optional structured event stream (agent-loop-capability-port sprint 5).
+     * Emits a typed `LoopEvent` at each natural loop point (init, turn-start,
+     * tool-start/tool-end, turn-end, result) — a pure host-side observation
+     * channel that adds zero tokens to the conversation and never changes loop
+     * behavior. A throwing `onEvent` is caught and logged, never crashes the
+     * loop. Absent (the default) is byte-identical to omitting it entirely.
+     */
+    onEvent?: (event: LoopEvent) => void;
+    /**
+     * Optional host-side hooks (agent-loop-capability-port sprint 5):
+     * `preToolUse` can veto a tool call (model gets an isError rejection, loop
+     * continues), `postToolUse` observes each tool result, `onStop` observes
+     * the final result exactly once. All observe-hooks are caught-and-logged
+     * on throw; a throwing `preToolUse` is treated as a fail-closed deny.
+     * Absent (the default) is byte-identical to omitting it entirely.
+     */
+    hooks?: LoopHooks;
+    /**
+     * Opt-in loop-transcript persistence (agent-loop-capability-port sprint 6).
+     * When present, the loop saves the full `Message[]` transcript + metadata
+     * to `.bober/sessions/<sessionId>.json` after every turn (crash-resumable).
+     * A save failure is caught and logged, never crashes the run. Absent (the
+     * default) is byte-identical — no files or directories are created.
+     */
+    session?: {
+        store: SessionStore;
+        sessionId: string;
+    };
+    /**
+     * A prior transcript to seed AHEAD of `userMessage` (loop resume). Use
+     * `resumeSession()` to load this from a persisted session. Absent (the
+     * default) is byte-identical to omitting it entirely.
+     */
+    initialMessages?: Message[];
+    /**
+     * Opt-in in-context auto-compaction (agent-loop-capability-port sprint 7).
+     * When set and a turn's `response.usage.inputTokens` (the PER-REQUEST
+     * prompt size, not a running total — a shrunken prompt naturally resets
+     * this, avoiding thrash) exceeds `maxContextTokens`, the loop summarizes
+     * older messages via ONE extra `client.chat` call, replacing the head with
+     * a single summary message and keeping the last `keepRecentTurns * 2`
+     * messages (default `2 * 2 = 4`) verbatim. The system prompt and the
+     * turn's own pending tool exchange are never touched — compaction only
+     * ever mutates `messages`. A failed summarization call fails open: logged,
+     * skipped for that turn, the run continues uncompacted. Absent (the
+     * default) => never compacts, byte-identical (sc-7-5).
+     */
+    compaction?: {
+        maxContextTokens: number;
+        keepRecentTurns?: number;
+        instructions?: string;
+    };
+    /**
+     * Optional abort signal (agent-loop-capability-port sprint 9). A
+     * web-standard `AbortSignal`. Checked at the top of every turn AND right
+     * after each chat response (before tool execution) — an in-flight
+     * Anthropic request is additionally cancelled mid-flight (threaded into
+     * `ChatParams.abortSignal`). When it fires, the loop ends gracefully at
+     * the next boundary/cancellation point with `stopReason: "aborted"` plus
+     * accumulated partial usage/costUsd/turnsUsed — NEVER a throw or rejected
+     * promise. Adapters without native cancellation (openai/google/claude-code)
+     * simply ignore the field; their in-flight request completes, but the
+     * loop discards that response at the post-response check rather than
+     * using it for a further turn. Absent (the default) is byte-identical.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Opt-in in-process scoped subagents (agent-loop-capability-port sprint 10).
+     * When non-empty, a `spawn_subagent` ToolDef is registered whose handler
+     * runs a NESTED `runAgenticLoop` with fresh context, the def's scoped tool
+     * subset, per-agent model/effort/maxTurns, and the SAME `Budget` instance
+     * (combined spend visible; a child cannot out-spend a parent ceiling).
+     * One-level hard cap: children always get `subagents: undefined` — no
+     * recursive nesting. Absent/empty => the tool list is byte-identical
+     * (sc-10-4).
+     */
+    subagents?: SubagentDef[];
 }
 export interface AgenticLoopResult {
     /** The final text response from the model. */
@@ -52,6 +161,27 @@ export interface AgenticLoopResult {
     };
     /** The stop reason of the final API response. */
     stopReason: string;
+    /**
+     * True only when the provider refused. Absent (not `false`) when no refusal
+     * occurred, so non-refusal runs stay byte-identical. Write-capable roles
+     * (generator/curator) MUST treat this as success:false (ADR-5).
+     */
+    refused?: boolean;
+    /**
+     * Cumulative USD cost summed across turns that reported a `costUsd`. Absent
+     * (not `undefined`-valued — the key itself is omitted) when no turn reported
+     * a cost, so cost-free runs stay byte-identical.
+     */
+    costUsd?: number;
+}
+/**
+ * Thrown by `chatWithRetry` (agent-loop-capability-port sprint 9) when a chat
+ * call fails because the run's `abortSignal` fired. Never retried and never
+ * escapes `runAgenticLoop` — the loop's chat catch maps it to a graceful
+ * `stopReason: "aborted"` return instead of `"error"`.
+ */
+export declare class AbortedError extends Error {
+    constructor();
 }
 export interface CoerceJsonParams {
     client: LLMClient;
@@ -102,4 +232,33 @@ export declare function coerceJsonOutput(params: CoerceJsonParams): Promise<stri
  * @returns The final text response and metadata about the conversation.
  */
 export declare function runAgenticLoop(params: AgenticLoopParams): Promise<AgenticLoopResult>;
+/**
+ * Load a persisted transcript so a NEW `runAgenticLoop` call can continue it
+ * with full prior context: pass the returned `initialMessages` (seeded
+ * AHEAD of the new `userMessage`) alongside `session: { store, sessionId }`
+ * so new turns append to the same session file.
+ *
+ * Never throws. A missing or corrupt session file returns a typed
+ * `{ error }` result instead — conceptually aligned with the loop's own
+ * `stopReason: "error"` path, but this runs BEFORE the loop starts, so it is
+ * a separate discriminated-union return, not a shared code path. The loop is
+ * never started on the error branch, so no empty session ever silently
+ * replaces the requested one (sc-6-5).
+ */
+export declare function resumeSession(store: SessionStore, sessionId: string): Promise<{
+    initialMessages: Message[];
+    sessionId: string;
+} | {
+    error: string;
+}>;
+/**
+ * Copy the transcript at `sessionId` into a new session file so a new
+ * `runAgenticLoop` invocation can branch from it without mutating the
+ * original (sc-6-3). `newId` may be supplied explicitly (e.g. by tests);
+ * when omitted, a deterministic id is derived from `sessionId` + the
+ * store's injected clock (`sessionForkId` — no argless randomness).
+ *
+ * @returns The new session id (== `newId` when supplied).
+ */
+export declare function forkSession(store: SessionStore, sessionId: string, newId?: string): Promise<string>;
 //# sourceMappingURL=agentic-loop.d.ts.map

package/dist/orchestrator/agentic-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentic-loop.d.ts","sourceRoot":"","sources":["../../src/orchestrator/agentic-loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAA4D,MAAM,uBAAuB,CAAC;AAE1H,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKpD,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,MAAM,EAAE,SAAS,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,sDAAsD;IACtD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,gEAAgE;IAChE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC/D;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAyED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,MAAM,CAAC,CA0CjB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CA0L5B"}
+{"version":3,"file":"agentic-loop.d.ts","sourceRoot":"","sources":["../../src/orchestrator/agentic-loop.ts"],"names":[],"mappings":"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"}