bare-agent 0.30.0 → 0.32.0

package/src/provider-clipipe.js

@@ -2,6 +2,7 @@
 
 const { spawn } = require('child_process');
 const { ProviderError } = require('./errors');
+const { buildToolSystemPrompt, renderTranscript, resolveToolProtocol, mapClaudeMeta } = require('./provider-clipipe-tools');
 
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -17,6 +18,8 @@ const { ProviderError } = require('./errors');
  * @property {string} [systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
  * @property {(chunk: string) => void} [onChunk] - Called with each stdout chunk as it streams.
  * @property {'claude-json'|((stdout: string) => Partial<GenerateResult>)} [parse] - Opt-in structured-output parser for stdout. Default (unset) returns stdout verbatim as `text` with zero usage (no behavior change). `'claude-json'` is a shipped preset for `claude -p --output-format json`: it maps the CLI's result envelope onto `GenerateResult` (text←`result`, usage←`usage.*`, model←first `modelUsage` key, costUsd←`total_cost_usd`) and throws `ProviderError` on malformed JSON or an error envelope (`is_error`/non-success subtype). A function is the CLI-agnostic escape hatch: it receives trimmed stdout and returns a partial `GenerateResult` (merged over defaults); throw to signal a parse failure.
+ * @property {'claude'} [toolProtocol] - Opt into TOOL MODE (v0.32.0). A subscription CLI is a plain turn-provider with no native tool channel; this enables schema-validated tool EMULATION so a caller's `tools` work over the CLI (letting a Claude/etc. subscription drive an agentic Loop without metered-API spend). When set, ANY `generate(msgs, tools)` call with a non-empty `tools` array auto-uses emulation (the caller's own system stance + a tool manifest + a JSON envelope, parsed back into normalized `toolCalls`); an empty `tools` array is unchanged plain-text. When NOT set, `tools` are IGNORED (plain-text mode, the long-standing behavior — a non-tool-calling CLI can legitimately sit in a Loop that has tools mounted) with a one-time `console.warn` for visibility. Claude-only for now (`'claude'`); the claude-specific flags/schema/parse live in `provider-clipipe-tools.js` so a second CLI slots in behind the same seam. NOTE: tool mode requires a capable model — weak models (e.g. haiku) answer in prose instead of calling tools; see `probeCapability`.
+ * @property {boolean} [probeCapability=true] - (tool mode only) On the first tool-mode `generate`, run ONE cheap upfront probe that asks the model to obtain unknowable info via a tool. If it answers in prose instead of emitting a tool_call, throw a loud `ProviderError` naming the model — FAIL FAST rather than silently degrade mid-run (the weak-model failure mode). Behaviour-based, never a model name-list (a roster goes stale, BA-10). The verdict is cached per instance (one probe per provider, not per turn). Set `false` to skip when the caller already knows the model is capable.
  */
 
 class CLIPipeProvider {
@@ -38,12 +41,23 @@ class CLIPipeProvider {
       throw new Error("[CLIPipeProvider] options.parse must be 'claude-json' or a function");
     }
     this.parse = options.parse || null;
+    // Tool mode (v0.32.0). Resolve the protocol adapter eagerly so an unknown name fails at
+    // construction, not mid-run. `_toolCapability` caches the upfront probe verdict per instance
+    // (null = not yet probed; a Promise while in flight; true once confirmed capable).
+    this.toolProtocol = options.toolProtocol ? resolveToolProtocol(options.toolProtocol) : null;
+    this.probeCapability = options.probeCapability !== false;
+    /** @type {Promise<void>|null} */
+    this._toolCapability = null;
   }
 
   /**
-   * Generate a response by piping messages to the CLI command.
+   * Generate a response by piping messages to the CLI command. With a `toolProtocol` configured and
+   * a non-empty `tools` array, routes to schema-validated tool EMULATION (v0.32.0); otherwise the
+   * plain-text path below (unchanged). Passing `tools` with no `toolProtocol` warns ONCE and ignores
+   * them (a non-tool-calling CLI legitimately coexists in a Loop with tools mounted); the loud
+   * failure for a genuinely tool-incapable model lives in the tool-mode capability probe.
    * @param {Message[]} messages - Conversation messages in OpenAI format.
-   * @param {ToolDef[]} [tools=[]] - Unused (CLI commands don't support tools).
+   * @param {ToolDef[]} [tools=[]] - Caller tools. Honored only in tool mode (`toolProtocol` set).
    * @param {Record<string, any>} [options={}] - Unused.
    * @returns {Promise<GenerateResult>}
    * @throws {Error} `[CLIPipeProvider] failed to spawn "cmd": ...` — when the command cannot be found or executed.
@@ -52,6 +66,24 @@ class CLIPipeProvider {
    * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
    */
   async generate(messages, tools = [], options = {}) {
+    if (Array.isArray(tools) && tools.length > 0) {
+      if (this.toolProtocol) return this._generateWithTools(messages, tools);
+      // No protocol configured → plain-text mode, tools IGNORED — the long-standing behavior, kept
+      // for backward compatibility (a non-tool-calling CLI legitimately coexists in a Loop that has
+      // tools mounted, e.g. via MCP; the Loop's contract lets a provider simply not call them).
+      // A silent ignore is the trap the caller might not notice, so warn ONCE per instance (the
+      // provider-temperature BA-10 pattern) — visible, not fatal. Genuine loud-failure for tool
+      // mode lives in the capability probe, where a weak model that SHOULD call tools cannot.
+      if (!this._warnedNoProtocol) {
+        this._warnedNoProtocol = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[CLIPipeProvider] received tools but no toolProtocol is configured — tools are IGNORED ' +
+          "(plain-text mode). Construct with { toolProtocol: 'claude' } to enable tool emulation.",
+        );
+      }
+    }
+
     /** @type {string[]} */
     let extraArgs = [];
     let promptMessages = messages;
