bare-agent 0.8.0 → 0.10.0

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 };