bare-agent 0.16.2 → 0.19.0

package/src/loop.js

@@ -7,6 +7,7 @@ const { ToolError, HaltError } = require('./errors');
 /** @typedef {import('../types').ToolDef} ToolDef */
 /** @typedef {import('../types').ToolCall} ToolCall */
 /** @typedef {import('../types').Usage} Usage */
+/** @typedef {import('../types').RunMetrics} RunMetrics */
 /** @typedef {import('../types').GenerateResult} GenerateResult */
 /** @typedef {import('../types').Store} Store */
 /** @typedef {import('./checkpoint').Checkpoint} Checkpoint */
@@ -52,24 +53,36 @@ const { ToolError, HaltError } = require('./errors');
  */
 
 // Average pricing per 1K tokens (USD). Adjust these to match your provider's rates.
-// Last updated: 2026-05-18. Source: public provider pricing pages.
-/** @type {Record<string, {in: number, out: number}>} */
+// Last updated: 2026-06-22. Source: public provider pricing pages (Anthropic rates + cache multipliers
+// cross-checked against the claude-api reference). Rates are USD per 1K tokens. `cacheReadMult` /
+// `cacheWriteMult` are multipliers ON the input rate for the two cache tiers (see estimateCost); when
+// omitted they default to Anthropic's convention (read 0.1×, write 1.25×). OpenAI/Gemini have no
+// cache-WRITE surcharge (their providers report cacheCreationTokens=0), so only cacheReadMult matters
+// there. NOTE: OpenAI's cached discount is ~0.5× on the 4o family; some newer models (4.1/o-series) are
+// ~0.25× — set to 0.5× here as the documented general value; refine per-model against current pricing.
+/** @type {Record<string, {in: number, out: number, cacheReadMult?: number, cacheWriteMult?: number}>} */
 const COST_PER_1K = {
-  // OpenAI
-  'gpt-4o': { in: 0.0025, out: 0.01 },
-  'gpt-4o-mini': { in: 0.00015, out: 0.0006 },
-  'gpt-4.1': { in: 0.002, out: 0.008 },
-  'gpt-4.1-mini': { in: 0.0004, out: 0.0016 },
-  'gpt-4.1-nano': { in: 0.0001, out: 0.0004 },
-  'o3-mini': { in: 0.0011, out: 0.0044 },
-  // Anthropic — Claude 4.x current generation (2026-05)
-  'claude-opus-4-7': { in: 0.015, out: 0.075 },
+  // OpenAI — cached input ~0.5× (no write tier)
+  'gpt-4o': { in: 0.0025, out: 0.01, cacheReadMult: 0.5 },
+  'gpt-4o-mini': { in: 0.00015, out: 0.0006, cacheReadMult: 0.5 },
+  'gpt-4.1': { in: 0.002, out: 0.008, cacheReadMult: 0.5 },
+  'gpt-4.1-mini': { in: 0.0004, out: 0.0016, cacheReadMult: 0.5 },
+  'gpt-4.1-nano': { in: 0.0001, out: 0.0004, cacheReadMult: 0.5 },
+  'o3-mini': { in: 0.0011, out: 0.0044, cacheReadMult: 0.5 },
+  // Anthropic — Claude current generation (2026-06). Cache tiers use the default 0.1×/1.25×.
+  'claude-fable-5': { in: 0.01, out: 0.05 },
+  'claude-opus-4-8': { in: 0.005, out: 0.025 },
+  'claude-opus-4-7': { in: 0.005, out: 0.025 },
+  'claude-opus-4-6': { in: 0.005, out: 0.025 },
   'claude-sonnet-4-6': { in: 0.003, out: 0.015 },
-  'claude-haiku-4-5-20251001': { in: 0.0008, out: 0.004 },
-  'claude-haiku-4-5': { in: 0.0008, out: 0.004 },
-  // Anthropic — earlier 4.x snapshots
+  'claude-haiku-4-5-20251001': { in: 0.001, out: 0.005 },
+  'claude-haiku-4-5': { in: 0.001, out: 0.005 },
+  // Anthropic — earlier snapshots (the original Opus 4 / Sonnet 4 generation, genuinely different rates)
   'claude-sonnet-4-20250514': { in: 0.003, out: 0.015 },
   'claude-opus-4-20250514': { in: 0.015, out: 0.075 },
+  // Google Gemini — cached content ~0.25× (no write tier). Native provider lands in a following piece.
+  'gemini-2.5-flash': { in: 0.0003, out: 0.0025, cacheReadMult: 0.25 },
+  'gemini-2.5-pro': { in: 0.00125, out: 0.01, cacheReadMult: 0.25 },
   // Fallback average across popular models (~$0.002 in, ~$0.008 out per 1K)
   '_default': { in: 0.002, out: 0.008 },
 };
