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
feat(tokens): capture one-hour cache writes and price them at the 1h rate
Claudee20ebf2f24da
diff --git a/CLAUDE.md b/CLAUDE.mdindex 40d2f187..d7c2ac32 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -539,7 +539,7 @@ unpacked through Chrome's developer mode.- Reading a runtime's own on-disk session store is a `poll` collection path, not a new method: it is a pull that sees committed records after the fact, which is what `poll` means. fx is the case that exercises it (`cli/beacon/internal/fxsession`); a future runtime with the same shape uses `poll` too rather than adding a fifth value to a release-contract field.- Set the provenance markers on every new collection path. `harness.collection_method` (`hook`, `otlp`, `plugin`, `poll`) records the mechanism; `event.fidelity` (`observed`, `inferred`) records whether the source named the action or Beacon derived it. Both are defined in `pkg/asymptoteobserve/provenance.go` and are the only sanctioned way to express that difference — do not add per-runtime confidence fields, and do not leave a derived action unmarked. A new plugin-shaped runtime must be added to `CollectionMethodForPlatform`, whose default is `hook`. An action synthesized from an adjacent observation, such as an approval built from a pre-tool notification on a runtime with no approval hook, is `inferred`.- Keep event identity derivable rather than asserted. `gen_ai.tool.call.id` carries the runtime's own name for one tool invocation, promoted on every capture path from the shared alias list in `pkg/asymptoteobserve.ToolCallIDKeys`; a new runtime adds its spelling there rather than in a mapper. `event.id` is a deterministic UUID derived by `EventIDForLine` from the event about to be written, so both capture paths name one action the same way. Its namespace constant and derivation are a contract: changing either renames every event ID Beacon has written, and a test pins the value.-- Keep `gen_ai.usage` as the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacy `llm.usage.*` aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields. `gen_ai.usage.cost_usd` carries runtime-reported cost only and is never written from a price list; list-price estimates are computed only at report time from the embedded catalog (`cli/beacon/internal/pricing`), are always labeled as estimates, and are never stored in events.+- Keep `gen_ai.usage` as the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacy `llm.usage.*` aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields. `gen_ai.usage.cache_creation.ephemeral_1h_input_tokens` (optional, Anthropic's own name) is the subset of `cache_creation.input_tokens` written with a one-hour TTL: a breakdown like `reasoning` inside output, never added to a total, built with `asymptoteobserve.NewCacheCreationUsage` (clamps it to the write count) and differenced with `GenAIUsageCacheCreationInfo.Minus`. It is set by Claude Code session files, Pi-family `cacheWrite1h` and the browser extension's Claude adapter; Claude Code's OTLP export has no split, and reports price unsplit writes at the five-minute rate. `gen_ai.usage.cost_usd` carries runtime-reported cost only and is never written from a price list; list-price estimates are computed only at report time from the embedded catalog (`cli/beacon/internal/pricing`), are always labeled as estimates, and are never stored in events.- `cli/beacon/internal/pricing` estimates list-price cost for reports: integer-microdollar math over the gen_ai.usage counts (disjoint input/output/cache read/cache write, a one-hour write subset, reasoning inside output), long-context bands only for a single request, and a strict model-name ladder (exact, canonical via `NormalizeModelName`, dotted version, Bedrock route prefix, then stripping a `[1m]` marker, snapshot date or effort suffix) that leaves a model unpriced rather than guess, including when two entries tie with different prices. Its `catalog.json` is embedded, offline and report-time only (hooks never import it); it is generated from LiteLLM's MIT-licensed `model_prices_and_context_window.json` and records the upstream URL, commit and fetch/generation dates. Regenerate with `cd cli/beacon && go run ./internal/pricing/internal/gen` (resolves LiteLLM's main with `git ls-remote` and fetches that commit; `-src`/`-commit` for a local copy) and review the one-model-per-line diff; the generator never runs in builds or tests.- When adding a new signal, include stable identifiers/counts/hashes alongside any retained raw content, and route raw fields through redaction, sanitization, truncation, and event-size controls.- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.diff --git a/browser-extension/fixtures/claude/with-cache-ttl.sse b/browser-extension/fixtures/claude/with-cache-ttl.ssenew file mode 100644index 00000000..63665cbd--- /dev/null+++ b/browser-extension/fixtures/claude/with-cache-ttl.sse@@ -0,0 +1,18 @@+event: message_start+data: {"type":"message_start","message":{"id":"chatcompl_REDACTED_TTL","type":"message","role":"assistant","model":"claude-opus-4-8","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":37,"cache_creation_input_tokens":20000,"cache_read_input_tokens":18500,"cache_creation":{"ephemeral_5m_input_tokens":4000,"ephemeral_1h_input_tokens":16000},"output_tokens":1,"service_tier":"standard"}}}++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":{"input_tokens":37,"cache_creation_input_tokens":20000,"cache_read_input_tokens":18500,"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 401a2fc9..ce61c2c6 100644--- a/browser-extension/src/adapters/claude.ts+++ b/browser-extension/src/adapters/claude.ts@@ -2,7 +2,8 @@//// claude.ai streams Server-Sent Events whose `data:` payloads are Anthropic// streaming objects keyed by `type`:-// message_start { message: { model, usage:{input_tokens, cache_creation_input_tokens, cache_read_input_tokens} } }+// message_start { message: { model, usage:{input_tokens, cache_creation_input_tokens, cache_read_input_tokens,+// cache_creation?:{ephemeral_5m_input_tokens, ephemeral_1h_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 }@@ -29,6 +30,7 @@ class ClaudeParser implements TurnParser {private inputTokens?: number;private outputTokens?: number;private cacheCreationInputTokens?: number;+ private cacheCreation1hInputTokens?: number;private cacheReadInputTokens?: number;private startedAt = Date.now();private completedAt?: number;@@ -154,6 +156,11 @@ class ClaudeParser implements TurnParser {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;+ // cache_creation breaks the writes down by TTL. Only the one-hour part is+ // kept: it is billed at 2x input against 1.25x for five-minute writes, and+ // the five-minute part is the remainder.+ if (typeof u.cache_creation?.ephemeral_1h_input_tokens === 'number')+ this.cacheCreation1hInputTokens = u.cache_creation.ephemeral_1h_input_tokens;if (typeof u.cache_read_input_tokens === 'number')this.cacheReadInputTokens = u.cache_read_input_tokens;}@@ -193,6 +200,7 @@ class ClaudeParser implements TurnParser {inputTokens: this.inputTokens,outputTokens: this.outputTokens,cacheCreationInputTokens: this.cacheCreationInputTokens,+ cacheCreation1hInputTokens: this.cacheCreation1hInputTokens,cacheReadInputTokens: this.cacheReadInputTokens,},startedAt: this.startedAt,diff --git a/browser-extension/src/shared/normalize.ts b/browser-extension/src/shared/normalize.tsindex dca9ce15..ca30c99c 100644--- a/browser-extension/src/shared/normalize.ts+++ b/browser-extension/src/shared/normalize.ts@@ -151,10 +151,20 @@ export function normalizeTurn(// 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?.cacheCreationInputTokens != null) {+ const writes = turn.usage.cacheCreationInputTokens;+ respAttrs.push(int('gen_ai.usage.cache_creation.input_tokens', writes));+ // The one-hour subset is a breakdown of the writes, not a fourth count, and+ // can never exceed them.+ const oneHour = turn.usage.cacheCreation1hInputTokens;+ if (oneHour != null)+ respAttrs.push(+ int(+ 'gen_ai.usage.cache_creation.ephemeral_1h_input_tokens',+ Math.min(Math.max(oneHour, 0), Math.max(writes, 0)),+ ),+ );+ }if (turn.usage?.cacheReadInputTokens != null)respAttrs.push(int('gen_ai.usage.cache_read.input_tokens', turn.usage.cacheReadInputTokens));diff --git a/browser-extension/src/shared/types.ts b/browser-extension/src/shared/types.tsindex b0ba6ffc..67b45408 100644--- a/browser-extension/src/shared/types.ts+++ b/browser-extension/src/shared/types.ts@@ -26,6 +26,10 @@ export interface Usage {outputTokens?: number;/** Prompt tokens written to the cache on this turn. */cacheCreationInputTokens?: number;+ /** The subset of cacheCreationInputTokens written with a one-hour TTL. A+ * breakdown, never added to a total; undefined when the stream did not+ * report the split. */+ cacheCreation1hInputTokens?: 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 d4af44c1..4eb09947 100644--- a/browser-extension/test/unit/claude.adapter.test.ts+++ b/browser-extension/test/unit/claude.adapter.test.ts@@ -107,6 +107,37 @@ describe('claude adapter -- usage counts', () => {});});+// The Messages API breaks cache writes down by TTL under usage.cache_creation.+// The one-hour part is billed at 2x input against 1.25x for five-minute writes,+// so it is kept as the subset of cache_creation_input_tokens it is.+describe('claude adapter -- one-hour cache writes', () => {+ const turn = run('with-cache-ttl', 'What is the capital of France?')!.getTurn()!;++ it('captures the one-hour subset beside the write count', () => {+ expect(turn.usage?.cacheCreationInputTokens).toBe(20000);+ expect(turn.usage?.cacheCreation1hInputTokens).toBe(16000);+ });++ it('keeps the subset when message_delta repeats the counts without the breakdown', () => {+ // message_delta repeats the flat counts but not cache_creation; a payload+ // that omits a field must never clear it.+ expect(turn.usage?.outputTokens).toBe(214);+ expect(turn.usage?.cacheCreation1hInputTokens).toBe(16000);+ });++ it('leaves the subset out of the disjoint total', () => {+ const u = turn.usage!;+ const total =+ u.inputTokens! + u.outputTokens! + u.cacheCreationInputTokens! + u.cacheReadInputTokens!;+ expect(total).toBe(37 + 214 + 20000 + 18500);+ });++ it('reports no subset for a stream without the breakdown', () => {+ const plain = run('with-usage', 'What is the capital of France?')!.getTurn()!;+ expect(plain.usage?.cacheCreation1hInputTokens).toBeUndefined();+ });+});+describe('claude adapter -- partial stream usage', () => {it('reports no output tokens when the stream aborts before message_delta', () => {const parser = claudeAdapter.createParser(1);diff --git a/browser-extension/test/unit/normalize.test.ts b/browser-extension/test/unit/normalize.test.tsindex ed4aea5f..c571a36e 100644--- a/browser-extension/test/unit/normalize.test.ts+++ b/browser-extension/test/unit/normalize.test.ts@@ -106,9 +106,31 @@ describe('normalizeTurn — full retention, simple completed turn', () => {expect(r['gen_ai.usage.cache_read.input_tokens']).toBe(18500);});+ it('emits the one-hour cache-write subset, clamped to the write count', () => {+ const emit = (cacheCreationInputTokens: number, cacheCreation1hInputTokens?: number) =>+ flat(+ byAction(+ normalize(+ baseTurn({+ usage: { inputTokens: 37, outputTokens: 214, cacheCreationInputTokens, cacheCreation1hInputTokens },+ }),+ ).logRecords,+ 'agent.response.completed',+ )!.attributes,+ );+ const r = emit(20000, 16000);+ expect(r['gen_ai.usage.cache_creation.input_tokens']).toBe(20000);+ expect(r['gen_ai.usage.cache_creation.ephemeral_1h_input_tokens']).toBe(16000);+ // A breakdown larger than its count is a malformed record, not extra writes.+ expect(emit(500, 900)['gen_ai.usage.cache_creation.ephemeral_1h_input_tokens']).toBe(500);+ // Unreported stays absent, never a guessed zero.+ expect(emit(500)['gen_ai.usage.cache_creation.ephemeral_1h_input_tokens']).toBeUndefined();+ });+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_creation.ephemeral_1h_input_tokens']).toBeUndefined();expect(r['gen_ai.usage.cache_read.input_tokens']).toBeUndefined();});diff --git a/cli/beacon-hooks/cmd/pi_event_test.go b/cli/beacon-hooks/cmd/pi_event_test.goindex 77939d74..733dc5f8 100644--- a/cli/beacon-hooks/cmd/pi_event_test.go+++ b/cli/beacon-hooks/cmd/pi_event_test.go@@ -358,6 +358,47 @@ func TestPiEventMessageEndRecordsUsageAndReasoning(t *testing.T) {}}+// Pi's Usage carries cacheWrite1h, the subset of cacheWrite written with one-hour retention, when+// the provider is Anthropic. It is recorded inside cache_creation as the subset it is, clamped to+// cacheWrite, and left absent when the provider does not report it.+func TestPiEventMessageEndRecordsTheOneHourCacheWriteSplit(t *testing.T) {+ cases := []struct {+ name string+ usage map[string]interface{}+ oneHour interface{} // nil: absent+ }{+ {"anthropic", map[string]interface{}{"input": float64(3), "output": float64(40), "cacheRead": float64(110000),+ "cacheWrite": float64(20000), "cacheWrite1h": float64(16000), "totalTokens": float64(130043)}, float64(16000)},+ {"clamped", map[string]interface{}{"input": float64(3), "output": float64(40),+ "cacheWrite": float64(500), "cacheWrite1h": float64(900), "totalTokens": float64(543)}, float64(500)},+ {"not reported", map[string]interface{}{"input": float64(3), "output": float64(40),+ "cacheWrite": float64(500), "totalTokens": float64(543)}, nil},+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ logPath := piTestLog(t)+ runHookWithInput(t, runPiEvent, map[string]interface{}{+ "type": "message_end", "sessionId": "sess-1",+ "message": map[string]interface{}{"role": "assistant", "model": "claude-opus-4-6", "usage": tc.usage},+ })+ got := nested(t, piEventWithAction(t, logPath, "token.usage"), "gen_ai", "usage", "cache_creation")+ if got["input_tokens"] != tc.usage["cacheWrite"] {+ t.Fatalf("cache_creation = %v, want input_tokens %v", got, tc.usage["cacheWrite"])+ }+ oneHour, present := got["ephemeral_1h_input_tokens"]+ if tc.oneHour == nil {+ if present {+ t.Fatalf("cache_creation = %v, want no one-hour split", got)+ }+ return+ }+ if oneHour != tc.oneHour {+ t.Fatalf("cache_creation = %v, want ephemeral_1h_input_tokens %v", got, tc.oneHour)+ }+ })+ }+}+// message_end fires for user and toolResult messages too. Emitting a row for each would put an// empty usage record in the log on every turn.func TestPiEventMessageEndIgnoresNonAssistantMessages(t *testing.T) {diff --git a/cli/beacon-hooks/cmd/pi_family.go b/cli/beacon-hooks/cmd/pi_family.goindex fabf94ff..7410449d 100644--- a/cli/beacon-hooks/cmd/pi_family.go+++ b/cli/beacon-hooks/cmd/pi_family.go@@ -765,7 +765,14 @@ func piUsage(usage map[string]interface{}) map[string]interface{} {out["cache_read"] = map[string]interface{}{"input_tokens": value}}if value, ok := firstToolIntAcross(sources, "cacheWrite"); ok {- out["cache_creation"] = map[string]interface{}{"input_tokens": value}+ creation := map[string]interface{}{"input_tokens": value}+ // cacheWrite1h is the subset of cacheWrite written with one-hour retention, which Pi fills+ // only for Anthropic (billed at 2x input against 1.25x for five-minute writes). It is a+ // breakdown inside cache_creation, never a count of its own, and cannot exceed cacheWrite.+ if oneHour, ok := firstToolIntAcross(sources, "cacheWrite1h"); ok {+ creation["ephemeral_1h_input_tokens"] = min(max(oneHour, 0), max(value, 0))+ }+ out["cache_creation"] = creation}if value, ok := firstToolIntAcross(sources, "reasoning"); ok {out["reasoning"] = map[string]interface{}{"output_tokens": value}diff --git a/cli/beacon/cmd/token_usage_cost_test.go b/cli/beacon/cmd/token_usage_cost_test.goindex 2e25c963..1ddb9e06 100644--- a/cli/beacon/cmd/token_usage_cost_test.go+++ b/cli/beacon/cmd/token_usage_cost_test.go@@ -60,7 +60,7 @@ func TestTokenUsageTextLabelsReportedAndEstimatedCost(t *testing.T) {"EST COST USD","COST USD is what the runtimes reported","list price",- "1h cache writes are priced at the 5m rate",+ "cache writes are priced at the 5m rate unless the source reported them as 1h writes",// 100 input + 40 output tokens of claude-sonnet-4-5 at $3/$15 per MTok."0.0009",} {diff --git a/cli/beacon/internal/claudesession/cache1h_test.go b/cli/beacon/internal/claudesession/cache1h_test.gonew file mode 100644index 00000000..4e861567--- /dev/null+++ b/cli/beacon/internal/claudesession/cache1h_test.go@@ -0,0 +1,88 @@+package claudesession++import (+ "encoding/json"+ "testing"+)++// claudeUsageLine is an assistant record carrying usage exactly as Claude Code writes it to the+// session file: the API response's usage block, including the per-TTL cache_creation breakdown+// beside the flat cache_creation_input_tokens count.+func claudeUsageLine(uuid, usage string) string {+ return `{"parentUuid":"u1","isSidechain":false,"type":"assistant","message":{"model":"claude-opus-4-6","id":"msg_` + uuid + `","type":"message","role":"assistant","content":[{"type":"text","text":"done"}],"stop_reason":"end_turn","usage":` + usage + `},"uuid":` + quote(uuid) + `,"timestamp":"2026-09-19T22:00:01.000Z","cwd":"/tmp/repo","sessionId":"sess-1","version":"2.1.154","gitBranch":"main"}`+}++func mappedCacheCreation(t *testing.T, usage string) map[string]interface{} {+ t.Helper()+ ref := SessionRef{ID: "sess-1", Path: "/tmp/sess-1.jsonl", ProjectPath: "/tmp/repo"}+ mapped := MapSession(ref, decodeFixture(t, []string{claudeUsageLine("a1", usage)}), MapOptions{})+ ev := findAction(t, mapped, "token.usage")+ encoded, err := json.Marshal(ev)+ if err != nil {+ t.Fatal(err)+ }+ var decoded struct {+ GenAI struct {+ Usage struct {+ CacheCreation map[string]interface{} `json:"cache_creation"`+ } `json:"usage"`+ } `json:"gen_ai"`+ }+ if err := json.Unmarshal(encoded, &decoded); err != nil {+ t.Fatal(err)+ }+ return decoded.GenAI.Usage.CacheCreation+}++func TestUsageCarriesTheOneHourCacheWriteSplit(t *testing.T) {+ cases := []struct {+ name string+ usage string+ total interface{}+ oneHour interface{} // nil: absent+ }{+ {+ name: "one-hour and five-minute writes",+ usage: `{"input_tokens":3,"cache_creation_input_tokens":20000,"cache_read_input_tokens":110000,"cache_creation":{"ephemeral_5m_input_tokens":4000,"ephemeral_1h_input_tokens":16000},"output_tokens":120,"service_tier":"standard"}`,+ total: float64(20000),+ oneHour: float64(16000),+ },+ {+ name: "all five-minute writes",+ usage: `{"input_tokens":3,"cache_creation_input_tokens":500,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":500,"ephemeral_1h_input_tokens":0},"output_tokens":5}`,+ total: float64(500),+ oneHour: float64(0),+ },+ {+ // Older Claude Code builds wrote no breakdown; absent stays absent, not zero.+ name: "no breakdown",+ usage: `{"input_tokens":3,"cache_creation_input_tokens":500,"output_tokens":5}`,+ total: float64(500),+ },+ {+ // A breakdown larger than the count it breaks down is clamped to the count.+ name: "breakdown exceeds the write count",+ usage: `{"input_tokens":3,"cache_creation_input_tokens":500,"cache_creation":{"ephemeral_1h_input_tokens":900},"output_tokens":5}`,+ total: float64(500),+ oneHour: float64(500),+ },+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ got := mappedCacheCreation(t, tc.usage)+ if got["input_tokens"] != tc.total {+ t.Fatalf("cache_creation = %v, want input_tokens %v", got, tc.total)+ }+ oneHour, present := got["ephemeral_1h_input_tokens"]+ if tc.oneHour == nil {+ if present {+ t.Fatalf("cache_creation = %v, want no one-hour split", got)+ }+ return+ }+ if oneHour != tc.oneHour {+ t.Fatalf("cache_creation = %v, want ephemeral_1h_input_tokens %v", got, tc.oneHour)+ }+ })+ }+}diff --git a/cli/beacon/internal/claudesession/mapper.go b/cli/beacon/internal/claudesession/mapper.goindex cc91da16..bf38699e 100644--- a/cli/beacon/internal/claudesession/mapper.go+++ b/cli/beacon/internal/claudesession/mapper.go@@ -357,7 +357,15 @@ func usageFromMessage(message map[string]interface{}) *schema.GenAIUsageInfo {usage.OutputTokens = &v}if v, ok := int64Value(firstValue(raw, "cache_creation_input_tokens", "cache_creation_tokens")); ok {- usage.CacheCreation = &schema.GenAIUsageCacheCreationInfo{InputTokens: &v}+ // The API response breaks cache writes down by TTL under cache_creation. Only the+ // one-hour part is kept: it is billed at 2x input against 1.25x for five-minute writes,+ // and the five-minute part is the remainder. Builds that write no breakdown leave the+ // split absent rather than zero.+ var oneHour *int64+ if h, ok := int64Value(mapValue(raw["cache_creation"])["ephemeral_1h_input_tokens"]); ok {+ oneHour = &h+ }+ usage.CacheCreation = asymptoteobserve.NewCacheCreationUsage(v, oneHour)}if v, ok := int64Value(firstValue(raw, "cache_read_input_tokens", "cache_read_tokens")); ok {usage.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: &v}diff --git a/cli/beacon/internal/endpoint/dashboard/history_store.go b/cli/beacon/internal/endpoint/dashboard/history_store.goindex ce798fe9..d94cb5b2 100644--- a/cli/beacon/internal/endpoint/dashboard/history_store.go+++ b/cli/beacon/internal/endpoint/dashboard/history_store.go@@ -41,12 +41,12 @@ const (// historyDerivationVersion covers everything computed from a stored line: trace keys, event// numbers, types, summaries and search text. Bump it when that projection changes; the next// catch-up recomputes it from the stored lines, so history survives the change.- historyDerivationVersion = 3 // 2: trace events carry the event's policy block; 3: and its error+ historyDerivationVersion = 4 // 2: trace events carry the event's policy block; 3: and its error; 4: usage carries the 1h cache-write splitdefaultHistoryRetentionDays = 90// maxHistoryRetentionDays is 100 years: a retention this long or longer means nothing expires.maxHistoryRetentionDays = 100 * 365- defaultHistoryMaxBytes = int64(1) << 30+ defaultHistoryMaxBytes = int64(1) << 30// historyMaxLineBytes matches the JSONL scanner's line limit, so a line too long for one path// is skipped by the other rather than read by only one of them.diff --git a/cli/beacon/internal/endpoint/dashboard/lens_data.go b/cli/beacon/internal/endpoint/dashboard/lens_data.goindex aab25771..467e9873 100644--- a/cli/beacon/internal/endpoint/dashboard/lens_data.go+++ b/cli/beacon/internal/endpoint/dashboard/lens_data.go@@ -140,12 +140,13 @@ func lensTokenUsage(raw []schema.Event) *asymptoteobserve.LensTokenUsageV1 {func lensUsage(u tokens.Usage) TraceUsageV1 {return TraceUsageV1{- InputTokens: u.InputTokens,- OutputTokens: u.OutputTokens,- CacheReadInputTokens: u.CacheReadInputTokens,- CacheCreationInputTokens: u.CacheCreationInputTokens,- ReasoningOutputTokens: u.ReasoningOutputTokens,- CostUSD: u.CostUSD,+ InputTokens: u.InputTokens,+ OutputTokens: u.OutputTokens,+ CacheReadInputTokens: u.CacheReadInputTokens,+ CacheCreationInputTokens: u.CacheCreationInputTokens,+ CacheCreation1hInputTokens: u.CacheCreation1hInputTokens,+ ReasoningOutputTokens: u.ReasoningOutputTokens,+ CostUSD: u.CostUSD,}}diff --git a/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.md b/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.mdindex f75ceed5..da25cf84 100644--- a/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.md+++ b/cli/beacon/internal/endpoint/dashboard/lenses/SPEC.md@@ -250,3 +250,6 @@ The host enforces these rules; a lens does not opt into them.- `lenses/v1`: initial specification.- `lenses/v1` (additive): `token_usage`, the counted usage of the trace.- `lenses/v1` (additive): `trace.events[].error`, the failure an event recorded.+- `lenses/v1` (additive): `cache_creation_1h_input_tokens` in every usage object,+ the subset of `cache_creation_input_tokens` written with a one-hour TTL where+ the source reported it. It is a breakdown; never add it to a total.diff --git a/cli/beacon/internal/endpoint/dashboard/trace_usage_cache1h_test.go b/cli/beacon/internal/endpoint/dashboard/trace_usage_cache1h_test.gonew file mode 100644index 00000000..062f1bfd--- /dev/null+++ b/cli/beacon/internal/endpoint/dashboard/trace_usage_cache1h_test.go@@ -0,0 +1,40 @@+package dashboard++import (+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"+)++// Trace usage carries the one-hour cache-write subset beside the write count, clamped to it, and+// sums it with the writes it belongs to.+func TestTraceUsageCarriesTheOneHourCacheWriteSubset(t *testing.T) {+ event := func(total, oneHour int64) schema.Event {+ claimed := oneHour+ return schema.Event{GenAI: &schema.GenAIInfo{Usage: &schema.GenAIUsageInfo{+ CacheCreation: &schema.GenAIUsageCacheCreationInfo{InputTokens: &total, Ephemeral1hInputTokens: &claimed},+ }}}+ }+ first := traceUsage(event(20000, 16000))+ if first == nil || first.CacheCreationInputTokens != 20000 || first.CacheCreation1hInputTokens != 16000 {+ t.Fatalf("usage = %+v, want 20000 writes of which 16000 one-hour", first)+ }+ // A log line claiming more one-hour writes than writes is clamped.+ second := traceUsage(event(500, 900))+ if second == nil || second.CacheCreation1hInputTokens != 500 {+ t.Fatalf("usage = %+v, want the subset clamped to 500", second)+ }+ sum := TraceUsageV1{}+ addTraceUsage(&sum, *first)+ addTraceUsage(&sum, *second)+ if sum.CacheCreationInputTokens != 20500 || sum.CacheCreation1hInputTokens != 16500 {+ t.Fatalf("sum = %+v", sum)+ }+ unsplit := traceUsage(schema.Event{GenAI: &schema.GenAIInfo{Usage: &schema.GenAIUsageInfo{+ CacheCreation: asymptoteobserve.NewCacheCreationUsage(300, nil),+ }}})+ if unsplit == nil || unsplit.CacheCreation1hInputTokens != 0 {+ t.Fatalf("usage = %+v, want no subset when unreported", unsplit)+ }+}diff --git a/cli/beacon/internal/endpoint/dashboard/traces.go b/cli/beacon/internal/endpoint/dashboard/traces.goindex db517eae..c6054627 100644--- a/cli/beacon/internal/endpoint/dashboard/traces.go+++ b/cli/beacon/internal/endpoint/dashboard/traces.go@@ -848,6 +848,7 @@ func traceUsage(event schema.Event) *TraceUsageV1 {}if usage.CacheCreation != nil && usage.CacheCreation.InputTokens != nil {out.CacheCreationInputTokens = *usage.CacheCreation.InputTokens+ out.CacheCreation1hInputTokens = usage.CacheCreation.OneHourInputTokens()}if usage.Reasoning != nil && usage.Reasoning.OutputTokens != nil {out.ReasoningOutputTokens = *usage.Reasoning.OutputTokens@@ -870,6 +871,7 @@ func addTraceUsage(u *TraceUsageV1, delta TraceUsageV1) {u.OutputTokens += delta.OutputTokensu.CacheReadInputTokens += delta.CacheReadInputTokensu.CacheCreationInputTokens += delta.CacheCreationInputTokens+ u.CacheCreation1hInputTokens += delta.CacheCreation1hInputTokensu.ReasoningOutputTokens += delta.ReasoningOutputTokensu.CostUSD += delta.CostUSD}diff --git a/cli/beacon/internal/pisession/cache1h_test.go b/cli/beacon/internal/pisession/cache1h_test.gonew file mode 100644index 00000000..400cdff3--- /dev/null+++ b/cli/beacon/internal/pisession/cache1h_test.go@@ -0,0 +1,54 @@+package pisession++import (+ "encoding/json"+ "testing"+)++// Pi's Usage type carries cacheWrite1h, the subset of cacheWrite written with one-hour retention,+// which its Anthropic provider fills from usage.cache_creation.ephemeral_1h_input_tokens. The+// session file stores the assistant message's usage as written.+func TestPiUsageCarriesTheOneHourCacheWriteSplit(t *testing.T) {+ cases := []struct {+ name string+ usage string+ oneHour *int64+ }{+ {+ name: "anthropic with one-hour writes",+ usage: `{"input":3,"output":120,"cacheRead":110000,"cacheWrite":20000,"cacheWrite1h":16000,"totalTokens":130123,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0.21}}`,+ oneHour: int64p(16000),+ },+ {+ // Providers other than Anthropic leave the field out.+ name: "no split",+ usage: `{"input":3,"output":120,"cacheRead":0,"cacheWrite":500,"totalTokens":623,"cost":{"total":0.01}}`,+ },+ {+ name: "split exceeds cacheWrite",+ usage: `{"input":3,"output":1,"cacheRead":0,"cacheWrite":500,"cacheWrite1h":900,"totalTokens":504,"cost":{"total":0.01}}`,+ oneHour: int64p(500),+ },+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ var raw map[string]interface{}+ if err := json.Unmarshal([]byte(tc.usage), &raw); err != nil {+ t.Fatal(err)+ }+ usage := piUsage(raw)+ if usage == nil || usage.CacheCreation == nil || usage.CacheCreation.InputTokens == nil {+ t.Fatalf("usage = %+v, want cache writes", usage)+ }+ got := usage.CacheCreation.Ephemeral1hInputTokens+ switch {+ case tc.oneHour == nil && got != nil:+ t.Fatalf("one-hour split = %d, want absent", *got)+ case tc.oneHour != nil && (got == nil || *got != *tc.oneHour):+ t.Fatalf("one-hour split = %v, want %d", got, *tc.oneHour)+ }+ })+ }+}++func int64p(v int64) *int64 { return &v }diff --git a/cli/beacon/internal/pisession/mapper.go b/cli/beacon/internal/pisession/mapper.goindex a4a88255..2be974ca 100644--- a/cli/beacon/internal/pisession/mapper.go+++ b/cli/beacon/internal/pisession/mapper.go@@ -533,7 +533,13 @@ func piUsage(usage map[string]interface{}) *schema.GenAIUsageInfo {out.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: &value}}if value, ok := int64Value(usage["cacheWrite"]); ok {- out.CacheCreation = &schema.GenAIUsageCacheCreationInfo{InputTokens: &value}+ // cacheWrite1h is the subset of cacheWrite written with one-hour retention, which only+ // Anthropic reports; it stays absent for every other provider.+ var oneHour *int64+ if h, ok := int64Value(usage["cacheWrite1h"]); ok {+ oneHour = &h+ }+ out.CacheCreation = asymptoteobserve.NewCacheCreationUsage(value, oneHour)}if value, ok := int64Value(usage["reasoning"]); ok {out.Reasoning = &schema.GenAIUsageReasoningInfo{OutputTokens: &value}diff --git a/cli/beacon/internal/pricing/doc.go b/cli/beacon/internal/pricing/doc.goindex 52540152..66551a2c 100644--- a/cli/beacon/internal/pricing/doc.go+++ b/cli/beacon/internal/pricing/doc.go@@ -32,9 +32,9 @@// never also inside Input (Beacon subtracts them on the runtimes that report input// inclusively, Codex among them).// - CacheCreation is every token written to the prompt cache. CacheCreation1h is the subset-// of those written with a one-hour TTL, so it is clamped to CacheCreation. gen_ai.usage does-// not carry the one-hour split today, so callers working from it leave the field zero and-// every write is priced at the five-minute rate.+// of those written with a one-hour TTL, so it is clamped to CacheCreation. It comes from+// gen_ai.usage.cache_creation.ephemeral_1h_input_tokens, which only some sources report;+// where it is absent the field is zero and every write is priced at the five-minute rate.// - Reasoning is a breakdown of Output, not an addition to it. That is the gen_ai.usage// contract (reasoning.output_tokens is a sub-field of output, as in the OTel GenAI// semantic conventions), and docs/cli/token-usage.mdx says reasoning tokens "must not bediff --git a/cli/beacon/internal/tokens/cache1h_test.go b/cli/beacon/internal/tokens/cache1h_test.gonew file mode 100644index 00000000..6c82b8a1--- /dev/null+++ b/cli/beacon/internal/tokens/cache1h_test.go@@ -0,0 +1,183 @@+package tokens++import (+ "encoding/json"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"+)++// decodeEvents reads JSONL-shaped events the way the report does, so these tests exercise the+// wire field rather than a Go struct literal.+func decodeEvents(t *testing.T, lines ...string) []schema.Event {+ t.Helper()+ out := make([]schema.Event, 0, len(lines))+ for _, line := range lines {+ var event schema.Event+ if err := json.Unmarshal([]byte(line), &event); err != nil {+ t.Fatalf("decode %s: %v", line, err)+ }+ out = append(out, event)+ }+ return out+}++// claudePollLine is a Claude Code session-file token.usage event (one API response, so request+// scoped) on claude-opus-4-6: $5 in, $25 out, $0.50 cache read, $6.25 five-minute cache write and+// $10 one-hour cache write per MTok.+func claudePollLine(ts, cacheCreation string) string {+ return `{"timestamp":"` + ts + `","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},` ++ `"harness":{"name":"claude_code","collection_method":"poll"},"session":{"id":"s1"},"model":"claude-opus-4-6",` ++ `"gen_ai":{"usage":{"input_tokens":10,"output_tokens":100,"cache_creation":` + cacheCreation + `}}}`+}++func TestEstimatePricesOneHourCacheWritesAtTheOneHourRate(t *testing.T) {+ cases := []struct {+ name string+ cacheCreation string+ // microdollars, worked by hand: 10x5 + 100x25 = 2550 for input and output, plus the writes.+ estimated int64+ oneHour int64+ }{+ {+ // 4000 five-minute writes x $6.25 + 16000 one-hour writes x $10 = 25000 + 160000.+ name: "split reported",+ cacheCreation: `{"input_tokens":20000,"ephemeral_1h_input_tokens":16000}`,+ estimated: 2550 + 25000 + 160000,+ oneHour: 16000,+ },+ {+ // Without the split every write is a five-minute write: 20000 x $6.25.+ name: "split not reported",+ cacheCreation: `{"input_tokens":20000}`,+ estimated: 2550 + 125000,+ },+ {+ // A breakdown cannot exceed the count it breaks down: all 20000 are one-hour writes.+ name: "split larger than the write count is clamped",+ cacheCreation: `{"input_tokens":20000,"ephemeral_1h_input_tokens":30000}`,+ estimated: 2550 + 200000,+ oneHour: 20000,+ },+ {+ name: "negative split is ignored",+ cacheCreation: `{"input_tokens":20000,"ephemeral_1h_input_tokens":-5}`,+ estimated: 2550 + 125000,+ },+ {+ name: "zero split",+ cacheCreation: `{"input_tokens":20000,"ephemeral_1h_input_tokens":0}`,+ estimated: 2550 + 125000,+ },+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ report := Aggregate(decodeEvents(t, claudePollLine("2026-06-11T10:00:00Z", tc.cacheCreation)), Options{})+ got := report.Totals+ if got.estimated != pricing.Microdollars(tc.estimated) {+ t.Fatalf("estimated = %d, want %d", got.estimated, tc.estimated)+ }+ if got.CacheCreation1hInputTokens != tc.oneHour {+ t.Fatalf("cache_creation_1h_input_tokens = %d, want %d", got.CacheCreation1hInputTokens, tc.oneHour)+ }+ // The subset is a breakdown, never an addition to the total.+ if got.TotalTokens() != 10+100+20000 {+ t.Fatalf("total tokens = %d, want the one-hour subset left out", got.TotalTokens())+ }+ })+ }+}++// Repeated events sum the subset with the count it belongs to, and the report JSON carries it+// only when it is non-zero, so reports over sources without the split are unchanged.+func TestOneHourSubsetSumsAndIsOmittedWhenAbsent(t *testing.T) {+ report := Aggregate(decodeEvents(t,+ claudePollLine("2026-06-11T10:00:00Z", `{"input_tokens":20000,"ephemeral_1h_input_tokens":16000}`),+ claudePollLine("2026-06-11T10:00:01Z", `{"input_tokens":1000,"ephemeral_1h_input_tokens":1000}`),+ claudePollLine("2026-06-11T10:00:02Z", `{"input_tokens":500}`),+ ), Options{})+ if got := report.Totals; got.CacheCreationInputTokens != 21500 || got.CacheCreation1hInputTokens != 17000 {+ t.Fatalf("totals = %+v, want 21500 writes of which 17000 one-hour", got)+ }+ // 2550x3 + (4000+0+500)x6.25 + 17000x10 = 7650 + 28125 + 170000.+ if got := report.Totals.estimated; got != 205775 {+ t.Fatalf("estimated = %d, want 205775", got)+ }+ encoded, _ := json.Marshal(report.Totals)+ var totals map[string]interface{}+ _ = json.Unmarshal(encoded, &totals)+ if totals["cache_creation_1h_input_tokens"] != float64(17000) {+ t.Fatalf("totals JSON = %s", encoded)+ }++ plain := Aggregate(decodeEvents(t, claudePollLine("2026-06-11T10:00:00Z", `{"input_tokens":500}`)), Options{})+ encoded, _ = json.Marshal(plain.Totals)+ totals = map[string]interface{}{}+ _ = json.Unmarshal(encoded, &totals)+ if _, ok := totals["cache_creation_1h_input_tokens"]; ok {+ t.Fatalf("an unreported split must stay absent: %s", encoded)+ }+}++// When a log channel and a metric channel both report cache writes, the metric's writes are+// removed field by field. The one-hour subset is part of those writes and goes with them, or the+// report would be left with one-hour writes larger than its writes.+func TestChannelDedupDropsTheOneHourSubsetWithItsWrites(t *testing.T) {+ report := Aggregate(decodeEvents(t,+ `{"timestamp":"2026-06-11T10:00:00Z","event":{"kind":"agent_runtime","action":"tool.invoked","category":"metric"},`++ `"message":"claude_code.api_request","harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"s1"},`++ `"model":"claude-opus-4-6","gen_ai":{"usage":{"input_tokens":10,"cache_creation":{"input_tokens":20000}}}}`,+ `{"timestamp":"2026-06-11T10:00:05Z","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},`++ `"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"s1"},"model":"claude-opus-4-6",`++ `"raw":{"metric_name":"claude_code.token.usage","metric_temporality":"delta"},`++ `"gen_ai":{"usage":{"cache_creation":{"input_tokens":20000,"ephemeral_1h_input_tokens":20000}}}}`,+ ), Options{})+ if got := report.Totals; got.CacheCreationInputTokens != 20000 || got.CacheCreation1hInputTokens != 0 {+ t.Fatalf("totals = %+v, want the metric's writes and their one-hour subset removed", got)+ }+}++// A cumulative series of cache writes is differenced, and its one-hour subset is differenced with+// it, including across a counter reset.+func TestCumulativeCacheWritesDifferenceTheOneHourSubset(t *testing.T) {+ line := func(ts string, total, oneHour int) string {+ return `{"timestamp":"` + ts + `","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},` ++ `"harness":{"name":"example_runtime","collection_method":"otlp"},"session":{"id":"s1"},"model":"claude-opus-4-6",` ++ `"raw":{"metric_name":"example.token.usage","metric_temporality":"cumulative"},` ++ `"gen_ai":{"usage":{"cache_creation":{"input_tokens":` + itoa(total) + `,"ephemeral_1h_input_tokens":` + itoa(oneHour) + `}}}}`+ }+ report := Aggregate(decodeEvents(t,+ line("2026-06-11T10:00:00Z", 1000, 800),+ line("2026-06-11T10:01:00Z", 3000, 1800),+ // Counter reset: the raw values are the new interval's totals.+ line("2026-06-11T10:02:00Z", 500, 500),+ ), Options{})+ // Deltas: (1000, 800), (2000, 1000), (500, 500).+ if got := report.Totals; got.CacheCreationInputTokens != 3500 || got.CacheCreation1hInputTokens != 2300 {+ t.Fatalf("totals = %+v, want 3500 writes of which 2300 one-hour", got)+ }+}++// A model with no published one-hour write rate prices its one-hour writes at the five-minute+// rate and names that fallback. anthropic.claude-3-5-haiku-20241022-v1:0 (Bedrock): $0.80 in,+// $4 out, $1 cache write, no one-hour rate.+func TestOneHourWritesWithoutAPublishedRateNameTheFallback(t *testing.T) {+ line := `{"timestamp":"2026-06-11T10:00:00Z","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},` ++ `"harness":{"name":"claude_code","collection_method":"poll"},"session":{"id":"s1"},"model":"anthropic.claude-3-5-haiku-20241022-v1:0",` ++ `"gen_ai":{"usage":{"input_tokens":1000,"cache_creation":{"input_tokens":2000,"ephemeral_1h_input_tokens":2000}}}}`+ report := Aggregate(decodeEvents(t, line), Options{})+ // 1000 x 0.80 + 2000 x 1.00 = 2800 microdollars.+ if got := report.Totals.estimated; got != 2800 {+ t.Fatalf("estimated = %d, want 2800", got)+ }+ if len(report.Pricing.Models) != 1 || len(report.Pricing.Models[0].Fallbacks) != 1 ||+ report.Pricing.Models[0].Fallbacks[0] != "cache_write_1h_at_write_rate" {+ t.Fatalf("pricing models = %+v, want the one-hour fallback named", report.Pricing.Models)+ }+}++func itoa(v int) string {+ b, _ := json.Marshal(v)+ return string(b)+}diff --git a/cli/beacon/internal/tokens/cost.go b/cli/beacon/internal/tokens/cost.goindex 87888259..e3c6033e 100644--- a/cli/beacon/internal/tokens/cost.go+++ b/cli/beacon/internal/tokens/cost.go@@ -96,7 +96,8 @@ type ModelPricing struct {RequestScopedEvents int `json:"request_scoped_events"`BandsApplied []BandUse `json:"bands_applied,omitempty"`// Fallbacks names each missing-rate fallback that priced a non-zero count:- // cache_read_at_input_rate, cache_write_at_input_rate, reasoning_at_output_rate.+ // cache_read_at_input_rate, cache_write_at_input_rate, cache_write_1h_at_write_rate,+ // reasoning_at_output_rate.Fallbacks []string `json:"fallbacks,omitempty"`EstimatedCostUSD float64 `json:"estimated_cost_usd"`@@ -270,9 +271,9 @@ func priceUsageEvents(events []*usageEvent, catalog *pricing.Catalog) *PricingSuOutput: u.OutputTokens,CacheRead: u.CacheReadInputTokens,CacheCreation: u.CacheCreationInputTokens,- // gen_ai.usage does not carry the one-hour cache-write split yet, so every- // write is priced at the five-minute rate.- CacheCreation1h: 0,+ // Zero for sources that do not report the TTL split, whose writes are all+ // priced at the five-minute rate.+ CacheCreation1h: u.CacheCreation1hInputTokens,Reasoning: u.ReasoningOutputTokens,}, scoped)// A saturated estimate means the counts are corrupt; it is not a price.@@ -353,6 +354,9 @@ func recordModelPricing(m *ModelPricing, model string, res pricing.Resolution, sif est.CacheWriteAtInputRate {m.fallbacks["cache_write_at_input_rate"] = true}+ if est.CacheWrite1hAtWriteRate {+ m.fallbacks["cache_write_1h_at_write_rate"] = true+ }if est.ReasoningAtOutputRate {m.fallbacks["reasoning_at_output_rate"] = true}diff --git a/cli/beacon/internal/tokens/report.go b/cli/beacon/internal/tokens/report.goindex 0a7c427a..6b489136 100644--- a/cli/beacon/internal/tokens/report.go+++ b/cli/beacon/internal/tokens/report.go@@ -159,7 +159,7 @@ func writePricingFooter(w io.Writer, report Report) {fmt.Fprintln(w, "COST USD is what the runtimes reported. EST COST USD is an estimate at list price:")fmt.Fprintf(w, " prices from %s (%s);\n", catalog.Name, provenance)fmt.Fprintf(w, " %s tier, no batch, priority or subscription discounts;\n", report.Pricing.Tier)- fmt.Fprintln(w, " 1h cache writes are priced at the 5m rate until Beacon captures the split.")+ fmt.Fprintln(w, " cache writes are priced at the 5m rate unless the source reported them as 1h writes.")totals := report.Totalsfmt.Fprintf(w, "Effective cost (reported where the runtime reported one, the estimate elsewhere): %s USD",effectiveString(totals))diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.goindex 26dd5517..f510f812 100644--- a/cli/beacon/internal/tokens/tokens.go+++ b/cli/beacon/internal/tokens/tokens.go@@ -32,18 +32,22 @@ const defaultNearLimitRatio = 0.8// UnpricedEvents and UnpricedTokens count what the estimate is missing: usage whose model the// catalog does not price.type Usage struct {- InputTokens int64 `json:"input_tokens"`- OutputTokens int64 `json:"output_tokens"`- CacheReadInputTokens int64 `json:"cache_read_input_tokens"`- CacheCreationInputTokens int64 `json:"cache_creation_input_tokens"`- ReasoningOutputTokens int64 `json:"reasoning_output_tokens"`- CostUSD float64 `json:"cost_usd"`- EstimatedCostUSD float64 `json:"estimated_cost_usd"`- EffectiveCostUSD float64 `json:"effective_cost_usd"`- CostSource string `json:"cost_source,omitempty"`- UnpricedEvents int `json:"unpriced_events,omitempty"`- UnpricedTokens int64 `json:"unpriced_tokens,omitempty"`- Events int `json:"events"`+ InputTokens int64 `json:"input_tokens"`+ OutputTokens int64 `json:"output_tokens"`+ CacheReadInputTokens int64 `json:"cache_read_input_tokens"`+ CacheCreationInputTokens int64 `json:"cache_creation_input_tokens"`+ // CacheCreation1hInputTokens is the subset of CacheCreationInputTokens written with a+ // one-hour TTL, from gen_ai.usage.cache_creation.ephemeral_1h_input_tokens. It is a breakdown+ // like ReasoningOutputTokens: never part of TotalTokens, and omitted when no source reported it.+ CacheCreation1hInputTokens int64 `json:"cache_creation_1h_input_tokens,omitempty"`+ ReasoningOutputTokens int64 `json:"reasoning_output_tokens"`+ CostUSD float64 `json:"cost_usd"`+ EstimatedCostUSD float64 `json:"estimated_cost_usd"`+ EffectiveCostUSD float64 `json:"effective_cost_usd"`+ CostSource string `json:"cost_source,omitempty"`+ UnpricedEvents int `json:"unpriced_events,omitempty"`+ UnpricedTokens int64 `json:"unpriced_tokens,omitempty"`+ Events int `json:"events"`// The exported cost fields above are derived from these by settle, so sums stay exact:// estimates are summed in integer microdollars and converted once, and the effective cost@@ -64,6 +68,7 @@ func (u *Usage) add(delta Usage) {u.OutputTokens += delta.OutputTokensu.CacheReadInputTokens += delta.CacheReadInputTokensu.CacheCreationInputTokens += delta.CacheCreationInputTokens+ u.CacheCreation1hInputTokens += delta.CacheCreation1hInputTokensu.ReasoningOutputTokens += delta.ReasoningOutputTokensu.CostUSD += delta.CostUSDu.UnpricedEvents += delta.UnpricedEvents@@ -531,6 +536,8 @@ func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []}if usage.CacheCreation != nil && usage.CacheCreation.InputTokens != nil {ue.usage.CacheCreationInputTokens = *usage.CacheCreation.InputTokens+ // Clamped to the write count it is a subset of.+ ue.usage.CacheCreation1hInputTokens = usage.CacheCreation.OneHourInputTokens()}if usage.Reasoning != nil && usage.Reasoning.OutputTokens != nil {ue.usage.ReasoningOutputTokens = *usage.Reasoning.OutputTokens@@ -684,7 +691,9 @@ func dedupeOverlappingChannels(events []*usageEvent) []*usageEvent {ue.usage.CacheReadInputTokens = 0}if fs.cacheCreation {+ // The one-hour subset is part of the writes, not a field of its own.ue.usage.CacheCreationInputTokens = 0+ ue.usage.CacheCreation1hInputTokens = 0}if fs.reasoning {ue.usage.ReasoningOutputTokens = 0@@ -730,14 +739,27 @@ func resolveCumulativeSeries(events []*usageEvent) {return points[i].ts.Before(points[j].ts)})previous := 0.0+ var previous1h int64for _, point := range points {delta := point.seriesValue - previous- if delta < 0 {+ reset := delta < 0+ if reset {// Counter reset: the raw value is the new interval's total.delta = point.seriesValue}previous = point.seriesValue+ oneHour := point.usage.CacheCreation1hInputTokenssetUsageField(&point.usage, point.seriesField, delta)+ if point.seriesField == "cache_creation_input_tokens" {+ // The one-hour subset of a cumulative write counter is cumulative too, and is+ // differenced alongside it, resetting when the counter does.+ delta1h := oneHour+ if !reset {+ delta1h -= previous1h+ }+ previous1h = oneHour+ point.usage.CacheCreation1hInputTokens = min(max(delta1h, 0), point.usage.CacheCreationInputTokens)+ }}}}diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.goindex 7af807ef..70b8ebc6 100644--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter.go@@ -1362,7 +1362,13 @@ func GenAIToolFromAttrs(attrs map[string]interface{}) *GenAIToolInfo {func GenAIUsageFromAttrs(attrs map[string]interface{}) *GenAIUsageInfo {usage := &GenAIUsageInfo{}if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_creation.input_tokens", "gen_ai.usage.cache_creation_input_tokens", "cache_creation_tokens"); ok {- usage.CacheCreation = &GenAIUsageCacheCreationInfo{InputTokens: &value}+ // The one-hour subset of the writes, from the browser extension's Claude adapter.+ // Claude Code's own api_request log reports only the cache_creation_tokens total.+ var oneHour *int64+ if h, ok := Int64Attr(attrs, "gen_ai.usage.cache_creation.ephemeral_1h_input_tokens"); ok {+ oneHour = &h+ }+ usage.CacheCreation = asymptoteobserve.NewCacheCreationUsage(value, oneHour)}if value, ok := Int64Attr(attrs, "gen_ai.usage.cache_read.input_tokens", "gen_ai.usage.cache_read_input_tokens", "cache_read_tokens"); ok {usage.CacheRead = &GenAIUsageCacheReadInfo{InputTokens: &value}diff --git a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.goindex deaa6ddf..03f9018b 100644--- a/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go+++ b/collector-builder/exporter/beaconjsonexporter/internal/beaconevent/converter_test.go@@ -634,6 +634,48 @@ func TestGenAIUsageFromAttrsNormalizesAliases(t *testing.T) {}},},+ {+ // The browser extension's Claude adapter emits the one-hour cache-write subset+ // beside the write count.+ name: "one-hour cache write subset",+ attrs: map[string]interface{}{+ "gen_ai.usage.cache_creation.input_tokens": int64(20000),+ "gen_ai.usage.cache_creation.ephemeral_1h_input_tokens": int64(16000),+ },+ check: func(t *testing.T, usage *GenAIUsageInfo) {+ c := usage.CacheCreation+ if c == nil || c.InputTokens == nil || *c.InputTokens != 20000 || c.Ephemeral1hInputTokens == nil || *c.Ephemeral1hInputTokens != 16000 {+ t.Fatalf("cache_creation = %#v, want 20000 with 16000 one-hour", c)+ }+ },+ },+ {+ name: "one-hour subset clamped to the write count",+ attrs: map[string]interface{}{+ "gen_ai.usage.cache_creation.input_tokens": int64(500),+ "gen_ai.usage.cache_creation.ephemeral_1h_input_tokens": int64(900),+ },+ check: func(t *testing.T, usage *GenAIUsageInfo) {+ c := usage.CacheCreation+ if c == nil || c.Ephemeral1hInputTokens == nil || *c.Ephemeral1hInputTokens != 500 {+ t.Fatalf("cache_creation = %#v, want the subset clamped to 500", c)+ }+ },+ },+ {+ // A subset without the count it belongs to cannot be placed; it is dropped rather+ // than invented into a write count.+ name: "one-hour subset without a write count",+ attrs: map[string]interface{}{+ "gen_ai.usage.input_tokens": int64(5),+ "gen_ai.usage.cache_creation.ephemeral_1h_input_tokens": int64(900),+ },+ check: func(t *testing.T, usage *GenAIUsageInfo) {+ if usage.CacheCreation != nil {+ t.Fatalf("cache_creation = %#v, want none", usage.CacheCreation)+ }+ },+ },{name: "runtime reported cost attribute",attrs: map[string]interface{}{"gen_ai.usage.cost": 0.0123},diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdxindex 1b7e2410..065ec867 100644--- a/docs/cli/token-usage.mdx+++ b/docs/cli/token-usage.mdx@@ -23,7 +23,7 @@ Beacon normalizes token telemetry from every runtime into one canonical [`gen_aiA few rules shape how the numbers read:-- **Counts are kept disjoint.** `input_tokens`, `output_tokens`, `cache_read`, and `cache_creation` do not overlap, so a total is `input + output + cache_read + cache_creation` without double-counting. Codex reports input inclusive of both cache reads and cache writes, so Beacon subtracts both before storing uncached input.+- **Counts are kept disjoint.** `input_tokens`, `output_tokens`, `cache_read`, and `cache_creation` do not overlap, so a total is `input + output + cache_read + cache_creation` without double-counting. Codex reports input inclusive of both cache reads and cache writes, so Beacon subtracts both before storing uncached input. `cache_creation.ephemeral_1h_input_tokens` is a breakdown of `cache_creation`, never a fifth count.- **Reported and estimated cost are kept apart.** `cost_usd` is what the runtime reported and nothing else. Beside it, every report carries a list-price estimate (`estimated_cost_usd`) for every runtime, including the ones that report no cost, and an effective cost that picks one of the two. See [Cost: reported, estimated, effective](#cost-reported-estimated-effective). Events never carry an estimate; it is computed when the report is built.- **Attribution depends on the metadata a runtime attaches.** Model, harness, repository, and run grouping work whenever those fields are present. Per-session grouping (`--session`, the session step tree) requires a session or conversation id on the usage signal. Per-user grouping uses the event user directly or a matching session context event from a local hook.- **Duplicate channels are de-duplicated.** When a runtime emits the same usage on more than one signal (Claude Code reports it on both logs and metrics), Beacon counts it once.@@ -125,7 +125,7 @@ The text report prints `COST USD` (reported) and `EST COST USD` (estimate) side- **Standard tier only.** No batch, flex or priority tiers, regional surcharges, or subscription and enterprise discounts: nothing in a usage record says a call used them.- **Model matching.** The model is matched to a catalog entry by exact name, then by canonical spelling (case, provider prefix), dotted versions (`claude-sonnet-4.6`), Bedrock route prefixes, and after stripping a context-window marker (`[1m]`), a snapshot date or an effort suffix. Never by similarity. `pricing.models` records, per model, the catalog key, how it matched, the base rates in USD per million tokens, and any rate fallback used.- **Missing rates.** A model with no published cache-read or cache-write price has those tokens priced at its input rate, and the fallback is named in `pricing.models[].fallbacks`.-- **1h cache writes** are priced at the 5-minute write rate, because `gen_ai.usage` does not yet carry the split.+- **1h cache writes.** Anthropic bills a cache write with a one-hour TTL at 2x the input rate, against 1.25x for the default five-minute TTL. Where the source reports the split, `gen_ai.usage.cache_creation.ephemeral_1h_input_tokens` carries the one-hour subset and those writes are priced at the model's one-hour rate (`cache_write_1h_at_write_rate` is named in `fallbacks` when the catalog has none). The split is reported by Claude Code session files (`beacon endpoint claude sync`), Pi-family runtimes whose usage carries `cacheWrite1h` (Pi fills it for Anthropic models), and the browser extension on claude.ai when the stream includes it. Claude Code's OTLP `api_request` log and token metric report only the total, so OTLP-only Claude Code usage prices every write at the five-minute rate and can understate sessions that use one-hour caching. Reports carry the subset as `cache_creation_1h_input_tokens` wherever it is non-zero.- **Reasoning** is part of output and is not billed again. It is priced at the output rate only when a runtime reported reasoning and no output.- **Long-context bands.** Several providers bill every token of a request above a prompt size at a higher rate (Anthropic and Gemini above 200k tokens, OpenAI's newer models above 272k). A band can only apply to a single request, so it is applied only to usage Beacon knows is one request: Claude Code `claude_code.api_request` records and session files, Codex session `token_count` records, Pi-family `message_end` and session files, OpenCode assistant messages, OpenClaw session files and DeepSeek Harness assistant messages. Metric datapoints, Codex turn spans, OpenClaw `llm_output` (one per turn), Cline task totals, Copilot shutdown totals and the Hermes, Factory and fx deltas sum several requests and are priced at base rates, which can understate a session that sent long prompts. `pricing.models[].bands_applied` counts the banded requests.- **After deduplication.** The estimate prices the final per-event counts, after duplicate channels are removed and cumulative counters are differenced, so it covers exactly the tokens the totals count.diff --git a/docs/telemetry-schema/fields.mdx b/docs/telemetry-schema/fields.mdxindex 2e80de5e..10c19a56 100644--- a/docs/telemetry-schema/fields.mdx+++ b/docs/telemetry-schema/fields.mdx@@ -51,7 +51,7 @@ When a runtime emits OpenTelemetry GenAI semantic convention attributes, Beacon|-------|--------|| `gen_ai.request` | Request settings such as `model`, `max_tokens`, `temperature`, `top_p`, `top_k`, `seed`, `stream`, `choice_count`, `encoding_formats`, and `stop_sequences` || `gen_ai.response` | Response metadata such as `id`, `model`, `finish_reasons`, and `time_to_first_chunk` |-| `gen_ai.usage` | Token counters such as `input_tokens`, `output_tokens`, `cache_creation.input_tokens`, `cache_read.input_tokens`, and `reasoning.output_tokens`, plus runtime-reported `cost_usd` |+| `gen_ai.usage` | Token counters such as `input_tokens`, `output_tokens`, `cache_creation.input_tokens` (with its optional one-hour subset `cache_creation.ephemeral_1h_input_tokens`), `cache_read.input_tokens`, and `reasoning.output_tokens`, plus runtime-reported `cost_usd` || `gen_ai.input.messages`, `gen_ai.output.messages` | Message arrays or objects emitted by the runtime || `gen_ai.tool` | Tool metadata such as `name`, `type`, `description`, `definitions`, and `call.id`, `call.arguments`, or `call.result` || `gen_ai.retrieval` | Retrieval context such as `query_text` and `documents` |diff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdxindex 86842de6..f7f5a484 100644--- a/docs/telemetry-schema/normalization.mdx+++ b/docs/telemetry-schema/normalization.mdx@@ -181,6 +181,7 @@ Beacon preserves OpenTelemetry GenAI semantic convention fields under the nested| `gen_ai.usage.input_tokens`, `llm.usage.prompt_tokens`, `gen_ai.usage.prompt_tokens` | `gen_ai.usage.input_tokens` || `gen_ai.usage.output_tokens`, `llm.usage.completion_tokens`, `gen_ai.usage.completion_tokens` | `gen_ai.usage.output_tokens` || `gen_ai.usage.cache_creation.input_tokens` | `gen_ai.usage.cache_creation.input_tokens` |+| `gen_ai.usage.cache_creation.ephemeral_1h_input_tokens` (browser extension), Anthropic `usage.cache_creation.ephemeral_1h_input_tokens` (Claude Code session files), Pi `cacheWrite1h` | `gen_ai.usage.cache_creation.ephemeral_1h_input_tokens`: the subset of `cache_creation.input_tokens` written with a one-hour TTL, clamped to it and never added to a total || `gen_ai.usage.cache_read.input_tokens` | `gen_ai.usage.cache_read.input_tokens` || `gen_ai.usage.reasoning.output_tokens` | `gen_ai.usage.reasoning.output_tokens` || `gen_ai.usage.cost`, runtime `*.cost.usage` metric datapoints | `gen_ai.usage.cost_usd` |diff --git a/pkg/asymptoteobserve/cache_creation_test.go b/pkg/asymptoteobserve/cache_creation_test.gonew file mode 100644index 00000000..dbb4fbbd--- /dev/null+++ b/pkg/asymptoteobserve/cache_creation_test.go@@ -0,0 +1,121 @@+package asymptoteobserve++import (+ "encoding/json"+ "testing"+)++func i64(v int64) *int64 { return &v }++func TestCacheCreationOneHourSubsetRoundTrips(t *testing.T) {+ line := `{"gen_ai":{"usage":{"input_tokens":3,"cache_creation":{"input_tokens":20000,"ephemeral_1h_input_tokens":16000}}}}`+ var event Event+ if err := json.Unmarshal([]byte(line), &event); err != nil {+ t.Fatal(err)+ }+ c := event.GenAI.Usage.CacheCreation+ if c == nil || c.InputTokens == nil || *c.InputTokens != 20000 || c.Ephemeral1hInputTokens == nil || *c.Ephemeral1hInputTokens != 16000 {+ t.Fatalf("cache_creation = %+v", c)+ }+ encoded, err := json.Marshal(event.GenAI.Usage)+ if err != nil {+ t.Fatal(err)+ }+ if want := `{"cache_creation":{"input_tokens":20000,"ephemeral_1h_input_tokens":16000},"input_tokens":3}`; string(encoded) != want {+ t.Fatalf("encoded = %s, want %s", encoded, want)+ }++ // Additive: a block without the split encodes exactly as before.+ encoded, _ = json.Marshal(&GenAIUsageCacheCreationInfo{InputTokens: i64(5)})+ if string(encoded) != `{"input_tokens":5}` {+ t.Fatalf("encoded = %s, want the field omitted", encoded)+ }+}++func TestNewCacheCreationUsageClampsTheSubset(t *testing.T) {+ cases := []struct {+ name string+ total int64+ oneHour *int64+ want *int64+ }{+ {"unreported", 100, nil, nil},+ {"within", 100, i64(40), i64(40)},+ {"equal", 100, i64(100), i64(100)},+ {"above", 100, i64(140), i64(100)},+ {"negative", 100, i64(-1), i64(0)},+ {"zero total", 0, i64(10), i64(0)},+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ got := NewCacheCreationUsage(tc.total, tc.oneHour)+ if got.InputTokens == nil || *got.InputTokens != tc.total {+ t.Fatalf("input_tokens = %v, want %d", got.InputTokens, tc.total)+ }+ switch {+ case tc.want == nil && got.Ephemeral1hInputTokens != nil:+ t.Fatalf("subset = %d, want absent", *got.Ephemeral1hInputTokens)+ case tc.want != nil && (got.Ephemeral1hInputTokens == nil || *got.Ephemeral1hInputTokens != *tc.want):+ t.Fatalf("subset = %v, want %d", got.Ephemeral1hInputTokens, *tc.want)+ }+ })+ }+}++func TestOneHourInputTokensClampsWhatALogLineClaims(t *testing.T) {+ var nilBlock *GenAIUsageCacheCreationInfo+ cases := []struct {+ name string+ block *GenAIUsageCacheCreationInfo+ want int64+ }{+ {"nil block", nilBlock, 0},+ {"unreported", &GenAIUsageCacheCreationInfo{InputTokens: i64(10)}, 0},+ {"reported", &GenAIUsageCacheCreationInfo{InputTokens: i64(10), Ephemeral1hInputTokens: i64(4)}, 4},+ {"above the total", &GenAIUsageCacheCreationInfo{InputTokens: i64(10), Ephemeral1hInputTokens: i64(40)}, 10},+ {"no total", &GenAIUsageCacheCreationInfo{Ephemeral1hInputTokens: i64(40)}, 0},+ }+ for _, tc := range cases {+ if got := tc.block.OneHourInputTokens(); got != tc.want {+ t.Fatalf("%s: OneHourInputTokens = %d, want %d", tc.name, got, tc.want)+ }+ }+}++func TestCacheCreationMinusDifferencesBothCounts(t *testing.T) {+ val := func(p *int64) interface{} {+ if p == nil {+ return nil+ }+ return *p+ }+ cases := []struct {+ name string+ next, prior *GenAIUsageCacheCreationInfo+ total, oneHrs interface{}+ }{+ {"nothing counted", &GenAIUsageCacheCreationInfo{InputTokens: i64(100), Ephemeral1hInputTokens: i64(60)}, nil, int64(100), int64(60)},+ {"grown", &GenAIUsageCacheCreationInfo{InputTokens: i64(300), Ephemeral1hInputTokens: i64(200)},+ &GenAIUsageCacheCreationInfo{InputTokens: i64(100), Ephemeral1hInputTokens: i64(60)}, int64(200), int64(140)},+ {"repeated snapshot", &GenAIUsageCacheCreationInfo{InputTokens: i64(100), Ephemeral1hInputTokens: i64(60)},+ &GenAIUsageCacheCreationInfo{InputTokens: i64(100), Ephemeral1hInputTokens: i64(60)}, int64(0), int64(0)},+ {"prior without split", &GenAIUsageCacheCreationInfo{InputTokens: i64(300), Ephemeral1hInputTokens: i64(250)},+ &GenAIUsageCacheCreationInfo{InputTokens: i64(100)}, int64(200), int64(200)},+ {"next without split", &GenAIUsageCacheCreationInfo{InputTokens: i64(300)},+ &GenAIUsageCacheCreationInfo{InputTokens: i64(100), Ephemeral1hInputTokens: i64(60)}, int64(200), nil},+ {"shrunk", &GenAIUsageCacheCreationInfo{InputTokens: i64(50), Ephemeral1hInputTokens: i64(10)},+ &GenAIUsageCacheCreationInfo{InputTokens: i64(100), Ephemeral1hInputTokens: i64(60)}, int64(0), int64(0)},+ }+ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ got := tc.next.Minus(tc.prior)+ if val(got.InputTokens) != tc.total || val(got.Ephemeral1hInputTokens) != tc.oneHrs {+ t.Fatalf("Minus = {%v %v}, want {%v %v}", val(got.InputTokens), val(got.Ephemeral1hInputTokens), tc.total, tc.oneHrs)+ }+ })+ }+ var nilBlock *GenAIUsageCacheCreationInfo+ if nilBlock.Minus(&GenAIUsageCacheCreationInfo{InputTokens: i64(1)}) != nil {+ t.Fatal("nil minus anything should be nil")+ }+}diff --git a/pkg/asymptoteobserve/event.go b/pkg/asymptoteobserve/event.goindex 5efc9c87..02484016 100644--- a/pkg/asymptoteobserve/event.go+++ b/pkg/asymptoteobserve/event.go@@ -351,8 +351,90 @@ type GenAIToolInfo struct {Type string `json:"type,omitempty"`}+// GenAIUsageCacheCreationInfo is the prompt-cache write count.+//+// InputTokens is every token written to the cache. Ephemeral1hInputTokens is the subset of those+// written with a one-hour TTL, which Anthropic bills at twice the input rate against 1.25x for the+// default five-minute TTL. It is a breakdown, never a parallel count: like reasoning inside output,+// it is already inside InputTokens and must not be added to any total. The name mirrors Anthropic's+// own usage.cache_creation.ephemeral_1h_input_tokens. Only sources that report the split set it, so+// absent means "not reported", not "no one-hour writes". Build it with NewCacheCreationUsage so it+// cannot exceed InputTokens.type GenAIUsageCacheCreationInfo struct {- InputTokens *int64 `json:"input_tokens,omitempty"`+ InputTokens *int64 `json:"input_tokens,omitempty"`+ Ephemeral1hInputTokens *int64 `json:"ephemeral_1h_input_tokens,omitempty"`+}++// NewCacheCreationUsage builds a cache-creation block from a write count and, when the source+// reports it, the one-hour subset. The subset is clamped to [0, inputTokens]: a breakdown larger+// than the count it breaks down is a malformed record, not extra writes.+func NewCacheCreationUsage(inputTokens int64, ephemeral1h *int64) *GenAIUsageCacheCreationInfo {+ out := &GenAIUsageCacheCreationInfo{InputTokens: &inputTokens}+ if ephemeral1h != nil {+ v := clampCacheSubset(*ephemeral1h, inputTokens)+ out.Ephemeral1hInputTokens = &v+ }+ return out+}++// OneHourInputTokens is the one-hour subset clamped to the write count, and zero when the source+// did not report it. Readers use this rather than the raw field, so a log line written by+// something other than Beacon cannot claim more one-hour writes than writes.+func (c *GenAIUsageCacheCreationInfo) OneHourInputTokens() int64 {+ if c == nil || c.Ephemeral1hInputTokens == nil {+ return 0+ }+ var total int64+ if c.InputTokens != nil {+ total = *c.InputTokens+ }+ return clampCacheSubset(*c.Ephemeral1hInputTokens, total)+}++// Minus is what c adds over an already-counted snapshot prior of the same usage, for callers+// that difference repeated or cumulative records field by field. Both counts are differenced and+// floored at zero, and the one-hour subset stays clamped to the differenced write count, so a+// delta can never carry more one-hour writes than writes. A nil prior counts as nothing counted.+func (c *GenAIUsageCacheCreationInfo) Minus(prior *GenAIUsageCacheCreationInfo) *GenAIUsageCacheCreationInfo {+ if c == nil {+ return nil+ }+ if prior == nil {+ prior = &GenAIUsageCacheCreationInfo{}+ }+ sub := func(next, counted *int64) *int64 {+ if next == nil {+ return nil+ }+ v := *next+ if counted != nil {+ v -= *counted+ }+ if v < 0 {+ v = 0+ }+ return &v+ }+ out := &GenAIUsageCacheCreationInfo{InputTokens: sub(c.InputTokens, prior.InputTokens)}+ if oneHour := sub(c.Ephemeral1hInputTokens, prior.Ephemeral1hInputTokens); oneHour != nil {+ var total int64+ if out.InputTokens != nil {+ total = *out.InputTokens+ }+ v := clampCacheSubset(*oneHour, total)+ out.Ephemeral1hInputTokens = &v+ }+ return out+}++func clampCacheSubset(subset, total int64) int64 {+ switch {+ case subset < 0 || total < 0:+ return 0+ case subset > total:+ return total+ }+ return subset}type GenAIUsageCacheReadInfo struct {diff --git a/pkg/asymptoteobserve/trace.go b/pkg/asymptoteobserve/trace.goindex 29492bfd..8e6d1f4d 100644--- a/pkg/asymptoteobserve/trace.go+++ b/pkg/asymptoteobserve/trace.go@@ -200,13 +200,17 @@ type TraceErrorV1 struct {Type string `json:"type,omitempty"`}+// TraceUsageV1 is gen_ai.usage flattened. CacheCreation1hInputTokens is the subset of+// CacheCreationInputTokens written with a one-hour TTL, where the source reported it; like+// ReasoningOutputTokens it is a breakdown and never part of a total.type TraceUsageV1 struct {- InputTokens int64 `json:"input_tokens,omitempty"`- OutputTokens int64 `json:"output_tokens,omitempty"`- CacheReadInputTokens int64 `json:"cache_read_input_tokens,omitempty"`- CacheCreationInputTokens int64 `json:"cache_creation_input_tokens,omitempty"`- ReasoningOutputTokens int64 `json:"reasoning_output_tokens,omitempty"`- CostUSD float64 `json:"cost_usd,omitempty"`+ InputTokens int64 `json:"input_tokens,omitempty"`+ OutputTokens int64 `json:"output_tokens,omitempty"`+ CacheReadInputTokens int64 `json:"cache_read_input_tokens,omitempty"`+ CacheCreationInputTokens int64 `json:"cache_creation_input_tokens,omitempty"`+ CacheCreation1hInputTokens int64 `json:"cache_creation_1h_input_tokens,omitempty"`+ ReasoningOutputTokens int64 `json:"reasoning_output_tokens,omitempty"`+ CostUSD float64 `json:"cost_usd,omitempty"`}type TraceSpanV1 struct {diff --git a/spec/lenses/SPEC.md b/spec/lenses/SPEC.mdindex f75ceed5..da25cf84 100644--- a/spec/lenses/SPEC.md+++ b/spec/lenses/SPEC.md@@ -250,3 +250,6 @@ The host enforces these rules; a lens does not opt into them.- `lenses/v1`: initial specification.- `lenses/v1` (additive): `token_usage`, the counted usage of the trace.- `lenses/v1` (additive): `trace.events[].error`, the failure an event recorded.+- `lenses/v1` (additive): `cache_creation_1h_input_tokens` in every usage object,+ the subset of `cache_creation_input_tokens` written with a one-hour TTL where+ the source reported it. It is a breakdown; never add it to a total.diff --git a/spec/threat-rules/FIELDS.md b/spec/threat-rules/FIELDS.mdindex 4b54890b..a3596562 100644--- a/spec/threat-rules/FIELDS.md+++ b/spec/threat-rules/FIELDS.md@@ -81,6 +81,7 @@ Regenerate with `beacon rules fields --markdown > spec/threat-rules/FIELDS.md`.| `e.gen_ai.tool.description` | string || `e.gen_ai.tool.name` | string || `e.gen_ai.tool.type` | string |+| `e.gen_ai.usage.cache_creation.ephemeral_1h_input_tokens` | int || `e.gen_ai.usage.cache_creation.input_tokens` | int || `e.gen_ai.usage.cache_read.input_tokens` | int || `e.gen_ai.usage.cost_usd` | double |