fix(observability): read Anthropic cache tokens instead of under-reporting input by orders of magnitude

`input_tokens` on an Anthropic-style usage envelope is the UNCACHED remainder,
not the whole prompt. This engine's prompts cache well -- a stable system prompt
plus repo context -- so on a cache hit the real prompt sits in
cache_read_input_tokens while input_tokens holds a handful of leftovers. Nothing
read those fields, on either the ORB or the miner.

Live evidence minutes after deploying orb-v3.7.0-beta.9, which is the image that
first carried #10212's fix for the scrubber that had been nulling tokens
entirely: a review that produced 787 output tokens and cost $0.21 reported TWO
input tokens, while the local ollama model on the same box reported 2,706. The
gap was invisible until tokens started arriving at all.

Parse cache_read_input_tokens and cache_creation_input_tokens and report them in
their own right, rather than folding them into inputTokens. That is what the
provider means by each field, and cache reads price at a fraction of fresh
input, so summing them in would trade one wrong number for another. PostHog
models the distinction directly and prices the two separately.

Also set $ai_cache_reporting_exclusive when cache fields are present. PostHog
otherwise auto-detects the convention from $ai_provider, and this deployment
reports "claude-code" / "claude-cli" / "agent-sdk" rather than "anthropic",
so the auto-detection would read the envelope as inclusive and price the cached
prompt as fresh input. The key names themselves are the exclusive-counting
convention, so their presence is the signal -- no provider-name sniffing.

Fixed in all four parsers that had the gap: the ORB's extractCliUsage, the
miner's deliberately-duplicated copy in cli-subprocess-driver, the Agent-SDK
driver's result reader, and through it runChatGrounding, which shares it.

Closes #10246

Author: JSONbored

packages/loopover-engine/src/miner/agent-sdk-driver.ts

@@ -103,11 +103,20 @@ function tokensFromResultMessage(resultMessage: Record<string, unknown> | null):
   const usage = asRecord(resultMessage?.usage);
   const inputTokens = finiteNonNegativeNumber(usage?.input_tokens);
   const outputTokens = finiteNonNegativeNumber(usage?.output_tokens);
-  if (inputTokens === undefined && outputTokens === undefined) return {};
+  // #10246: on a cache hit `input_tokens` is only the UNCACHED remainder -- the real prompt sits here. Kept
+  // separate rather than folded into `inputTokens`, because that is what the provider means by each and
+  // cache reads are priced at a fraction of fresh input.
+  const cacheReadInputTokens = finiteNonNegativeNumber(usage?.cache_read_input_tokens);
+  const cacheCreationInputTokens = finiteNonNegativeNumber(usage?.cache_creation_input_tokens);
+  if (inputTokens === undefined && outputTokens === undefined && cacheReadInputTokens === undefined && cacheCreationInputTokens === undefined) {
+    return {};
+  }
   return {
     tokensUsed: (inputTokens ?? 0) + (outputTokens ?? 0),
     ...(inputTokens === undefined ? {} : { inputTokens }),
     ...(outputTokens === undefined ? {} : { outputTokens }),
+    ...(cacheReadInputTokens === undefined ? {} : { cacheReadInputTokens }),
+    ...(cacheCreationInputTokens === undefined ? {} : { cacheCreationInputTokens }),
   };
 }
 

packages/loopover-engine/src/miner/ai-generation-sink.ts

@@ -37,6 +37,10 @@ export type MinerAiGenerationRecord = {
   totalTokens?: number | undefined;
   inputTokens?: number | undefined;
   outputTokens?: number | undefined;
+  /** #10246: Anthropic-style cache accounting. On a cache hit `inputTokens` is only the UNCACHED remainder,
+   *  so these carry the rest -- separately, because the provider prices them separately and PostHog does too. */
+  cacheReadInputTokens?: number | undefined;
+  cacheCreationInputTokens?: number | undefined;
   totalCostUsd?: number | undefined;
   error?: unknown;
 };
@@ -101,6 +105,8 @@ export function withCodingAgentGenerationCapture(provider: string, model: string
           totalTokens: result.tokensUsed,
           inputTokens: result.inputTokens,
           outputTokens: result.outputTokens,
+          cacheReadInputTokens: result.cacheReadInputTokens,
+          cacheCreationInputTokens: result.cacheCreationInputTokens,
           totalCostUsd: result.costUsd,
           error: result.ok ? undefined : result.error,
         });

packages/loopover-engine/src/miner/chat-grounding.ts

