bare-agent 0.12.1 → 0.12.2

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.12.1 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
+> v0.12.2 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 

package/examples/README.md

@@ -0,0 +1,14 @@
+# examples
+
+Runnable reference scripts for bare-agent. Each is self-contained — the top-of-file docstring documents flags and required env vars. These ship in the npm package, so you can copy them straight out of `node_modules/bare-agent/examples/`.
+
+| Example | What it shows |
+|---------|---------------|
+| [`with-bareguard.mjs`](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`](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`](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/`](orchestrator/) | Multi-agent dispatch via `spawn`. Three configs, one system prompt — no orchestrator class, no role types. Roles are JSON files. See its [README](orchestrator/README.md). |
+| [`wake.sh`](wake.sh) + [`wake.md`](wake.md) | Reference cron + jq script for firing deferred actions. The runtime half of `createDeferTool` — bareagent emits, `wake.sh` fires. |
+| [`replay-job.js`](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. |
+
+For wiring recipes and API details see the [Integration Guide](../bareagent.context.md); for usage patterns and design philosophy see the [Usage Guide](../docs/02-features/usage-guide.md).

package/examples/mcp-bridge-concurrent.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Concurrent MCP stress test — real domains, real payloads, varying complexity.
+ *
+ * Usage:
+ *   node examples/mcp-bridge-concurrent.js
+ */
+
+const { readFileSync } = require('node:fs');
+const { createMCPBridge } = require('../src/mcp-bridge');
+
+async function main() {
+  console.log('Connecting to barebrowse...');
+  const bridge = await createMCPBridge({ servers: ['barebrowse'], timeout: 15000 });
+
+  if (bridge.servers.length === 0) {
+    console.error('No servers connected');
+    process.exit(1);
+  }
+
+  const browse = bridge.tools.find(t => t.name === 'barebrowse_browse');
+
+  const tasks = [
+    {
+      label: 'Amazon NL — 2.5 inch HDD SATA case',
+      args: { url: 'https://www.amazon.nl/s?k=2.5+inch+hdd+sata+case', maxChars: 3000 },
+      verify: (r) => /amazon/i.test(r) || /hdd|sata|case|behuizing/i.test(r),
+      shouldFail: false,
+    },
+    {
+      label: 'Wikipedia — Phoenician language',
+      args: { url: 'https://en.wikipedia.org/wiki/Phoenician_language', maxChars: 3000 },
+      verify: (r) => /phoenician/i.test(r) || /semitic|canaanite/i.test(r),
+      shouldFail: false,
+    },
+    {
+      label: 'Dead domain — should fail or timeout',
+      args: { url: 'https://this-domain-does-not-exist-xyz-999.com/page', maxChars: 1000 },
+      verify: () => true, // any response is fine, we just want to see it doesn't hang or crash others
+      shouldFail: true,
+    },
+    {
+      label: 'GitHub — bare-agent repo',
+      args: { url: 'https://github.com/nicobailon/bareagent', maxChars: 2000 },
+      verify: (r) => /bare.?agent|orchestration|lightweight/i.test(r),
+      shouldFail: false,
+    },
+    {
+      label: 'Slow static page — archive.org',
+      args: { url: 'https://web.archive.org/web/2024/https://example.com/', maxChars: 2000 },
+      verify: (r) => /example|wayback|archive/i.test(r),
+      shouldFail: false,
+    },
+  ];
+
+  console.log(`\nFiring ${tasks.length} concurrent browse calls...\n`);
+
+  const t0 = Date.now();
+  const results = await Promise.allSettled(
+    tasks.map(t => browse.execute(t.args))
+  );
+  const elapsed = Date.now() - t0;
+
+  let passed = 0;
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i];
+    const r = results[i];
+    const status = r.status === 'fulfilled' ? 'OK' : 'FAIL';
+    const value = r.status === 'fulfilled' ? r.value : r.reason.message;
+    let text = typeof value === 'string' ? value : JSON.stringify(value);
+    // If barebrowse saved to disk, read the file to verify actual content
+    const fileMatch = text.match(/saved to (.+\.yml)/);
+    if (fileMatch) {
+      try { text += '\n' + readFileSync(fileMatch[1], 'utf8'); } catch {}
+    }
+    const correct = r.status === 'fulfilled' && task.verify(text);
+
+    console.log(`[${i + 1}] ${task.label}`);
+    if (task.shouldFail) {
+      const handled = r.status === 'rejected' || (r.status === 'fulfilled' && /error|fail|not|ERR_/i.test(text.slice(0, 500)));
+      console.log(`    Status: ${status} | Error handled gracefully: ${handled ? 'YES' : 'NO'}`);
+      console.log(`    Preview: ${(r.status === 'rejected' ? r.reason.message : text).slice(0, 120)}...`);
+      console.log();
+      if (handled) passed++;
+    } else {
+      console.log(`    Status: ${status} | Routed correctly: ${correct ? 'YES' : 'NO'}`);
+      console.log(`    Size: ${text.length} chars`);
+      console.log(`    Preview: ${text.slice(0, 120)}...`);
+      console.log();
+      if (correct) passed++;
+    }
+  }
+
+  console.log(`--- Result: ${passed}/${tasks.length} routed correctly in ${elapsed}ms ---`);
+  console.log(passed === tasks.length ? 'PASS' : 'FAIL');
+
+  await bridge.close();
+  console.log('Closed.');
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/mcp-bridge-poc.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * MCP Bridge POC — auto-discover MCP servers, expose as bareagent tools, run Loop.
+ *
+ * First run: discovers servers from IDE configs, writes .mcp-bridge.json (all tools allowed).
+ * Edit .mcp-bridge.json to deny tools. Changes survive refresh.
+ *
+ * Usage:
+ *   OPENAI_API_KEY=sk-... node examples/mcp-bridge-poc.js Go to example.com and describe it
+ *   ANTHROPIC_API_KEY=sk-... node examples/mcp-bridge-poc.js --provider anthropic What tools do you have?
+ *   node examples/mcp-bridge-poc.js --refresh                     # force re-discovery
+ */
+
+const { Loop } = require('../src/loop');
+const { createMCPBridge } = require('../src/mcp-bridge');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse flags
+  const providerFlag = args.includes('--provider') ? args.splice(args.indexOf('--provider'), 2)[1] : 'openai';
+  const refresh = args.includes('--refresh') ? (args.splice(args.indexOf('--refresh'), 1), true) : false;
+
+  // Everything left is the prompt
+  const prompt = args.join(' ') || 'List all your available tools and describe what each one does.';
+
+  // Provider
+  let provider;
+  if (providerFlag === 'anthropic') {
+    const { AnthropicProvider } = require('../src/provider-anthropic');
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) { console.error('Set ANTHROPIC_API_KEY'); process.exit(1); }
+    provider = new AnthropicProvider({ apiKey, model: 'claude-sonnet-4-20250514' });
+  } else {
+    const { OpenAIProvider } = require('../src/provider-openai');
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) { console.error('Set OPENAI_API_KEY'); process.exit(1); }
+    provider = new OpenAIProvider({ apiKey, model: 'gpt-4.1-mini' });
+  }
+
+  // Bridge — reads .mcp-bridge.json if it exists, discovers on first run or TTL expiry
+  const bridge = await createMCPBridge({ refresh, timeout: 20000 });
+
+  if (bridge.servers.length === 0) {
+    console.error('No MCP servers found. Check your .mcp.json or ~/.claude/mcp_servers.json');
+    process.exit(1);
+  }
+
+  console.log();
+  console.log(`Prompt: ${prompt}`);
+  console.log('---');
+
+  const loop = new Loop({
+    provider,
+    maxRounds: 5,
+    system: `You are a helpful assistant with access to MCP tools. Use them to accomplish the user\'s request. Be concise.\n\n${bridge.systemContext}`,
+    onToolCall: (name, args) => console.log(`[tool] ${name}(${JSON.stringify(args)})`),
+    onText: (text) => console.log(`[response] ${text}`),
+  });
+
+  try {
+    const result = await loop.run(
+      [{ role: 'user', content: prompt }],
+      bridge.tools,
+    );
+    console.log('---');
+    console.log('Done.', { usage: result.usage, cost: result.cost ? `$${result.cost.toFixed(4)}` : 'n/a' });
+  } catch (err) {
+    console.error('Loop error:', err.message);
+  } finally {
+    await bridge.close();
+  }
+}
+
+main();

