bare-agent 0.12.2 → 0.13.1

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. The CE function reads its inputs from the per-run `ctx` — litectx's budget-fitter uses `ctx.budget` (and `ctx.task`), so you **must** populate it via `run(msgs, tools, { ctx })`: an unset `ctx.budget` means the fitter has no budget, keeps everything, and returns the window unchanged — a silent no-op, not a bug (see `examples/litectx-assemble.mjs`). `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 |
@@ -82,11 +82,11 @@ Every piece works alone — take what you need, ignore the rest.
 | **Browsing** | Web navigation, clicking, typing, reading via `barebrowse` (17 tools). Two modes: library tools (inline snapshots, pass to Loop) or CLI session (disk-based snapshots, token-efficient for multi-step flows). Optional `assess` tool (privacy scan) when `wearehere` is installed |
 | **Mobile** | Android + iOS device control via `baremobile`. Same two modes: library tools (`createMobileTools` — action tools auto-return snapshots) or CLI session (`baremobile` CLI — disk-based snapshots) |
 | **Shell** | Cross-platform `shell_read`, `shell_grep`, `shell_run` (argv, no shell), `shell_exec` (raw shell). Pure Node — no `grep`/`rg`/`findstr` dependency. Injection-proof `shell_run` for policy-gated use |
-| **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Static allow/deny via `.mcp-bridge.json`, `systemContext` for LLM awareness. Runtime policy lives in `Loop({ policy })` — one hook for MCP + native tools alike. Returns both bulk `tools` (one per MCP tool) and `metaTools` (`mcp_discover` + `mcp_invoke` for token-thrifty access to large catalogs). Zero deps |
+| **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Static allow/deny via `.mcp-bridge.json`, `systemContext` for LLM awareness. Runtime policy lives in `Loop({ policy })` — one hook for MCP + native tools alike. Returns both bulk `tools` (one per MCP tool) and `metaTools` (`mcp_discover` + `mcp_invoke` for token-thrifty access to large catalogs). Connecting runs a server's `command` (which may come from a cwd `.mcp.json`): pass `confirmServer` to vet each before it spawns — otherwise the bridge warns naming every command it runs. Every RPC is time-bounded (`timeout` for the handshake, `callTimeout` for `tools/call`), and a server that breaks its stdin pipe fails the connection instead of crashing the host. Zero deps |
 | **Spawn** | Fork a child bareagent process as a specialist agent. LLM-callable form blocks until child exits; library form returns a handle (`wait`, `onLine`, `kill`). One JSONL channel per child — child stderr captured and re-emitted as `child:stderr` events on the parent stream. Threads `BAREGUARD_AUDIT_PATH` / `BAREGUARD_PARENT_RUN_ID` / `BAREGUARD_BUDGET_FILE` / `BAREGUARD_SPAWN_DEPTH` so the family stitches into one audit + budget. `bareguard ^0.2.0` adds `spawn.ratePerMinute` + `limits.maxDepth` per-family caps |
 | **Defer** | Append a `{action, when}` record to a JSONL queue for a separate waker (cron / systemd timer / `examples/wake.sh`) to fire later. Two-phase governance: emit-time `gate.check` on the `defer` action; fire-time `gate.check` on the inner action when the waker re-invokes. `bareguard ^0.2.0` adds `defer.ratePerMinute` family-wide cap |
 
-**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely.
+**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely. The OpenAI provider warns if it would send your key over plaintext `http://` to a non-loopback host (use `https`, or drop `apiKey` for keyless local endpoints).
 
 **Tools:** Any function is a tool. REST APIs, MCP servers, CLI commands, shell scripts — if it's a function, it works. Built-in: `barebrowse` for web browsing, `baremobile` for Android + iOS device control (both optional) — library tools for inline results or CLI session mode for token-efficient disk-based snapshots.
 
@@ -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.1 | 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.
 
@@ -253,7 +254,19 @@ or `content.denyPatterns` over the serialized action.
 repo) as well as your home/IDE configs. Pass `confirmServer(name, def)
 => boolean` to `createMCPBridge` to approve each server **before its
 command is spawned** (return `false` to skip it; a throw fails closed).
