feat(usage): normalize variant cache-token field names across upstreams

[Menci]

Summary

The OpenAI-shape usage.prompt_tokens_details.cached_tokens convention is dominant but not universal among the "wild" OpenAI-compatible upstreams Floway routes to. Several providers emit cache-hit counts under different field names, and our extractors silently miscounted those rows as zero cache activity (the entire prompt landed on the bare input dimension).

A short cross-provider survey:

Cache-read shape	Upstreams emitting it	Covered before?
usage.prompt_tokens_details.cached_tokens (OpenAI canonical)	OpenAI, Gemini OpenAI-compat, xAI, Mistral, OpenRouter, Groq, Cerebras, Zhipu, Doubao, Qwen main, llama.cpp, vLLM, SGLang	✓
usage.prompt_cache_hit_tokens + usage.prompt_cache_miss_tokens (root level, prompt_tokens is the sum)	DeepSeek	✗
usage.cached_tokens (flat, no wrapper)	Moonshot / Kimi, Cohere v2 native, Qwen Singapore legacy	✗
HTTP header fireworks-cached-prompt-tokens + perf_metrics["cached-prompt-tokens"] (outside usage)	Fireworks AI	irreducible at this layer
Not reported	Anthropic OpenAI-compat, Together, Perplexity, SiliconFlow, TGI, Ollama-compat	n/a

A parallel divergence for cache-write under the OpenAI wrapper:

Cache-write shape	Source	Covered before?
prompt_tokens_details.cache_creation_input_tokens	the gateway's Anthropic messages → chat-completions translation pair (Anthropic-native name forwarded under OpenAI's wrapper)	✓
prompt_tokens_details.cache_write_tokens	OpenRouter (Anthropic / explicit-Gemini / Alibaba-routed)	✗

Change

• New openAICacheTokensFromUsage(usage: unknown): { cacheRead, cacheWrite } helper in shared/telemetry/usage.ts. It sniffs the variants in explicit precedence order:
  • cache-read: prompt_tokens_details.cached_tokens → prompt_cache_hit_tokens → flat cached_tokens
  • cache-write: prompt_tokens_details.cache_creation_input_tokens → prompt_tokens_details.cache_write_tokens
• Both per-API extractors (tokenUsageFromChatCompletionsUsage, tokenUsageFromCompletionsUsage) now call the helper instead of reading the fields directly. The chat extractor keeps its strict ChatCompletionsUsage parameter type — the variant sniff lives at the extraction boundary and the protocol type stays clean of non-standard fields.
• Completions also gains cache-write subtraction so its three input dimensions stay disjoint when an upstream that emits cache-write happens to answer there (no-op when cache-write is 0).
• Tests cover each variant shape on the helper and on both per-API extractors, plus the precedence behavior when multiple candidates are present, the null prompt_tokens_details case (Gemini cache miss), and that a real cached_tokens: 0 is honored rather than falling through to the next candidate.

Out of scope

• Fireworks: HTTP-header + perf_metrics sibling, completely outside the usage block. Capturing it needs provider-specific extraction at the transport layer, deferred to a separate change.
• vLLM streaming /v1/completions bug (vllm-project/vllm#44961, fixed by #44383 on main): pure upstream-side, no gateway code change can recover the omitted field. The Zhipu/GLM fork we observed predates that fix.

Test plan

• pnpm run typecheck — clean
• pnpm run lint — clean
• pnpm run test — 3364 / 3364 pass (was 3295 on main; +16 new test cases across shared/telemetry/usage_test.ts, completions/usage_test.ts, chat-completions/usage_test.ts)
• Manual end-to-end against a DeepSeek upstream once configured, to confirm a cache-hit request lands input_cache_read > 0 in the usage row