bare-agent 0.12.1 → 0.13.0

package/README.md

@@ -66,13 +66,13 @@ 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. Returns estimated USD cost per run. Governance via `Loop({ policy })` — wire bareguard's `Gate` through `wireGate(gate)` and every tool call (native, MCP, browsing, mobile) traverses one chokepoint with per-caller `ctx` routing. Bareguard owns the audit log, budget caps, and halt decisions; Loop respects the verdict. `onError` + `loop:error` surface every silent-ish failure (callback throw, Checkpoint timeout) |
+| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Returns estimated USD cost per run. Governance via `Loop({ policy })` — wire bareguard's `Gate` through `wireGate(gate)` and every tool call (native, MCP, browsing, mobile) traverses one chokepoint with per-caller `ctx` routing. Bareguard owns the audit log, budget caps, and halt decisions; Loop respects the verdict. Context engineering via `Loop({ assemble })` — a per-round `assemble(msgs, ctx)` chokepoint to recall/compress/trim the window sent to the model (the seam litectx plugs into); returns a view, the canonical transcript stays intact, fail-open. The exported `unitAssembler`/`toUnits`/`fromUnits` adapter lets a consumer work over a neutral unit `{id, role, content, kind, pinned, atomic, tokensApprox}` — bareagent owns the grammar (atomic tool-pair bundling, pinned system/task, a pairing seatbelt), the consumer owns content + relevance. `onError` + `loop:error` surface every silent-ish failure (callback throw, Checkpoint timeout) |
 | **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` |
 | **CircuitBreaker** | Fail fast after N errors. Auto-recovers after cooldown. Per-key isolation |
 | **Fallback** | Try providers in order — if one is down, next one picks up. Transparent to Loop |
-| **Memory** | Persist and search context. SQLite with FTS (default) or zero-dep JSON file |
+| **Memory** | Persist and search context across turns/sessions through a swappable `Store`. Zero-dep JSON file by default, or mount [litectx](https://npmjs.com/package/litectx) for ranked, graph-aware recall in one line — the host code never changes ([example](examples/litectx-as-store.mjs)). A minimal `SQLite` FTS5 store also ships, though litectx supersedes it for SQLite-backed memory |
 | **StateMachine** | Task lifecycle tracking with event hooks. `pending → running → done / failed / waiting / cancelled` |
 | **Checkpoint** | Human approval gate. You provide the transport — terminal, Telegram, Slack, whatever |
 | **Scheduler** | Cron (`0 9 * * 1-5`) or relative (`2h`, `30m`). Persisted jobs survive restarts |
@@ -182,6 +182,8 @@ Runnable scripts in [`examples/`](examples/) — each is self-contained and the
 | [`orchestrator/`](examples/orchestrator/) | Multi-agent dispatch via `spawn`. Three configs, one system prompt — no orchestrator class, no role types. Roles are JSON files. |
 | [`wake.sh`](examples/wake.sh) + [`wake.md`](examples/wake.md) | Reference cron + jq script for firing deferred actions. The runtime half of `createDeferTool` — bareagent emits, `wake.sh` fires. |
 | [`replay-job.js`](examples/replay-job.js) | Supervised replay POC: record a browser task once with the LLM driving, then replay against fresh snapshots with the LLM as locator-only. Falls back to full reasoning when the locator misses, and patches the trace. |
+| [`litectx-as-store.mjs`](examples/litectx-as-store.mjs) | Mount [litectx](https://npmjs.com/package/litectx) as the `Memory` `Store` — one-line swap from `JsonFileStore` to ranked, graph-aware recall; the host code never changes (RT-3). |
+| [`litectx-mcp-child.mjs`](examples/litectx-mcp-child.mjs) | Give a spawned child agent litectx's reasoning verbs as MCP tools, read-only on its own db, via `liteCtxMcpBridgeConfig` + `cfg.mcp` (RT-4). |
 
 ---
 

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.13.0 | 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)
 
@@ -14,12 +14,12 @@ npm install bare-agent
 ```
 
 Eight entry points:
