bare-agent 0.42.0 → 0.44.0

package/src/provider-ollama.js

@@ -6,6 +6,7 @@ const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
+const { parseToolCalls } = require('./provider-toolcalls');
 
 // BA-24: raw Ollama usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
 const OLLAMA_USAGE_KEYS = ['prompt_eval_count', 'eval_count'];
@@ -26,6 +27,10 @@ const OLLAMA_USAGE_KEYS = ['prompt_eval_count', 'eval_count'];
 class OllamaProvider {
   /**
    * @param {OllamaOptions} [options]
+   * @when you want local models via Ollama as the Loop's provider — no API key, self-hosted
+   * @fails normalizes stopReason (promoting a complete tool call) and usage; a malformed tool-call JSON returns no usable calls with usage metered; a socket idle/deadline cut rejects with a retryable error.
+   * @example
+   *   const provider = new OllamaProvider({ model: 'llama3' });
    */
   constructor(options = {}) {
     this.model = options.model || 'llama3.2';
@@ -85,8 +90,11 @@ class OllamaProvider {
     });
     const msg = data.message || {};
 
-    /** @type {import('../types').ToolCall[]} */
-    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+    // BA-27: Ollama returns `function.arguments` as an OBJECT for well-formed calls, but some builds
+    // pass it through as a model-generated STRING — a malformed one must not throw here (the round
+    // already billed; a throw loses usage + hangs metering). Mirror the OpenAI path: no usable calls
+    // + a marker, never repair. The object case is untouched (JSON.parse only runs on a string).
+    const { toolCalls, malformedToolCall } = parseToolCalls(msg.tool_calls, (/** @type {any} */ tc) => ({
       id: tc.id || `call_${Date.now()}`,
       name: tc.function.name,
       arguments: typeof tc.function.arguments === 'string'
@@ -97,6 +105,7 @@ class OllamaProvider {
     return {
       text: msg.content || '',
       toolCalls,
+      ...(malformedToolCall && { malformedToolCall }),
       model: data.model || this.model,
       // BA-6: `length` ⇒ cut off at num_predict. VERIFIED LIVE on qwen2.5:0.5b
       // (`poc/ba6-stop-reason-gemini-ollama.mjs`): stop→end_turn, length→max_tokens. Lifecycle values

package/src/provider-openai.d.ts

@@ -68,6 +68,10 @@ export type OpenAIOptions = {
 export class OpenAIProvider {
     /**
      * @param {OpenAIOptions} [options]
+     * @when you want OpenAI or any OpenAI-compatible endpoint as the Loop's provider — tool-calling, toolChoice, and a custom baseUrl
+     * @fails throws on a missing apiKey; a malformed tool-call JSON returns no usable calls with usage still metered (BA-27); a socket idle/deadline/transport cut rejects with a retryable error.
+     * @example
+     *   const provider = new OpenAIProvider({ apiKey, model: 'gpt-5' });
      */
     constructor(options?: OpenAIOptions);
     apiKey: string | undefined;

package/src/provider-openai.js

@@ -7,6 +7,7 @@ const { requestWithTemperatureFallback } = require('./provider-temperature');
 const { normalizeStopReason } = require('./provider-stop-reason');
 const { resolveTimeoutMs, applyRequestBounds, guardResponseSettles } = require('./provider-http');
 const { hasUsageSignal } = require('./provider-usage');
+const { parseToolCalls } = require('./provider-toolcalls');
 
 // BA-24: raw OpenAI usage fields. Any present (even 0) ⇒ a usage signal; none ⇒ null (unpriceable).
 const OPENAI_USAGE_KEYS = ['prompt_tokens', 'completion_tokens', 'prompt_tokens_details'];
@@ -30,7 +31,13 @@ function toOpenAIToolChoice(choice) {
   if (typeof choice === 'object' && typeof choice.name === 'string' && choice.name) {
     return { type: 'function', function: { name: choice.name } };
   }
-  throw new ProviderError(`[OpenAIProvider] invalid toolChoice: expected 'auto', 'required', or { name }, got ${JSON.stringify(choice)}`);
+  let describedChoice;
+  try {
+    describedChoice = JSON.stringify(choice);
+  } catch {
+    describedChoice = '<unserializable>';
+  }
+  throw new ProviderError(`[OpenAIProvider] invalid toolChoice: expected 'auto', 'required', or { name }, got ${describedChoice}`);
 }
 
 /** @param {string} hostname @returns {boolean} */
@@ -69,6 +76,10 @@ function isLoopbackHost(hostname) {
 class OpenAIProvider {
   /**
    * @param {OpenAIOptions} [options]
+   * @when you want OpenAI or any OpenAI-compatible endpoint as the Loop's provider — tool-calling, toolChoice, and a custom baseUrl
+   * @fails throws on a missing apiKey; a malformed tool-call JSON returns no usable calls with usage still metered (BA-27); a socket idle/deadline/transport cut rejects with a retryable error.
+   * @example
+   *   const provider = new OpenAIProvider({ apiKey, model: 'gpt-5' });
    */
   constructor(options = {}) {
     this.apiKey = options.apiKey?.trim();
@@ -125,11 +136,27 @@ class OpenAIProvider {
       stripTemperature: () => { delete body.temperature; },
       warnOnce: () => this._warnTemperatureDropped(),
     });
+    // BA-27: a successful 200 whose body carries no `choices` (some OpenAI-compat servers return a
+    // 4xx-shaped error object with HTTP 200) reached `data.choices[0]` as a bare TypeError with no
+    // context. Throw a ProviderError carrying the first ~300 bytes of the body so it can be told apart.
+    if (!Array.isArray(data.choices) || data.choices.length === 0) {
+      // The `context.bound:'no-choices'` marker ALWAYS distinguishes a 4xx-in-200 from other failures.
+      // The raw body snippet is gated behind `exposeErrorBody` (default off) like every other error path
+      // here — an unexpected field in a compat server's error body must not leak into logs/audit rows
+      // (err.message flows into Loop.run().error) unless the caller opts in.
+      throw new ProviderError(
+        `[OpenAIProvider] response has no choices` +
+          (this.exposeErrorBody ? `: ${JSON.stringify(data).slice(0, 300)}` : ''),
+        /** @type {any} */ ({ context: { bound: 'no-choices' }, body: this.exposeErrorBody ? data : undefined })
+      );
+    }
     const choice = data.choices[0];
     const msg = choice.message;
 
-    /** @type {import('../types').ToolCall[]} */
-    const toolCalls = (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
+    // BA-27: `function.arguments` is a model-generated JSON STRING — a malformed one (extra brace,
+    // truncated object) must NOT throw here (the round already billed; a throw loses usage + hangs
+    // metering). parseToolCalls returns no usable calls + a marker; usage/model still flow below.
+    const { toolCalls, malformedToolCall } = parseToolCalls(msg.tool_calls, (/** @type {any} */ tc) => ({
       id: tc.id,
       name: tc.function.name,
       arguments: JSON.parse(tc.function.arguments),
@@ -138,6 +165,7 @@ class OpenAIProvider {
     return {
       text: msg.content || '',
       toolCalls,
+      ...(malformedToolCall && { malformedToolCall }),
       model: data.model || this.model,
       // BA-6: `length` ⇒ cut off at the output cap (normalized to 'max_tokens'). Note OpenAI refuses to
       // emit a tool call it cannot finish — it 400s instead — so a truncated round here carries no

package/src/provider-toolcalls.d.ts

@@ -0,0 +1,29 @@
+export type ToolCall = import("../types").ToolCall;
+/** @typedef {import('../types').ToolCall} ToolCall */
+/**
+ * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
+ * malformed arguments.
+ *
+ * OpenAI-compatible providers return `function.arguments` as a JSON STRING the model generated, so a
+ * model that emits syntactically-broken JSON (an extra brace, a truncated object — seen live on
+ * deepseek-flash and other compat servers) makes a bare `JSON.parse` throw a `SyntaxError`. That throw
+ * lands AFTER the HTTP round already succeeded and `usage` came back, so it loses the billed round and
+ * hangs any metering, and no caller can tell "the model emitted bad arguments" from a transport fault.
+ *
+ * Instead: on the FIRST unparseable call, return NO usable tool calls (`toolCalls: []`) plus a marker
+ * `{ name, error }`. The caller treats it as "no usable tool call" and retries; usage/model still flow
+ * so the round is metered. We NEVER repair the JSON — a guessed brace could execute the wrong action.
+ * All-or-nothing (mirrors BA-4's refusal to execute a truncated round's calls): a partial set risks
+ * running half a decomposed intent, so one bad call voids the whole round's calls.
+ *
+ * @param {any[]} rawToolCalls - provider-native tool-call entries (may be undefined/empty)
+ * @param {(tc: any) => ToolCall} mapOne - maps one raw entry to a ToolCall; MAY throw on bad arguments
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string } }}
+ */
+export function parseToolCalls(rawToolCalls: any[], mapOne: (tc: any) => ToolCall): {
+    toolCalls: ToolCall[];
+    malformedToolCall?: {
+        name: string | undefined;
+        error: string;
+    };
+};

package/src/provider-toolcalls.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/** @typedef {import('../types').ToolCall} ToolCall */
+
+/**
+ * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
+ * malformed arguments.
+ *
+ * OpenAI-compatible providers return `function.arguments` as a JSON STRING the model generated, so a
+ * model that emits syntactically-broken JSON (an extra brace, a truncated object — seen live on
+ * deepseek-flash and other compat servers) makes a bare `JSON.parse` throw a `SyntaxError`. That throw
+ * lands AFTER the HTTP round already succeeded and `usage` came back, so it loses the billed round and
+ * hangs any metering, and no caller can tell "the model emitted bad arguments" from a transport fault.
+ *
+ * Instead: on the FIRST unparseable call, return NO usable tool calls (`toolCalls: []`) plus a marker
+ * `{ name, error }`. The caller treats it as "no usable tool call" and retries; usage/model still flow
+ * so the round is metered. We NEVER repair the JSON — a guessed brace could execute the wrong action.
+ * All-or-nothing (mirrors BA-4's refusal to execute a truncated round's calls): a partial set risks
+ * running half a decomposed intent, so one bad call voids the whole round's calls.
+ *
+ * @param {any[]} rawToolCalls - provider-native tool-call entries (may be undefined/empty)
+ * @param {(tc: any) => ToolCall} mapOne - maps one raw entry to a ToolCall; MAY throw on bad arguments
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string } }}
+ */
+function parseToolCalls(rawToolCalls, mapOne) {
+  const raw = rawToolCalls || [];
+  /** @type {ToolCall[]} */
+  const toolCalls = [];
+  for (const tc of raw) {
+    try {
+      toolCalls.push(mapOne(tc));
+    } catch (e) {
+      return {
+        toolCalls: [],
+        malformedToolCall: {
+          name: tc && tc.function ? tc.function.name : undefined,
+          error: e instanceof Error ? e.message : String(e),
+        },
+      };
+    }
+  }
+  return { toolCalls };
+}
+
+module.exports = { parseToolCalls };

package/src/recurse-retrieval.d.ts

@@ -99,6 +99,12 @@ export function normalizeCorpus(corpus: unknown): Slice[];
  * @param {{recall: Function}} litectx
  * @param {{kinds?: string[], n?: number}} [opts]
  * @returns {ToolDef}
+ * @category integration
+ * @when you want to give a recurse worker a needle-search handle over litectx (embeddings recall for the relevant few) — for FINDING, never counting
+ * @fails returns matched bodies only and CANNOT count (the completeness guard blocks a "how many" ask before it is offered); a dead window yields nothing, never a fabricated hit.
+ * @example
+ *   const tool = buildSearchTool(litectx, { n: 8 });
+ *   await recurse(task, ctx, { retrieval: 'search', tools: [tool] });
  */
 export function buildSearchTool(litectx: {
     recall: Function;
@@ -114,6 +120,11 @@ export function buildSearchTool(litectx: {
  * OFF to stay exact — deferred; the code-side filter is the embeddings-free path shipped now.)
  * @param {Slice[]} corpus - The validated slice-source.
  * @returns {ToolDef}
+ * @when you want an embeddings-free, exact AND-term filter handle over a slice-source — complete over its slices, for precise lexical matches
+ * @fails only as good as a lexical rule; complete over the slices it is given (no recall cap) but matches nothing outside them.
+ * @example
+ *   const tool = buildExactTool(corpus);
+ *   await recurse(task, ctx, { retrieval: 'exact', tools: [tool] });
  */
 export function buildExactTool(corpus: Slice[]): ToolDef;
 /**
@@ -131,6 +142,11 @@ export function buildExactTool(corpus: Slice[]): ToolDef;
  *   materialized lazily on first call and cached for the tool's lifetime.
  * @param {{provider: Provider, window?: number, passes?: number, ctx?: object, onLlmResult?: Function, policy?: Function}} opts
  * @returns {ToolDef}
+ * @when you need the complete count/"all" path — scan every slice + LLM-judge + code-count — the only retrieval mode that can honestly answer "how many"
+ * @fails a dead window surfaces as `INCOMPLETE — the count is a floor`, never a clean number over a hole; a governance HaltError propagates clean.
+ * @example
+ *   const tool = buildScanTool(corpus, { provider, window: 8 });
+ *   await recurse('how many mention X', ctx, { tools: [tool] });
  */
 export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts: {
     provider: Provider;
@@ -154,6 +170,12 @@ export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts:
  * @param {{enumerate: Function}} litectx
  * @param {{kind?: 'fact'|'episode', pageSize?: number}} [opts]
  * @returns {() => Promise<Slice[]>}
+ * @category integration
+ * @when you want a resident slice-source that paginates a litectx corpus via enumerate — for a corpus ALREADY in litectx, feeding scan/partition
+ * @fails never ingests a fresh corpus (strictly worse than scanning an in-hand array); returns an async source materialized once and cached.
+ * @example
+ *   const corpus = litectxCorpus(litectx, { kind: 'fact' });
+ *   await recurse(task, ctx, { mode: 'partition', corpus });
  */
 export function litectxCorpus(litectx: {
     enumerate: Function;

package/src/recurse-retrieval.js

@@ -188,6 +188,12 @@ function normalizeCorpus(corpus) {
  * @param {{recall: Function}} litectx
  * @param {{kinds?: string[], n?: number}} [opts]
  * @returns {ToolDef}
+ * @category integration
+ * @when you want to give a recurse worker a needle-search handle over litectx (embeddings recall for the relevant few) — for FINDING, never counting
+ * @fails returns matched bodies only and CANNOT count (the completeness guard blocks a "how many" ask before it is offered); a dead window yields nothing, never a fabricated hit.
+ * @example
+ *   const tool = buildSearchTool(litectx, { n: 8 });
+ *   await recurse(task, ctx, { retrieval: 'search', tools: [tool] });
  */
 function buildSearchTool(litectx, opts = {}) {
   const kinds = Array.isArray(opts.kinds) && opts.kinds.length ? opts.kinds : ['fact', 'episode'];
@@ -224,6 +230,11 @@ function buildSearchTool(litectx, opts = {}) {
  * OFF to stay exact — deferred; the code-side filter is the embeddings-free path shipped now.)
  * @param {Slice[]} corpus - The validated slice-source.
  * @returns {ToolDef}
+ * @when you want an embeddings-free, exact AND-term filter handle over a slice-source — complete over its slices, for precise lexical matches
+ * @fails only as good as a lexical rule; complete over the slices it is given (no recall cap) but matches nothing outside them.
+ * @example
+ *   const tool = buildExactTool(corpus);
+ *   await recurse(task, ctx, { retrieval: 'exact', tools: [tool] });
  */
 function buildExactTool(corpus) {
   const slices = normalizeCorpus(corpus);
@@ -269,6 +280,11 @@ function buildExactTool(corpus) {
  *   materialized lazily on first call and cached for the tool's lifetime.
  * @param {{provider: Provider, window?: number, passes?: number, ctx?: object, onLlmResult?: Function, policy?: Function}} opts
  * @returns {ToolDef}
+ * @when you need the complete count/"all" path — scan every slice + LLM-judge + code-count — the only retrieval mode that can honestly answer "how many"
+ * @fails a dead window surfaces as `INCOMPLETE — the count is a floor`, never a clean number over a hole; a governance HaltError propagates clean.
+ * @example
+ *   const tool = buildScanTool(corpus, { provider, window: 8 });
+ *   await recurse('how many mention X', ctx, { tools: [tool] });
  */
 function buildScanTool(corpus, opts) {
   /** @type {Slice[]|null} */
@@ -337,6 +353,12 @@ const ENUM_PAGE = 200;
  * @param {{enumerate: Function}} litectx
  * @param {{kind?: 'fact'|'episode', pageSize?: number}} [opts]
  * @returns {() => Promise<Slice[]>}
+ * @category integration
+ * @when you want a resident slice-source that paginates a litectx corpus via enumerate — for a corpus ALREADY in litectx, feeding scan/partition
+ * @fails never ingests a fresh corpus (strictly worse than scanning an in-hand array); returns an async source materialized once and cached.
+ * @example
+ *   const corpus = litectxCorpus(litectx, { kind: 'fact' });
+ *   await recurse(task, ctx, { mode: 'partition', corpus });
  */
 function litectxCorpus(litectx, opts = {}) {
   const kind = opts.kind === 'episode' ? 'episode' : 'fact'; // enumerate v1 is the memory axis (fact/episode)

package/src/recurse.d.ts

@@ -604,5 +604,11 @@ export type Slice = {
  * @returns {Promise<RecurseResult>} `{ result, verdict, receipts }` on convergence; `{ incomplete, best,
  *   receipts }` on guard exhaustion. NEVER a fabricated success (RC-9).
  * @throws {Error} no provider supplied (on neither `ctx.provider` nor `opts.provider`).
+ * @when a task is too big for one model pass and you want it split, fanned out, verified, and merged — with total cost capped by a gate
+ * @fails returns `{incomplete, best}` on guard exhaustion or a dead worker (never a faked pass); a gate HaltError exits clean. Cost is open by design — run under a budget gate.
+ * @example
+ *   const ctx = wireGate(gate);
+ *   const { result, incomplete } = await recurse('audit 400 logs', ctx, { provider, corpus });
+ *   if (incomplete) retryOrEscalate(result);
  */
 export function recurse(task: string, ctx?: RecurseCtx, opts?: RecurseOptions): Promise<RecurseResult>;

package/src/recurse.js

@@ -395,6 +395,12 @@ function auditSafeCtx(ctx, overrides = {}) {
  * @returns {Promise<RecurseResult>} `{ result, verdict, receipts }` on convergence; `{ incomplete, best,
  *   receipts }` on guard exhaustion. NEVER a fabricated success (RC-9).
  * @throws {Error} no provider supplied (on neither `ctx.provider` nor `opts.provider`).
+ * @when a task is too big for one model pass and you want it split, fanned out, verified, and merged — with total cost capped by a gate
+ * @fails returns `{incomplete, best}` on guard exhaustion or a dead worker (never a faked pass); a gate HaltError exits clean. Cost is open by design — run under a budget gate.
+ * @example
+ *   const ctx = wireGate(gate);
+ *   const { result, incomplete } = await recurse('audit 400 logs', ctx, { provider, corpus });
+ *   if (incomplete) retryOrEscalate(result);
  */
 async function recurse(task, ctx = {}, opts = {}) {
   if (typeof task !== 'string' || task.length === 0) {

package/src/refine.d.ts

@@ -98,5 +98,10 @@ export type RefineOutcome = {
  *
  * @param {RefineOptions} options
  * @returns {Promise<RefineOutcome>}
+ * @when you have a caller-supplied attempt + evaluate pair and want to iterate generate → grade → regenerate until it passes or hits a bound
+ * @fails returns the last outcome on maxIterations or a terminal `failed` verdict (never a faked pass); a HaltError from either callback propagates clean.
+ * @example
+ *   const { result, passed } = await refine({ attempt, evaluate, maxIterations: 3 });
+ *   if (!passed) escalate(result);
  */
 export function refine(options: RefineOptions): Promise<RefineOutcome>;

package/src/refine.js

@@ -38,6 +38,11 @@
  *
  * @param {RefineOptions} options
  * @returns {Promise<RefineOutcome>}
+ * @when you have a caller-supplied attempt + evaluate pair and want to iterate generate → grade → regenerate until it passes or hits a bound
+ * @fails returns the last outcome on maxIterations or a terminal `failed` verdict (never a faked pass); a HaltError from either callback propagates clean.
+ * @example
+ *   const { result, passed } = await refine({ attempt, evaluate, maxIterations: 3 });
+ *   if (!passed) escalate(result);
  */
 async function refine(options) {
   const { attempt, evaluate } = options;

package/src/remember.d.ts

@@ -84,6 +84,11 @@ export type Store = import("../types").Store;
  *   Each is a transcript chunk — a raw string, or an object with `content`/`text`. Empty/blank spans are skipped.
  * @param {RememberOptions} options
  * @returns {Promise<RememberOutcome>}
+ * @when you want to distill durable facts from harvested transcript spans and persist them through a Store socket (the consolidation pass)
+ * @fails skips empty spans and never fabricates; a provider HaltError propagates clean. Each pass forwards usage via onLlmResult; a fact counts once via ctx.recordMemoryOp.
+ * @example
+ *   const { facts } = await remember(spans, { provider, store });
+ *   console.log(`consolidated ${facts.length} durable facts`);
  */
 export function remember(spans: Array<string | {
     content?: string;

package/src/remember.js

@@ -73,6 +73,11 @@ const DISTILL_PROMPT = [
  *   Each is a transcript chunk — a raw string, or an object with `content`/`text`. Empty/blank spans are skipped.
  * @param {RememberOptions} options
  * @returns {Promise<RememberOutcome>}
+ * @when you want to distill durable facts from harvested transcript spans and persist them through a Store socket (the consolidation pass)
+ * @fails skips empty spans and never fabricates; a provider HaltError propagates clean. Each pass forwards usage via onLlmResult; a fact counts once via ctx.recordMemoryOp.
+ * @example
+ *   const { facts } = await remember(spans, { provider, store });
+ *   console.log(`consolidated ${facts.length} durable facts`);
  */
 async function remember(spans, options = /** @type {RememberOptions} */ ({})) {
   if (!Array.isArray(spans)) throw new Error('[remember] spans must be an array');

package/src/retry.d.ts

@@ -21,7 +21,14 @@ export type RetryOptions = {
     jitter?: number | boolean | "full" | "equal" | undefined;
 };
 export class Retry {
-    /** @param {RetryOptions} [options={}] */
+    /**
+     * @param {RetryOptions} [options={}]
+     * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with
+     * @fails rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.
+     * @example
+     *   const retry = new Retry({ maxAttempts: 3, jitter: true });
+     *   const res = await retry.call(() => provider.generate(msgs));
+     */
     constructor(options?: RetryOptions);
     maxAttempts: number;
     backoff: number | "linear" | "exponential";

package/src/retry.js

@@ -23,7 +23,14 @@ const DEFAULT_RETRY_ON = (err) => {
 };
 
 class Retry {
-  /** @param {RetryOptions} [options={}] */
+  /**
+   * @param {RetryOptions} [options={}]
+   * @when you want backoff-with-jitter around a flaky async call (a provider request, a plan step) — the retry seam Loop and runPlan wrap providers with
+   * @fails rethrows the last error once attempts are exhausted; by default only transient errors (429/5xx/ECONNRESET/ETIMEDOUT) are retried.
+   * @example
+   *   const retry = new Retry({ maxAttempts: 3, jitter: true });
+   *   const res = await retry.call(() => provider.generate(msgs));
+   */
   constructor(options = {}) {
     this.maxAttempts = options.maxAttempts !== undefined ? options.maxAttempts : 3;
     this.backoff = options.backoff || 'exponential';

package/src/run-plan.d.ts

@@ -122,5 +122,10 @@ export type StepResult = {
  * @throws {Error} `[runPlan] executeFn must be a function` — when executeFn is not a function.
  * @throws {Error} `[runPlan] duplicate step id: "X"` — when two steps share an id.
  * @throws {Error} `[runPlan] step "X" depends on unknown step "Y"` — when dependsOn references missing id.
+ * @when you have a step DAG from the Planner and want to execute it with wave-based parallelism (independent steps run concurrently)
+ * @fails throws on a malformed DAG (empty steps, non-function executeFn, duplicate ids, unknown dependency); a step's own error surfaces per StepResult, never crashing the wave.
+ * @example
+ *   const steps = await planner.plan(goal);
+ *   const results = await runPlan(steps, step => execute(step));
  */
 export function runPlan(steps: Step[], executeFn: (step: Step) => any, options?: RunPlanOptions): Promise<StepResult[]>;

package/src/run-plan.js

@@ -47,6 +47,11 @@
  * @throws {Error} `[runPlan] executeFn must be a function` — when executeFn is not a function.
  * @throws {Error} `[runPlan] duplicate step id: "X"` — when two steps share an id.
  * @throws {Error} `[runPlan] step "X" depends on unknown step "Y"` — when dependsOn references missing id.
+ * @when you have a step DAG from the Planner and want to execute it with wave-based parallelism (independent steps run concurrently)
+ * @fails throws on a malformed DAG (empty steps, non-function executeFn, duplicate ids, unknown dependency); a step's own error surfaces per StepResult, never crashing the wave.
+ * @example
+ *   const steps = await planner.plan(goal);
+ *   const results = await runPlan(steps, step => execute(step));
  */
 async function runPlan(steps, executeFn, options = {}) {
   if (!Array.isArray(steps) || steps.length === 0) {

package/src/scheduler.d.ts

@@ -48,7 +48,14 @@ export type SchedulerOptions = {
  * @property {((err: any, job: Job) => void)|null} [onError] - Handler errors callback.
  */
 export class Scheduler {
-    /** @param {SchedulerOptions} [options={}] */
+    /**
+     * @param {SchedulerOptions} [options={}]
+     * @when you need to fire agent turns on a schedule — cron expressions or relative intervals — driven by a periodic tick
+     * @fails an errored job routes to the onError handler and never crashes the tick loop; a malformed cron/interval is rejected when the job is added.
+     * @example
+     *   const sched = new Scheduler({ interval: 60000 });
+     *   sched.add({ id: 'poll', cron: '0 * * * *', run });
+     */
     constructor(options?: SchedulerOptions);
     _file: string | null;
     _interval: number;

package/src/scheduler.js

@@ -32,7 +32,14 @@ const { readFileSync, writeFileSync, existsSync } = require('node:fs');
  */
 
 class Scheduler {
-  /** @param {SchedulerOptions} [options={}] */
+  /**
+   * @param {SchedulerOptions} [options={}]
+   * @when you need to fire agent turns on a schedule — cron expressions or relative intervals — driven by a periodic tick
+   * @fails an errored job routes to the onError handler and never crashes the tick loop; a malformed cron/interval is rejected when the job is added.
+   * @example
+   *   const sched = new Scheduler({ interval: 60000 });
+   *   sched.add({ id: 'poll', cron: '0 * * * *', run });
+   */
   constructor(options = {}) {
     this._file = options.file || null;
     this._interval = options.interval || 60000;

package/src/skills.d.ts

@@ -24,6 +24,12 @@ export class SkillRegistry {
      *   skill tool that would collide with one is rejected at `register` time. Tool names are globally unique
      *   for DISPATCH (PRD §2.6, D6) — this is the collision check across native + MCP + skills, not security.
      * @param {string} [options.metaToolName='skill_use'] - Override the meta-tool name if `skill_use` is taken.
+     * @when you want to expose operator-registered skill bundles to a model by progressive disclosure — one meta-tool whose catalog unlocks a skill's tools on demand
+     * @fails register() rejects an unsafe or colliding name fail-fast and commits nothing on failure; governance is unchanged — discovery never authorizes.
+     * @example
+     *   const skills = new SkillRegistry();
+     *   skills.register({ name: 'deploy', description: 'ship a release', instructions: '...', tools: [] });
+     *   const loop = new Loop({ provider, tools: skills.activeTools });
      */
     constructor(options?: {
         reserved?: Iterable<string> | undefined;

package/src/skills.js

@@ -51,6 +51,12 @@ class SkillRegistry {
    *   skill tool that would collide with one is rejected at `register` time. Tool names are globally unique
    *   for DISPATCH (PRD §2.6, D6) — this is the collision check across native + MCP + skills, not security.
    * @param {string} [options.metaToolName='skill_use'] - Override the meta-tool name if `skill_use` is taken.
+   * @when you want to expose operator-registered skill bundles to a model by progressive disclosure — one meta-tool whose catalog unlocks a skill's tools on demand
+   * @fails register() rejects an unsafe or colliding name fail-fast and commits nothing on failure; governance is unchanged — discovery never authorizes.
+   * @example
+   *   const skills = new SkillRegistry();
+   *   skills.register({ name: 'deploy', description: 'ship a release', instructions: '...', tools: [] });
+   *   const loop = new Loop({ provider, tools: skills.activeTools });
    */
   constructor(options = {}) {
     /** @type {Map<string, {name: string, description: string, instructions: string, tools: ToolDef[]}>} */

package/src/stash.d.ts

@@ -19,6 +19,11 @@ export type ToolDef = import("../types").ToolDef;
  * @param {number} [options.compaction.keepRecentTurns=3] - Recent turns to keep at the END (live working set).
  * @param {(msg: string) => void} [options.onNote=console.warn] - Sink for the loud one-time/backstop notes.
  * @returns {{ skill: { name: string, description: string, instructions: string, tools: ToolDef[] }, trim: (msgs: any[], ctx: any) => Promise<any[]>, restoreHandles: () => string[] }}
+ * @when you need compaction-first context hygiene — a registrable skill whose checkpoint/compact/restore tools fold the live transcript at round boundaries
+ * @fails never throws for a fold; degrades LOUDLY to a lossless park when summarize is unwired. Preserves tool-pairing and role alternation by construction.
+ * @example
+ *   const { skill, trim } = createStashSkill({ compaction: { ceilingTokens: 100000 } });
+ *   const loop = new Loop({ provider, trim });
  */
 export function createStashSkill(options?: {
     defaultStrategy?: "summarize" | "stash" | undefined;

package/src/stash.js

@@ -82,6 +82,11 @@ const INSTRUCTIONS =
  * @param {number} [options.compaction.keepRecentTurns=3] - Recent turns to keep at the END (live working set).
  * @param {(msg: string) => void} [options.onNote=console.warn] - Sink for the loud one-time/backstop notes.
  * @returns {{ skill: { name: string, description: string, instructions: string, tools: ToolDef[] }, trim: (msgs: any[], ctx: any) => Promise<any[]>, restoreHandles: () => string[] }}
+ * @when you need compaction-first context hygiene — a registrable skill whose checkpoint/compact/restore tools fold the live transcript at round boundaries
+ * @fails never throws for a fold; degrades LOUDLY to a lossless park when summarize is unwired. Preserves tool-pairing and role alternation by construction.
+ * @example
+ *   const { skill, trim } = createStashSkill({ compaction: { ceilingTokens: 100000 } });
+ *   const loop = new Loop({ provider, trim });
  */
 function createStashSkill(options = {}) {
   const {

package/src/state.d.ts

@@ -12,7 +12,14 @@ export type Task = {
  * @property {string} updatedAt
  */
 export class StateMachine extends EventEmitter<[never]> {
-    /** @param {{ file?: string|null }} [options={}] */
+    /**
+     * @param {{ file?: string|null }} [options={}]
+     * @when you need to track task lifecycle (pending/running/done/failed/waiting/cancelled) with enforced transitions and optional file persistence
+     * @fails rejects an illegal state transition and never throws on a valid one; state changes are emitted as events.
+     * @example
+     *   const sm = new StateMachine();
+     *   sm.create('t1'); sm.transition('t1', 'running');
+     */
     constructor(options?: {
         file?: string | null;
     });

package/src/state.js

@@ -21,7 +21,14 @@ const TRANSITIONS = {
  */
 
 class StateMachine extends EventEmitter {
-  /** @param {{ file?: string|null }} [options={}] */
+  /**
+   * @param {{ file?: string|null }} [options={}]
+   * @when you need to track task lifecycle (pending/running/done/failed/waiting/cancelled) with enforced transitions and optional file persistence
+   * @fails rejects an illegal state transition and never throws on a valid one; state changes are emitted as events.
+   * @example
+   *   const sm = new StateMachine();
+   *   sm.create('t1'); sm.transition('t1', 'running');
+   */
   constructor(options = {}) {
     super();
     this.file = options.file || null;

package/src/store-jsonfile.d.ts

@@ -42,6 +42,11 @@ export class JsonFileStore {
     /**
      * @param {{ path?: string }} [options]
      * @throws {Error} `[JsonFileStore] requires options.path` — when path is missing.
+     * @name JsonFile
+     * @when you want zero-dependency JSON-file storage for Memory (store/search/get/delete) — the simplest durable backend, no native deps
+     * @fails throws on a missing path; implements the four-verb Store socket over a plain JSON file.
+     * @example
+     *   const store = new JsonFile({ path: './agent.json' });
      */
     constructor(options?: {
         path?: string;

package/src/store-jsonfile.js

@@ -31,6 +31,11 @@ class JsonFileStore {
   /**
    * @param {{ path?: string }} [options]
    * @throws {Error} `[JsonFileStore] requires options.path` — when path is missing.
+   * @name JsonFile
+   * @when you want zero-dependency JSON-file storage for Memory (store/search/get/delete) — the simplest durable backend, no native deps
+   * @fails throws on a missing path; implements the four-verb Store socket over a plain JSON file.
+   * @example
+   *   const store = new JsonFile({ path: './agent.json' });
    */
   constructor(options = {}) {
     if (!options.path) throw new Error('[JsonFileStore] requires options.path');

package/src/store-sqlite.d.ts

@@ -43,6 +43,11 @@ export class SQLiteStore {
      * @param {{ path?: string }} [options]
      * @throws {Error} `[SQLiteStore] requires options.path` — when path is missing.
      * @throws {Error} `[SQLiteStore] requires better-sqlite3` — when peer dep is not installed.
+     * @name SQLite
+     * @when you want durable, queryable SQLite-backed storage for Memory (store/search/get/delete) persisted on disk
+     * @fails throws on a missing path or an absent better-sqlite3 peer dep; implements the four-verb Store socket.
+     * @example
+     *   const store = new SQLite({ path: './agent.db' });
      */
     constructor(options?: {
         path?: string;

package/src/store-sqlite.js

@@ -23,6 +23,11 @@ class SQLiteStore {
    * @param {{ path?: string }} [options]
    * @throws {Error} `[SQLiteStore] requires options.path` — when path is missing.
    * @throws {Error} `[SQLiteStore] requires better-sqlite3` — when peer dep is not installed.
+   * @name SQLite
+   * @when you want durable, queryable SQLite-backed storage for Memory (store/search/get/delete) persisted on disk
+   * @fails throws on a missing path or an absent better-sqlite3 peer dep; implements the four-verb Store socket.
+   * @example
+   *   const store = new SQLite({ path: './agent.db' });
    */
   constructor(options = {}) {
     if (!options.path) throw new Error('[SQLiteStore] requires options.path');

package/src/stream.d.ts

@@ -60,6 +60,11 @@ export type StreamOptions = {
 export class Stream {
     /**
      * @param {StreamOptions} [options={}]
+     * @when you want a structured event emitter for loop/tool/governance events, optionally piped to a transport sink
+     * @fails never throws on emit; a transport write error is isolated and does not interrupt the run.
+     * @example
+     *   const stream = new Stream({ transport });
+     *   stream.emit('loop:round', { n: 1 });
      */
     constructor(options?: StreamOptions);
     /** @type {Transport|null} */