@@ -105,6 +118,11 @@ function sealDanglingToolCalls(msgs, rule) {
 }
 
 /**
+ * Estimate the USD cost of one round's usage, pricing the FOUR token tiers separately (D9/L7):
+ * uncached input, output, cache-read, and cache-creation. Folding cache tokens into the full input
+ * rate mis-prices badly — a warm prompt is mostly cache-read (~0.1–0.5× input) and Anthropic's
+ * cache-creation is a ~1.25× premium — so each tier gets its own rate. Returns null (not 0) when the
+ * model is unknown/absent so the caller can mark the round `unpriced` rather than silently free.
  * @param {string|null} model
  * @param {Usage|null} usage
  * @returns {number|null}
@@ -112,10 +130,20 @@ function sealDanglingToolCalls(msgs, rule) {
 function estimateCost(model, usage) {
   if (!usage || !model) return null;
   const rates = COST_PER_1K[model] || COST_PER_1K['_default'];
-  return (
-    ((usage.inputTokens || 0) * rates.in +
-      (usage.outputTokens || 0) * rates.out) / 1000
-  );
+  const readMult = rates.cacheReadMult ?? 0.1;    // Anthropic convention when unspecified
+  const writeMult = rates.cacheWriteMult ?? 1.25;
+  const cost = (
+    (usage.inputTokens || 0) * rates.in +
+    (usage.outputTokens || 0) * rates.out +
+    (usage.cacheReadTokens || 0) * rates.in * readMult +
+    (usage.cacheCreationTokens || 0) * rates.in * writeMult
+  ) / 1000;
+  // A non-finite cost (±Infinity from runaway token counts, NaN from a garbage rate-table entry) is a
+  // COULDN'T-PRICE, not a price. Return null so the round is marked `unpriced` and the value never
+  // poisons `totalCost`, `result.metrics.costUsd`, or — via onLlmResult → the gate — `spentUsd`. The
+  // last is the dangerous one: `NaN >= cap` is false, which would DISABLE a budget cap, not just
+  // under-count it. Same silent-unenforceable class as a null model (§3.7).
+  return Number.isFinite(cost) ? cost : null;
 }
 
 // R-C6: default instruction for the provider-bound `ctx.summarize` lent to the assemble seam.
@@ -262,9 +290,11 @@ class Loop {
   /**
    * Run the think/act/observe loop.
    * @param {Message[]} messages - Conversation messages in OpenAI format.
-   * @param {ToolDef[]} [tools=[]] - Tool definitions with name, execute, description, parameters.
+   * @param {ToolDef[] | (() => ToolDef[])} [tools=[]] - Tool definitions, or a thunk returning them. A
+   *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
+   *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
    * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, msgs: Message[]}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, msgs: Message[], metrics: RunMetrics}>}
    *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
    *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
    *   dangling assistant `tool_calls` from the halted round are paired with
@@ -281,29 +311,118 @@ class Loop {
     const msgs = system
       ? [{ role: 'system', content: system }, ...messages]
       : [...messages];
-    const toolMap = new Map(tools.map(t => [t.name, t]));
-
-    // Validate tools at wire time
-    for (const tool of tools) {
-      if (typeof tool.name !== 'string' || !tool.name) {
-        throw new Error(`[Loop] Tool is missing a name (got ${JSON.stringify(tool.name)}). Every tool must have a non-empty string name.`);
-      }
-      if (typeof tool.execute !== 'function') {
-        throw new Error(`[Loop] Tool "${tool.name}" is missing an execute() function.`);
+    // D4 (eval-assist F2): `tools` may be a `() => ToolDef[]` thunk, re-evaluated each round so a set that
+    // grows mid-run (e.g. a skill unlocking its tools via skill_use last round) is offered to the model on
+    // the NEXT round's generate(). Loop stays skill-agnostic — it only gains the general tools-as-thunk
+    // capability, the same independence as the assemble/trim seams. A static array keeps today's exact
+    // behavior (resolved once at wire time, never changes).
+    const toolsThunk = typeof tools === 'function' ? tools : null;
+    const resolveTools = () => {
+      const list = toolsThunk ? toolsThunk() : tools;
+      if (!Array.isArray(list)) {
+        throw new Error(`[Loop] tools must be an array of ToolDef or a () => ToolDef[] thunk returning one, got ${typeof list}.`);
       }
-      if (tool.description !== undefined && typeof tool.description !== 'string') {
-        console.warn(`[Loop] Tool "${tool.name}" has a non-string description — providers may ignore it.`);
-      }
-      if (tool.parameters !== undefined && (typeof tool.parameters !== 'object' || tool.parameters === null)) {
-        throw new Error(`[Loop] Tool "${tool.name}" has invalid parameters — expected an object, got ${typeof tool.parameters}.`);
+      return list;
+    };
+    // A non-string description is a soft warning, not a throw — but validateTools re-runs every round for a
+    // thunk, so dedup the warning by tool name to avoid per-round log spam (warn once per offending tool/run).
+    const warnedBadDesc = new Set();
+    /** Validate a resolved tool list — wire-time contract, re-checked each round for thunks. @param {ToolDef[]} list */
+    const validateTools = (list) => {
+      for (const tool of list) {
+        if (typeof tool.name !== 'string' || !tool.name) {
+          throw new Error(`[Loop] Tool is missing a name (got ${JSON.stringify(tool.name)}). Every tool must have a non-empty string name.`);
+        }
+        if (typeof tool.execute !== 'function') {
+          throw new Error(`[Loop] Tool "${tool.name}" is missing an execute() function.`);
+        }
+        if (tool.description !== undefined && typeof tool.description !== 'string' && !warnedBadDesc.has(tool.name)) {
+          warnedBadDesc.add(tool.name);
+          console.warn(`[Loop] Tool "${tool.name}" has a non-string description — providers may ignore it.`);
+        }
+        if (tool.parameters !== undefined && (typeof tool.parameters !== 'object' || tool.parameters === null)) {
+          throw new Error(`[Loop] Tool "${tool.name}" has invalid parameters — expected an object, got ${typeof tool.parameters}.`);
+        }
       }
-    }
+    };
+
+    // Resolve + validate once at wire time (this throws for a misconfigured static array OR thunk —
+    // fail-fast on setup). Per-round re-resolution for thunks happens at the top of the loop below.
+    let activeTools = resolveTools();
+    validateTools(activeTools);
+    let toolMap = new Map(activeTools.map(t => [t.name, t]));
 
     this._safeEmit({ type: 'loop:start', data: { messageCount: msgs.length } });
 
     let lastUsage = { inputTokens: 0, outputTokens: 0 };
     let totalCost = 0;
 
