[SDK] assistant.usage: cacheReadTokens and cacheWriteTokens never populated (all providers)

[KennyTurtle]

Summary

The assistant.usage event defines cacheReadTokens and cacheWriteTokens fields (documented in SDK docs/features/streaming-events.md:309-310), but these values are never populated — they always arrive as 0.0 regardless of whether the LLM provider returns cache metrics.

Both Anthropic and OpenAI APIs return prompt caching metrics, but the CLI doesn't extract and map them.

Repro (confirmed 2026-04-13)

SDK v0.2.2, model: claude-sonnet-4-20250514 via BYOK (CAPI relay)

Collected 3 assistant.usage events:

  Message 1:  input=44.0   output=4.0   cacheReadTokens=0.0   cacheWriteTokens=0.0
  Message 2:  input=89.0   output=4.0   cacheReadTokens=0.0   cacheWriteTokens=0.0
  Message 3:  input=134.0  output=4.0   cacheReadTokens=0.0   cacheWriteTokens=0.0

All calls return 0.0 even though Anthropic returns cache_read_input_tokens / cache_creation_input_tokens in the API response.

Provider response formats (not being extracted by CLI)

Anthropic returns: usage.cache_read_input_tokens, usage.cache_creation_input_tokens
OpenAI returns: usage.prompt_tokens_details.cached_tokens

SDK code references

File	Line	What
python/copilot/generated/session_events.py	798, 801	cache_read_tokens / cache_write_tokens fields defined
python/copilot/generated/session_events.py	2328, 2331	Per-call Data class fields
go/generated_session_events.go	1084-1086	Go equivalents
nodejs/src/generated/session-events.ts	1586, 1590	TS equivalents
docs/features/streaming-events.md	309-310	Documented as optional fields

Impact on Dracarys

• No visibility into prompt cache hit rates in our Kusto telemetry
• Cannot optimize system prompts for cacheability
• Cannot reconcile costs (Anthropic cache reads are ~90% cheaper)

[github-actions]

Investigation Results: Confirmed Bug 🐛

Thanks for the detailed report. I investigated this across all SDK language implementations and confirmed this is a genuine bug.

What I Investigated

SDK type definitions — checked all four SDK languages:

• TypeScript (nodejs/src/generated/session-events.ts:1586,1590): cacheReadTokens?: number — optional ✅
• Python (python/copilot/generated/session_events.py:2328,2331): cache_read_tokens: float | None = None — optional ✅
• Go (go/generated_session_events.go:1084-1086): CacheReadTokens *float64 — optional pointer ✅
• .NET (dotnet/src/Generated/SessionEvents.cs:1847,1852): double? CacheReadTokens with JsonIgnore(WhenWritingNull) — optional ✅

Documentation (docs/features/streaming-events.md:309-310): Fields are properly documented as optional fields in assistant.usage events.

Aggregated metrics (Rpc.cs:1422-1427, Python Usage class): The session.usage.getMetrics RPC also exposes these fields in the cumulative usage summary.

Test snapshots (test/snapshots/): No existing snapshot coverage for assistant.usage events with cache token data.

Root Cause

The SDK is correctly designed — all language bindings define cacheReadTokens/cacheWriteTokens as optional fields, ready to receive values. The bug lies in the Copilot CLI server, which:

1. Emits explicit 0 for these fields rather than omitting them or reading the provider-specific cache metrics
2. Does not map the provider-specific response fields to these SDK fields:
   • Anthropic: usage.cache_read_input_tokens → cacheReadTokens, usage.cache_creation_input_tokens → cacheWriteTokens
   • OpenAI: usage.prompt_tokens_details.cached_tokens → cacheReadTokens

The fix needs to happen in the CLI server implementation (separate repository). The SDK schema and types are already correct and ready to surface the data once the CLI populates these fields properly.

Label applied: bug — the fields exist and are documented to carry real cache token data, but the CLI is not wiring up provider API response values to them.

Generated by Bug Handler for issue #1073 · ● 612.2K · ◷