bare-agent 0.6.2 → 0.7.0

package/README.md

@@ -60,7 +60,7 @@ Every piece works alone — take what you need, ignore the rest.
 
 | Component | What it does |
 |---|---|
-| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Throws on error by default. Returns estimated USD cost per run. Loop-level `policy` + `audit` gate every tool call (native, MCP, browsing, mobile, user-defined) through one hook, JSONL audit to disk |
+| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Throws on error by default. Returns estimated USD cost per run. Loop-level `policy(toolName, args, ctx)` + `audit` gate every tool call (native, MCP, browsing, mobile, user-defined) through one hook — `ctx` is a per-call opaque blob for multi-tenant routing. `maxCost` cap catches runaway loops before they burn budget. Unified `loop:error` + `onError` surface every previously silent failure (audit write, callback throw, Checkpoint timeout) |
 | **Planner** | Break a goal into a step DAG via LLM. Built-in caching (`cacheTTL`) |
 | **runPlan** | Execute steps in parallel waves. Dependency-aware, failure propagation, per-step retry |
 | **Retry** | Exponential/linear backoff with jitter. Respects `err.retryable` |
@@ -71,7 +71,8 @@ Every piece works alone — take what you need, ignore the rest.
 | **Checkpoint** | Human approval gate. You provide the transport — terminal, Telegram, Slack, whatever |
 | **Scheduler** | Cron (`0 9 * * 1-5`) or relative (`2h`, `30m`). Persisted jobs survive restarts |
 | **Stream** | Structured event emitter. Pipe as JSONL, subscribe in-process, or custom transport |
-| **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `MaxRoundsError`, `CircuitOpenError` |
+| **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `MaxRoundsError`, `MaxCostError`, `CircuitOpenError`, `ValidationError` |
+| **Policy helpers** | `pathAllowlist`, `commandAllowlist`, `combinePolicies` — composable predicates for `Loop({ policy })`. Home expansion, deny-wins, short-circuit combinator, argv-based safe allowlists. `require('bare-agent/policy')` |
 | **Browsing** | Web navigation, clicking, typing, reading via `barebrowse` (17 tools). Two modes: library tools (inline snapshots, pass to Loop) or CLI session (disk-based snapshots, token-efficient for multi-step flows). Optional `assess` tool (privacy scan) when `wearehere` is installed |
 | **Mobile** | Android + iOS device control via `baremobile`. Same two modes: library tools (`createMobileTools` — action tools auto-return snapshots) or CLI session (`baremobile` CLI — disk-based snapshots) |
 | **Shell** | Cross-platform `shell_read`, `shell_grep`, `shell_run` (argv, no shell), `shell_exec` (raw shell). Pure Node — no `grep`/`rg`/`findstr` dependency. Injection-proof `shell_run` for policy-gated use |

package/index.js

