[nightlightmare]

Summary

estimateCost(usage, prices)
  p ← prices, overlaid by the tier with the highest `above` < inputTokens
  input      = max(0, inputTokens − cacheRead − cacheWrite) × p.input
  cacheRead  = cacheReadTokens  × (p.cacheRead  ?? p.input)
  cacheWrite = cacheWriteTokens × (p.cacheWrite ?? p.input)
  output     = outputTokens × p.output                  (all ÷ 1e6)
  missing    = 'input' | 'output' whose count is absent (absent if none)

toUsage(raw)
  promptTokenCount…           → fromGemini
  prompt_tokens…              → fromChat
  cache_*_input_tokens…       → fromAnthropic   (adds cached tokens to input)
  input_tokens / output_tokens→ fromResponses
  anything else               → {}

 src/
+├── cost/              # estimateCost, toUsage
 ├── shared/
+│   └── usage.ts       # fromAnthropic, fromChat, fromResponses, fromGemini
 └── sse/providers/
-    anthropic.ts, openai.ts, openai-responses.ts, gemini.ts: each its own usage conversion
+    the same files, calling src/shared/usage.ts

• The stream adapters and toUsage now share one conversion per Provider, so a raw reply and a stream of the same call give the same LlmUsage. One behaviour change in the adapters: a null count (Anthropic sends cache_creation_input_tokens: null in some cases) is treated as absent instead of passing through.
• README section, API and size rows, docs/api.md section: all in three languages. llms.txt regenerated.

Evidence

toUsage({ input_tokens: 1_200, cache_read_input_tokens: 40_000, cache_creation_input_tokens: 0, output_tokens: 800 })
→ { inputTokens: 41_200, outputTokens: 800, cacheReadTokens: 40_000, cacheWriteTokens: 0 }
estimateCost(↑, { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 })
→ { total: 0.0276, input: 0.0036, cacheRead: 0.012, cacheWrite: 0, output: 0.012 }

Before: the raw Anthropic input_tokens (1,200) priced as all input misses the 40,000 cached tokens; adding them at the input price overstates the cost tenfold.
After: 12 new tests (tiers, missing counts, every raw shape, unknown shapes); all 342 SSE tests pass unchanged on the shared conversion; 875 tests, docs, smoke, publint and attw pass. llmmend/cost is 689 B of its 1 kB limit; the SSE bundles did not grow (collectText 6.78 kB, streamToolCalls 6.92 kB).

Merge Danger

Door: two-way

Blast Radius: stream usage events

Additive module, but the stream adapters' usage code moved to src/shared/usage.ts. The recorded fixtures for all four Providers pass unchanged; the only difference is null counts, now dropped.

Closes #90

🤖 Generated with Claude Code

https://claude.ai/code/session_01F61ff7dDPwJn5kuD25LtiS