@@ -85,6 +117,82 @@ class CLIPipeProvider {
     };
   }
 
+  /**
+   * Tool mode (v0.32.0) — one turn of schema-validated tool emulation. Renders the Loop's
+   * OpenAI-shaped transcript to text, injects the caller's system stance + a tool manifest + the
+   * envelope contract, spawns the CLI under the protocol's flags, and parses the envelope back into
+   * normalized `toolCalls` (a `tool_call`) or `text` (a `final_answer`). The Loop drives the cycle.
+   * @param {Message[]} messages
+   * @param {ToolDef[]} tools
+   * @returns {Promise<GenerateResult>}
+   */
+  async _generateWithTools(messages, tools) {
+    await this._ensureToolCapability();
+    const proto = this.toolProtocol;
+    if (!proto) throw new ProviderError('[CLIPipeProvider] tool mode not configured', /** @type {any} */ ({ status: 0 })); // unreachable: only called from the tools branch
+    const sysMsg = messages.find((m) => m.role === 'system');
+    const systemPrompt = buildToolSystemPrompt(sysMsg && typeof sysMsg.content === 'string' ? sysMsg.content : null, tools);
+    const stdout = await this._spawn(renderTranscript(messages), proto.turnArgs(systemPrompt));
+    const parsed = proto.parseResult(stdout);
+
+    /** @type {GenerateResult} */
+    const result = { text: '', toolCalls: [], usage: parsed.usage, model: parsed.model ?? null };
+    if (Number.isFinite(parsed.costUsd)) result.costUsd = parsed.costUsd;
+    if (parsed.action === 'tool_call') {
+      this._toolCallSeq = (this._toolCallSeq || 0) + 1;
+      result.toolCalls = [{ id: `cli_${this._toolCallSeq}`, name: parsed.toolName || '', arguments: parsed.toolArguments || {} }];
+    } else {
+      result.text = parsed.answer || '';
+    }
+    return result;
+  }
+
+  /**
+   * Run the upfront capability probe ONCE per instance (cached), unless `probeCapability` is off.
+   * A model that answers the probe in prose instead of emitting a tool_call throws a loud
+   * `ProviderError` — fail fast, never silently degrade to a no-tools run mid-conversation.
+   * NOTE: the probe is a single internal CLI turn whose token usage/cost is NOT surfaced to the Loop
+   * (it never flows to `onLlmResult`), so a wired budget gate does not see it — negligible for the
+   * subscription use case this exists for (flat cost, one probe per instance), by design.
+   * @returns {Promise<void>}
+   */
+  _ensureToolCapability() {
+    if (!this.probeCapability) return Promise.resolve();
+    // Cache the in-flight promise so concurrent first-calls share one probe, and a resolved
+    // capable verdict is never re-probed.
+    if (this._toolCapability) return this._toolCapability;
+    const proto = this.toolProtocol;
+    if (!proto) return Promise.resolve(); // unreachable: only called from the tools branch
+    this._toolCapability = (async () => {
+      const stdout = await this._spawn(proto.probe.user, proto.turnArgs(proto.probe.system));
+      let parsed;
+      try {
+        parsed = proto.parseResult(stdout);
+      } catch (err) {
+        // A malformed probe response is itself an incapability signal — name it as such.
+        this._toolCapability = null; // allow a retry on a transient parse failure
+        throw new ProviderError(`[CLIPipeProvider] tool-mode capability probe failed to parse: ${/** @type {Error} */ (err).message}`, /** @type {any} */ ({ status: 0 }));
+      }
+      if (!proto.probe.isCapable(parsed)) {
+        const model = this._modelFromArgs();
+        throw new ProviderError(
+          `[CLIPipeProvider] the CLI model${model ? ` '${model}'` : ''} is not capable of tool use: the ` +
+          'capability probe answered in prose instead of emitting a tool_call. Weak models (e.g. haiku) ' +
+          'cannot drive tool emulation reliably — use a stronger model for tool mode, or run without ' +
+          'tools for plain-text. (Set { probeCapability: false } to skip this check.)',
+          /** @type {any} */ ({ status: 0 }),
+        );
+      }
+    })();
+    return this._toolCapability;
+  }
+
+  /** Best-effort model id from `--model X` in the base args, for a clearer probe-failure message. */
+  _modelFromArgs() {
+    const i = this.args.indexOf('--model');
+    return i >= 0 && i + 1 < this.args.length ? this.args[i + 1] : null;
+  }
+
   /**
    * Map the `claude -p --output-format json` result envelope onto a normalized GenerateResult.
    * The caller explicitly opted into structured output, so a malformed or error envelope is a LOUD
@@ -109,21 +217,7 @@ class CLIPipeProvider {
       throw new ProviderError(`[CLIPipeProvider] claude CLI reported failure (subtype='${obj.subtype}'): ${detail}`, /** @type {any} */ ({ status: 0 }));
     }
 