-- `require('bare-agent')` — Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, **HaltError**
+- `require('bare-agent')` — Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, **toUnits, fromUnits, unitAssembler** (the `assemble` context-units adapter, v0.13+), BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, **HaltError**
 - `require('bare-agent/errors')` — same error classes via a stable subpath (v0.10.1+) for adopters who want to import only the error surface
 - `require('bare-agent/providers')` — OpenAI, Anthropic, Ollama, CLIPipe, Fallback (the canonical short names; `*Provider` aliases — `OpenAIProvider`, `AnthropicProvider`, etc. — are also exported and match the class names, so either destructure works, v0.12.1+)
 - `require('bare-agent/stores')` — SQLite (FTS5), JsonFile
 - `require('bare-agent/transports')` — JsonlTransport
-- `require('bare-agent/tools')` — createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, createDeferTool, spawnChild, readDeferQueue
+- `require('bare-agent/tools')` — createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, createDeferTool, spawnChild, readDeferQueue, liteCtxMcpBridgeConfig
 - `require('bare-agent/mcp')` — createMCPBridge (returns `tools` + `metaTools`), discoverServers, buildMetaTools
 - `require('bare-agent/bareguard')` — wireGate (one-line bareguard Gate integration), defaultActionTranslator
 
@@ -69,6 +69,7 @@ Eight entry points:
 | **Spawn a child specialist agent** | createSpawnTool + bin/cli.js --config (v0.9+) |
 | **Defer an action for later (cron-fired)** | createDeferTool + examples/wake.sh (v0.9+) |
 | **Expose a large MCP catalog dynamically** | createMCPBridge → bridge.metaTools (v0.9+) |
+| **Give a child agent litectx memory (read-only, own db)** | liteCtxMcpBridgeConfig → `cfg.mcp` in a spawn child config (RT-4) |
 
 **Most projects start with Loop + Provider.** Add components as needed.
 
@@ -549,15 +550,39 @@ All return `{ text, toolCalls, usage: { inputTokens, outputTokens } }`. CLIPipe
 
 ```javascript
 // SQLite FTS5 — full-text search with BM25 ranking (requires: npm install better-sqlite3)
+// Minimal store, kept for back-compat. litectx strictly dominates it (same better-sqlite3
+// requirement, but adds ranked graph-aware recall) — prefer litectx for SQLite-backed memory.
 new SQLite({ path: './memory.db' })
 
 // JSON file — zero deps, substring search
 new JsonFile({ path: './memory.json' })
 
+// litectx — ranked, graph-aware recall (RT-3 mount; requires: npm install litectx)
+// One-line swap; the host code (memory.store/search/get/delete) never changes.
+//   import { LiteCtx, liteCtxAsStore } from 'litectx';
+//   const memory = new Memory({ store: liteCtxAsStore(new LiteCtx({ dbPath: './agent.db' })) });
+// See examples/litectx-as-store.mjs. litectx ships the adapter; bareagent owns the Store socket.
+
 // Custom — implement { store, search, get, delete }
 ```
 
-**JsonFile scaling:** `search()` is an O(n) substring scan (no index) and every `store()`/`delete()` rewrites the whole file. Fine for hundreds–low-thousands of entries; for larger or write-heavy memory use `SQLite` (FTS5 index, incremental writes). JsonFile warns once past ~10k entries.
+**JsonFile scaling:** `search()` is an O(n) substring scan (no index) and every `store()`/`delete()` rewrites the whole file. Fine for hundreds–low-thousands of entries; for larger or write-heavy memory mount `litectx` for ranked graph-aware recall (the minimal bundled `SQLite` FTS5 store remains for back-compat, but litectx strictly dominates it — same `better-sqlite3` requirement, richer recall). JsonFile warns once past ~10k entries.
+
+**Two ways to use litectx, pick by who consumes it (the two are independent):**
+- **As your `Store`** (RT-3, above) — *your* host code recalls via `memory.search/get`. One-line `liteCtxAsStore` swap.
+- **As a child agent's MCP toolbox** (RT-4) — give a *spawned sub-agent* litectx's own reasoning verbs (`litectx_recall`, `litectx_get`, …) so the model calls them in its loop. Use `liteCtxMcpBridgeConfig` to build the curated mount and hand it to the child via `cfg.mcp`:
+
+```js
+const { liteCtxMcpBridgeConfig } = require('bare-agent/tools');
+// Read-only by default: recall/get/impact/recent allowed; remember/forget denied
+// (writable:true to opt in — writes stay in the child's OWN --root db); index/promotions always denied.
+const mcp = liteCtxMcpBridgeConfig({ root: './child-mem' });   // own-db isolation via --root
+// In the spawn child config (bin/cli.js --config): { provider, model, tools, mcp, gate }
+//   mcp: <the config above>   → child's MCPBridge mounts litectx-mcp; tools join BEFORE gating
+// cfg.mcp also accepts a directory-confined { bridgePath } pointing at a .mcp-bridge.json on disk.
+```
+
+Requires litectx's `litectx-mcp` binary on PATH. Isolation is **physical** (each child a distinct `--root` db) — promotion to the parent is an explicit parent-side `recall`→`remember`, never automatic. See `examples/litectx-mcp-child.mjs`. bareagent imports nothing from litectx; the helper is pure config curation.
 
 ## Tool format
 

