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: never grep-fold timestamped logs, size-weight savings, warn on no-op model limits (#3419)

Morteza Rastgoo73a6edbe83af
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdx
index ce44b245a..305f19ed1 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/configuration.mdx
@@ -334,6 +334,7 @@ headroom proxy --learn --min-evidence 3
| `HEADROOM_TELEMETRY` | Set to `on` for **local-only** usage stats (powers your own `/stats` and dashboard; nothing is sent externally) | `off` |
| `HEADROOM_STATELESS` | Set to `true` to disable filesystem writes | `false` |
| `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | -- |
+| `HEADROOM_LOSSLESS_COMPACTION` | Set to `0` to disable the byte-reversible lossless folds (grep heading, log run-collapse, diff/config folds) while leaving the rest of the compression pipeline active. Read per request, so the proxy's `/admin/runtime-env` hot-sync applies without a restart. | `1` |
| `HEADROOM_BASE_URL` | Base URL of the Headroom proxy (TypeScript SDK) | `http://localhost:8787` |
| `HEADROOM_API_KEY` | Optional API key for authenticated Headroom endpoints (TypeScript SDK) | -- |
| `HEADROOM_CONFIG_DIR` | Canonical config (read-mostly) root. Derives `models.json` and per-plugin config paths when set. | `~/.headroom/config` |
diff --git a/headroom/providers/anthropic.py b/headroom/providers/anthropic.py
index fb7278ab4..badce7a24 100644
--- a/headroom/providers/anthropic.py
+++ b/headroom/providers/anthropic.py
@@ -287,6 +287,31 @@ def _load_custom_model_config() -> dict[str, Any]:
config["context_limits"].update(anthropic_config["context_limits"])
if "pricing" in anthropic_config:
config["pricing"].update(anthropic_config["pricing"])
+ # Another provider's namespaced section ({"openai": {"context_limits":
+ # ...}}) is a correctly shaped config that this loader is simply not
+ # meant to consume, so it must not trip the no-effect warning below.
+ other_provider_section = "anthropic" not in loaded and any(
+ isinstance(section, dict)
+ and any(key in section for key in ("context_limits", "pricing", "encodings"))
+ for section in loaded.values()
+ )
+ if (
+ "context_limits" not in anthropic_config
+ and "pricing" not in anthropic_config
+ and not other_provider_section
+ ):
+ # Valid JSON object, but none of the keys we consume. Previously
+ # this was a SILENT no-op: the unknown-model warning tells the
+ # operator to "set HEADROOM_MODEL_LIMITS", they set the obvious
+ # flat shape {"my-model": 262144}, nothing happens, and there is
+ # no diagnostic anywhere. Name the expected shape instead.
+ logger.warning(
+ "HEADROOM_MODEL_LIMITS parsed but contained no 'context_limits' "
+ "or 'pricing' key, so it had NO EFFECT. Expected shape: "
+ '{"context_limits": {"<model>": <int>}, "pricing": {...}} '
+ '(optionally nested under an "anthropic" key). '
+ f"Got top-level keys: {sorted(map(str, anthropic_config))[:10]}"
+ )
logger.debug(f"Loaded custom model config from HEADROOM_MODEL_LIMITS: {loaded}")
except (ValueError, OSError) as e:
diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.py
index fc5d41545..bd11f1465 100644
--- a/headroom/proxy/cost.py
+++ b/headroom/proxy/cost.py
@@ -641,10 +641,16 @@ def build_session_summary(
best_compression = 0.0
best_detail = ""
if compressed_requests:
- avg_compression = round(
- sum(r["savings_pct"] for r in compressed_requests) / len(compressed_requests),
- 1,
- )
+ # Size-WEIGHTED, not a mean of per-request percentages. An unweighted
+ # mean lets one tiny, highly-compressible request (e.g. a repeated log
+ # line that folds 6,070 -> 83 tokens, 98.6%) dominate the headline while
+ # the large real requests it is averaged with barely moved, so the card
+ # can read "18.6% saved" on traffic whose forwarded bytes fell ~3%.
+ # Weighting by original size makes the number mean what an operator
+ # reads it as: the share of total tokens actually removed.
+ _orig_total = sum(r["original"] for r in compressed_requests)
+ _saved_total = sum(r["tokens_saved"] for r in compressed_requests)
+ avg_compression = round(100.0 * _saved_total / _orig_total, 1) if _orig_total else 0.0
best = max(compressed_requests, key=lambda r: r["savings_pct"])
best_compression = best["savings_pct"]
best_detail = f"{best['original']:,} → {best['optimized']:,} tokens"
diff --git a/headroom/transforms/lossless_compaction.py b/headroom/transforms/lossless_compaction.py
index 76c167e15..035615d83 100644
--- a/headroom/transforms/lossless_compaction.py
+++ b/headroom/transforms/lossless_compaction.py
@@ -14,6 +14,7 @@ unchanged. Nothing here raises.
from __future__ import annotations
+import os
import re
__all__ = [
@@ -59,6 +60,21 @@ _GREP_ROW_RE = re.compile(r"^(?P<path>[^\n:]+):(?P<line>\d+):(?P<content>.*)$")
# heading-form data row (``line:content``) produced by search_heading.
_HEADING_ROW_RE = re.compile(r"^(?P<line>\d+):(?P<content>.*)$")
+# A timestamped log line is NOT a grep row, but it has the same colon-delimited
+# shape: ``2026-09-02 14:30:00 [FATAL] ...`` splits as path=``2026-09-02 14``,
+# line=``30``, content=``00 [FATAL] ...``. Folding it hoists the date+hour into
+# a heading and strips it from every row, so the model sees ``30:00 [FATAL]``
+# and has to reconstruct the clock itself. The fold round-trips exactly, so the
+# inverse-check in compact_lossless cannot catch it -- it must be excluded here.
+_TIMESTAMP_ROW_RE = re.compile(
+ r"^\s*\[?(?:"
+ r"\d{4}-\d{2}-\d{2}[ T]\d{1,2}:\d{2}" # 2026-09-02 14:30 / ISO 8601 'T'
+ r"|\d{2}/\d{2}/\d{2,4}[ T]\d{1,2}:\d{2}" # 09/02/2026 14:30
+ r"|[A-Z][a-z]{2}\s+\d{1,2}\s+\d{1,2}:\d{2}" # syslog: Aug 16 11:02
+ r"|\d{1,2}:\d{2}:\d{2}(?:[.,]\d+)?(?:\s|\]|$)" # bare 15:03:53 / [15:03:53]
+ r")"
+)
+
# unified-diff ``index <sha>..<sha> <mode>`` line. The diff still applies
# without it (git only uses it for rename/blob bookkeeping).
_DIFF_INDEX_RE = re.compile(r"^index [0-9a-fA-F]+\.\.[0-9a-fA-F]+( [0-7]+)?$")
@@ -234,7 +250,7 @@ def search_heading(text: str) -> str:
out: list[str] = []
current_path: str | None = None
for line in lines:
- m = _GREP_ROW_RE.match(line)
+ m = None if _TIMESTAMP_ROW_RE.match(line) else _GREP_ROW_RE.match(line)
if m:
path = m.group("path")
if path != current_path:
@@ -307,7 +323,7 @@ def search_dir_heading(text: str) -> str:
out: list[str] = []
current_dir: str | None = None
for line in lines:
- m = _GREP_ROW_RE.match(line)
+ m = None if _TIMESTAMP_ROW_RE.match(line) else _GREP_ROW_RE.match(line)
if m and "/" in m.group("path"):
path = m.group("path")
cut = path.rindex("/") + 1
@@ -435,6 +451,19 @@ def _smaller(candidate: str, original: str) -> bool:
return len(candidate) < len(original)
+#: Env kill-switch for every fold in this module. Read per call (not cached at
+#: import) so the proxy's live ``POST /admin/runtime-env`` hot-sync applies
+#: without a restart, matching how the output-shaper switches behave.
+_LOSSLESS_COMPACTION_ENV = "HEADROOM_LOSSLESS_COMPACTION"
+
+
+def _lossless_compaction_enabled() -> bool:
+ raw = os.environ.get(_LOSSLESS_COMPACTION_ENV)
+ if raw is None:
+ return True
+ return raw.strip().lower() not in ("0", "false", "no", "off")
+
+
def compact_lossless(content: str, kind: str) -> str:
"""Dispatch format-native lossless compaction by ``kind``.
@@ -443,8 +472,15 @@ def compact_lossless(content: str, kind: str) -> str:
non-semantic bits, e.g. ANSI color for logs); if verification fails or the
result is not smaller, the original content is returned unchanged. Never
raises; unknown kinds pass through.
+
+ Set ``HEADROOM_LOSSLESS_COMPACTION=0`` to disable every fold here while
+ leaving the rest of the pipeline (Kompress, SmartCrusher, CCR) active. The
+ folds are byte-reversible, but the model only ever sees the folded side and
+ must reconstruct the original shape itself, which costs output tokens on
+ reasoning models. Operators need to be able to turn that off without
+ resorting to ``--no-optimize`` (which disables all compression).
"""
- if not content:
+ if not content or not _lossless_compaction_enabled():
return content
try:
if kind == "log":
diff --git a/tests/test_lossless_timestamp_guard.py b/tests/test_lossless_timestamp_guard.py
new file mode 100644
index 000000000..9136a06d2
--- /dev/null
+++ b/tests/test_lossless_timestamp_guard.py
@@ -0,0 +1,82 @@
+"""Timestamped log lines must never be folded as grep ``path:line:content`` rows.
+
+``2026-09-02 14:30:00 [FATAL] ...`` splits under _GREP_ROW_RE as
+path=``2026-09-02 14`` / line=``30`` / content=``00 [FATAL] ...``. Folding it
+hoists the date+hour into a heading and strips it from every row, so the model
+receives ``30:00 [FATAL] ...`` and has to rebuild the clock itself. The fold is
+byte-reversible, so compact_lossless's inverse-check cannot catch it.
+"""
+
+import os
+
+import pytest
+
+from headroom.transforms.lossless_compaction import compact_lossless
+
+
+def _multi_hour_log() -> str:
+ lines = [
+ f"2026-09-02 {h:02d}:{m:02d}:10 [INFO] worker heartbeat ok id={m}"
+ for h in (14, 15, 16)
+ for m in range(60)
+ ]
+ lines.insert(90, "2026-09-02 14:30:00 [FATAL] node evicted disk full")
+ return "\n".join(lines)
+
+
+ "sample",
+ [
+ _multi_hour_log(),
+ "\n".join(
+ f"Aug 16 11:{m:02d}:22 web-01 systemd[3397]: Starting example-worker.service {m}"
+ for m in range(60)
+ ),
+ "\n".join(f"[15:{m:02d}:53] tool: Bash(cmd {m})" for m in range(60)),
+ "\n".join(f"2026-09-02T14:{m:02d}:10 [WARN] latency high {m}" for m in range(60)),
+ ],
+ ids=["iso-datetime", "syslog", "bracketed-time", "iso-T"],
+)
+def test_timestamped_logs_are_never_folded(sample: str) -> None:
+ assert compact_lossless(sample, "search") == sample
+
+
+def test_fatal_line_keeps_its_full_timestamp() -> None:
+ out = compact_lossless(_multi_hour_log(), "search")
+ fatal = [line for line in out.split("\n") if "FATAL" in line]
+ assert fatal == ["2026-09-02 14:30:00 [FATAL] node evicted disk full"]
+
+
+def test_genuine_grep_output_still_folds() -> None:
+ """The guard must not cost us the real feature."""
+ grep = "\n".join(
+ f"src/lumina_tray/panel.py:{i}: def handler_{i}(self): pass" for i in range(40)
+ )
+ out = compact_lossless(grep, "search")
+ assert out != grep
+ assert len(out) < len(grep)
+ assert out.split("\n")[0] == "src/lumina_tray/panel.py"
+
+
+def test_env_kill_switch_disables_all_folds(monkeypatch: pytest.MonkeyPatch) -> None:
+ grep = "\n".join(
+ f"src/lumina_tray/panel.py:{i}: def handler_{i}(self): pass" for i in range(40)
+ )
+ monkeypatch.setenv("HEADROOM_LOSSLESS_COMPACTION", "0")
+ assert compact_lossless(grep, "search") == grep
+ monkeypatch.setenv("HEADROOM_LOSSLESS_COMPACTION", "1")
+ assert compact_lossless(grep, "search") != grep
+
+
+def test_kill_switch_is_read_live_not_cached_at_import() -> None:
+ """The proxy hot-syncs runtime env; a cached flag would ignore it."""
+ grep = "\n".join(f"src/a.py:{i}: x = {i}" for i in range(40))
+ prior = os.environ.pop("HEADROOM_LOSSLESS_COMPACTION", None)
+ try:
+ assert compact_lossless(grep, "search") != grep
+ os.environ["HEADROOM_LOSSLESS_COMPACTION"] = "off"
+ assert compact_lossless(grep, "search") == grep
+ finally:
+ os.environ.pop("HEADROOM_LOSSLESS_COMPACTION", None)
+ if prior is not None:
+ os.environ["HEADROOM_LOSSLESS_COMPACTION"] = prior
diff --git a/tests/test_provider_model_fallback.py b/tests/test_provider_model_fallback.py
index 9a83ec0ac..1edd18299 100644
--- a/tests/test_provider_model_fallback.py
+++ b/tests/test_provider_model_fallback.py
@@ -1,6 +1,7 @@
"""Tests for provider model fallback and configuration."""
import json
+import logging
import os
import tempfile
from pathlib import Path
@@ -245,6 +246,51 @@ class TestAnthropicConfigLoading:
loaded = anthropic_load_config()
assert loaded == {"context_limits": {}, "pricing": {}}
+ def test_flat_shape_env_var_warns_that_it_had_no_effect(self, caplog):
+ """A JSON *object* using the intuitive-but-wrong flat shape
+ ``{"my-model": 262144}`` is silently ignored by the loader.
+
+ The unknown-model warning tells operators to "set HEADROOM_MODEL_LIMITS",
+ so the flat shape is the natural first guess. Without a diagnostic the
+ operator sees the conservative default silently persist and has no way
+ to tell the config was never applied. Assert we now say so explicitly.
+ """
+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": '{"qwen3.8": 262144}'}):
+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):
+ loaded = anthropic_load_config()
+ assert loaded == {"context_limits": {}, "pricing": {}}
+ assert "NO EFFECT" in caplog.text
+ assert "context_limits" in caplog.text
+
+ def test_correct_shape_env_var_does_not_warn(self, caplog):
+ """The documented nested shape must apply cleanly and stay silent."""
+ cfg = '{"context_limits": {"qwen3.8": 262144}}'
+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": cfg}):
+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):
+ loaded = anthropic_load_config()
+ assert loaded["context_limits"]["qwen3.8"] == 262144
+ assert "NO EFFECT" not in caplog.text
+
+ def test_other_provider_namespaced_env_var_does_not_warn(self, caplog):
+ """``{"openai": {"context_limits": ...}}`` is the documented shape for the
+ OpenAI loader. The Anthropic loader consumes nothing from it, which is
+ correct, so it must not claim the config had no effect."""
+ cfg = '{"openai": {"context_limits": {"gpt-x": 400000}}}'
+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": cfg}):
+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):
+ loaded = anthropic_load_config()
+ assert loaded == {"context_limits": {}, "pricing": {}}
+ assert "NO EFFECT" not in caplog.text
+
+ def test_anthropic_section_without_known_keys_still_warns(self, caplog):
+ """An explicit ``anthropic`` section that carries none of the consumed
+ keys is the same silent no-op as the flat shape, so it warns."""
+ cfg = '{"anthropic": {"qwen3.8": 262144}}'
+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": cfg}):
+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):
+ anthropic_load_config()
+ assert "NO EFFECT" in caplog.text
+
def test_non_object_config_file_falls_back_to_defaults(self):
"""A models.json whose top level is not an object must not crash."""
with tempfile.TemporaryDirectory() as tmpdir: