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): add --no-ccr-response-handling flag to bypass response buffering (#3082) (#3100)

Kiell Tampubolonce14271ba8ca
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index a18f6101d..6cedd7997 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -548,6 +548,18 @@ def dashboard(port: int, no_open: bool) -> None:
"Env: HEADROOM_NO_CCR_PROACTIVE_EXPANSION."
),
)
+ "--no-ccr-response-handling",
+ is_flag=True,
+ envvar="HEADROOM_NO_CCR_RESPONSE_HANDLING",
+ help=(
+ "Disable server-side buffering of streaming responses for CCR response "
+ "handling, independent of --no-ccr. A client that offers the "
+ "headroom_retrieve tool itself (e.g. the bundled OpenCode plugin) "
+ "otherwise always takes the buffered-stream path with no opt-out "
+ "(issue #3082). Env: HEADROOM_NO_CCR_RESPONSE_HANDLING."
+ ),
+)
@click.option(
"--proxy-extension",
"proxy_extension",
@@ -1191,6 +1203,7 @@ def proxy(
ccr_inline_resolve: bool,
ccr_buffered_chat_streaming: bool,
no_ccr_proactive_expansion: bool,
+ no_ccr_response_handling: bool,
proxy_extension: tuple[str, ...],
compressor: tuple[str, ...],
no_subscription_tracking: bool,
@@ -1528,7 +1541,7 @@ def proxy(
# for exactly the clients told to use it (#3082).
ccr_inject_tool=not no_ccr,
ccr_inject_marker=not no_ccr,
- ccr_handle_responses=not no_ccr,
+ ccr_handle_responses=not (no_ccr or no_ccr_response_handling),
ccr_resolve_markers_inline=ccr_inline_resolve,
ccr_buffered_chat_streaming=ccr_buffered_chat_streaming,
lossless=lossless,
diff --git a/headroom/settings_store.py b/headroom/settings_store.py
index 014740f4b..784e4fdcb 100644
--- a/headroom/settings_store.py
+++ b/headroom/settings_store.py
@@ -150,6 +150,16 @@ SETTINGS: tuple[SettingField, ...] = (
help="Disable CCR entirely (no markers, no injected retrieve tool).",
tier="basic",
),
+ SettingField(
+ "HEADROOM_NO_CCR_RESPONSE_HANDLING",
+ "no_ccr_response_handling",
+ "Disable CCR response handling",
+ "Compression",
+ "bool",
+ default=False,
+ help="Disable CCR response buffering while preserving retrieval tool and marker settings.",
+ tier="advanced",
+ ),
SettingField(
"HEADROOM_CCR_INLINE_RESOLVE",
"ccr_inline_resolve",
diff --git a/tests/test_cli_proxy_env.py b/tests/test_cli_proxy_env.py
index 33724d992..6887b5bed 100644
--- a/tests/test_cli_proxy_env.py
+++ b/tests/test_cli_proxy_env.py
@@ -1175,6 +1175,89 @@ class TestCLICompressionOnlyFlags:
assert cfg.ccr_inject_tool is False
+class TestCLINoCcrResponseHandlingFlag:
+ """--no-ccr-response-handling / HEADROOM_NO_CCR_RESPONSE_HANDLING must flip
+ ccr_handle_responses, independent of --no-ccr (issue #3082).
+
+ Before this flag existed, ccr_handle_responses had no CLI/env wiring at
+ all — a client that offers the headroom_retrieve tool itself (e.g. the
+ bundled OpenCode plugin) always took the buffered-stream path with no
+ supported opt-out, even with --no-ccr set.
+ """
+
+ def test_ccr_handle_responses_defaults_on(self, runner):
+ """Without the flag, ccr_handle_responses stays enabled (no behavior change)."""
+ 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"], catch_exceptions=False)
+
+ assert result.exit_code == 0, result.output
+ assert captured_config["config"].ccr_handle_responses is True
+
+ def test_no_ccr_response_handling_flag(self, runner):
+ """--no-ccr-response-handling disables ccr_handle_responses only."""
+ 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", "--no-ccr-response-handling"], catch_exceptions=False
+ )
+
+ assert result.exit_code == 0, result.output
+ cfg = captured_config["config"]
+ assert cfg.ccr_handle_responses is False
+ # Unrelated CCR knobs stay on: this flag is independent of --no-ccr.
+ assert cfg.ccr_inject_tool is True
+ assert cfg.ccr_inject_marker is True
+
+ def test_no_ccr_response_handling_from_env(self, runner):
+ """HEADROOM_NO_CCR_RESPONSE_HANDLING env var disables ccr_handle_responses."""
+ 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={"HEADROOM_NO_CCR_RESPONSE_HANDLING": "1"},
+ catch_exceptions=False,
+ )
+
+ assert result.exit_code == 0, result.output
+ assert captured_config["config"].ccr_handle_responses is False
+
+ def test_no_ccr_response_handling_combines_with_no_ccr(self, runner):
+ """--no-ccr-response-handling composes with --no-ccr instead of being
+ implied by it: both can be set together for a fully unbuffered,
+ no-retrieval-path configuration."""
+ 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", "--no-ccr", "--no-ccr-response-handling"],
+ catch_exceptions=False,
+ )
+
+ assert result.exit_code == 0, result.output
+ cfg = captured_config["config"]
+ assert cfg.ccr_inject_tool is False
+ assert cfg.ccr_inject_marker is False
+ assert cfg.ccr_handle_responses is False
+
+
class TestNoCcrMarkerCompressors:
"""Verify --no-ccr actually suppresses <<ccr:...>> markers
from every compressor, not just SmartCrusher (#1022)."""