@@ -341,6 +341,8 @@ export async function* runChatGrounding(
       totalTokens: tokens.tokensUsed,
       inputTokens: tokens.inputTokens,
       outputTokens: tokens.outputTokens,
+      cacheReadInputTokens: tokens.cacheReadInputTokens,
+      cacheCreationInputTokens: tokens.cacheCreationInputTokens,
       totalCostUsd: costUsd,
       ...(failure === undefined ? {} : { error: new Error(failure) }),
     });

packages/loopover-engine/src/miner/cli-subprocess-driver.ts

@@ -143,8 +143,21 @@ const COST_KEYS = ["total_cost_usd", "totalCostUsd", "cost_usd", "costUsd"] as c
 const INPUT_TOKEN_KEYS = ["input_tokens", "inputTokens", "prompt_tokens", "promptTokens"] as const;
 const OUTPUT_TOKEN_KEYS = ["output_tokens", "outputTokens", "completion_tokens", "completionTokens"] as const;
 const TOTAL_TOKEN_KEYS = ["total_tokens", "totalTokens"] as const;
+/** #10246: Anthropic-style cache accounting. `input_tokens` on such an envelope is the UNCACHED remainder,
+ *  not the whole prompt, so reading it alone under-reports input by orders of magnitude on a cache hit --
+ *  the same gap this file's src/selfhost/ai.ts counterpart had. These key names ARE the exclusive-counting
+ *  convention, so their presence is what identifies the envelope; no provider-name sniffing required. */
+const CACHE_READ_TOKEN_KEYS = ["cache_read_input_tokens", "cacheReadInputTokens"] as const;
+const CACHE_CREATION_TOKEN_KEYS = ["cache_creation_input_tokens", "cacheCreationInputTokens"] as const;
 
-type CliUsage = { costUsd?: number; inputTokens?: number; outputTokens?: number; totalTokens?: number };
+type CliUsage = {
+  costUsd?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+};
 
 function finiteNonNegativeNumber(value: unknown): number | undefined {
   const n = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number(value) : NaN;
@@ -182,6 +195,10 @@ function mergeCliUsage(out: CliUsage, record: Record<string, unknown>): void {
     if (outputTokens !== undefined) out.outputTokens = Math.max(out.outputTokens ?? 0, outputTokens);
     const totalTokens = maxNumber(entry, TOTAL_TOKEN_KEYS);
     if (totalTokens !== undefined) out.totalTokens = Math.max(out.totalTokens ?? 0, totalTokens);
+    const cacheRead = maxNumber(entry, CACHE_READ_TOKEN_KEYS);
+    if (cacheRead !== undefined) out.cacheReadInputTokens = Math.max(out.cacheReadInputTokens ?? 0, cacheRead);
+    const cacheCreation = maxNumber(entry, CACHE_CREATION_TOKEN_KEYS);
+    if (cacheCreation !== undefined) out.cacheCreationInputTokens = Math.max(out.cacheCreationInputTokens ?? 0, cacheCreation);
   }
 }
 
