bare-agent 0.10.3 → 0.11.0

package/README.md

@@ -169,6 +169,21 @@ Halts also fire `loop:error` on the stream (`source: 'halt'`) and the `onError`
 
 ---
 
+## Examples
+
+Runnable scripts in [`examples/`](examples/) — each is self-contained and the file's top docstring documents flags and required env vars.
+
+| File | What it shows |
+|---|---|
+| [`with-bareguard.mjs`](examples/with-bareguard.mjs) | End-to-end Loop + bareguard wiring: budget cap, fs scope, bash allowlist, audit log, humanChannel. The canonical governed-loop reference. |
+| [`mcp-bridge-poc.js`](examples/mcp-bridge-poc.js) | Auto-discover MCP servers from your IDE configs and expose them as bareagent tools. First run writes `.mcp-bridge.json` (edit to deny tools). |
+| [`mcp-bridge-concurrent.js`](examples/mcp-bridge-concurrent.js) | Soak test: fan out concurrent `barebrowse_browse` calls against real domains (Amazon, Wikipedia, GitHub, a dead host) and verify resilience. |
+| [`orchestrator/`](examples/orchestrator/) | Multi-agent dispatch via `spawn`. Three configs, one system prompt — no orchestrator class, no role types. Roles are JSON files. |
+| [`wake.sh`](examples/wake.sh) + [`wake.md`](examples/wake.md) | Reference cron + jq script for firing deferred actions. The runtime half of `createDeferTool` — bareagent emits, `wake.sh` fires. |
+| [`replay-job.js`](examples/replay-job.js) | Supervised replay POC: record a browser task once with the LLM driving, then replay against fresh snapshots with the LLM as locator-only. Falls back to full reasoning when the locator misses, and patches the trace. |
+
+---
+
 ## Cross-language usage
 
 Not using Node.js? Spawn bare-agent as a subprocess from any language. Ready-made wrappers in [`contrib/`](contrib/README.md) for Python, Go, Rust, Ruby, and Java — copy one file, no package registry needed.

package/bin/cli.js

@@ -23,7 +23,9 @@
  *        "provider":      "openai" | "anthropic" | "ollama",
  *        "model":         "gpt-4o-mini" (etc),
  *        "tools":         ["shell_read", "shell_grep", "spawn", "defer", ...],
- *        "gate":          { ...bareguard config; humanChannel headless-defaults to deny }
+ *        "gate":          { ...bareguard config; humanChannel headless-defaults to deny },
+ *        "ungoverned":    false  // omit/false ⇒ a config with no `gate` is refused;
+ *                                // set true to explicitly run without governance (not recommended)
  *      }
  */
 