-    const u = (obj.usage && typeof obj.usage === 'object') ? obj.usage : {};
-    /** @type {import('../types').Usage} */
-    const usage = {
-      inputTokens: Number(u.input_tokens) || 0,
-      outputTokens: Number(u.output_tokens) || 0,
-    };
-    // Absent cache tiers mean the model didn't cache — omit rather than emit a synthetic 0 (per Usage docs).
-    if (Number.isFinite(u.cache_read_input_tokens)) usage.cacheReadTokens = u.cache_read_input_tokens;
-    if (Number.isFinite(u.cache_creation_input_tokens)) usage.cacheCreationTokens = u.cache_creation_input_tokens;
-
-    // `modelUsage` is an object keyed by model id (e.g. {"claude-opus-4-8[1m]": {...}}) — take the first key.
-    const model = (obj.modelUsage && typeof obj.modelUsage === 'object')
-      ? (Object.keys(obj.modelUsage)[0] ?? null)
-      : null;
-
+    const { usage, model, costUsd } = mapClaudeMeta(obj);
     /** @type {GenerateResult} */
     const result = {
       text: typeof obj.result === 'string' ? obj.result : '',
@@ -131,9 +225,7 @@ class CLIPipeProvider {
       usage,
       model,
     };
-    // The CLI's own price is authoritative (subscription runs report an equivalent cost even at $0
-    // marginal) — feeds bareguard's USD axis with no local rate table. Only a finite number counts.
-    if (Number.isFinite(obj.total_cost_usd)) result.costUsd = obj.total_cost_usd;
+    if (costUsd !== undefined) result.costUsd = costUsd;
     return result;
   }
 

package/src/recurse.d.ts

