bare-agent 0.20.0 → 0.21.1

package/README.md

@@ -94,9 +94,16 @@ Every piece works alone — take what you need, ignore the rest. Two axes: **Act
 
 ### Recurse — break a hard task into a tree *(the RLM primitive)*
 
-`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
+`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. Give workers a stance with `opts.persona` (prepended to every worker, carries down the tree, deliberately kept out of the isolated verifier). The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
 
-Over a corpus, context reaches a worker as a **handle routed by question shape**: `'scan'` answers *"how many / all"* by scanning every slice and **code-counting** the matches (the only path that can't silently undercount); `'search'` / `'exact'` are per-query handle tools for needles and rules; `'tools'` offers all three and lets the worker pick per sub-query.
+Over a corpus, context reaches a worker as a **handle routed by question shape** (`opts.retrieval`):
+
+| `retrieval` | Use it for | How |
+|---|---|---|
+| `'scan'` *(default over a corpus)* | "how many / all / count" | scans every slice, LLM-judges each, **code-counts** the union — the only path that can't silently undercount |
+| `'search'` | find a needle (few matches) | litectx `recall` handle tool, embeddings on — **cannot count** |
+| `'exact'` | rule / exact-term match | code-side AND-filter, embeddings off |
+| `'tools'` | mixed task (needle *and* count) | offers all three; the worker picks per sub-query by tool description |
 
 ```js
 const { recurse } = require('bare-agent');

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.20.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
+> v0.21.1 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -34,6 +34,9 @@ Eight entry points:
 | Size a goal before planning (no LLM) | assessComplexity — `needsPlanning` gates a Planner pass |
 | Kill a spawned child that hangs silently | createSpawnTool / spawnChild `{ idleTimeoutMs }` |
 | Execute a step DAG with parallelism | runPlan + executeFn |
+| Decompose a hard task into a verified tree (RLM) | recurse — decompose → fan-out → verify → synthesize in one call (**wire a gate**, cost is open by design) |
+| Count / answer "how many / all" over a corpus, honestly | recurse(task, ctx, `{ corpus, retrieval: 'scan' }`) — scans every slice, CODE-counts |
+| Give recurse workers a persona/role (senior-dev stance) | recurse(task, ctx, `{ persona }`) — prepended to every worker, carries down the tree; not applied to the verifier |
 | Track task state (pending/running/done/failed) | StateMachine |
 | Run agent turns on a schedule (cron, timers) | Scheduler |
 | Require human approval before dangerous actions | Checkpoint |
@@ -599,6 +602,107 @@ const results = await runPlan(steps, async (step) => {
 // results: [{ id: 's1', status: 'done', result: '...' }, { id: 's2', status: 'failed', error: '...' }, ...]
 ```
 
+## Wiring with recurse (RLM — decompose → fan-out → verify → synthesize)
+
+`recurse(task, ctx, opts)` is the **Recursive Language Models** primitive (v0.20.0): one import that decomposes a hard task into fresh-context workers, verifies against a setpoint, and synthesizes one result. It is **thin glue composed around `Loop`/`Planner`/`runPlan`/`Evaluator`/`spawn`** — not a new engine, never imported by `loop.js`. Returns `{ result, verdict, receipts }` on convergence, or `{ incomplete, best, missingSlices, receipts }` on guard exhaustion / a dead worker — **never a fabricated success** (RC-9).
+
+> **⚠️ Cost is open by DESIGN — wire a gate.** `recurse()` adds NO intrinsic total-work cap. On the **Family-A default** (model-driven) a node can spawn up to ~100 children per level, each recursing to `opts.maxDepth` (default 3) — so token/$ spend compounds and is bounded **only by your gate**, not by recurse. A live POC saw a weak model do 40–117 calls in one run. **Always wire bareguard** (`ctx.policy` via `wireGate`) for any non-trivial or untrusted run — it enforces depth/budget/call caps and turns a runaway into a clean `{ incomplete }` (proven: a wired `Gate` cut a 43–117-call runaway to 4–5 calls). The local brake without a gate is `opts.maxDepth: 1` (flat, no nesting). The forced modes (`mode:'fanout'`/`'partition'`) ARE bounded (deterministic count + concurrency cap).
+
+```javascript
+const { recurse, wireGate } = require('bare-agent');
+const { Gate } = require('bareguard');
+
+// ALWAYS run governed for real work — the gate is the total-work bound.
+const gate = new Gate({ budget: { maxCostUsd: 0.50 }, limits: { maxTurns: 30, maxDepth: 3 }, humanChannel: async () => ({ decision: 'deny' }) });
+await gate.init();
+const { policy, onLlmResult } = wireGate(gate);
+
+// ctx = runtime wiring threaded down the whole tree; opts = policy knobs.
+const ctx = { provider, policy, onLlmResult };     // policy + onLlmResult = the gate over every node + the verifier
+const out = await recurse('Audit this 2000-line module for security bugs and rank them', ctx, { maxDepth: 3 });
+
+if (out.incomplete) {
+  console.warn('did not converge:', out.missingSlices, '— best partial:', out.best);  // honest, never a faked pass
+} else {
+  console.log(out.result, out.verdict);            // the synthesized answer + the verifier's gap report
+}
+console.log(out.receipts.spawned.length);          // RC-10 audit tree: parent→child lineage, per-node tokens/verdict
+```
+
+**Control families (how the tree is shaped):**
+
+- **Family A — model-driven (default).** The worker is handed an in-process `spawn_child` tool and *decides* whether to split. `assessComplexity` is a **hint, not a gate** (only `simple → single-shot`, and the non-overridable `critical → force adversarial verify` safety floor). Nothing extra to set.
+- **Family B — forced fan-out (opt-in).** `{ count: N }` → exactly N independent parallel workers via `Planner`→`runPlan`; or `{ mode: 'fanout' }` → count derived from the complexity tier (medium/complex/critical → 2/4/6). Deterministic + concurrency-capped.
+- **`{ mode: 'partition', corpus, workerBudget }`** — data-driven WIDTH: measure the corpus, split into `max(count floor, ⌈size/workerBudget⌉)` parallel scan-workers, union-count. A pre-wave `recurse_partition` policy checkpoint fires before any worker spends.
+
+**Retrieval over a corpus** (`opts.corpus = {id,text}[]` or an async `() => Promise<Slice[]>`, e.g. `litectxCorpus(litectx, {kind})`). Context reaches a worker as a HANDLE routed by question shape:
+
+| `retrieval` | For | Note |
+|---|---|---|
+| `'scan'` *(default when `corpus` present)* | "how many / all / count" | scans every slice, LLM-judges, **CODE-counts** the union — the only path that can't undercount; `window` 8, `passes` 2 |
+| `'search'` | find a needle | litectx `recall` tool (needs `ctx.litectx`), embeddings on — **cannot count** |
+| `'exact'` | rule / exact-term match | code-side AND-filter, embeddings off |
+| `'tools'` | mixed task (needle *and* count) | offers `scan_count` + `search_memory` + `exact_match`; worker picks per sub-query by tool description |
+
+A completeness guard **upgrades** a `'search'` on a "how many / all" ask to `'scan'` (upgrade-only, never a silent downgrade). Aggregation is **always code**, never a model-stated number.
+
+```javascript
+// Honest count over a corpus — scans every slice, code-counts the matches.
+const { result } = await recurse(
+  'How many of these support tickets are billing disputes?',
+  { provider, policy },                            // still wire the gate
+  { corpus: tickets /* {id,text}[] */, retrieval: 'scan' },
+);
+console.log(result.count, result.matchedIds);      // a code-derived count + the ids that back it
+```
+
+**Synthesis (`opts.synthesize`):** a **function** (deterministic code-reduce over child `results` — use for arithmetic/aggregation; LLM arithmetic over partials carried ~10–15% error), or `'concat'` (lossless no-LLM join), or `'merge'` (isolated Loop-driven subjective merge). Default = the parent model's own closing-turn synthesis. **`opts.contract`** = a definition-of-done the verifier grades against (instead of the loose task); **`opts.evaluate`** overrides the verifier. Exported helpers for the per-query face: `buildScanTool`, `buildSearchTool`, `buildExactTool`, `litectxCorpus`.
+
+**Worker persona (`opts.persona`, v0.21.0):** a string PREPENDED to every Family-A worker's system prompt — give workers a stance (`persona: 'You are a senior security engineer; be specific and cite the exact file:line'`). It **augments**, never replaces, the built-in decomposition policy + depth-scrub (those drive the spawn mechanics), and **carries down the whole tree** (a child of a "senior security engineer" is still one). It is deliberately **not** applied to the isolated verifier (that isolation is what defeats self-grading sycophancy) nor the deterministic scan judge. Absent ⇒ the worker prompt is unchanged from pre-0.21. **Security:** treat `persona` like a system prompt — it is prepended ahead of the decomposition policy and can override it for every worker, so pass caller-trusted text only, never untrusted/end-user input.
+
+```javascript
+const out = await recurse('Audit auth.js, billing.js, gateway.js for authz bugs', ctx, {
+  persona: 'You are a blunt senior application-security engineer. Report each finding as file:line + impact + fix.',
+});
+```
+
+**What a delegated child inherits (important — the setpoint is the TOP node's job):** when a worker delegates with `spawn_child`, the child runs a **fresh `recurse`** that inherits `tools`, `synthesize`, `maxDepth`, and `persona` — but the parent's **`contract`/`evaluate` are stripped** (and the forced `count`/`mode` + the corpus `retrieval` knobs). A slice is not graded against the *whole*-task definition-of-done (that verdict is the top node's, and a slice satisfying the whole DoD is the wrong question); only the top `recurse` verifies the synthesized result. The non-overridable `critical → force-verify` safety floor still fires per node (it keys on the task text, not the contract). So: set `contract`/`evaluate` once at the top; they do not — and should not — re-run per intermediate node.
+
+## Wiring with Evaluator + refine (output-side verification)
+
+`Evaluator` is the output-side judge (the mirror of `Planner`): it grades a result against a goal and returns a tri-state `Verdict`. `refine` is the bounded generate → evaluate → regenerate loop. Both compose *around* a Loop — neither lives inside `loop.js`.
+
+```javascript
+const { Evaluator, refine } = require('bare-agent');
+
+const evaluator = new Evaluator({ provider });   // provider REQUIRED for rubric/agentic; predicate needs none
+
+// Three criteria types — pass EXACTLY ONE:
+const v1 = await evaluator.evaluate(goal, result, { predicate: (r) => r.includes('DONE') });       // deterministic, 0 tokens
+const v2 = await evaluator.evaluate(goal, result, { rubric: 'Cites a source for every claim.' });  // isolated adversarial LLM grader
+const v3 = await evaluator.evaluate(goal, url,    { agentic: 'Open the page, click Submit, check the console for errors.' }); // tool-running critic that EXERCISES the artifact
+
+// Verdict: { status: 'satisfied' | 'needs_revision' | 'failed', pass, score, critique, suggestions }
+//   pass = (status === 'satisfied');  needs_revision is retryable;  failed is terminal (stop spending).
+if (!v2.pass) console.log(v2.critique, v2.suggestions);
+```
+
+Key invariants:
+- The **rubric path runs an isolated adversarial grader** — a separate context window with a harsh, independent prompt, never the generator's transcript. That isolation (not a feedback knob) is what defeats the self-evaluation trap; the grader treats the RESULT as untrusted DATA (judge prompt-injection defence).
+- **`agentic`** (the third type) spins up a fresh Loop with scoped tools (set on the Evaluator, or per-call `opts.tools`) that **exercises** the live artifact — clicks, reads console/network — rather than reading text. Each critic round forwards to `onLlmResult`; a governance `HaltError` re-throws clean.
+- **`contract`** (a definition of done) is graded against instead of the loose goal: `evaluate(goal, result, { rubric, contract })`. Judge tokens forward to the gate via `onLlmResult` (`kind:'evaluate'`) so verification spend is visible to the budget.
+
+**`refine`** drives a caller-supplied `attempt`/`evaluate` until a satisfied verdict, a terminal `failed`, or `maxIterations` (the real bound is bareguard maxTurns/budget). It threads the latest `critique` into the next attempt (fresh-feedback, not anchoring on a failed answer) and a shared `contract` to both sides.
+
+```javascript
+const { result, verdict, iterations, history } = await refine({
+  attempt:  ({ critique, contract }) => generate(prompt, { critique, contract }), // critique = null on the first pass
+  evaluate: (result, { contract })   => evaluator.evaluate(goal, result, { rubric, contract }),
+  contract: 'No TODOs; every public fn has a JSDoc; tests pass.',
+  maxIterations: 3,   // hard cap; the REAL bound is the gate
+});
+```
+
 ## Provider options
 
 ```javascript
@@ -608,6 +712,9 @@ new OpenAI({ apiKey, model: 'gpt-4o-mini', baseUrl: 'https://api.openai.com/v1'
 // Anthropic
 new Anthropic({ apiKey, model: 'claude-haiku-4-5-20251001' })
 
+// Gemini (native generateContent — needed for prompt-cache token tiers; the OpenAI-compat endpoint drops them)
+new Gemini({ apiKey, model: 'gemini-2.5-flash', baseUrl: 'https://generativelanguage.googleapis.com/v1beta' })
+
 // Ollama (local, no key needed)
 new Ollama({ model: 'llama3.2', url: 'http://localhost:11434' })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "files": [
     "index.js",
     "index.d.ts",

package/src/recurse.d.ts

@@ -47,6 +47,18 @@ export type RecurseOptions = {
      * and actual depth is always ≤ `limits.maxDepth`.
      */
     maxDepth?: number | undefined;
+    /**
+     * - (Gap 3 / 0.21.0) An optional caller stance PREPENDED to every Family-A worker's
+     * system prompt (e.g. "You are a senior security engineer; …"). It AUGMENTS the built-in decomposition policy +
+     * depth-scrub, never replaces them (that text drives the spawn mechanics), and CARRIES DOWN the whole tree
+     * (preserved by `forChild` — a durable worker stance, unlike the top-only `contract`/`evaluate`). Deliberately
+     * NOT applied to the isolated verifier (would defeat the anti-sycophancy isolation, A1) nor the deterministic
+     * scan judge. Absent/blank ⇒ the worker prompt is byte-identical to pre-0.21 (backward-compatible).
+     * **SECURITY:** this is a PRIVILEGED system-prompt seam — treat `persona` like a system prompt. Do NOT pass
+     * untrusted / end-user-controlled text here; a hostile persona is prepended ahead of the decomposition policy
+     * and can override it (and any safety framing) for every worker in the tree. Caller-trusted input only.
+     */
+    persona?: string | undefined;
     /**
      * - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
      * `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
@@ -252,6 +264,15 @@ export type Slice = {
  * @property {number} [maxDepth=3] - Open topology ceiling (§1): the depth past which the `spawn_child` tool is
  *   no longer offered (`maxDepth=1` ⇒ flat fan-out, no nesting). NOT the safety halt — that is bareguard's,
  *   and actual depth is always ≤ `limits.maxDepth`.
+ * @property {string} [persona] - (Gap 3 / 0.21.0) An optional caller stance PREPENDED to every Family-A worker's
+ *   system prompt (e.g. "You are a senior security engineer; …"). It AUGMENTS the built-in decomposition policy +
+ *   depth-scrub, never replaces them (that text drives the spawn mechanics), and CARRIES DOWN the whole tree
+ *   (preserved by `forChild` — a durable worker stance, unlike the top-only `contract`/`evaluate`). Deliberately
+ *   NOT applied to the isolated verifier (would defeat the anti-sycophancy isolation, A1) nor the deterministic
+ *   scan judge. Absent/blank ⇒ the worker prompt is byte-identical to pre-0.21 (backward-compatible).
+ *   **SECURITY:** this is a PRIVILEGED system-prompt seam — treat `persona` like a system prompt. Do NOT pass
+ *   untrusted / end-user-controlled text here; a hostile persona is prepended ahead of the decomposition policy
+ *   and can override it (and any safety framing) for every worker in the tree. Caller-trusted input only.
  * @property {ToolDef[]} [tools] - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
  *   `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
  * @property {string} [contract] - Definition of done (A3). When present, the verifier grades against THIS,

package/src/recurse.js

@@ -69,6 +69,19 @@ function partitionInto(arr, n) {
   return chunks;
 }
 
+/**
+ * The persona prefix for a worker system prompt (Gap 3 / 0.21.0). A caller-supplied `opts.persona` AUGMENTS the
+ * decomposition policy + scrub (never replaces them — that text drives the spawn mechanics). Returns '' when
+ * absent/blank, so the default worker prompt is byte-identical to pre-0.21 (backward-compatible). Validated live
+ * by `poc/rlm-persona-seam.mjs` (the worker still decomposes, adopts the persona, and carries it to children).
+ * @param {unknown} persona
+ * @returns {string}
+ */
+function workerPersonaPrefix(persona) {
+  const p = typeof persona === 'string' ? persona.trim() : '';
+  return p ? p + '\n\n' : '';
+}
+
 /**
  * The opts a delegated child inherits. Strips the parent's TOP-LEVEL SETPOINT — `contract`/`evaluate` grade
  * the WHOLE task's final answer; a child grading its own slice against the whole definition-of-done is wasted
@@ -78,7 +91,9 @@ function partitionInto(arr, n) {
  * answered over the parent's corpus; a child has its own subtask and must not re-scan the parent's full corpus
  * (that would fan a whole-corpus count out under every child). The `critical → force-verify` SAFETY FLOOR is
  * unaffected — it keys on the task text via `isCritical`, not the contract, so a critical child still
- * self-verifies. Handle tools (`opts.tools`), `synthesize`, and `maxDepth` carry down.
+ * self-verifies. Handle tools (`opts.tools`), `synthesize`, `maxDepth`, and **`persona`** carry down — the
+ * persona is a DURABLE worker stance (a child of a "senior security engineer" is still one), unlike the
+ * top-only `contract`/`evaluate` setpoint. It rides through the `...opts` spread (not in the strip list).
  * @param {RecurseOptions} opts
  * @returns {RecurseOptions}
  */
@@ -120,6 +135,15 @@ function forChild(opts) {
  * @property {number} [maxDepth=3] - Open topology ceiling (§1): the depth past which the `spawn_child` tool is
  *   no longer offered (`maxDepth=1` ⇒ flat fan-out, no nesting). NOT the safety halt — that is bareguard's,
  *   and actual depth is always ≤ `limits.maxDepth`.
+ * @property {string} [persona] - (Gap 3 / 0.21.0) An optional caller stance PREPENDED to every Family-A worker's
+ *   system prompt (e.g. "You are a senior security engineer; …"). It AUGMENTS the built-in decomposition policy +
+ *   depth-scrub, never replaces them (that text drives the spawn mechanics), and CARRIES DOWN the whole tree
+ *   (preserved by `forChild` — a durable worker stance, unlike the top-only `contract`/`evaluate`). Deliberately
+ *   NOT applied to the isolated verifier (would defeat the anti-sycophancy isolation, A1) nor the deterministic
+ *   scan judge. Absent/blank ⇒ the worker prompt is byte-identical to pre-0.21 (backward-compatible).
+ *   **SECURITY:** this is a PRIVILEGED system-prompt seam — treat `persona` like a system prompt. Do NOT pass
+ *   untrusted / end-user-controlled text here; a hostile persona is prepended ahead of the decomposition policy
+ *   and can override it (and any safety framing) for every worker in the tree. Caller-trusted input only.
  * @property {ToolDef[]} [tools] - Handle tools offered to EVERY worker (RC-5 pull-default: litectx
  *   `recall`/`get`, wired at build step 7). Workers query on demand; never the whole corpus.
  * @property {string} [contract] - Definition of done (A3). When present, the verifier grades against THIS,
@@ -312,10 +336,15 @@ async function recurse(task, ctx = {}, opts = {}) {
   // and what makes `maxDepth=1` flat (RC-11): top spawns, children cannot (no nesting).
   const canSpawn = depth < maxDepth && assessment.level !== 'simple';
 
-  // Capability-scrub (NB-4 / RC-12): the worker system prompt is the decomposition policy (NB-5) + a
-  // depth-conservative suffix that nudges deeper workers toward direct action. Tool set is monotone: a
-  // child's tools ⊆ its parent's (same handle tools, spawn dropped at the cap).
-  const system = DECOMPOSITION_POLICY + capabilityScrub(depth, maxDepth);
+  // Capability-scrub (NB-4 / RC-12): the worker system prompt is the OPTIONAL caller persona (`opts.persona`) +
+  // the decomposition policy (NB-5) + a depth-conservative suffix that nudges deeper workers toward direct
+  // action. The persona AUGMENTS, never replaces — the decomposition + scrub text is load-bearing for the spawn
+  // mechanics, so a persona that replaced it would break decomposition (POC `rlm-persona-seam.mjs` validated the
+  // prepend: the worker still decomposes AND adopts the persona). Persona CARRIES DOWN the tree (it is preserved
+  // by `forChild`, unlike contract/evaluate) — a durable worker stance, not a top-only setpoint. It is deliberately
+  // NOT applied to the isolated verifier (that would defeat the anti-sycophancy isolation) nor the scan judge.
+  // Tool set is monotone: a child's tools ⊆ its parent's (same handle tools, spawn dropped at the cap).
+  const system = workerPersonaPrefix(opts.persona) + DECOMPOSITION_POLICY + capabilityScrub(depth, maxDepth);
 
   // Handle tools (RC-5 pull-default) = caller-supplied `opts.tools` + the retrieval handle for `search`/`exact`/
   // `tools` (offered so the Family-A worker pulls context per sub-query, never the whole corpus). `search` needs