bare-agent 0.21.0 → 0.21.1

package/README.md

@@ -94,7 +94,7 @@ 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** (`opts.retrieval`):
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.21.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)
 
@@ -658,7 +658,7 @@ console.log(result.count, result.matchedIds);      // a code-derived count + the
 
 **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.
+**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, {
@@ -668,6 +668,41 @@ const out = await recurse('Audit auth.js, billing.js, gateway.js for authz bugs'
 
 **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
@@ -677,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.21.0",
+  "version": "0.21.1",
   "files": [
     "index.js",
     "index.d.ts",

package/src/recurse.d.ts

@@ -54,6 +54,9 @@ export type RecurseOptions = {
      * (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;
     /**
@@ -267,6 +270,9 @@ export type Slice = {
  *   (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

@@ -78,7 +78,8 @@ function partitionInto(arr, n) {
  * @returns {string}
  */
 function workerPersonaPrefix(persona) {
-  return typeof persona === 'string' && persona.trim() ? persona.trim() + '\n\n' : '';
+  const p = typeof persona === 'string' ? persona.trim() : '';
+  return p ? p + '\n\n' : '';
 }
 
 /**
@@ -140,6 +141,9 @@ function forChild(opts) {
  *   (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,