@@ -215,6 +232,8 @@ function totalTokensFromUsage(usage: CliUsage): CodingAgentTokenUsage {
   const split = {
     ...(usage.inputTokens === undefined ? {} : { inputTokens: usage.inputTokens }),
     ...(usage.outputTokens === undefined ? {} : { outputTokens: usage.outputTokens }),
+    ...(usage.cacheReadInputTokens === undefined ? {} : { cacheReadInputTokens: usage.cacheReadInputTokens }),
+    ...(usage.cacheCreationInputTokens === undefined ? {} : { cacheCreationInputTokens: usage.cacheCreationInputTokens }),
   };
   if (usage.totalTokens !== undefined) return { tokensUsed: usage.totalTokens, ...split };
   if (usage.inputTokens === undefined && usage.outputTokens === undefined) return {};

packages/loopover-engine/src/miner/coding-agent-driver.ts

@@ -34,12 +34,20 @@ export type CodingAgentDriverResult = {
    *  that reports only a blended total leaves these absent, and the blended `tokensUsed` still stands alone. */
   inputTokens?: number | undefined;
   outputTokens?: number | undefined;
+  /** #10246: Anthropic-style cache accounting, reported SEPARATELY from `inputTokens` because that is what
+   *  the provider means by each -- on a cache hit `inputTokens` is only the uncached remainder. Same
+   *  never-fabricated convention: a provider that reports no cache fields leaves these absent. */
+  cacheReadInputTokens?: number | undefined;
+  cacheCreationInputTokens?: number | undefined;
   error?: string | undefined;
 };
 
 /** The token fields a driver contributes to its result (#10198) -- spread into the result at each return site
  *  so a driver can never report a split that disagrees with its own blended total. */
-export type CodingAgentTokenUsage = Pick<CodingAgentDriverResult, "tokensUsed" | "inputTokens" | "outputTokens">;
+export type CodingAgentTokenUsage = Pick<
+  CodingAgentDriverResult,
+  "tokensUsed" | "inputTokens" | "outputTokens" | "cacheReadInputTokens" | "cacheCreationInputTokens"
+>;
 
 export interface CodingAgentDriver {
   run(task: CodingAgentDriverTask): Promise<CodingAgentDriverResult>;

packages/loopover-engine/test/agent-sdk-driver.test.ts

@@ -473,3 +473,54 @@ test("a side the provider did not report stays ABSENT rather than being zeroed (
   assert.equal(noUsageResult.inputTokens, undefined);
   assert.equal(noUsageResult.outputTokens, undefined);
 });
+
+// #10246: `input_tokens` on an Anthropic-style envelope is the UNCACHED remainder. Reading it alone
+// under-reported a real review's prompt by roughly four orders of magnitude.
+test("reports Anthropic-style cache tokens alongside the input/output split (#10246)", async () => {
+  const driver = driverWith({
+    query: queryYielding([
+      {
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        num_turns: 2,
+        result: "done",
+        usage: { input_tokens: 2, output_tokens: 787, cache_read_input_tokens: 48210, cache_creation_input_tokens: 1536 },
+      },
+    ]),
+  });
+
+  const result = await driver.run(task);
+
+  assert.equal(result.inputTokens, 2);
+  assert.equal(result.outputTokens, 787);
+  assert.equal(result.cacheReadInputTokens, 48210);
+  assert.equal(result.cacheCreationInputTokens, 1536);
+  // tokensUsed stays input+output: the cache figures are reported in their own right, not silently summed
+  // into a blended total that would price cache reads as fresh input.
+  assert.equal(result.tokensUsed, 789);
+});
+
+test("a cache-only usage envelope still produces a usage record (#10246)", async () => {
+  // A fully-cached turn can report zero fresh input; that must not read as "no usage at all".
+  const driver = driverWith({
+    query: queryYielding([
+      { type: "result", subtype: "success", is_error: false, num_turns: 1, result: "done", usage: { cache_read_input_tokens: 900 } },
+    ]),
+  });
+  const result = await driver.run(task);
+  assert.equal(result.cacheReadInputTokens, 900);
+  assert.equal(result.inputTokens, undefined);
+  assert.equal(result.tokensUsed, 0);
+});
+
+test("leaves the cache fields ABSENT when the provider reports none (#10246)", async () => {
+  const driver = driverWith({
+    query: queryYielding([
+      { type: "result", subtype: "success", is_error: false, num_turns: 1, result: "done", usage: { input_tokens: 100, output_tokens: 50 } },
+    ]),
+  });
+  const result = await driver.run(task);
+  assert.equal(result.cacheReadInputTokens, undefined);
+  assert.equal(result.cacheCreationInputTokens, undefined);
+});

packages/loopover-miner/lib/posthog.ts

@@ -138,6 +138,10 @@ export type MinerAiGenerationEvent = {
   totalTokens?: number | undefined;
   inputTokens?: number | undefined;
   outputTokens?: number | undefined;
+  /** #10246: Anthropic-style cache accounting, reported separately -- see the ORB-side counterpart in
+   *  src/selfhost/posthog.ts for why folding them into the input count is a different wrong answer. */
+  cacheReadInputTokens?: number | undefined;
+  cacheCreationInputTokens?: number | undefined;
   totalCostUsd?: number | undefined;
   error?: unknown;
 };
@@ -162,6 +166,14 @@ export function captureMinerPostHogAiGeneration(event: MinerAiGenerationEvent):
   // now contributes nothing to the token properties rather than a run of false zeros.
   if (Number.isFinite(event.inputTokens)) properties.$ai_input_tokens = event.inputTokens;
   if (Number.isFinite(event.outputTokens)) properties.$ai_output_tokens = event.outputTokens;
+  // #10246: their presence also marks the envelope EXCLUSIVE. PostHog otherwise auto-detects that from
+  // `$ai_provider`, which here reads "claude-cli"/"agent-sdk" rather than "anthropic", so it would guess
+  // inclusive and price the cached prompt as fresh input.
+  if (Number.isFinite(event.cacheReadInputTokens)) properties.$ai_cache_read_input_tokens = event.cacheReadInputTokens;
+  if (Number.isFinite(event.cacheCreationInputTokens)) properties.$ai_cache_creation_input_tokens = event.cacheCreationInputTokens;
+  if (Number.isFinite(event.cacheReadInputTokens) || Number.isFinite(event.cacheCreationInputTokens)) {
+    properties.$ai_cache_reporting_exclusive = true;
+  }
   if (Number.isFinite(event.totalTokens)) properties.tokens_used = event.totalTokens;
   if (Number.isFinite(event.totalCostUsd)) properties.$ai_total_cost_usd = event.totalCostUsd;
   if (event.isError) {

src/selfhost/ai.ts

@@ -721,6 +721,10 @@ export type CliUsage = {
   inputTokens?: number;
   outputTokens?: number;
   totalTokens?: number;
+  /** #10246: Anthropic-style cache accounting, reported SEPARATELY from `inputTokens` -- see
+   *  CACHE_READ_TOKEN_KEYS for why folding them in would be a different wrong answer. */
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
   costUsd?: number;
   model?: string;
 };
@@ -739,6 +743,8 @@ function buildAiUsage(fields: {
   inputTokens?: number | undefined;
   outputTokens?: number | undefined;
   totalTokens?: number | undefined;
+  cacheReadInputTokens?: number | undefined;
+  cacheCreationInputTokens?: number | undefined;
   costUsd?: number | undefined;
   effort?: string | undefined;
 }): AiUsage {
@@ -748,6 +754,8 @@ function buildAiUsage(fields: {
   if (fields.inputTokens !== undefined) usage.inputTokens = fields.inputTokens;
   if (fields.outputTokens !== undefined) usage.outputTokens = fields.outputTokens;
   if (fields.totalTokens !== undefined) usage.totalTokens = fields.totalTokens;
+  if (fields.cacheReadInputTokens !== undefined) usage.cacheReadInputTokens = fields.cacheReadInputTokens;
+  if (fields.cacheCreationInputTokens !== undefined) usage.cacheCreationInputTokens = fields.cacheCreationInputTokens;
   if (fields.costUsd !== undefined) usage.costUsd = fields.costUsd;
   if (fields.effort !== undefined) usage.effort = fields.effort;
   return usage;
@@ -796,9 +804,24 @@ export function providerNameFromBaseUrl(baseUrl: string | undefined): "ollama" |
   return "openai-compatible";
 }
 
+// #10246: `input_tokens` is the UNCACHED remainder on an Anthropic-style envelope, NOT the whole prompt.
+// Anthropic (and therefore the claude-code CLI) reports cached prompt tokens in their own fields, and this
+// engine's prompts cache well -- a stable system prompt plus repo context -- so on a cache hit `input_tokens`
+// is a handful of tokens while the real prompt sits in `cache_read_input_tokens`. Live evidence: a review that
+// produced 787 output tokens and cost $0.21 reported TWO input tokens.
+//
+// The fix keeps `inputTokens` faithful to what the provider means by it, and reports the cache fields
+// alongside, because PostHog models exactly this distinction: `$ai_cache_reporting_exclusive` tells it
+// whether cache tokens sit outside (Anthropic) or inside (OpenAI and most others) the input count, and it
+// prices them separately. Folding cache reads into `inputTokens` would price them at full input rate, which
+// is a different wrong answer -- cache reads are roughly a tenth the cost.
 const INPUT_TOKEN_KEYS = ["input_tokens", "inputTokens", "prompt_tokens", "promptTokens"] as const;
 const OUTPUT_TOKEN_KEYS = ["output_tokens", "outputTokens", "completion_tokens", "completionTokens"] as const;
 const TOTAL_TOKEN_KEYS = ["total_tokens", "totalTokens"] as const;
+/** Anthropic-style cache accounting (#10246). These key names ARE the exclusive-counting convention, so their
+ *  presence is what marks a usage envelope as exclusive -- no provider-name sniffing required. */
+const CACHE_READ_TOKEN_KEYS = ["cache_read_input_tokens", "cacheReadInputTokens"] as const;
+const CACHE_CREATION_TOKEN_KEYS = ["cache_creation_input_tokens", "cacheCreationInputTokens"] as const;
 const COST_KEYS = ["total_cost_usd", "totalCostUsd", "cost_usd", "costUsd"] as const;
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -835,6 +858,10 @@ function mergeUsage(out: CliUsage, record: Record<string, unknown>): void {
     if (outputTokens !== undefined) out.outputTokens = Math.max(out.outputTokens ?? 0, outputTokens);
     const totalTokens = maxNumber(entry, TOTAL_TOKEN_KEYS);
     if (totalTokens !== undefined) out.totalTokens = Math.max(out.totalTokens ?? 0, totalTokens);
+    const cacheReadInputTokens = maxNumber(entry, CACHE_READ_TOKEN_KEYS);
+    if (cacheReadInputTokens !== undefined) out.cacheReadInputTokens = Math.max(out.cacheReadInputTokens ?? 0, cacheReadInputTokens);
+    const cacheCreationInputTokens = maxNumber(entry, CACHE_CREATION_TOKEN_KEYS);
+    if (cacheCreationInputTokens !== undefined) out.cacheCreationInputTokens = Math.max(out.cacheCreationInputTokens ?? 0, cacheCreationInputTokens);
     const costUsd = maxNumber(entry, COST_KEYS);
     if (costUsd !== undefined) out.costUsd = Math.max(out.costUsd ?? 0, costUsd);
     if (typeof entry.model === "string" && entry.model.trim()) out.model = entry.model.trim();
@@ -1629,6 +1656,8 @@ async function runProviderWithOtel(
       isError: false,
       inputTokens: usage?.inputTokens,
       outputTokens: usage?.outputTokens,
+      cacheReadInputTokens: usage?.cacheReadInputTokens,
+      cacheCreationInputTokens: usage?.cacheCreationInputTokens,
       totalCostUsd: usage?.costUsd,
       effort: usage?.effort,
       context: { repo: options.repoFullName, pullNumber: options.pullNumber },
@@ -1825,6 +1854,8 @@ export function withAiGenerationCapture(providerName: string, ai: SelfHostAi): S
           isError: false,
           inputTokens: usage?.inputTokens,
           outputTokens: usage?.outputTokens,
+          cacheReadInputTokens: usage?.cacheReadInputTokens,
+          cacheCreationInputTokens: usage?.cacheCreationInputTokens,
           totalCostUsd: usage?.costUsd,
           effort: usage?.effort,
           input: aiContentInput(options),

src/selfhost/posthog.ts

@@ -433,6 +433,11 @@ export type PostHogAiGenerationEvent = {
    *  never fabricates a split its source data doesn't have. Absent for the claude-code/codex subscription
    *  CLIs whenever their own stdout reports none (a flat subscription has no real per-call dollar cost). */
   totalCostUsd?: number | undefined;
+  /** #10246: Anthropic-style cache accounting, reported SEPARATELY from `inputTokens` because that is what
+   *  the provider means by each. PostHog prices cache reads at their own (much lower) rate and uses
+   *  `$ai_cache_reporting_exclusive` to know which side of the input count they fall on. */
+  cacheReadInputTokens?: number | undefined;
+  cacheCreationInputTokens?: number | undefined;
   /** Reasoning-effort dial ("low"/"medium"/"high"/"max") -- generation CONFIG, never prompt content. */
   effort?: string | undefined;
   /** Correlation context (repo/PR), the same optional fields AiRunOptions already threads through for
@@ -633,6 +638,16 @@ export function capturePostHogAiGeneration(event: PostHogAiGenerationEvent): voi
   // outliers. A genuinely reported 0 still lands, because absence is tested, not falsiness.
   if (Number.isFinite(event.inputTokens)) properties.$ai_input_tokens = event.inputTokens;
   if (Number.isFinite(event.outputTokens)) properties.$ai_output_tokens = event.outputTokens;
+  // #10246: only emitted when the provider actually reported them. Their presence is also what marks the
+  // envelope as EXCLUSIVE -- these key names are the Anthropic convention, so no provider-name sniffing is
+  // needed. Setting the flag explicitly matters because PostHog otherwise auto-detects it from
+  // `$ai_provider`, and this deployment reports "claude-code", not "anthropic", so the auto-detection would
+  // read it as inclusive and price the same prompt twice over.
+  if (Number.isFinite(event.cacheReadInputTokens)) properties.$ai_cache_read_input_tokens = event.cacheReadInputTokens;
+  if (Number.isFinite(event.cacheCreationInputTokens)) properties.$ai_cache_creation_input_tokens = event.cacheCreationInputTokens;
+  if (Number.isFinite(event.cacheReadInputTokens) || Number.isFinite(event.cacheCreationInputTokens)) {
+    properties.$ai_cache_reporting_exclusive = true;
+  }
   if (Number.isFinite(event.totalCostUsd)) properties.$ai_total_cost_usd = event.totalCostUsd;
   if (event.effort) properties.$ai_model_parameters = { effort: event.effort };
   if (event.isError) {