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
fix(savings): cap ledger retention at 30 days (#1985)
Ztkentb3a559ba56a3
diff --git a/headroom/cli/savings.py b/headroom/cli/savings.pyindex 302bde4ec..5e72a2eed 100644--- a/headroom/cli/savings.py+++ b/headroom/cli/savings.py@@ -40,7 +40,7 @@ def _window_line(label: str, window: dict[str, Any]) -> str:before = int(window.get("tokens_before", 0) or 0)cost = float(window.get("cost_usd", 0.0) or 0.0)return (- f"{label:<11} {_bar(pct)} {pct:5.1f}% "+ f"{label:<12} {_bar(pct)} {pct:5.1f}% "f"saved {_tokens(saved)} / {_tokens(before)} tokens {_money(cost)}")@@ -49,10 +49,10 @@ def _window_line(label: str, window: dict[str, Any]) -> str:@click.option("--json", "as_json", is_flag=True, help="Emit the raw report as JSON.")@click.option("--days",- type=click.IntRange(min=1),+ type=click.IntRange(min=1, max=savings_ledger.MAX_RETENTION_DAYS),default=savings_ledger.DEFAULT_RETENTION_DAYS,show_default=True,- help="Retention/lookback window for the ledger, in days.",+ help=f"Retention/lookback window for the ledger, in days (max {savings_ledger.MAX_RETENTION_DAYS}).",)@click.option("--reset", is_flag=True, help="Delete the savings ledger and start fresh.")def savings(as_json: bool, days: int, reset: bool) -> None:@@ -87,7 +87,7 @@ def savings(as_json: bool, days: int, reset: bool) -> None:click.echo("")click.echo(_window_line("Today", report.windows["today"]))click.echo(_window_line("Last 7 days", report.windows["last_7_days"]))- click.echo(_window_line("All time", report.windows["all_time"]))+ click.echo(_window_line("Last 30 days", report.windows["last_30_days"]))if report.by_model:click.echo("")diff --git a/headroom/savings_ledger.py b/headroom/savings_ledger.pyindex 19c0c7374..0b0454ee6 100644--- a/headroom/savings_ledger.py+++ b/headroom/savings_ledger.py@@ -48,14 +48,18 @@ except ImportError:SCHEMA_VERSION = 1UNKNOWN = "unknown"-DEFAULT_RETENTION_DAYS = 365+# Report windows never look back further than 30 days, and events older than+# this are pruned from disk, keeping the JSONL small.+MAX_RETENTION_DAYS = 30+DEFAULT_RETENTION_DAYS = 30# Blended input price ($/token) used only when litellm cannot price the model.# Mirrors the ~$3 / 1M input-token assumption the MCP stats path already uses.DEFAULT_FALLBACK_INPUT_COST_PER_TOKEN = 3.0 / 1_000_000# Disk hygiene: compact the ledger once it grows past this size. Retention is# also enforced on read, so accuracy never depends on compaction having run.-_COMPACT_SIZE_BYTES = 8 * 1024 * 1024+# Small because retention is only 30 days — the file should never be large.+_COMPACT_SIZE_BYTES = 1 * 1024 * 1024def _utc_now() -> datetime:@@ -286,6 +290,9 @@ def aggregate_savings("""Aggregate the durable ledger into lifetime / windowed / per-dimension views."""now = now or _utc_now()+ # Hard-cap the lookback at 30 days regardless of caller input (0/None means+ # "use the cap", never "unbounded"), keeping the report bounded and small.+ retention_days = max(1, min(retention_days or MAX_RETENTION_DAYS, MAX_RETENTION_DAYS))events = _read_events(path, retention_days=retention_days, now=now)# "Today" is local-calendar-day; the 7-day window is a rolling 168h.@@ -294,7 +301,9 @@ def aggregate_savings()week_cutoff = now - timedelta(days=7)- all_time = _Bucket()+ # All retained events are within the 30-day cap, so this bucket doubles as+ # both the "Last 30 days" window and the (now 30-day-bounded) lifetime view.+ windowed = _Bucket()today = _Bucket()last_7 = _Bucket()by_model: dict[str, _Bucket] = {}@@ -309,7 +318,7 @@ def aggregate_savings(except (TypeError, ValueError):cost = 0.0- all_time.add(saved=saved, before=before, cost=cost)+ windowed.add(saved=saved, before=before, cost=cost)if ts >= today_cutoff:today.add(saved=saved, before=before, cost=cost)if ts >= week_cutoff:@@ -328,11 +337,11 @@ def aggregate_savings(return SavingsReport(path=str(_resolve_path(path)),schema_version=SCHEMA_VERSION,- lifetime=all_time.to_dict(),+ lifetime=windowed.to_dict(),windows={"today": today.to_dict(),"last_7_days": last_7.to_dict(),- "all_time": all_time.to_dict(),+ "last_30_days": windowed.to_dict(),},by_model=model_rows,by_client=_ranked(by_client, "client"),@@ -383,6 +392,7 @@ def _maybe_compact(target: Path) -> None:__all__ = ["SCHEMA_VERSION",+ "MAX_RETENTION_DAYS","DEFAULT_RETENTION_DAYS","DEFAULT_FALLBACK_INPUT_COST_PER_TOKEN","SavingsReport",diff --git a/tests/test_savings_ledger.py b/tests/test_savings_ledger.pyindex b19590251..83782f0b5 100644--- a/tests/test_savings_ledger.py+++ b/tests/test_savings_ledger.py@@ -66,7 +66,7 @@ def test_breakdowns_aggregate_by_dimension(monkeypatch, tmp_path):assert clients["proxy"]["tokens_saved"] == 1400-def test_windows_today_week_alltime(monkeypatch, tmp_path):+def test_windows_today_week_last30(monkeypatch, tmp_path):_events_env(monkeypatch, tmp_path)now = datetime(2026, 6, 17, 12, 0, tzinfo=UTC)L.record_savings_event(@@ -84,32 +84,35 @@ def test_windows_today_week_alltime(monkeypatch, tmp_path):tokens_after=700,model=None,client="c",- timestamp=now - timedelta(days=30),+ timestamp=now - timedelta(days=20),)report = L.aggregate_savings(now=now)assert report.windows["today"]["tokens_saved"] == 500assert report.windows["last_7_days"]["tokens_saved"] == 500 + 400- assert report.windows["all_time"]["tokens_saved"] == 500 + 400 + 300- assert report.windows["all_time"]["calls"] == 3+ assert report.windows["last_30_days"]["tokens_saved"] == 500 + 400 + 300+ assert report.windows["last_30_days"]["calls"] == 3# 500 saved out of 1000 before todayassert report.windows["today"]["savings_percent"] == pytest.approx(50.0)-def test_retention_excludes_old_events(monkeypatch, tmp_path):+def test_retention_hard_capped_at_30_days(monkeypatch, tmp_path):_events_env(monkeypatch, tmp_path)now = datetime(2026, 6, 17, 12, 0, tzinfo=UTC)L.record_savings_event(tokens_before=1000, tokens_after=500, model=None, client="c", timestamp=now)+ # 60 days old: within the requested 365-day window but past the 30-day cap.L.record_savings_event(tokens_before=1000,tokens_after=500,model=None,client="c",- timestamp=now - timedelta(days=400),+ timestamp=now - timedelta(days=60),)+ # Caller asks for 365 days, but retention is hard-capped at 30.report = L.aggregate_savings(now=now, retention_days=365)assert report.lifetime["calls"] == 1+ assert report.windows["last_30_days"]["calls"] == 1def test_appends_do_not_clobber_and_survive_restart(monkeypatch, tmp_path):@@ -184,7 +187,7 @@ def test_cli_renders_sections_and_json(monkeypatch, tmp_path):assert result.exit_code == 0# No redundant top-line headline; the windows lead the output.assert "cost avoided" not in result.output- assert "Today" in result.output and "All time" in result.output+ assert "Today" in result.output and "Last 30 days" in result.outputassert "Savings by client" in result.output and "claude-code" in result.outputassert "Per-repo totals" not in result.output@@ -192,7 +195,7 @@ def test_cli_renders_sections_and_json(monkeypatch, tmp_path):assert result_json.exit_code == 0payload = json.loads(result_json.output)assert payload["lifetime"]["tokens_saved"] == 700- assert payload["windows"]["all_time"]["calls"] == 1+ assert payload["windows"]["last_30_days"]["calls"] == 1assert "by_repo" not in payload@@ -279,3 +282,21 @@ def test_proxy_record_request_appends_ledger_event(tmp_path, monkeypatch):assert "claude-code" in clientsassert "proxy" in clientsassert any(row["model"] == "gpt-4o" for row in report.by_model)+++# --------------------------------------------------------------------------- #+# retention cap + stale-schema reset+# --------------------------------------------------------------------------- #++[email protected]("bad_days", ["31", "60", "365"])+def test_cli_days_flag_capped_at_30(monkeypatch, tmp_path, bad_days):+ pytest.importorskip("click")+ from click.testing import CliRunner++ from headroom.cli.savings import savings++ _events_env(monkeypatch, tmp_path)+ result = CliRunner().invoke(savings, ["--days", bad_days])+ assert result.exit_code != 0+ assert "30" in result.output # IntRange error mentions the allowed max