package/bin/cli.js

@@ -66,11 +66,54 @@ async function runConfigMode(cfgPath) {
   const stream = new Stream({ transport: new JsonlTransport() });
 
   // Provider
-  const provider = createProvider(cfg.provider || 'openai', cfg.model);
+  const provider = createProvider(cfg.provider || 'openai', cfg.model, { command: cfg.command, args: cfg.args });
 
   // Tools — registry resolved by name from a curated set of built-ins.
   const tools = await resolveTools(cfg.tools || [], { stream });
 
+  // Optional MCP mount (RT-4) — a child config can mount MCP servers (e.g. litectx-mcp, read-only on
+  // its own db) via `cfg.mcp`. Accepts an inline bridge config (`{ servers, ttl }`, as built by
+  // `liteCtxMcpBridgeConfig`) or `{ bridgePath }` pointing at one (confined to the config directory,
+  // same rule as gate.humanChannel). Mounted tools join the set BEFORE gating, so they traverse the
+  // same policy as native tools. The server `command` runs unsandboxed — same trust as `cfg.tools`.
+  /** @type {{ tools: ToolDef[], close: Function } | null} */
+  let mcpBridge = null;
+  if (cfg.mcp) {
+    const { createMCPBridge } = require('../src/mcp-bridge');
+    const os = require('node:os');
+    const cfgDir = path.resolve(path.dirname(cfgPath));
+    let bridgePath;
+    let tmpBridge = null;
+    if (cfg.mcp && typeof cfg.mcp === 'object' && cfg.mcp.servers) {
+      tmpBridge = path.join(os.tmpdir(), `bareagent-mcp-${process.pid}.json`);
+      fs.writeFileSync(tmpBridge, JSON.stringify(cfg.mcp));
+      bridgePath = tmpBridge;
+    } else if (cfg.mcp && typeof cfg.mcp.bridgePath === 'string') {
+      const p = path.resolve(cfgDir, cfg.mcp.bridgePath);
+      if (p !== cfgDir && !p.startsWith(cfgDir + path.sep)) {
+        process.stderr.write(`[cli] cfg.mcp.bridgePath must resolve inside the config directory (${cfgDir}); refusing ${p}\n`);
+        process.exit(1);
+      }
+      bridgePath = p;
+    } else {
+      process.stderr.write('[cli] cfg.mcp must be an inline bridge config ({ servers }) or { bridgePath }\n');
+      process.exit(1);
+    }
+    try {
+      mcpBridge = await createMCPBridge({
+        bridgePath,
+        servers: cfg.mcp.servers ? Object.keys(cfg.mcp.servers) : undefined,
+        timeout: cfg.mcp.timeout || 15000,
+      });
+      tools.push(...mcpBridge.tools);
+    } catch (err) {
+      process.stderr.write(`[cli] failed to mount MCP (cfg.mcp): ${err.message}\n`);
+      process.exit(1);
+    } finally {
+      if (tmpBridge) { try { fs.unlinkSync(tmpBridge); } catch { /* best-effort */ } }
+    }
+  }
+
   // Bareguard Gate (optional but strongly recommended for spawn children).
   // Fail-closed: if the config asks for a gate but wiring fails, exit non-zero
   // rather than run an ungoverned child agent.
@@ -163,6 +206,7 @@ async function runConfigMode(cfgPath) {
   });
 
   await loop.run([initialMessage], gatedTools);
+  if (mcpBridge) await mcpBridge.close();
   // Stream's loop:done event has already been emitted; exit clean.
   process.exit(0);
 }
