Skip to content

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

feat(tokens): capture one-hour cache writes and price them at the 1h rate

Claudee20ebf2f24da
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.sse
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.go
index 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.go
index 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.go
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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 split
defaultHistoryRetentionDays = 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.go
index 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.md
index 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.go
new file mode 100644
index 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.go
index 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.OutputTokens
u.CacheReadInputTokens += delta.CacheReadInputTokens
u.CacheCreationInputTokens += delta.CacheCreationInputTokens
+ u.CacheCreation1hInputTokens += delta.CacheCreation1hInputTokens
u.ReasoningOutputTokens += delta.ReasoningOutputTokens
u.CostUSD += delta.CostUSD
}
diff --git a/cli/beacon/internal/pisession/cache1h_test.go b/cli/beacon/internal/pisession/cache1h_test.go
new file mode 100644
index 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.go
index 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.go
index 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 be
diff --git a/cli/beacon/internal/tokens/cache1h_test.go b/cli/beacon/internal/tokens/cache1h_test.go
new file mode 100644
index 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.go
index 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) *PricingSu
Output: 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, s
if 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.go
index 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.Totals
fmt.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.go
index 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.OutputTokens
u.CacheReadInputTokens += delta.CacheReadInputTokens
u.CacheCreationInputTokens += delta.CacheCreationInputTokens
+ u.CacheCreation1hInputTokens += delta.CacheCreation1hInputTokens
u.ReasoningOutputTokens += delta.ReasoningOutputTokens
u.CostUSD += delta.CostUSD
u.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 int64
for _, 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.CacheCreation1hInputTokens
setUsageField(&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.go
index 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.go
index 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.mdx
index 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_ai
A 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.mdx
index 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.mdx
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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.md
index 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.md
index 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 |