fix(proxy): let an explicit compress-user-messages off beat the profile

The default `coding` savings profile turns user-message compression on,
and the documented way to override a profile knob is its env var. For
HEADROOM_COMPRESS_USER_MESSAGES that only worked one way:
ProxyConfig.compress_user_messages was a plain bool defaulting to False,
so an explicit 0 was indistinguishable from "not set", and
proxy_pipeline_kwargs() only ever forced the value to True. With the
coding profile, HEADROOM_COMPRESS_USER_MESSAGES=0 was silently ignored:
the startup banner still reported compress_user=True and the router kept
rewriting plain user text (pasted logs, error output, paths).

Make the field tri-state like compress_system_messages: None follows the
profile, an explicit True or False overrides it. The `headroom proxy`
command, the `python -m headroom.proxy.server` entry point and the
uvicorn factory now read the env var as an optional bool. With nothing
set, every profile behaves exactly as before. Anthropic tool_result
blocks still compress with the flag off; the role gate only covers text.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garm
2026-10-02 15:31:05 +02:00
co-authored by Claude Opus 5.5
parent d5318ac235
commit 95ff25f991
7 changed files with 46 additions and 8 deletions
+1 -1
View File
@@ -231,7 +231,7 @@ Fine-grained control over what gets compressed and how hard. Most users pick a [
| `--mode` / `HEADROOM_MODE` | `cache` | `cache` compresses only the newest delta (prefix-cache safe); `token` maximizes removal. |
| `--target-ratio` / `HEADROOM_TARGET_RATIO` | unset | Keep-ratio for ML text compression; lower = more aggressive (e.g. `0.10`). |
| `HEADROOM_MIN_TOKENS` | `500` | Minimum block size before a tool output is compressed. |
| `HEADROOM_COMPRESS_USER_MESSAGES` | `false` | Compress content inside user-role messages (tool results live there). The `coding` profile turns this on. No `--compress-user-messages` flag on `headroom proxy`; the direct module entry point (`python -m headroom.proxy.server`) does accept one. |
| `HEADROOM_COMPRESS_USER_MESSAGES` | profile | Compress text inside user-role messages. The `coding` profile turns this on; set `0` to keep user text verbatim under it. Anthropic `tool_result` blocks compress either way. No `--compress-user-messages` flag on `headroom proxy`; the direct module entry point (`python -m headroom.proxy.server`) does accept one. |
| `HEADROOM_COMPRESS_SYSTEM_MESSAGES` | unset | Compress system prompts. Off by default to keep the hottest cache prefix stable. |
| `HEADROOM_PROTECT_RECENT` | profile | Never compress the N most recent turns. |
| `--protect-tool-results` / `HEADROOM_PROTECT_TOOL_RESULTS` | empty | Comma-separated tool names whose output is never lossy-compressed. |
+3 -2
View File
@@ -336,8 +336,9 @@ def proxy_pipeline_kwargs(config: object) -> dict[str, object]:
if profile.min_chars_for_block is not None:
kwargs["min_chars_for_block_compression"] = profile.min_chars_for_block
if getattr(config, "compress_user_messages", False):
kwargs["compress_user_messages"] = True
compress_user_messages = getattr(config, "compress_user_messages", None)
if compress_user_messages is not None:
kwargs["compress_user_messages"] = bool(compress_user_messages)
compress_system_messages = getattr(config, "compress_system_messages", None)
if compress_system_messages is not None:
+1 -1
View File
@@ -1346,7 +1346,7 @@ def proxy(
rate_limit_enabled=not no_rate_limit,
rate_limit_requests_per_minute=rpm if rpm is not None else 60,
rate_limit_tokens_per_minute=tpm,
compress_user_messages=_get_env_bool("HEADROOM_COMPRESS_USER_MESSAGES", False),
compress_user_messages=_get_env_bool_optional("HEADROOM_COMPRESS_USER_MESSAGES"),
periodic_malloc_trim_enabled=_get_env_bool(
"HEADROOM_MALLOC_TRIM", default_periodic_malloc_trim()
),
+4 -2
View File
@@ -283,8 +283,10 @@ class ProxyConfig:
# prefix-cache zone. Enable for OpenAI/Azure chat workloads where the bulk
# of input lives in user messages (pasted code/text, RAG context) and the
# router would otherwise have nothing eligible to compress.
# CLI: --compress-user-messages; env: HEADROOM_COMPRESS_USER_MESSAGES=1.
compress_user_messages: bool = False
# None follows the savings profile (`coding` turns it on); an explicit
# True/False overrides the profile either way.
# CLI: --compress-user-messages; env: HEADROOM_COMPRESS_USER_MESSAGES=1/0.
compress_user_messages: bool | None = None
# Named savings policy shared across Claude/Codex/Cursor proxy handlers.
# CLI/env: HEADROOM_SAVINGS_PROFILE=agent-90.
savings_profile: str | None = None
+6 -2
View File
@@ -6017,6 +6017,7 @@ def _proxy_config_from_env() -> ProxyConfig:
# posture (compress_user, protect_recent, min_tokens). HEADROOM_SAVINGS_PROFILE
# overrides.
savings_profile=os.environ.get("HEADROOM_SAVINGS_PROFILE") or "coding",
compress_user_messages=_get_env_optional_bool("HEADROOM_COMPRESS_USER_MESSAGES"),
read_maturation=rollout.is_enabled("read_maturation"),
read_maturation_quiesce_turns=_get_env_int("HEADROOM_READ_MATURATION_QUIESCE_TURNS", 5),
read_maturation_max_hold_turns=_get_env_int("HEADROOM_READ_MATURATION_MAX_HOLD_TURNS", 25),
@@ -6808,8 +6809,11 @@ if __name__ == "__main__":
if protect_tool_results
else frozenset(),
mode=normalize_proxy_mode(_get_env_str("HEADROOM_MODE", PROXY_MODE_CACHE)),
compress_user_messages=args.compress_user_messages
or _get_env_bool("HEADROOM_COMPRESS_USER_MESSAGES", False),
compress_user_messages=(
True
if args.compress_user_messages
else _get_env_optional_bool("HEADROOM_COMPRESS_USER_MESSAGES")
),
savings_profile=os.environ.get("HEADROOM_SAVINGS_PROFILE") or "coding",
# Default 0.4 keep-ratio so the Kompress text (prose/code) path compresses
# meaningfully out of the box; HEADROOM_TARGET_RATIO overrides.
+11
View File
@@ -500,6 +500,17 @@ def test_proxy_explicit_config_overrides_agent_90_profile() -> None:
assert kwargs["min_tokens_to_compress"] == 300
def test_proxy_explicit_compress_user_messages_off_overrides_coding_profile() -> None:
# coding turns user-message compression on; an explicit off
# (HEADROOM_COMPRESS_USER_MESSAGES=0) must win like every other override,
# and leaving it unset must keep the profile default.
explicit_off = ProxyConfig(savings_profile="coding", compress_user_messages=False)
unset = ProxyConfig(savings_profile="coding")
assert proxy_pipeline_kwargs(explicit_off)["compress_user_messages"] is False
assert proxy_pipeline_kwargs(unset)["compress_user_messages"] is True
def test_agent_90_router_uses_ccr_sampling_not_lossless_table() -> None:
router = ContentRouter(
ContentRouterConfig(
+20
View File
@@ -291,6 +291,26 @@ class TestCLIProxyEnvVars:
assert result.exit_code == 0, result.output
assert captured_config["config"].min_tokens_to_crush == 120
@pytest.mark.parametrize(
("env", "expected"), [({"HEADROOM_COMPRESS_USER_MESSAGES": "0"}, False), ({}, True)]
)
def test_compress_user_messages_env_off_overrides_profile(self, runner, env, expected):
"""HEADROOM_COMPRESS_USER_MESSAGES=0 must turn off the coding profile's
user-message compression; unset keeps the profile default (on)."""
from headroom.agent_savings import proxy_pipeline_kwargs
captured_config = {}
def mock_run_server(config, **kwargs):
captured_config["config"] = config
with patch("headroom.proxy.server.run_server", mock_run_server):
result = runner.invoke(main, ["proxy"], env=env, catch_exceptions=False)
assert result.exit_code == 0, result.output
kwargs = proxy_pipeline_kwargs(captured_config["config"])
assert kwargs["compress_user_messages"] is expected
def test_headroom_min_tokens_zero_is_preserved(self, runner):
"""HEADROOM_MIN_TOKENS=0 is a legitimate value ("crush everything") and
must not be discarded by an `or 500` fallback (regression)."""