package/examples/orchestrator/README.md

@@ -0,0 +1,53 @@
+# orchestrator/
+
+Reference pattern for multi-agent dispatch. **Three configs and a system
+prompt — no orchestrator class, no role types, no DAG runner.** The LLM
+itself is the dispatcher; the only primitive is `spawn(config, input)`.
+
+```
+orchestrator/
+├── orchestrator.json     # the parent agent — picks a specialist per job
+└── specialists/
+    ├── summarizer.json   # specialist: summarise text given as input
+    └── researcher.json   # specialist: shell_grep + shell_read across cwd
+```
+
+## Run it
+
+```bash
+cd examples/orchestrator
+OPENAI_API_KEY=... echo '{"content":"Summarise the README in this repo."}' \
+  | bare-agent --config orchestrator.json
+```
+
+The orchestrator's system prompt tells the model:
+
+> You receive a job. Decide which specialist handles it (summarizer or
+> researcher), `spawn` that specialist with the relevant input, and return
+> the specialist's result.
+
+The model picks `spawn(config: 'specialists/researcher.json', input: ...)`,
+the researcher reads the README via `shell_read`, returns its summary, the
+orchestrator returns that to stdout.
+
+## What's gated
+
+Both `orchestrator.json` and `specialists/*.json` declare a `gate` block
+that wires bareguard. Defaults:
+
+- `budget.maxCostUsd: 0.50` — hard cap on the *family* (parent + children
+  share via `BAREGUARD_BUDGET_FILE`).
+- `limits.maxTurns: 20`, `limits.maxChildren: 3`, `limits.maxDepth: 2` —
+  spawn-tree shape bounds.
+- `spawn.ratePerMinute: 5`, `defer.ratePerMinute: 10` — bareguard 0.2 rate
+  caps.
+- `bash.allow` and `fs.readScope` scoped per specialist.
+
+## Why this isn't a framework
+
+There's no `class Orchestrator`, no `dispatch_to_specialist()`, no shared
+state object. Roles are *configs*, not types. Adding a new specialist is
+adding one JSON file — no code change to bareagent or the orchestrator.
+
+The "intelligence" is the orchestrator's system prompt. Substitute a
+better-written prompt and the same primitives handle a 5-specialist team.

