bare-agent 0.43.0 → 0.44.0

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} */

package/src/stream.js

@@ -36,6 +36,11 @@
 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 = {}) {
     /** @type {Transport|null} */

package/src/transport-jsonl.d.ts

@@ -17,6 +17,10 @@ export type JsonlTransportOptions = {
 export class JsonlTransport {
     /**
      * @param {JsonlTransportOptions} [options={}]
+     * @when you want to pipe structured Stream events as JSONL to a writable stream — pipe-friendly observability
+     * @fails never throws on write; defaults to process.stdout when no output stream is given.
+     * @example
+     *   const stream = new Stream({ transport: new JsonlTransport() });
      */
     constructor(options?: JsonlTransportOptions);
     _output: NodeJS.WritableStream | (NodeJS.WriteStream & {

package/src/transport-jsonl.js

@@ -15,6 +15,10 @@
 class JsonlTransport {
   /**
    * @param {JsonlTransportOptions} [options={}]
+   * @when you want to pipe structured Stream events as JSONL to a writable stream — pipe-friendly observability
+   * @fails never throws on write; defaults to process.stdout when no output stream is given.
+   * @example
+   *   const stream = new Stream({ transport: new JsonlTransport() });
    */
   constructor(options = {}) {
     this._output = options.output || process.stdout;

package/tools/browse.d.ts

@@ -3,6 +3,11 @@
  * Returns { tools, close } or null if barebrowse is not installed.
  * @param {object} [opts] - Options passed to barebrowse createBrowseTools
  * @returns {Promise<{tools: Array, close: Function}|null>}
+ * @when you want to give an agent browser tools (navigate, click, read) via barebrowse for inline snapshots
+ * @fails returns null if barebrowse (optional dep) is not installed; otherwise returns {tools, close} — call close() to release the browser.
+ * @example
+ *   const b = await createBrowsingTools();
+ *   const loop = new Loop({ provider, tools: b.tools });
  */
 export function createBrowsingTools(opts?: object): Promise<{
     tools: any[];

package/tools/browse.js

@@ -5,6 +5,11 @@
  * Returns { tools, close } or null if barebrowse is not installed.
  * @param {object} [opts] - Options passed to barebrowse createBrowseTools
  * @returns {Promise<{tools: Array, close: Function}|null>}
+ * @when you want to give an agent browser tools (navigate, click, read) via barebrowse for inline snapshots
+ * @fails returns null if barebrowse (optional dep) is not installed; otherwise returns {tools, close} — call close() to release the browser.
+ * @example
+ *   const b = await createBrowsingTools();
+ *   const loop = new Loop({ provider, tools: b.tools });
  */
 async function createBrowsingTools(opts = {}) {
   try {

package/tools/defer.d.ts

@@ -2,6 +2,11 @@
  * @param {object} [options]
  * @param {string} [options.queuePath] - Override queue file path.
  * @returns {{tool: import('../types').ToolDef, readQueue: () => Promise<Record<string, any>[]>, queuePath: string}}
+ * @when you want a tool that queues an action to a JSONL file for an external waker (cron) to fire later — two-phase governance (emit-time + fire-time)
+ * @fails returns {tool, readQueue, queuePath}; the inner action is re-gated at fire time when the waker runs. bareguard caps via defer.ratePerMinute.
+ * @example
+ *   const { tool } = createDeferTool();
+ *   const loop = new Loop({ provider, tools: [tool] });
  */
 export function createDeferTool(options?: {
     queuePath?: string | undefined;
@@ -15,7 +20,14 @@ export function createDeferTool(options?: {
  * append-only status lines (latest wins). Exposed for tests + library
  * users; the wake script does its own jq-based fold.
  */
-/** @param {string} [queuePath] */
+/**
+ * @param {string} [queuePath]
+ * @name readDeferQueue
+ * @when you want to read the deferred-action queue and reconstruct each id's live status (an external waker or a status check)
+ * @fails never throws on a missing/empty queue; folds append-only status lines (latest wins) and returns the reconstructed records.
+ * @example
+ *   const queue = await readDeferQueue();
+ */
 export function readQueue(queuePath?: string): Promise<Record<string, any>[]>;
 /**
  * Generate a sortable, unique id. 9-char base36 timestamp + 20-char hex

package/tools/defer.js

@@ -128,7 +128,14 @@ async function appendRecord(queuePath, record) {
  * append-only status lines (latest wins). Exposed for tests + library
  * users; the wake script does its own jq-based fold.
  */
-/** @param {string} [queuePath] */
+/**
+ * @param {string} [queuePath]
+ * @name readDeferQueue
+ * @when you want to read the deferred-action queue and reconstruct each id's live status (an external waker or a status check)
+ * @fails never throws on a missing/empty queue; folds append-only status lines (latest wins) and returns the reconstructed records.
+ * @example
+ *   const queue = await readDeferQueue();
+ */
 async function readQueue(queuePath) {
   const path = resolveQueuePath(queuePath);
   try {
@@ -156,6 +163,11 @@ async function readQueue(queuePath) {
  * @param {object} [options]
  * @param {string} [options.queuePath] - Override queue file path.
  * @returns {{tool: import('../types').ToolDef, readQueue: () => Promise<Record<string, any>[]>, queuePath: string}}
+ * @when you want a tool that queues an action to a JSONL file for an external waker (cron) to fire later — two-phase governance (emit-time + fire-time)
+ * @fails returns {tool, readQueue, queuePath}; the inner action is re-gated at fire time when the waker runs. bareguard caps via defer.ratePerMinute.
+ * @example
+ *   const { tool } = createDeferTool();
+ *   const loop = new Loop({ provider, tools: [tool] });
  */
 function createDeferTool(options = {}) {
   const queuePath = resolveQueuePath(options.queuePath);

package/tools/litectx-mcp.d.ts

@@ -10,6 +10,12 @@
  * @param {string} [opts.now] - ISO timestamp for `discovered` (default: now). Pre-seed fresh so
  *   `createMCPBridge` skips IDE discovery and connects straight to this curated server.
  * @returns {import('../src/mcp-bridge').BridgeConfig}
+ * @category integration
+ * @when you want to connect a litectx instance to a bareagent runner over the MCP bridge — a curated, child-db-local litectx server
+ * @fails read-only by default (opt-in `writable` allows remember/forget); pre-seeding `now` makes createMCPBridge skip IDE discovery and connect straight to this server.
+ * @example
+ *   const cfg = liteCtxMcpBridgeConfig({ root: './child.db' });
+ *   const { tools } = await createMCPBridge({ config: cfg });
  */
 export function liteCtxMcpBridgeConfig(opts: {
     root: string;

package/tools/litectx-mcp.js

@@ -36,6 +36,12 @@ const ADMIN_VERBS = ['index', 'promotions'];
  * @param {string} [opts.now] - ISO timestamp for `discovered` (default: now). Pre-seed fresh so
  *   `createMCPBridge` skips IDE discovery and connects straight to this curated server.
  * @returns {import('../src/mcp-bridge').BridgeConfig}
+ * @category integration
+ * @when you want to connect a litectx instance to a bareagent runner over the MCP bridge — a curated, child-db-local litectx server
+ * @fails read-only by default (opt-in `writable` allows remember/forget); pre-seeding `now` makes createMCPBridge skip IDE discovery and connect straight to this server.
+ * @example
+ *   const cfg = liteCtxMcpBridgeConfig({ root: './child.db' });
+ *   const { tools } = await createMCPBridge({ config: cfg });
  */
 function liteCtxMcpBridgeConfig(opts) {
   if (!opts || typeof opts.root !== 'string' || !opts.root) {

package/tools/mobile.d.ts

@@ -23,6 +23,11 @@ export type MobilePage = any;
  * @param {string} [opts.device] - Device serial or 'auto'
  * @param {boolean} [opts.termux] - Use Termux ADB on-device mode
  * @returns {Promise<{tools: ToolDef[], close: Function}|null>}
+ * @when you want to give an agent Android/iOS device control (tap, type, snapshot) via baremobile
+ * @fails returns null if baremobile (optional dep) is not installed; otherwise returns {tools, close} — call close() to disconnect.
+ * @example
+ *   const m = await createMobileTools({ platform: 'android' });
+ *   const loop = new Loop({ provider, tools: m.tools });
  */
 export function createMobileTools(opts?: {
     platform?: string | undefined;

package/tools/mobile.js

@@ -21,6 +21,11 @@
  * @param {string} [opts.device] - Device serial or 'auto'
  * @param {boolean} [opts.termux] - Use Termux ADB on-device mode
  * @returns {Promise<{tools: ToolDef[], close: Function}|null>}
+ * @when you want to give an agent Android/iOS device control (tap, type, snapshot) via baremobile
+ * @fails returns null if baremobile (optional dep) is not installed; otherwise returns {tools, close} — call close() to disconnect.
+ * @example
+ *   const m = await createMobileTools({ platform: 'android' });
+ *   const loop = new Loop({ provider, tools: m.tools });
  */
 async function createMobileTools(opts = {}) {
   const platform = opts.platform || 'android';

package/tools/shell.d.ts

@@ -41,6 +41,11 @@ type ToolDef = import("../types").ToolDef;
  * gating is the caller's responsibility via `new Loop({ policy })`.
  *
  * @returns {{tools: ToolDef[]}}
+ * @when you want to give an agent shell/file tools (read, grep, write, edit, run, exec) — cross-platform, pure Node, zero deps
+ * @fails never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, and shell_edit refuses a non-unique anchor as a tool result (file untouched).
+ * @example
+ *   const { tools } = createShellTools();
+ *   const loop = new Loop({ provider, tools, policy });
  */
 declare function createShellTools(): {
     tools: ToolDef[];

package/tools/shell.js

@@ -499,6 +499,11 @@ function execCommand({ command, cwd, timeout, maxBuffer, env }) {
  * gating is the caller's responsibility via `new Loop({ policy })`.
  *
  * @returns {{tools: ToolDef[]}}
+ * @when you want to give an agent shell/file tools (read, grep, write, edit, run, exec) — cross-platform, pure Node, zero deps
+ * @fails never throws at creation; gating is the caller's via Loop({ policy }) and fs.writeScope, and shell_edit refuses a non-unique anchor as a tool result (file untouched).
+ * @example
+ *   const { tools } = createShellTools();
+ *   const loop = new Loop({ provider, tools, policy });
  */
 function createShellTools() {
   /** @type {ToolDef[]} */

package/tools/spawn.d.ts

@@ -68,6 +68,11 @@ export type Stream = import("../src/stream").Stream;
  *   (heartbeat watchdog; default off). Resets on every line, so slow-but-working children survive.
  * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
  * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
+ * @when you want an LLM-callable spawn tool so a model can fork child bareagents itself — governed per-family by bareguard
+ * @fails returns {tool, spawnChild}; the tool blocks per child and child stderr is re-emitted as child:stderr on the wired Stream.
+ * @example
+ *   const { tool } = createSpawnTool();
+ *   const loop = new Loop({ provider, tools: [tool] });
  */
 export function createSpawnTool(options?: {
     cliPath?: string | undefined;
@@ -104,6 +109,11 @@ export function createSpawnTool(options?: {
  * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
  *
  * @param {SpawnChildOptions} [opts]
+ * @when you want to fork a child bareagent process programmatically and get a handle — heavyweight delegation, not the in-process recurse default
+ * @fails bounded by timeoutMs (wall-clock) and opt-in idleTimeoutMs (heartbeat); the result carries idleKilled if the watchdog fired. Threads BAREGUARD env vars to the child.
+ * @example
+ *   const handle = spawnChild({ config, input });
+ *   const result = await handle.wait();
  */
 export function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream }?: SpawnChildOptions): {
     wait: () => Promise<{

package/tools/spawn.js

@@ -74,6 +74,11 @@ function resolveCliPath() {
  * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
  *
  * @param {SpawnChildOptions} [opts]
+ * @when you want to fork a child bareagent process programmatically and get a handle — heavyweight delegation, not the in-process recurse default
+ * @fails bounded by timeoutMs (wall-clock) and opt-in idleTimeoutMs (heartbeat); the result carries idleKilled if the watchdog fired. Threads BAREGUARD env vars to the child.
+ * @example
+ *   const handle = spawnChild({ config, input });
+ *   const result = await handle.wait();
  */
 function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream } = {}) {
   if (typeof config !== 'string' || !config) {
@@ -257,6 +262,11 @@ function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream }
  *   (heartbeat watchdog; default off). Resets on every line, so slow-but-working children survive.
  * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
  * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
+ * @when you want an LLM-callable spawn tool so a model can fork child bareagents itself — governed per-family by bareguard
+ * @fails returns {tool, spawnChild}; the tool blocks per child and child stderr is re-emitted as child:stderr on the wired Stream.
+ * @example
+ *   const { tool } = createSpawnTool();
+ *   const loop = new Loop({ provider, tools: [tool] });
  */
 function createSpawnTool(options = {}) {
   const tool = {