Skip to content

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.

fix(savings): cap ledger retention at 30 days (#1985)

Ztkentb3a559ba56a3
diff --git a/headroom/cli/savings.py b/headroom/cli/savings.py
index 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.py
index 19c0c7374..0b0454ee6 100644
--- a/headroom/savings_ledger.py
+++ b/headroom/savings_ledger.py
@@ -48,14 +48,18 @@ except ImportError:
SCHEMA_VERSION = 1
UNKNOWN = "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 * 1024
def _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.py
index 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"] == 500
assert 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 today
assert 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"] == 1
def 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.output
assert "Savings by client" in result.output and "claude-code" in result.output
assert "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 == 0
payload = 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"] == 1
assert "by_repo" not in payload
@@ -279,3 +282,21 @@ def test_proxy_record_request_appends_ledger_event(tmp_path, monkeypatch):
assert "claude-code" in clients
assert "proxy" in clients
assert 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