bare-agent 0.5.0 → 0.6.2

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** | 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 |
 | **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` |
@@ -74,7 +74,8 @@ Every piece works alone — take what you need, ignore the rest.
 | **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `MaxRoundsError`, `CircuitOpenError` |
 | **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) |
-| **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Allow/deny filtering, policy functions, `systemContext` for LLM awareness. Zero deps |
+| **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 |
+| **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Static allow/deny via `.mcp-bridge.json`, `systemContext` for LLM awareness. Runtime policy lives in `Loop({ policy })` — one hook for MCP + native tools alike. Zero deps |
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely.
 

package/package.json

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

package/src/loop.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const fs = require('node:fs');
 const { ToolError, MaxRoundsError } = require('./errors');
 
 // Average pricing per 1K tokens (USD). Adjust these to match your provider's rates.
@@ -39,6 +40,8 @@ class Loop {
    * @param {object} [options.retry] - Retry instance for backoff on failures.
    * @param {object} [options.stream] - Stream instance for event emission.
    * @param {object} [options.store] - Store instance for validate() health check.
+   * @param {Function} [options.policy] - Async (toolName, args) => true|false|string. Deny returns the string (or a generic message) to the LLM as tool result.
+   * @param {string} [options.audit] - File path for JSONL audit log. Each tool call appends one line: {ts, tool, args, decision, result|reason|error, durationMs}.
    * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
    */
   constructor(options = {}) {
@@ -54,8 +57,38 @@ class Loop {
     this.onError = options.onError || null;
     this.throwOnError = options.throwOnError !== undefined ? options.throwOnError : true;
     this.store = options.store || null;
+    if (options.policy != null && typeof options.policy !== 'function') {
+      throw new Error('[Loop] options.policy must be a function (toolName, args) => true | false | string');
+    }
+    this.policy = options.policy || null;
+    this.audit = options.audit || null;
     this._stopped = false;
     this._history = []; // for chat() stateful mode
+    this._auditInFlight = new Set();
+  }
+
+  // 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) {
+    if (!this.audit) return;
+    let line;
+    try {
+      line = JSON.stringify(record) + '\n';
+    } catch (err) {
+      console.warn(`[Loop] audit serialize failed: ${err.message}`);
+      return;
+    }
+    const p = fs.promises.appendFile(this.audit, line)
+      .catch(err => console.warn(`[Loop] audit write failed: ${err.message}`))
+      .finally(() => this._auditInFlight.delete(p));
+    this._auditInFlight.add(p);
+  }
+
+  // Await any in-flight audit writes. Safe to call multiple times; resolves immediately
+  // when no writes are pending. Called automatically at the end of each `run()`.
+  async flush() {
+    if (this._auditInFlight.size === 0) return;
+    await Promise.all([...this._auditInFlight]);
   }
 
   /**
@@ -107,6 +140,7 @@ class Loop {
       } catch (err) {
         this.stream?.emit({ type: 'loop:error', data: { error: err.message, round } });
         this.onError?.(err);
+        await this.flush();
         if (this.throwOnError) throw err;
         return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message };
       }
@@ -120,6 +154,7 @@ class Loop {
       if (!result.toolCalls || result.toolCalls.length === 0) {
         this.stream?.emit({ type: 'loop:text', data: { text: result.text } });
         this.onText?.(result.text);
+        await this.flush();
         this.stream?.emit({ type: 'loop:done', data: { text: result.text, usage: lastUsage, cost: totalCost } });
         return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null };
       }
@@ -163,23 +198,68 @@ class Loop {
         this.stream?.emit({ type: 'loop:tool_call', data: { tool: tc.name, args: tc.arguments } });
         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.
+        if (this.policy) {
+          let verdict;
+          try {
+            verdict = await this.policy(tc.name, tc.arguments);
+          } catch (err) {
+            verdict = `[Loop] policy error: ${err.message}`;
+          }
+          if (verdict !== true) {
+            const reason = typeof verdict === 'string'
+              ? 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._writeAudit({
+              ts: new Date().toISOString(),
+              tool: tc.name,
+              args: tc.arguments,
+              decision: 'deny',
+              reason,
+            });
+            continue;
+          }
+        }
+
+        const startedAt = Date.now();
         try {
           const execute = () => tool.execute(tc.arguments);
           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._writeAudit({
+            ts: new Date().toISOString(),
+            tool: tc.name,
+            args: tc.arguments,
+            decision: 'allow',
+            result: content,
+            durationMs: Date.now() - startedAt,
+          });
         } catch (err) {
           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._writeAudit({
+            ts: new Date().toISOString(),
+            tool: tc.name,
+            args: tc.arguments,
+            decision: 'allow',
+            error: toolErr.message,
+            durationMs: Date.now() - startedAt,
+          });
         }
       }
     }
 
     // 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 } });
     if (this.throwOnError) throw new MaxRoundsError(warning);
     return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: warning };

package/src/mcp-bridge.js

@@ -194,21 +194,15 @@ function unwrapContent(content) {
 
 // --- Tool wrapping ---
 
-function wrapTools(serverName, mcpTools, rpc, policy) {
+// Runtime arg-dependent policy has moved to Loop-level (new Loop({ policy })).
+// mcp-bridge retains only the static .mcp-bridge.json allow/deny filter below —
+// that decides which tools are exposed to the Loop in the first place.
+function wrapTools(serverName, mcpTools, rpc) {
   return mcpTools.map(t => ({
     name: `${serverName}_${t.name}`,
     description: t.description || '',
     parameters: t.inputSchema || { type: 'object', properties: {} },
     execute: async (args) => {
-      if (policy) {
-        const verdict = await policy(serverName, t.name, args);
-        if (verdict === false || typeof verdict === 'string') {
-          const reason = typeof verdict === 'string'
-            ? verdict
-            : `[GOVERNANCE] Tool "${serverName}_${t.name}" is not permitted by policy. Do not retry this tool.`;
-          throw new ToolError(reason, { context: { server: serverName, tool: t.name } });
-        }
-      }
       const result = await rpc('tools/call', { name: t.name, arguments: args });
       if (result.isError) {
         throw new ToolError(unwrapContent(result.content) || 'MCP tool error', {
@@ -327,11 +321,17 @@ function buildSystemContext(servers, tools, denied) {
  * @param {string[]} [opts.configPaths] - IDE config paths for discovery.
  * @param {string[]} [opts.servers] - Limit to these server names.
  * @param {number} [opts.timeout=15000] - Per-server init timeout in ms.
- * @param {Function} [opts.policy] - Async function(serverName, toolName, args) for runtime arg-dependent checks.
  * @param {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
  * @returns {Promise<{tools: Array, servers: string[], systemContext: string, denied: Array, close: Function}>}
  */
 async function createMCPBridge(opts = {}) {
+  if ('policy' in opts) {
+    throw new Error(
+      '[MCP Bridge] The `policy` option was removed in v0.6.0. Runtime arg-dependent policy is now Loop-level: ' +
+      'pass `policy` to `new Loop({ policy })` instead — it gates MCP tools identically to native tools. ' +
+      'The static allow/deny filter in .mcp-bridge.json is unchanged.'
+    );
+  }
   const bridgePath = opts.bridgePath || DEFAULT_BRIDGE_PATH();
   const timeout = opts.timeout || 15000;
 
@@ -411,7 +411,7 @@ async function createMCPBridge(opts = {}) {
 
       // Only wrap tools that are allowed in config
       const allowed = mcpTools.filter(t => allowedToolNames.includes(t.name));
-      const wrapped = wrapTools(name, allowed, client.rpc, opts.policy);
+      const wrapped = wrapTools(name, allowed, client.rpc);
 
       tools.push(...wrapped);
       children.push(client.child);

package/src/tools.js

@@ -2,5 +2,6 @@
 
 const { createBrowsingTools } = require('../tools/browse');
 const { createMobileTools } = require('../tools/mobile');
+const { createShellTools } = require('../tools/shell');
 
-module.exports = { createBrowsingTools, createMobileTools };
+module.exports = { createBrowsingTools, createMobileTools, createShellTools };

package/tools/shell.js

@@ -0,0 +1,286 @@
+'use strict';
+
+/**
+ * Pure-Node shell tools — cross-platform (linux, macOS, Windows), no external binaries.
+ *
+ * Three primitives:
+ *   shell_read  — read a file or list a directory
+ *   shell_grep  — regex search across files (JS regex, no grep/rg/findstr)
+ *   shell_exec  — run a shell command with timeout + max buffer
+ *
+ * All three run through Loop's policy hook when wired via `new Loop({ policy })`.
+ * Library ships zero baked-in allowlist — gating is the agent author's responsibility.
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { exec, execFile } = require('node:child_process');
+
+const DEFAULT_READ_MAX_BYTES = 256 * 1024;       // 256 KB
+const DEFAULT_GREP_MAX_MATCHES = 200;
+const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
+const DEFAULT_EXEC_MAX_BUFFER = 1024 * 1024;     // 1 MB
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p.startsWith('~/') || p === '~') {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, p.slice(1));
+  }
+  return p;
+}
+
+async function readEntry(rawPath, maxBytes) {
+  const resolved = path.resolve(expandHome(rawPath));
+  const stat = await fs.stat(resolved);
+  if (stat.isDirectory()) {
+    const entries = await fs.readdir(resolved, { withFileTypes: true });
+    const lines = entries.map(e => {
+      const kind = e.isDirectory() ? 'dir' : e.isSymbolicLink() ? 'link' : 'file';
+      return `${kind}\t${e.name}`;
+    });
+    return `dir ${resolved}\n${lines.join('\n')}`;
+  }
+  const cap = maxBytes || DEFAULT_READ_MAX_BYTES;
+  if (stat.size > cap) {
+    const fh = await fs.open(resolved, 'r');
+    try {
+      const buf = Buffer.alloc(cap);
+      await fh.read(buf, 0, cap, 0);
+      return buf.toString('utf8') + `\n\n[truncated: ${stat.size - cap} more bytes not shown]`;
+    } finally {
+      await fh.close();
+    }
+  }
+  return fs.readFile(resolved, 'utf8');
+}
+
+// Probe the first 1KB for NUL bytes to skip binary files in grep walks.
+async function isProbablyText(filePath) {
+  try {
+    const fh = await fs.open(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(1024);
+      const { bytesRead } = await fh.read(buf, 0, 1024, 0);
+      for (let i = 0; i < bytesRead; i++) {
+        if (buf[i] === 0) return false;
+      }
+      return true;
+    } finally {
+      await fh.close();
+    }
+  } catch {
+    return false;
+  }
+}
+
+async function* walk(dir, recursive) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive) yield* walk(full, true);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+
+async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i' }) {
+  const resolved = path.resolve(expandHome(rawPath));
+  const cap = maxMatches || DEFAULT_GREP_MAX_MATCHES;
+  let re;
+  try {
+    re = new RegExp(pattern, flags);
+  } catch (err) {
+    throw new Error(`shell_grep: invalid regex — ${err.message}`);
+  }
+
+  const hits = [];
+  const stat = await fs.stat(resolved).catch(() => null);
+  if (!stat) throw new Error(`shell_grep: path not found — ${rawPath}`);
+
+  const files = [];
+  if (stat.isFile()) {
+    files.push(resolved);
+  } else if (stat.isDirectory()) {
+    for await (const f of walk(resolved, recursive)) files.push(f);
+  }
+
+  for (const file of files) {
+    if (hits.length >= cap) break;
+    if (!(await isProbablyText(file))) continue;
+    let content;
+    try {
+      content = await fs.readFile(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (hits.length >= cap) break;
+      if (re.test(lines[i])) {
+        hits.push({ file, line: i + 1, text: lines[i].slice(0, 500) });
+      }
+    }
+  }
+
+  const truncated = hits.length >= cap;
+  return { hits, truncated, fileCount: files.length };
+}
+
+function runArgv({ argv, cwd, timeout, maxBuffer, env }) {
+  if (!Array.isArray(argv) || argv.length === 0 || typeof argv[0] !== 'string') {
+    return Promise.reject(new Error('shell_run: argv must be a non-empty array of strings, starting with the command'));
+  }
+  const [file, ...args] = argv;
+  return new Promise((resolve) => {
+    execFile(
+      file,
+      args,
+      {
+        cwd: cwd ? expandHome(cwd) : undefined,
+        timeout: timeout || DEFAULT_EXEC_TIMEOUT_MS,
+        maxBuffer: maxBuffer || DEFAULT_EXEC_MAX_BUFFER,
+        env: env ? { ...process.env, ...env } : process.env,
+        windowsHide: true,
+        shell: false,
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          if (err.killed) {
+            resolve({ stdout: stdout || '', stderr: stderr || '', code: null, timedOut: true });
+            return;
+          }
+          if (err.code === 'ENOENT') {
+            resolve({ stdout: '', stderr: `shell_run: command not found: ${file}`, code: null, timedOut: false });
+            return;
+          }
+          resolve({
+            stdout: stdout || '',
+            stderr: stderr || '',
+            code: typeof err.code === 'number' ? err.code : null,
+            timedOut: false,
+          });
+          return;
+        }
+        resolve({ stdout: stdout || '', stderr: stderr || '', code: 0, timedOut: false });
+      }
+    );
+  });
+}
+
+function execCommand({ command, cwd, timeout, maxBuffer, env }) {
+  return new Promise((resolve) => {
+    exec(
+      command,
+      {
+        cwd: cwd ? expandHome(cwd) : undefined,
+        timeout: timeout || DEFAULT_EXEC_TIMEOUT_MS,
+        maxBuffer: maxBuffer || DEFAULT_EXEC_MAX_BUFFER,
+        env: env ? { ...process.env, ...env } : process.env,
+        windowsHide: true,
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          if (err.killed) {
+            resolve({ stdout: stdout || '', stderr: stderr || '', code: null, timedOut: true });
+            return;
+          }
+          resolve({
+            stdout: stdout || '',
+            stderr: stderr || '',
+            code: typeof err.code === 'number' ? err.code : null,
+            timedOut: false,
+          });
+          return;
+        }
+        resolve({ stdout: stdout || '', stderr: stderr || '', code: 0, timedOut: false });
+      }
+    );
+  });
+}
+
+/**
+ * Create the three shell tools. No options — configuration is per-call via tool args,
+ * gating is the caller's responsibility via `new Loop({ policy })`.
+ *
+ * @returns {{tools: Array}}
+ */
+function createShellTools() {
+  const tools = [
+    {
+      name: 'shell_read',
+      description: 'Read a file or list a directory. Returns file contents (truncated at 256KB) or a tab-separated directory listing.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File or directory path. ~ expands to home.' },
+          maxBytes: { type: 'integer', description: 'Optional cap for file reads (default 262144).' },
+        },
+        required: ['path'],
+      },
+      execute: async ({ path: p, maxBytes }) => readEntry(p, maxBytes),
+    },
+    {
+      name: 'shell_grep',
+      description: 'Search for a JavaScript regex pattern across files. Skips binary files. Returns matching lines with file paths and line numbers.',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'JavaScript regex (without surrounding slashes).' },
+          path: { type: 'string', description: 'File or directory to search. ~ expands to home.' },
+          recursive: { type: 'boolean', description: 'Recurse into subdirectories (default true).' },
+          maxMatches: { type: 'integer', description: 'Stop after this many hits (default 200).' },
+          flags: { type: 'string', description: 'Regex flags, e.g. "i" or "gim" (default "i").' },
+        },
+        required: ['pattern', 'path'],
+      },
+      execute: async (args) => grepPath(args),
+    },
+    {
+      name: 'shell_run',
+      description: 'Run a command with an argv array (no shell, no interpolation) and return {stdout, stderr, code, timedOut}. Use this when a policy allowlist needs to match on argv[0] — no shell metacharacter injection is possible. Default timeout 30s, max output 1MB.',
+      parameters: {
+        type: 'object',
+        properties: {
+          argv: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Non-empty array of strings: argv[0] is the command, argv[1..] are its arguments. Spawned via child_process.execFile (shell: false).',
+          },
+          cwd: { type: 'string', description: 'Working directory. ~ expands to home.' },
+          timeout: { type: 'integer', description: 'Kill after this many ms (default 30000).' },
+          maxBuffer: { type: 'integer', description: 'Max stdout/stderr bytes (default 1048576).' },
+          env: { type: 'object', description: 'Additional env vars merged over process.env.' },
+        },
+        required: ['argv'],
+      },
+      execute: async (args) => runArgv(args),
+    },
+    {
+      name: 'shell_exec',
+      description: 'Run a raw shell command string via /bin/sh -c (or cmd.exe) and return {stdout, stderr, code, timedOut}. SECURITY: shell metacharacters (;, &&, |, `, $(), etc.) are interpreted — a naive base-command allowlist like `command.split(/\\s+/)[0]` is bypassable via "ls;rm -rf". Prefer shell_run for policy-gated use cases. Default timeout 30s, max output 1MB.',
+      parameters: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: 'Raw shell command string. Goes through the system shell.' },
+          cwd: { type: 'string', description: 'Working directory. ~ expands to home.' },
+          timeout: { type: 'integer', description: 'Kill after this many ms (default 30000).' },
+          maxBuffer: { type: 'integer', description: 'Max stdout/stderr bytes (default 1048576).' },
+          env: { type: 'object', description: 'Additional env vars merged over process.env.' },
+        },
+        required: ['command'],
+      },
+      execute: async (args) => execCommand(args),
+    },
+  ];
+  return { tools };
+}
+
+module.exports = { createShellTools };