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(proxy): wire CompressionPolicy through handlers + flip default enabled (F2.1 c5/5)

chopratejas0fef428f1fec
diff --git a/crates/headroom-proxy/src/config.rs b/crates/headroom-proxy/src/config.rs
index c7d02db51..8cc0ae593 100644
--- a/crates/headroom-proxy/src/config.rs
+++ b/crates/headroom-proxy/src/config.rs
@@ -288,18 +288,20 @@ pub struct CliArgs {
)]
pub cache_control_auto_frozen: CacheControlAutoFrozen,
- /// Phase F PR-F2.1 c3/6: gate the per-auth-mode `CompressionPolicy`
- /// enforcement. Default `disabled`: F2.1 c1–c5 ship behaviour-
- /// identical to current main. c6/6 flips the default to `enabled`.
+ /// Phase F PR-F2.1 c5/5: per-auth-mode `CompressionPolicy`
+ /// enforcement is now ON by default. Subscription users skip
+ /// CacheAligner; PAYG/OAuth keep current behaviour. Operators
+ /// can flip back to `disabled` via the env var if F2.1 surfaces
+ /// any subscription regression.
///
/// Source priority: CLI flag →
/// `HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT` env var →
- /// default (`disabled` in c3–c5, `enabled` from c6/6 onward).
+ /// default (`enabled` from c5/5 onward).
#[arg(
long = "auth-mode-policy-enforcement",
env = "HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT",
value_enum,
- default_value_t = AuthModePolicyEnforcement::Disabled,
+ default_value_t = AuthModePolicyEnforcement::Enabled,
)]
pub auth_mode_policy_enforcement: AuthModePolicyEnforcement,
@@ -606,10 +608,14 @@ impl Config {
// Match production default so the cache-control walker is
// exercised under test without per-test opt-in.
cache_control_auto_frozen: CacheControlAutoFrozen::Enabled,
- // F2.1 default: enforcement off so existing tests (which
- // expect PAYG-style behaviour for every auth mode) stay
- // green without per-test opt-out. F2.1's own integration
- // tests opt-IN per-case to assert the enforcement path.
+ // F2.1 c5/5: enforcement is ON by default in production
+ // (Config::from_cli inherits the CliArgs default which is
+ // `Enabled`). For tests, we keep `Disabled` so the
+ // existing PAYG-shaped test expectations stay green
+ // without per-test opt-out — F2.1's regression tests
+ // opt-IN to enforcement explicitly. If you're writing a
+ // new test that needs to exercise the enforcement-on
+ // path, set this field to `Enabled` in your test setup.
auth_mode_policy_enforcement: AuthModePolicyEnforcement::Disabled,
// Production default: strip internal `x-headroom-*` headers
// from upstream-bound requests. Tests opt out per-case via
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 2b598fde3..45251393b 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -880,6 +880,17 @@ class AnthropicHandlerMixin:
# Record all tool_results in the verified frozen prefix as stable
comp_cache.mark_stable_from_messages(messages, frozen_message_count)
+ # F2.1 c5/5: derive the per-request CompressionPolicy
+ # from the auth_mode classified at request entry. The
+ # policy short-circuits CacheAligner for subscription
+ # users (closes the cache-instability complaints in
+ # #327/#388). When the enforcement env var is off, the
+ # policy collapses to PAYG so behaviour is unchanged.
+ from headroom.transforms.compression_policy import resolve_policy
+
+ compression_policy = resolve_policy(
+ getattr(request.state, "auth_mode", None)
+ )
async with stage_timer.measure("compression_first_stage"):
result = await self._run_compression_in_executor(
lambda: self.anthropic_pipeline.apply(
@@ -890,6 +901,7 @@ class AnthropicHandlerMixin:
frozen_message_count=frozen_message_count,
biases=biases,
request_id=request_id,
+ compression_policy=compression_policy,
),
timeout=COMPRESSION_TIMEOUT_SECONDS,
)
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 7f9e999b0..2b2805b5b 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -431,6 +431,11 @@ class OpenAIHandlerMixin:
# Re-freeze boundary
openai_frozen_count = comp_cache.compute_frozen_count(messages)
+ # F2.1 c5/5: per-request CompressionPolicy. See the
+ # equivalent block in handlers/anthropic.py.
+ from headroom.transforms.compression_policy import resolve_policy
+
+ compression_policy = resolve_policy(getattr(request.state, "auth_mode", None))
result = await self._run_compression_in_executor(
lambda: self.openai_pipeline.apply(
messages=working_messages,
@@ -439,6 +444,7 @@ class OpenAIHandlerMixin:
context=extract_user_query(working_messages),
frozen_message_count=openai_frozen_count,
biases=_hook_biases,
+ compression_policy=compression_policy,
),
timeout=COMPRESSION_TIMEOUT_SECONDS,
)
@@ -462,6 +468,7 @@ class OpenAIHandlerMixin:
context=extract_user_query(messages),
frozen_message_count=openai_frozen_count,
biases=_hook_biases,
+ compression_policy=compression_policy,
),
timeout=COMPRESSION_TIMEOUT_SECONDS,
)
diff --git a/headroom/transforms/compression_policy.py b/headroom/transforms/compression_policy.py
index a52e19f1d..ea71cfb9b 100644
--- a/headroom/transforms/compression_policy.py
+++ b/headroom/transforms/compression_policy.py
@@ -18,6 +18,7 @@ docstring.
from __future__ import annotations
+import os
from dataclasses import dataclass
from headroom.proxy.auth_mode import AuthMode
@@ -78,3 +79,43 @@ def policy_default_payg() -> CompressionPolicy:
enforcement-on and enforcement-off paths.
"""
return policy_for_mode(AuthMode.PAYG)
+
+
+_ENFORCEMENT_ENV = "HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT"
+
+
+def is_enforcement_enabled() -> bool:
+ """Read the enforcement flag from the environment.
+
+ Same env var the Rust proxy reads (``Config::auth_mode_policy_enforcement``)
+ so the two paths stay in lockstep with one operator switch.
+ Default (when unset): ``True`` from F2.1 c5/5 onward, matching
+ the Rust default after the c5 flip.
+
+ NOT cached — read every call so an operator can flip the env var
+ in a hot-reload scenario. The cost is one ``dict.get`` per call,
+ well below noise.
+ """
+ val = os.environ.get(_ENFORCEMENT_ENV, "enabled").strip().lower()
+ # Same set of off-values the telemetry beacon honours
+ # (`headroom/telemetry/beacon.py::_OFF_VALUES`) so operators don't
+ # have to remember a different vocabulary per flag.
+ return val not in ("disabled", "off", "false", "0", "no")
+
+
+def resolve_policy(auth_mode: AuthMode | None) -> CompressionPolicy:
+ """Resolve the effective ``CompressionPolicy`` for a request.
+
+ - If the enforcement flag is off, returns PAYG-equivalent
+ regardless of the classified auth mode.
+ - If the enforcement flag is on and ``auth_mode`` is ``None``,
+ returns PAYG-equivalent (defensive default for the unclassified
+ / batch-row path).
+ - Otherwise returns the per-mode policy.
+
+ This is the single public entry point handlers should call when
+ deriving the policy from a request's classification result.
+ """
+ if auth_mode is None or not is_enforcement_enabled():
+ return policy_default_payg()
+ return policy_for_mode(auth_mode)