bare-agent 0.13.1 → 0.14.0

package/README.md

@@ -66,7 +66,7 @@ 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. 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) |
+| **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`). For summary-window compaction the Loop also lends a provider-bound `ctx.summarize(excerpt) => Promise<string>` (R-C6): the consumer owns when/what to summarize and the splice, bareagent makes the one model call (counted against the budget via `onLlmResult`, tagged `kind:'summarize'`). `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` |

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.13.1 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
+> v0.14.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)
 
@@ -306,7 +306,7 @@ if (result.error?.startsWith('halt:')) {
 }
 ```
 
-**Why four pieces (`policy` + `onLlmResult` + `onToolResult` + `filterTools`).** `policy` runs `gate.check` *before* every tool call. `onLlmResult` fires after every successful `provider.generate` — without it, `budget.maxCostUsd` never sees LLM cost and is silently undercounted for token-heavy / tool-light workloads (every chatbot). `onToolResult` fires after every `tool.execute` and carries the per-run `ctx` opaque blob into `gate.record` so per-principal accounting works. `filterTools` is a `gate.allows` pre-filter — denied tools are dropped from the catalog the LLM ever sees, no `gate.check` round-trip per call.
+**Why four pieces (`policy` + `onLlmResult` + `onToolResult` + `filterTools`).** `policy` runs `gate.check` *before* every tool call. `onLlmResult` fires after every successful `provider.generate` — without it, `budget.maxCostUsd` never sees LLM cost and is silently undercounted for token-heavy / tool-light workloads (every chatbot). It also fires for the out-of-band `ctx.summarize` call (R-C6) tagged `kind:'summarize'`; main-loop rounds carry `kind:'turn'` — so summary-window tokens count against the budget too, and a consumer can tell the two apart. `onToolResult` fires after every `tool.execute` and carries the per-run `ctx` opaque blob into `gate.record` so per-principal accounting works. `filterTools` is a `gate.allows` pre-filter — denied tools are dropped from the catalog the LLM ever sees, no `gate.check` round-trip per call.
 
 Halt-severity decisions exit the loop cleanly via a typed `HaltError` — full mechanics (sealed `msgs`, `halt:<rule>` error token, `loop:done{halted:true}` event, `throwOnError:true` interaction, `halt:unknown` coalesce) are in the **Halt decisions throw `HaltError`** paragraph below. Short version: check `result.error?.startsWith('halt:')` after the run.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -99,7 +99,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
-    "litectx": "^0.11.0",
+    "litectx": "^0.13.0",
     "typescript": "^5.7.0"
   }
 }

package/src/loop.d.ts

@@ -27,9 +27,18 @@ export type LoopOptions = {
      * 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.
+     * (src/context-units.js), which composes over this msgs-level seam. When `ctx` is an object, the
+     * Loop also lends a provider-bound `ctx.summarize(excerpt, opts?) => Promise<string>` (R-C6,
+     * non-enumerable): assemble calls it to roll a summary window — bareagent makes the one model
+     * call, the consumer owns the trigger/N/splice. Its usage is forwarded to `onLlmResult` so the
+     * summary tokens count against the budget.
      */
     assemble?: Function | undefined;
+    /**
+     * - async (event) => void after each LLM call; forwards usage to
+     * gate.record (via wireGate). `event.kind` discriminates the source: `'turn'` for a main-loop round,
+     * `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget.
+     */
     onLlmResult?: Function | undefined;
     onToolResult?: Function | undefined;
     /**

package/src/loop.js

@@ -32,8 +32,14 @@ const { ToolError, HaltError } = require('./errors');
  *   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]
+ *   (src/context-units.js), which composes over this msgs-level seam. When `ctx` is an object, the
+ *   Loop also lends a provider-bound `ctx.summarize(excerpt, opts?) => Promise<string>` (R-C6,
+ *   non-enumerable): assemble calls it to roll a summary window — bareagent makes the one model
+ *   call, the consumer owns the trigger/N/splice. Its usage is forwarded to `onLlmResult` so the
+ *   summary tokens count against the budget.
+ * @property {Function} [onLlmResult] - async (event) => void after each LLM call; forwards usage to
+ *   gate.record (via wireGate). `event.kind` discriminates the source: `'turn'` for a main-loop round,
+ *   `'summarize'` for an out-of-band `ctx.summarize` call (R-C6). Both count against the budget.
  * @property {Function} [onToolResult]
  * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
  */
@@ -105,6 +111,38 @@ function estimateCost(model, usage) {
   );
 }
 
