bare-agent 0.12.2 → 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.2 | 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

@@ -10,5 +10,6 @@ Runnable reference scripts for bare-agent. Each is self-contained — the top-of
 | [`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/index.d.ts

@@ -10,6 +10,9 @@ import { runPlan } from "./src/run-plan";
 import { CircuitBreaker } from "./src/circuit-breaker";
 import { wireGate } from "./src/bareguard-adapter";
 import { defaultActionTranslator } from "./src/bareguard-adapter";
+import { toUnits } from "./src/context-units";
+import { fromUnits } from "./src/context-units";
+import { unitAssembler } from "./src/context-units";
 import { BareAgentError } from "./src/errors";
 import { ProviderError } from "./src/errors";
 import { ToolError } from "./src/errors";
@@ -17,4 +20,4 @@ import { TimeoutError } from "./src/errors";
 import { ValidationError } from "./src/errors";
 import { CircuitOpenError } from "./src/errors";
 import { HaltError } from "./src/errors";
-export { Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };
+export { Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };

package/index.js

@@ -11,6 +11,7 @@ const { Retry } = require('./src/retry');
 const { runPlan } = require('./src/run-plan');
 const { CircuitBreaker } = require('./src/circuit-breaker');
 const { wireGate, defaultActionTranslator } = require('./src/bareguard-adapter');
+const { toUnits, fromUnits, unitAssembler } = require('./src/context-units');
 const {
   BareAgentError,
   ProviderError,
@@ -34,6 +35,9 @@ module.exports = {
   CircuitBreaker,
   wireGate,
   defaultActionTranslator,
+  toUnits,
+  fromUnits,
+  unitAssembler,
   BareAgentError,
   ProviderError,
   ToolError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -91,7 +91,7 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/**/*.test.js",
+    "test": "node --test test/**/*.test.js",
     "typecheck": "tsc --noEmit",
     "prebuild:types": "node scripts/clean-types.js",
     "build:types": "tsc",
@@ -99,6 +99,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
+    "litectx": "^0.11.0",
     "typescript": "^5.7.0"
   }
 }

package/src/context-units.d.ts

@@ -0,0 +1,44 @@
+/**
+ * msgs → neutral units. Bundles each assistant-tool-call message with the contiguous tool result(s)
+ * that answer its ids into ONE atomic unit (so pairing can never be split). system + first user turn
+ * are pinned.
+ * @param {Array<Record<string, any>>} msgs
+ * @returns {Array<Record<string, any>>}
+ */
+export function toUnits(msgs: Array<Record<string, any>>): Array<Record<string, any>>;
+/**
+ * units → msgs. Honors drop (absent units), reorder (order of the returned array), recall-inject
+ * (units with no backing → one synthesised message), and COMPRESS (a unit whose `content` was rewritten
+ * is reconstructed from the new content). Atomic units keep their assistant tool-call message verbatim
+ * so pairing holds; a content rewrite lands on the tool RESULT. A multi-result atomic bundle whose
+ * content was rewritten is kept VERBATIM — a flat string can't be faithfully split back into N
+ * results, and splitting is grammar (bareagent's), not litectx's to attempt. This isn't a special
+ * case: litectx's compress() is a pure text→text render that returns verbatim when handed no single
+ * parseable format (compress.js — "never returns less than the body losslessly"), so a flattened
+ * multi-result unit round-trips unchanged on both sides. RATIFIED by litectx (2026-06-12). The pairing
+ * seatbelt is the final guard.
+ * @param {Array<Record<string, any>>} units
+ * @returns {Array<Record<string, any>>}
+ */
+export function fromUnits(units: Array<Record<string, any>>): Array<Record<string, any>>;
+/**
+ * Wrap litectx's `assemble(units, ctx)` verb into the Loop's msgs-level `assemble(msgs, ctx)` seam.
+ * litectx ships the **`AssembleResult` envelope** `{ units, dropped, tokens }` (CE-PRD §8.2: `dropped[]`
+ * is load-bearing — it ships in the same slice, never silently truncated). This wrapper accepts that
+ * envelope (uses `.units`) OR a bare `units` array (a simpler consumer). `dropped`/`tokens` are litectx's
+ * accounting; the Loop's seam is msgs-in/msgs-out, so they're not threaded onward here (the canonical
+ * transcript already holds every dropped unit by id — restorable on demand).
+ * Fail-OPEN at this layer too: any other return shape → the original msgs are sent unchanged. A thrown
+ * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
+ * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
+ * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ */
+export function unitAssembler(assembleUnits: (units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)): (msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>;
+/** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */
+export function approxTokens(msgs: any): number;
+/**
+ * Drop any tool-result whose tool_call_id has no open assistant tool-call before it, and any assistant
+ * tool-call message left with zero surviving results. The final grammar guard: even if litectx hands
+ * back something that would orphan a pair, the wire is always valid. Returns a fresh array.
+ */
+export function pairingSeatbelt(msgs: any): any[];

package/src/context-units.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// RT-1 — the msgs⇄units adapter for the `assemble` context-assembly seam (src/loop.js).
+//
+// Division of labour (litectx CE-PRD §8.2, line 321 — the frozen contract):
+//   - bareagent owns GRAMMAR: msgs→units, units→msgs, atomic bundling of a tool-call + its result(s),
+//     `pinned` flags, the pairing seatbelt, and fail-open. Broken tool-pairing and a dropped system
+//     prompt are UNREPRESENTABLE here, by construction — not by trusting the consumer.
+//   - litectx owns CONTENT + RELEVANCE: a single verb `assemble(units, ctx) → { units, dropped, tokens }`
+//     (the AssembleResult envelope — `dropped[]` is load-bearing, ships in the same slice, never silent)
+//     that does SELECT (keep / drop / reorder / recall-inject) + COMPRESS (rewrite a unit's `content`) +
+//     fit-to-`ctx.budget`, best-effort. It never learns the message grammar. `unitAssembler` unwraps `.units`.
+//
+// The neutral unit (the SOCKET litectx codes against — exactly these 7 enumerable fields):
+//   { id, role, content, kind, pinned, atomic, tokensApprox }
+//     id           — stable within one assemble() call; litectx references units by it.
+//     role         — 'system' | 'user' | 'assistant' | 'tool' (the message grammar role).
+//     content      — flat string view litectx reads to score and MAY rewrite to COMPRESS.
+//     kind         — litectx's memory-node kind ('code'|'doc'|'fact'|'episode') on units litectx
+//                    INJECTS from recall. Transcript-derived units carry `null` — and that is the
+//                    CORRECT value, not a placeholder. `role` and `kind` are orthogonal: `role`
+//                    (user/assistant/tool/system) carries conversational position = bareagent's
+//                    grammar, present on every unit; `kind` carries litectx's graph-node type, present
+//                    only on units litectx owns. Typing a live turn would force litectx to learn the
+//                    provider's conversation structure — the exact coupling the keystone boundary
+//                    forbids (PRD §1.2 / litectx CE-PRD §8.2). RATIFIED by litectx (2026-06-12): do
+//                    NOT define transcript-kinds. injected = kinded, transcript = null.
+//     pinned       — true ⇒ bareagent guarantees the unit is never dropped and never reordered
+//                    (system prompt, first user/task turn). litectx still sees its tokensApprox so the
+//                    pin counts against the budget: pin-don't-hide.
+//     atomic       — group-id (string) | null. litectx keeps/drops units sharing one group-id WHOLE,
+//                    never split. bareagent pre-bundles an assistant tool-call + ALL its result(s) into
+//                    one unit, so each bundle is its OWN group (group-id = the unit's id); everything
+//                    else is null. NOTE: string|null, not boolean — a boolean collapses every bundle
+//                    under one key and litectx would fit them all-or-nothing (test/context-units.test.js (real-litectx sweep)).
+//     tokensApprox — chars/4 estimate over the unit's backing messages, for litectx's budget math.
+//
+// `_msgs` (the verbatim backing messages) is attached NON-ENUMERABLE: it does not appear in the 7-field
+// view, JSON, or iteration. It is bareagent's reconstruction backing — litectx must not read it. A unit
+// with no backing (one litectx minted via recall-inject) is synthesised into a single message on the
+// way out.
+
+/** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */
+function approxTokens(msgs) {
+  let c = 0;
+  for (const m of msgs) {
+    if (m.content != null) c += String(m.content).length;
+    if (m.tool_calls) c += JSON.stringify(m.tool_calls).length;
+  }
+  return Math.ceil(c / 4);
+}
+
+/** Flat string view of a unit's backing messages — what litectx scores on and may rewrite. */
+function renderContent(msgs) {
+  const parts = [];
+  for (const m of msgs) {
+    if (m.content != null && String(m.content).length) parts.push(String(m.content));
+  }
+  return parts.join('\n');
+}
+
+let _seq = 0;
+/** Attach the verbatim backing + original-content fingerprint as non-enumerable carry. */
+function withBacking(unit, msgs) {
+  Object.defineProperty(unit, '_msgs', { value: msgs, enumerable: false, writable: true });
+  Object.defineProperty(unit, '_origContent', { value: unit.content, enumerable: false, writable: true });
+  return unit;
+}
+
+/**
+ * msgs → neutral units. Bundles each assistant-tool-call message with the contiguous tool result(s)
+ * that answer its ids into ONE atomic unit (so pairing can never be split). system + first user turn
+ * are pinned.
+ * @param {Array<Record<string, any>>} msgs
+ * @returns {Array<Record<string, any>>}
+ */
+function toUnits(msgs) {
+  const units = [];
+  let seenUser = false;
+  for (let i = 0; i < msgs.length; i++) {
+    const m = msgs[i];
+
+    if (m.role === 'system') {
+      units.push(withBacking({ id: `u${_seq++}`, role: 'system', content: renderContent([m]), kind: null, pinned: true, atomic: null, tokensApprox: approxTokens([m]) }, [m]));
+      continue;
+    }
+    if (m.role === 'user') {
+      const pinned = !seenUser; // first user turn = the task; pin it
+      seenUser = true;
+      units.push(withBacking({ id: `u${_seq++}`, role: 'user', content: renderContent([m]), kind: null, pinned, atomic: null, tokensApprox: approxTokens([m]) }, [m]));
+      continue;
+    }
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      // bundle this assistant message with the contiguous tool results answering its ids
+      const ids = new Set(m.tool_calls.map((t) => t.id));
+      const group = [m];
+      let j = i + 1;
+      while (j < msgs.length && msgs[j].role === 'tool' && ids.has(msgs[j].tool_call_id)) {
+        group.push(msgs[j]);
+        j++;
+      }
+      // `atomic` is litectx's group-id (string|null), NOT a boolean: units sharing one are kept/dropped
+      // whole. bareagent already pre-bundles a tool-call + its result(s) into ONE unit, so each bundle is
+      // its OWN group — group-id = the unit's id. (A boolean would collapse every bundle under one key,
+      // making litectx fit them all-or-nothing — see test/context-units.test.js (real-litectx sweep).)
+      const gid = `u${_seq++}`;
+      units.push(withBacking({ id: gid, role: 'assistant', content: renderContent(group.slice(1)), kind: null, pinned: false, atomic: gid, tokensApprox: approxTokens(group) }, group));
+      i = j - 1;
+      continue;
+    }
+    // plain assistant text, or a stray tool message (handled by the seatbelt on the way out)
+    units.push(withBacking({ id: `u${_seq++}`, role: m.role, content: renderContent([m]), kind: null, pinned: false, atomic: null, tokensApprox: approxTokens([m]) }, [m]));
+  }
+  return units;
+}
+
+/**
+ * Drop any tool-result whose tool_call_id has no open assistant tool-call before it, and any assistant
+ * tool-call message left with zero surviving results. The final grammar guard: even if litectx hands
+ * back something that would orphan a pair, the wire is always valid. Returns a fresh array.
+ */
+function pairingSeatbelt(msgs) {
+  // pass 1: which tool_call ids actually have a result present?
+  const resultIds = new Set();
+  for (const m of msgs) if (m.role === 'tool' && m.tool_call_id != null) resultIds.add(m.tool_call_id);
+
+  const out = [];
+  const open = new Set();
+  for (const m of msgs) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      const surviving = m.tool_calls.filter((tc) => resultIds.has(tc.id));
+      if (!surviving.length) continue; // assistant tool-call with no results at all → drop the message
+      for (const tc of surviving) open.add(tc.id);
+      out.push(surviving.length === m.tool_calls.length ? m : { ...m, tool_calls: surviving });
+      continue;
+    }
+    if (m.role === 'tool') {
+      if (!open.has(m.tool_call_id)) continue; // orphan result → drop
+      open.delete(m.tool_call_id);
+      out.push(m);
+      continue;
+    }
+    out.push(m);
+  }
+  return out;
+}
+
+/**
+ * units → msgs. Honors drop (absent units), reorder (order of the returned array), recall-inject
+ * (units with no backing → one synthesised message), and COMPRESS (a unit whose `content` was rewritten
+ * is reconstructed from the new content). Atomic units keep their assistant tool-call message verbatim
+ * so pairing holds; a content rewrite lands on the tool RESULT. A multi-result atomic bundle whose
+ * content was rewritten is kept VERBATIM — a flat string can't be faithfully split back into N
+ * results, and splitting is grammar (bareagent's), not litectx's to attempt. This isn't a special
+ * case: litectx's compress() is a pure text→text render that returns verbatim when handed no single
+ * parseable format (compress.js — "never returns less than the body losslessly"), so a flattened
+ * multi-result unit round-trips unchanged on both sides. RATIFIED by litectx (2026-06-12). The pairing
+ * seatbelt is the final guard.
+ * @param {Array<Record<string, any>>} units
+ * @returns {Array<Record<string, any>>}
+ */
+function fromUnits(units) {
+  const msgs = [];
+  for (const u of units) {
+    if (!u || typeof u !== 'object') continue;
+    const backing = u._msgs;
+
+    if (!Array.isArray(backing)) {
+      // litectx-minted (recall-inject): synthesise one message from role + content
+      msgs.push({ role: u.role || 'user', content: u.content == null ? '' : String(u.content) });
+      continue;
+    }
+
+    const edited = u.content !== u._origContent;
+    if (!edited) {
+      for (const m of backing) msgs.push(m); // verbatim — preserves tool_call_id pairing exactly
+      continue;
+    }
+
+    if (!u.atomic) {
+      // single backing message, content rewritten
+      msgs.push({ ...backing[0], content: u.content == null ? '' : String(u.content) });
+      continue;
+    }
+
+    // atomic + content rewritten: assistant message stays verbatim (pairing); rewrite lands on the
+    // single result. Multi-result bundle → keep verbatim (unsplittable).
+    const results = backing.slice(1);
+    if (results.length === 1) {
+      msgs.push(backing[0]);
+      msgs.push({ ...results[0], content: u.content == null ? '' : String(u.content) });
+    } else {
+      for (const m of backing) msgs.push(m);
+    }
+  }
+  return pairingSeatbelt(msgs);
+}
+
+/**
+ * Wrap litectx's `assemble(units, ctx)` verb into the Loop's msgs-level `assemble(msgs, ctx)` seam.
+ * litectx ships the **`AssembleResult` envelope** `{ units, dropped, tokens }` (CE-PRD §8.2: `dropped[]`
+ * is load-bearing — it ships in the same slice, never silently truncated). This wrapper accepts that
+ * envelope (uses `.units`) OR a bare `units` array (a simpler consumer). `dropped`/`tokens` are litectx's
+ * accounting; the Loop's seam is msgs-in/msgs-out, so they're not threaded onward here (the canonical
+ * transcript already holds every dropped unit by id — restorable on demand).
+ * Fail-OPEN at this layer too: any other return shape → the original msgs are sent unchanged. A thrown
+ * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
+ * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
+ * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ */
+function unitAssembler(assembleUnits) {
+  if (typeof assembleUnits !== 'function') {
+    throw new Error('[context-units] unitAssembler(fn): fn must be (units, ctx) => units');
+  }
+  return async (msgs, ctx) => {
+    const units = toUnits(msgs);
+    const out = await assembleUnits(units, ctx);
+    // litectx returns { units, dropped, tokens }; a bare array is also accepted. Anything else → fail-open.
+    const view = Array.isArray(out) ? out : (out && Array.isArray(out.units) ? out.units : null);
+    if (!view) return msgs; // fail-open: unrecognised return → full context
+    return fromUnits(view);
+  };
+}
+
+module.exports = { toUnits, fromUnits, unitAssembler, approxTokens, pairingSeatbelt };

package/src/loop.d.ts

@@ -20,6 +20,16 @@ export type LoopOptions = {
     onError?: Function | undefined;
     throwOnError?: boolean | undefined;
     policy?: Function | undefined;
+    /**
+     * - async (msgs, ctx) => msgs. Context-assembly chokepoint: shape the
+     * window sent to the provider each round (e.g. a context-engineering library). Returns a VIEW — the
+     * canonical transcript is never mutated. Fail-open (a thrown error degrades to full context); a
+     * thrown HaltError propagates. `ctx` is the per-run opaque blob (`run(msgs, tools, { ctx })`), the
+     * same object forwarded to `policy`; litectx reads `ctx.task` (intent) and `ctx.budget`. The
+     * neutral-unit signature `assemble(units, ctx)` is provided by bareagent's msgs⇄units adapter
+     * (src/context-units.js), which composes over this msgs-level seam.
+     */
+    assemble?: Function | undefined;
     onLlmResult?: Function | undefined;
     onToolResult?: Function | undefined;
     /**
@@ -49,6 +59,7 @@ export class Loop {
     throwOnError: boolean;
     store: import("../types").Store | null;
     policy: Function | null;
+    assemble: Function | null;
     onLlmResult: Function | null;
     onToolResult: Function | null;
     _stopped: boolean;

package/src/loop.js

@@ -26,6 +26,13 @@ const { ToolError, HaltError } = require('./errors');
  * @property {Function} [onError]
  * @property {boolean} [throwOnError]
  * @property {Function} [policy]
+ * @property {Function} [assemble] - async (msgs, ctx) => msgs. Context-assembly chokepoint: shape the
+ *   window sent to the provider each round (e.g. a context-engineering library). Returns a VIEW — the
+ *   canonical transcript is never mutated. Fail-open (a thrown error degrades to full context); a
+ *   thrown HaltError propagates. `ctx` is the per-run opaque blob (`run(msgs, tools, { ctx })`), the
+ *   same object forwarded to `policy`; litectx reads `ctx.task` (intent) and `ctx.budget`. The
+ *   neutral-unit signature `assemble(units, ctx)` is provided by bareagent's msgs⇄units adapter
+ *   (src/context-units.js), which composes over this msgs-level seam.
  * @property {Function} [onLlmResult]
  * @property {Function} [onToolResult]
  * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
@@ -132,6 +139,10 @@ class Loop {
       throw new Error('[Loop] options.policy must be a function (toolName, args, ctx) => true | string');
     }
     this.policy = options.policy || null;
+    if (options.assemble != null && typeof options.assemble !== 'function') {
+      throw new Error('[Loop] options.assemble must be a function (msgs, info) => msgs');
+    }
+    this.assemble = options.assemble || null;
     if (options.onLlmResult != null && typeof options.onLlmResult !== 'function') {
       throw new Error('[Loop] options.onLlmResult must be a function');
     }
@@ -243,10 +254,29 @@ class Loop {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
 
+      // RT-1: context-assembly chokepoint. Let a caller (e.g. a context-engineering library) shape
+      // the window sent to the provider this round. Returns a VIEW — the canonical `msgs` transcript
+      // is never mutated, so result.msgs stays complete and correct. Fail-OPEN: an assembly error
+      // degrades to sending full context (a context-optimizer bug must not halt the agent); a thrown
+      // HaltError is a governance exit and propagates (same contract as onLlmResult).
+      let toSend = msgs;
+      if (this.assemble) {
+        try {
+          const view = await this.assemble(msgs, ctx);
+          if (Array.isArray(view)) {
+            toSend = view;
+            this._safeEmit({ type: 'loop:assemble', data: { round, before: msgs.length, after: toSend.length } });
+          }
+        } catch (err) {
+          if (err instanceof HaltError) throw err;
+          this._reportError('assemble', err, { round });
+        }
+      }
+
       let result;
       const llmStartedAt = Date.now();
       try {
-        const generate = () => this.provider.generate(msgs, tools, options);
+        const generate = () => this.provider.generate(toSend, tools, options);
         result = this.retry ? await this.retry.call(generate) : await generate();
       } catch (err) {
         this._reportError('provider', err, { round });

package/src/tools.d.ts

@@ -5,4 +5,5 @@ import { createSpawnTool } from "../tools/spawn";
 import { spawnChild } from "../tools/spawn";
 import { createDeferTool } from "../tools/defer";
 import { readQueue as readDeferQueue } from "../tools/defer";
-export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue };
+import { liteCtxMcpBridgeConfig } from "../tools/litectx-mcp";
+export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue, liteCtxMcpBridgeConfig };

package/src/tools.js

@@ -5,6 +5,7 @@ const { createMobileTools } = require('../tools/mobile');
 const { createShellTools } = require('../tools/shell');
 const { createSpawnTool, spawnChild } = require('../tools/spawn');
 const { createDeferTool, readQueue: readDeferQueue } = require('../tools/defer');
+const { liteCtxMcpBridgeConfig } = require('../tools/litectx-mcp');
 
 module.exports = {
   createBrowsingTools,
@@ -14,4 +15,5 @@ module.exports = {
   spawnChild,
   createDeferTool,
   readDeferQueue,
+  liteCtxMcpBridgeConfig,
 };

package/tools/litectx-mcp.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Build a curated bridge config that mounts litectx-mcp read-only on its own db.
+ * @param {object} opts
+ * @param {string} opts.root - the child's OWN litectx root/db (passed as `--root`). Isolation.
+ * @param {string} [opts.command='litectx-mcp'] - the server command (override for a fake/abs path).
+ * @param {string[]} [opts.args=[]] - extra args appended after `--root <root>` (e.g. `--no-embeddings`).
+ * @param {boolean} [opts.writable=false] - opt-in: allow remember/forget (still child-db-local).
+ * @param {string} [opts.name='litectx'] - server name (tool prefix → `<name>_recall`, …).
+ * @param {string} [opts.ttl='24h'] - bridge config TTL.
+ * @param {string} [opts.now] - ISO timestamp for `discovered` (default: now). Pre-seed fresh so
+ *   `createMCPBridge` skips IDE discovery and connects straight to this curated server.
+ * @returns {import('../src/mcp-bridge').BridgeConfig}
+ */
+export function liteCtxMcpBridgeConfig(opts: {
+    root: string;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    writable?: boolean | undefined;
+    name?: string | undefined;
+    ttl?: string | undefined;
+    now?: string | undefined;
+}): import("../src/mcp-bridge").BridgeConfig;
+/** Read/reason verbs a child is given by default. */
+export const READ_VERBS: string[];
+/** Write verbs — denied unless `writable`, then allowed (writes still land in the child's OWN db). */
+export const WRITE_VERBS: string[];
+/** Admin/review verbs — always denied to a child (human/hook + review flows). */
+export const ADMIN_VERBS: string[];

package/tools/litectx-mcp.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// RT-4 — mount litectx-mcp into a child agent, read-only, on its own db. A thin recipe helper: it
+// builds the curated `.mcp-bridge.json` config that `createMCPBridge` consumes, so a parent composing
+// a child's toolbox can't fat-finger the allow-list (e.g. accidentally allow a write verb). It encodes
+// ONE thing — the agreed read-only default (PRD §4.2) — and knows only litectx-mcp's public verb names
+// (the same strings a hand-written `.mcp-bridge.json` would carry). It does NOT import litectx: the
+// dependency direction stays one-way; this is config curation, bareagent's job.
+//
+// Default toolbox (PRD §4.2):
+//   recall · get · impact · recent  → allow   (read / reason — the point of giving a child memory)
+//   remember · forget               → deny    (agent writes are by:"agent", suspect-until-curated;
+//                                               flip with { writable: true } as the explicit opt-in)
+//   index · promotions              → deny    (index is human/hook-driven; promotions is a review flow)
+//
+// Isolation is OWN-DB, not a scope column (this is what decouples RT-4 from RT-5): the child gets its
+// own `--root` → physical isolation, zero schema change. An opted-in child's writes land in ITS db;
+// promotion to the parent is an explicit parent-side `recall`→`remember`, never automatic.
+
+/** Read/reason verbs a child is given by default. */
+const READ_VERBS = ['recall', 'get', 'impact', 'recent'];
+/** Write verbs — denied unless `writable`, then allowed (writes still land in the child's OWN db). */
+const WRITE_VERBS = ['remember', 'forget'];
+/** Admin/review verbs — always denied to a child (human/hook + review flows). */
+const ADMIN_VERBS = ['index', 'promotions'];
+
+/**
+ * Build a curated bridge config that mounts litectx-mcp read-only on its own db.
+ * @param {object} opts
+ * @param {string} opts.root - the child's OWN litectx root/db (passed as `--root`). Isolation.
+ * @param {string} [opts.command='litectx-mcp'] - the server command (override for a fake/abs path).
+ * @param {string[]} [opts.args=[]] - extra args appended after `--root <root>` (e.g. `--no-embeddings`).
+ * @param {boolean} [opts.writable=false] - opt-in: allow remember/forget (still child-db-local).
+ * @param {string} [opts.name='litectx'] - server name (tool prefix → `<name>_recall`, …).
+ * @param {string} [opts.ttl='24h'] - bridge config TTL.
+ * @param {string} [opts.now] - ISO timestamp for `discovered` (default: now). Pre-seed fresh so
+ *   `createMCPBridge` skips IDE discovery and connects straight to this curated server.
+ * @returns {import('../src/mcp-bridge').BridgeConfig}
+ */
+function liteCtxMcpBridgeConfig(opts) {
+  if (!opts || typeof opts.root !== 'string' || !opts.root) {
+    throw new Error('[litectx-mcp] requires opts.root (the child\'s own db root — own-db isolation)');
+  }
+  const { root, command = 'litectx-mcp', args = [], writable = false, name = 'litectx', ttl = '24h', now } = opts;
+
+  /** @type {Record<string, string>} */
+  const tools = {};
+  for (const v of READ_VERBS) tools[v] = 'allow';
+  for (const v of WRITE_VERBS) tools[v] = writable ? 'allow' : 'deny';
+  for (const v of ADMIN_VERBS) tools[v] = 'deny';
+
+  return {
+    discovered: now || new Date().toISOString(),
+    ttl,
+    servers: {
+      [name]: {
+        command,
+        args: ['--root', root, ...args],
+        tools,
+      },
+    },
+  };
+}
+
+module.exports = { liteCtxMcpBridgeConfig, READ_VERBS, WRITE_VERBS, ADMIN_VERBS };