@@ -299,7 +343,15 @@ function runStdioMode() {
  * @param {string} [model]
  * @returns {Provider}
  */
-function createProvider(name, model) {
+function createProvider(name, model, opts = {}) {
+  if (name === 'clipipe') {
+    const { CLIPipeProvider } = require('../src/provider-clipipe');
+    if (!opts.command) {
+      process.stderr.write('[cli] provider "clipipe" requires a `command` in the config (or --command).\n');
+      process.exit(1);
+    }
+    return new CLIPipeProvider({ command: opts.command, args: opts.args || [], ...(model && { model }) });
+  }
   if (name === 'openai') {
     const { OpenAIProvider } = require('../src/provider-openai');
     return new OpenAIProvider({

package/examples/README.md

@@ -0,0 +1,15 @@
+# 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. |
+| [`litectx-as-store.mjs`](litectx-as-store.mjs) | RT-3 Store mount: swap the zero-dep `JsonFileStore` for litectx's ranked, graph-aware recall in one line — the host code never changes. Runs the JsonFileStore half always; runs the litectx half if `litectx` is installed, else prints the one-line swap. |
+
+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/litectx-as-store.mjs

@@ -0,0 +1,78 @@
+// examples/litectx-as-store.mjs
+//
+// RT-3 — mount litectx as a bareagent `Memory` backend (the rich `Store`).
+//
+// Run:  node examples/litectx-as-store.mjs
+//       (zero-dep: runs the JsonFileStore half always; runs the litectx half only if `litectx`
+//        is installed — `npm install litectx` — otherwise it prints the one-line swap and skips.)
+//
+// What this demonstrates:
+//   - The `Store` socket (`{ store, search, get, delete }`) is litectx's documented mount point.
+//     Swapping the zero-dep JsonFileStore for litectx's ranked, graph-aware recall is a ONE-LINE
+//     change — the host code (everything in `hostWorkflow` below) never changes.
+//   - litectx ships the adapter (`liteCtxAsStore`); bareagent ships the socket. No bareagent import
+//     in litectx, no litectx import in bareagent — the dependency direction stays one-way.
+//
+// The five points where the schemaless socket and litectx's typed model are reconciled (PRD §3.2),
+// all handled INSIDE litectx's adapter — the host never sees them:
+//   #1 the adapter mints the id (`kind:uuid`); the host supplies none.
+//   #2 `search` returns content inline via `recall({ body: true })`.
+//   #3 arbitrary host metadata round-trips through a sealed `meta` passthrough (kind/by are typed).
+//   #4 an un-kinded write defaults to `kind:"fact"` (durable agent memory); `metadata.kind` overrides.
+//   #5 `search` targets one kind so scores stay comparable across hits.
+
+import { createRequire } from 'node:module';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+const require = createRequire(import.meta.url);
+const { Memory } = require('bare-agent');
+const { JsonFile: JsonFileStore } = require('bare-agent/stores');
+
+// --- the HOST workflow: written once, runs against ANY Store. This is the code that does NOT change
+//     when you swap the backend. Note `await` works whether the store is sync (JsonFileStore) or
+//     async (litectx) — Memory delegates the return value without awaiting. ---
+async function hostWorkflow(memory, label) {
+  const id = await memory.store(
+    'the auth service uses a token-bucket rate limiter on /login',
+    { sessionId: 'sess-1', tag: 'architecture' }, // arbitrary metadata — must survive the round-trip
+  );
+  const hits = await memory.search('rate limiter');
+  const fetched = memory.get(id);
+
+  console.log(`\n[${label}]`);
+  console.log(`  store() → id: ${id}`);
+  console.log(`  search('rate limiter') → ${hits.length} hit(s); top score=${hits[0]?.score?.toFixed?.(3) ?? hits[0]?.score}`);
+  console.log(`  get(id).content: ${JSON.stringify(fetched?.content)}`);
+  console.log(`  get(id).metadata: ${JSON.stringify(fetched?.metadata)}  ← host metadata round-tripped`);
+}
+
+async function main() {
+  // 1) Zero-dep baseline: JsonFileStore (always runs).
+  const dir = mkdtempSync(join(tmpdir(), 'litectx-as-store-'));
+  try {
+    await hostWorkflow(new Memory({ store: new JsonFileStore({ path: join(dir, 'mem.json') }) }), 'JsonFileStore (zero-dep)');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  // 2) The ONE-LINE swap to litectx — identical hostWorkflow, ranked graph-aware recall.
+  let liteCtxAsStore, LiteCtx;
+  try {
+    ({ LiteCtx, liteCtxAsStore } = require('litectx')); // both from the main entry (litectx 0.10+)
+  } catch {
+    console.log('\n[litectx] not installed — the swap is one line:');
+    console.log("    import { LiteCtx, liteCtxAsStore } from 'litectx';");
+    console.log('    const lc = new LiteCtx({ dbPath: \'./agent.db\' }); await lc.ready();');
+    console.log('    const memory = new Memory({ store: liteCtxAsStore(lc) });  // ← only this line changes');
+    console.log('\n  Install it (`npm install litectx`) to run the litectx half of this example.');
+    return;
+  }
+
+  const lc = new LiteCtx({ dbPath: join(tmpdir(), `litectx-as-store-${process.pid}.db`) });
+  if (typeof lc.ready === 'function') await lc.ready();
+  await hostWorkflow(new Memory({ store: liteCtxAsStore(lc) }), 'litectx (ranked, graph-aware)');
+  if (typeof lc.close === 'function') lc.close();
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/examples/litectx-mcp-child.mjs

@@ -0,0 +1,57 @@
+// examples/litectx-mcp-child.mjs
+//
+// RT-4 — give a child/sub-agent litectx memory, READ-ONLY, on its own db (own-db isolation).
+//
+// Run:  node examples/litectx-mcp-child.mjs [--root <indexed-litectx-root>]
+//       Prints the curated .mcp-bridge.json always; launches the real mount if `litectx-mcp` is on
+//       PATH (`npm install -g litectx`), otherwise prints the one-line recipe and exits 0.
+//
+// What this demonstrates:
+//   - `liteCtxMcpBridgeConfig({ root })` builds the curated bridge config: the read-only default
+//     (recall/get/impact/recent allow; remember/forget/index/promotions deny) so a child can reason
+//     over memory but can't mutate durable shared state. Flip with `{ writable: true }` to opt a child
+//     into writes — which still land in ITS OWN db, never the parent's.
+//   - `createMCPBridge` launches `litectx-mcp --root <child-db>` over stdio and exposes only the
+//     allowed verbs as bareagent tools. Pass `bridge.tools` to a child Loop.
+//   - Isolation is the child's own `--root`, not a shared store — which is what keeps RT-5's scope
+//     column deferred. Promotion of a child-learned fact to the parent is an explicit, parent-side
+//     `recall`(child db) → `remember`(parent db); never automatic.
+
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { createMCPBridge } = require('../src/mcp-bridge');
+const { liteCtxMcpBridgeConfig } = require('bare-agent/tools');
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const rootFlag = process.argv.indexOf('--root');
+const childRoot = rootFlag !== -1 ? process.argv[rootFlag + 1] : process.cwd();
+
+// 1) Build the curated config — the artifact a parent drops in to compose the child's toolbox.
+const cfg = liteCtxMcpBridgeConfig({ root: childRoot });
+console.log('Curated .mcp-bridge.json (read-only litectx mount):');
+console.log(JSON.stringify(cfg, null, 2));
+console.log('\n  allow: recall, get, impact, recent   deny: remember, forget, index, promotions');
+console.log('  (writable:true opts into remember/forget — still child-db-local)\n');
+
+// 2) Attempt the real mount. Connects iff `litectx-mcp` is on PATH and the root is an indexed litectx db.
+const dir = mkdtempSync(join(tmpdir(), 'litectx-mcp-child-'));
+const bridgePath = join(dir, '.mcp-bridge.json');
+writeFileSync(bridgePath, JSON.stringify(cfg));
+try {
+  const bridge = await createMCPBridge({ bridgePath, servers: ['litectx'], timeout: 8000 });
+  if (bridge.servers.includes('litectx')) {
+    console.log(`[mounted] child tools: ${bridge.tools.map((t) => t.name).join(', ')}`);
+    console.log(`[mounted] withheld:    ${bridge.denied.map((d) => d.tool).join(', ')}`);
+    // hand bridge.tools to a child Loop here: new Loop({ provider, ... }).run(msgs, bridge.tools)
+    await bridge.close();
+  } else {
+    console.log('[litectx-mcp not on PATH] the mount above is the recipe. To run it live:');
+    console.log('    npm install -g litectx           # provides the `litectx-mcp` command');
+    console.log(`    litectx-mcp --root ${childRoot}   # (index the root first; see litectx docs)`);
+    console.log('  then re-run this example. The parent code never changes.');
+  }
+} finally {
+  rmSync(dir, { recursive: true, force: true });
+}

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" }
+  }
+}