+// R-C6: default instruction for the provider-bound `ctx.summarize` lent to the assemble seam.
+const DEFAULT_SUMMARY_INSTRUCTION =
+  'You are a precise conversation summarizer. Produce a concise, factual summary of the following ' +
+  'conversation excerpt. Preserve concrete facts, decisions, and identifiers (names, ids, file ' +
+  'paths, numbers), and note any open or unresolved threads. Do not invent information. Output ' +
+  'only the summary prose, with no preamble.';
+
+// Flatten an excerpt (array of OpenAI-format messages, or a raw string) into one prose block for the
+// summarizer's single user turn. Rendering to text — rather than forwarding raw messages — sidesteps
+// tool-call/result pairing entirely: a summary input never needs to be a valid wire transcript.
+/**
+ * @param {Array<any>|string|null|undefined} excerpt
+ * @returns {string}
+ */
+function renderForSummary(excerpt) {
+  if (excerpt == null) return '';
+  if (typeof excerpt === 'string') return excerpt;
+  if (!Array.isArray(excerpt)) return String(excerpt);
+  const parts = [];
+  for (const m of excerpt) {
+    if (m == null) continue;
+    if (typeof m === 'string') { parts.push(m); continue; }
+    const role = m.role || 'message';
+    let text = m.content != null ? String(m.content) : '';
+    if (Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      text += (text ? '\n' : '') + `[tool_calls: ${JSON.stringify(m.tool_calls)}]`;
+    }
+    parts.push(`${role}: ${text}`);
+  }
+  return parts.join('\n\n');
+}
+
 class Loop {
   /**
    * `policy` is async `(toolName, args, ctx) => true | string`. Recommended wiring: a closure
@@ -250,6 +288,65 @@ class Loop {
     let lastUsage = { inputTokens: 0, outputTokens: 0 };
     let totalCost = 0;
 
+    // R-C6: lend a provider-bound summarizer to the assemble seam via `ctx.summarize`. litectx owns
+    // the trigger/N/splice (its restorable COMPRESS path keeps summarized turns recoverable by id);
+    // bareagent lends ONLY the single model call. Attached NON-ENUMERABLE so it never shows up in the
+    // caller's ctx via JSON/iteration/deepEqual — preserving the `assemble(units, ctx)` identity
+    // contract (test/loop-assemble.test.js). `summarize(excerpt, opts?) => Promise<string>`:
+    //   excerpt — array of OpenAI-format messages (or a raw string) litectx wants compressed
+    //   opts    — { instruction?, ...generateOpts } (instruction overrides the default; the rest pass
+    //             through to provider.generate; temperature defaults to 0 for determinism)
+    // The summary call's usage is forwarded to onLlmResult so its tokens count against the budget
+    // (BA1 lineage — token-only flows must not be invisible to the gate); a HaltError there is a
+    // governance exit and propagates, matching the main-loop onLlmResult contract.
+    if (ctx && typeof ctx === 'object') {
+      const loop = this;
+      /**
+       * @param {Array<any>|string} excerpt
+       * @param {Record<string, any>} [opts]
+       * @returns {Promise<string>}
+       */
+      const summarize = async (excerpt, opts = {}) => {
+        const { instruction, ...genOpts } = opts || {};
+        const prompt = [
+          { role: 'system', content: instruction || DEFAULT_SUMMARY_INSTRUCTION },
+          { role: 'user', content: renderForSummary(excerpt) },
+        ];
+        const startedAt = Date.now();
+        const result = await loop.provider.generate(prompt, [], { temperature: 0, ...genOpts });
+        const usage = (result && result.usage) || null;
+        const model = loop.provider.model || null;
+        const cost = estimateCost(model, usage);
+        if (cost !== null) totalCost += cost;
+        loop._safeEmit({ type: 'loop:summarize', data: { usage, costUsd: cost, durationMs: Date.now() - startedAt } });
+        if (loop.onLlmResult) {
+          try {
+            await loop.onLlmResult({
+              model,
+              provider: loop.provider.name || null,
+              usage,
+              costUsd: cost,
+              durationMs: Date.now() - startedAt,
+              ctx,
+              kind: 'summarize',
+            });
+          } catch (err) {
+            if (err instanceof HaltError) throw err;
+            loop._reportError('onLlmResult', err, { phase: 'summarize' });
+          }
+        }
+        return (result && result.text) || '';
+      };
+      // Fail-OPEN to match the assemble seam's own contract: a frozen / sealed / non-configurable ctx
+      // must NOT crash the agent. On failure the seam is simply unavailable (consumers already handle
+      // ctx.summarize being absent — it only exists when ctx is an object), reported, never silent.
+      try {
+        Object.defineProperty(ctx, 'summarize', { value: summarize, enumerable: false, configurable: true, writable: true });
+      } catch (err) {
+        this._reportError('summarize-attach', err);
+      }
+    }
+
     try {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
@@ -301,6 +398,7 @@ class Loop {
             costUsd: roundCost,
             durationMs: Date.now() - llmStartedAt,
             ctx,
+            kind: 'turn',
           });
         } catch (err) {
           if (err instanceof HaltError) throw err;