+    // The meter (Feature 3): bareagent is the canonical run counter. Accumulates across rounds and is
+    // returned as `result.metrics`. `tokens` is CUMULATIVE over all four tiers (fixes the last-round-only
+    // `result.usage` bug — result.usage stays last-round for back-compat; metrics.tokens is the run total).
+    // `costUsd` is the priced cumulative (null only if NOTHING could be priced — the explicit-unknown
+    // signal, distinct from a genuine 0); `unpricedRounds` makes an unenforceable-on-budget run visible.
+    const meterStartedAt = Date.now();
+    let pricedAny = false;
+    const metrics = {
+      turns: 0,
+      toolCalls: 0,
+      /** @type {Record<string, number>} */
+      byTool: {},
+      tokens: { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 },
+      unpricedRounds: 0,
+      // §3.6 CE-activity rollup — convenience counts derived in-place from the same events already
+      // on the Stream (loop:trim, loop:summarize), not a second source. `compactions` counts
+      // destructive trim evictions; `summaries` counts ctx.summarize calls; `tokensTrimmed` is an
+      // APPROXIMATE (~4 chars/token) count of tokens evicted from the canonical transcript — evicted
+      // spans have no exact provider count, so we estimate rather than emit a silent zero (§3.10).
+      context: { compactions: 0, summaries: 0, tokensTrimmed: 0 },
+      // §3.6 memory footprint — the ops bareagent INITIATES, reported via the loop-lent `ctx.recordMemoryOp`
+      // hook (channel A: the originating module announces; the loop counts + emits `loop:memory`). Bounded
+      // PER RUN by construction: the hook is re-attached each loop.run() and closes over THIS run's meter,
+      // and result.metrics is a copy taken at run end. `stashed`/`episodes` flow through the stash fold;
+      // The Memory wrapper is metered on BOTH sides, symmetrically and opt-in: `recalls` (Memory.search,
+      // the read) and `stored` (Memory.store, the generic durable write). The caller threads the run's ctx so
+      // the op counts against that run (a session-scoped LiteCtx → bounded to that session). `facts` now has its
+      // writer: `remember` (src/remember.js, the consolidation pass) distills durable facts and announces each via
+      // recordMemoryOp('facts'). It is DISJOINT from `stored` (remember writes through the socket WITHOUT ctx, so a
+      // distilled fact counts once, as a fact). litectx's own episode→fact promotion stays litectx-internal to
+      // surface (recentActivity/promotionCandidates) — that is NOT this counter.
+      memory: { stashed: 0, episodes: 0, recalls: 0, stored: 0, facts: 0 },
+    };
+    /** Accumulate one usage object into the cumulative token tiers. @param {Usage|null|undefined} u */
+    const addUsage = (u) => {
+      if (!u) return;
+      metrics.tokens.input += u.inputTokens || 0;
+      metrics.tokens.output += u.outputTokens || 0;
+      metrics.tokens.cacheCreation += u.cacheCreationTokens || 0;
+      metrics.tokens.cacheRead += u.cacheReadTokens || 0;
+    };
+    /** Snapshot the meter for a return — finalizes the run-scoped fields. @returns {RunMetrics} */
+    const finalizeMetrics = () => ({
+      turns: metrics.turns,
+      toolCalls: metrics.toolCalls,
+      byTool: metrics.byTool,
+      tokens: { ...metrics.tokens },
+      costUsd: pricedAny ? totalCost : null,
+      unpricedRounds: metrics.unpricedRounds,
+      spawned: metrics.byTool.spawn || 0, // §3.6 — spawn-tool invocations (byTool counts every call, incl. denied)
+      context: { ...metrics.context }, // §3.6 CE-activity rollup
+      memory: { ...metrics.memory }, // §3.6 memory footprint (stashed/episodes/recalls/stored/facts; see init note)
+      durationMs: Date.now() - meterStartedAt,
+    });
+    // Approximate token count of a message array (~4 chars/token over the stringified message).
+    // Used ONLY for the observability rollup metrics.context.tokensTrimmed — NEVER for pricing or
+    // governance, which use exact provider counts. A deliberate estimate (§3.10): the trim event
+    // carries message COUNTS and evicted spans have no exact provider token count.
+    /** @param {any[]} arr @returns {number} */
+    const estimateTokens = (arr) => {
+      if (!Array.isArray(arr)) return 0;
+      let chars = 0;
+      for (const m of arr) { try { chars += JSON.stringify(m).length; } catch { /* unstringifiable — skip */ } }
+      return Math.ceil(chars / 4);
+    };
+
     // R-C6: lend a provider-bound summarizer to the assemble seam via `ctx.summarize`. litectx owns
     // the trigger/N/splice (its restorable COMPRESS path keeps summarized turns recoverable by id);
     // bareagent lends ONLY the single model call. Attached NON-ENUMERABLE so it never shows up in the
