The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
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.ssenew file mode 100644index 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.tsindex 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.tsindex 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): NormalizedTrespAttrs.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.tsindex 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.tsindex 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.tsindex 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.mdxindex 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.mdxindex 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).## Relateddiff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdxindex 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.mdxindex 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