bare-agent 0.12.1 → 0.13.0

package/examples/replay-job.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Replay-job POC — supervised replay of a recorded browser task.
+ *
+ * The idea: record once with the LLM driving (full reasoning), then on every
+ * subsequent run replay the recorded *intents* against a fresh snapshot, with
+ * the LLM acting as a locator/supervisor — not a planner. If the locator
+ * can't find a match for a step, fall back to full Loop reasoning from that
+ * point and overwrite the trace. That's the self-healing path.
+ *
+ * Why this isn't a barebrowse feature: barebrowse stays dumb (URL → snapshot,
+ * ref → action). The "job" concept (trace storage, replay supervisor, scheduler
+ * hookup) is composed from bareagent primitives.
+ *
+ * Usage:
+ *   # First run — record:
+ *   OPENAI_API_KEY=sk-... node examples/replay-job.js --record demo-job \
+ *     "Go to example.com and click the 'More information' link"
+ *
+ *   # Subsequent runs — replay:
+ *   OPENAI_API_KEY=sk-... node examples/replay-job.js --replay demo-job
+ *
+ *   # Cron'd:
+ *   *\/15 * * * * node /path/to/replay-job.js --replay demo-job
+ *
+ * What's deliberately NOT in this POC (next steps, in order):
+ *   1. Fingerprint fast-path: hash selector+role+text per step, try direct
+ *      match before calling the locator LLM. Brings per-step cost to ~0 on
+ *      stable UIs (Gmail, IG).
+ *   2. PostState assertion: after each step, ask the LLM "does this snapshot
+ *      reflect the expected outcome?" Without this, replay can silently drift
+ *      on subtly-changed UIs.
+ *   3. Trace confidence: rolling success rate per step; below a threshold,
+ *      re-derive the whole trace instead of patching one entry.
+ *   4. Scheduler integration: wrap as a Scheduler trigger so cron is a config
+ *      line instead of an OS cron entry.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Loop } = require('../src/loop');
+
+const JOBS_DIR = path.join(__dirname, '..', '.jobs');
+
+function parseArgs(argv) {
+  const mode = argv.includes('--record') ? 'record'
+             : argv.includes('--replay') ? 'replay'
+             : null;
+  const flagIdx = argv.indexOf(`--${mode}`);
+  const name = mode ? argv[flagIdx + 1] : null;
+  const goal = argv.slice(flagIdx + 2).join(' ');
+  return { mode, name, goal };
+}
+
+function jobPath(name) { return path.join(JOBS_DIR, `${name}.json`); }
+
+function loadProvider() {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) { console.error('Set OPENAI_API_KEY'); process.exit(1); }
+  const { OpenAIProvider } = require('../src/provider-openai');
+  return new OpenAIProvider({ apiKey, model: 'gpt-4.1-mini' });
+}
+
+async function loadBrowseTools() {
+  const mod = await import('barebrowse/bareagent');
+  return mod.createBrowseTools({});
+}
+
+// --- RECORD ----------------------------------------------------------------
+// Run Loop normally. The onToolCall hook captures each step as it happens.
+// The trace stores the LLM's free-text "intent" (the assistant message
+// immediately preceding the tool call) alongside the tool name and args.
+// On replay, intent is what the locator LLM matches against — not args.
+async function record({ name, goal }) {
+  const provider = loadProvider();
+  const { tools, close } = await loadBrowseTools();
+
+  const trace = [];
+  let pendingIntent = '';
+
+  const loop = new Loop({
+    provider,
+    maxRounds: 15,
+    onText: (text) => { pendingIntent = text; },
+    onToolCall: (toolName, args) => {
+      trace.push({ intent: pendingIntent.trim().slice(0, 500), tool: toolName, args });
+      pendingIntent = '';
+    },
+  });
+
+  try {
+    const result = await loop.run([{ role: 'user', content: goal }], tools);
+    fs.mkdirSync(JOBS_DIR, { recursive: true });
+    fs.writeFileSync(jobPath(name), JSON.stringify({ goal, recordedAt: new Date().toISOString(), trace }, null, 2));
+    console.log(`[record] saved ${trace.length} steps to ${jobPath(name)}`);
+    console.log(`[record] cost: $${(result.cost ?? 0).toFixed(4)}`);
+  } finally {
+    await close();
+  }
+}
+
+// --- REPLAY ----------------------------------------------------------------
+// For each recorded step:
+//   1. Take a fresh snapshot.
+//   2. Ask the LLM (no tools, JSON-mode) to map the recorded intent to a ref
+//      in the current snapshot — OR return null if no match.
+//   3. On match: execute the tool with the resolved ref. The recorded args
+//      that aren't refs (e.g. type's `text`, goto's `url`) carry over verbatim.
+//   4. On miss: fall back to driving Loop from the remaining goal, capture
+//      the new sub-trace, and splice it into the saved trace.
+async function replay({ name }) {
+  const job = JSON.parse(fs.readFileSync(jobPath(name), 'utf8'));
+  const provider = loadProvider();
+  const { tools, close } = await loadBrowseTools();
+  const toolByName = Object.fromEntries(tools.map((t) => [t.name, t]));
+
+  let mutated = false;
+
+  try {
+    for (let i = 0; i < job.trace.length; i++) {
+      const step = job.trace[i];
+      const tool = toolByName[step.tool];
+      if (!tool) throw new Error(`unknown tool in trace: ${step.tool}`);
+
+      // Steps whose args have no ref (goto, browse, back, scroll) replay verbatim.
+      if (!('ref' in (step.args || {}))) {
+        console.log(`[replay ${i + 1}/${job.trace.length}] ${step.tool}(${JSON.stringify(step.args)})`);
+        await tool.execute(step.args);
+        continue;
+      }
+
+      // Ref-bearing steps: snapshot, then ask the LLM to locate.
+      const snapshot = await toolByName.snapshot.execute({});
+      const snapshotText = typeof snapshot === 'string' ? snapshot : (snapshot?.snapshot ?? JSON.stringify(snapshot));
+      const located = await locate({ provider, intent: step.intent, tool: step.tool, snapshotText });
+
+      if (located.ref) {
+        const args = { ...step.args, ref: located.ref };
+        console.log(`[replay ${i + 1}/${job.trace.length}] ${step.tool}(ref=${located.ref}) — intent="${step.intent.slice(0, 60)}"`);
+        await tool.execute(args);
+      } else {
+        console.warn(`[replay ${i + 1}/${job.trace.length}] locator miss — falling back to full Loop`);
+        const remaining = `Continue this task from the current page. Original goal: ${job.goal}. We have completed ${i} of ${job.trace.length} recorded steps; the next intended step was: "${step.intent}".`;
+        const subTrace = await driveFallback({ provider, tools, goal: remaining });
+        job.trace.splice(i, job.trace.length - i, ...subTrace);
+        mutated = true;
+        break;
+      }
+    }
+
+    if (mutated) {
+      job.recordedAt = new Date().toISOString();
+      fs.writeFileSync(jobPath(name), JSON.stringify(job, null, 2));
+      console.log(`[replay] trace patched after locator miss; saved ${job.trace.length} steps`);
+    } else {
+      console.log(`[replay] completed ${job.trace.length} steps without falling back`);
+    }
+  } finally {
+    await close();
+  }
+}
+
+// Locator: structured-output call, no tools, no loop. One LLM call per ref-bearing step.
+async function locate({ provider, intent, tool, snapshotText }) {
+  const system = 'You map a recorded intent to a ref in a current ARIA snapshot. Reply with strict JSON: {"ref": "<ref>"} if confident, or {"ref": null, "reason": "<why>"} if no element matches. Never invent refs not present in the snapshot.';
+  const user = `Recorded intent: ${intent}\nTool: ${tool}\n\nCurrent snapshot:\n${snapshotText}\n\nReturn JSON only.`;
+  const { text } = await provider.generate({
+    messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+  });
+  try {
+    const match = text.match(/\{[\s\S]*\}/);
+    return JSON.parse(match ? match[0] : text);
+  } catch {
+    return { ref: null, reason: 'unparseable locator response' };
+  }
+}
+
+// Fallback driver: same shape as record(), just used mid-replay when the
+// locator can't resolve a step. Returns the new sub-trace to splice in.
+async function driveFallback({ provider, tools, goal }) {
+  const sub = [];
+  let pendingIntent = '';
+  const loop = new Loop({
+    provider,
+    maxRounds: 10,
+    onText: (text) => { pendingIntent = text; },
+    onToolCall: (toolName, args) => {
+      sub.push({ intent: pendingIntent.trim().slice(0, 500), tool: toolName, args });
+      pendingIntent = '';
+    },
+  });
+  await loop.run([{ role: 'user', content: goal }], tools);
+  return sub;
+}
+
+async function main() {
+  const { mode, name, goal } = parseArgs(process.argv.slice(2));
+  if (!mode || !name) {
+    console.error('Usage:\n  --record <name> "<goal>"\n  --replay <name>');
+    process.exit(1);
+  }
+  if (mode === 'record') {
+    if (!goal) { console.error('record mode requires a goal string'); process.exit(1); }
+    await record({ name, goal });
+  } else {
+    if (!fs.existsSync(jobPath(name))) { console.error(`no job at ${jobPath(name)}`); process.exit(1); }
+    await replay({ name });
+  }
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/examples/wake.md

@@ -0,0 +1,99 @@
+# wake.sh — defer queue runner
+
+`examples/wake.sh` is the reference scheduler that fires bareagent's
+deferred actions. It's not a library primitive — it's a small bash script
+you copy into your project and adapt. Bareagent emits JSONL records via
+the `defer` tool; wake.sh reads the queue and re-invokes bareagent with
+the fired action.
+
+## Installation
+
+```bash
+cp examples/wake.sh /usr/local/bin/bareagent-wake
+chmod +x /usr/local/bin/bareagent-wake
+```
+
+## Cron entry (every minute)
+
+```cron
+* * * * *  /usr/local/bin/bareagent-wake
+```
+
+For project-scoped use, run from the project directory:
+
+```cron
+* * * * *  cd /path/to/your/project && /usr/local/bin/bareagent-wake
+```
+
+## Environment overrides
+
+| Variable | Default | What it does |
+|---|---|---|
+| `BAREAGENT_DEFER_QUEUE` | `./bareagent-defers.jsonl` | Path to the JSONL defer queue (must match what the `defer` tool writes). |
+| `ORCHESTRATOR_CONFIG` | `./orchestrator.json` | Bareagent config file the wake script invokes for fired actions. |
+| `LOCKFILE` | `/tmp/bareagent-wake.lock` | Single-instance lock via `flock`. |
+| `BAREAGENT_WAKE_LOG_DIR` | `/tmp/bareagent-wake` | Per-fired-action log directory. |
+
+## Dependencies
+
+- `jq` — JSONL fold + filter
+- `flock` (Linux util-linux) — single-instance lock
+- `bare-agent` on `$PATH` — `npm install -g bare-agent` or use the full path
+
+## Behaviour
+
+1. **Folds** the queue: `{id, status, ...}` records are append-only; the
+   live status of each id is the *latest* line. jq does the fold.
+2. **Filters** to `status === 'pending' AND when <= now()`.
+3. For each due record: appends `{id, status: 'fired', ts}` (atomic JSONL
+   append on POSIX), then invokes
+   `bare-agent --config $ORCHESTRATOR_CONFIG` with the inner action as
+   stdin input. Bareagent runs the action through bareguard's gate as a
+   fresh action — full pipeline against the inner action, separate audit
+   line.
+4. After the fired invocation completes: appends `{id, status: 'done|failed', ts, exit_code?}`.
+
+## Why bash and not Node
+
+The wake script is OS-level glue — cron + filesystem + subprocess. Keeping
+it as a shell script makes the dependency on bareagent (and only bareagent)
+obvious, and avoids users thinking the script is a library to import.
+
+## Customisation points
+
+- **Different queue path:** set `BAREAGENT_DEFER_QUEUE` and pass the same
+  to your `defer` tool config (or `BAREAGENT_DEFER_QUEUE` env on the
+  bareagent process that emits).
+- **Different orchestrator per action type:** parse `record.action.type`
+  and pick a config file accordingly. ~5 lines added inside the per-record
+  loop.
+- **Different fire-time semantics:** instead of invoking bareagent CLI,
+  shell out to a Node script that wires Loop differently. The defer queue
+  schema doesn't constrain you.
+
+## Log rotation
+
+`logrotate(8)` is the standard answer. Example
+`/etc/logrotate.d/bareagent-wake`:
+
+```
+/tmp/bareagent-wake/*.log {
+    daily
+    rotate 7
+    compress
+    missingok
+    notifempty
+}
+
+/path/to/your/project/bareagent-defers.jsonl {
+    weekly
+    rotate 4
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+`copytruncate` matters for the queue: it preserves the file inode (which
+the defer tool's `appendFile` depends on for atomic POSIX appends).

package/examples/wake.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# examples/wake.sh — reference scheduler for bareagent's defer queue.
+#
+# This is a *reference*, not a primitive. Copy into your project and modify.
+# See examples/wake.md for the cron entry and customization points.
+#
+# What this script does:
+#   1. Reads the JSONL defer queue file.
+#   2. Folds status-update lines per id (latest wins) using jq.
+#   3. For each pending record whose `when` <= now: appends a "fired" status
+#      line to the queue (atomic JSONL append), then invokes
+#      `bareagent --config <orchestrator>` with the inner action as stdin.
+#   4. Uses flock(1) to prevent overlapping wake invocations.
+#
+# The fired action goes through bareguard's gate AGAIN at fire time — full
+# pipeline against the inner action, separate from the emit-time check.
+# (Two gate.check calls, two distinct audit lines, reconstructable via
+# parent_run_id.)
+
+set -euo pipefail
+
+QUEUE="${BAREAGENT_DEFER_QUEUE:-./bareagent-defers.jsonl}"
+ORCHESTRATOR_CONFIG="${ORCHESTRATOR_CONFIG:-./orchestrator.json}"
+LOCKFILE="${LOCKFILE:-/tmp/bareagent-wake.lock}"
+LOG_DIR="${BAREAGENT_WAKE_LOG_DIR:-/tmp/bareagent-wake}"
+
+mkdir -p "$LOG_DIR"
+
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Single-instance: bail if another wake is running.
+exec 9>"$LOCKFILE"
+if ! flock -n 9; then
+  echo "[wake $NOW] another instance running, exiting" >&2
+  exit 0
+fi
+
+# No queue file = nothing to do.
+if [ ! -f "$QUEUE" ]; then
+  exit 0
+fi
+
+# Reconstruct status by folding all lines per id (latest wins) and filter
+# to records whose `when` <= now AND status == "pending". One JSON object
+# per output line.
+PENDING=$(jq -n -c '
+  reduce inputs as $r ({};
+    .[$r.id] |= (. // {}) + $r
+  )
+  | to_entries
+  | map(.value)
+  | map(select(.status == "pending" and .when <= "'"$NOW"'"))
+  | .[]
+' < "$QUEUE")
+
+if [ -z "$PENDING" ]; then
+  exit 0
+fi
+
+echo "$PENDING" | while IFS= read -r record; do
+  [ -z "$record" ] && continue
+
+  ID=$(echo "$record" | jq -r '.id')
+  ACTION=$(echo "$record" | jq -c '.action')
+
+  # Append "fired" status line first (defer queue is append-only).
+  printf '{"id":"%s","status":"fired","ts":"%s"}\n' "$ID" "$NOW" >> "$QUEUE"
+
+  # Invoke bareagent with the deferred action as stdin input.
+  # Run in background — wake script doesn't wait for completion.
+  ( echo "$ACTION" | bare-agent --config "$ORCHESTRATOR_CONFIG" \
+      >> "$LOG_DIR/fired-$ID.log" 2>&1
+    rc=$?
+    if [ $rc -ne 0 ]; then
+      printf '{"id":"%s","status":"failed","ts":"%s","exit_code":%d}\n' \
+        "$ID" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$rc" >> "$QUEUE"
+    else
+      printf '{"id":"%s","status":"done","ts":"%s"}\n' \
+        "$ID" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> "$QUEUE"
+    fi
+  ) &
+done
+
+wait

package/examples/with-bareguard.mjs

@@ -0,0 +1,65 @@
+// examples/with-bareguard.mjs
+//
+// End-to-end: bareagent Loop + bareguard Gate.
+// Runs a small LLM loop with budget cap, fs scope, audit log, and humanChannel.
+//
+// Run:  OPENAI_API_KEY=... node examples/with-bareguard.mjs
+//
+// What this demonstrates:
+//   - Single-gate governance: every tool call traverses gate.check; every
+//     result reaches gate.record (via wrapTools).
+//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop.
+//   - Audit log: one JSONL line per gated event at ./bareagent-audit.jsonl.
+//   - humanChannel: required by bareguard. Here we auto-deny asks; in real use
+//     wire it to a chat platform, terminal prompt, etc.
+
+import { Gate } from 'bareguard';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { Loop, wireGate } = require('bare-agent');
+const { OpenAI } = require('bare-agent/providers');
+const { createShellTools } = require('bare-agent/tools');
+
+// 1. Build the gate. Every primitive is optional with sensible defaults.
+const gate = new Gate({
+  budget: { maxCostUsd: 0.10 },           // hard USD cap
+  limits: { maxTurns: 20 },                // safety net on think/act cycles
+  fs:     { readScope: ['/tmp', '~/'] },   // shell_read / shell_grep allowed roots
+  bash:   { allow: ['ls', 'cat', 'echo', 'pwd'] },  // argv[0] allowlist for shell_run
+  audit:  { path: './bareagent-audit.jsonl' },
+  // Required by bareguard: any ask/halt event flows through here.
+  // Auto-deny is the safest default for headless use; in real apps, wire to
+  // a Telegram/Slack/terminal prompt and return { decision: 'allow' | 'deny' }.
+  humanChannel: async (event) => {
+    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying`);
+    return { decision: 'deny' };
+  },
+});
+await gate.init();
+
+// 2. Wire the gate into Loop's policy slot and wrap tools so gate.record fires.
+const { policy, wrapTools } = wireGate(gate);
+
+// 3. Standard bareagent setup.
+const provider = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o-mini',
+});
+const { tools } = createShellTools();
+
+const loop = new Loop({
+  provider,
+  policy,
+  onError: (err, meta) => console.error(`[onError ${meta.source}]`, err.message),
+});
+
+// 4. Run.
+const result = await loop.run(
+  [{ role: 'user', content: 'List the contents of /tmp using shell_run with argv ["ls", "/tmp"].' }],
+  wrapTools(tools),
+);
+
+console.log('---');
+console.log('text:', result.text);
+console.log('cost:', result.cost?.toFixed(6) ?? 'n/a');
+console.log('audit log → ./bareagent-audit.jsonl');

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.1",
+  "version": "0.13.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -9,6 +9,7 @@
     "bin/",
     "tools/",
     "types/",
+    "examples/",
     "LICENSE",
     "NOTICE"
   ],
@@ -90,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",
@@ -98,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[];