## Description
Requests whose path doesn't match a built-in API route fall through to
`handle_passthrough`, which forwarded the body verbatim — bypassing
ContentRouter/Kompress/TOIN entirely. Wrapper-proxy setups that front
Headroom on custom paths (e.g. `/api/codex-proxy/<key>/v1/responses`)
got zero compression on coding-agent traffic and hit context-limit 400s
in long sessions. This adds an opt-in flag that routes OpenAI
Responses-shaped passthrough bodies through the same compression path
the native `/v1/responses` handler uses.
Closes#1546
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] 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
- Added `ProxyConfig.compress_passthrough` (default `False`) +
`--compress-passthrough` CLI flag + `HEADROOM_COMPRESS_PASSTHROUGH=1`
env.
- `handle_passthrough`: when enabled, POST requests whose path ends in
`/responses` with an OpenAI Responses-shaped body are compressed via the
existing `_compress_openai_responses_payload_in_executor` before
forwarding; stale `Content-Length` is dropped so httpx recomputes it.
- New `_maybe_compress_passthrough_responses` helper — fail-open:
non-JSON, non-Responses payloads, unmodified results, and any compressor
error forward the original body unchanged.
- Documented the flag in `docs/content/docs/proxy.mdx`.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ .venv/bin/python -m pytest tests/test_compress_passthrough.py -q
collected 6 items
tests/test_compress_passthrough.py ...... [100%]
============================== 6 passed in 0.35s ===============================
$ .venv/bin/ruff check headroom/proxy/handlers/openai.py headroom/proxy/models.py headroom/proxy/server.py tests/test_compress_passthrough.py
All checks passed!
```
## Real Behavior Proof
- Environment: macOS arm64, Python 3.14, repo `.venv`.
- Exact command / steps: `.venv/bin/python -m pytest
tests/test_compress_passthrough.py -q` — covers a Responses-shaped body
being compressed, non-JSON passthrough, non-Responses (`messages`)
payload untouched, unmodified-result short-circuit, compressor-error
fail-open, and `ProxyConfig().compress_passthrough is False` default.
Plus import smoke: `ProxyConfig(compress_passthrough=True)`,
server/handler modules import, helper present.
- Observed result: 6 passed; flag defaults off; enabled path reuses the
native Responses compressor and never raises out to the request.
- Not tested: live end-to-end through a real second proxy to a real
upstream (no external wrapper proxy / upstream credentials in sandbox);
the compression call is the same one `/v1/responses` already exercises
in CI.
## 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
- [x] 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
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Additional Notes
Scoped to OpenAI Responses-shaped bodies (the reporter's exact case).
Anthropic `/messages` and OpenAI `/chat/completions` passthrough
compression are natural follow-ups — deliberately left out to keep this
change focused and fail-safe. CHANGELOG is release-managed, left
unchecked.
