Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Add observed cache TTL metrics and dashboard coverage
JerrettDavisa6787556beec
diff --git a/docs/metrics.md b/docs/metrics.mdindex 6664fa989..66bcdef43 100644--- a/docs/metrics.md+++ b/docs/metrics.md@@ -53,6 +53,41 @@ for backward compatibility. The new `persistent_savings` block is durable localproxy compression history stored by default at `~/.headroom/proxy_savings.json`.Use `HEADROOM_SAVINGS_PATH` to override the file location.+For Anthropic-style providers that return cache-write TTL buckets, `/stats`+also surfaces observed cache TTL usage under `prefix_cache`:++```json+{+ "prefix_cache": {+ "by_provider": {+ "anthropic": {+ "observed_ttl_buckets": {+ "5m": {"tokens": 20000, "requests": 8},+ "1h": {"tokens": 50000, "requests": 12}+ },+ "observed_ttl_mix": {+ "5m_pct": 28.6,+ "1h_pct": 71.4,+ "active_buckets": ["5m", "1h"]+ }+ }+ },+ "totals": {+ "observed_ttl_buckets": {+ "5m": {"tokens": 20000, "requests": 8},+ "1h": {"tokens": 50000, "requests": 12}+ }+ }+ }+}+```++These fields are observational only:++- they reflect provider-reported cache write buckets+- they do not configure TTL+- they do not represent remaining expiration time+### Historical Savings Endpoint```bashdiff --git a/docs/proxy.md b/docs/proxy.mdindex 244e9bde6..cc0ee7959 100644--- a/docs/proxy.md+++ b/docs/proxy.md@@ -133,6 +133,16 @@ curl http://localhost:8787/statssmall recent preview. The existing `savings_history` field is still present andremains session-scoped for backward compatibility.+For providers that return cache-write TTL bucket usage, `/stats` also includes+observed TTL breakdowns under `prefix_cache`:++- `observed_ttl_buckets.5m.tokens`+- `observed_ttl_buckets.1h.tokens`+- `observed_ttl_mix`++These are provider-reported observations, not configured TTL and not remaining+expiration time.+### Historical Savings```bashdiff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.htmlindex 68e4f4df7..68f12319f 100644--- a/headroom/dashboard/templates/dashboard.html+++ b/headroom/dashboard/templates/dashboard.html@@ -208,6 +208,60 @@<span class="flex items-center gap-1"><span class="w-2 h-2 rounded-full bg-border inline-block"></span> Uncached</span></div></div>+ <template x-if="hasObservedTtlBuckets">+ <div class="mt-5 border-t border-border pt-4">+ <div class="flex items-center justify-between mb-3">+ <div>+ <div class="text-xs text-gray-500 uppercase tracking-[0.22em]">Observed TTL Buckets</div>+ <div class="text-sm text-gray-300 mt-1">Provider-reported cache write mix</div>+ </div>+ <div class="text-xs text-gray-500 font-mono" x-text="observedTtlWindowLabel"></div>+ </div>+ <div class="grid grid-cols-1 xl:grid-cols-[1.3fr_0.9fr] gap-4">+ <div class="rounded-2xl border border-cyan-500/20 bg-[linear-gradient(180deg,rgba(34,211,238,0.10),rgba(12,16,22,0.88))] p-4 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]">+ <div class="flex items-start justify-between gap-3">+ <div>+ <div class="text-[11px] uppercase tracking-[0.22em] text-cyan-300/75">Bucket Mix</div>+ <div class="mt-1 text-2xl font-light text-cyan-50">+ <span data-testid="ttl-bucket-mix-1h-total" x-text="formatNumber(stats.prefix_cache?.totals?.cache_write_1h_tokens || 0)"></span>+ <span class="text-sm text-cyan-300/70">1h</span>+ <span class="mx-2 text-cyan-500/60">/</span>+ <span data-testid="ttl-bucket-mix-5m-total" x-text="formatNumber(stats.prefix_cache?.totals?.cache_write_5m_tokens || 0)"></span>+ <span class="text-sm text-cyan-300/70">5m</span>+ </div>+ </div>+ <div data-testid="ttl-bucket-headline" class="rounded-full border border-cyan-400/20 bg-black/20 px-3 py-1 text-[11px] uppercase tracking-[0.18em] text-cyan-200/80" x-text="observedTtlHeadline"></div>+ </div>+ <div class="mt-4">+ <div class="flex justify-between text-xs text-gray-500 mb-1">+ <span>Observed write-token split</span>+ <span x-text="(stats.prefix_cache?.totals?.observed_ttl_mix?.active_buckets || []).join(' + ')"></span>+ </div>+ <div class="h-3 overflow-hidden rounded-full bg-black/30 ring-1 ring-white/5 flex">+ <div class="h-full bg-cyan-400 transition-all duration-500" :style="'width:' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['1h_pct'] || 0) + '%'"></div>+ <div class="h-full bg-violet-400 transition-all duration-500" :style="'width:' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['5m_pct'] || 0) + '%'"></div>+ </div>+ <div class="mt-2 flex flex-wrap gap-3 text-xs text-gray-400">+ <span class="inline-flex items-center gap-1.5"><span class="inline-block h-2 w-2 rounded-full bg-cyan-400"></span><span data-testid="ttl-bucket-mix-1h-pct" x-text="'1h ' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['1h_pct'] || 0).toFixed(1) + '%'"></span></span>+ <span class="inline-flex items-center gap-1.5"><span class="inline-block h-2 w-2 rounded-full bg-violet-400"></span><span data-testid="ttl-bucket-mix-5m-pct" x-text="'5m ' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['5m_pct'] || 0).toFixed(1) + '%'"></span></span>+ </div>+ </div>+ </div>+ <div class="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-1 gap-3">+ <div class="rounded-2xl border border-white/8 bg-black/20 p-4">+ <div class="text-[11px] uppercase tracking-[0.18em] text-cyan-300/75">1h Cache Writes</div>+ <div data-testid="ttl-bucket-1h-value" class="mt-2 text-3xl font-light text-cyan-50" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['1h']?.tokens || 0)"></div>+ <div class="mt-1 text-xs text-gray-500" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['1h']?.requests || 0) + ' requests observed'"></div>+ </div>+ <div class="rounded-2xl border border-white/8 bg-black/20 p-4">+ <div class="text-[11px] uppercase tracking-[0.18em] text-violet-300/75">5m Cache Writes</div>+ <div data-testid="ttl-bucket-5m-value" class="mt-2 text-3xl font-light text-violet-50" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['5m']?.tokens || 0)"></div>+ <div class="mt-1 text-xs text-gray-500" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['5m']?.requests || 0) + ' requests observed'"></div>+ </div>+ </div>+ </div>+ </div>+ </template><!-- Per-provider breakdown --><template x-if="Object.keys(stats.prefix_cache?.by_provider || {}).length > 0"><div class="mt-4 border-t border-border pt-3">@@ -219,11 +273,14 @@<span class="px-2 py-0.5 bg-border rounded text-xs font-mono" x-text="prov"></span><span class="text-xs text-gray-500" x-text="pc.label"></span></div>- <div class="flex items-center gap-4 text-xs font-mono">+ <div class="flex flex-wrap items-center justify-end gap-4 text-xs font-mono"><span class="text-emerald-400" x-text="formatNumber(pc.cache_read_tokens) + ' reads (' + pc.read_discount + ' off)'"></span><template x-if="pc.write_premium !== 'none'"><span class="text-amber-400" x-text="formatNumber(pc.cache_write_tokens) + ' writes (+' + pc.write_premium + ')'"></span></template>+ <template x-if="pc.observed_ttl_mix">+ <span class="text-cyan-300" x-text="'TTL 1h ' + (pc.observed_ttl_mix['1h_pct'] || 0).toFixed(1) + '% / 5m ' + (pc.observed_ttl_mix['5m_pct'] || 0).toFixed(1) + '%'"></span>+ </template><span :class="pc.bust_count > 0 ? 'text-red-400' : 'text-gray-500'" x-text="pc.bust_count + ' busts'"></span><span class="text-emerald-400" x-text="'$' + formatCurrency(pc.net_savings_usd)"></span></div>@@ -1054,6 +1111,26 @@return Math.round((t.cache_write_tokens || 0) / total * 100);},+ get hasObservedTtlBuckets() {+ const buckets = this.stats.prefix_cache?.totals?.observed_ttl_buckets || {};+ return ((buckets['5m']?.tokens || 0) + (buckets['1h']?.tokens || 0)) > 0;+ },++ get observedTtlHeadline() {+ const mix = this.stats.prefix_cache?.totals?.observed_ttl_mix || {};+ const oneHour = mix['1h_pct'] || 0;+ const fiveMinute = mix['5m_pct'] || 0;+ if (oneHour === fiveMinute) return 'Balanced';+ return oneHour > fiveMinute ? '1h leaning' : '5m leaning';+ },++ get observedTtlWindowLabel() {+ const mix = this.stats.prefix_cache?.totals?.observed_ttl_mix || {};+ const active = mix.active_buckets || [];+ if (!active.length) return 'No TTL bucket data';+ return active.length === 1 ? active[0] + ' only' : active.join(' / ');+ },+// --- Waste Signals ---wasteSignalLabel(signal) {diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.pyindex d2f1859ea..0f0bd9011 100644--- a/headroom/proxy/cost.py+++ b/headroom/proxy/cost.py@@ -78,6 +78,10 @@ def build_prefix_cache_stats(totals = {"cache_read_tokens": 0,"cache_write_tokens": 0,+ "cache_write_5m_tokens": 0,+ "cache_write_1h_tokens": 0,+ "cache_write_5m_requests": 0,+ "cache_write_1h_requests": 0,"requests": 0,"hit_requests": 0,"bust_count": 0,@@ -119,6 +123,10 @@ def build_prefix_cache_stats(# for observability but don't penalise our savings number.read_tokens: int = pc["cache_read_tokens"] # type: ignore[assignment]write_tokens: int = pc["cache_write_tokens"] # type: ignore[assignment]+ write_5m_tokens: int = pc["cache_write_5m_tokens"] # type: ignore[assignment]+ write_1h_tokens: int = pc["cache_write_1h_tokens"] # type: ignore[assignment]+ write_5m_requests: int = pc["cache_write_5m_requests"] # type: ignore[assignment]+ write_1h_requests: int = pc["cache_write_1h_requests"] # type: ignore[assignment]savings_usd = 0.0write_premium_usd = 0.0@@ -134,6 +142,10 @@ def build_prefix_cache_stats(provider_stats = {"cache_read_tokens": read_tokens,"cache_write_tokens": write_tokens,+ "cache_write_5m_tokens": write_5m_tokens,+ "cache_write_1h_tokens": write_1h_tokens,+ "cache_write_5m_requests": write_5m_requests,+ "cache_write_1h_requests": write_1h_requests,"requests": pc["requests"],"hit_requests": pc["hit_requests"],"hit_rate": hit_rate,@@ -145,12 +157,37 @@ def build_prefix_cache_stats("write_premium_usd": round(write_premium_usd, 4),"net_savings_usd": round(savings_usd, 4),"label": str(econ["label"]),+ "observed_ttl_buckets": {+ "5m": {+ "tokens": write_5m_tokens,+ "requests": write_5m_requests,+ },+ "1h": {+ "tokens": write_1h_tokens,+ "requests": write_1h_requests,+ },+ },}+ total_observed_ttl_tokens = write_5m_tokens + write_1h_tokens+ if total_observed_ttl_tokens > 0:+ provider_stats["observed_ttl_mix"] = {+ "5m_pct": round(write_5m_tokens / total_observed_ttl_tokens * 100, 1),+ "1h_pct": round(write_1h_tokens / total_observed_ttl_tokens * 100, 1),+ "active_buckets": [+ bucket+ for bucket, tokens in (("5m", write_5m_tokens), ("1h", write_1h_tokens))+ if tokens > 0+ ],+ }by_provider[provider] = provider_stats# Accumulate totalstotals["cache_read_tokens"] += read_tokenstotals["cache_write_tokens"] += write_tokens+ totals["cache_write_5m_tokens"] += write_5m_tokens+ totals["cache_write_1h_tokens"] += write_1h_tokens+ totals["cache_write_5m_requests"] += write_5m_requests+ totals["cache_write_1h_requests"] += write_1h_requeststotals["requests"] += pc["requests"]totals["hit_requests"] += pc["hit_requests"]totals["bust_count"] += pc["bust_count"]@@ -164,6 +201,33 @@ def build_prefix_cache_stats(totals["hit_rate"] = (round(totals["hit_requests"] / totals["requests"] * 100, 1) if totals["requests"] > 0 else 0)+ total_observed_ttl_tokens = totals["cache_write_5m_tokens"] + totals["cache_write_1h_tokens"]+ totals["observed_ttl_buckets"] = {+ "5m": {+ "tokens": totals["cache_write_5m_tokens"],+ "requests": totals["cache_write_5m_requests"],+ },+ "1h": {+ "tokens": totals["cache_write_1h_tokens"],+ "requests": totals["cache_write_1h_requests"],+ },+ }+ totals["observed_ttl_mix"] = {+ "5m_pct": round(totals["cache_write_5m_tokens"] / total_observed_ttl_tokens * 100, 1)+ if total_observed_ttl_tokens > 0+ else 0.0,+ "1h_pct": round(totals["cache_write_1h_tokens"] / total_observed_ttl_tokens * 100, 1)+ if total_observed_ttl_tokens > 0+ else 0.0,+ "active_buckets": [+ bucket+ for bucket, tokens in (+ ("5m", totals["cache_write_5m_tokens"]),+ ("1h", totals["cache_write_1h_tokens"]),+ )+ if tokens > 0+ ],+ }return {"by_provider": by_provider,@@ -180,7 +244,9 @@ def build_prefix_cache_stats("Prefix caching is performed by the LLM provider (Anthropic, OpenAI). ""Headroom reports cache stats as observed from API responses. ""CacheAligner and prefix freeze improve cache hit rates by stabilizing "- "the message prefix, but baseline caching happens without Headroom."+ "the message prefix, but baseline caching happens without Headroom. "+ "Observed TTL bucket metrics reflect provider-reported cache write usage "+ "(for example Anthropic 5m vs 1h), not configured or remaining TTL."),}@@ -356,6 +422,8 @@ class CostTracker:# API-reported cache breakdown per model (for accurate cost calculation)self._api_cache_read_by_model: dict[str, int] = {}self._api_cache_write_by_model: dict[str, int] = {}+ self._api_cache_write_5m_by_model: dict[str, int] = {}+ self._api_cache_write_1h_by_model: dict[str, int] = {}self._api_uncached_by_model: dict[str, int] = {}# Cache resolved model names to avoid repeated litellm lookups.@@ -480,6 +548,8 @@ class CostTracker:tokens_sent: int,cache_read_tokens: int = 0,cache_write_tokens: int = 0,+ cache_write_5m_tokens: int = 0,+ cache_write_1h_tokens: int = 0,uncached_tokens: int = 0,):"""Record token counts per model.@@ -503,6 +573,12 @@ class CostTracker:self._api_cache_write_by_model[model] = (self._api_cache_write_by_model.get(model, 0) + cache_write_tokens)+ self._api_cache_write_5m_by_model[model] = (+ self._api_cache_write_5m_by_model.get(model, 0) + cache_write_5m_tokens+ )+ self._api_cache_write_1h_by_model[model] = (+ self._api_cache_write_1h_by_model.get(model, 0) + cache_write_1h_tokens+ )self._api_uncached_by_model[model] = (self._api_uncached_by_model.get(model, 0) + uncached_tokens)@@ -574,6 +650,8 @@ class CostTracker:"requests": reqs,"tokens_saved": saved,"tokens_sent": sent,+ "cache_write_5m_tokens": self._api_cache_write_5m_by_model.get(model, 0),+ "cache_write_1h_tokens": self._api_cache_write_1h_by_model.get(model, 0),"reduction_pct": round(saved / (saved + sent) * 100, 1)if (saved + sent) > 0else 0,@@ -625,6 +703,8 @@ class CostTracker:"total_tokens_saved": total_saved,"total_input_tokens": total_input_tokens,"total_input_cost_usd": round(cost_with_headroom, 4),+ "cache_write_5m_tokens": sum(self._api_cache_write_5m_by_model.values()),+ "cache_write_1h_tokens": sum(self._api_cache_write_1h_by_model.values()),"per_model": per_model,"cost_with_headroom_usd": round(cost_with_headroom, 4),"savings_usd": round(savings_usd, 4),diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 7a3fb9a9d..cf0407466 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -40,6 +40,24 @@ class AnthropicHandlerMixin:canonical = str(tool)return (name, canonical)+ @staticmethod+ def _extract_anthropic_cache_ttl_metrics(usage: dict[str, Any] | None) -> tuple[int, int]:+ """Extract observed Anthropic cache-write TTL bucket usage.++ Returns (cache_write_5m_tokens, cache_write_1h_tokens) from provider usage.+ These are observational metrics only; they do not imply configured or+ remaining TTL.+ """+ if not isinstance(usage, dict):+ return (0, 0)+ cache_creation = usage.get("cache_creation")+ if not isinstance(cache_creation, dict):+ return (0, 0)+ return (+ int(cache_creation.get("ephemeral_5m_input_tokens", 0) or 0),+ int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),+ )+@classmethoddef _sort_tools_deterministically(cls, tools: list[dict[str, Any]] | None@@ -1196,12 +1214,15 @@ class AnthropicHandlerMixin:output_tokens = 0cr_tokens = 0cw_tokens = 0+ cw_5m_tokens = 0+ cw_1h_tokens = 0uncached_input_tokens = 0if resp_json:usage = resp_json.get("usage", {})output_tokens = usage.get("output_tokens", 0)cr_tokens = usage.get("cache_read_input_tokens", 0)cw_tokens = usage.get("cache_creation_input_tokens", 0)+ cw_5m_tokens, cw_1h_tokens = self._extract_anthropic_cache_ttl_metrics(usage)uncached_input_tokens = usage.get("input_tokens", 0)# Update prefix cache tracker for next turn@@ -1225,6 +1246,8 @@ class AnthropicHandlerMixin:optimized_tokens,cache_read_tokens=cr_tokens,cache_write_tokens=cw_tokens,+ cache_write_5m_tokens=cw_5m_tokens,+ cache_write_1h_tokens=cw_1h_tokens,uncached_tokens=uncached_input_tokens,)@@ -1252,6 +1275,8 @@ class AnthropicHandlerMixin:waste_signals=waste_signals_dict,cache_read_tokens=cr_tokens,cache_write_tokens=cw_tokens,+ cache_write_5m_tokens=cw_5m_tokens,+ cache_write_1h_tokens=cw_1h_tokens,uncached_input_tokens=uncached_input_tokens,)diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.pyindex ea9065915..80c6656c8 100644--- a/headroom/proxy/handlers/streaming.py+++ b/headroom/proxy/handlers/streaming.py@@ -24,6 +24,19 @@ logger = logging.getLogger("headroom.proxy")class StreamingMixin:"""Mixin providing streaming response methods for HeadroomProxy."""+ @staticmethod+ def _extract_anthropic_cache_ttl_metrics(usage: dict[str, Any] | None) -> tuple[int, int]:+ """Extract observed Anthropic cache-write TTL bucket usage."""+ if not isinstance(usage, dict):+ return (0, 0)+ cache_creation = usage.get("cache_creation")+ if not isinstance(cache_creation, dict):+ return (0, 0)+ return (+ int(cache_creation.get("ephemeral_5m_input_tokens", 0) or 0),+ int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),+ )+def _parse_sse_usage(self, chunk: bytes, provider: str) -> dict[str, int] | None:"""Parse usage information from SSE chunk.@@ -31,7 +44,9 @@ class StreamingMixin:For OpenAI: Looks for final chunk with usage object (requires stream_options.include_usage=true)For Gemini: Looks for usageMetadata in each chunk- Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens+ Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens,+ cache_creation_input_tokens, cache_creation_ephemeral_5m_input_tokens,+ cache_creation_ephemeral_1h_input_tokensReturns None if no usage found in this chunk."""try:@@ -67,6 +82,11 @@ class StreamingMixin:usage["cache_creation_input_tokens"] = msg_usage.get("cache_creation_input_tokens", 0)+ cache_write_5m, cache_write_1h = (+ self._extract_anthropic_cache_ttl_metrics(msg_usage)+ )+ usage["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m+ usage["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1helif event_type == "message_delta":delta_usage = data.get("usage", {})@@ -148,6 +168,11 @@ class StreamingMixin:usage_found["cache_creation_input_tokens"] = msg_usage.get("cache_creation_input_tokens", 0)+ cache_write_5m, cache_write_1h = (+ self._extract_anthropic_cache_ttl_metrics(msg_usage)+ )+ usage_found["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m+ usage_found["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h# INFO logging for cache token tracking (temporary for debugging)logger.info(f"[CACHE] Anthropic usage: input={usage_found.get('input_tokens')}, "@@ -450,6 +475,8 @@ class StreamingMixin:"output_tokens": None,"cache_read_input_tokens": 0,"cache_creation_input_tokens": 0,+ "cache_creation_ephemeral_5m_input_tokens": 0,+ "cache_creation_ephemeral_1h_input_tokens": 0,"total_bytes": 0,"sse_buffer": "", # Buffer for incomplete SSE events"ttfb_ms": None, # Time to first byte from upstream@@ -550,6 +577,14 @@ class StreamingMixin:stream_state["cache_creation_input_tokens"] = usage["cache_creation_input_tokens"]+ if "cache_creation_ephemeral_5m_input_tokens" in usage:+ stream_state["cache_creation_ephemeral_5m_input_tokens"] = usage[+ "cache_creation_ephemeral_5m_input_tokens"+ ]+ if "cache_creation_ephemeral_1h_input_tokens" in usage:+ stream_state["cache_creation_ephemeral_1h_input_tokens"] = usage[+ "cache_creation_ephemeral_1h_input_tokens"+ ]# Memory tool handling after stream completes# Chunks were already yielded in real-time above, so we only@@ -637,6 +672,8 @@ class StreamingMixin:# misleading for aggregation (often just 1 with prompt caching).cache_read_tokens = stream_state["cache_read_input_tokens"]cache_write_tokens = stream_state["cache_creation_input_tokens"]+ cache_write_5m_tokens = stream_state["cache_creation_ephemeral_5m_input_tokens"]+ cache_write_1h_tokens = stream_state["cache_creation_ephemeral_1h_input_tokens"]uncached_input_tokens = stream_state.get("input_tokens") or 0# Structured perf log line for `headroom perf` analysis@@ -672,6 +709,8 @@ class StreamingMixin:optimized_tokens,cache_read_tokens=cache_read_tokens,cache_write_tokens=cache_write_tokens,+ cache_write_5m_tokens=cache_write_5m_tokens,+ cache_write_1h_tokens=cache_write_1h_tokens,uncached_tokens=uncached_input_tokens,)@@ -687,6 +726,8 @@ class StreamingMixin:pipeline_timing=pipeline_timing,cache_read_tokens=cache_read_tokens,cache_write_tokens=cache_write_tokens,+ cache_write_5m_tokens=cache_write_5m_tokens,+ cache_write_1h_tokens=cache_write_1h_tokens,uncached_input_tokens=uncached_input_tokens,)diff --git a/headroom/proxy/prometheus_metrics.py b/headroom/proxy/prometheus_metrics.pyindex c23bafe78..e5889d406 100644--- a/headroom/proxy/prometheus_metrics.py+++ b/headroom/proxy/prometheus_metrics.py@@ -77,6 +77,10 @@ class PrometheusMetrics:lambda: {"cache_read_tokens": 0,"cache_write_tokens": 0,+ "cache_write_5m_tokens": 0,+ "cache_write_1h_tokens": 0,+ "cache_write_5m_requests": 0,+ "cache_write_1h_requests": 0,"requests": 0,"hit_requests": 0, # requests with cache_read > 0"bust_count": 0,@@ -158,6 +162,8 @@ class PrometheusMetrics:waste_signals: dict[str, int] | None = None,cache_read_tokens: int = 0,cache_write_tokens: int = 0,+ cache_write_5m_tokens: int = 0,+ cache_write_1h_tokens: int = 0,uncached_input_tokens: int = 0,):"""Record metrics for a request."""@@ -178,6 +184,12 @@ class PrometheusMetrics:pc = self.cache_by_provider[provider]pc["cache_read_tokens"] += cache_read_tokenspc["cache_write_tokens"] += cache_write_tokens+ pc["cache_write_5m_tokens"] += cache_write_5m_tokens+ pc["cache_write_1h_tokens"] += cache_write_1h_tokens+ if cache_write_5m_tokens > 0:+ pc["cache_write_5m_requests"] += 1+ if cache_write_1h_tokens > 0:+ pc["cache_write_1h_requests"] += 1pc["requests"] += 1if cache_read_tokens > 0:pc["hit_requests"] += 1diff --git a/tests/test_dashboard_cache_ttl_playwright.py b/tests/test_dashboard_cache_ttl_playwright.pynew file mode 100644index 000000000..09b398dc3--- /dev/null+++ b/tests/test_dashboard_cache_ttl_playwright.py@@ -0,0 +1,211 @@+"""Behavior-driven Playwright validation for dashboard TTL cache metrics."""++from __future__ import annotations++import json+import os+from pathlib import Path++import pytest++from headroom.dashboard import get_dashboard_html++playwright = pytest.importorskip("playwright.sync_api")+Page = playwright.Page+expect = playwright.expect+sync_playwright = playwright.sync_playwright+++def _sample_stats() -> dict:+ return {+ "cost": {+ "savings_usd": 12.34,+ "compression_savings_usd": 12.34,+ "cache_savings_usd": 5.67,+ "cli_tokens_avoided": 0,+ },+ "requests": {+ "total": 128,+ "cached": 96,+ "rate_limited": 0,+ "failed": 0,+ "by_provider": {"anthropic": 128},+ "by_model": {"claude-opus-4-6": 128},+ },+ "tokens": {+ "input": 245_000,+ "output": 88_000,+ "saved": 143_000,+ "cli_tokens_avoided": 0,+ "total_before_compression": 388_000,+ "savings_percent": 36.86,+ },+ "overhead": {"average_ms": 14.2, "min_ms": 4.5, "max_ms": 42.7},+ "ttfb": {"average_ms": 1320.0, "min_ms": 420.0, "max_ms": 2900.0},+ "latency": {"average_ms": 1510.0, "min_ms": 520.0, "max_ms": 3300.0},+ "waste_signals": {"json_bloat": 95_000, "repetition": 48_000},+ "savings_history": [+ ["2026-04-01T00:00:00Z", 12_000],+ ["2026-04-02T00:00:00Z", 38_000],+ ["2026-04-03T00:00:00Z", 57_000],+ ["2026-04-04T00:00:00Z", 102_000],+ ["2026-04-05T00:00:00Z", 143_000],+ ],+ "persistent_savings": {+ "display_session": {},+ "lifetime": {"tokens_saved": 143_000, "compression_savings_usd": 12.34},+ },+ "pipeline_timing": {},+ "compression_cache": {"mode": "cache"},+ "prefix_cache": {+ "by_provider": {+ "anthropic": {+ "cache_read_tokens": 9_800_000,+ "cache_write_tokens": 420_000,+ "cache_write_5m_tokens": 185_000,+ "cache_write_1h_tokens": 235_000,+ "cache_write_5m_requests": 18,+ "cache_write_1h_requests": 24,+ "requests": 128,+ "hit_requests": 96,+ "hit_rate": 75.0,+ "bust_count": 0,+ "bust_write_tokens": 0,+ "read_discount": "90%",+ "write_premium": "25%",+ "savings_usd": 5.67,+ "write_premium_usd": 0.42,+ "net_savings_usd": 5.67,+ "label": "Explicit breakpoints, 5-min TTL",+ "observed_ttl_buckets": {+ "5m": {"tokens": 185_000, "requests": 18},+ "1h": {"tokens": 235_000, "requests": 24},+ },+ "observed_ttl_mix": {+ "5m_pct": 44.0,+ "1h_pct": 56.0,+ "active_buckets": ["5m", "1h"],+ },+ }+ },+ "totals": {+ "cache_read_tokens": 9_800_000,+ "cache_write_tokens": 420_000,+ "cache_write_5m_tokens": 185_000,+ "cache_write_1h_tokens": 235_000,+ "cache_write_5m_requests": 18,+ "cache_write_1h_requests": 24,+ "requests": 128,+ "hit_requests": 96,+ "bust_count": 0,+ "bust_write_tokens": 0,+ "savings_usd": 5.67,+ "write_premium_usd": 0.42,+ "net_savings_usd": 5.67,+ "hit_rate": 75.0,+ "observed_ttl_buckets": {+ "5m": {"tokens": 185_000, "requests": 18},+ "1h": {"tokens": 235_000, "requests": 24},+ },+ "observed_ttl_mix": {+ "5m_pct": 44.0,+ "1h_pct": 56.0,+ "active_buckets": ["5m", "1h"],+ },+ },+ "prefix_freeze": {+ "busts_avoided": 0,+ "tokens_preserved": 0,+ "compression_foregone_tokens": 0,+ "net_benefit_tokens": 0,+ },+ "attribution": "Observed provider TTL buckets.",+ },+ }+++def _sample_history() -> dict:+ return {+ "history": [+ {+ "timestamp": "2026-04-01T00:00:00Z",+ "total_tokens_saved": 12_000,+ "compression_savings_usd": 0.6,+ },+ {+ "timestamp": "2026-04-05T00:00:00Z",+ "total_tokens_saved": 143_000,+ "compression_savings_usd": 12.34,+ },+ ],+ "series": {+ "daily": [+ {+ "timestamp": "2026-04-05T00:00:00Z",+ "tokens_saved": 20_000,+ "total_tokens_saved": 143_000,+ "compression_savings_usd_delta": 1.7,+ }+ ],+ "weekly": [],+ "monthly": [],+ },+ "lifetime": {"tokens_saved": 143_000, "compression_savings_usd": 12.34},+ }+++def _install_dashboard_routes(page: Page) -> None:+ stats = _sample_stats()+ history = _sample_history()+ health = {"status": "healthy", "version": "0.3.0"}+ dashboard_html = get_dashboard_html()++ def handler(route) -> None: # type: ignore[no-untyped-def]+ url = route.request.url+ if url.endswith("/dashboard") or url == "http://headroom.local/":+ route.fulfill(status=200, content_type="text/html", body=dashboard_html)+ return+ if url.endswith("/stats"):+ route.fulfill(status=200, content_type="application/json", body=json.dumps(stats))+ return+ if "/stats-history" in url:+ route.fulfill(+ status=200,+ content_type="application/json",+ body=json.dumps(history),+ )+ return+ if url.endswith("/health"):+ route.fulfill(status=200, content_type="application/json", body=json.dumps(health))+ return+ route.continue_()++ page.route("**/*", handler)+++def test_dashboard_renders_observed_ttl_metrics_and_can_capture_screenshot() -> None:+ artifact_dir = os.environ.get("HEADROOM_PLAYWRIGHT_ARTIFACT_DIR")++ with sync_playwright() as pw:+ browser = pw.chromium.launch()+ page = browser.new_page(viewport={"width": 1720, "height": 1400}, color_scheme="dark")+ _install_dashboard_routes(page)+ page.goto("http://headroom.local/dashboard", wait_until="load")++ expect(page.get_by_text("Observed TTL Buckets")).to_be_visible()+ expect(page.get_by_text("Provider-reported cache write mix")).to_be_visible()+ expect(page.get_by_test_id("ttl-bucket-headline")).to_have_text("1h leaning")+ expect(page.get_by_test_id("ttl-bucket-mix-1h-pct")).to_have_text("1h 56.0%")+ expect(page.get_by_test_id("ttl-bucket-mix-5m-pct")).to_have_text("5m 44.0%")+ expect(page.get_by_test_id("ttl-bucket-1h-value")).to_have_text("235.0k")+ expect(page.get_by_test_id("ttl-bucket-5m-value")).to_have_text("185.0k")+ expect(page.get_by_text("TTL 1h 56.0% / 5m 44.0%")).to_be_visible()++ screenshot_path = (+ Path(artifact_dir) / "dashboard-cache-ttl-main.png"+ if artifact_dir+ else Path.cwd() / "dashboard-cache-ttl-main.png"+ )+ screenshot_path.parent.mkdir(parents=True, exist_ok=True)+ page.screenshot(path=str(screenshot_path), full_page=True)+ browser.close()diff --git a/tests/test_proxy_cache_ttl_metrics.py b/tests/test_proxy_cache_ttl_metrics.pynew file mode 100644index 000000000..3d9301048--- /dev/null+++ b/tests/test_proxy_cache_ttl_metrics.py@@ -0,0 +1,147 @@+"""Tests for observed Anthropic cache TTL bucket metrics."""++from __future__ import annotations++import asyncio++import pytest++from headroom.proxy.cost import CostTracker, build_prefix_cache_stats+from headroom.proxy.prometheus_metrics import PrometheusMetrics+++def test_prometheus_metrics_tracks_observed_ttl_buckets() -> None:+ metrics = PrometheusMetrics()++ asyncio.run(+ metrics.record_request(+ provider="anthropic",+ model="claude-opus-4-6",+ input_tokens=100,+ output_tokens=20,+ tokens_saved=5,+ latency_ms=10.0,+ cache_read_tokens=40,+ cache_write_tokens=60,+ cache_write_5m_tokens=10,+ cache_write_1h_tokens=50,+ )+ )++ stats = metrics.cache_by_provider["anthropic"]+ assert stats["cache_write_5m_tokens"] == 10+ assert stats["cache_write_1h_tokens"] == 50+ assert stats["cache_write_5m_requests"] == 1+ assert stats["cache_write_1h_requests"] == 1+++def test_cost_tracker_exposes_observed_ttl_buckets_per_model() -> None:+ tracker = CostTracker()+ tracker.record_tokens(+ "claude-opus-4-6",+ tokens_saved=10,+ tokens_sent=90,+ cache_read_tokens=40,+ cache_write_tokens=60,+ cache_write_5m_tokens=10,+ cache_write_1h_tokens=50,+ uncached_tokens=20,+ )++ stats = tracker.stats()+ assert stats["cache_write_5m_tokens"] == 10+ assert stats["cache_write_1h_tokens"] == 50+ assert stats["per_model"]["claude-opus-4-6"]["cache_write_5m_tokens"] == 10+ assert stats["per_model"]["claude-opus-4-6"]["cache_write_1h_tokens"] == 50+++def test_prefix_cache_stats_include_observed_ttl_mix() -> None:+ metrics = PrometheusMetrics()+ provider_stats = metrics.cache_by_provider["anthropic"]+ provider_stats["requests"] = 2+ provider_stats["hit_requests"] = 1+ provider_stats["cache_read_tokens"] = 40+ provider_stats["cache_write_tokens"] = 60+ provider_stats["cache_write_5m_tokens"] = 15+ provider_stats["cache_write_1h_tokens"] = 45+ provider_stats["cache_write_5m_requests"] = 1+ provider_stats["cache_write_1h_requests"] = 1++ stats = build_prefix_cache_stats(metrics, None)+ anthropic = stats["by_provider"]["anthropic"]++ assert anthropic["observed_ttl_buckets"]["5m"]["tokens"] == 15+ assert anthropic["observed_ttl_buckets"]["1h"]["tokens"] == 45+ assert anthropic["observed_ttl_mix"]["5m_pct"] == 25.0+ assert anthropic["observed_ttl_mix"]["1h_pct"] == 75.0+ assert stats["totals"]["observed_ttl_buckets"]["5m"]["tokens"] == 15+ assert stats["totals"]["observed_ttl_buckets"]["1h"]["tokens"] == 45+++def test_streaming_parser_extracts_anthropic_ttl_bucket_usage() -> None:+ from headroom.proxy.server import HeadroomProxy, ProxyConfig++ proxy = HeadroomProxy(+ ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ )+ )++ chunk = (+ b'data: {"type":"message_start","message":{"usage":{"input_tokens":12,'+ b'"cache_read_input_tokens":3,"cache_creation_input_tokens":9,'+ b'"cache_creation":{"ephemeral_5m_input_tokens":4,"ephemeral_1h_input_tokens":5}}}}\n\n'+ )+ usage = proxy._parse_sse_usage(chunk, "anthropic")++ assert usage is not None+ assert usage["cache_creation_ephemeral_5m_input_tokens"] == 4+ assert usage["cache_creation_ephemeral_1h_input_tokens"] == 5+++def test_stats_endpoint_reports_observed_ttl_buckets() -> None:+ pytest.importorskip("fastapi")+ from fastapi.testclient import TestClient++ from headroom.proxy.server import ProxyConfig, create_app++ app = create_app(+ ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ )+ )++ proxy = app.state.proxy+ provider_stats = proxy.metrics.cache_by_provider["anthropic"]+ provider_stats["requests"] = 1+ provider_stats["hit_requests"] = 1+ provider_stats["cache_read_tokens"] = 30+ provider_stats["cache_write_tokens"] = 70+ provider_stats["cache_write_5m_tokens"] = 20+ provider_stats["cache_write_1h_tokens"] = 50+ provider_stats["cache_write_5m_requests"] = 1+ provider_stats["cache_write_1h_requests"] = 1++ with TestClient(app) as client:+ response = client.get("/stats")++ assert response.status_code == 200+ prefix_cache = response.json()["prefix_cache"]+ anthropic = prefix_cache["by_provider"]["anthropic"]+ assert anthropic["observed_ttl_buckets"]["5m"]["tokens"] == 20+ assert anthropic["observed_ttl_buckets"]["1h"]["tokens"] == 50+ assert prefix_cache["totals"]["observed_ttl_mix"]["active_buckets"] == ["5m", "1h"]