@@ -81,7 +83,16 @@ async function runConfigMode(cfgPath) {
       let humanChannel = cfg.gate.humanChannel;
       if (typeof humanChannel === 'string') {
         // Allow `humanChannel: "./my-channel.js"` — load from a file relative to config.
-        const fnPath = path.resolve(path.dirname(cfgPath), humanChannel);
+        // Confine the resolved path to the config directory: a JSON config (data)
+        // must not be able to require() arbitrary code elsewhere on disk (e.g.
+        // "../../evil.js"), which would execute outside the gate.
+        const cfgDir = path.resolve(path.dirname(cfgPath));
+        const fnPath = path.resolve(cfgDir, humanChannel);
+        if (fnPath !== cfgDir && !fnPath.startsWith(cfgDir + path.sep)) {
+          throw new Error(
+            `gate.humanChannel must resolve inside the config directory (${cfgDir}); refusing to load ${fnPath}`,
+          );
+        }
         humanChannel = require(fnPath);
       }
       if (typeof humanChannel !== 'function') {
@@ -106,6 +117,23 @@ async function runConfigMode(cfgPath) {
       process.stderr.write(`[cli] failed to wire bareguard: ${err.message}. Refusing to run ungoverned (cfg.gate set).\n`);
       process.exit(1);
     }
+  } else if (cfg.ungoverned === true) {
+    // Explicit opt-out. A config-driven / spawned agent runs with no policy,
+    // budget, depth, or rate limits — every configured tool executes unchecked.
+    process.stderr.write(
+      '[cli] WARNING: running UNGOVERNED (cfg.ungoverned=true) — no policy/budget/depth/rate limits. ' +
+      'All configured tools run unchecked.\n',
+    );
+  } else {
+    // Fail-closed: a config with no `gate` is rejected rather than silently run
+    // ungoverned. This is the path the LLM-callable `spawn` tool drives — without
+    // it, a gate-less child config bypasses all governance (and recursive spawn is
+    // unbounded, since maxDepth is only enforced by a wired Gate).
+    process.stderr.write(
+      '[cli] refusing to run: config has no `gate` block. A config-driven / spawned agent must be governed.\n' +
+      '      Add a bareguard `gate` config, or set `"ungoverned": true` to explicitly opt out (not recommended).\n',
+    );
+    process.exit(1);
   }
 
   // Read ONE input record from stdin (JSON or raw string). Treat blank stdin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "files": [
     "index.js",
     "src/",

package/src/loop.js

@@ -279,7 +279,13 @@ class Loop {
             continue;
           }
           this._safeEmit({ type: 'checkpoint:reply', data: { reply } });
-          if (!reply || reply.toLowerCase() === 'no' || reply.toLowerCase() === 'n') {
+          // Fail-closed: approve ONLY on an explicit affirmative. Any other reply —
+          // an unrecognized string ("denied", "wait"), empty, or a non-string — denies.
+          // A human approval gate must never approve on ambiguous input, and reading
+          // .toLowerCase() off a non-string here used to throw out of run().
+          const approved = typeof reply === 'string'
+            && ['yes', 'y', 'approve', 'approved'].includes(reply.trim().toLowerCase());
+          if (!approved) {
             msgs.push({ role: 'tool', tool_call_id: tc.id, content: 'User denied this action.' });
             continue;
           }

package/src/mcp-bridge.js

@@ -431,6 +431,13 @@ function buildMetaTools(tools, discoveredAt) {
  * @param {string[]} [opts.servers] - Limit to these server names.
  * @param {number} [opts.timeout=15000] - Per-server init timeout in ms.
  * @param {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
+ * @param {(name: string, def: object) => boolean | Promise<boolean>} [opts.confirmServer]
+ *   Vet each discovered server BEFORE its `command` is spawned. Connecting to an
+ *   MCP server runs its command, and discovery reads configs from the cwd (a
+ *   `.mcp.json` in an untrusted repo) as well as the user's home/IDE configs.
+ *   Return false to skip a server (its command is never executed). A throw is
+ *   treated as a deny (fail-closed). Default: every discovered server is trusted
+ *   (unchanged behavior) — pass this to gate command execution.
  * @returns {Promise<{tools: Array, metaTools: Array, servers: string[], systemContext: string, denied: Array, close: Function}>}
  */
 async function createMCPBridge(opts = {}) {
@@ -444,6 +451,15 @@ async function createMCPBridge(opts = {}) {
   const bridgePath = opts.bridgePath || DEFAULT_BRIDGE_PATH();
   const timeout = opts.timeout || 15000;
 
+  // Vet a server before spawning its command. Fail-closed: an undefined hook
+  // trusts all (unchanged behavior); a throw denies.
+  const confirmServer = typeof opts.confirmServer === 'function' ? opts.confirmServer : null;
+  const vetServer = async (name, def) => {
+    if (!confirmServer) return true;
+    try { return (await confirmServer(name, def)) === true; }
+    catch { return false; }
+  };
+
   let config = readBridgeConfig(bridgePath);
   const needsRefresh = opts.refresh || !config || isExpired(config);
 
@@ -469,6 +485,9 @@ async function createMCPBridge(opts = {}) {
 
       await Promise.all(toDiscover.map(async ([name, def]) => {
         try {
+          // Denied by confirmServer: skip silently — this is the caller's own
+          // decision, not a connection failure, so it must not land in `errors`.
+          if (!(await vetServer(name, def))) return;
           const result = await connectAndListTools(name, def, timeout);
           freshTools.set(name, result.mcpTools);
           connectResults.set(name, result.client);
@@ -525,6 +544,8 @@ async function createMCPBridge(opts = {}) {
       .map(([t]) => t);
 
     try {
+      // Denied by confirmServer: skip silently (the caller's decision, not a failure).
+      if (!(await vetServer(name, serverConf))) return;
       const { mcpTools, client } = await connectAndListTools(name, serverConf, timeout);
 
       // Only wrap tools that are allowed in config

package/src/provider-anthropic.js

@@ -8,12 +8,15 @@ class AnthropicProvider {
    * @param {object} options
    * @param {string} options.apiKey - Anthropic API key (required).
    * @param {string} [options.model='claude-haiku-4-5-20251001'] - Model ID.
+   * @param {boolean} [options.exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
    * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
    */
   constructor(options = {}) {
     if (!options.apiKey) throw new Error('[AnthropicProvider] requires apiKey');
     this.apiKey = options.apiKey.trim();
     this.model = options.model || 'claude-haiku-4-5-20251001';
+    // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
+    this.exposeErrorBody = options.exposeErrorBody === true;
   }
 
   /**
@@ -126,7 +129,7 @@ class AnthropicProvider {
             if (res.statusCode >= 400) {
               return reject(new ProviderError(
                 `[AnthropicProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: parsed }
+                { status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined }
               ));
             }
             resolve(parsed);

package/src/provider-ollama.js

@@ -7,6 +7,8 @@ class OllamaProvider {
   constructor(options = {}) {
     this.model = options.model || 'llama3.2';
     this.url = options.url || 'http://localhost:11434';
+    // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
+    this.exposeErrorBody = options.exposeErrorBody === true;
   }
 
   /**
@@ -70,7 +72,7 @@ class OllamaProvider {
             if (res.statusCode >= 400) {
               return reject(new ProviderError(
                 `[OllamaProvider] ${parsed.error || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: parsed }
+                { status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined }
               ));
             }
             resolve(parsed);

package/src/provider-openai.js

@@ -5,10 +5,22 @@ const http = require('http');
 const { ProviderError } = require('./errors');
 
 class OpenAIProvider {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.apiKey]
+   * @param {string} [options.model='gpt-4o-mini']
+   * @param {string} [options.baseUrl='https://api.openai.com/v1']
+   * @param {boolean} [options.exposeErrorBody=false] - Attach the full upstream
+   *   response to `err.body` on HTTP errors. Off by default so an unexpected
+   *   field in an error payload can't leak through logs that dump the error
+   *   object; `err.message` still carries the API's error message. Turn on for
+   *   debugging only.
+   */
   constructor(options = {}) {
     this.apiKey = options.apiKey?.trim();
     this.model = options.model || 'gpt-4o-mini';
     this.baseUrl = options.baseUrl || 'https://api.openai.com/v1';
+    this.exposeErrorBody = options.exposeErrorBody === true;
   }
 
   /**
@@ -73,7 +85,7 @@ class OpenAIProvider {
             if (res.statusCode >= 400) {
               return reject(new ProviderError(
                 `[OpenAIProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: parsed }
+                { status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined }
               ));
             }
             resolve(parsed);

package/src/store-jsonfile.js

@@ -2,9 +2,18 @@
 
 const { readFileSync, writeFileSync, existsSync } = require('node:fs');
 
+// Past this many entries, the O(n) scan + whole-file rewrite per write becomes a
+// real latency/availability concern. Warn once (per instance) and point at SQLiteStore.
+const LARGE_STORE_THRESHOLD = 10000;
+
 /**
  * JSON file memory store. Zero deps, case-insensitive substring search.
  *
+ * SCALING: intended for small memory sets. `search()` is an O(n) substring scan
+ * (no index), and every `store()`/`delete()` re-serializes and rewrites the entire
+ * file synchronously. Fine for hundreds–low-thousands of entries; for larger or
+ * write-heavy memory use SQLiteStore (FTS5 index, parameterized, incremental writes).
+ *
  * Interface (implements Memory store contract):
  *   store(content, metadata)   → id
  *   search(query, options)     → [{ id, content, metadata, score }]
@@ -26,6 +35,7 @@ class JsonFileStore {
     this._nextId = this._data.length
       ? this._data.reduce((max, d) => Math.max(max, d.id), 0) + 1
       : 1;
+    this._warnedLarge = false;
   }
 
   _save() {
@@ -36,6 +46,13 @@ class JsonFileStore {
     const id = this._nextId++;
     this._data.push({ id, content, metadata, createdAt: new Date().toISOString() });
     this._save();
+    if (!this._warnedLarge && this._data.length > LARGE_STORE_THRESHOLD) {
+      this._warnedLarge = true;
+      console.warn(
+        `[JsonFileStore] ${this._data.length} entries — search is O(n) and every write rewrites ` +
+        `the whole file. Switch to SQLiteStore for memory this size.`,
+      );
+    }
     return id;
   }
 

package/tools/shell.js

@@ -91,9 +91,37 @@ async function* walk(dir, recursive) {
   }
 }
 
+// Conservative ReDoS guard. Rejects the classic catastrophic-backtracking shape:
+// a quantifier (* + {n,}) applied to a group whose body itself contains an
+// unbounded quantifier — e.g. (a+)+, (a*)*, (.+)* . JS RegExp has no execution
+// timeout, and grep runs the pattern against attacker-influenceable file content
+// on the main thread, so one such pattern blocks the whole event loop. Errs toward
+// rejection; the agent simply rephrases. (Single-level nesting only — does not
+// detect deeply nested groups or overlapping alternation like (a|a)*.)
+const UNBOUNDED_QUANT = /[*+]|\{\d+,\}/;
+function looksCatastrophic(pattern) {
+  // A quantifier binds to the atom immediately before it — no whitespace between
+  // `)` and the quantifier in a real regex.
+  const groupQuant = /\(([^()]*)\)(?:[*+]|\{\d+,\})/g;
+  let m;
+  while ((m = groupQuant.exec(pattern)) !== null) {
+    // Drop escaped literals (\+ \* \{ …) so a group like (\+)+ — one-or-more
+    // literal plus signs, which is linear — isn't mistaken for a nested quantifier.
+    const body = m[1].replace(/\\./g, '');
+    if (UNBOUNDED_QUANT.test(body)) return true;
+  }
+  return false;
+}
+
 async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i' }) {
   const resolved = path.resolve(expandHome(rawPath));
   const cap = maxMatches || DEFAULT_GREP_MAX_MATCHES;
+  if (looksCatastrophic(pattern)) {
+    throw new Error(
+      `shell_grep: pattern rejected — nested unbounded quantifier (e.g. "(a+)+") risks catastrophic ` +
+      `backtracking that would block the process. Simplify the regex.`,
+    );
+  }
   let re;
   try {
     re = new RegExp(pattern, flags);