bare-agent 0.16.1 → 0.18.0

package/README.md

@@ -17,7 +17,7 @@
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
 </p>
 
-**Agent orchestration in ~2.7K lines of core. One required dep ([bareguard](https://npmjs.com/package/bareguard) ^0.2.0).**
+**Lightweight agent orchestration. One required dep ([bareguard](https://npmjs.com/package/bareguard) ^0.9.0).**
 
 Lightweight enough to understand completely. Complete enough to not reinvent wheels. Not a framework, not 50,000 lines of opinions — just composable building blocks for agents. Single-gate governance via bareguard: every tool call traverses one policy hook, one audit log, one budget cap.
 
@@ -62,38 +62,44 @@ and show me the wiring code.
 
 ## What's inside
 
-Every piece works alone — take what you need, ignore the rest.
+Every piece works alone — take what you need, ignore the rest. Two axes: **Act** (get work done) and **Verify** (check it, keep context clean), with **one gate** over both.
+
+### Act — get work done
 
 | Component | What it does |
 |---|---|
-| **Loop** | Think → act → observe → repeat. Calls any LLM, runs your tools, loops until done, returns estimated USD cost per run. Three opt-in seams hook external libraries in without touching your code: **`policy`** (governance — wire bareguard for one gated chokepoint over every tool call), **`assemble`** (context engineering — recall/compress/trim the window per round; the seam [litectx](https://npmjs.com/package/litectx) plugs into, transcript untouched), and **`trim`** (destructively bound the transcript for unbounded runs, harvesting turns before eviction). Each is a single chokepoint, fail-open, off by default. `onError` + `loop:error` surface every silent failure |
-| **Planner** | Break a goal into a step DAG via LLM. Built-in caching (`cacheTTL`) |
-| **assessComplexity** | Pure-code pre-planner (no LLM): rates a goal `simple`/`medium`/`complex`/`critical` from its text via keyword scoring + a critical safety override. `needsPlanning` gates whether to spend a Planner pass; `critical` flags security/production/compliance work for extra scrutiny. Free, instant, debuggable via `signals` |
-| **runPlan** | Execute steps in parallel waves. Dependency-aware, failure propagation, per-step retry |
-| **Retry** | Exponential/linear backoff with jitter. Respects `err.retryable` |
-| **CircuitBreaker** | Fail fast after N errors. Auto-recovers after cooldown. Per-key isolation |
-| **Fallback** | Try providers in order — if one is down, next one picks up. Transparent to Loop |
-| **Memory** | Persist and search context across turns/sessions through a swappable `Store`. Zero-dep JSON file by default, or mount [litectx](https://npmjs.com/package/litectx) for ranked, graph-aware recall in one line — the host code never changes ([example](examples/litectx-as-store.mjs)). A minimal `SQLite` FTS5 store also ships, though litectx supersedes it for SQLite-backed memory |
-| **StateMachine** | Task lifecycle tracking with event hooks. `pending → running → done / failed / waiting / cancelled` |
-| **Checkpoint** | Human approval gate. You provide the transport — terminal, Telegram, Slack, whatever |
-| **Scheduler** | Cron (`0 9 * * 1-5`) or relative (`2h`, `30m`). Persisted jobs survive restarts |
-| **Stream** | Structured event emitter. Pipe as JSONL, subscribe in-process, or custom transport |
-| **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `CircuitOpenError`, `ValidationError`. Halt decisions (turn cap, budget cap, content rules) come from bareguard, not Loop |
-| **bareguard adapter** | `wireGate(gate)` → `{ policy, onLlmResult, onToolResult, filterTools, formatDeny }`: one-line wiring to bareguard's `Gate`. Routes every LLM + tool result through the gate so budget caps cover token-heavy workloads, drops denied tools before the LLM ever sees them, and turns halts into a clean exit. `require('bare-agent/bareguard')` |
-| **Browsing** | Web navigation, clicking, typing, reading via `barebrowse` (17 tools). Two modes: library tools (inline snapshots, pass to Loop) or CLI session (disk-based snapshots, token-efficient for multi-step flows). Optional `assess` tool (privacy scan) when `wearehere` is installed |
-| **Mobile** | Android + iOS device control via `baremobile`. Same two modes: library tools (`createMobileTools` — action tools auto-return snapshots) or CLI session (`baremobile` CLI — disk-based snapshots) |
-| **Shell** | Cross-platform `shell_read`, `shell_grep`, `shell_run` (argv, no shell), `shell_exec` (raw shell). Pure Node — no `grep`/`rg`/`findstr` dependency. Injection-proof `shell_run` for policy-gated use |
-| **MCP Bridge** | Auto-discover MCP servers from your $HOME/IDE configs (Claude Code, Cursor, …) and expose them as bareagent tools — bulk (`tools`) or token-thrifty meta-tools (`mcp_discover` + `mcp_invoke`) for large catalogs. Same `Loop({ policy })` hook governs MCP and native tools alike. The project-cwd `.mcp.json` is **opt-in** (untrusted-repo safety); vet every server spawn with `confirmServer`; every RPC is time-bounded. Zero deps |
-| **Spawn** | Fork a child bareagent as a specialist agent — LLM-callable (blocks until exit) or a library handle (`wait`, `onLine`, `kill`). The whole family stitches into one audit log + budget; `bareguard ^0.2.0` adds per-family rate + depth caps. `timeoutMs` caps wall-clock, opt-in `idleTimeoutMs` kills a child gone silent (slow-but-working children survive) |
-| **Defer** | Queue a `{action, when}` record for a separate waker (cron / `examples/wake.sh`) to fire later. Governed twice — once when emitted, again when it fires. `bareguard ^0.2.0` adds a family-wide rate cap |
-
-**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely. The OpenAI provider warns if it would send your key over plaintext `http://` to a non-loopback host (use `https`, or drop `apiKey` for keyless local endpoints).
-
-**Tools:** Any function is a tool. REST APIs, MCP servers, CLI commands, shell scripts — if it's a function, it works. Built-in: `barebrowse` for web browsing, `baremobile` for Android + iOS device control (both optional) — library tools for inline results or CLI session mode for token-efficient disk-based snapshots.
-
-**Cross-language:** Runs as a subprocess. Communicate via JSONL on stdin/stdout from Python, Go, Rust, Ruby, Java, or anything that can spawn a process. Ready-made wrappers in [`contrib/`](contrib/README.md).
-
-**Deps:** 1 required (`bareguard ^0.2.0` for governance — single-gate policy + audit + budget + per-family rate caps). Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing), `baremobile` (Android + iOS device control), `wearehere` (privacy assessment via barebrowse).
+| **Loop** | Think → act → observe until done. Any LLM, your tools, per-run cost. Opt-in seams: `policy` (govern), `assemble` (context engineering), `trim` (bound the transcript) |
+| **Planner** | Break a goal into a step DAG. Cached |
+| **assessComplexity** | Rate a goal `simple`→`critical` from its text — no LLM. Gates whether to plan |
+| **runPlan** | Run plan steps in parallel waves. Dependency-aware, per-step retry |
+| **Memory** | Persist + recall across sessions via a swappable `Store` — zero-dep JSON, SQLite, or [litectx](https://npmjs.com/package/litectx) in a one-line swap |
+| **StateMachine** | Task lifecycle: `pending → running → done / failed / waiting / cancelled` |
+| **Scheduler** | Cron or relative triggers. Jobs survive restarts |
+| **Checkpoint** | Human approval gate — bring your own transport |
+| **Spawn** | Fork a child agent. One shared audit log + budget |
+| **Defer** | Queue an action for a waker to fire later. Governed when emitted *and* when it fires |
+| **Retry · CircuitBreaker · Fallback** | Resilience: backoff with jitter, fail-fast, provider failover |
+| **Stream · Errors** | Structured JSONL events; typed error hierarchy |
+| **Browsing · Mobile · Shell** | Hands: web ([barebrowse](https://npmjs.com/package/barebrowse)), Android + iOS ([baremobile](https://npmjs.com/package/baremobile)), cross-platform shell — library tools or token-thrifty CLI sessions |
+| **MCP Bridge** | Auto-discover MCP servers from your IDE configs; expose as tools (bulk or meta-tools) |
+
+### Verify — check the work, keep context clean *(the eval-assist suite)*
+
+| Component | What it does |
+|---|---|
+| **Evaluator + refine** | Judge output by `predicate` (no tokens), `rubric` (an isolated adversarial grader), or `agentic` (a critic that exercises the live artifact). `refine` is the bounded generate→evaluate→regenerate loop |
+| **SkillRegistry** | Surface skills on demand: one meta-tool catalog; activating a skill injects its instructions and unlocks its tools |
+| **stash** | Compact finished work out of the live window (restorable), or auto-fold the middle under token pressure |
+
+**Govern — one gate over both axes.** `wireGate(gate)` routes every LLM + tool call through one bareguard policy + audit + budget. Denied tools never reach the model; halts (turn / budget / content caps) exit cleanly. `require('bare-agent/bareguard')`
+
+**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Gemini (native), Ollama, CLIPipe, Fallback — or bring your own (one `generate` method). All return the same shape; swap freely. Usage including prompt-cache tiers is normalized, so `result.metrics` reports honest cumulative tokens + cost — and `null`, never a silent `0`, for a model it couldn't price.
+
+**Tools:** Any function is a tool — REST, MCP, CLI, shell. Built-in web + mobile (optional).
+
+**Cross-language:** Run as a subprocess; talk JSONL over stdin/stdout from Python, Go, Rust, Ruby, or Java. Wrappers in [`contrib/`](contrib/README.md).
+
+**Deps:** 1 required (`bareguard ^0.9.0`). Optional: `cron-parser`, `better-sqlite3`, `barebrowse`, `baremobile`, `wearehere`.
 
 This table is the map, not the manual — per-component wiring and API detail live in the [Integration Guide](bareagent.context.md) and [Usage Guide](docs/02-features/usage-guide.md).
 

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.16.1 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
+> v0.18.0 | Node.js >= 18 | one required dep (`bareguard ^0.9.0`) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -46,6 +46,10 @@ Eight entry points:
 | Retry individual plan steps | runPlan({ stepRetry }) |
 | Use a CLI tool as an LLM provider | CLIPipe |
 | Health-check provider, store, and tools | Loop.validate() |
+| Verify an agent's output (judge / grade / critic) | Evaluator + refine — `predicate` / `rubric` / `agentic` criteria |
+| Offer skills on demand without bloating context | SkillRegistry — `skill_use` meta-tool + `skills.activeTools` thunk |
+| Keep the context window lean (compact finished sub-tasks) | createStashSkill — register the skill + wire its `trim` into `Loop({ trim })` |
+| Consolidate finished work into durable facts (across runs) | remember — distill harvested spans → write through any `Store` socket |
 | Track cost per run | Automatic — `result.cost` and `loop:done` event |
 | Catch typed errors programmatically | ProviderError, ToolError, TimeoutError, CircuitOpenError |
 | Cache identical planner calls | Planner({ cacheTTL: 60000 }) |
@@ -142,6 +146,61 @@ const loop = new Loop({
 });
 ```
 
+## Wiring with remember (consolidate harvested spans → durable facts)
+
+`remember` is the consolidation pass: it distills the spans `stash` folded out of the live transcript into durable facts and writes them through the **same `Store` socket** Memory uses (`store/search/get/delete`) — so it works with any backend (JsonFile, SQLite, litectx, or your own), with no backend coupling. One cheap LLM pass per span keeps only durable signal (decisions, config, identifiers, stable prefs) and drops chatter, superseded values, and unanswered questions. It composes *around* the Loop — never inside it.
+
+```javascript
+const { remember, Memory } = require('bare-agent');
+const { Anthropic } = require('bare-agent/providers');
+const { JsonFile } = require('bare-agent/stores');
+
+const memory = new Memory({ store: new JsonFile({ path: './facts.json' }) });
+
+// `spans` are the harvested chunks stash evicted (lossless parks), or any finished-work transcript text.
+const { facts } = await remember(spans, {
+  provider: new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-haiku-4-5' }),
+  store: memory,                 // writes each fact as { kind: 'fact', ... } via memory.store()
+  contract: 'only architecture + config decisions count as durable', // optional: steer "durable"
+  ctx,                           // optional: counts each write into result.metrics.memory.facts (disjoint from `stored`)
+  onLlmResult,                   // optional: forward distill-pass usage to a wired bareguard gate
+});
+```
+
+Budget visibility carries through `onLlmResult` (mirror of Evaluator); a governance `HaltError` from the provider propagates clean. Cheap by design — a small model and one pass per span.
+
+**Security:** facts are model output over *untrusted* transcript content written to durable memory. The distiller refuses a direct "record this fact" injection (validated live), but treat recalled facts as untrusted **context**, not authority — gate them like any model output before a privileged action.
+
+## Wiring with Skills + Stash (progressive disclosure + compaction)
+
+Skills are operator-registered `{ name, description, instructions, tools }` bundles surfaced on demand: only a one-liner per skill sits in context until the agent calls `skill_use({ name })`, which injects the skill's instructions and unlocks its (namespaced) tools for the next round. Pass `skills.activeTools` (a bound thunk) as the Loop's `tools` — it is re-evaluated each round, so freshly-unlocked tools appear automatically. The gate still governs every unlocked tool; skills change discovery, not authorization.
+
+The shipped reference skill is **stash** — compaction-first context hygiene. Its `trim` wires into `Loop({ trim })` and folds finished sub-tasks out of the live transcript (restorable), keeping long runs under budget. Pass a litectx instance as `ctx` for lossless verbatim parking + the `ctx.summarize` lossy path; set `compaction.ceilingTokens` to enable automatic token-pressure folding.
+
+```javascript
+const { Loop, SkillRegistry, createStashSkill } = require('bare-agent');
+const { Anthropic } = require('bare-agent/providers');
+
+const { skill, trim } = createStashSkill({
+  // optional auto-compaction: fold the middle when measured input tokens cross 70% of the ceiling
+  compaction: { ceilingTokens: 150000, triggerAt: 0.7, strategy: 'summarize' },
+});
+
+const skills = new SkillRegistry();
+skills.register(skill);                       // catalog now lists "stash" in skill_use's description
+
+const loop = new Loop({
+  provider: new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  trim,                                       // stash's fold runs here, at each round boundary
+});
+
+// Pass the bound thunk as tools; ctx carries litectx (lossless parking + summarizer).
+await loop.run(messages, skills.activeTools, { ctx });
+// The model: skill_use({name:'stash'}) → stash_checkpoint({label}) → …work… → stash_compact({label, reason})
+```
+
+Folds are provider-safe by construction (whole rounds, alternation-preserving note pairs) and confirmed on the real Anthropic wire. Governance, budget visibility (`ctx.summarize` tokens forward to the gate), and `result.metrics.context.compactions` all flow through unchanged.
+
 ## Multi-agent: spawn + defer + wake (v0.9)
 
 Three primitives, no framework. The "always-on" feeling of multi-agent
@@ -257,7 +316,9 @@ $HOME/IDE configs — NOT the project-cwd `./.mcp.json`** (v0.16.1): a checked-i
 config in an untrusted repo would otherwise auto-spawn arbitrary commands. To
 include the project config, pass `createMCPBridge({ includeProjectConfig: true })`,
 or a `confirmServer` hook (which implies it, since the hook vets every command).
-Explicitly-passed `configPaths` are honored verbatim. Pass `confirmServer(name,
+Explicitly-passed `configPaths` are honored verbatim. So you're not left guessing,
+discovery logs a one-line hint (v0.16.2) when a `./.mcp.json` is present but skipped —
+naming the opt-in — rather than silently ignoring it. Pass `confirmServer(name,
 def) => boolean` to approve each server **before its command is spawned** (return
 `false` to skip it; a throw fails closed). When no `confirmServer` is set, the
 bridge still trusts all *discovered* servers and prints a one-time warning naming

package/index.d.ts

@@ -1,6 +1,12 @@
 import { Loop } from "./src/loop";
 import { Planner } from "./src/planner";
+import { Evaluator } from "./src/evaluator";
+import { refine } from "./src/refine";
+import { remember } from "./src/remember";
 import { assessComplexity } from "./src/complexity";
+import { isCritical } from "./src/complexity";
+import { SkillRegistry } from "./src/skills";
+import { createStashSkill } from "./src/stash";
 import { StateMachine } from "./src/state";
 import { Scheduler } from "./src/scheduler";
 import { Checkpoint } from "./src/checkpoint";
@@ -23,4 +29,4 @@ import { TimeoutError } from "./src/errors";
 import { ValidationError } from "./src/errors";
 import { CircuitOpenError } from "./src/errors";
 import { HaltError } from "./src/errors";
-export { Loop, Planner, assessComplexity, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };
+export { Loop, Planner, Evaluator, refine, remember, assessComplexity, isCritical, SkillRegistry, createStashSkill, 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

@@ -2,7 +2,12 @@
 
 const { Loop } = require('./src/loop');
 const { Planner } = require('./src/planner');
-const { assessComplexity } = require('./src/complexity');
+const { Evaluator } = require('./src/evaluator');
+const { refine } = require('./src/refine');
+const { remember } = require('./src/remember');
+const { assessComplexity, isCritical } = require('./src/complexity');
+const { SkillRegistry } = require('./src/skills');
+const { createStashSkill } = require('./src/stash');
 const { StateMachine } = require('./src/state');
 const { Scheduler } = require('./src/scheduler');
 const { Checkpoint } = require('./src/checkpoint');
@@ -26,7 +31,13 @@ const {
 module.exports = {
   Loop,
   Planner,
+  Evaluator,
+  refine,
+  remember,
   assessComplexity,
+  isCritical,
+  SkillRegistry,
+  createStashSkill,
   StateMachine,
   Scheduler,
   Checkpoint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -13,7 +13,7 @@
     "LICENSE",
     "NOTICE"
   ],
-  "description": "Lightweight, composable agent orchestration for autonomous agents. Multi-agent primitives (spawn, defer, MCP meta-tools), single-gate governance via bareguard, cross-platform shell tools, MCP bridge. ~2.7K lines core, one required dep.",
+  "description": "Lightweight, composable agent orchestration for autonomous agents. Multi-agent primitives (spawn, defer, MCP meta-tools), single-gate governance via bareguard, cross-platform shell tools, MCP bridge. Lightweight core, one required dep.",
   "license": "Apache-2.0",
   "author": "hamr0",
   "repository": {
@@ -75,7 +75,7 @@
     "governance"
   ],
   "dependencies": {
-    "bareguard": "^0.4.2"
+    "bareguard": "^0.9.0"
   },
   "optionalDependencies": {
     "barebrowse": "^0.5.0",
@@ -91,7 +91,8 @@
     }
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js",
+    "test": "node --test --test-force-exit test/**/*.test.js",
+    "test:unit": "node --test --test-force-exit \"test/!(integration*|*mcp*|spawn*).test.js\"",
     "typecheck": "tsc --noEmit",
     "prebuild:types": "node scripts/clean-types.js",
     "build:types": "tsc",

package/src/bareguard-adapter.js

@@ -139,18 +139,36 @@ function wireGate(gate, options = {}) {
    * @param {string|null} [arg.model]
    * @param {string|null} [arg.provider]
    * @param {Usage} [arg.usage]
-   * @param {number} [arg.costUsd]
+   * @param {number|null} [arg.costUsd]
+   * @param {('priced'|'unpriced')} [arg.pricing] - The meter's price verdict, forwarded VERBATIM
+   *   (never synthesized here). Absent (older meter) ⇒ forwarded as undefined; bareguard's
+   *   back-compat treats an absent flag as priced, keeping the contract back-compatible.
    * @param {number|null} [arg.durationMs]
    * @param {Ctx} [arg.ctx]
    */
-  const onLlmResult = async ({ model, provider, usage, costUsd, durationMs, ctx }) => {
+  const onLlmResult = async ({ model, provider, usage, costUsd, pricing, durationMs, ctx }) => {
     // LLM rounds bypass actionTranslator — they always use the canonical
     // {type:'llm'} action so budget rules can match without translator collusion.
     await gate.record(
       { type: 'llm', args: { model: model || null, provider: provider || null }, _ctx: ctx ?? null },
       {
-        costUsd: typeof costUsd === 'number' ? costUsd : 0,
-        tokens: (usage?.inputTokens || 0) + (usage?.outputTokens || 0),
+        // Forward costUsd AS-IS — a null (unpriced) cost must NOT coerce to 0 here. Coercing it
+        // tells the gate the round was "free" instead of "couldn't price", so an active
+        // budget.maxCostUsd cap silently accrues zero and never halts — the #3 silent-zero class
+        // (§3.7), reproduced on the adapter.
+        costUsd: costUsd ?? null,
+        // Forward the meter's price verdict VERBATIM — never synthesize it. bareguard treats an
+        // explicit pricing:'unpriced' as the SOLE trigger for the unpriced contract; a null cost
+        // WITHOUT pricing deliberately stays on bareguard's back-compat (?? 0 ⇒ priced) path. loop.js
+        // always sets pricing (loop.js:566), so faithful forwarding arms the contract on every real
+        // round. Manufacturing 'unpriced' from a bare null here would arm cases the gate intentionally
+        // leaves unarmed — the exact mirror of bareguard's budget-pricing round-trip. (§3.8 contract.)
+        pricing,
+        // ALL FOUR token tiers, not just input+output — cache read/creation are real consumed
+        // tokens; omitting them undercounts the gate's token axis on a cached run (L7). The token
+        // axis stays enforceable even when pricing is 'unpriced' — only the cost axis goes unknown.
+        tokens: (usage?.inputTokens || 0) + (usage?.outputTokens || 0)
+              + (usage?.cacheReadTokens || 0) + (usage?.cacheCreationTokens || 0),
         durationMs: durationMs ?? null,
       },
     );

package/src/complexity.d.ts

@@ -29,3 +29,15 @@ export type ComplexityResult = {
  * @returns {ComplexityResult}
  */
 export function assessComplexity(prompt: string): ComplexityResult;
+/**
+ * The durable critical-safety floor, standalone. Returns `true` when a goal touches high-stakes
+ * work (security/production/compliance/financial incidents, or a securing action on a sensitive
+ * domain) — the same deterministic override `assessComplexity` applies, exported on its own so a
+ * consumer can gate extra scrutiny (e.g. the Evaluator's adversarial verification, Feature 1)
+ * WITHOUT pulling in the frozen 3-tier scorer. Deterministic, auditable, testable — not a
+ * capability estimate. Normalizes input (trims, length-caps, lowercases) then applies the override;
+ * non-string / blank input is `false`.
+ * @param {string} prompt - The goal to test.
+ * @returns {boolean}
+ */
+export function isCritical(prompt: string): boolean;

package/src/complexity.js

@@ -16,6 +16,15 @@
  * and two calibrated thresholds. It is a heuristic — transparent and debuggable via `signals`, not
  * a model. On the upstream validation corpus it lands ~89% (the fuller LLM-free original ~95%);
  * the gap is long-tail ambiguity ("add a button" is genuinely context-dependent).
+ *
+ * FROZEN (eval-assist Feature 4, do not re-litigate). The 3-tier scorer is deletable scaffolding —
+ * the exact input-side routing a stronger model does better — so it is kept optional but NOT grown:
+ * **do not extend the keyword lists or add tiers.** The durable half is the deterministic critical
+ * override (`isCritical`), a safety FLOOR for high-stakes work (security/production/compliance/
+ * financial), exported standalone so a consumer can gate adversarial verification on it (the
+ * Evaluator, Feature 1) without the scorer. Adding critical keywords reopens the same treadmill the
+ * scorer froze, so the override list is frozen too. Input-side LLM subgoal-decomposition is a
+ * deliberate NO-BUILD (mechanical anchoring + cascading errors); the Planner is the durable form.
  */
 
 const has = (/** @type {Set<string>} */ words, /** @type {Set<string>} */ set) =>
@@ -35,8 +44,12 @@ const CRIT_ACTIONS = ['fix', 'patch', 'investigate', 'secure', 'protect', 'mitig
 const FINANCIAL = ['payment', 'transaction', 'billing', 'financial'];
 const SECURE_ACTS = ['encrypt', 'secure', 'protect', 'audit'];
 
-/** @param {string} s lowercased prompt */
-function isCritical(s) {
+/**
+ * Internal: the critical override over an already-lowercased string. Public callers use
+ * {@link isCritical}, which normalizes first; `assessComplexity` calls this on its lowered text.
+ * @param {string} s lowercased prompt
+ */
+function isCriticalLower(s) {
   if (hasAny(s, CRIT_INCIDENT) || hasAny(s, CRIT_COMPLIANCE)) return true;
   if (hasAny(s, SEC_CONTEXT) && hasAny(s, CRIT_ACTIONS)) return true;     // e.g. "fix security ..."
   if (hasAny(s, FINANCIAL) && hasAny(s, SECURE_ACTS)) return true;        // e.g. "encrypt payment ..."
@@ -83,7 +96,7 @@ function assessComplexity(prompt) {
   }
   const text = prompt.trim().slice(0, MAX_ASSESS_LEN);
   const lower = text.toLowerCase();
-  if (isCritical(lower)) {
+  if (isCriticalLower(lower)) {
     return { level: 'critical', score: 100, needsPlanning: true, signals: ['critical_override'] };
   }
 
@@ -146,4 +159,20 @@ function assessComplexity(prompt) {
   return { level, score, needsPlanning: level !== 'simple', signals };
 }
 
-module.exports = { assessComplexity };
+/**
+ * The durable critical-safety floor, standalone. Returns `true` when a goal touches high-stakes
+ * work (security/production/compliance/financial incidents, or a securing action on a sensitive
+ * domain) — the same deterministic override `assessComplexity` applies, exported on its own so a
+ * consumer can gate extra scrutiny (e.g. the Evaluator's adversarial verification, Feature 1)
+ * WITHOUT pulling in the frozen 3-tier scorer. Deterministic, auditable, testable — not a
+ * capability estimate. Normalizes input (trims, length-caps, lowercases) then applies the override;
+ * non-string / blank input is `false`.
+ * @param {string} prompt - The goal to test.
+ * @returns {boolean}
+ */
+function isCritical(prompt) {
+  if (typeof prompt !== 'string' || !prompt.trim()) return false;
+  return isCriticalLower(prompt.trim().slice(0, MAX_ASSESS_LEN).toLowerCase());
+}
+
+module.exports = { assessComplexity, isCritical };

package/src/evaluator.d.ts

@@ -0,0 +1,147 @@
+export type Provider = import("../types").Provider;
+export type ToolDef = import("../types").ToolDef;
+/**
+ * The uniform outcome of an evaluation, across every criteria type.
+ *
+ * Tri-state `status` mirrors Anthropic Managed Agents "Outcomes" (`satisfied` /
+ * `needs_revision` / `failed`) — the distinction matters to `refine`: `needs_revision`
+ * is retryable, `failed` is terminal (stop spending). `pass` is derived (`status ===
+ * 'satisfied'`) so a boolean consumer never has to special-case the enum.
+ */
+export type Verdict = {
+    /**
+     * - Tri-state outcome.
+     */
+    status: "satisfied" | "needs_revision" | "failed";
+    /**
+     * - Derived: `status === 'satisfied'`.
+     */
+    pass: boolean;
+    /**
+     * - 0–10 for the rubric path; null for predicate (pass/fail only).
+     */
+    score: number | null;
+    /**
+     * - Why it failed / what to improve. '' when satisfied with no notes.
+     */
+    critique: string;
+    /**
+     * - Concrete fixes (rubric may populate; [] otherwise).
+     */
+    suggestions: string[];
+};
+export type EvaluatorOptions = {
+    /**
+     * - LLM provider — REQUIRED for the rubric and agentic paths; predicate needs none.
+     */
+    provider?: import("../types").Provider | undefined;
+    /**
+     * - Override the adversarial grader system prompt (rubric path).
+     */
+    prompt?: string | undefined;
+    /**
+     * - Override the adversarial tool-running critic system prompt (agentic path).
+     */
+    agenticPrompt?: string | undefined;
+    /**
+     * - The critic's SCOPED functional tools (`barebrowse`/`baremobile`) for the
+     * agentic path — what lets it exercise the live artifact rather than read text. Overridable per call via
+     * `EvaluateOptions.tools`. Ignored by predicate/rubric.
+     */
+    tools?: import("../types").ToolDef[] | undefined;
+};
+export type Criteria = {
+    /**
+     * - Deterministic check, no tokens.
+     */
+    predicate?: ((result: any) => boolean | Promise<boolean>) | undefined;
+    /**
+     * - Natural-language grading criteria an LLM scores. Exactly one of predicate|rubric|agentic.
+     */
+    rubric?: string | undefined;
+    /**
+     * - Instructions for a tool-running critic (D9): how to EXERCISE the live artifact
+     * (open it, click, read console/network) and what would make it fail. Runs an ISOLATED Loop with the scoped
+     * `tools`. The strongest verification — catches what only running the thing reveals. Exactly one of the three.
+     */
+    agentic?: string | undefined;
+    /**
+     * - The shared, authoritative "definition of done" the grader judges against
+     * (A3 / D10). When present it is what success means — not the loose goal. Folded into the rubric/agentic prompt.
+     */
+    contract?: string | undefined;
+};
+export type EvaluateOptions = {
+    /**
+     * - Budget hook.
+     * Judge-call tokens are real spend; forward them to the gate (BA1 lineage) so they count against budget and
+     * are never invisible. For the agentic path EVERY critic round forwards here (re-tagged `kind:'evaluate'`).
+     * A `HaltError` thrown here propagates as a clean governance exit. Wire `wireGate`'s.
+     */
+    onLlmResult?: ((payload: {
+        usage: any;
+        model: string | null;
+        kind: "evaluate";
+    }) => any) | undefined;
+    /**
+     * - Per-call override of the agentic critic's scoped tools (else `EvaluatorOptions.tools`).
+     */
+    tools?: import("../types").ToolDef[] | undefined;
+    /**
+     * - bareguard `policy` forwarded to the agentic critic's Loop — a tool-running
+     * critic MUST be bounded (turn/budget caps come from the gate; the Loop's HARD_ROUND_LIMIT is only a net).
+     */
+    policy?: Function | undefined;
+};
+/**
+ * Output-side judge — the mirror of `Planner` (input-side). Judges whether a result meets a goal, by a
+ * deterministic `predicate`, an LLM `rubric`, or a tool-running `agentic` critic, returning one uniform
+ * `Verdict`. The rubric and agentic paths run an ISOLATED adversarial critic (separate context + independent
+ * system prompt) — that isolation, not a feedback knob, is what defeats the self-evaluation trap. The agentic
+ * path additionally EXERCISES the artifact with scoped tools (it does not read the diff). Composes AROUND a
+ * Loop (never inside `loop.js`).
+ *
+ * Built flagged-and-deletable per D11 — opt-in by import; calibrate the rubric/prompt from execution traces.
+ */
+export class Evaluator {
+    /** @param {EvaluatorOptions} [options] */
+    constructor(options?: EvaluatorOptions);
+    provider: import("../types").Provider | null;
+    prompt: string;
+    agenticPrompt: string;
+    tools: import("../types").ToolDef[];
+    /**
+     * Judge `result` against `goal` by exactly one criteria type.
+     * @param {string} goal - The objective the result is judged against.
+     * @param {any} result - The output under judgment.
+     * @param {Criteria} criteria - Exactly one of `predicate` | `rubric` | `agentic` (none/more-than-one throws).
+     * @param {EvaluateOptions} [opts]
+     * @returns {Promise<Verdict>}
+     * @throws {ValidationError} not-exactly-one criteria supplied, or rubric/agentic requested with no provider.
+     */
+    evaluate(goal: string, result: any, criteria: Criteria, opts?: EvaluateOptions): Promise<Verdict>;
+    /**
+     * Agentic path — run an ISOLATED tool-running critic Loop that exercises the artifact, then parse its
+     * final text into a `Verdict`. Isolation is by construction: a brand-new Loop with its own message array
+     * and the harsh `agenticPrompt` system prompt — a separate context window, never the generator's
+     * transcript (A1/D8). Budget visibility: every critic round forwards to `onLlmResult` (re-tagged
+     * `kind:'evaluate'`). A budget HALT during investigation re-throws as a clean `HaltError` (governance
+     * exit) so `refine` stops spending rather than misreading it as a verdict.
+     * @param {string} goal
+     * @param {any} result
+     * @param {string} instructions - The `agentic` criteria string: how to exercise the artifact.
+     * @param {string|null} contract
+     * @param {EvaluateOptions} opts
+     * @returns {Promise<Verdict>}
+     * @throws {ValidationError} no provider, or the critic loop errored / produced no parseable verdict.
+     * @throws {HaltError} a governance cap halted the critic mid-run.
+     */
+    _evaluateAgentic(goal: string, result: any, instructions: string, contract: string | null, opts: EvaluateOptions): Promise<Verdict>;
+    /**
+     * Defensive JSON parse of a grader response into a `Verdict` (mirrors `Planner._parse`).
+     * @param {string} text
+     * @returns {Verdict}
+     * @throws {ValidationError} when no JSON object can be recovered (a `refine` loop can catch to abort).
+     */
+    _parse(text: string): Verdict;
+}