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
feat: persist proxy savings history
Garm69080be9668e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1a68f4ac2..66285057f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- **Durable proxy savings history**+ - Persists proxy compression savings history locally at `~/.headroom/proxy_savings.json`+ - Supports `HEADROOM_SAVINGS_PATH` to override the storage location+ - Adds `/stats-history` with lifetime totals plus hourly/daily rollups for frontends+ - Extends `/stats` with a `persistent_savings` block while keeping `savings_history` backward compatible+ - Adds a historical mode to `/dashboard` backed by `/stats-history`- **`headroom learn`** — Offline failure learning for coding agents- Analyzes past conversation history (Claude Code, extensible to Cursor/Codex)- **Success correlation**: for each failure, finds what succeeded after and extracts the specific correctiondiff --git a/docs/metrics.md b/docs/metrics.mdindex 5c41571cd..ade1ba9b0 100644--- a/docs/metrics.md+++ b/docs/metrics.md@@ -12,6 +12,19 @@ curl http://localhost:8787/stats```json{+ "persistent_savings": {+ "lifetime": {+ "tokens_saved": 12500,+ "compression_savings_usd": 0.04+ },+ "recent_history": [+ {+ "timestamp": "2026-03-27T09:00:00Z",+ "total_tokens_saved": 12500,+ "compression_savings_usd": 0.04+ }+ ]+ },"requests": {"total": 42,"cached": 5,@@ -35,6 +48,43 @@ curl http://localhost:8787/stats}```+`/stats` keeps the existing live/session fields, including `savings_history`,+for backward compatibility. The new `persistent_savings` block is durable local+proxy compression history stored by default at `~/.headroom/proxy_savings.json`.+Use `HEADROOM_SAVINGS_PATH` to override the file location.++### Historical Savings Endpoint++```bash+curl http://localhost:8787/stats-history+```++```json+{+ "schema_version": 1,+ "generated_at": "2026-03-27T09:10:00Z",+ "lifetime": {+ "tokens_saved": 12500,+ "compression_savings_usd": 0.04+ },+ "history": [+ {+ "timestamp": "2026-03-27T09:00:00Z",+ "total_tokens_saved": 12000,+ "compression_savings_usd": 0.038+ }+ ],+ "series": {+ "hourly": [],+ "daily": []+ }+}+```++`/stats-history` is the stable frontend-facing API for durable proxy+compression history. It survives proxy restarts, tolerates missing or malformed+state files, and powers the historical view in `/dashboard`.+### Prometheus Metrics```bashdiff --git a/docs/proxy.md b/docs/proxy.mdindex ef805df17..9b10a50b6 100644--- a/docs/proxy.md+++ b/docs/proxy.md@@ -104,6 +104,28 @@ Response:curl http://localhost:8787/stats```+`/stats` remains the live/session-oriented endpoint and now also includes a+`persistent_savings` block with durable proxy compression lifetime totals plus a+small recent preview. The existing `savings_history` field is still present and+remains session-scoped for backward compatibility.++### Historical Savings++```bash+curl http://localhost:8787/stats-history+```++`/stats-history` exposes durable proxy compression history for dashboards and+other Headroom frontends. It returns:++- lifetime proxy compression totals+- bounded persisted checkpoint history+- derived hourly and daily rollups for charts+- UTC timestamps throughout++By default the proxy stores this history at `~/.headroom/proxy_savings.json`.+Set `HEADROOM_SAVINGS_PATH` to override the location.+### Prometheus Metrics```bashdiff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.htmlindex ee3a59c0e..bfc8dea97 100644--- a/headroom/dashboard/templates/dashboard.html+++ b/headroom/dashboard/templates/dashboard.html@@ -54,6 +54,29 @@</header><main class="p-6 max-w-7xl mx-auto">+ <div class="flex flex-col gap-3 md:flex-row md:items-center md:justify-between mb-6">+ <div>+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-2">Dashboard View</div>+ <div class="inline-flex rounded-lg border border-border bg-surface p-1">+ <button class="px-3 py-1.5 text-sm rounded-md transition-colors"+ :class="viewMode === 'live' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"+ @click="viewMode = 'live'">+ Current / Live+ </button>+ <button class="px-3 py-1.5 text-sm rounded-md transition-colors"+ :class="viewMode === 'history' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"+ @click="viewMode = 'history'">+ Historical+ </button>+ </div>+ </div>+ <div class="text-xs text-gray-500" x-show="viewMode === 'history'">+ Stored at <span class="font-mono text-gray-400" x-text="historyStats.storage_path || '~/.headroom/proxy_savings.json'"></span>+ </div>+ </div>++ <template x-if="viewMode === 'live'">+ <div><!-- Hero Metrics (reordered: Savings $ -> Tokens Saved % -> Quality Confidence -> Overhead) --><div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6"><!-- Savings ($) - Combined: compression + prefix cache -->@@ -507,6 +530,172 @@</table></div></div>+ </div>+ </template>++ <template x-if="viewMode === 'history'">+ <div>+ <div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6">+ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Lifetime Compression Savings</div>+ <div class="flex items-baseline gap-2">+ <span class="text-3xl font-light tabular-nums text-emerald-400"+ x-text="'$' + formatCurrency(historyStats.lifetime?.compression_savings_usd || 0)"></span>+ </div>+ <div class="mt-2 text-xs text-gray-500">+ Proxy compression only+ </div>+ </div>++ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Lifetime Tokens Saved</div>+ <div class="flex items-baseline gap-2">+ <span class="text-3xl font-light tabular-nums text-accent"+ x-text="formatNumber(historyStats.lifetime?.tokens_saved || 0)"></span>+ </div>+ <div class="mt-2 text-xs text-gray-500"+ x-text="formatNumber((historyStats.history || []).length) + ' recorded checkpoints'"></div>+ </div>++ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Active Days</div>+ <div class="flex items-baseline gap-2">+ <span class="text-3xl font-light tabular-nums"+ x-text="formatNumber((historyStats.series?.daily || []).length)"></span>+ </div>+ <div class="mt-2 text-xs text-gray-500" x-text="historyWindowLabel"></div>+ </div>++ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Average Saved / Day</div>+ <div class="flex items-baseline gap-2">+ <span class="text-3xl font-light tabular-nums"+ x-text="formatNumber(historyAverageTokensPerDay)"></span>+ </div>+ <div class="mt-2 text-xs text-gray-500">Based on persisted daily buckets</div>+ </div>+ </div>++ <template x-if="hasHistoricalData">+ <div>+ <div class="grid grid-cols-1 lg:grid-cols-3 gap-4 mb-6">+ <div class="bg-surface rounded-lg p-4 border border-border lg:col-span-2">+ <div class="flex justify-between items-center mb-4">+ <span class="text-sm font-medium text-gray-300">Historical Savings Trend</span>+ <span class="text-xs text-gray-500 font-mono" x-text="historyTrendLabel"></span>+ </div>+ <template x-if="historicalTrend.length >= 2">+ <div class="h-48">+ <svg class="w-full h-full" viewBox="0 0 200 64" preserveAspectRatio="none">+ <defs>+ <linearGradient id="history-trend-gradient" x1="0%" y1="0%" x2="0%" y2="100%">+ <stop offset="0%" style="stop-color:#22d3ee;stop-opacity:0.2"/>+ <stop offset="100%" style="stop-color:#22d3ee;stop-opacity:0"/>+ </linearGradient>+ </defs>+ <path :d="getObjectTrendArea(historicalTrend, 'total_tokens_saved')"+ fill="url(#history-trend-gradient)"></path>+ <path class="trend-line"+ :d="getObjectTrendLine(historicalTrend, 'total_tokens_saved')"></path>+ </svg>+ </div>+ </template>+ <template x-if="historicalTrend.length < 2">+ <div class="h-48 flex items-center justify-center text-sm text-gray-500 italic">+ Historical trend data will appear after more saved checkpoints.+ </div>+ </template>+ </div>++ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-sm font-medium mb-4 text-gray-300">Historical Summary</div>+ <div class="space-y-3">+ <div class="flex justify-between items-center">+ <span class="text-sm text-gray-400">Latest total</span>+ <span class="font-mono text-sm"+ x-text="formatNumber(historyStats.lifetime?.tokens_saved || 0) + ' tokens'"></span>+ </div>+ <div class="flex justify-between items-center">+ <span class="text-sm text-gray-400">Hourly buckets</span>+ <span class="font-mono text-sm"+ x-text="formatNumber((historyStats.series?.hourly || []).length)"></span>+ </div>+ <div class="flex justify-between items-center">+ <span class="text-sm text-gray-400">Daily buckets</span>+ <span class="font-mono text-sm"+ x-text="formatNumber((historyStats.series?.daily || []).length)"></span>+ </div>+ <div class="flex justify-between items-center">+ <span class="text-sm text-gray-400">Retention</span>+ <span class="font-mono text-sm"+ x-text="(historyStats.retention?.max_history_age_days || 0) + 'd / ' + formatNumber(historyStats.retention?.max_history_points || 0)"></span>+ </div>+ </div>+ </div>+ </div>++ <div class="grid grid-cols-1 lg:grid-cols-2 gap-4">+ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-sm font-medium mb-4 text-gray-300">Daily Savings</div>+ <template x-if="(historyStats.series?.daily || []).length > 0">+ <div class="space-y-3">+ <template x-for="point in recentDailyHistory" :key="point.timestamp">+ <div class="flex items-center justify-between">+ <div>+ <div class="text-sm text-gray-300" x-text="formatDate(point.timestamp)"></div>+ <div class="text-xs text-gray-500"+ x-text="formatNumber(point.total_tokens_saved) + ' cumulative'"></div>+ </div>+ <div class="text-right">+ <div class="font-mono text-sm text-accent"+ x-text="formatNumber(point.tokens_saved) + ' tokens'"></div>+ <div class="text-xs text-emerald-400"+ x-text="'$' + formatCurrency(point.compression_savings_usd_delta || 0)"></div>+ </div>+ </div>+ </template>+ </div>+ </template>+ <template x-if="(historyStats.series?.daily || []).length === 0">+ <div class="text-sm text-gray-500 italic py-8 text-center">+ Daily rollups will appear after persisted history spans at least one checkpoint.+ </div>+ </template>+ </div>++ <div class="bg-surface rounded-lg p-4 border border-border">+ <div class="text-sm font-medium mb-4 text-gray-300">Recent Historical Checkpoints</div>+ <div class="space-y-3">+ <template x-for="point in recentHistoricalPoints" :key="point.timestamp">+ <div class="flex items-center justify-between">+ <div>+ <div class="text-sm text-gray-300" x-text="formatDateTime(point.timestamp)"></div>+ <div class="text-xs text-gray-500">Cumulative proxy compression savings</div>+ </div>+ <div class="text-right">+ <div class="font-mono text-sm text-accent"+ x-text="formatNumber(point.total_tokens_saved) + ' tokens'"></div>+ <div class="text-xs text-emerald-400"+ x-text="'$' + formatCurrency(point.compression_savings_usd || 0)"></div>+ </div>+ </div>+ </template>+ </div>+ </div>+ </div>+ </div>+ </template>++ <template x-if="!hasHistoricalData">+ <div class="bg-surface rounded-lg border border-border p-10 text-center">+ <div class="text-lg text-gray-300 mb-2">No persisted savings history yet</div>+ <div class="text-sm text-gray-500 max-w-2xl mx-auto">+ Historical data is written locally after proxy requests save tokens. Keep using Headroom and this view will fill in automatically across restarts.+ </div>+ </div>+ </template>+ </div>+ </template></main>@@ -526,9 +715,11 @@function dashboard() {return {stats: {},+ historyStats: {},healthy: true,version: '0.3.0',lastUpdate: 'never',+ viewMode: 'live',requestHistory: [],savingsHistory: [],expandedRows: {},@@ -548,12 +739,14 @@async fetchStats() {try {- const [statsRes, healthRes] = await Promise.all([+ const [statsRes, historyRes, healthRes] = await Promise.all([fetch('/stats'),+ fetch('/stats-history'),fetch('/health')]);this.stats = await statsRes.json();+ this.historyStats = await historyRes.json();const health = await healthRes.json();this.healthy = health.status === 'healthy';this.version = health.version || '0.3.0';@@ -600,6 +793,24 @@return d.toLocaleTimeString();},+ formatDate(ts) {+ if (!ts) return '-';+ return new Date(ts).toLocaleDateString(undefined, {+ month: 'short',+ day: 'numeric',+ });+ },++ formatDateTime(ts) {+ if (!ts) return '-';+ return new Date(ts).toLocaleString(undefined, {+ month: 'short',+ day: 'numeric',+ hour: '2-digit',+ minute: '2-digit',+ });+ },+truncateModel(model) {if (!model) return '-';return model.replace(/^(anthropic\.|openai\.|bedrock\/)/, '')@@ -607,6 +818,52 @@.substring(0, 20);},+ // --- Historical View ---++ get hasHistoricalData() {+ return (this.historyStats.history || []).length > 0;+ },++ get historicalTrend() {+ const daily = this.historyStats.series?.daily || [];+ if (daily.length >= 2) return daily;+ const hourly = this.historyStats.series?.hourly || [];+ if (hourly.length >= 2) return hourly;+ return this.historyStats.history || [];+ },++ get historyTrendLabel() {+ const daily = this.historyStats.series?.daily || [];+ if (daily.length >= 2) return 'Daily cumulative savings';+ const hourly = this.historyStats.series?.hourly || [];+ if (hourly.length >= 2) return 'Hourly cumulative savings';+ return 'Checkpoint history';+ },++ get historyWindowLabel() {+ const history = this.historyStats.history || [];+ if (history.length === 0) return 'Waiting for saved requests';+ const first = history[0]?.timestamp;+ const last = history[history.length - 1]?.timestamp;+ if (!first || !last) return 'Persisted locally';+ return this.formatDate(first) + ' to ' + this.formatDate(last);+ },++ get historyAverageTokensPerDay() {+ const daily = this.historyStats.series?.daily || [];+ const lifetime = this.historyStats.lifetime?.tokens_saved || 0;+ if (daily.length === 0) return 0;+ return Math.round(lifetime / daily.length);+ },++ get recentDailyHistory() {+ return [...(this.historyStats.series?.daily || [])].slice(-7).reverse();+ },++ get recentHistoricalPoints() {+ return [...(this.historyStats.history || [])].slice(-8).reverse();+ },+// --- Prefix Cache ---get cacheSavingsPercent() {@@ -759,7 +1016,7 @@getTrendLine(history) {if (!history || history.length < 2) return '';- const values = history.map(h => h[1]);+ const values = history.map(h => Array.isArray(h) ? h[1] : (h?.total_tokens_saved || 0));const min = Math.min(...values);const max = Math.max(...values);const range = max - min || 1;@@ -779,6 +1036,29 @@if (!line) return '';return line + ` L200,64 L0,64 Z`;},++ getObjectTrendLine(history, valueKey) {+ if (!history || history.length < 2) return '';+ const values = history.map(point => point?.[valueKey] || 0);+ const min = Math.min(...values);+ const max = Math.max(...values);+ const range = max - min || 1;++ const points = values.map((value, index) => {+ const x = (index / (values.length - 1)) * 200;+ const y = 60 - ((value - min) / range) * 56;+ return `${x},${y}`;+ });++ return 'M' + points.join(' L');+ },++ getObjectTrendArea(history, valueKey) {+ if (!history || history.length < 2) return '';+ const line = this.getObjectTrendLine(history, valueKey);+ if (!line) return '';+ return line + ` L200,64 L0,64 Z`;+ },};}</script>diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pynew file mode 100644index 000000000..b92987fb5--- /dev/null+++ b/headroom/proxy/savings_tracker.py@@ -0,0 +1,427 @@+"""Durable proxy savings history tracking.++Persists cumulative proxy compression savings to a local JSON file so+historical charts survive proxy restarts and can be shared by multiple+Headroom frontends.+"""++from __future__ import annotations++import json+import logging+import os+import tempfile+import threading+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Any++logger = logging.getLogger(__name__)++HEADROOM_SAVINGS_PATH_ENV_VAR = "HEADROOM_SAVINGS_PATH"+DEFAULT_SAVINGS_DIR = ".headroom"+DEFAULT_SAVINGS_FILE = "proxy_savings.json"+SCHEMA_VERSION = 1+DEFAULT_MAX_HISTORY_POINTS = 5000+DEFAULT_MAX_HISTORY_AGE_DAYS = 365++try:+ import litellm++ LITELLM_AVAILABLE = True+except ImportError:+ LITELLM_AVAILABLE = False+++def get_default_savings_storage_path() -> str:+ """Return the configured savings storage path."""+ env_path = os.environ.get(HEADROOM_SAVINGS_PATH_ENV_VAR, "").strip()+ if env_path:+ return env_path+ return str(Path.home() / DEFAULT_SAVINGS_DIR / DEFAULT_SAVINGS_FILE)+++def _utc_now() -> datetime:+ return datetime.now(UTC)+++def _to_utc_iso(dt: datetime) -> str:+ return dt.astimezone(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")+++def _parse_timestamp(value: Any) -> datetime | None:+ if not isinstance(value, str) or not value:+ return None++ normalized = value.replace("Z", "+00:00")+ try:+ dt = datetime.fromisoformat(normalized)+ except ValueError:+ return None++ if dt.tzinfo is None:+ dt = dt.replace(tzinfo=UTC)+ return dt.astimezone(UTC)+++def _coerce_int(value: Any, default: int = 0) -> int:+ try:+ return max(int(value), 0)+ except (TypeError, ValueError):+ return default+++def _coerce_float(value: Any, default: float = 0.0) -> float:+ try:+ return max(float(value), 0.0)+ except (TypeError, ValueError):+ return default+++def _resolve_litellm_model(model: str) -> str:+ """Resolve model name to one LiteLLM recognizes."""+ if not LITELLM_AVAILABLE:+ return model++ try:+ litellm.cost_per_token(model=model, prompt_tokens=1, completion_tokens=0)+ return model+ except Exception:+ pass++ prefixes = {+ "claude-": "anthropic/",+ "gpt-": "openai/",+ "o1-": "openai/",+ "o3-": "openai/",+ "o4-": "openai/",+ "gemini-": "google/",+ }+ for pattern, prefix in prefixes.items():+ if model.startswith(pattern):+ candidate = f"{prefix}{model}"+ try:+ litellm.cost_per_token(model=candidate, prompt_tokens=1, completion_tokens=0)+ return candidate+ except Exception:+ break++ return model+++def _estimate_compression_savings_usd(model: str, tokens_saved: int) -> float:+ """Estimate compression savings in USD from saved input tokens."""+ if tokens_saved <= 0 or not LITELLM_AVAILABLE:+ return 0.0++ try:+ resolved = _resolve_litellm_model(model)+ info = litellm.model_cost.get(resolved, {})+ input_cost_per_token = info.get("input_cost_per_token")+ if not input_cost_per_token:+ return 0.0+ return float(tokens_saved) * float(input_cost_per_token)+ except Exception:+ return 0.0+++def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:+ """Normalize persisted history entries across schema shapes."""+ timestamp: datetime | None = None+ total_tokens_saved = 0+ compression_savings_usd = 0.0++ if isinstance(entry, dict):+ timestamp = _parse_timestamp(entry.get("timestamp"))+ total_tokens_saved = _coerce_int(entry.get("total_tokens_saved"))+ compression_savings_usd = _coerce_float(entry.get("compression_savings_usd"))+ elif isinstance(entry, (list, tuple)) and len(entry) >= 2:+ timestamp = _parse_timestamp(entry[0])+ total_tokens_saved = _coerce_int(entry[1])+ if len(entry) >= 3:+ compression_savings_usd = _coerce_float(entry[2])+ else:+ return None++ if timestamp is None:+ return None++ return {+ "timestamp": _to_utc_iso(timestamp),+ "total_tokens_saved": total_tokens_saved,+ "compression_savings_usd": round(compression_savings_usd, 6),+ }+++class SavingsTracker:+ """Persist bounded proxy compression savings history."""++ def __init__(+ self,+ path: str | None = None,+ max_history_points: int = DEFAULT_MAX_HISTORY_POINTS,+ max_history_age_days: int = DEFAULT_MAX_HISTORY_AGE_DAYS,+ ) -> None:+ self._path = Path(path or get_default_savings_storage_path())+ self._max_history_points = max_history_points+ self._max_history_age_days = max_history_age_days+ self._lock = threading.Lock()+ self._state = self._load_state()++ @property+ def storage_path(self) -> str:+ return str(self._path)++ def record_compression_savings(+ self,+ *,+ model: str,+ tokens_saved: int,+ timestamp: datetime | str | None = None,+ ) -> bool:+ """Persist a cumulative savings checkpoint when compression changed totals."""+ delta_tokens = _coerce_int(tokens_saved)+ if delta_tokens <= 0:+ return False++ timestamp_dt = (+ _parse_timestamp(timestamp)+ if isinstance(timestamp, str)+ else timestamp.astimezone(UTC)+ if isinstance(timestamp, datetime)+ else _utc_now()+ )+ if timestamp_dt is None:+ timestamp_dt = _utc_now()++ delta_usd = _estimate_compression_savings_usd(model, delta_tokens)++ with self._lock:+ lifetime = self._state["lifetime"]+ lifetime["tokens_saved"] += delta_tokens+ lifetime["compression_savings_usd"] = round(+ lifetime["compression_savings_usd"] + delta_usd, 6+ )++ self._state["history"].append(+ {+ "timestamp": _to_utc_iso(timestamp_dt),+ "total_tokens_saved": lifetime["tokens_saved"],+ "compression_savings_usd": lifetime["compression_savings_usd"],+ }+ )+ self._trim_history_locked(reference_time=timestamp_dt)+ self._save_locked()+ return True++ def stats_preview(self, recent_points: int = 20) -> dict[str, Any]:+ """Return a compact preview for `/stats`."""+ snapshot = self.snapshot()+ return {+ "schema_version": snapshot["schema_version"],+ "storage_path": snapshot["storage_path"],+ "lifetime": snapshot["lifetime"],+ "history_points": len(snapshot["history"]),+ "recent_history": snapshot["history"][-recent_points:],+ "retention": snapshot["retention"],+ }++ def history_response(self) -> dict[str, Any]:+ """Return frontend-friendly historical data for `/stats-history`."""+ snapshot = self.snapshot()+ history = snapshot["history"]+ return {+ "schema_version": snapshot["schema_version"],+ "generated_at": _to_utc_iso(_utc_now()),+ "storage_path": snapshot["storage_path"],+ "lifetime": snapshot["lifetime"],+ "history": history,+ "series": {+ "hourly": self._build_rollup(history, bucket="hour"),+ "daily": self._build_rollup(history, bucket="day"),+ },+ "retention": snapshot["retention"],+ }++ def snapshot(self) -> dict[str, Any]:+ with self._lock:+ history = [dict(item) for item in self._state["history"]]+ return {+ "schema_version": SCHEMA_VERSION,+ "storage_path": str(self._path),+ "lifetime": dict(self._state["lifetime"]),+ "history": history,+ "retention": {+ "max_history_points": self._max_history_points,+ "max_history_age_days": self._max_history_age_days,+ },+ }++ def _default_state(self) -> dict[str, Any]:+ return {+ "schema_version": SCHEMA_VERSION,+ "lifetime": {"tokens_saved": 0, "compression_savings_usd": 0.0},+ "history": [],+ }++ def _load_state(self) -> dict[str, Any]:+ if not self._path.exists():+ return self._default_state()++ try:+ with open(self._path, encoding="utf-8") as f:+ raw = json.load(f)+ except (json.JSONDecodeError, OSError) as e:+ logger.warning("Failed to load savings history from %s: %s", self._path, e)+ return self._default_state()++ return self._sanitize_state(raw)++ def _sanitize_state(self, raw: Any) -> dict[str, Any]:+ if not isinstance(raw, dict):+ return self._default_state()++ history_raw = raw.get("history", [])+ normalized_history = []+ if isinstance(history_raw, list):+ for item in history_raw:+ normalized = _normalize_history_entry(item)+ if normalized is not None:+ normalized_history.append(normalized)++ normalized_history.sort(key=lambda item: item["timestamp"])++ lifetime_raw = raw.get("lifetime", {})+ lifetime_tokens_saved = 0+ lifetime_savings_usd = 0.0+ if isinstance(lifetime_raw, dict):+ lifetime_tokens_saved = _coerce_int(lifetime_raw.get("tokens_saved"))+ lifetime_savings_usd = _coerce_float(lifetime_raw.get("compression_savings_usd"))++ if normalized_history:+ last = normalized_history[-1]+ lifetime_tokens_saved = max(lifetime_tokens_saved, last["total_tokens_saved"])+ lifetime_savings_usd = max(+ lifetime_savings_usd,+ _coerce_float(last["compression_savings_usd"]),+ )++ state = {+ "schema_version": SCHEMA_VERSION,+ "lifetime": {+ "tokens_saved": lifetime_tokens_saved,+ "compression_savings_usd": round(lifetime_savings_usd, 6),+ },+ "history": normalized_history,+ }++ if normalized_history:+ reference_time = _parse_timestamp(normalized_history[-1]["timestamp"]) or _utc_now()+ original_state = self._state if hasattr(self, "_state") else None+ self._state = state+ try:+ self._trim_history_locked(reference_time=reference_time)+ state = self._state+ finally:+ if original_state is not None:+ self._state = original_state++ return state++ def _trim_history_locked(self, reference_time: datetime | None = None) -> None:+ history = self._state["history"]+ if not history:+ return++ if self._max_history_age_days > 0:+ cutoff = (reference_time or _utc_now()) - timedelta(days=self._max_history_age_days)+ filtered = [+ item+ for item in history+ if (_parse_timestamp(item["timestamp"]) or _utc_now()) >= cutoff+ ]+ if not filtered:+ filtered = [history[-1]]+ history = filtered++ if self._max_history_points > 0 and len(history) > self._max_history_points:+ history = history[-self._max_history_points :]++ self._state["history"] = history++ def _save_locked(self) -> None:+ try:+ self._path.parent.mkdir(parents=True, exist_ok=True)+ payload = {+ "schema_version": SCHEMA_VERSION,+ "lifetime": self._state["lifetime"],+ "history": self._state["history"],+ }+ json_data = json.dumps(payload, indent=2)++ fd, tmp_path = tempfile.mkstemp(+ dir=self._path.parent,+ prefix=".proxy_savings_",+ suffix=".tmp",+ )+ try:+ with os.fdopen(fd, "w", encoding="utf-8") as f:+ f.write(json_data)+ f.flush()+ os.fsync(f.fileno())+ Path(tmp_path).replace(self._path)+ except Exception:+ try:+ Path(tmp_path).unlink()+ except OSError:+ pass+ raise+ except OSError as e:+ logger.warning("Failed to save savings history to %s: %s", self._path, e)++ def _build_rollup(self, history: list[dict[str, Any]], bucket: str) -> list[dict[str, Any]]:+ if not history:+ return []++ aggregated: dict[str, dict[str, Any]] = {}+ prev_total_tokens = 0+ prev_total_usd = 0.0++ for point in history:+ timestamp = _parse_timestamp(point["timestamp"])+ if timestamp is None:+ continue++ if bucket == "hour":+ bucket_start = timestamp.replace(minute=0, second=0, microsecond=0)+ else:+ bucket_start = timestamp.replace(hour=0, minute=0, second=0, microsecond=0)++ bucket_key = _to_utc_iso(bucket_start)+ total_tokens_saved = _coerce_int(point.get("total_tokens_saved"))+ total_usd = _coerce_float(point.get("compression_savings_usd"))+ delta_tokens = max(total_tokens_saved - prev_total_tokens, 0)+ delta_usd = max(total_usd - prev_total_usd, 0.0)++ prev_total_tokens = total_tokens_saved+ prev_total_usd = total_usd++ entry = aggregated.setdefault(+ bucket_key,+ {+ "timestamp": bucket_key,+ "tokens_saved": 0,+ "compression_savings_usd_delta": 0.0,+ "total_tokens_saved": total_tokens_saved,+ "compression_savings_usd": total_usd,+ },+ )+ entry["tokens_saved"] += delta_tokens+ entry["compression_savings_usd_delta"] = round(+ entry["compression_savings_usd_delta"] + delta_usd,+ 6,+ )+ entry["total_tokens_saved"] = total_tokens_saved+ entry["compression_savings_usd"] = round(total_usd, 6)++ return list(aggregated.values())diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex a5a62c3a2..6aa78ee83 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -89,6 +89,7 @@ from headroom.config import (from headroom.dashboard import get_dashboard_htmlfrom headroom.providers import AnthropicProvider, OpenAIProviderfrom headroom.proxy.memory_handler import MemoryConfig, MemoryHandler+from headroom.proxy.savings_tracker import SavingsTrackerfrom headroom.telemetry import get_telemetry_collectorfrom headroom.telemetry.toin import get_toinfrom headroom.tokenizers import get_tokenizer@@ -1252,7 +1253,7 @@ class CostTracker:class PrometheusMetrics:"""Prometheus-compatible metrics."""- def __init__(self):+ def __init__(self, savings_tracker: SavingsTracker | None = None):self.requests_total = 0self.requests_by_provider: dict[str, int] = defaultdict(int)self.requests_by_model: dict[str, int] = defaultdict(int)@@ -1315,6 +1316,7 @@ class PrometheusMetrics:# Cumulative savings history (timestamp → cumulative tokens saved)self.savings_history: list[tuple[str, int]] = []+ self.savings_tracker = savings_tracker or SavingsTracker()self._lock = asyncio.Lock()@@ -1406,6 +1408,12 @@ class PrometheusMetrics:if len(self.savings_history) > 500:self.savings_history = self.savings_history[-500:]+ if tokens_saved > 0:+ self.savings_tracker.record_compression_savings(+ model=model,+ tokens_saved=tokens_saved,+ )+async def record_rate_limited(self):async with self._lock:self.requests_rate_limited += 1@@ -2006,6 +2014,7 @@ class HeadroomProxy:logger.info(f"CCR (Compress-Cache-Retrieve): ENABLED ({', '.join(ccr_features)})")else:logger.info("CCR: DISABLED")+ logger.info(f"Savings history: {self.metrics.savings_tracker.storage_path}")async def shutdown(self):"""Cleanup async resources."""@@ -6997,6 +7006,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:version=__version__,lifespan=lifespan,)+ app.state.proxy = proxy# CORSapp.add_middleware(@@ -7124,6 +7134,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:compression_tokens = m.tokens_saved_totalcache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)total_tokens_all_layers = compression_tokens + cli_tokens_avoided+ persistent_savings = m.savings_tracker.stats_preview()return {"summary": summary,@@ -7199,6 +7210,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:else {},"waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},"savings_history": m.savings_history[-100:], # Last 100 data points+ "persistent_savings": persistent_savings,"prefix_cache": prefix_cache_stats,"cost": _merge_cost_stats(proxy.cost_tracker.stats() if proxy.cost_tracker else None,@@ -7240,6 +7252,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:"recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],}+ @app.get("/stats-history")+ async def stats_history():+ """Get durable proxy compression savings history for frontends."""+ return proxy.metrics.savings_tracker.history_response()+@app.get("/metrics")async def metrics():"""Prometheus metrics endpoint."""diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.pynew file mode 100644index 000000000..a74fcad0f--- /dev/null+++ b/tests/test_proxy_savings_history.py@@ -0,0 +1,171 @@+"""Tests for durable proxy savings history."""++from __future__ import annotations++import asyncio+import json++import pytest++pytest.importorskip("fastapi")++from fastapi.testclient import TestClient++from headroom.proxy.savings_tracker import SavingsTracker+from headroom.proxy.server import ProxyConfig, create_app+++def _record_request(client: TestClient, *, model: str, tokens_saved: int) -> None:+ proxy = client.app.state.proxy+ asyncio.run(+ proxy.metrics.record_request(+ provider="openai",+ model=model,+ input_tokens=120,+ output_tokens=24,+ tokens_saved=tokens_saved,+ latency_ms=15.0,+ )+ )+++def test_savings_tracker_rollups_are_chart_friendly(tmp_path, monkeypatch):+ path = tmp_path / "proxy_savings.json"+ tracker = SavingsTracker(path=str(path), max_history_points=100, max_history_age_days=30)+ monkeypatch.setattr(+ "headroom.proxy.savings_tracker._estimate_compression_savings_usd",+ lambda model, tokens_saved: tokens_saved / 1000.0,+ )++ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=100,+ timestamp="2026-03-27T09:10:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=50,+ timestamp="2026-03-27T09:40:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=25,+ timestamp="2026-03-27T10:05:00Z",+ )+ tracker.record_compression_savings(+ model="gpt-4o",+ tokens_saved=10,+ timestamp="2026-03-28T08:00:00Z",+ )++ response = tracker.history_response()++ assert response["lifetime"]["tokens_saved"] == 185+ assert response["lifetime"]["compression_savings_usd"] == pytest.approx(0.185)+ assert len(response["history"]) == 4++ hourly = response["series"]["hourly"]+ assert [point["timestamp"] for point in hourly] == [+ "2026-03-27T09:00:00Z",+ "2026-03-27T10:00:00Z",+ "2026-03-28T08:00:00Z",+ ]+ assert hourly[0]["tokens_saved"] == 150+ assert hourly[0]["total_tokens_saved"] == 150+ assert hourly[1]["tokens_saved"] == 25+ assert hourly[1]["total_tokens_saved"] == 175+ assert hourly[2]["tokens_saved"] == 10+ assert hourly[2]["total_tokens_saved"] == 185++ daily = response["series"]["daily"]+ assert [point["timestamp"] for point in daily] == [+ "2026-03-27T00:00:00Z",+ "2026-03-28T00:00:00Z",+ ]+ assert daily[0]["tokens_saved"] == 175+ assert daily[0]["total_tokens_saved"] == 175+ assert daily[1]["tokens_saved"] == 10+ assert daily[1]["total_tokens_saved"] == 185+++def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ _record_request(client, model="gpt-4o", tokens_saved=40)++ stats = client.get("/stats")+ assert stats.status_code == 200+ stats_data = stats.json()+ assert "savings_history" in stats_data+ assert "persistent_savings" in stats_data+ assert all(len(point) == 2 for point in stats_data["savings_history"])+ assert stats_data["persistent_savings"]["lifetime"]["tokens_saved"] == 40+ assert stats_data["persistent_savings"]["storage_path"] == str(savings_path)++ history = client.get("/stats-history")+ assert history.status_code == 200+ history_data = history.json()+ assert history_data["schema_version"] == 1+ assert history_data["storage_path"] == str(savings_path)+ assert history_data["lifetime"]["tokens_saved"] == 40+ assert list(history_data["series"].keys()) == ["hourly", "daily"]++ with TestClient(create_app(config)) as client:+ history = client.get("/stats-history")+ assert history.status_code == 200+ assert history.json()["lifetime"]["tokens_saved"] == 40++ _record_request(client, model="gpt-4o", tokens_saved=15)++ updated = client.get("/stats-history").json()+ assert updated["lifetime"]["tokens_saved"] == 55+ assert len(updated["history"]) == 2++ persisted = json.loads(savings_path.read_text())+ assert persisted["lifetime"]["tokens_saved"] == 55+++def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ savings_path.write_text("{not valid json", encoding="utf-8")+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ response = client.get("/stats-history")+ assert response.status_code == 200+ data = response.json()+ assert data["lifetime"]["tokens_saved"] == 0+ assert data["history"] == []+++def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):+ savings_path = tmp_path / "proxy_savings.json"+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))++ config = ProxyConfig(+ cache_enabled=False,+ rate_limit_enabled=False,+ log_requests=False,+ )++ with TestClient(create_app(config)) as client:+ response = client.get("/dashboard")+ assert response.status_code == 200+ html = response.text+ assert "Current / Live" in html+ assert "Historical" in html+ assert "fetch('/stats-history')" in html