Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Capture claude.ai cache token counts and correct the coverage claim

Claude298e192ea34a
diff --git a/browser-extension/fixtures/claude/with-usage.sse b/browser-extension/fixtures/claude/with-usage.sse
new file mode 100644
index 00000000..d41ef049
--- /dev/null
+++ b/browser-extension/fixtures/claude/with-usage.sse
@@ -0,0 +1,17 @@
+event: message_start
+data: {"type":"message_start","message":{"id":"chatcompl_REDACTED","type":"message","role":"assistant","model":"claude-opus-4-8","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":37,"cache_creation_input_tokens":1024,"cache_read_input_tokens":18500,"output_tokens":1}}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":"","citations":[]}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Paris."}}
+
+event: content_block_stop
+data: {"type":"content_block_stop","index":0}
+
+event: message_delta
+data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":214}}
+
+event: message_stop
+data: {"type":"message_stop"}
diff --git a/browser-extension/src/adapters/claude.ts b/browser-extension/src/adapters/claude.ts
index a6adf410..401a2fc9 100644
--- a/browser-extension/src/adapters/claude.ts
+++ b/browser-extension/src/adapters/claude.ts
@@ -2,11 +2,11 @@
//
// claude.ai streams Server-Sent Events whose `data:` payloads are Anthropic
// streaming objects keyed by `type`:
-// message_start { message: { model, usage:{input_tokens} } }
+// message_start { message: { model, usage:{input_tokens, cache_creation_input_tokens, cache_read_input_tokens} } }
// content_block_start { index, content_block:{ type:'text'|'tool_use', id?, name? } }
// content_block_delta { index, delta:{ type:'text_delta', text } | { type:'input_json_delta', partial_json } }
// content_block_stop { index }
-// message_delta { delta:{ stop_reason }, usage:{ output_tokens } }
+// message_delta { delta:{ stop_reason }, usage:{ output_tokens, ...possibly the input counts again } }
// message_stop
// A legacy shape ({ completion: "…delta" }) is also tolerated.
//
@@ -28,6 +28,8 @@ class ClaudeParser implements TurnParser {
private responseText = '';
private inputTokens?: number;
private outputTokens?: number;
+ private cacheCreationInputTokens?: number;
+ private cacheReadInputTokens?: number;
private startedAt = Date.now();
private completedAt?: number;
private reqId: number;
@@ -91,7 +93,7 @@ class ClaudeParser implements TurnParser {
// the URL/request body; using message.id would mis-correlate turns).
if (typeof m.uuid === 'string') this.messageId = m.uuid;
else if (typeof m.id === 'string') this.messageId = m.id;
- if (typeof m.usage?.input_tokens === 'number') this.inputTokens = m.usage.input_tokens;
+ this.readUsage(m.usage);
break;
}
case 'content_block_start': {
@@ -118,7 +120,12 @@ class ClaudeParser implements TurnParser {
break;
}
case 'message_delta': {
+ // output_tokens is read only here. message_start carries a placeholder
+ // of 1 rather than a count, so reading it there would report 1 output
+ // token for any stream that aborts before message_delta -- worse than
+ // the honest "unknown" that leaving it undefined gives.
if (typeof obj.usage?.output_tokens === 'number') this.outputTokens = obj.usage.output_tokens;
+ this.readUsage(obj.usage);
break;
}
case 'message_stop': {
@@ -128,6 +135,29 @@ class ClaudeParser implements TurnParser {
}
}
+ /** Merge the input-side counts of an Anthropic `usage` object into the turn.
+ *
+ * Read from both `message_start` and `message_delta` because which of the two
+ * carries them has moved between API versions: they have always been on
+ * `message_start`, and newer streams repeat them on `message_delta`. Each
+ * field is taken independently and only when numeric, so a payload carrying
+ * one of them never clears the others.
+ *
+ * The three input counts are disjoint in Anthropic's usage object --
+ * `input_tokens` excludes both cached reads and cache writes -- which is
+ * already the disjointness `gen_ai.usage` requires, so nothing is subtracted
+ * here the way the Codex turn span needs.
+ *
+ * output_tokens is deliberately not read here; see the message_delta case. */
+ private readUsage(u: any): void {
+ if (!u) return;
+ if (typeof u.input_tokens === 'number') this.inputTokens = u.input_tokens;
+ if (typeof u.cache_creation_input_tokens === 'number')
+ this.cacheCreationInputTokens = u.cache_creation_input_tokens;
+ if (typeof u.cache_read_input_tokens === 'number')
+ this.cacheReadInputTokens = u.cache_read_input_tokens;
+ }
+
getTurn(): ChatTurn | null {
if (!this.responseText && this.blocks.size === 0 && !this.promptText) return null;
const toolCalls: ToolCall[] = [];
@@ -159,7 +189,12 @@ class ClaudeParser implements TurnParser {
outputMessages: [{ role: 'assistant', text: this.responseText }],
responseText: this.responseText,
toolCalls,
- usage: { inputTokens: this.inputTokens, outputTokens: this.outputTokens },
+ usage: {
+ inputTokens: this.inputTokens,
+ outputTokens: this.outputTokens,
+ cacheCreationInputTokens: this.cacheCreationInputTokens,
+ cacheReadInputTokens: this.cacheReadInputTokens,
+ },
startedAt: this.startedAt,
completedAt: this.completedAt,
captureMode: 'sse',
diff --git a/browser-extension/src/shared/normalize.ts b/browser-extension/src/shared/normalize.ts
index c93f907c..225b7032 100644
--- a/browser-extension/src/shared/normalize.ts
+++ b/browser-extension/src/shared/normalize.ts
@@ -137,6 +137,15 @@ export function normalizeTurn(turn: ChatTurn, retention: Retention): NormalizedT
respAttrs.push(int('gen_ai.usage.input_tokens', turn.usage.inputTokens));
if (turn.usage?.outputTokens != null)
respAttrs.push(int('gen_ai.usage.output_tokens', turn.usage.outputTokens));
+ // Cache counts use the dotted spelling the collector reads first
+ // (GenAIUsageFromAttrs), and are disjoint from input_tokens, so a total is
+ // input + output + cache_read + cache_creation with nothing double-counted.
+ if (turn.usage?.cacheCreationInputTokens != null)
+ respAttrs.push(
+ int('gen_ai.usage.cache_creation.input_tokens', turn.usage.cacheCreationInputTokens),
+ );
+ if (turn.usage?.cacheReadInputTokens != null)
+ respAttrs.push(int('gen_ai.usage.cache_read.input_tokens', turn.usage.cacheReadInputTokens));
let respTrunc = false;
const outputMsgs = shapeText(JSON.stringify(turn.outputMessages), retention);
diff --git a/browser-extension/src/shared/types.ts b/browser-extension/src/shared/types.ts
index 7123bd92..b0ba6ffc 100644
--- a/browser-extension/src/shared/types.ts
+++ b/browser-extension/src/shared/types.ts
@@ -21,8 +21,13 @@ export interface ToolCall {
}
export interface Usage {
+ /** Uncached prompt tokens. Disjoint from the two cache counts below. */
inputTokens?: number;
outputTokens?: number;
+ /** Prompt tokens written to the cache on this turn. */
+ cacheCreationInputTokens?: number;
+ /** Prompt tokens served from the cache on this turn. */
+ cacheReadInputTokens?: number;
}
/**
diff --git a/browser-extension/test/unit/claude.adapter.test.ts b/browser-extension/test/unit/claude.adapter.test.ts
index ec1a4620..d4af44c1 100644
--- a/browser-extension/test/unit/claude.adapter.test.ts
+++ b/browser-extension/test/unit/claude.adapter.test.ts
@@ -37,9 +37,14 @@ describe('claude adapter — simple turn', () => {
it('captures the model', () => {
expect(turn.responseModel).toBe('claude-opus-4-8');
});
- it('leaves usage tokens undefined (claude.ai does not stream them)', () => {
+ it('leaves every usage count undefined when the stream carries no usage object', () => {
+ // This fixture is recorded claude.ai traffic, and it carries no `usage` at
+ // all. Unknown must stay unknown rather than becoming zero: a zero would sum
+ // into token rollups as a real observation of "this turn cost nothing".
expect(turn.usage?.inputTokens).toBeUndefined();
expect(turn.usage?.outputTokens).toBeUndefined();
+ expect(turn.usage?.cacheCreationInputTokens).toBeUndefined();
+ expect(turn.usage?.cacheReadInputTokens).toBeUndefined();
});
it('marks the turn completed', () => {
expect(turn.completedAt).toBeTypeOf('number');
@@ -69,3 +74,50 @@ describe('claude adapter — chunk-size invariance', () => {
for (const t of texts) expect(t).toBe('Paris.');
});
});
+
+// The usage fixture is synthetic, not recorded traffic: no claude.ai capture on
+// hand carries a `usage` object (see the simple-turn assertions above). It pins
+// the Anthropic streaming shape the parser is written against, so that if and
+// when claude.ai does start sending counts, the four fields land in the right
+// places instead of silently going to input_tokens or nowhere.
+describe('claude adapter -- usage counts', () => {
+ const turn = run('with-usage', 'What is the capital of France?')!.getTurn()!;
+
+ it('captures uncached input and both cache counts from message_start', () => {
+ expect(turn.usage?.inputTokens).toBe(37);
+ expect(turn.usage?.cacheCreationInputTokens).toBe(1024);
+ expect(turn.usage?.cacheReadInputTokens).toBe(18500);
+ });
+
+ it('takes output_tokens from message_delta, not the message_start placeholder', () => {
+ // message_start reports output_tokens:1 as a placeholder. Reading it there
+ // would report 1 output token for any stream that aborts before
+ // message_delta, which is worse than reporting nothing.
+ expect(turn.usage?.outputTokens).toBe(214);
+ });
+
+ it('keeps the input counts disjoint so a total never double-counts', () => {
+ // Anthropic excludes cached reads and cache writes from input_tokens, which
+ // is the disjointness gen_ai.usage requires; nothing is subtracted here the
+ // way the Codex turn span needs.
+ const u = turn.usage!;
+ const total =
+ u.inputTokens! + u.outputTokens! + u.cacheCreationInputTokens! + u.cacheReadInputTokens!;
+ expect(total).toBe(19775);
+ });
+});
+
+describe('claude adapter -- partial stream usage', () => {
+ it('reports no output tokens when the stream aborts before message_delta', () => {
+ const parser = claudeAdapter.createParser(1);
+ parser.onRequest(URL, 'POST', JSON.stringify({ prompt: 'hi', conversation_id: CONV }));
+ const body = fixture('with-usage');
+ parser.onChunk(body.slice(0, body.indexOf('event: message_delta')));
+ parser.onDone();
+ const turn = parser.getTurn()!;
+ expect(turn.usage?.outputTokens).toBeUndefined();
+ // The input side is already final at message_start, so it survives the abort.
+ expect(turn.usage?.inputTokens).toBe(37);
+ expect(turn.usage?.cacheReadInputTokens).toBe(18500);
+ });
+});
diff --git a/browser-extension/test/unit/normalize.test.ts b/browser-extension/test/unit/normalize.test.ts
index c2633b37..b729b7fe 100644
--- a/browser-extension/test/unit/normalize.test.ts
+++ b/browser-extension/test/unit/normalize.test.ts
@@ -85,6 +85,27 @@ describe('normalizeTurn — full retention, simple completed turn', () => {
expect(r['gen_ai.usage.output_tokens']).toBe(2);
});
+ it('emits cache counts under the dotted names the collector reads', () => {
+ // GenAIUsageFromAttrs in the beaconjson exporter reads
+ // gen_ai.usage.cache_creation.input_tokens first and the flat
+ // gen_ai.usage.cache_creation_input_tokens only as an alias, so the dotted
+ // spelling is the one to emit.
+ const records = normalize(
+ baseTurn({
+ usage: { inputTokens: 37, outputTokens: 214, cacheCreationInputTokens: 1024, cacheReadInputTokens: 18500 },
+ }),
+ ).logRecords;
+ const r = flat(byAction(records, 'agent.response.completed')!.attributes);
+ expect(r['gen_ai.usage.cache_creation.input_tokens']).toBe(1024);
+ expect(r['gen_ai.usage.cache_read.input_tokens']).toBe(18500);
+ });
+
+ it('omits cache attributes entirely when the stream reported none', () => {
+ const r = flat(respRec.attributes);
+ expect(r['gen_ai.usage.cache_creation.input_tokens']).toBeUndefined();
+ expect(r['gen_ai.usage.cache_read.input_tokens']).toBeUndefined();
+ });
+
it('does NOT set fields the exporter fills', () => {
for (const rec of logRecords) {
const a = flat(rec.attributes);
diff --git a/docs/runtimes/browser-extension.mdx b/docs/runtimes/browser-extension.mdx
index 95ef495f..490c619a 100644
--- a/docs/runtimes/browser-extension.mdx
+++ b/docs/runtimes/browser-extension.mdx
@@ -11,7 +11,7 @@ One extension covers both supported sites:
<Columns cols={2}>
<Card title="Claude.ai" icon="message" href="/runtimes/claude-web">
- Prompts, responses, tool calls, and token usage from the claude.ai chat stream.
+ Prompts, responses, and tool calls from the claude.ai chat stream.
</Card>
<Card title="ChatGPT" icon="message" href="/runtimes/chatgpt-web">
Prompts, responses, and tool activity from the chatgpt.com chat stream.
diff --git a/docs/runtimes/claude-web.mdx b/docs/runtimes/claude-web.mdx
index b89db192..d5829e59 100644
--- a/docs/runtimes/claude-web.mdx
+++ b/docs/runtimes/claude-web.mdx
@@ -53,7 +53,7 @@ Turns from one conversation share a session id, so a conversation reads as a ses
| Assistant response telemetry | Supported, including the response text and the model reported by the stream |
| Tool telemetry | Supported. Tool call id, name, and arguments are captured from `tool_use` blocks |
| Tool results | Not available. The chat stream carries the tool call, not the result Anthropic computed for it |
-| Token usage | Supported. Input and output token counts are normalized into `gen_ai.usage` |
+| Token usage | Parsed when the stream carries it, which recorded traffic so far does not. See [Limits](#limits) |
| Cost | Not available. claude.ai does not report per-turn cost to the page |
| Command and file telemetry | Not applicable. Browser chat performs no local commands or file edits |
| Approval telemetry | Not available. claude.ai does not expose approval decisions to a page script |
@@ -84,6 +84,7 @@ If nothing arrives, work through the [troubleshooting steps](/runtimes/browser-e
- **The stream format is private.** The adapter is written defensively and degrades to a partial turn rather than failing, but a site change can still stop capture until the adapter is updated.
- **Only the chat stream is read.** Attachments, artifacts rendered outside the stream, and project files are not captured.
- **Prompt text comes from the request body.** A turn sent through a path the adapter does not recognize arrives with the response but without the prompt.
+- **Token counts are usually absent.** The adapter reads uncached input, cache creation, cache read, and output counts from the `message_start` and `message_delta` usage objects, but no claude.ai capture on hand has carried a `usage` object at all. Turns therefore normally reach `beacon token-usage` with no token attribution, and Asymptote does not estimate counts it was not given. If the site starts sending them, they land in `gen_ai.usage` with no extension change.
- **Retention defaults to `full`.** Prompt and response text is retained unless you change the mode in the extension's popup. See [retained content](/runtimes/browser-extension#retained-content).
## Related
diff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdx
index cbe5b988..5ad05108 100644
--- a/docs/runtimes/index.mdx
+++ b/docs/runtimes/index.mdx
@@ -54,7 +54,7 @@ Two rows in that table are not hook or OTLP integrations. [fx](/runtimes/vercel-
| Agent harness | Collection path | Telemetry coverage |
|----------------|-----------------|--------------------|
-| [Claude.ai](/runtimes/claude-web) (beta) | Managed browser extension over local OTLP | Prompt, assistant response, tool call, and token usage telemetry from the claude.ai chat stream |
+| [Claude.ai](/runtimes/claude-web) (beta) | Managed browser extension over local OTLP | Prompt, assistant response, and tool call telemetry from the claude.ai chat stream. Token usage is parsed when the stream carries it, which recorded traffic so far does not |
| [ChatGPT](/runtimes/chatgpt-web) (beta) | Managed browser extension over local OTLP | Prompt, assistant response, and web search tool telemetry from the chatgpt.com chat stream. No token usage, which the site does not report |
Both sites are collected by one optional Chrome extension. Browser chat resolves to the `claude_web` and `chatgpt_web` harness names, so it stays distinguishable from CLI agents. The extension retains full prompt and response text by default. See [Browser Extension](/runtimes/browser-extension) to install it and to change the retention mode.
diff --git a/docs/security/data-inventory.mdx b/docs/security/data-inventory.mdx
index 830e23fe..034026f9 100644
--- a/docs/security/data-inventory.mdx
+++ b/docs/security/data-inventory.mdx
@@ -24,7 +24,7 @@ Beacon writes normalized endpoint events only when supported runtimes provide te
| Cursor | Native hooks | Prompt, tool, shell command, MCP-like, approval, and file edit telemetry |
| Claude Cowork | Admin-configured OTLP | Prompt and assistant response content; approvals; command, tool, file, and MCP activity; session lifecycle; model and token usage; runtime-reported cost; source user identifier and cloud origin when emitted through Cowork OTLP |
| OpenClaw Gateway | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |
-| [Claude.ai](/runtimes/claude-web) (`claude_web`) | Managed browser extension over local OTLP | Prompt text, assistant response text, request and response model, tool call id/name/arguments/results, token usage, and conversation id from the claude.ai chat stream |
+| [Claude.ai](/runtimes/claude-web) (`claude_web`) | Managed browser extension over local OTLP | Prompt text, assistant response text, request and response model, tool call id/name/arguments/results, conversation id, and token usage when the stream carries it, from the claude.ai chat stream |
| [ChatGPT](/runtimes/chatgpt-web) (`chatgpt_web`) | Managed browser extension over local OTLP | Prompt text, assistant response text, model, tool call activity, and conversation id from the chatgpt.com chat stream. ChatGPT web does not report token usage in its stream |
The browser extension is the only surface that reads content from a site the