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): coding profile compresses the recent delta (protect_recent 2->0, min_tokens 25->10) (#2145)

Tejas Chopraeca3db62a33c
diff --git a/headroom/agent_savings.py b/headroom/agent_savings.py
index aa90bc437..9861bf8ea 100644
--- a/headroom/agent_savings.py
+++ b/headroom/agent_savings.py
@@ -158,9 +158,15 @@ _PROFILES: dict[str, AgentSavingsProfile] = {
# append-only forwarding), not by refusing to touch user turns.
compress_user_messages=True,
compress_system_messages=False, # system prompt is the hottest cache
- protect_recent=2, # keep the active code working set verbatim
+ # Compress the newest observation delta. In cache mode the delta IS the
+ # newest turn(s), so a positional guard here suppresses the only thing
+ # cache mode can compress (large recent grep/test/build tool output).
+ # The code working set stays byte-exact via protect_reads below — a TYPE
+ # guard on file reads — which is the real fidelity protection, so 0 loses
+ # no correctness while unblocking compression of recent non-read output.
+ protect_recent=0,
protect_analysis_context=True,
- min_tokens_to_compress=25, # low → compression is visible
+ min_tokens_to_compress=10, # low → even modest deltas are eligible
max_items_after_crush=15,
smart_crusher_with_compaction=True,
force_kompress=False, # don't override diff/log lossless with lossy ML
diff --git a/tests/test_agent_savings.py b/tests/test_agent_savings.py
index 165949b7a..6b319fbe5 100644
--- a/tests/test_agent_savings.py
+++ b/tests/test_agent_savings.py
@@ -64,15 +64,15 @@ def test_agent_90_profile_exports_cross_agent_proxy_env() -> None:
assert env["HEADROOM_ACCURACY_GUARD"] == "strict"
-def test_coding_persona_protects_working_set_and_stays_visible() -> None:
+def test_coding_persona_compresses_recent_delta_and_stays_visible() -> None:
profile = get_agent_savings_profile("coding")
env = profile.proxy_env()
assert env["HEADROOM_SAVINGS_PROFILE"] == "coding"
assert env["HEADROOM_MODE"] == "cache" # delta-only compression at ~0 prefix-cache busts
- assert env["HEADROOM_PROTECT_RECENT"] == "2" # keep the active code working set verbatim
- assert env["HEADROOM_MIN_TOKENS"] == "25" # low → compression is actually visible
+ assert env["HEADROOM_PROTECT_RECENT"] == "0" # reads guarded by type, not position
+ assert env["HEADROOM_MIN_TOKENS"] == "10" # low → even modest deltas are eligible
# Cache mode compresses the newest observation delta → compress_user must be ON.
assert env["HEADROOM_COMPRESS_USER_MESSAGES"] == "1"
assert env["HEADROOM_COMPRESS_SYSTEM_MESSAGES"] == "0" # system prompt is the hottest cache
@@ -89,6 +89,35 @@ def test_coding_persona_protects_working_set_and_stays_visible() -> None:
assert env["HEADROOM_MIN_CHARS_FOR_BLOCK"] == "25"
+def test_coding_profile_couples_zero_protect_recent_with_type_read_guard() -> None:
+ """Fidelity invariant behind #2145's protect_recent 2->0.
+
+ Dropping positional protection (protect_recent=0) is only safe because the
+ code working set stays byte-exact via the TYPE-based read guard
+ (protect_reads=True), and any *other* recent delta that does get compressed
+ stays losslessly recoverable via CCR (lossless=0 means lossy-with-CCR, not
+ silent loss) while the frozen prefix is left untouched (cache mode). This is
+ the honest boundary: recent file reads are verbatim, recent non-read deltas
+ are recoverable — not "nothing is ever touched". If a future edit drops the
+ read guard while keeping protect_recent=0, recent reads would silently
+ degrade, so this test fails closed on that pairing.
+ """
+ profile = get_agent_savings_profile("coding")
+
+ # Positional protection is off ...
+ assert profile.protect_recent == 0
+ # ... so the byte-exact guarantee for reads MUST come from the type guard.
+ assert profile.protect_reads is True
+
+ env = profile.proxy_env()
+ assert env["HEADROOM_PROTECT_RECENT"] == "0"
+ assert env["HEADROOM_PROTECT_READS"] == "1"
+ # Lossy compression is on, but CCR keeps compressed deltas recoverable, and
+ # cache mode compresses only the newest delta (frozen prefix stays byte-stable).
+ assert env["HEADROOM_LOSSLESS"] == "0"
+ assert env["HEADROOM_MODE"] == "cache"
+
+
def test_general_persona_has_no_positional_code_protection() -> None:
profile = get_agent_savings_profile("general")
@@ -102,15 +131,15 @@ def test_general_persona_has_no_positional_code_protection() -> None:
def test_personas_omit_target_ratio_in_pipeline_kwargs() -> None:
# coding compresses the delta observation (cache mode) → compress_user True;
# general has no positional code working set and leaves user turns intact.
- for name, expected_protect, expected_compress_user in (
- ("coding", 2, True),
- ("general", 0, False),
+ for name, expected_protect, expected_compress_user, expected_min_tokens in (
+ ("coding", 0, True, 10),
+ ("general", 0, False, 25),
):
kwargs = proxy_pipeline_kwargs(ProxyConfig(savings_profile=name))
assert kwargs["protect_recent"] == expected_protect
assert kwargs["read_protection_window"] == expected_protect
- assert kwargs["min_tokens_to_compress"] == 25
+ assert kwargs["min_tokens_to_compress"] == expected_min_tokens
assert kwargs["compress_user_messages"] is expected_compress_user
assert kwargs["compress_system_messages"] is False
assert kwargs["force_kompress"] is False
@@ -122,8 +151,8 @@ def test_persona_apply_profile_leaves_target_ratio_untouched() -> None:
apply_agent_savings_profile(cfg, "coding")
- assert cfg.protect_recent == 2
- assert cfg.min_tokens_to_compress == 25
+ assert cfg.protect_recent == 0
+ assert cfg.min_tokens_to_compress == 10
assert cfg.target_ratio == 0.42 # persona did not override an explicit ratio