@@ -18,6 +18,7 @@ const {
   ValidationError,
   CircuitOpenError,
   MaxRoundsError,
+  MaxCostError,
 } = require('./src/errors');
 
 module.exports = {
@@ -38,4 +39,5 @@ module.exports = {
   ValidationError,
   CircuitOpenError,
   MaxRoundsError,
+  MaxCostError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "files": [
     "index.js",
     "src/",
@@ -24,7 +24,8 @@
     "./stores": "./src/stores.js",
     "./transports": "./src/transports.js",
     "./tools": "./src/tools.js",
-    "./mcp": "./src/mcp.js"
+    "./mcp": "./src/mcp.js",
+    "./policy": "./src/policy.js"
   },
   "engines": {
     "node": ">=18"

package/src/checkpoint.js

@@ -1,11 +1,24 @@
 'use strict';
 
+const { TimeoutError } = require('./errors');
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
 class Checkpoint {
+  /**
+   * @param {object} options
+   * @param {Array<string>} [options.tools] - Tool names that require approval (exact match).
+   * @param {Function} [options.shouldAsk] - Custom predicate `(toolName, args) => bool` — overrides tools list if set.
+   * @param {Function} options.send - Async `(question, context) => void` to deliver the question.
+   * @param {Function} options.waitForReply - Async `(context) => string` that resolves with the user's reply.
+   * @param {number} [options.timeout=300000] - Ms to wait before auto-denying. 0 disables.
+   */
   constructor(options = {}) {
     this.tools = new Set(options.tools || []);
     this.send = options.send || null;
     this.waitForReply = options.waitForReply || null;
-    this.shouldAskFn = options.shouldAsk || null; // custom predicate override
+    this.shouldAskFn = options.shouldAsk || null;
+    this.timeout = options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
   }
 
   shouldAsk(toolName, args) {
@@ -14,19 +27,40 @@ class Checkpoint {
   }
 
   /**
-   * Send a question and wait for a reply.
+   * Send a question and wait for a reply. Rejects with TimeoutError if `timeout` ms elapse
+   * without a reply — the Loop catches this, auto-denies the tool call, and routes the
+   * error through loop:error + onError. No silent hangs.
    * @param {string} question - The approval question to send.
    * @param {object} [context={}] - Context passed to send and waitForReply.
    * @returns {Promise<string|null>} The user's reply, or null.
    * @throws {Error} `[Checkpoint] send and waitForReply callbacks required` — when callbacks are missing.
+   * @throws {TimeoutError} When no reply arrives within `timeout` ms.
    */
   async ask(question, context = {}) {
     if (!this.send || !this.waitForReply) {
       throw new Error('[Checkpoint] send and waitForReply callbacks required');
     }
     await this.send(question, context);
-    const reply = await this.waitForReply(context);
-    return reply ?? null;
+    const waitPromise = Promise.resolve(this.waitForReply(context));
+    if (!this.timeout || this.timeout <= 0) {
+      const reply = await waitPromise;
+      return reply ?? null;
+    }
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(new TimeoutError(`[Checkpoint] no reply within ${this.timeout}ms — auto-denied`, {
+          context: { tool: context?.tool, timeout: this.timeout },
+        })),
+        this.timeout,
+      );
+    });
+    try {
+      const reply = await Promise.race([waitPromise, timeoutPromise]);
+      return reply ?? null;
+    } finally {
+      clearTimeout(timer);
+    }
   }
 }
 

package/src/errors.js

@@ -49,6 +49,12 @@ class MaxRoundsError extends BareAgentError {
   }
 }
 
+class MaxCostError extends BareAgentError {
+  constructor(message, opts = {}) {
+    super(message || 'Loop exceeded maximum cost cap', { code: 'MAX_COST', retryable: false, ...opts });
+  }
+}
+
 module.exports = {
   BareAgentError,
   ProviderError,
@@ -57,4 +63,5 @@ module.exports = {
   ValidationError,
   CircuitOpenError,
   MaxRoundsError,
+  MaxCostError,
 };

package/src/loop.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const fs = require('node:fs');
-const { ToolError, MaxRoundsError } = require('./errors');
+const { ToolError, MaxRoundsError, MaxCostError } = require('./errors');
 
 // Average pricing per 1K tokens (USD). Adjust these to match your provider's rates.
 // Last updated: 2026-03-18. Source: public provider pricing pages.
@@ -62,11 +62,50 @@ class Loop {
     }
     this.policy = options.policy || null;
     this.audit = options.audit || null;
+    this.maxCost = typeof options.maxCost === 'number' && options.maxCost > 0 ? options.maxCost : null;
     this._stopped = false;
     this._history = []; // for chat() stateful mode
     this._auditInFlight = new Set();
   }
 
+  // Unified error emitter — every silent-ish failure path routes through here so
+  // operators see audit writes, callback throws, checkpoint timeouts, stream listener
+  // errors in one place: loop:error stream event + onError callback.
+  _reportError(source, err, extra = {}) {
+    const message = err?.message || String(err);
+    this._safeEmit({ type: 'loop:error', data: { source, error: message, ...extra } });
+    if (this.onError) {
+      try {
+        this.onError(err, { source, ...extra });
+      } catch (cbErr) {
+        console.warn(`[Loop] onError callback threw: ${cbErr.message}`);
+      }
+    }
+  }
+
+  // Swallow-proof stream emit: a throwing listener must not corrupt Loop state.
+  _safeEmit(event) {
+    if (!this.stream) return;
+    try {
+      this.stream.emit(event);
+    } catch (err) {
+      console.warn(`[Loop] stream listener threw on ${event.type}: ${err.message}`);
+      if (this.onError && event.type !== 'loop:error') {
+        try { this.onError(err, { source: 'stream', eventType: event.type }); } catch { /* swallow */ }
+      }
+    }
+  }
+
+  // Fire a user callback without letting its throw kill the loop.
+  _safeCall(name, fn, ...args) {
+    if (!fn) return;
+    try {
+      fn(...args);
+    } catch (err) {
+      this._reportError(`callback:${name}`, err);
+    }
+  }
+
   // Append one JSONL record. Returns nothing (fire-and-forget for callers)
   // but tracks the in-flight promise so `flush()` and the end of `run()` can await it.
   _writeAudit(record) {
@@ -75,11 +114,11 @@ class Loop {
     try {
       line = JSON.stringify(record) + '\n';
     } catch (err) {
-      console.warn(`[Loop] audit serialize failed: ${err.message}`);
+      this._reportError('audit:serialize', err, { tool: record?.tool });
       return;
     }
     const p = fs.promises.appendFile(this.audit, line)
-      .catch(err => console.warn(`[Loop] audit write failed: ${err.message}`))
+      .catch(err => this._reportError('audit:write', err, { tool: record?.tool }))
       .finally(() => this._auditInFlight.delete(p));
     this._auditInFlight.add(p);
   }
@@ -104,6 +143,7 @@ class Loop {
   async run(messages, tools = [], options = {}) {
     this._stopped = false;
     const system = options.system || this.system;
+    const ctx = options.ctx || null; // per-run opaque blob forwarded to policy
     const msgs = system
       ? [{ role: 'system', content: system }, ...messages]
       : [...messages];
@@ -125,7 +165,7 @@ class Loop {
       }
     }
 
-    this.stream?.emit({ type: 'loop:start', data: { messageCount: msgs.length } });
+    this._safeEmit({ type: 'loop:start', data: { messageCount: msgs.length } });
 
     let lastUsage = { inputTokens: 0, outputTokens: 0 };
     let totalCost = 0;
@@ -138,8 +178,7 @@ class Loop {
         const generate = () => this.provider.generate(msgs, tools, options);
         result = this.retry ? await this.retry.call(generate) : await generate();
       } catch (err) {
-        this.stream?.emit({ type: 'loop:error', data: { error: err.message, round } });
-        this.onError?.(err);
+        this._reportError('provider', err, { round });
         await this.flush();
         if (this.throwOnError) throw err;
         return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message };
@@ -150,12 +189,22 @@ class Loop {
       const roundCost = estimateCost(model, lastUsage);
       if (roundCost !== null) totalCost += roundCost;
 
+      // Cost cap — fail fast before the next round costs more money.
+      if (this.maxCost !== null && totalCost > this.maxCost) {
+        const msg = `[Loop] cost ${totalCost.toFixed(4)} exceeded cap ${this.maxCost.toFixed(4)} after round ${round + 1}`;
+        const err = new MaxCostError(msg, { context: { cost: totalCost, maxCost: this.maxCost, round } });
+        this._reportError('cost-cap', err, { cost: totalCost, maxCost: this.maxCost });
+        await this.flush();
+        if (this.throwOnError) throw err;
+        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: msg };
+      }
+
       // No tool calls — LLM gave a final text response
       if (!result.toolCalls || result.toolCalls.length === 0) {
-        this.stream?.emit({ type: 'loop:text', data: { text: result.text } });
-        this.onText?.(result.text);
+        this._safeEmit({ type: 'loop:text', data: { text: result.text } });
+        this._safeCall('onText', this.onText, result.text);
         await this.flush();
-        this.stream?.emit({ type: 'loop:done', data: { text: result.text, usage: lastUsage, cost: totalCost } });
+        this._safeEmit({ type: 'loop:done', data: { text: result.text, usage: lastUsage, cost: totalCost } });
         return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null };
       }
 
@@ -177,34 +226,44 @@ class Loop {
         if (!tool) {
           const errMsg = `[Loop] Unknown tool: ${tc.name}`;
           msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
-          this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
+          this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
           continue;
         }
 
         // Checkpoint — ask for approval before executing
         if (this.checkpoint?.shouldAsk(tc.name, tc.arguments)) {
-          this.stream?.emit({ type: 'checkpoint:ask', data: { tool: tc.name, args: tc.arguments } });
-          const reply = await this.checkpoint.ask(
-            `Approve ${tc.name}(${JSON.stringify(tc.arguments)})?`,
-            { tool: tc.name, args: tc.arguments }
-          );
-          this.stream?.emit({ type: 'checkpoint:reply', data: { reply } });
+          this._safeEmit({ type: 'checkpoint:ask', data: { tool: tc.name, args: tc.arguments } });
+          let reply;
+          try {
+            reply = await this.checkpoint.ask(
+              `Approve ${tc.name}(${JSON.stringify(tc.arguments)})?`,
+              { tool: tc.name, args: tc.arguments }
+            );
+          } catch (err) {
+            // Checkpoint errors (e.g. timeout, transport failure) auto-deny and
+            // get reported via loop:error + onError. The loop never hangs silently.
+            this._reportError('checkpoint', err, { tool: tc.name });
+            msgs.push({ role: 'tool', tool_call_id: tc.id, content: `[Loop] Checkpoint failed: ${err.message}. Action auto-denied.` });
+            continue;
+          }
+          this._safeEmit({ type: 'checkpoint:reply', data: { reply } });
           if (!reply || reply.toLowerCase() === 'no' || reply.toLowerCase() === 'n') {
             msgs.push({ role: 'tool', tool_call_id: tc.id, content: 'User denied this action.' });
             continue;
           }
         }
 
-        this.stream?.emit({ type: 'loop:tool_call', data: { tool: tc.name, args: tc.arguments } });
-        this.onToolCall?.(tc.name, tc.arguments);
+        this._safeEmit({ type: 'loop:tool_call', data: { tool: tc.name, args: tc.arguments } });
+        this._safeCall('onToolCall', this.onToolCall, tc.name, tc.arguments);
 
         // Policy check — runs before execute. Fail-safe: only verdict === true allows;
         // anything else (false, string, undefined, object, throw) denies. A string verdict
-        // is used verbatim as the deny reason.
+        // is used verbatim as the deny reason. `ctx` (opaque blob passed via
+        // loop.run(msgs, tools, { ctx })) is forwarded as the third arg for per-caller gating.
         if (this.policy) {
           let verdict;
           try {
-            verdict = await this.policy(tc.name, tc.arguments);
+            verdict = await this.policy(tc.name, tc.arguments, ctx);
           } catch (err) {
             verdict = `[Loop] policy error: ${err.message}`;
           }
@@ -213,7 +272,7 @@ class Loop {
               ? verdict
               : `[Loop] Tool "${tc.name}" denied by policy`;
             msgs.push({ role: 'tool', tool_call_id: tc.id, content: reason });
-            this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, denied: true, reason } });
+            this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, denied: true, reason } });
             this._writeAudit({
               ts: new Date().toISOString(),
               tool: tc.name,
@@ -231,7 +290,7 @@ class Loop {
           const toolResult = this.retry ? await this.retry.call(execute) : await execute();
           const content = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
           msgs.push({ role: 'tool', tool_call_id: tc.id, content });
-          this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, result: content } });
+          this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, result: content } });
           this._writeAudit({
             ts: new Date().toISOString(),
             tool: tc.name,
@@ -244,7 +303,7 @@ class Loop {
           const toolErr = err instanceof ToolError ? err : new ToolError(err.message, { context: { tool: tc.name } });
           const errMsg = `[Loop] Tool error: ${toolErr.message}`;
           msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
-          this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
+          this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
           this._writeAudit({
             ts: new Date().toISOString(),
             tool: tc.name,
@@ -260,7 +319,7 @@ class Loop {
     // maxRounds exceeded
     const warning = `[Loop] ended after ${this.maxRounds} rounds without final response`;
     await this.flush();
-    this.stream?.emit({ type: 'loop:done', data: { text: '', warning, cost: totalCost } });
+    this._safeEmit({ type: 'loop:done', data: { text: '', warning, cost: totalCost } });
     if (this.throwOnError) throw new MaxRoundsError(warning);
     return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: warning };
   }

package/src/policy.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * Policy helpers — composable predicates for `new Loop({ policy })`.
+ *
+ * Each helper returns an async function `(toolName, args, ctx) => true | string`
+ * matching bareagent's policy contract. `true` allows; anything else denies.
+ * A string is fed verbatim to the LLM as the deny reason.
+ *
+ * Compose multiple helpers with `combinePolicies(a, b, c)` — first non-`true`
+ * verdict wins, short-circuit semantics.
+ *
+ * Zero deps. Pure Node. Cross-platform.
+ */
+
+const path = require('node:path');
+
+function expandHome(p) {
+  if (!p || typeof p !== 'string') return p;
+  if (p === '~') return process.env.HOME || process.env.USERPROFILE || '';
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, p.slice(2));
+  }
+  return p;
+}
+
+function normalize(p) {
+  try {
+    return path.resolve(expandHome(p));
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Allow/deny file-system paths used by tools like shell_read, shell_grep.
+ *
+ * Deny wins over allow. Paths containing `..` after normalization are denied
+ * unconditionally (prevents traversal bypassing the allow list).
+ *
+ * @param {object} options
+ * @param {string[]} [options.allow] - Path prefixes users may access. `~` expands.
+ * @param {string[]} [options.deny] - Path prefixes hard-denied. `~` expands.
+ * @param {string[]} [options.toolNames] - Only check these tool names. If omitted, checks any tool with an `args.path` string.
+ * @param {string} [options.argKey='path'] - Name of the args field to inspect.
+ * @returns {Function} policy predicate `(toolName, args) => true | string`
+ */
+function pathAllowlist({ allow = [], deny = [], toolNames, argKey = 'path' } = {}) {
+  const allowNorm = allow.map(normalize);
+  const denyNorm = deny.map(normalize);
+  const gatedTools = toolNames ? new Set(toolNames) : null;
+
+  return async function pathPolicy(toolName, args) {
+    if (gatedTools && !gatedTools.has(toolName)) return true;
+    const raw = args?.[argKey];
+    if (typeof raw !== 'string') return true; // nothing to check
+    const target = normalize(raw);
+
+    for (const d of denyNorm) {
+      if (target === d || target.startsWith(d + path.sep) || target.startsWith(d + '/')) {
+        return `Path denied: ${raw} is under a denied root (${d}).`;
+      }
+    }
+    if (allowNorm.length === 0) return true;
+    for (const a of allowNorm) {
+      if (target === a || target.startsWith(a + path.sep) || target.startsWith(a + '/')) {
+        return true;
+      }
+    }
+    return `Path denied: ${raw} is not under any allowed root.`;
+  };
+}
+
+/**
+ * Allow/deny commands by their base name.
+ *
+ * For `shell_run` (argv-array): inspects `args.argv[0]`. Safe — no shell in path.
+ * For `shell_exec` (raw shell): inspects `args.command.split(/\s+/)[0]` BUT this
+ * is defeatable by shell metacharacters. Prefer gating `shell_run` with this helper
+ * and denying `shell_exec` entirely, or handling shell_exec with a custom policy
+ * that parses the command string carefully.
+ *
+ * Deny wins over allow.
+ *
+ * @param {object} options
+ * @param {string[]} [options.allow] - Base command names allowed.
+ * @param {string[]} [options.deny] - Base command names denied.
+ * @param {string} [options.toolName='shell_run'] - Which tool this helper gates.
+ * @returns {Function} policy predicate `(toolName, args) => true | string`
+ */
+function commandAllowlist({ allow = [], deny = [], toolName = 'shell_run' } = {}) {
+  const allowSet = new Set(allow);
+  const denySet = new Set(deny);
+
+  return async function commandPolicy(name, args) {
+    if (name !== toolName) return true;
+    let base;
+    if (name === 'shell_run') {
+      if (!Array.isArray(args?.argv) || typeof args.argv[0] !== 'string') return true;
+      base = args.argv[0];
+    } else {
+      if (typeof args?.command !== 'string') return true;
+      base = args.command.trim().split(/\s+/)[0];
+    }
+    if (denySet.has(base)) return `Command denied: ${base} is on the denylist.`;
+    if (allowSet.size > 0 && !allowSet.has(base)) {
+      return `Command denied: ${base} is not on the allowlist.`;
+    }
+    return true;
+  };
+}
+
+/**
+ * Compose multiple policy predicates into one. First non-true verdict wins.
+ * Short-circuits on first deny — later predicates are not called.
+ *
+ * @param {...Function} policies - Any number of policy predicates.
+ * @returns {Function} combined policy predicate `(toolName, args, ctx) => true | string`
+ */
+function combinePolicies(...policies) {
+  const list = policies.filter(p => typeof p === 'function');
+  return async function combined(toolName, args, ctx) {
+    for (const p of list) {
+      const verdict = await p(toolName, args, ctx);
+      if (verdict !== true) return verdict;
+    }
+    return true;
+  };
+}
+
+module.exports = { pathAllowlist, commandAllowlist, combinePolicies };