fix(proxy): add --no-ccr-response-handling flag to bypass response buffering (#3082) (#3100)

## Description

`ccr_handle_responses` (`headroom/proxy/models.py`) gates whether the
proxy buffers a streaming response server-side to run CCR
retrieval-marker handling on it
(`headroom/proxy/buffered_ccr_response.py`). It had no CLI or
environment-variable wiring at all, and `--no-ccr`/`HEADROOM_NO_CCR`
only ever toggled `ccr_inject_tool`/`ccr_inject_marker` (see the comment
above that call site in `headroom/cli/proxy.py`). Any client that offers
the `headroom_retrieve` tool itself — e.g. the bundled OpenCode plugin —
unconditionally takes the buffered-stream path with no supported
opt-out, which is the root cause of #3082 and the underlying issue
behind the buffered-CCR bug family the team has been patching (#3091,
#3092, #3094 landed in the ~24h before this PR).

This PR adds `--no-ccr-response-handling` /
`HEADROOM_NO_CCR_RESPONSE_HANDLING`, wired independently of `--no-ccr`,
so operators get an actual kill switch instead of another point patch on
the next incident in this family.

Closes #3082

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/cli/proxy.py`: new `--no-ccr-response-handling` /
`HEADROOM_NO_CCR_RESPONSE_HANDLING` click option, and
`ccr_handle_responses=not no_ccr_response_handling` wired into the
`ProxyConfig(...)` construction, right next to the other `ccr_*` fields.
- `tests/test_cli_proxy_env.py`: new `TestCLINoCcrResponseHandlingFlag`
class (4 tests) — default stays `True`, the flag sets `False`, the env
var sets `False`, and it composes correctly alongside `--no-ccr` without
either implying the other.

## Testing

- [ ] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Linting passes (`ruff format --check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ ruff check .
All checks passed!

$ ruff format --check .
1510 files already formatted
```

`pytest tests/test_cli_proxy_env.py` could not be run in my dev
environment — see "Not tested" below — but see "Real Behavior Proof" for
an equivalent-coverage manual run of the actual changed code path.

## Real Behavior Proof

- Environment: Windows dev machine, no MSVC Build Tools installed (no
admin rights available to install them), so `headroom._core` (the
maturin/PyO3 Rust extension) could not be built. `headroom.proxy.server`
transitively imports `headroom._core` via
`headroom.transforms.content_router` → `error_detection`, so **every**
test in `tests/test_cli_proxy_env.py` that does
`patch("headroom.proxy.server.run_server", ...)` — not just the 4 I
added — fails in this environment with `AttributeError: module
'headroom.proxy' has no attribute 'server'`. Confirmed this is
pre-existing/environmental and not caused by this change (66
pre-existing tests in the same file fail identically on an unmodified
checkout).
- Exact command / steps: Since the real `headroom.proxy.server` module
can't load here, I stubbed `sys.modules["headroom.proxy.server"]` with
the real `headroom.proxy.models.ProxyConfig` plus no-op fakes for
`_parse_csv_tools` / `_parse_exclude_tools` / `_parse_tool_profiles` /
`run_server` / `_get_code_aware_banner_status` (the only other names
`headroom/cli/proxy.py`'s `proxy` command lazily imports from that
module), then drove the real, unmodified `proxy` click command through
`CliRunner.invoke(main, ["proxy", ...])`, exactly like the existing test
suite does — same code path, same assertions, just without needing the
native build.
- Observed result: `--no-ccr-response-handling` and
`HEADROOM_NO_CCR_RESPONSE_HANDLING=1` both produce a `ProxyConfig` with
`ccr_handle_responses=False` while leaving
`ccr_inject_tool`/`ccr_inject_marker` at their defaults; passing neither
leaves `ccr_handle_responses=True`; combining `--no-ccr` with
`--no-ccr-response-handling` sets all three fields `False`; `--no-ccr`
alone does **not** set `ccr_handle_responses=False` (confirms the two
switches are independent, as intended). Also confirmed `--help` lists
the new flag with `HEADROOM_NO_CCR_RESPONSE_HANDLING` documented.
- Not tested: The actual buffered-response code path in
`headroom/proxy/buffered_ccr_response.py` / `server.py` that reads
`config.ccr_handle_responses` at runtime — I could not build
`headroom._core` to exercise the real proxy server end-to-end. This PR
only changes how the flag is populated (CLI/env → `ProxyConfig`); the
field itself and its runtime consumer (`server.py:1214`,
`server.py:1883`) are unchanged.

## Runtime Rollout Safety

- Rollout-managed feature(s): None — this is a CLI/env flag, not a
rollout-gated feature.
- Minimum rollout channel: N/A
- Stable/default behavior changed: No. `ccr_handle_responses` defaults
to `True` exactly as before; the new flag is opt-in and off by default.
- Kill switch / disable path: This PR *is* the kill switch —
`--no-ccr-response-handling` / `HEADROOM_NO_CCR_RESPONSE_HANDLING=1`
fully disables the buffered-response path.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert the two touched files; no state/schema/config
migration involved.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- "Unit tests pass locally" and "type checking passes" are unchecked
because I could not build the Rust extension in this environment (see
Real Behavior Proof) or run `mypy` locally; CI builds the extension and
should be the authoritative signal for both. Happy to address any
failures CI surfaces.
- No docs currently enumerate `--no-ccr*` flags individually (e.g.
README doesn't list `--no-ccr-proactive-expansion` either), so I didn't
add a doc section for symmetry with the existing flags — let me know if
you'd like one added.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3100"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `85c4a0a2c2501285d49c7d80034beebfddabbca7`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Re-reviewed latest integration head 3fd2cd018 and current author
response. Clean integration with upstream/main
2d3ee51846. The narrow response-handling
opt-out combines with global no-CCR using not(no_ccr or
no_ccr_response_handling), preserving the global-disable invariant while
leaving unrelated CCR knobs enabled for the narrow flag alone. CLI and
environment wiring plus default/narrow/global combination regressions
were reviewed; no new PR-specific source blocker found in scope.

All 173 CLI-proxy-environment/release/version/MCP tests pass; Ruff
check/format and whitespace pass. Earlier repository dependency failures
are not contributor-code blockers. Maintainers handle fresh exact-head
qualification; no contributor CI run requested. Existing native
extension supported local startup, not a fresh native build. No
contributor response-handling logic rewritten; nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `e0f941fce18eab0992c074418fb15c8bee7971eb`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.

Exact-head CI run42113164357/shard3 found one drift-guard failure:
HEADROOM_NO_CCR_RESPONSE_HANDLING had no settings registry entry. Added
its matching advanced boolean SettingField, default false, without
changing CLI/runtime flag behavior or weakening the registry guard.
All135 settings-store/CLI-proxy tests pass; Ruff check/format and
whitespace pass. Production routing/compression inputs remain unchanged
from previously reviewed85c4a0a2c and its173 local passes.
Main2d3ee51846435ef5b320eea4806af14e602b0d8c remains included. Approval
awaits fresh exact-head hosted qualification. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Signed-off-by: glatinone <93207632+glatinone@users.noreply.github.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kiell Tampubolon
2026-11-05 21:08:32 -06:00
committed by GitHub
co-authored by JD Davis Claude Opus 5.5
parent 910588e6b1
commit ce14271ba8
3 changed files with 107 additions and 1 deletions
+14 -1
View File
@@ -548,6 +548,18 @@ def dashboard(port: int, no_open: bool) -> None:
"Env: HEADROOM_NO_CCR_PROACTIVE_EXPANSION."
),
)
@click.option(
"--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,
+10
View File
@@ -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",
+83
View File
@@ -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)."""