@@ -107,6 +107,13 @@ export type RecurseOptions = {
      * NEVER a worker side-effect a worker with edit tools could GAME (writing a passing file then returning junk, or
      * editing the failing test itself). A gameable close is the reward-hacking surface every RSI system in the field
      * got bitten by; the loop optimizes against WHATEVER the sensor reads, so keep it outside what the worker can write.
+     * **Broken sensor ≠ failing model (BA-15):** a sensor that THROWS (non-Halt) or returns a MALFORMED verdict
+     * (anything but `{pass: boolean}` or a valid tri-state `status`) is a faulty ARBITER — the loop stops at the
+     * FIRST broken close (never retries against it) and returns a labeled `{incomplete, blocker:'broken-sensor'}`
+     * (+ `receipts.blockerDetail`), with `best` preserving the model's last attempt. A `HaltError` thrown by the
+     * sensor stays a clean governance halt. The sensor's EXECUTION environment is the caller's: run untrusted /
+     * model-generated checks in an isolated child process WITH A TIMEOUT — a sensor that hangs forever hangs the
+     * leaf (no bareguard checkpoint fires between sensor start and return; confirmed by `poc/rlmplans-hung-sensor.mjs`).
      * **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
      * surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
      * STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation
@@ -233,10 +240,29 @@ export type RecurseNode = {
     incomplete: boolean;
     halted: boolean;
     /**
-     * - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
-     * short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
+     * - Set when this node stopped for a specific non-model reason (mirrors
+     * `RecurseResult.blocker`): `'governance-deny'` (BA-11) — its Loop short-circuited a consecutive-policy-deny
+     * spin; `'broken-sensor'` (BA-15) — the caller's `refineLeaf.sensor` threw or returned a malformed verdict;
+     * `'broken-verifier'` (BA-15) — the caller's `opts.evaluate` did (the default Evaluator path is never labeled).
      */
     blocker?: string | undefined;
+    /**
+     * - (BA-15) with a `broken-*` blocker: what the arbiter did (threw with
+     * which message, or which malformed shape it returned) — the actionable half of the label.
+     */
+    blockerDetail?: string | undefined;
+    /**
+     * - (BA-15) a
+     * DESCENDANT's blocker, surfaced here so an aggregating node still reports the fault upward. Deliberately
+     * SEPARATE from this node's own `blocker` (which means "THIS node's arbiter/Loop broke"): stamping a
+     * descendant's label onto every ancestor made the receipts tree accuse nodes whose sensor never ran, and
+     * re-labelled a parent `governance-deny` when only one child was denied. `blockerTask` names the culprit.
+     */
+    blockerFrom?: {
+        blocker: string;
+        blockerDetail?: string;
+        blockerTask?: string;
+    } | undefined;
     /**
      * - The worker Loop's `metrics.tokens`.
      */
@@ -318,8 +344,26 @@ export type RecurseResult = {
      * - Present when `incomplete` for a specific, actionable reason. `'governance-deny'`
      * (BA-11): the worker's Loop short-circuited after N consecutive policy denials rather than burn to the
      * budget cap — the caller can widen scope / re-gate / escalate instead of reading it as a model failure.
+     * `'broken-sensor'` (BA-15): the caller's `refineLeaf.sensor` threw or returned a malformed verdict — the
+     * ARBITER is faulty, not the model; fix the sensor and re-run (`receipts.blockerDetail` says what it did).
+     * `'broken-verifier'` (BA-15): same fault class at the verify slot — the caller's `opts.evaluate` threw
+     * (non-Halt) or returned a malformed verdict; the default Evaluator path is never labeled (its failures are
+     * provider-class faults). For both `broken-*` blockers `best` preserves the model's last non-empty output
+     * (BA-5) — the arbiter broke, so treat it as best-effort work rather than a graded pass.
      */
     blocker?: string | undefined;
+    /**
+     * - (BA-15) with a `broken-*` blocker: what the arbiter did — the
+     * ACTIONABLE half of the label, surfaced on the result (not only in `receipts`) so a caller branching on
+     * `blocker` can report the cause without walking the receipts tree.
+     */
+    blockerDetail?: string | undefined;
+    /**
+     * - (BA-15) when the blocker was INHERITED from a descendant in a nested run:
+     * which sub-task actually broke. Without it a nested failure reports "a sensor broke" with no way to find
+     * which one.
+     */
+    blockerTask?: string | undefined;
     /**
      * - The audit node for this call (RC-10).
      */
@@ -406,6 +450,13 @@ export type Slice = {
  *   NEVER a worker side-effect a worker with edit tools could GAME (writing a passing file then returning junk, or
  *   editing the failing test itself). A gameable close is the reward-hacking surface every RSI system in the field
  *   got bitten by; the loop optimizes against WHATEVER the sensor reads, so keep it outside what the worker can write.
+ *   **Broken sensor ≠ failing model (BA-15):** a sensor that THROWS (non-Halt) or returns a MALFORMED verdict
+ *   (anything but `{pass: boolean}` or a valid tri-state `status`) is a faulty ARBITER — the loop stops at the
+ *   FIRST broken close (never retries against it) and returns a labeled `{incomplete, blocker:'broken-sensor'}`
+ *   (+ `receipts.blockerDetail`), with `best` preserving the model's last attempt. A `HaltError` thrown by the
+ *   sensor stays a clean governance halt. The sensor's EXECUTION environment is the caller's: run untrusted /
+ *   model-generated checks in an isolated child process WITH A TIMEOUT — a sensor that hangs forever hangs the
+ *   leaf (no bareguard checkpoint fires between sensor start and return; confirmed by `poc/rlmplans-hung-sensor.mjs`).
  *   **`rejectedBuffer` (BA-14):** a SkillOpt-shaped rejected-attempt buffer — instead of only the LATEST critique,
  *   surface the model's OWN prior failed attempts verbatim ("you wrote these, they failed X — write something
  *   STRUCTURALLY DIFFERENT"). This is DIRECTED diversity (attack the specific repeated mistake), where escalation
@@ -473,8 +524,17 @@ export type Slice = {
  * @property {Verdict|null} verdict
  * @property {boolean} incomplete
  * @property {boolean} halted
- * @property {string} [blocker] - (BA-11) set to `'governance-deny'` when this node stopped because its Loop
- *   short-circuited a consecutive-policy-deny spin (not a model failure). Mirrors `RecurseResult.blocker`.
+ * @property {string} [blocker] - Set when this node stopped for a specific non-model reason (mirrors
+ *   `RecurseResult.blocker`): `'governance-deny'` (BA-11) — its Loop short-circuited a consecutive-policy-deny
+ *   spin; `'broken-sensor'` (BA-15) — the caller's `refineLeaf.sensor` threw or returned a malformed verdict;
+ *   `'broken-verifier'` (BA-15) — the caller's `opts.evaluate` did (the default Evaluator path is never labeled).
+ * @property {string} [blockerDetail] - (BA-15) with a `broken-*` blocker: what the arbiter did (threw with
+ *   which message, or which malformed shape it returned) — the actionable half of the label.
+ * @property {{blocker: string, blockerDetail?: string, blockerTask?: string}} [blockerFrom] - (BA-15) a
+ *   DESCENDANT's blocker, surfaced here so an aggregating node still reports the fault upward. Deliberately
+ *   SEPARATE from this node's own `blocker` (which means "THIS node's arbiter/Loop broke"): stamping a
+ *   descendant's label onto every ancestor made the receipts tree accuse nodes whose sensor never ran, and
+ *   re-labelled a parent `governance-deny` when only one child was denied. `blockerTask` names the culprit.
  * @property {object|null} tokens - The worker Loop's `metrics.tokens`.
  * @property {{iterations: number, passed: boolean, temperatures: (number|null)[], rejectedBuffer: boolean}} [refineLeaf] - (BA-8) when
  *   this leaf ran as a bounded refine loop: how many attempts it took and whether the deterministic sensor finally
@@ -507,6 +567,18 @@ export type Slice = {
  * @property {string} [blocker] - Present when `incomplete` for a specific, actionable reason. `'governance-deny'`
  *   (BA-11): the worker's Loop short-circuited after N consecutive policy denials rather than burn to the
  *   budget cap — the caller can widen scope / re-gate / escalate instead of reading it as a model failure.
+ *   `'broken-sensor'` (BA-15): the caller's `refineLeaf.sensor` threw or returned a malformed verdict — the
+ *   ARBITER is faulty, not the model; fix the sensor and re-run (`receipts.blockerDetail` says what it did).
+ *   `'broken-verifier'` (BA-15): same fault class at the verify slot — the caller's `opts.evaluate` threw
+ *   (non-Halt) or returned a malformed verdict; the default Evaluator path is never labeled (its failures are
+ *   provider-class faults). For both `broken-*` blockers `best` preserves the model's last non-empty output
+ *   (BA-5) — the arbiter broke, so treat it as best-effort work rather than a graded pass.
+ * @property {string} [blockerDetail] - (BA-15) with a `broken-*` blocker: what the arbiter did — the
+ *   ACTIONABLE half of the label, surfaced on the result (not only in `receipts`) so a caller branching on
+ *   `blocker` can report the cause without walking the receipts tree.
+ * @property {string} [blockerTask] - (BA-15) when the blocker was INHERITED from a descendant in a nested run:
+ *   which sub-task actually broke. Without it a nested failure reports "a sensor broke" with no way to find
+ *   which one.
  * @property {RecurseNode} receipts - The audit node for this call (RC-10).
  */
 /**