-Default trusts all discovered servers — unchanged behavior.
+Default trusts all discovered servers — unchanged behavior. **When no
+`confirmServer` is set, the bridge prints a one-time warning naming every
+command it is about to spawn** (before the first spawn, discovery included),
+so a cwd `.mcp.json` can't run a command unannounced — `confirmServer` is
+still how you actually *gate* it.
+
+**RPC timeouts (Unreleased).** Every JSON-RPC round-trip is now bounded, so a
+server that never answers can't hang the bridge or the loop. `opts.timeout`
+(default 15 s) bounds the handshake (`initialize` + `tools/list`);
+`opts.callTimeout` (default 120 s, `0` disables) bounds each `tools/call`. A
+timed-out tool call rejects with a `timed out after Nms` `ToolError` rather
+than blocking forever; a server that breaks its stdin pipe surfaces as a
+failed connection, never an uncaught `EPIPE` crash.
 
 ## Wiring with bareguard
 
@@ -543,21 +556,47 @@ All return `{ text, toolCalls, usage: { inputTokens, outputTokens } }`. CLIPipe
 
 **Error body (v0.11.0):** on an HTTP error the OpenAI/Anthropic/Ollama providers throw a `ProviderError` whose `message` carries the upstream error string. The full parsed response is **not** attached to `err.body` by default (so an unexpected field can't leak through logs that dump the error object). Pass `{ exposeErrorBody: true }` to attach it for debugging.
 
+**Plaintext-key warning (Unreleased):** the OpenAI provider's `baseUrl` accepts `http://` (for local/OpenAI-compatible endpoints), but a `Bearer` key sent over plaintext http to a **non-loopback** host is exposed on the wire. The provider now warns once when that happens. Loopback hosts (`localhost`/`127.0.0.0/8`/`::1` — local proxies, Ollama-style endpoints) stay silent, since that's the legitimate keyless-local case. The header is **not** stripped (some local proxies want a key), so use `https` for any remote endpoint, or drop `apiKey` when the local endpoint needs none.
+
 **Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. Pricing covers OpenAI and Anthropic models; unknown models use a default average. To adjust rates, edit `COST_PER_1K` at the top of `src/loop.js`.
 
 ## Store options
 
 ```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-assemble.mjs

@@ -0,0 +1,78 @@
+// examples/litectx-assemble.mjs
+//
+// RT-1 — wire litectx's budget-fit `assemble` verb into bareagent's Loop context-assembly seam,
+// and show the ONE footgun: you must populate `ctx.budget`, or the fit is a silent no-op.
+//
+// Run:  node examples/litectx-assemble.mjs
+//       (runs litectx's real verb if installed — `npm install litectx` — otherwise an inline
+//        stand-in with identical budget semantics, so the lesson runs zero-dep.)
+//
+// How the seam works:
+//   - Loop({ assemble }) calls `assemble(msgs, ctx)` before EVERY provider call, sending the
+//     returned view (the canonical transcript is never mutated).
+//   - bareagent's `unitAssembler()` wraps a litectx-shaped `assemble(units, ctx)` into that
+//     msgs-level seam — bareagent owns the grammar (atomic tool-pair bundling, pinned system/task),
+//     litectx owns content + relevance.
+//   - litectx reads its inputs from the per-run `ctx`: `ctx.budget` (token budget) and `ctx.task`
+//     (recall intent). You pass that ctx via `loop.run(msgs, tools, { ctx })`.
+//
+// THE FOOTGUN: an unset `ctx.budget` is NOT a litectx bug. With no budget the fit defaults to
+// Infinity, keeps everything, and returns the window unchanged — so litectx's core verb LOOKS
+// broken when it is really a wiring omission. Always pass `ctx.budget`.
+
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { unitAssembler } = require('bare-agent');
+
+// litectx's real assemble verb if installed; else an inline stand-in with the same budget semantics
+// (best-effort, recency-anchored, never drops `pinned`, returns the { units, dropped, tokens } envelope).
+let assembleVerb;
+try {
+  ({ assemble: assembleVerb } = require('litectx')); // free function on the main entry (litectx 0.11+)
+  console.log("using litectx's real assemble() verb\n");
+} catch {
+  console.log('litectx not installed — using an inline stand-in with identical budget semantics\n');
+  const tok = (u) => (Number.isFinite(u.tokensApprox) ? u.tokensApprox : Math.ceil((u.content?.length ?? 0) / 4));
+  assembleVerb = (units, ctx = {}) => {
+    const budget = Number.isFinite(ctx.budget) ? ctx.budget : Infinity;
+    const keep = new Set();
+    let used = 0;
+    for (const u of units) if (u.pinned) { keep.add(u.id); used += tok(u); } // pinned always kept
+    // newest-first, skip-and-continue greedy over the un-pinned remainder
+    const rest = units.map((u, i) => ({ u, i })).filter(({ u }) => !u.pinned).sort((a, b) => b.i - a.i);
+    for (const { u } of rest) if (used + tok(u) <= budget) { keep.add(u.id); used += tok(u); }
+    const kept = units.filter((u) => keep.has(u.id));
+    const dropped = units.filter((u) => !keep.has(u.id)).map((u) => ({ id: u.id, reason: 'budget' }));
+    return { units: kept, dropped, tokens: used };
+  };
+}
+
+// the seam bareagent's Loop calls: assemble(msgs, ctx) => msgs
+const assemble = unitAssembler(assembleVerb);
+
+// a transcript grown past budget: a pinned system prompt + the task, then several tool rounds.
+const msgs = [
+  { role: 'system', content: 'You are a helpful coding agent. '.repeat(20) },
+  { role: 'user', content: 'Find and fix the rate-limiter bug in the auth service.' },
+];
+for (let i = 1; i <= 8; i++) {
+  const id = `call_${i}`;
+  msgs.push({ role: 'assistant', content: `Round ${i}: inspecting.`, tool_calls: [{ id, type: 'function', function: { name: 'read_file', arguments: `{"path":"src/auth/round${i}.js"}` } }] });
+  msgs.push({ role: 'tool', tool_call_id: id, content: `// round ${i} file contents — `.repeat(40) });
+}
+const before = msgs.length;
+
+// (1) ctx.budget SET — the fit drops the oldest un-pinned rounds to fit the budget.
+const fitted = await assemble(msgs, { budget: 400, task: 'rate-limiter bug' });
+console.log(`with ctx.budget=400  : ${before} msgs -> ${fitted.length} msgs (fit dropped ${before - fitted.length})`);
+
+// (2) ctx.budget UNSET — the footgun. No budget => Infinity => nothing drops => window unchanged.
+const noop = await assemble(msgs, { task: 'rate-limiter bug' }); // <-- budget missing
+console.log(`with ctx.budget unset: ${before} msgs -> ${noop.length} msgs (fit dropped ${before - noop.length})  <-- silent no-op!`);
+
+// the pinned system prompt + task always survive the fit (pin, don't hide):
+console.log(`\nsystem prompt survives the tight fit: ${fitted.some((m) => m.role === 'system')}`);
+console.log(`task (first user turn) survives the tight fit: ${fitted.some((m) => m.role === 'user')}`);
+
+console.log('\nLesson: wire it as  loop.run(msgs, tools, { ctx: { budget, task } }).');
+console.log('An unset ctx.budget is not a litectx bug — the fitter correctly keeps everything when given no budget.');

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/wake.sh

@@ -63,6 +63,14 @@ echo "$PENDING" | while IFS= read -r record; do
   ID=$(echo "$record" | jq -r '.id')
   ACTION=$(echo "$record" | jq -c '.action')
 
+  # The defer tool generates ids as def_<base36>_<hex>. Anything else means a
+  # hand-edited / untrusted queue line — reject before $ID reaches a file path
+  # below (defence-in-depth against path traversal via a crafted id).
+  case "$ID" in
+    def_[a-z0-9]*_[a-f0-9]*) ;;
+    *) echo "[wake $NOW] skipping record with unexpected id: $ID" >&2; continue ;;
+  esac
+
   # Append "fired" status line first (defer queue is append-only).
   printf '{"id":"%s","status":"fired","ts":"%s"}\n' "$ID" "$NOW" >> "$QUEUE"
 

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.1",
   "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[];