@@ -333,7 +452,9 @@ class Loop {
         const usage = (result && result.usage) || null;
         const model = (result && result.model) || loop.provider.model || null;
         const cost = estimateCost(model, usage);
-        if (cost !== null) totalCost += cost;
+        if (cost !== null) { totalCost += cost; pricedAny = true; }
+        addUsage(usage); // summarize tokens are real spend → count them in the cumulative meter
+        metrics.context.summaries++; // §3.6 CE-activity rollup
         loop._safeEmit({ type: 'loop:summarize', data: { usage, costUsd: cost, durationMs: Date.now() - startedAt } });
         if (loop.onLlmResult) {
           try {
@@ -342,6 +463,7 @@ class Loop {
               provider: loop.provider.name || null,
               usage,
               costUsd: cost,
+              pricing: cost === null ? 'unpriced' : 'priced',
               durationMs: Date.now() - startedAt,
               ctx,
               kind: 'summarize',
@@ -361,12 +483,46 @@ class Loop {
       } catch (err) {
         this._reportError('summarize-attach', err);
       }
+      // §3.6 memory footprint (channel A). Lend a recorder the originating module calls when it
+      // initiates a memory op (stash.js at a lossless park → 'stashed'; at an episode write → 'episodes').
+      // The loop owns the count + the Stream emit; the module stays Loop-agnostic (it just calls an
+      // optional ctx hook, exactly like ctx.summarize). Non-enumerable so it never leaks into the
+      // assemble(units, ctx) identity contract. Unknown kinds are ignored (forward-compatible).
+      const recordMemoryOp = (/** @type {string} */ kind) => {
+        if (Object.prototype.hasOwnProperty.call(metrics.memory, kind)) {
+          metrics.memory[kind]++;
+          loop._safeEmit({ type: 'loop:memory', data: { op: kind } });
+        }
+      };
+      try {
+        Object.defineProperty(ctx, 'recordMemoryOp', { value: recordMemoryOp, enumerable: false, configurable: true, writable: true });
+      } catch (err) {
+        this._reportError('recordMemoryOp-attach', err);
+      }
     }
 
     try {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
 
+      // D4: re-evaluate the tools thunk for THIS round, so a tool unlocked last round (e.g. by skill_use)
+      // is now offered to the model. Static arrays skip this (toolsThunk === null) and keep their wire-time
+      // set. Round 0 also skips — the wire-time resolution above already produced its set, so the thunk is
+      // called exactly once per round, never twice for round 0. Fail-OPEN like the assemble/trim seams: a
+      // thunk fault degrades to the previous round's set (a tool-discovery bug must not halt the agent); a
+      // HaltError is a governance exit and propagates.
+      if (toolsThunk && round > 0) {
+        try {
+          const next = resolveTools();
+          validateTools(next);
+          activeTools = next;
+          toolMap = new Map(activeTools.map(t => [t.name, t]));
+        } catch (err) {
+          if (err instanceof HaltError) throw err;
+          this._reportError('tools', err, { round });
+        }
+      }
+
       // RT-2: destructive transcript-trim chokepoint — bound the canonical transcript before assembling
       // the window. Runs BEFORE assemble (trim shrinks canonical; assemble shapes the per-call view of
       // what remains). The trimmer harvests every evicted turn BEFORE returning the smaller set, so this
@@ -378,11 +534,17 @@ class Loop {
       if (this.trim) {
         try {
           const before = msgs.length;
+          const beforeTokens = estimateTokens(msgs); // pre-trim estimate (msgs not yet spliced)
           const kept = await this.trim(msgs, ctx);
           if (Array.isArray(kept) && kept !== msgs) {
+            const trimmed = beforeTokens - estimateTokens(kept); // approx tokens evicted from the transcript
             msgs.length = 0;
             msgs.push(...kept);
-            if (msgs.length !== before) this._safeEmit({ type: 'loop:trim', data: { round, before, after: msgs.length } });
+            if (msgs.length !== before) {
+              metrics.context.compactions++;
+              if (trimmed > 0) metrics.context.tokensTrimmed += trimmed;
+              this._safeEmit({ type: 'loop:trim', data: { round, before, after: msgs.length, tokensTrimmed: trimmed > 0 ? trimmed : 0 } });
+            }
           }
         } catch (err) {
           if (err instanceof HaltError) throw err;
@@ -412,21 +574,36 @@ class Loop {
       let result;
       const llmStartedAt = Date.now();
       try {
-        const generate = () => this.provider.generate(toSend, tools, options);
+        const generate = () => this.provider.generate(toSend, activeTools, options);
         result = this.retry ? await this.retry.call(generate) : await generate();
       } catch (err) {
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
-        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, msgs };
+        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, msgs, metrics: finalizeMetrics() };
       }
 
       lastUsage = result.usage || lastUsage;
+      // Publish the latest measured usage to ctx (non-enumerable, fail-open) so a transcript-bound seam —
+      // e.g. F2 stash auto-compaction — can read EXACT provider-counted `inputTokens` to gauge context
+      // pressure on the NEXT round's trim. Symmetric with lending ctx.summarize; the Loop stays unaware of
+      // the consumer. A frozen/sealed ctx simply doesn't get it (reported, never fatal).
+      if (ctx && typeof ctx === 'object') {
+        try { Object.defineProperty(ctx, 'usage', { value: lastUsage, enumerable: false, configurable: true, writable: true }); }
+        catch (err) { this._reportError('usage-attach', err); }
+      }
       // Prefer the model the response reports (robust when provider.model is absent or varies per
       // response — e.g. FallbackProvider, or a CircuitBreaker-wrapped provider that drops .model).
       const model = result.model || this.provider.model || null;
       const roundCost = estimateCost(model, lastUsage);
       if (roundCost !== null) totalCost += roundCost;
 
+      // Meter this round: count the turn, accumulate the four token tiers, and classify pricing —
+      // an unpriced round (null cost: no model / no rate) is tallied so the run is observably
+      // unenforceable on budget rather than silently free (the #3 cost contract).
+      metrics.turns++;
+      addUsage(result.usage);
+      if (roundCost === null) metrics.unpricedRounds++; else pricedAny = true;
+
       // BA1: forward LLM usage to gate.record (via wireGate) so budget.maxCostUsd
       // covers token-heavy / tool-light workloads. Callback errors route through
       // _reportError but never kill the loop — governance failure ≠ run failure.
@@ -437,6 +614,9 @@ class Loop {
             provider: this.provider.name || null,
             usage: result.usage || null,
             costUsd: roundCost,
+            // Priced vs unpriced is explicit so the gate never mistakes "couldn't price" (null) for
+            // "free" (0) — the silent-zero that made #3's budget cap a no-op. (D5 / §3.7.)
+            pricing: roundCost === null ? 'unpriced' : 'priced',
             durationMs: Date.now() - llmStartedAt,
             ctx,
             kind: 'turn',
@@ -462,7 +642,7 @@ class Loop {
           try { await flush(msgs, ctx); }
           catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
         }
-        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs };
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs, metrics: finalizeMetrics() };
       }
 
       // Execute tool calls
@@ -479,6 +659,11 @@ class Loop {
       for (const tc of result.toolCalls) {
         if (this._stopped) break;
 
+        // Meter every tool call the model makes (per-tool tally), regardless of outcome — a denied or
+        // unknown call is still an invocation the operator wants to see.
+        metrics.toolCalls++;
+        metrics.byTool[tc.name] = (metrics.byTool[tc.name] || 0) + 1;
+
         const tool = toolMap.get(tc.name);
         if (!tool) {
           const errMsg = `[Loop] Unknown tool: ${tc.name}`;
@@ -555,6 +740,10 @@ class Loop {
           msgs.push({ role: 'tool', tool_call_id: tc.id, content });
           this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, result: content } });
         } catch (err) {
+          // A HaltError from a tool body is a deliberate governance exit, not a tool failure — re-throw it
+          // like every other seam (the outer catch pairs dangling tool_calls + returns halt cleanly). Ordinary
+          // errors (plain Error) still become a ToolError, preserving the tool-as-untrusted-execution boundary.
+          if (err instanceof HaltError) throw err;
           toolError = err instanceof ToolError ? err : new ToolError(err.message, { context: { tool: tc.name } });
           const errMsg = `[Loop] Tool error: ${toolError.message}`;
           msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
@@ -592,7 +781,7 @@ class Loop {
         sealDanglingToolCalls(msgs, rule);
         this._reportError('halt', err, { rule, reason: err.decision?.reason ?? null });
         this._safeEmit({ type: 'loop:done', data: { text: '', halted: true, rule, cost: totalCost } });
-        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, msgs };
+        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, msgs, metrics: finalizeMetrics() };
       }
       throw err;
     }
@@ -601,7 +790,7 @@ class Loop {
     // limits.maxTurns (or the LLM's natural completion) ends the loop first.
     const warning = `[Loop] hit internal safety limit of ${HARD_ROUND_LIMIT} rounds. Wire bareguard for proper governance — see bare-agent/bareguard.`;
     this._safeEmit({ type: 'loop:done', data: { text: '', warning, cost: totalCost } });
-    return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, msgs };
+    return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, msgs, metrics: finalizeMetrics() };
   }
 
   /**
@@ -674,7 +863,7 @@ class Loop {
    * @param {string} text - User message.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
    * @param {Record<string, any>} [options={}] - Per-run overrides.
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, msgs: Message[]}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, msgs: Message[], metrics: RunMetrics}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });
@@ -691,4 +880,4 @@ class Loop {
   }
 }
 
-module.exports = { Loop };
+module.exports = { Loop, estimateCost, COST_PER_1K };

package/src/memory.d.ts

@@ -27,13 +27,20 @@ export class Memory {
     _store: Store;
     /**
      * @param {any} content
-     * @param {Record<string, any>} [metadata]
+     * @param {Record<string, any>} [metadata] - Stored alongside the content; persisted to the backend.
+     * @param {Record<string, any>} [opts] - Transient call options (NOT persisted). If `opts.ctx` carries a
+     *   Loop-lent `recordMemoryOp` hook, this write is counted against that run's `result.metrics.memory.stored`
+     *   (§3.6, opt-in — the write-side mirror of search's `recalls`). `ctx` rides here, never in `metadata`,
+     *   precisely because `metadata` is persisted. Memory stays Loop-agnostic: it only calls an optional hook.
      * @returns {any} id
      */
