@saccolabs/pi-claude-cli 0.4.9 → 0.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/event-bridge.ts

@@ -1,6 +1,7 @@
 import type {
   ClaudeApiEvent,
   ClaudeAssistantEnvelope,
+  ClaudeModelUsage,
   ClaudeResultMessage,
   ClaudeUsage,
   TrackedContentBlock,
@@ -131,9 +132,69 @@ export function createEventBridge(
     cache_creation_input_tokens: 0,
   };
   let cycleUsage: ClaudeUsage = {};
+  /**
+   * Context size of the most recent cycle — what the model actually saw on
+   * its last call, which is NOT the episode's summed usage.
+   *
+   * pi reads `usage.totalTokens` as the conversation's context size
+   * (`calculateContextTokens` in pi's compaction module short-circuits on it)
+   * and uses it for both the context gauge and the auto-compaction trigger.
+   * Every cycle re-sends the same cached prefix, so summing cycles counts
+   * that prefix once per cycle: a captured 3-cycle episode sums to 82,174
+   * while the model's real context never exceeded 28,243. The host then
+   * showed 41% of a 200k window instead of 14%, and a long enough turn
+   * crossed pi's compaction threshold at a fraction of true occupancy.
+   *
+   * So the four component figures stay cumulative — they are what gets
+   * billed — and `totalTokens` carries the last cycle's context instead.
+   */
+  let lastCycleContext = 0;
   /** Tool ids already surfaced as markers (envelope arrives once per block). */
   const markedToolIds = new Set<string>();
 
+  /**
+   * Fold per-model spend into one `ClaudeUsage`.
+   *
+   * Every entry counts, including models the session did not pick: a
+   * sub-agent may run a different model, and the auto-titler always does.
+   * Returns undefined when the CLI sent no `modelUsage` (older versions), so
+   * the caller can fall back to the main-agent-only `usage`.
+   *
+   * The folded tokens are priced at the SESSION's model rates by
+   * `calculateCost`. That is exact for sub-agents, which inherit the session
+   * model, and slightly off for a cheaper helper model — a known skew worth
+   * far less than the tokens it stops hiding.
+   */
+  function sumModelUsage(
+    modelUsage: Record<string, ClaudeModelUsage> | undefined,
+  ): ClaudeUsage | undefined {
+    if (!modelUsage) return undefined;
+    const entries = Object.values(modelUsage);
+    if (entries.length === 0) return undefined;
+    const total = {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    };
+    for (const entry of entries) {
+      total.input_tokens += entry.inputTokens ?? 0;
+      total.output_tokens += entry.outputTokens ?? 0;
+      total.cache_read_input_tokens += entry.cacheReadInputTokens ?? 0;
+      total.cache_creation_input_tokens += entry.cacheCreationInputTokens ?? 0;
+    }
+    return total;
+  }
+
+  /** Prompt size of one cycle: everything the model read, excluding output. */
+  function contextOf(usage: ClaudeUsage): number {
+    return (
+      (usage.input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0)
+    );
+  }
+
   function recomputeUsage(): void {
     output.usage.input =
       cumulativeUsage.input_tokens + (cycleUsage.input_tokens ?? 0);
@@ -145,11 +206,18 @@ export function createEventBridge(
     output.usage.cacheWrite =
       cumulativeUsage.cache_creation_input_tokens +
       (cycleUsage.cache_creation_input_tokens ?? 0);
+    // Latch the newest cycle we have numbers for. `applyResult` clears
+    // cycleUsage, so a zero here means "no fresher figure", never "empty
+    // context" — the last latched value must survive.
+    const cycleContext = contextOf(cycleUsage);
+    if (cycleContext > 0) lastCycleContext = cycleContext;
     output.usage.totalTokens =
-      output.usage.input +
-      output.usage.output +
-      output.usage.cacheRead +
-      output.usage.cacheWrite;
+      lastCycleContext > 0
+        ? lastCycleContext
+        : output.usage.input +
+          output.usage.output +
+          output.usage.cacheRead +
+          output.usage.cacheWrite;
     calculateCost(model, output.usage);
   }
 
@@ -536,19 +604,28 @@ export function createEventBridge(
   }
 
   function applyResult(result: ClaudeResultMessage): void {
-    // Authoritative cumulative usage for the whole episode (verified to
-    // equal the per-cycle sums on captured streams; trusted over them).
-    const usage = result.usage;
-    if (usage) {
+    // Authoritative spend for the whole episode. `modelUsage` is preferred
+    // over `usage` because `usage` is the MAIN AGENT ONLY: sub-agents run
+    // inside the CLI and never appear in the parent stream, so their tokens
+    // — often the majority — were simply missing from what the host billed.
+    // Same for helper models like the haiku auto-titler.
+    //
+    // Measured 2026-08-27: a lane's turn reported $2.34 while seven
+    // sub-agents spent 28.6M cache-read tokens on top of it, a 10x
+    // under-report. On a captured single-sub-agent episode `modelUsage`
+    // summed to exactly main + sub-agent (102,641 cache-read / 56,920
+    // cache-write), which is why it is trusted here.
+    const totals = sumModelUsage(result.modelUsage) ?? result.usage;
+    if (totals) {
       cumulativeUsage.input_tokens =
-        usage.input_tokens ?? cumulativeUsage.input_tokens;
+        totals.input_tokens ?? cumulativeUsage.input_tokens;
       cumulativeUsage.output_tokens =
-        usage.output_tokens ?? cumulativeUsage.output_tokens;
+        totals.output_tokens ?? cumulativeUsage.output_tokens;
       cumulativeUsage.cache_read_input_tokens =
-        usage.cache_read_input_tokens ??
+        totals.cache_read_input_tokens ??
         cumulativeUsage.cache_read_input_tokens;
       cumulativeUsage.cache_creation_input_tokens =
-        usage.cache_creation_input_tokens ??
+        totals.cache_creation_input_tokens ??
         cumulativeUsage.cache_creation_input_tokens;
       cycleUsage = {};
       recomputeUsage();

package/src/types.ts

@@ -7,14 +7,37 @@ export interface ClaudeStreamEventMessage {
   event: ClaudeApiEvent;
 }
 
+/**
+ * Per-model spend for the episode, keyed by model id.
+ *
+ * This is the ONLY place the CLI accounts for work done outside the main
+ * agent's own transcript: sub-agents (which run inside the CLI and never
+ * appear in the parent stream) and helper models such as the haiku
+ * auto-titler. `result.usage` covers the main agent alone.
+ *
+ * Verified 2026-08-27 on a captured episode with one synchronous sub-agent:
+ * main agent 74,562 cache-read / 26,808 cache-write, sub-agent 28,079 /
+ * 30,112, and `modelUsage` reported exactly the two summed — 102,641 /
+ * 56,920.
+ */
+export interface ClaudeModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  costUSD?: number;
+}
+
 export interface ClaudeResultMessage {
   type: "result";
   subtype: "success" | "error";
   result?: string;
   error?: string;
   session_id?: string;
-  /** Cumulative usage across every cycle of the episode (authoritative). */
+  /** Cumulative usage for the MAIN agent across every cycle of the episode. */
   usage?: ClaudeUsage;
+  /** Per-model spend, including sub-agents and helper models. */
+  modelUsage?: Record<string, ClaudeModelUsage>;
   num_turns?: number;
   total_cost_usd?: number;
 }