bare-agent 0.12.1 → 0.13.0

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