package/examples/orchestrator/orchestrator.json

@@ -0,0 +1,14 @@
+{
+  "systemPrompt": "You are an orchestrator. You receive a job (the user's first message), decide which specialist handles it, then spawn that specialist with the relevant input and return its result.\n\nAvailable specialists (config paths relative to cwd):\n  - specialists/summarizer.json — summarises text content given via input.content\n  - specialists/researcher.json — searches and reads files in the project\n\nUse the spawn tool: spawn({ config: '<path>', input: { ...whatever the specialist expects... } }). The result.text from spawn is the specialist's final answer — return it verbatim or with a one-line preface.\n\nDo not attempt the work yourself; you are a router. If no specialist fits, say so plainly.",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "tools": ["spawn"],
+  "gate": {
+    "budget": { "maxCostUsd": 0.50 },
+    "limits": { "maxTurns": 20, "maxChildren": 3, "maxDepth": 2 },
+    "spawn":  { "ratePerMinute": 5 },
+    "defer":  { "ratePerMinute": 10 },
+    "tools":  { "allowlist": ["spawn"] },
+    "audit":  { "path": "./bareagent-audit.jsonl" }
+  }
+}

package/examples/orchestrator/specialists/researcher.json

@@ -0,0 +1,12 @@
+{
+  "systemPrompt": "You are a researcher. You have shell_read and shell_grep tools scoped to the current working directory. The user's message describes what to find or read. Use shell_grep to locate matches and shell_read to read whole files. Return a concise summary of what you found (3-8 sentences). Do not invent file contents; if you can't find something, say so.",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "tools": ["shell_read", "shell_grep"],
+  "gate": {
+    "limits": { "maxTurns": 10 },
+    "fs":     { "readScope": ["."] },
+    "tools":  { "allowlist": ["shell_read", "shell_grep"] },
+    "audit":  { "path": "./bareagent-audit.jsonl" }
+  }
+}

