bare-agent 0.8.0 → 0.9.0

package/README.md

@@ -11,7 +11,7 @@
 
 ```
 
-**Agent orchestration in ~2.4K lines of core. One required dep ([bareguard](https://npmjs.com/package/bareguard)). Apache 2.0.**
+**Agent orchestration in ~2.7K lines of core. One required dep ([bareguard](https://npmjs.com/package/bareguard) ^0.2.0). Apache 2.0.**
 
 Lightweight enough to understand completely. Complete enough to not reinvent wheels. Not a framework, not 50,000 lines of opinions — just composable building blocks for agents. Single-gate governance via bareguard: every tool call traverses one policy hook, one audit log, one budget cap.
 
@@ -76,7 +76,9 @@ Every piece works alone — take what you need, ignore the rest.
 | **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 |
-| **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 |
+| **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. Returns both bulk `tools` (one per MCP tool) and `metaTools` (`mcp_discover` + `mcp_invoke` for token-thrifty access to large catalogs). Zero deps |
+| **Spawn** | Fork a child bareagent process as a specialist agent. LLM-callable form blocks until child exits; library form returns a handle (`wait`, `onLine`, `kill`). One JSONL channel per child — child stderr captured and re-emitted as `child:stderr` events on the parent stream. Threads `BAREGUARD_AUDIT_PATH` / `BAREGUARD_PARENT_RUN_ID` / `BAREGUARD_BUDGET_FILE` / `BAREGUARD_SPAWN_DEPTH` so the family stitches into one audit + budget. `bareguard ^0.2.0` adds `spawn.ratePerMinute` + `limits.maxDepth` per-family caps |
+| **Defer** | Append a `{action, when}` record to a JSONL queue for a separate waker (cron / systemd timer / `examples/wake.sh`) to fire later. Two-phase governance: emit-time `gate.check` on the `defer` action; fire-time `gate.check` on the inner action when the waker re-invokes. `bareguard ^0.2.0` adds `defer.ratePerMinute` family-wide cap |
 
 **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.
 
@@ -84,7 +86,7 @@ Every piece works alone — take what you need, ignore the rest.
 
 **Cross-language:** Runs as a subprocess. Communicate via JSONL on stdin/stdout from Python, Go, Rust, Ruby, Java, or anything that can spawn a process. Ready-made wrappers in [`contrib/`](contrib/README.md).
 
-**Deps:** 1 required (`bareguard` for governance — single-gate policy + audit + budget). Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing), `baremobile` (Android + iOS device control), `wearehere` (privacy assessment via barebrowse).
+**Deps:** 1 required (`bareguard ^0.2.0` for governance — single-gate policy + audit + budget + per-family rate caps). Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing), `baremobile` (Android + iOS device control), `wearehere` (privacy assessment via barebrowse).
 
 ---
 

package/bin/cli.js

@@ -1,7 +1,35 @@
 #!/usr/bin/env node
 'use strict';
 
+/**
+ * bin/cli.js — bareagent subprocess entry point.
+ *
+ * Two modes (auto-detected by flag presence):
+ *
+ *   1. Stdio JSONL mode (no --config):
+ *      Reads JSONL requests `{ method, params: { goal | messages } }` from stdin,
+ *      runs Loop with no special tools, emits JSONL events on stdout. Used by
+ *      contrib/ subprocess wrappers and ad-hoc invocations.
+ *
+ *   2. Config-driven agent mode (--config <path>):
+ *      Loads a JSON specialist/orchestrator config, wires the configured tools
+ *      and bareguard Gate, reads ONE input record from stdin, runs Loop, emits
+ *      JSONL events on stdout, exits when loop:done fires. This is what the
+ *      `spawn` tool uses to fork child agents (PRD §10.6).
+ *
+ *      Config schema (v0.9):
+ *      {
+ *        "systemPrompt":  "string",
+ *        "provider":      "openai" | "anthropic" | "ollama",
+ *        "model":         "gpt-4o-mini" (etc),
+ *        "tools":         ["shell_read", "shell_grep", "spawn", "defer", ...],
+ *        "gate":          { ...bareguard config; humanChannel headless-defaults to deny }
+ *      }
+ */
+
 const { createInterface } = require('node:readline');
+const fs = require('node:fs');
+const path = require('node:path');
 const { Loop } = require('../src/loop');
 const { Stream } = require('../src/stream');
 const { JsonlTransport } = require('../src/transport-jsonl');
@@ -12,60 +40,221 @@ const flag = (name) => {
   return i >= 0 ? args[i + 1] : undefined;
 };
 
-const providerName = flag('provider') || 'openai';
-const model = flag('model');
+const configPath = flag('config');
+
+if (configPath) {
+  runConfigMode(configPath).catch((err) => {
+    process.stdout.write(JSON.stringify({ type: 'loop:error', data: { source: 'cli', error: err.message } }) + '\n');
+    process.exit(1);
+  });
+} else {
+  runStdioMode();
+}
+
+// ─── Mode 2: config-driven ────────────────────────────────────────────────
+
+async function runConfigMode(cfgPath) {
+  const cfg = readConfig(cfgPath);
+  const stream = new Stream({ transport: new JsonlTransport() });
+
+  // Provider
+  const provider = createProvider(cfg.provider || 'openai', cfg.model);
+
+  // Tools — registry resolved by name from a curated set of built-ins.
+  const tools = await resolveTools(cfg.tools || [], { stream });
+
+  // Bareguard Gate (optional but strongly recommended for spawn children)
+  let policy = null;
+  let wrapToolsFn = (t) => t;
+  if (cfg.gate) {
+    try {
+      const { Gate } = require('bareguard');
+      const { wireGate } = require('../src/bareguard-adapter');
+
+      // Headless humanChannel default: warn once, deny safely. Overridden if
+      // the config explicitly sets humanChannel (rare in JSON, but supported
+      // via a require path).
+      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);
+        humanChannel = require(fnPath);
+      }
+      if (typeof humanChannel !== 'function') {
+        let warned = false;
+        humanChannel = async (event) => {
+          if (!warned) {
+            process.stderr.write(`[cli] no humanChannel configured — ${event.kind} on ${event.rule} auto-denying.\n`);
+            warned = true;
+          }
+          return { decision: 'deny' };
+        };
+      }
+
+      const gate = new Gate({ ...cfg.gate, humanChannel });
+      await gate.init();
+      const wired = wireGate(gate);
+      policy = wired.policy;
+      wrapToolsFn = wired.wrapTools;
+    } catch (err) {
+      process.stderr.write(`[cli] failed to wire bareguard: ${err.message}. Continuing without policy gate.\n`);
+    }
+  }
+
+  // Read ONE input record from stdin (JSON or raw string). Treat blank stdin
+  // as no input — let the systemPrompt drive the loop alone.
+  const stdin = await readStdin();
+  const initialMessage = buildInitialMessage(cfg, stdin);
+
+  const loop = new Loop({
+    provider,
+    system: cfg.systemPrompt || null,
+    stream,
+    policy,
+    onError: (err, meta) => {
+      process.stderr.write(`[loop:error ${meta.source}] ${err.message}\n`);
+    },
+  });
+
+  const wrapped = wrapToolsFn(tools);
+  await loop.run([initialMessage], wrapped);
+  // Stream's loop:done event has already been emitted; exit clean.
+  process.exit(0);
+}
 
-function createProvider() {
-  if (providerName === 'openai') {
+function readConfig(cfgPath) {
+  const abs = path.resolve(cfgPath);
+  let raw;
+  try { raw = fs.readFileSync(abs, 'utf8'); }
+  catch (err) { throw new Error(`[cli] cannot read config at ${abs}: ${err.message}`); }
+  try { return JSON.parse(raw); }
+  catch (err) { throw new Error(`[cli] config at ${abs} is not valid JSON: ${err.message}`); }
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let buf = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { buf += chunk; });
+    process.stdin.on('end', () => resolve(buf.trim()));
+    // Safety: don't hang forever if stdin never closes.
+    setTimeout(() => resolve(buf.trim()), 100).unref();
+  });
+}
+
+function buildInitialMessage(cfg, stdin) {
+  if (!stdin) {
+    return { role: 'user', content: cfg.defaultPrompt || 'Begin.' };
+  }
+  // Try to parse as JSON; fall back to raw string.
+  let parsed;
+  try { parsed = JSON.parse(stdin); } catch { /* fine */ }
+  if (parsed && typeof parsed === 'object') {
+    if (typeof parsed.content === 'string') {
+      return { role: 'user', content: parsed.content };
+    }
+    return { role: 'user', content: JSON.stringify(parsed) };
+  }
+  return { role: 'user', content: stdin };
+}
+
+async function resolveTools(names, ctx) {
+  const tools = [];
+  for (const name of names) {
+    const resolved = await resolveOneTool(name, ctx);
+    if (resolved) tools.push(...(Array.isArray(resolved) ? resolved : [resolved]));
+  }
+  return tools;
+}
+
+async function resolveOneTool(name, ctx) {
+  switch (name) {
+    case 'shell_read':
+    case 'shell_grep':
+    case 'shell_run':
+    case 'shell_exec': {
+      const { createShellTools } = require('../tools/shell');
+      const { tools } = createShellTools();
+      return tools.find(t => t.name === name) || null;
+    }
+    case 'shell_*': {
+      const { createShellTools } = require('../tools/shell');
+      return createShellTools().tools;
+    }
+    case 'spawn': {
+      const { createSpawnTool } = require('../tools/spawn');
+      return createSpawnTool({ stream: ctx.stream }).tool;
+    }
+    case 'defer': {
+      const { createDeferTool } = require('../tools/defer');
+      return createDeferTool().tool;
+    }
+    default:
+      process.stderr.write(`[cli] unknown tool name in config: ${name}\n`);
+      return null;
+  }
+}
+
+// ─── Mode 1: stdio JSONL (legacy) ─────────────────────────────────────────
+
+function runStdioMode() {
+  const providerName = flag('provider') || 'openai';
+  const model = flag('model');
+  const stream = new Stream({ transport: new JsonlTransport() });
+  const loop = new Loop({ provider: createProvider(providerName, model), stream });
+
+  let pending = 0;
+  let closing = false;
+
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', async (line) => {
+    pending++;
+    try {
+      const req = JSON.parse(line);
+      const messages = req.params?.messages || [
+        { role: 'user', content: req.params?.goal || '' },
+      ];
+      const result = await loop.run(messages, []);
+      stream.emit({ type: 'result', data: result });
+    } catch (err) {
+      stream.emit({ type: 'error', data: { error: err.message } });
+    } finally {
+      pending--;
+      if (closing && pending === 0) process.exit(0);
+    }
+  });
+
+  rl.on('close', () => {
+    closing = true;
+    if (pending === 0) process.exit(0);
+  });
+}
+
+// ─── Shared: provider construction ────────────────────────────────────────
+
+function createProvider(name, model) {
+  if (name === 'openai') {
     const { OpenAIProvider } = require('../src/provider-openai');
     return new OpenAIProvider({
       apiKey: process.env.OPENAI_API_KEY,
       ...(model && { model }),
     });
   }
-  if (providerName === 'anthropic') {
+  if (name === 'anthropic') {
     const { AnthropicProvider } = require('../src/provider-anthropic');
     return new AnthropicProvider({
       apiKey: process.env.ANTHROPIC_API_KEY,
       ...(model && { model }),
     });
   }
-  if (providerName === 'ollama') {
+  if (name === 'ollama') {
     const { OllamaProvider } = require('../src/provider-ollama');
     return new OllamaProvider({
       ...(model && { model }),
       ...(flag('url') && { url: flag('url') }),
     });
   }
-  process.stderr.write(`Unknown provider: ${providerName}\n`);
+  process.stderr.write(`Unknown provider: ${name}\n`);
   process.exit(1);
 }
-
-const stream = new Stream({ transport: new JsonlTransport() });
-const loop = new Loop({ provider: createProvider(), stream });
-
-let pending = 0;
-let closing = false;
-
-const rl = createInterface({ input: process.stdin });
-rl.on('line', async (line) => {
-  pending++;
-  try {
-    const req = JSON.parse(line);
-    const messages = req.params?.messages || [
-      { role: 'user', content: req.params?.goal || '' },
-    ];
-    const result = await loop.run(messages, []);
-    stream.emit({ type: 'result', data: result });
-  } catch (err) {
-    stream.emit({ type: 'error', data: { error: err.message } });
-  } finally {
-    pending--;
-    if (closing && pending === 0) process.exit(0);
-  }
-});
-
-rl.on('close', () => {
-  closing = true;
-  if (pending === 0) process.exit(0);
-});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "files": [
     "index.js",
     "src/",
@@ -9,7 +9,7 @@
     "LICENSE",
     "NOTICE"
   ],
-  "description": "Lightweight, composable agent orchestration for autonomous agents. Single-gate governance via bareguard, cross-platform shell tools, MCP bridge. ~2.4K lines core, one required dep.",
+  "description": "Lightweight, composable agent orchestration for autonomous agents. Multi-agent primitives (spawn, defer, MCP meta-tools), single-gate governance via bareguard, cross-platform shell tools, MCP bridge. ~2.7K lines core, one required dep.",
   "license": "Apache-2.0",
   "author": "hamr0",
   "repository": {
@@ -44,7 +44,7 @@
     "governance"
   ],
   "dependencies": {
-    "bareguard": "^0.1.1"
+    "bareguard": "^0.2.0"
   },
   "optionalDependencies": {
     "barebrowse": "^0.5.0",
@@ -60,6 +60,6 @@
     }
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "node --test --test-force-exit test/**/*.test.js"
   }
 }

package/src/mcp-bridge.js

@@ -219,29 +219,30 @@ function wrapTools(serverName, mcpTools, rpc) {
 async function killServer(child) {
   if (child.exitCode !== null) return;
 
-  child.stdin?.destroy();
+  // end() sends FIN so the child sees stdin EOF and can exit cleanly;
+  // destroy() alone does not always propagate.
+  try { child.stdin?.end(); } catch { /* already closed */ }
   child.stdout?.destroy();
   child.stderr?.destroy();
 
-  await new Promise(resolve => {
-    const onClose = () => resolve();
+  // Short grace, then SIGTERM, then SIGKILL. Each wait clears its timer
+  // promptly when the child closes so we don't block the event loop after
+  // exit (which kept node:test's file-level wrapper hanging).
+  const waitClose = (ms) => new Promise(resolve => {
+    let timer;
+    const onClose = () => { clearTimeout(timer); resolve(); };
     child.once('close', onClose);
-    setTimeout(() => {
+    timer = setTimeout(() => {
       child.removeListener('close', onClose);
       resolve();
-    }, 700);
+    }, ms);
   });
 
+  await waitClose(150);
+
   if (child.exitCode === null) {
     child.kill('SIGTERM');
-    await new Promise(resolve => {
-      const onClose = () => resolve();
-      child.once('close', onClose);
-      setTimeout(() => {
-        child.removeListener('close', onClose);
-        resolve();
-      }, 700);
-    });
+    await waitClose(300);
   }
 
   if (child.exitCode === null) {
@@ -262,11 +263,12 @@ async function connectAndListTools(name, def, timeout = 15000) {
     clientInfo: { name: 'bare-agent', version: '0.5.0' },
   });
 
-  const timer = new Promise((_, reject) =>
-    setTimeout(() => reject(new ToolError(`MCP server "${name}" init timed out after ${timeout}ms`)), timeout)
-  );
+  let timerId;
+  const timer = new Promise((_, reject) => {
+    timerId = setTimeout(() => reject(new ToolError(`MCP server "${name}" init timed out after ${timeout}ms`)), timeout);
+  });
 
-  await Promise.race([init, timer]);
+  try { await Promise.race([init, timer]); } finally { clearTimeout(timerId); }
   client.notify('notifications/initialized');
 
   const { tools: mcpTools } = await client.rpc('tools/list');
@@ -308,6 +310,103 @@ function buildSystemContext(servers, tools, denied) {
   return lines.join('\n');
 }
 
+// --- Meta-tools: mcp_discover + mcp_invoke (v0.9) ---
+
+/**
+ * Build the LLM-callable meta-tool surface from a fully-connected bridge.
+ * Shares the underlying tool array and RPC clients with the bulk surface —
+ * one set of connections, one factory, two output forms. The user picks
+ * `bridge.tools` (bulk) for small catalogs the LLM should see upfront, or
+ * `bridge.metaTools` for large catalogs the LLM should discover on demand.
+ *
+ * Gov shape: when the LLM calls mcp_invoke, the action sent to gate.check
+ * is `{ type: 'mcp_invoke', args: { name, args }, _ctx }` — bareguard sees
+ * `mcp_invoke` as the type. To deny specific MCP tools, use bareguard's
+ * `tools.denyArgPatterns: { mcp_invoke: [/"name":"linear_admin_.*"/] }`
+ * or `content.denyPatterns` over the JSON-serialized form. The inner MCP
+ * tool name doesn't travel as `action.type` — that's a deliberate v0.9
+ * trade for one consistent gate-check call per LLM tool invocation.
+ *
+ * @param {Array} tools - The bulk-loaded, name-prefixed tools array.
+ * @param {string} discoveredAt - ISO timestamp from .mcp-bridge.json.
+ * @returns {Array} [mcp_discover, mcp_invoke]
+ */
+function buildMetaTools(tools, discoveredAt) {
+  // Catalog descriptors: same info the LLM would see for bulk-loaded tools,
+  // but exposed via mcp_discover instead of taking up tool-array slots upfront.
+  const catalog = tools.map(t => {
+    const sep = t.name.indexOf('_');
+    return {
+      name: t.name,
+      description: t.description || '',
+      schema: t.parameters || { type: 'object', properties: {} },
+      server: sep > 0 ? t.name.slice(0, sep) : t.name,
+      tool: sep > 0 ? t.name.slice(sep + 1) : '',
+    };
+  });
+  const byName = new Map(tools.map(t => [t.name, t]));
+
+  const mcpDiscover = {
+    name: 'mcp_discover',
+    description:
+      'List MCP tools currently available across all configured servers. Returns descriptors with name, description, schema, server, and tool. Pass refresh:true to force a fresh discovery (otherwise the catalog is the one loaded at agent startup). Discovery itself is ungated — read-only catalog access. Gov decisions still happen at invoke time via mcp_invoke.',
+    parameters: {
+      type: 'object',
+      properties: {
+        refresh: {
+          type: 'boolean',
+          description: 'Currently a no-op flag in v0.9 — the catalog is loaded once at bridge construction. Set true to signal intent; behavior may change in a later version.',
+        },
+        server: {
+          type: 'string',
+          description: 'Optional: filter the catalog to one server name.',
+        },
+      },
+    },
+    execute: async ({ server } = {}) => {
+      const filtered = server
+        ? catalog.filter(t => t.server === server)
+        : catalog;
+      return {
+        tools: filtered,
+        cachedAt: discoveredAt || new Date().toISOString(),
+        count: filtered.length,
+      };
+    },
+  };
+
+  const mcpInvoke = {
+    name: 'mcp_invoke',
+    description:
+      'Invoke an MCP tool by its canonical bareagent name (the `name` field returned by mcp_discover, e.g. "linear_list_issues"). Args are passed through to the underlying MCP server. Returns the tool result. Bareguard governs every invocation — denies fed back as deny strings, halts as [HALT] strings.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Canonical MCP tool name (from mcp_discover). Format: <server>_<tool>.',
+        },
+        args: {
+          type: 'object',
+          description: 'Arguments for the MCP tool, matching its schema (also from mcp_discover).',
+        },
+      },
+      required: ['name'],
+    },
+    execute: async ({ name, args }) => {
+      const tool = byName.get(name);
+      if (!tool) {
+        throw new ToolError(`mcp_invoke: unknown tool "${name}". Call mcp_discover for the current catalog.`, {
+          context: { name, knownNames: [...byName.keys()] },
+        });
+      }
+      return await tool.execute(args || {});
+    },
+  };
+
+  return [mcpDiscover, mcpInvoke];
+}
+
 // --- Main entry point ---
 
 /**
@@ -316,13 +415,22 @@ function buildSystemContext(servers, tools, denied) {
  * On subsequent runs, reads .mcp-bridge.json and respects allow/deny per tool.
  * Re-discovers when TTL expires (default: 24h).
  *
+ * Returns BOTH surfaces (v0.9+):
+ *   - `tools`     — bulk-loaded array of name-prefixed tools (small catalogs;
+ *                   LLM sees them upfront).
+ *   - `metaTools` — [mcp_discover, mcp_invoke] LLM-callable pair (large catalogs;
+ *                   LLM picks tools dynamically). Shares the same RPC connections.
+ *
+ * Wire one or the other into Loop's tool array; never both (the LLM would see
+ * the same MCP tool twice). Pick by catalog size and token budget.
+ *
  * @param {object} [opts]
  * @param {string} [opts.bridgePath] - Path to .mcp-bridge.json. Default: .mcp-bridge.json in cwd.
  * @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 {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
- * @returns {Promise<{tools: Array, servers: string[], systemContext: string, denied: Array, close: Function}>}
+ * @returns {Promise<{tools: Array, metaTools: Array, servers: string[], systemContext: string, denied: Array, close: Function}>}
  */
 async function createMCPBridge(opts = {}) {
   if ('policy' in opts) {
@@ -435,8 +543,11 @@ async function createMCPBridge(opts = {}) {
   const systemContext = buildSystemContext(connected, tools, denied);
   if (connected.length > 0) console.log(systemContext);
 
+  const metaTools = buildMetaTools(tools, config?.discovered);
+
   return {
     tools,
+    metaTools,
     servers: connected,
     denied,
     systemContext,
@@ -447,4 +558,4 @@ async function createMCPBridge(opts = {}) {
   };
 }
 
-module.exports = { createMCPBridge, discoverServers };
+module.exports = { createMCPBridge, discoverServers, buildMetaTools };

package/src/mcp.js

@@ -1,5 +1,5 @@
 'use strict';
 
-const { createMCPBridge, discoverServers } = require('./mcp-bridge');
+const { createMCPBridge, discoverServers, buildMetaTools } = require('./mcp-bridge');
 
-module.exports = { createMCPBridge, discoverServers };
+module.exports = { createMCPBridge, discoverServers, buildMetaTools };

package/src/retry.js

@@ -35,15 +35,23 @@ class Retry {
     const timeout = options.timeout || this.timeout;
 
     for (let attempt = 1; attempt <= max; attempt++) {
+      let timeoutId;
       try {
         const result = await (timeout
-          ? Promise.race([fn(), new Promise((_, rej) => setTimeout(() => rej(new TimeoutError('[Retry] Timeout')), timeout))])
+          ? Promise.race([
+              fn(),
+              new Promise((_, rej) => {
+                timeoutId = setTimeout(() => rej(new TimeoutError('[Retry] Timeout')), timeout);
+              }),
+            ])
           : fn());
         return result;
       } catch (err) {
         if (attempt === max || !retryOn(err)) throw err;
         const delay = this._delay(attempt);
         await new Promise(r => setTimeout(r, delay));
+      } finally {
+        if (timeoutId) clearTimeout(timeoutId);
       }
     }
   }

package/src/tools.js

@@ -3,5 +3,15 @@
 const { createBrowsingTools } = require('../tools/browse');
 const { createMobileTools } = require('../tools/mobile');
 const { createShellTools } = require('../tools/shell');
+const { createSpawnTool, spawnChild } = require('../tools/spawn');
+const { createDeferTool, readQueue: readDeferQueue } = require('../tools/defer');
 
-module.exports = { createBrowsingTools, createMobileTools, createShellTools };
+module.exports = {
+  createBrowsingTools,
+  createMobileTools,
+  createShellTools,
+  createSpawnTool,
+  spawnChild,
+  createDeferTool,
+  readDeferQueue,
+};

package/tools/defer.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * tools/defer.js — emit a deferred-action record to a JSONL queue.
+ *
+ * LLM-callable form: `defer({ action, when })` appends ONE JSONL record
+ * to the defer queue file and returns `{ id }`. bareagent does NOT wake
+ * up later — the running process exits when the loop ends. An external
+ * scheduler (cron + `examples/wake.sh`) reads the queue and fires due
+ * actions by re-invoking bareagent.
+ *
+ * Two-phase gate semantics (per bareagent PRD §10.7 + bareguard PRD §14):
+ *   - At emit (this tool): one gate.check on `{ type: 'defer', args: { action, when }, _ctx }`
+ *     runs the full pipeline (defer.ratePerMinute, tools.allowlist on `defer`,
+ *     content.* over the JSON-serialized form). Bareguard does NOT extract
+ *     args.action and run a second pipeline against it at emit time.
+ *   - At fire (wake.sh invokes bareagent with the inner action): a separate
+ *     gate.check runs the full pipeline against the inner action as a fresh
+ *     action. Two distinct gate.check calls, two distinct audit lines,
+ *     reconstructable via parent_run_id.
+ *
+ * Queue file format — one JSON record per line, append-only:
+ *   { id, ts_emitted, when, action, parent_run_id, status }
+ * Status updates are appends, not edits: wake.sh appends
+ *   { id, status: 'fired', ts }
+ * Reconstruction folds by `id` (latest wins).
+ *
+ * Default queue path: ./bareagent-defers.jsonl (cwd-only, project-scoped).
+ * Override via BAREAGENT_DEFER_QUEUE env var or createDeferTool({queuePath}).
+ */
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DEFAULT_QUEUE_PATH = './bareagent-defers.jsonl';
+const ID_PREFIX = 'def_';
+
+/**
+ * Generate a sortable, unique id. 9-char base36 timestamp + 20-char hex
+ * random. Lexicographically sortable by emit time; unique enough for any
+ * realistic defer rate. Same shape as the PRD's `def_01J...` sketch.
+ */
+function generateId() {
+  const ts = Date.now().toString(36).padStart(9, '0');
+  const rand = crypto.randomBytes(10).toString('hex');
+  return `${ID_PREFIX}${ts}_${rand}`;
+}
+
+/**
+ * Resolve the active queue path. Precedence:
+ *   1. Caller-supplied option (createDeferTool({ queuePath: '...' }))
+ *   2. BAREAGENT_DEFER_QUEUE env var
+ *   3. ./bareagent-defers.jsonl
+ */
+function resolveQueuePath(option) {
+  return option
+    || process.env.BAREAGENT_DEFER_QUEUE
+    || DEFAULT_QUEUE_PATH;
+}
+
+/**
+ * Validate a `when` field. Accepts an ISO 8601 timestamp string. Rejects
+ * past timestamps loosely (more than 60s in the past) — the wake script
+ * would fire them immediately, which is almost always not what the agent
+ * meant. Future timestamps within reason are accepted as-is.
+ *
+ * Returns { ok: true, iso } on success, { ok: false, error } on failure.
+ */
+function validateWhen(when) {
+  if (typeof when !== 'string' || !when) {
+    return { ok: false, error: 'when must be an ISO 8601 timestamp string' };
+  }
+  const t = Date.parse(when);
+  if (Number.isNaN(t)) {
+    return { ok: false, error: `when is not a valid ISO 8601 timestamp: ${when}` };
+  }
+  const driftMs = Date.now() - t;
+  if (driftMs > 60_000) {
+    return { ok: false, error: `when is more than 60s in the past (drift=${driftMs}ms) — would fire immediately` };
+  }
+  return { ok: true, iso: new Date(t).toISOString() };
+}
+
+/**
+ * Validate an `action` field. Must be an object with a string `type`.
+ * Anything else is the LLM either confused or trying to defer something
+ * meaningless.
+ */
+function validateAction(action) {
+  if (!action || typeof action !== 'object' || Array.isArray(action)) {
+    return { ok: false, error: 'action must be an object' };
+  }
+  if (typeof action.type !== 'string' || !action.type) {
+    return { ok: false, error: 'action.type must be a non-empty string' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Append one JSONL record to the queue file. fs.promises.appendFile is
+ * atomic for writes < PIPE_BUF on POSIX (4KB on Linux); a JSON record
+ * with a small action is well under that.
+ */
+async function appendRecord(queuePath, record) {
+  const dir = path.dirname(path.resolve(queuePath));
+  // Best-effort dir creation; ignore "already exists".
+  try { await fsp.mkdir(dir, { recursive: true }); } catch { /* fine */ }
+  const line = JSON.stringify(record) + '\n';
+  if (line.length > 4000) {
+    // Soft guard — if the action payload is huge, the audit-and-fire chain
+    // will still work but POSIX atomicity guarantee is gone. Warn.
+    process.stderr.write(`[defer] record is ${line.length}B (> ~4KB POSIX_PIPE_BUF) — atomicity not guaranteed\n`);
+  }
+  await fsp.appendFile(queuePath, line);
+}
+
+/**
+ * Read the queue and reconstruct the live status of each id by folding
+ * append-only status lines (latest wins). Exposed for tests + library
+ * users; the wake script does its own jq-based fold.
+ */
+async function readQueue(queuePath) {
+  const path = resolveQueuePath(queuePath);
+  try {
+    const text = await fsp.readFile(path, 'utf8');
+    const records = {};
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }
+      if (!r.id) continue;
+      records[r.id] = { ...records[r.id], ...r };
+    }
+    return Object.values(records);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.queuePath] - Override queue file path.
+ * @returns {{tool: object, readQueue: Function}}
+ */
+function createDeferTool(options = {}) {
+  const queuePath = resolveQueuePath(options.queuePath);
+
+  const tool = {
+    name: 'defer',
+    description:
+      'Append a deferred action to the queue. The action will be fired at or after `when` by the external wake script (cron + examples/wake.sh). bareagent does NOT wake up — the queue is project-scoped JSONL on disk. Returns { id }. Use sparingly: defer.ratePerMinute caps emits per agent family (default 15/min in bareguard 0.2).',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'object',
+          description: 'The action to fire. Must have a string `type` field naming a tool the wake-time agent can invoke (e.g. `{ type: "spawn", args: { config: "specialists/check-ci.json" } }`).',
+        },
+        when: {
+          type: 'string',
+          description: 'ISO 8601 timestamp for when to fire (e.g. "2026-04-30T18:00:00Z"). Must not be more than 60s in the past.',
+        },
+      },
+      required: ['action', 'when'],
+    },
+    execute: async ({ action, when }) => {
+      const a = validateAction(action);
+      if (!a.ok) throw new Error(`[defer] ${a.error}`);
+      const w = validateWhen(when);
+      if (!w.ok) throw new Error(`[defer] ${w.error}`);
+
+      const record = {
+        id: generateId(),
+        ts_emitted: new Date().toISOString(),
+        when: w.iso,
+        action,
+        parent_run_id:
+          process.env.BAREGUARD_RUN_ID
+          || process.env.BAREGUARD_PARENT_RUN_ID
+          || null,
+        status: 'pending',
+      };
+      await appendRecord(queuePath, record);
+      return { id: record.id };
+    },
+  };
+
+  return {
+    tool,
+    readQueue: () => readQueue(queuePath),
+    queuePath,
+  };
+}
+
+module.exports = {
+  createDeferTool,
+  readQueue,
+  generateId,        // exported for tests
+  resolveQueuePath,  // exported for tests
+};

package/tools/spawn.js

@@ -0,0 +1,242 @@
+'use strict';
+
+/**
+ * tools/spawn.js — fork a child bareagent process.
+ *
+ * LLM-callable form: `spawn({ config, input? })` blocks until the child
+ * exits and returns the child's final result. Per the PRD: LLMs don't
+ * manage handles across tool calls, so blocking is the only sane LLM
+ * surface. Library callers can use the lower-level `spawnChild()` export
+ * for fire-and-forget / handle-based use.
+ *
+ * The child is bareagent itself, invoked as:
+ *   <node> <bin/cli.js> --config <config-path>
+ *
+ * Env-var threading (per bareguard 0.1.1+ stitching contract):
+ *   - BAREGUARD_AUDIT_PATH    — single audit file across the family
+ *   - BAREGUARD_BUDGET_FILE   — shared budget ledger
+ *   - BAREGUARD_PARENT_RUN_ID — parent's run_id becomes child's parent
+ *   - BAREGUARD_SPAWN_DEPTH   — incremented; bareguard.limits.maxDepth caps it
+ *
+ * Stream model (per v0.9 §10.6 decision):
+ *   ONE JSONL channel per child. Child stdout is the structured event
+ *   stream. Child stderr is captured here and re-emitted as
+ *   `{type: 'child:stderr', text, ts}` events on the parent's stream
+ *   (if any). No two-channel split.
+ *
+ * Action shape sent to gate.check (when wired through wireGate):
+ *   { type: 'spawn', args: { config, input }, _ctx }
+ *   Bareguard treats `args` as opaque — content patterns scan the
+ *   JSON-serialized form. spawn.ratePerMinute (bareguard 0.2+) caps emits
+ *   per-family.
+ */
+
+const { spawn: cpSpawn } = require('node:child_process');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000; // 10 min — children should finish or be killed
+
+/**
+ * Resolve the bareagent CLI path. Prefers the local repo's bin/cli.js so
+ * the test suite + dev runs use the in-tree CLI; falls back to npx.
+ */
+function resolveCliPath() {
+  // tools/spawn.js → ../bin/cli.js (works in dev tree and when installed via npm)
+  return path.resolve(__dirname, '..', 'bin', 'cli.js');
+}
+
+/**
+ * Library-level: spawn a child and return a handle.
+ *
+ * Returns: {
+ *   wait()      — Promise<{ text, usage, cost, error, events }>
+ *   onLine(fn)  — subscribe to every JSONL event from child stdout
+ *   kill(sig?)  — terminate the child
+ *   pid         — child process id
+ * }
+ *
+ * Use this from library code; the LLM-callable tool below wraps it with blocking semantics.
+ */
+function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
+  if (typeof config !== 'string' || !config) {
+    throw new Error('[spawn] requires { config: <path> }');
+  }
+  const cli = cliPath || resolveCliPath();
+  const child = cpSpawn(process.execPath, [cli, '--config', config], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      BAREGUARD_AUDIT_PATH:    process.env.BAREGUARD_AUDIT_PATH || '',
+      BAREGUARD_BUDGET_FILE:   process.env.BAREGUARD_BUDGET_FILE || '',
+      BAREGUARD_PARENT_RUN_ID: process.env.BAREGUARD_RUN_ID
+        || process.env.BAREGUARD_PARENT_RUN_ID
+        || '',
+      BAREGUARD_SPAWN_DEPTH:   String((Number(process.env.BAREGUARD_SPAWN_DEPTH) || 0) + 1),
+    },
+  });
+
+  if (input !== undefined) {
+    child.stdin.write(JSON.stringify(input) + '\n');
+  }
+  child.stdin.end();
+
+  const events = [];
+  const lineSubscribers = [];
+  const onLine = (fn) => { lineSubscribers.push(fn); return () => {
+    const i = lineSubscribers.indexOf(fn);
+    if (i >= 0) lineSubscribers.splice(i, 1);
+  }; };
+
+  // stdout — JSONL events from the child loop
+  const outRl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+  outRl.on('line', (line) => {
+    if (!line) return;
+    let event;
+    try { event = JSON.parse(line); }
+    catch {
+      // Not JSON — treat as raw text on the child's stdout (rare; surface as event)
+      event = { type: 'child:stdout_raw', text: line, ts: new Date().toISOString() };
+    }
+    events.push(event);
+    for (const fn of lineSubscribers) {
+      try { fn(event); } catch (err) {
+        // never let a subscriber kill the read loop
+        process.stderr.write(`[spawn] onLine subscriber threw: ${err.message}\n`);
+      }
+    }
+  });
+
+  // stderr — re-emit as child:stderr events on the same JSONL channel.
+  // Per the v0.9 decision: one stream per child. Wake.sh captures everything
+  // (events + debug) by redirecting child stdout alone; stderr was the
+  // *parent's* problem to consolidate into the JSONL stream.
+  const errRl = readline.createInterface({ input: child.stderr, crlfDelay: Infinity });
+  errRl.on('line', (line) => {
+    if (!line) return;
+    const event = { type: 'child:stderr', text: line, ts: new Date().toISOString() };
+    events.push(event);
+    if (stream) {
+      try { stream.emit(event); } catch { /* swallow */ }
+    }
+  });
+
+  // Pre-register close-event promises NOW (not lazily inside child.on('exit')).
+  // The close event can fire before the exit handler runs; attaching .once()
+  // after the fact would hang forever.
+  const outClosePromise = new Promise(r => outRl.once('close', r));
+  const errClosePromise = new Promise(r => errRl.once('close', r));
+
+  // Timeout: kill child if it overruns. The grace period after SIGTERM is 5s
+  // before SIGKILL — enough for the child to flush its final JSONL line.
+  let killTimer = null;
+  if (timeoutMs && timeoutMs > 0) {
+    killTimer = setTimeout(() => {
+      try { child.kill('SIGTERM'); } catch { /* already dead */ }
+      setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* already dead */ } }, 5000).unref();
+    }, timeoutMs);
+    killTimer.unref();
+  }
+
+  const exitPromise = new Promise((resolve) => {
+    child.on('exit', async (code, signal) => {
+      if (killTimer) clearTimeout(killTimer);
+      // Drain stdio readlines before resolving — last line may still be in buffer.
+      await Promise.all([outClosePromise, errClosePromise]);
+      resolve({ code, signal });
+    });
+    child.on('error', (err) => {
+      if (killTimer) clearTimeout(killTimer);
+      resolve({ code: null, signal: null, spawnError: err });
+    });
+  });
+
+  async function wait() {
+    const { code, signal, spawnError } = await exitPromise;
+    if (spawnError) {
+      return {
+        text: '',
+        usage: { inputTokens: 0, outputTokens: 0 },
+        cost: 0,
+        error: `[spawn] failed to spawn child: ${spawnError.message}`,
+        events,
+        exitCode: null,
+        signal: null,
+      };
+    }
+    // Pluck the final loop:done event — that's the canonical child result.
+    const done = events.findLast?.(e => e.type === 'loop:done')
+      || [...events].reverse().find(e => e.type === 'loop:done');
+    if (done) {
+      return {
+        text: done.data?.text || '',
+        usage: done.data?.usage || { inputTokens: 0, outputTokens: 0 },
+        cost: done.data?.cost ?? 0,
+        error: done.data?.warning || null,
+        events,
+        exitCode: code,
+        signal,
+      };
+    }
+    // No loop:done — child exited abnormally or never reached the LLM.
+    const errEvent = events.find(e => e.type === 'loop:error' || e.type === 'error');
+    return {
+      text: '',
+      usage: { inputTokens: 0, outputTokens: 0 },
+      cost: 0,
+      error: errEvent?.data?.error || `[spawn] child exited (code=${code}, signal=${signal}) without loop:done`,
+      events,
+      exitCode: code,
+      signal,
+    };
+  }
+
+  function kill(sig = 'SIGTERM') {
+    try { child.kill(sig); } catch { /* already dead */ }
+  }
+
+  return { wait, onLine, kill, pid: child.pid };
+}
+
+/**
+ * LLM-callable spawn tool. Blocks; returns the child's final result.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cliPath] - Override the bareagent CLI path (default: ./bin/cli.js relative to this file).
+ * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min).
+ * @param {object} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
+ * @returns {{tool: object, spawnChild: Function}}
+ */
+function createSpawnTool(options = {}) {
+  const tool = {
+    name: 'spawn',
+    description:
+      'Fork a child bareagent process with the given config file and optional JSON input. Blocks until the child finishes; returns its final {text, usage, cost, error, events}. Use this to delegate work to a specialist agent. Per-family limits (maxChildren, maxDepth, spawn.ratePerMinute) are enforced by bareguard.',
+    parameters: {
+      type: 'object',
+      properties: {
+        config: {
+          type: 'string',
+          description: 'Path to a bareagent config JSON file (specialist definition). Resolved relative to the parent process cwd.',
+        },
+        input: {
+          description: 'Optional JSON input passed to the child on stdin (any shape; the child config decides how to interpret it).',
+        },
+      },
+      required: ['config'],
+    },
+    execute: async ({ config, input }) => {
+      const handle = spawnChild({
+        config,
+        input,
+        cliPath: options.cliPath,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        stream: options.stream,
+      });
+      return await handle.wait();
+    },
+  };
+  return { tool, spawnChild };
+}
+
+module.exports = { createSpawnTool, spawnChild };