bare-agent 0.42.0 → 0.44.0

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 = {

package/types/index.d.ts

@@ -134,6 +134,16 @@ export interface GenerateResult {
    * temperature, not the one requested — callers reporting an effective temperature must honor this.
    */
   temperatureDropped?: boolean;
+  /**
+   * BA-27 — present ONLY when the model emitted a tool call whose `function.arguments` was
+   * syntactically-broken JSON (an extra brace, a truncated object). The billed round already
+   * succeeded, so rather than throw (which loses the round's usage and hangs metering), the provider
+   * returns NO usable tool calls (`toolCalls: []`) plus this marker. A caller treats it as "no usable
+   * tool call" and retries; `usage`/`model` still flow so the round is metered. The JSON is NEVER
+   * repaired. Absent on a clean round. OpenAI-compatible + Ollama string-arguments only; Anthropic
+   * arrives pre-parsed and cannot hit this.
+   */
+  malformedToolCall?: { name: string | undefined; error: string };
   /**
    * BA-7 — provider-native content blocks the normalized `{text, toolCalls}` shape cannot express
    * (Anthropic `thinking` / `redacted_thinking`), captured opaquely so the Loop can put them on the