package/examples/orchestrator/specialists/summarizer.json

@@ -0,0 +1,11 @@
+{
+  "systemPrompt": "You are a summarizer. The user's message contains text to summarise. Produce a concise (3-5 sentence) summary capturing the main points. Return the summary as your final response — no tool calls needed unless the input is malformed.",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "tools": [],
+  "gate": {
+    "limits": { "maxTurns": 5 },
+    "tools":  { "allowlist": [] },
+    "audit":  { "path": "./bareagent-audit.jsonl" }
+  }
+}

package/examples/replay-job.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Replay-job POC — supervised replay of a recorded browser task.
+ *
+ * The idea: record once with the LLM driving (full reasoning), then on every
+ * subsequent run replay the recorded *intents* against a fresh snapshot, with
+ * the LLM acting as a locator/supervisor — not a planner. If the locator
+ * can't find a match for a step, fall back to full Loop reasoning from that
+ * point and overwrite the trace. That's the self-healing path.
+ *
+ * Why this isn't a barebrowse feature: barebrowse stays dumb (URL → snapshot,
+ * ref → action). The "job" concept (trace storage, replay supervisor, scheduler
+ * hookup) is composed from bareagent primitives.
+ *
+ * Usage:
+ *   # First run — record:
+ *   OPENAI_API_KEY=sk-... node examples/replay-job.js --record demo-job \
+ *     "Go to example.com and click the 'More information' link"
+ *
+ *   # Subsequent runs — replay:
+ *   OPENAI_API_KEY=sk-... node examples/replay-job.js --replay demo-job
+ *
+ *   # Cron'd:
+ *   *\/15 * * * * node /path/to/replay-job.js --replay demo-job
+ *
+ * What's deliberately NOT in this POC (next steps, in order):
+ *   1. Fingerprint fast-path: hash selector+role+text per step, try direct
+ *      match before calling the locator LLM. Brings per-step cost to ~0 on
+ *      stable UIs (Gmail, IG).
+ *   2. PostState assertion: after each step, ask the LLM "does this snapshot
+ *      reflect the expected outcome?" Without this, replay can silently drift
+ *      on subtly-changed UIs.
+ *   3. Trace confidence: rolling success rate per step; below a threshold,
+ *      re-derive the whole trace instead of patching one entry.
+ *   4. Scheduler integration: wrap as a Scheduler trigger so cron is a config
+ *      line instead of an OS cron entry.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Loop } = require('../src/loop');
+
+const JOBS_DIR = path.join(__dirname, '..', '.jobs');
+
+function parseArgs(argv) {
+  const mode = argv.includes('--record') ? 'record'
+             : argv.includes('--replay') ? 'replay'
+             : null;
+  const flagIdx = argv.indexOf(`--${mode}`);
+  const name = mode ? argv[flagIdx + 1] : null;
+  const goal = argv.slice(flagIdx + 2).join(' ');
+  return { mode, name, goal };
+}
+
+function jobPath(name) { return path.join(JOBS_DIR, `${name}.json`); }
+
+function loadProvider() {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) { console.error('Set OPENAI_API_KEY'); process.exit(1); }
+  const { OpenAIProvider } = require('../src/provider-openai');
+  return new OpenAIProvider({ apiKey, model: 'gpt-4.1-mini' });
+}
+
+async function loadBrowseTools() {
+  const mod = await import('barebrowse/bareagent');
+  return mod.createBrowseTools({});
+}
+
+// --- RECORD ----------------------------------------------------------------
+// Run Loop normally. The onToolCall hook captures each step as it happens.
+// The trace stores the LLM's free-text "intent" (the assistant message
+// immediately preceding the tool call) alongside the tool name and args.
+// On replay, intent is what the locator LLM matches against — not args.
+async function record({ name, goal }) {
+  const provider = loadProvider();
+  const { tools, close } = await loadBrowseTools();
+
+  const trace = [];
+  let pendingIntent = '';
+
+  const loop = new Loop({
+    provider,
+    maxRounds: 15,
+    onText: (text) => { pendingIntent = text; },
+    onToolCall: (toolName, args) => {
+      trace.push({ intent: pendingIntent.trim().slice(0, 500), tool: toolName, args });
+      pendingIntent = '';
+    },
+  });
+
+  try {
+    const result = await loop.run([{ role: 'user', content: goal }], tools);
+    fs.mkdirSync(JOBS_DIR, { recursive: true });
+    fs.writeFileSync(jobPath(name), JSON.stringify({ goal, recordedAt: new Date().toISOString(), trace }, null, 2));
+    console.log(`[record] saved ${trace.length} steps to ${jobPath(name)}`);
+    console.log(`[record] cost: $${(result.cost ?? 0).toFixed(4)}`);
+  } finally {
+    await close();
+  }
+}
+
+// --- REPLAY ----------------------------------------------------------------
+// For each recorded step:
+//   1. Take a fresh snapshot.
+//   2. Ask the LLM (no tools, JSON-mode) to map the recorded intent to a ref
+//      in the current snapshot — OR return null if no match.
+//   3. On match: execute the tool with the resolved ref. The recorded args
+//      that aren't refs (e.g. type's `text`, goto's `url`) carry over verbatim.
+//   4. On miss: fall back to driving Loop from the remaining goal, capture
+//      the new sub-trace, and splice it into the saved trace.
+async function replay({ name }) {
+  const job = JSON.parse(fs.readFileSync(jobPath(name), 'utf8'));
+  const provider = loadProvider();
+  const { tools, close } = await loadBrowseTools();
+  const toolByName = Object.fromEntries(tools.map((t) => [t.name, t]));
+
+  let mutated = false;
+
+  try {
+    for (let i = 0; i < job.trace.length; i++) {
+      const step = job.trace[i];
+      const tool = toolByName[step.tool];
+      if (!tool) throw new Error(`unknown tool in trace: ${step.tool}`);
+
+      // Steps whose args have no ref (goto, browse, back, scroll) replay verbatim.
+      if (!('ref' in (step.args || {}))) {
+        console.log(`[replay ${i + 1}/${job.trace.length}] ${step.tool}(${JSON.stringify(step.args)})`);
+        await tool.execute(step.args);
+        continue;
+      }
+
+      // Ref-bearing steps: snapshot, then ask the LLM to locate.
+      const snapshot = await toolByName.snapshot.execute({});
+      const snapshotText = typeof snapshot === 'string' ? snapshot : (snapshot?.snapshot ?? JSON.stringify(snapshot));
+      const located = await locate({ provider, intent: step.intent, tool: step.tool, snapshotText });
+
+      if (located.ref) {
+        const args = { ...step.args, ref: located.ref };
+        console.log(`[replay ${i + 1}/${job.trace.length}] ${step.tool}(ref=${located.ref}) — intent="${step.intent.slice(0, 60)}"`);
+        await tool.execute(args);
+      } else {
+        console.warn(`[replay ${i + 1}/${job.trace.length}] locator miss — falling back to full Loop`);
+        const remaining = `Continue this task from the current page. Original goal: ${job.goal}. We have completed ${i} of ${job.trace.length} recorded steps; the next intended step was: "${step.intent}".`;
+        const subTrace = await driveFallback({ provider, tools, goal: remaining });
+        job.trace.splice(i, job.trace.length - i, ...subTrace);
+        mutated = true;
+        break;
+      }
+    }
+
+    if (mutated) {
+      job.recordedAt = new Date().toISOString();
+      fs.writeFileSync(jobPath(name), JSON.stringify(job, null, 2));
+      console.log(`[replay] trace patched after locator miss; saved ${job.trace.length} steps`);
+    } else {
+      console.log(`[replay] completed ${job.trace.length} steps without falling back`);
+    }
+  } finally {
+    await close();
+  }
+}
+
+// Locator: structured-output call, no tools, no loop. One LLM call per ref-bearing step.
+async function locate({ provider, intent, tool, snapshotText }) {
+  const system = 'You map a recorded intent to a ref in a current ARIA snapshot. Reply with strict JSON: {"ref": "<ref>"} if confident, or {"ref": null, "reason": "<why>"} if no element matches. Never invent refs not present in the snapshot.';
+  const user = `Recorded intent: ${intent}\nTool: ${tool}\n\nCurrent snapshot:\n${snapshotText}\n\nReturn JSON only.`;
+  const { text } = await provider.generate({
+    messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+  });
+  try {
+    const match = text.match(/\{[\s\S]*\}/);
+    return JSON.parse(match ? match[0] : text);
+  } catch {
+    return { ref: null, reason: 'unparseable locator response' };
+  }
+}
+
+// Fallback driver: same shape as record(), just used mid-replay when the
+// locator can't resolve a step. Returns the new sub-trace to splice in.
+async function driveFallback({ provider, tools, goal }) {
+  const sub = [];
+  let pendingIntent = '';
+  const loop = new Loop({
+    provider,
+    maxRounds: 10,
+    onText: (text) => { pendingIntent = text; },
+    onToolCall: (toolName, args) => {
+      sub.push({ intent: pendingIntent.trim().slice(0, 500), tool: toolName, args });
+      pendingIntent = '';
+    },
+  });
+  await loop.run([{ role: 'user', content: goal }], tools);
+  return sub;
+}
+
+async function main() {
+  const { mode, name, goal } = parseArgs(process.argv.slice(2));
+  if (!mode || !name) {
+    console.error('Usage:\n  --record <name> "<goal>"\n  --replay <name>');
+    process.exit(1);
+  }
+  if (mode === 'record') {
+    if (!goal) { console.error('record mode requires a goal string'); process.exit(1); }
+    await record({ name, goal });
+  } else {
+    if (!fs.existsSync(jobPath(name))) { console.error(`no job at ${jobPath(name)}`); process.exit(1); }
+    await replay({ name });
+  }
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/examples/wake.md

@@ -0,0 +1,99 @@
+# wake.sh — defer queue runner
+
+`examples/wake.sh` is the reference scheduler that fires bareagent's
+deferred actions. It's not a library primitive — it's a small bash script
+you copy into your project and adapt. Bareagent emits JSONL records via
+the `defer` tool; wake.sh reads the queue and re-invokes bareagent with
+the fired action.
+
+## Installation
+
+```bash
+cp examples/wake.sh /usr/local/bin/bareagent-wake
+chmod +x /usr/local/bin/bareagent-wake
+```
+
+## Cron entry (every minute)
+
+```cron
+* * * * *  /usr/local/bin/bareagent-wake
+```
+
+For project-scoped use, run from the project directory:
+
+```cron
+* * * * *  cd /path/to/your/project && /usr/local/bin/bareagent-wake
+```
+
+## Environment overrides
+
+| Variable | Default | What it does |
+|---|---|---|
+| `BAREAGENT_DEFER_QUEUE` | `./bareagent-defers.jsonl` | Path to the JSONL defer queue (must match what the `defer` tool writes). |
+| `ORCHESTRATOR_CONFIG` | `./orchestrator.json` | Bareagent config file the wake script invokes for fired actions. |
+| `LOCKFILE` | `/tmp/bareagent-wake.lock` | Single-instance lock via `flock`. |
+| `BAREAGENT_WAKE_LOG_DIR` | `/tmp/bareagent-wake` | Per-fired-action log directory. |
+
+## Dependencies
+
+- `jq` — JSONL fold + filter
+- `flock` (Linux util-linux) — single-instance lock
+- `bare-agent` on `$PATH` — `npm install -g bare-agent` or use the full path
+
+## Behaviour
+
+1. **Folds** the queue: `{id, status, ...}` records are append-only; the
+   live status of each id is the *latest* line. jq does the fold.
+2. **Filters** to `status === 'pending' AND when <= now()`.
+3. For each due record: appends `{id, status: 'fired', ts}` (atomic JSONL
+   append on POSIX), then invokes
+   `bare-agent --config $ORCHESTRATOR_CONFIG` with the inner action as
+   stdin input. Bareagent runs the action through bareguard's gate as a
+   fresh action — full pipeline against the inner action, separate audit
+   line.
+4. After the fired invocation completes: appends `{id, status: 'done|failed', ts, exit_code?}`.
+
+## Why bash and not Node
+
+The wake script is OS-level glue — cron + filesystem + subprocess. Keeping
+it as a shell script makes the dependency on bareagent (and only bareagent)
+obvious, and avoids users thinking the script is a library to import.
+
+## Customisation points
+
+- **Different queue path:** set `BAREAGENT_DEFER_QUEUE` and pass the same
+  to your `defer` tool config (or `BAREAGENT_DEFER_QUEUE` env on the
+  bareagent process that emits).
+- **Different orchestrator per action type:** parse `record.action.type`
+  and pick a config file accordingly. ~5 lines added inside the per-record
+  loop.
+- **Different fire-time semantics:** instead of invoking bareagent CLI,
+  shell out to a Node script that wires Loop differently. The defer queue
+  schema doesn't constrain you.
+
+## Log rotation
+
+`logrotate(8)` is the standard answer. Example
+`/etc/logrotate.d/bareagent-wake`:
+
+```
+/tmp/bareagent-wake/*.log {
+    daily
+    rotate 7
+    compress
+    missingok
+    notifempty
+}
+
+/path/to/your/project/bareagent-defers.jsonl {
+    weekly
+    rotate 4
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+`copytruncate` matters for the queue: it preserves the file inode (which
+the defer tool's `appendFile` depends on for atomic POSIX appends).

package/examples/wake.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# examples/wake.sh — reference scheduler for bareagent's defer queue.
+#
+# This is a *reference*, not a primitive. Copy into your project and modify.
+# See examples/wake.md for the cron entry and customization points.
+#
+# What this script does:
+#   1. Reads the JSONL defer queue file.
+#   2. Folds status-update lines per id (latest wins) using jq.
+#   3. For each pending record whose `when` <= now: appends a "fired" status
+#      line to the queue (atomic JSONL append), then invokes
+#      `bareagent --config <orchestrator>` with the inner action as stdin.
+#   4. Uses flock(1) to prevent overlapping wake invocations.
+#
+# The fired action goes through bareguard's gate AGAIN at fire time — full
+# pipeline against the inner action, separate from the emit-time check.
+# (Two gate.check calls, two distinct audit lines, reconstructable via
+# parent_run_id.)
+
+set -euo pipefail
+
+QUEUE="${BAREAGENT_DEFER_QUEUE:-./bareagent-defers.jsonl}"
+ORCHESTRATOR_CONFIG="${ORCHESTRATOR_CONFIG:-./orchestrator.json}"
+LOCKFILE="${LOCKFILE:-/tmp/bareagent-wake.lock}"
+LOG_DIR="${BAREAGENT_WAKE_LOG_DIR:-/tmp/bareagent-wake}"
+
+mkdir -p "$LOG_DIR"
+
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Single-instance: bail if another wake is running.
+exec 9>"$LOCKFILE"
+if ! flock -n 9; then
+  echo "[wake $NOW] another instance running, exiting" >&2
+  exit 0
+fi
+
+# No queue file = nothing to do.
+if [ ! -f "$QUEUE" ]; then
+  exit 0
+fi
+
+# Reconstruct status by folding all lines per id (latest wins) and filter
+# to records whose `when` <= now AND status == "pending". One JSON object
+# per output line.
+PENDING=$(jq -n -c '
+  reduce inputs as $r ({};
+    .[$r.id] |= (. // {}) + $r
+  )
+  | to_entries
+  | map(.value)
+  | map(select(.status == "pending" and .when <= "'"$NOW"'"))
+  | .[]
+' < "$QUEUE")
+
+if [ -z "$PENDING" ]; then
+  exit 0
+fi
+
+echo "$PENDING" | while IFS= read -r record; do
+  [ -z "$record" ] && continue
+
+  ID=$(echo "$record" | jq -r '.id')
+  ACTION=$(echo "$record" | jq -c '.action')
+
+  # Append "fired" status line first (defer queue is append-only).
+  printf '{"id":"%s","status":"fired","ts":"%s"}\n' "$ID" "$NOW" >> "$QUEUE"
+
+  # Invoke bareagent with the deferred action as stdin input.
+  # Run in background — wake script doesn't wait for completion.
+  ( echo "$ACTION" | bare-agent --config "$ORCHESTRATOR_CONFIG" \
+      >> "$LOG_DIR/fired-$ID.log" 2>&1
+    rc=$?
+    if [ $rc -ne 0 ]; then
+      printf '{"id":"%s","status":"failed","ts":"%s","exit_code":%d}\n' \
+        "$ID" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$rc" >> "$QUEUE"
+    else
+      printf '{"id":"%s","status":"done","ts":"%s"}\n' \
+        "$ID" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> "$QUEUE"
+    fi
+  ) &
+done
+
+wait

package/examples/with-bareguard.mjs

@@ -0,0 +1,65 @@
+// examples/with-bareguard.mjs
+//
+// End-to-end: bareagent Loop + bareguard Gate.
+// Runs a small LLM loop with budget cap, fs scope, audit log, and humanChannel.
+//
+// Run:  OPENAI_API_KEY=... node examples/with-bareguard.mjs
+//
+// What this demonstrates:
+//   - Single-gate governance: every tool call traverses gate.check; every
+//     result reaches gate.record (via wrapTools).
+//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop.
+//   - Audit log: one JSONL line per gated event at ./bareagent-audit.jsonl.
+//   - humanChannel: required by bareguard. Here we auto-deny asks; in real use
+//     wire it to a chat platform, terminal prompt, etc.
+
+import { Gate } from 'bareguard';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { Loop, wireGate } = require('bare-agent');
+const { OpenAI } = require('bare-agent/providers');
+const { createShellTools } = require('bare-agent/tools');
+
+// 1. Build the gate. Every primitive is optional with sensible defaults.
+const gate = new Gate({
+  budget: { maxCostUsd: 0.10 },           // hard USD cap
+  limits: { maxTurns: 20 },                // safety net on think/act cycles
+  fs:     { readScope: ['/tmp', '~/'] },   // shell_read / shell_grep allowed roots
+  bash:   { allow: ['ls', 'cat', 'echo', 'pwd'] },  // argv[0] allowlist for shell_run
+  audit:  { path: './bareagent-audit.jsonl' },
+  // Required by bareguard: any ask/halt event flows through here.
+  // Auto-deny is the safest default for headless use; in real apps, wire to
+  // a Telegram/Slack/terminal prompt and return { decision: 'allow' | 'deny' }.
+  humanChannel: async (event) => {
+    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying`);
+    return { decision: 'deny' };
+  },
+});
+await gate.init();
+
+// 2. Wire the gate into Loop's policy slot and wrap tools so gate.record fires.
+const { policy, wrapTools } = wireGate(gate);
+
+// 3. Standard bareagent setup.
+const provider = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o-mini',
+});
+const { tools } = createShellTools();
+
+const loop = new Loop({
+  provider,
+  policy,
+  onError: (err, meta) => console.error(`[onError ${meta.source}]`, err.message),
+});
+
+// 4. Run.
+const result = await loop.run(
+  [{ role: 'user', content: 'List the contents of /tmp using shell_run with argv ["ls", "/tmp"].' }],
+  wrapTools(tools),
+);
+
+console.log('---');
+console.log('text:', result.text);
+console.log('cost:', result.cost?.toFixed(6) ?? 'n/a');
+console.log('audit log → ./bareagent-audit.jsonl');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "files": [
     "index.js",
     "index.d.ts",
@@ -9,6 +9,7 @@
     "bin/",
     "tools/",
     "types/",
+    "examples/",
     "LICENSE",
     "NOTICE"
   ],