bare-agent 0.14.0 → 0.15.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`). 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) |
+| **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'`). For an unbounded long-running agent there's the **destructive** counterpart `Loop({ trim })` (RT-2) — a per-round bound on the canonical transcript that evicts old turns *after* harvesting them; wire it with the exported `unitTrimmer({ trim, onHarvest, policy })` over litectx's `trim` verb (harvest-before-evict, fail-open; `harvestKey` gives the stable upsert id), opt-in (requires a consumer on litectx ≥ 0.16.0). `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` |
@@ -240,17 +240,20 @@ For wiring recipes and API details, see the **[Integration Guide](bareagent.cont
 
 ## The bare ecosystem
 
-Four vanilla JS modules. Zero deps where possible (bareguard has one). Same API patterns.
+Local-first, composable agent infrastructure. Same API patterns throughout —
+mix and match, each module works standalone.
 
-| | [**bareagent**](https://npmjs.com/package/bare-agent) | [**barebrowse**](https://npmjs.com/package/barebrowse) | [**baremobile**](https://npmjs.com/package/baremobile) | [**bareguard**](https://npmjs.com/package/bareguard) |
-|---|---|---|---|---|
-| **Does** | Gives agents a think→act loop | Gives agents a real browser | Gives agents Android + iOS devices | Gates everything an agent does |
-| **How** | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out | Action in → allow / deny / human-asked out |
-| **Replaces** | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, XCUITest | Hand-rolled allowlists, scattered policy code |
-| **Interfaces** | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP | Library |
-| **Solo or together** | Orchestrates the others as tools | Works standalone | Works standalone | Embedded in bareagent's loop; usable by any runner |
+**Core** — the brain, the gate, the memory.
 
-> **Reach 50+ messengers with one Docker container via [beeperbox](https://github.com/hamr0/beeperbox)** — a headless Beeper Desktop that exposes WhatsApp, iMessage, Signal, Telegram, Slack, Discord, RCS, SMS and more as a single MCP server. Wire it through bareagent's MCP bridge; bareguard policies the invocations like any other tool (per-chat allowlists, ask patterns on destructive sends, all the usual layered defense).
+- **[bareagent](https://npmjs.com/package/bare-agent)** — the think→act→observe loop. *Goal in → coordinated actions out.* Replaces LangChain, CrewAI, AutoGen.
+- **[bareguard](https://npmjs.com/package/bareguard)** — the single gate every action passes through. *Action in → allow / deny / ask-a-human out.* Replaces hand-rolled allowlists and scattered policy code.
+- **[litectx](https://npmjs.com/package/litectx)** — tree-sitter code + memory graph with activation decay, plus lightweight context engineering (write · select · compress · isolate). *Query in → ranked context out.*
+
+**Optional reach** — give the agent hands.
+
+- **[barebrowse](https://npmjs.com/package/barebrowse)** — a real browser for agents. *URL in → pruned snapshot out.* Replaces Playwright, Selenium, Puppeteer.
+- **[baremobile](https://npmjs.com/package/baremobile)** — Android + iOS device control. *Screen in → pruned snapshot out.* Replaces Appium, Espresso, XCUITest.
+- **[beeperbox](https://github.com/hamr0/beeperbox)** — 50+ messaging networks via one MCP server (headless Beeper Desktop in Docker). *Chat in → unified message stream out.* Replaces Twilio, per-platform bot APIs.
 
 **What you can build:**
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.14.0 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
+> v0.15.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,7 +14,7 @@ npm install bare-agent
 ```
 
 Eight entry points:
-- `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')` — Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, **toUnits, fromUnits, unitAssembler** (the `assemble` context-units adapter, v0.13+), **unitTrimmer, harvestKey** (the destructive `trim` seam adapter — RT-2 harvest-before-evict, needs a consumer on litectx ≥ 0.16.0), 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

package/index.d.ts

@@ -13,6 +13,8 @@ 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 { unitTrimmer } from "./src/context-units";
+import { harvestKey } from "./src/context-units";
 import { BareAgentError } from "./src/errors";
 import { ProviderError } from "./src/errors";
 import { ToolError } from "./src/errors";
@@ -20,4 +22,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, toUnits, fromUnits, unitAssembler, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };
+export { Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };

package/index.js

@@ -11,7 +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 { toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey } = require('./src/context-units');
 const {
   BareAgentError,
   ProviderError,
@@ -38,6 +38,8 @@ module.exports = {
   toUnits,
   fromUnits,
   unitAssembler,
+  unitTrimmer,
+  harvestKey,
   BareAgentError,
   ProviderError,
   ToolError,

package/package.json

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

package/src/context-units.d.ts

@@ -34,6 +34,67 @@ export function fromUnits(units: Array<Record<string, any>>): Array<Record<strin
  * @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>>>;
+/**
+ * Wrap litectx's `trim(units, policy)` verb (R-C5) into the Loop's destructive `trim(msgs, ctx)` seam —
+ * the RT-2 harvest-before-evict interlock. Unlike {@link unitAssembler} (a non-destructive per-round VIEW),
+ * this is EVICTION: the Loop replaces its canonical transcript with the returned (smaller) msgs, so old
+ * turns are permanently dropped — which is only safe because every dropped turn is harvested FIRST.
+ *
+ * The returned function `(msgs, ctx) => keptMsgs`:
+ *   1. `toUnits(msgs)` → `trim(units, policy)` → `{ units (kept), dropped, harvest }`.
+ *   2. **Interlock — harvest BEFORE evict:** `await onHarvest({ key, content, unit })` for every harvest
+ *      unit. If `onHarvest` throws (e.g. a write-gate `deny` → HaltError, or a store fault), this throws
+ *      BEFORE returning the evicted view → the Loop fail-opens (no eviction that round) → nothing is lost;
+ *      the next round retries and the idempotent key upserts the already-persisted ones. You cannot drop
+ *      history you have not persisted.
+ *   3. `fromUnits(kept)` is the bounded transcript. Fail-OPEN: an unrecognised `trim` return shape → the
+ *      original msgs unchanged (no eviction). A throw propagates (HaltError → governance halt).
+ *
+ * `.flush(msgs, ctx)` — the F2 residual harvest: `trim` only hands back EVICTED turns, so the final
+ * keepLastN window is never harvested mid-run and a clean run would diverge from an end-of-task batch.
+ * Call `.flush` on completion to harvest the surviving non-pinned turns (no eviction); the idempotent key
+ * means it never duplicates what eviction already harvested. The Loop invokes it only on **clean
+ * completion** — on a halt (e.g. bareguard `maxTurns`), `stop()`, or error exit the survivors stay intact
+ * in `result.msgs` but are NOT auto-flushed (auto-flushing a content-halt could re-trigger the deny that
+ * caused it); harvest `result.msgs` yourself on those exits if you need the final window persisted.
+ *
+ * `onHarvest` is the consumer's harvest POLICY point (litectx CE-PRD §6/R-W*: bareagent owns the trigger
+ * + what's worth keeping, litectx owns the mechanism + worklist). It is REQUIRED — the adapter structurally
+ * enforces harvest-before-evict; pass `async () => {}` to opt INTO lossy bounding.
+ *
+ * @param {{ trim?: Function, onHarvest?: Function, policy?: any }} [opts]
+ *   `trim` — litectx's `(units, policy) => { units, harvest }` verb (REQUIRED). `onHarvest` —
+ *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
+ *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
+ * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ */
+export function unitTrimmer(opts?: {
+    trim?: Function;
+    onHarvest?: Function;
+    policy?: any;
+}): ((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & {
+    flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void>;
+};
+/**
+ * Stable harvest key for a unit — the dedup id for harvest-before-evict (RT-2). MUST come from a durable
+ * property of the TURN, never from `unit.id`: `toUnits` mints ids from a module counter, so the same turn
+ * is `u1` on one call and `u3` on the next (poc/rt2-trim-interlock.mjs F1) — keying on it double-writes.
+ * Derived here from the unit's verbatim `_msgs` backing: the joined `tool_call_id`s for a tool turn (stable
+ * by construction), else a hash of `[role, content]` for a plain turn. The consumer namespaces it (e.g.
+ * `${taskId}:${key}`) and feeds it to `remember(id, …)`, which upserts → a replayed hop overwrites instead
+ * of duplicating. NOT a content search (litectx FTS can't match ids; sealed meta is unsearchable) — a
+ * deterministic key passed to the keyed write. The consumer's `taskId` prefix is the isolation boundary;
+ * treat the returned key as opaque (don't re-parse it).
+ *
+ * Two collision hardenings (grounded in poc/rt2-audit-grounding.mjs): ids are `encodeURIComponent`-escaped
+ * before the `,` join, so `['a','b']` and `['a,b']` can no longer alias the same key; and the plain-turn
+ * hash is **two near-independent streams** (FNV-1a + DJB2) → ~64-bit, so a long-running agent's harvest
+ * can't silently overwrite a turn via a 32-bit birthday collision (a single 32-bit FNV exhausted in ~5e5
+ * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
+ * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
+ * @returns {string}
+ */
+export function harvestKey(unit: Record<string, any>): string;
 /** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */
 export function approxTokens(msgs: any): number;
 /**

package/src/context-units.js

@@ -222,4 +222,104 @@ function unitAssembler(assembleUnits) {
   };
 }
 
-module.exports = { toUnits, fromUnits, unitAssembler, approxTokens, pairingSeatbelt };
+/**
+ * Stable harvest key for a unit — the dedup id for harvest-before-evict (RT-2). MUST come from a durable
+ * property of the TURN, never from `unit.id`: `toUnits` mints ids from a module counter, so the same turn
+ * is `u1` on one call and `u3` on the next (poc/rt2-trim-interlock.mjs F1) — keying on it double-writes.
+ * Derived here from the unit's verbatim `_msgs` backing: the joined `tool_call_id`s for a tool turn (stable
+ * by construction), else a hash of `[role, content]` for a plain turn. The consumer namespaces it (e.g.
+ * `${taskId}:${key}`) and feeds it to `remember(id, …)`, which upserts → a replayed hop overwrites instead
+ * of duplicating. NOT a content search (litectx FTS can't match ids; sealed meta is unsearchable) — a
+ * deterministic key passed to the keyed write. The consumer's `taskId` prefix is the isolation boundary;
+ * treat the returned key as opaque (don't re-parse it).
+ *
+ * Two collision hardenings (grounded in poc/rt2-audit-grounding.mjs): ids are `encodeURIComponent`-escaped
+ * before the `,` join, so `['a','b']` and `['a,b']` can no longer alias the same key; and the plain-turn
+ * hash is **two near-independent streams** (FNV-1a + DJB2) → ~64-bit, so a long-running agent's harvest
+ * can't silently overwrite a turn via a 32-bit birthday collision (a single 32-bit FNV exhausted in ~5e5
+ * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
+ * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
+ * @returns {string}
+ */
+function harvestKey(unit) {
+  const back = (unit && unit._msgs) || [];
+  /** @type {string[]} */
+  const calls = [];
+  for (const m of back) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls)) for (const tc of m.tool_calls) if (tc && tc.id) calls.push(tc.id);
+  }
+  // escape so a literal ',' inside an id can't alias across call shapes ([{id:'a,b'}] vs [{id:'a'},{id:'b'}]).
+  if (calls.length) return `tc:${calls.map((id) => encodeURIComponent(id)).join(',')}`;
+  // plain turn (no tool_calls): two near-independent rolling hashes over role+content (FNV-1a + DJB2),
+  // concatenated to ~64 bits → collision-resistant at agent scale. Stable across toUnits calls.
+  let h1 = 0x811c9dc5; // FNV-1a offset basis
+  let h2 = 5381;       // DJB2 seed
+  const s = JSON.stringify(back.map((m) => [m.role, m.content]));
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 ^= c; h1 = Math.imul(h1, 0x01000193);
+    h2 = (Math.imul(h2, 33) + c) | 0;
+  }
+  return `h:${(h1 >>> 0).toString(36)}${(h2 >>> 0).toString(36)}`;
+}
+
+/**
+ * Wrap litectx's `trim(units, policy)` verb (R-C5) into the Loop's destructive `trim(msgs, ctx)` seam —
+ * the RT-2 harvest-before-evict interlock. Unlike {@link unitAssembler} (a non-destructive per-round VIEW),
+ * this is EVICTION: the Loop replaces its canonical transcript with the returned (smaller) msgs, so old
+ * turns are permanently dropped — which is only safe because every dropped turn is harvested FIRST.
+ *
+ * The returned function `(msgs, ctx) => keptMsgs`:
+ *   1. `toUnits(msgs)` → `trim(units, policy)` → `{ units (kept), dropped, harvest }`.
+ *   2. **Interlock — harvest BEFORE evict:** `await onHarvest({ key, content, unit })` for every harvest
+ *      unit. If `onHarvest` throws (e.g. a write-gate `deny` → HaltError, or a store fault), this throws
+ *      BEFORE returning the evicted view → the Loop fail-opens (no eviction that round) → nothing is lost;
+ *      the next round retries and the idempotent key upserts the already-persisted ones. You cannot drop
+ *      history you have not persisted.
+ *   3. `fromUnits(kept)` is the bounded transcript. Fail-OPEN: an unrecognised `trim` return shape → the
+ *      original msgs unchanged (no eviction). A throw propagates (HaltError → governance halt).
+ *
+ * `.flush(msgs, ctx)` — the F2 residual harvest: `trim` only hands back EVICTED turns, so the final
+ * keepLastN window is never harvested mid-run and a clean run would diverge from an end-of-task batch.
+ * Call `.flush` on completion to harvest the surviving non-pinned turns (no eviction); the idempotent key
+ * means it never duplicates what eviction already harvested. The Loop invokes it only on **clean
+ * completion** — on a halt (e.g. bareguard `maxTurns`), `stop()`, or error exit the survivors stay intact
+ * in `result.msgs` but are NOT auto-flushed (auto-flushing a content-halt could re-trigger the deny that
+ * caused it); harvest `result.msgs` yourself on those exits if you need the final window persisted.
+ *
+ * `onHarvest` is the consumer's harvest POLICY point (litectx CE-PRD §6/R-W*: bareagent owns the trigger
+ * + what's worth keeping, litectx owns the mechanism + worklist). It is REQUIRED — the adapter structurally
+ * enforces harvest-before-evict; pass `async () => {}` to opt INTO lossy bounding.
+ *
+ * @param {{ trim?: Function, onHarvest?: Function, policy?: any }} [opts]
+ *   `trim` — litectx's `(units, policy) => { units, harvest }` verb (REQUIRED). `onHarvest` —
+ *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
+ *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
+ * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ */
+function unitTrimmer(opts) {
+  const { trim, onHarvest, policy = {} } = opts || {};
+  if (typeof trim !== 'function') throw new Error('[context-units] unitTrimmer({ trim }): trim must be litectx\'s (units, policy) => { units, harvest } verb');
+  if (typeof onHarvest !== 'function') throw new Error('[context-units] unitTrimmer({ onHarvest }): onHarvest is required (harvest-before-evict). Pass `async () => {}` to opt into lossy bounding.');
+
+  /** @type {any} */
+  const run = async (/** @type {Array<Record<string, any>>} */ msgs /*, ctx */) => {
+    const units = toUnits(msgs);
+    const r = await trim(units, policy);
+    const kept = r && Array.isArray(r.units) ? r.units : null;
+    if (!kept) return msgs; // fail-open: unrecognised return shape → no eviction
+    const harvest = r && Array.isArray(r.harvest) ? r.harvest : [];
+    for (const u of harvest) await onHarvest({ key: harvestKey(u), content: u.content, unit: u }); // BEFORE evict
+    return fromUnits(kept);
+  };
+
+  // F2 residual: harvest the surviving non-pinned turns (no eviction). pinned (system + first user) are
+  // reconstructable/anchor turns, never evicted by trim, so they're excluded here for symmetry.
+  run.flush = async (/** @type {Array<Record<string, any>>} */ msgs /*, ctx */) => {
+    for (const u of toUnits(msgs)) if (!u.pinned) await onHarvest({ key: harvestKey(u), content: u.content, unit: u });
+  };
+
+  return run;
+}
+
+module.exports = { toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, approxTokens, pairingSeatbelt };

package/src/loop.d.ts

@@ -34,6 +34,16 @@ export type LoopOptions = {
      * summary tokens count against the budget.
      */
     assemble?: Function | undefined;
+    /**
+     * - async (msgs, ctx) => msgs. DESTRUCTIVE transcript-trim chokepoint (RT-2),
+     * the opposite of `assemble`: it BOUNDS the canonical transcript — the Loop replaces `msgs` with what
+     * this returns, evicting old turns AFTER they are harvested. Runs once per round before `assemble`.
+     * So eviction never drops un-persisted history, wire it via `unitTrimmer({ trim, onHarvest, policy })`
+     * (src/context-units.js), which performs the harvest-before-evict interlock over litectx's `trim` verb.
+     * An optional `.flush(msgs, ctx)` method is called on clean completion for the residual-window harvest.
+     * Fail-open (a trim fault degrades to no eviction that round); a thrown HaltError propagates.
+     */
+    trim?: 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,
@@ -69,6 +79,7 @@ export class Loop {
     store: import("../types").Store | null;
     policy: Function | null;
     assemble: Function | null;
+    trim: Function | null;
     onLlmResult: Function | null;
     onToolResult: Function | null;
     _stopped: boolean;

package/src/loop.js

@@ -37,6 +37,13 @@ const { ToolError, HaltError } = require('./errors');
  *   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} [trim] - async (msgs, ctx) => msgs. DESTRUCTIVE transcript-trim chokepoint (RT-2),
+ *   the opposite of `assemble`: it BOUNDS the canonical transcript — the Loop replaces `msgs` with what
+ *   this returns, evicting old turns AFTER they are harvested. Runs once per round before `assemble`.
+ *   So eviction never drops un-persisted history, wire it via `unitTrimmer({ trim, onHarvest, policy })`
+ *   (src/context-units.js), which performs the harvest-before-evict interlock over litectx's `trim` verb.
+ *   An optional `.flush(msgs, ctx)` method is called on clean completion for the residual-window harvest.
+ *   Fail-open (a trim fault degrades to no eviction that round); a thrown HaltError propagates.
  * @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.
@@ -181,6 +188,15 @@ class Loop {
       throw new Error('[Loop] options.assemble must be a function (msgs, info) => msgs');
     }
     this.assemble = options.assemble || null;
+    // RT-2: optional DESTRUCTIVE transcript-trim seam. Unlike `assemble` (a non-destructive view), `trim`
+    // bounds the canonical transcript — the Loop replaces `msgs` with what it returns, evicting old turns
+    // AFTER they've been harvested (the harvest-before-evict interlock lives in the trimmer; see
+    // src/context-units.js unitTrimmer). Opt-in: a Loop with no `trim` is unchanged. A `.flush` method on
+    // the function (if present) is called on clean completion for the F2 residual harvest.
+    if (options.trim != null && typeof options.trim !== 'function') {
+      throw new Error('[Loop] options.trim must be a function (msgs, ctx) => msgs (e.g. unitTrimmer({ trim, onHarvest, policy }))');
+    }
+    this.trim = options.trim || null;
     if (options.onLlmResult != null && typeof options.onLlmResult !== 'function') {
       throw new Error('[Loop] options.onLlmResult must be a function');
     }
@@ -351,6 +367,29 @@ class Loop {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
 
+      // RT-2: destructive transcript-trim chokepoint — bound the canonical transcript before assembling
+      // the window. Runs BEFORE assemble (trim shrinks canonical; assemble shapes the per-call view of
+      // what remains). The trimmer harvests every evicted turn BEFORE returning the smaller set, so this
+      // never drops un-persisted history. Mutate `msgs` IN PLACE (it's `const`, and result.msgs returns
+      // this same reference) → result.msgs becomes the bounded transcript; evicted turns live in the
+      // harvest store, restorable by id. Fail-OPEN: a trim fault degrades to no eviction this round (a
+      // context-bounding bug must not halt the agent); a HaltError (e.g. a write-gate deny during harvest)
+      // propagates as a clean governance exit — same contract as assemble/onLlmResult.
+      if (this.trim) {
+        try {
+          const before = msgs.length;
+          const kept = await this.trim(msgs, ctx);
+          if (Array.isArray(kept) && kept !== msgs) {
+            msgs.length = 0;
+            msgs.push(...kept);
+            if (msgs.length !== before) this._safeEmit({ type: 'loop:trim', data: { round, before, after: msgs.length } });
+          }
+        } catch (err) {
+          if (err instanceof HaltError) throw err;
+          this._reportError('trim', err, { round });
+        }
+      }
+
       // 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
@@ -412,6 +451,15 @@ class Loop {
         this._safeCall('onText', this.onText, result.text);
         this._safeEmit({ type: 'loop:done', data: { text: result.text, usage: lastUsage, cost: totalCost } });
         msgs.push({ role: 'assistant', content: result.text });
+        // RT-2 F2: residual harvest of the surviving window (incl. this final answer) on clean completion.
+        // `trim` only harvests EVICTED turns; without this, the never-evicted tail would diverge from an
+        // end-of-task batch. The trimmer's idempotent key means it never re-writes what eviction harvested.
+        // Fail-open / HaltError per the trim seam contract. No-op unless a `.flush`-capable trim is wired.
+        const flush = this.trim && /** @type {any} */ (this.trim).flush;
+        if (typeof flush === 'function') {
+          try { await flush(msgs, ctx); }
+          catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
+        }
         return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs };
       }