-    store(content: any, metadata?: Record<string, any>): any;
+    store(content: any, metadata?: Record<string, any>, opts?: Record<string, any>): any;
     /**
      * @param {string} query
-     * @param {Record<string, any>} [options]
+     * @param {Record<string, any>} [options] - Store search options. If `options.ctx` carries a Loop-lent
+     *   `recordMemoryOp` hook, this recall is counted against that run's `result.metrics.memory.recalls`
+     *   (§3.6, opt-in — the hook is absent unless the caller threads the run's ctx). Memory stays
+     *   Loop-agnostic: it only calls an optional hook, and `ctx` is stripped, never forwarded to the store.
      * @returns {any}
      */
     search(query: string, options?: Record<string, any>): any;

package/src/memory.js

@@ -30,20 +30,31 @@ class Memory {
 
   /**
    * @param {any} content
-   * @param {Record<string, any>} [metadata]
+   * @param {Record<string, any>} [metadata] - Stored alongside the content; persisted to the backend.
+   * @param {Record<string, any>} [opts] - Transient call options (NOT persisted). If `opts.ctx` carries a
+   *   Loop-lent `recordMemoryOp` hook, this write is counted against that run's `result.metrics.memory.stored`
+   *   (§3.6, opt-in — the write-side mirror of search's `recalls`). `ctx` rides here, never in `metadata`,
+   *   precisely because `metadata` is persisted. Memory stays Loop-agnostic: it only calls an optional hook.
    * @returns {any} id
    */
-  store(content, metadata = {}) {
+  store(content, metadata = {}, opts = {}) {
+    const ctx = opts && opts.ctx;
+    if (ctx && typeof ctx.recordMemoryOp === 'function') ctx.recordMemoryOp('stored');
     return this._store.store(content, metadata);
   }
 
   /**
    * @param {string} query
-   * @param {Record<string, any>} [options]
+   * @param {Record<string, any>} [options] - Store search options. If `options.ctx` carries a Loop-lent
+   *   `recordMemoryOp` hook, this recall is counted against that run's `result.metrics.memory.recalls`
+   *   (§3.6, opt-in — the hook is absent unless the caller threads the run's ctx). Memory stays
+   *   Loop-agnostic: it only calls an optional hook, and `ctx` is stripped, never forwarded to the store.
    * @returns {any}
    */
   search(query, options = {}) {
-    return this._store.search(query, options);
+    const { ctx, ...storeOptions } = options || {};
+    if (ctx && typeof ctx.recordMemoryOp === 'function') ctx.recordMemoryOp('recalls');
+    return this._store.search(query, storeOptions);
   }
 
   /**

package/src/provider-anthropic.d.ts

@@ -10,6 +10,14 @@ export type AnthropicOptions = {
      * - Model ID.
      */
     model?: string | undefined;
+    /**
+     * - API base (override for proxies/gateways; the request posts to `${baseUrl}/messages`).
+     */
+    baseUrl?: string | undefined;
+    /**
+     * - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
+     */
+    cacheSystem?: boolean | undefined;
     /**
      * - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
      */
@@ -22,6 +30,8 @@ export type AnthropicOptions = {
  * @typedef {object} AnthropicOptions
  * @property {string} [apiKey] - Anthropic API key (required).
  * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
+ * @property {string} [baseUrl='https://api.anthropic.com/v1'] - API base (override for proxies/gateways; the request posts to `${baseUrl}/messages`).
+ * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
  */
 export class AnthropicProvider {
@@ -32,6 +42,8 @@ export class AnthropicProvider {
     constructor(options?: AnthropicOptions);
     apiKey: string;
     model: string;
+    baseUrl: string;
+    cacheSystem: boolean;
     exposeErrorBody: boolean;
     /**
      * Generate a response from the Anthropic API.
@@ -52,4 +64,5 @@ export class AnthropicProvider {
      * @returns {Promise<any>}
      */
     _request(body: Record<string, any>): Promise<any>;
+    _warnedInsecure: boolean | undefined;
 }

package/src/provider-anthropic.js

@@ -1,8 +1,15 @@
 'use strict';
 
 const https = require('https');
+const http = require('http');
 const { ProviderError } = require('./errors');
 
+/** @param {string} hostname @returns {boolean} */
+function isLoopbackHost(hostname) {
+  const h = hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.startsWith('127.');
+}
+
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
 /** @typedef {import('../types').GenerateResult} GenerateResult */
@@ -11,6 +18,8 @@ const { ProviderError } = require('./errors');
  * @typedef {object} AnthropicOptions
  * @property {string} [apiKey] - Anthropic API key (required).
  * @property {string} [model='claude-haiku-4-5-20251001'] - Model ID.
+ * @property {string} [baseUrl='https://api.anthropic.com/v1'] - API base (override for proxies/gateways; the request posts to `${baseUrl}/messages`).
+ * @property {boolean} [cacheSystem=false] - Opt-in prompt caching: send the system prompt with a `cache_control` breakpoint so Anthropic caches it. Anthropic does NOT auto-cache, so without this its cache tiers are always 0. Overridable per call via `generate(..., { cacheSystem })`.
  * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default to avoid leaking unexpected fields through error logs; `err.message` still carries the API error).
  */
 
@@ -23,6 +32,11 @@ class AnthropicProvider {
     if (!options.apiKey) throw new Error('[AnthropicProvider] requires apiKey');
     this.apiKey = options.apiKey.trim();
     this.model = options.model || 'claude-haiku-4-5-20251001';
+    this.baseUrl = options.baseUrl || 'https://api.anthropic.com/v1';
+    // Opt-in prompt caching: when true, the system prompt is sent with a cache_control breakpoint so
+    // Anthropic caches it (unlike OpenAI/Gemini, Anthropic does NOT auto-cache — without this its
+    // cache_read/cache_creation tiers are always 0). Default off keeps requests byte-identical to before.
+    this.cacheSystem = options.cacheSystem === true;
     // See OpenAIProvider: attach full upstream body to err.body only on opt-in.
     this.exposeErrorBody = options.exposeErrorBody === true;
   }
@@ -52,6 +66,15 @@ class AnthropicProvider {
     // Override with options.system if provided
     if (options.system) system = options.system;
 
+    // Opt-in caching: mark a string system prompt as a cache breakpoint. Anthropic caches the prefix
+    // up to this point (min ~1024-4096 tok depending on model; a shorter prompt silently won't cache —
+    // harmless). A per-call options.cacheSystem can override the instance default. Arrays are passed
+    // through untouched (the caller already shaped their own cache_control blocks).
+    const cacheSystem = options.cacheSystem != null ? options.cacheSystem === true : this.cacheSystem;
+    if (cacheSystem && typeof system === 'string' && system.length > 0) {
+      system = [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }];
+    }
+
     /** @type {Record<string, any>} */
     const body = {
       model: this.model,
@@ -84,9 +107,13 @@ class AnthropicProvider {
       text,
       toolCalls,
       model: data.model || this.model,
+      // Anthropic's `input_tokens` is ALREADY the uncached remainder (cached tokens are reported
+      // separately, not folded in — verified live), so no subtraction here, unlike OpenAI/Gemini.
       usage: {
         inputTokens: data.usage?.input_tokens || 0,
         outputTokens: data.usage?.output_tokens || 0,
+        cacheReadTokens: data.usage?.cache_read_input_tokens || 0,
+        cacheCreationTokens: data.usage?.cache_creation_input_tokens || 0,
       },
     };
   }
@@ -134,7 +161,15 @@ class AnthropicProvider {
   _request(body) {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
-      const req = https.request('https://api.anthropic.com/v1/messages', {
+      const url = new URL(this.baseUrl + '/messages');
+      const transport = url.protocol === 'https:' ? https : http;
+      // Plaintext key to a remote host exposes it on the wire; loopback (test servers / local
+      // proxies) is the legitimate http case. Warn once, mirror OpenAIProvider.
+      if (url.protocol === 'http:' && !isLoopbackHost(url.hostname) && !this._warnedInsecure) {
+        this._warnedInsecure = true;
+        console.warn(`[AnthropicProvider] sending x-api-key over PLAINTEXT http to ${url.hostname} — key exposed on the wire. Use https.`);
+      }
+      const req = transport.request(url, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',