mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
feat/https-compose-caddy
38
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
6b41b6e451 |
feat(proxy): add cli and settings knob for ccr_inject_system_instructions (#4642)
<!-- maintainer-current-main --> ## Maintainer latest-main checkpoint Published `d13ba17dff65a5b31253ef3cf0775ffc2504d8da` contains current upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 150 CLI/settings/Gemini tests passed. Earlier live behavior proofs below retain their commit/platform scope; contributor runtime logic is unchanged. The common shard-2 failure was independently confirmed on main's hosted job 127069149772 and locally (four failures, six passes): the Gemini memory fixture mocked an unused body reader and provided no request stream. The maintainer test-only follow-up now constructs a real FastAPI/ASGI Request carrying JSON bytes and exercises the actual body reader. All six test-function ASTs/assertions are unchanged, and all 10 parameterized Gemini cases pass. Touched-file Ruff/format and whitespace checks pass. This fixes the inherited fixture instead of asking contributors to run CI or weakening the memory/content assertions. Fresh exact-head hosted qualification is requested. Nothing merged. <!-- /maintainer-current-main --> ## Description Closes #4636. `ccr_inject_system_instructions` (which instructs models how to retrieve compressed context when CCR markers are present) previously existed as a field on `ProxyConfig` but could only be toggled programmatically via the Python API. Operators deploying `headroom proxy` as a container or standalone service had no CLI flag, environment variable, or settings store entry to enable it without wrapping the process in custom Python code. This PR exposes `ccr_inject_system_instructions` as: 1. CLI flag: `--ccr-inject-system-instructions` 2. Environment variable: `HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS` 3. Curated settings store field: `ccr_inject_system_instructions` in `settings_store.SETTINGS` 4. Server environment configuration: loaded in `_proxy_config_from_env()` The default remains `False` preserving exact existing behavior. ## Type of Change - [x] New feature (non-breaking change that adds functionality) ## Changes Made - `headroom/cli/proxy.py`: Add `@click.option("--ccr-inject-system-instructions", is_flag=True, envvar="HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS", ...)`, add parameter to `proxy()`, and thread it into `ProxyConfig`. - `headroom/settings_store.py`: Add `SettingField("HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS", "ccr_inject_system_instructions", ...)` to `SETTINGS` registry so it is validated, saved to `settings.json`, and surfaced on `/settings`. - `headroom/proxy/server.py`: Read `HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS` in `_proxy_config_from_env()` for multi-worker and container deployments. - `docs/content/docs/proxy.mdx`: Document `--ccr-inject-system-instructions` and `HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS` in the CCR configuration table. - `tests/test_cli_proxy_env.py`: Add test cases verifying `--ccr-inject-system-instructions`, `HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS`, `settings.json`, and `_proxy_config_from_env()` correctly populate `ProxyConfig.ccr_inject_system_instructions`. ## Testing - [x] Unit tests pass (`pytest tests/test_proxy/test_settings_store.py tests/test_cli_proxy_env.py`) - [x] Linting passes (`ruff check`) - [x] Formatting passes (`ruff format --check`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest tests/test_proxy/test_settings_store.py -q 40 passed, 1 warning in 2.18s $ pytest tests/test_cli_proxy_env.py -k "test_ccr_inject_system_instructions or test_settings_file_reaches_ccr_inject_system_instructions or test_proxy_config_from_env_reads_ccr_inject_system_instructions" -q 5 passed, 91 deselected in 3.42s $ ruff check headroom/cli/proxy.py headroom/settings_store.py headroom/proxy/server.py tests/test_cli_proxy_env.py All checks passed! $ ruff format --check headroom/cli/proxy.py headroom/settings_store.py headroom/proxy/server.py tests/test_cli_proxy_env.py 4 files already formatted ``` ## Real Behavior Proof - Environment: Windows 11 x86_64, Python 3.14.5, Click CliRunner test harness and settings store test harness. - Exact command / steps: Executed `runner.invoke(main, ["proxy", "--ccr-inject-system-instructions"])`, verified captured ProxyConfig; tested env var `HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS=1`, verified ProxyConfig; tested `settings.json` with `{"ccr_inject_system_instructions": true}`, verified ProxyConfig; tested `_proxy_config_from_env()`. - Observed result: In all test cases, ProxyConfig.ccr_inject_system_instructions resolved to True when enabled and False by default, matching the behavior of sibling knobs like HEADROOM_CCR_INLINE_RESOLVE and HEADROOM_CCR_BUFFERED_CHAT_STREAMING. - Not tested: Live Kubernetes deployment or multi-node container cluster. ## Runtime Rollout Safety - Rollout-managed feature(s): none, opt-in configuration knob - Minimum rollout channel: n/a - Stable/default behavior changed: no, default remains False - Kill switch / disable path: omit the flag or unset HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS - Unsafe override required: no - Qualification impact: none while disabled - Rollback path: git revert this commit ## 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 - [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 Follows the exact pattern established by `--ccr-inline-resolve` and `--ccr-buffered-chat-streaming` (#4631). <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4642" 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 runtime and integration qualification Published `9c0b0a10d63227554350a3ba2cb936e09cea1286` includes upstream main `ee975d49c0b742e34b09df50a01c7b5680e85cdc` with a clean merge and no contributor logic changes. Main is actively advancing, so final qualification must check the then-current main again. Windows/Python 3.12.13: `python -m pytest tests/test_cli_proxy_env.py tests/test_proxy/test_settings_store.py -q` reports **140 passed** with the existing development native extension. Touched-file Ruff, format and whitespace checks pass; no fresh native build claimed. Real CLI proof (no replaced run_server or provider transport): launch the actual Click entry point `from headroom.cli import main; main()` in six isolated subprocesses with `proxy --mode token --no-optimize --no-cache --no-rate-limit --no-ccr-proactive-expansion --no-memory-tools --no-memory-context --disable-kompress --anthropic-api-url http://127.0.0.1:<fixture-port>`. Each process has an isolated workspace/settings file, offline/beacon opt-out and a real CompressionStore entry created before launch; GET `/v1/retrieve/{hash}` confirms ownership. Send `/v1/messages` with that stored hash in a historical tool-result marker, through the actual TCP proxy to a local HTTP Anthropic-shaped provider fixture, and inspect the received upstream JSON. Observed: all six calls return HTTP 200. Default: no `Compressed Context Available` instructions. CLI flag, environment `HEADROOM_CCR_INJECT_SYSTEM_INSTRUCTIONS=1`, and a settings file with `{"ccr_inject_system_instructions":true}` each produce the instructions upstream. `--no-ccr` and `--lossless`, both requested alongside the flag, produce neither instructions nor a retrieval tool despite the owned historical marker. This verifies the disabled-CCR finding is addressed on the real request path. The documented warm-prefix/cache-mode skip remains an intentional limitation; this run uses token mode. Not tested: live cloud models, Kubernetes/multiple nodes, every provider wire shape, warm-cache replay or a fresh native build. The local HTTP fixture is synthetic; request/configuration/ownership paths and TCP transport are real. Hosted CI must finish on the final head; nothing merged. ### Maintainer current-main requalification Exact head `b38e5a5937cf09c3b5127f3f066e0384db235955`, upstream main `ea59ac3eef3a3dc02076e9fe4bb30d572ca9c1a9`. Clean integration with upstream/main |
||
|
|
0ddaa56c21 |
fix(vertex): explain Vertex failures in-band, correct the model/region matrix (#2640)
## Description Vertex rejects onboarding requests for a handful of recurring reasons — expired ADC, a partner model never enabled in Model Garden, a model not served in the requested location, a missing optional SDK — and its own error text names none of the fixes. Users see a bare `404` or an opaque `500` through their SDK and cannot tell a proxy bug from a project-config gap. This makes the proxy explain those failures where it happens, adds a `[vertex]` extra so the LiteLLM Vertex backend can actually start, and corrects an example, a test matrix, and three documentation claims that could not have worked as written. Closes #2632 ## Type of Change - [x] 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made **Explain Vertex failures in-band** (`headroom/providers/vertex/diagnostics.py`, new) - On `401/403/404/429`, attach an actionable hint three ways: a WARNING in the proxy log, an `x-headroom-hint` response header, and a note appended to `error.message`. The last is load-bearing — SDKs raise with the message string and discard headers. - Successful responses are never modified; annotation is idempotent; statuses we cannot explain get no hint rather than a plausible-sounding wrong one. - Routes opt in via a one-line `@with_vertex_diagnostics` decorator reading path params FastAPI already injects (**+8 lines** in `proxy_routes.py`, no re-indentation). - Same treatment for backend setup failures, where `--backend vertex` surfaced LiteLLM's raw `No module named 'vertexai'` as an opaque 500. **Make `--backend vertex` able to start** (`pyproject.toml`, `registry.py`, `cli/proxy.py`) - New `[vertex]` extra carrying `google-cloud-aiplatform>=1.38`. Deliberately **not** folded into `[proxy]`: measured at ~175 MB installed, and the native passthrough routes never needed it. Follows the existing `proxy-prod` split. - Startup preflight keyed on the **resolved provider**, so every alias normalized at `registry.py:229` (`vertex`, `vertex_ai`, `litellm-vertex`, `google-vertex`, `googlevertex`) is covered. Skipped when a backend class is injected, so existing fake-based tests are unaffected. - New `BackendUnavailableError` so the CLI prints the remedy and exits `2` instead of dumping a traceback through startup internals. **Correct things that could not have worked** | | was | is | |---|---|---| | SDK client | `http_options={"api_endpoint": ...}` | `{"base_url": "http://..."}` — `api_endpoint` is not a field on `HttpOptions`; pydantic rejects it before any request is sent | | Thinking config | `ThinkingConfig(thinking_budget_tokens=)` | `thinking_budget=` | | Request payload | `contents: [{parts: [...]}]` | adds `role: "user"` — the `global` endpoint enforces it, regional was silently lenient | | Auth guidance | `gcloud auth print-access-token` | `application-default` — the plain user token gets `401 ACCESS_TOKEN_TYPE_UNSUPPORTED` | | Test matrix | model × location cross-product | explicit servable pairs | - Test matrix is now four pairs that can actually serve: `global`/`gemini-flash-latest`, `global`/`claude-sonnet-4-6`, `europe-west2`/`gemini-3.5-flash`, `us-east5`/`claude-sonnet-4-6`. Gemini 3.x has no US regional endpoint and `-latest` aliases are global-only, so a pinned `us-central1` Gemini case can never pass. No Gemini 2.5 — it retires 2026-10-16. - `test_thinking_levels` asserted only `status_code < 500` while sending an ignored `thinkingBudgetTokens` key: it passed on 400s and proved nothing. Now asserts 200 plus scored usage metadata with the correct `thinkingBudget` spelling. - Cases the caller's project genuinely cannot serve now **skip** with an actionable reason instead of reporting a red proxy. **Docs** (`proxy.mdx`, `installation.mdx`, `wiki/vertex.md`) - `proxy.mdx` claimed `publisher=anthropic` passthrough "routes through the same LiteLLM-Vertex path as `--backend vertex_ai`". It does not — without the flag it is a direct forward, which is why it works on a bare `[proxy]` install where the LiteLLM path cannot even import. - Documented the trap of combining `--backend vertex` with native Vertex URLs: LiteLLM takes project/region/model from its own config and ignores the URL. - `installation.mdx` and `wiki/vertex.md` said the SDK is "not included in any extra". - Cleared 15 pre-existing `ruff` findings in the two files this PR rewrites (4 remain in `plugins/headroom-oauth2`, untouched by this work). ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ mypy headroom Success: no issues found in 511 source files $ ruff check . Found 4 errors. # all in plugins/headroom-oauth2, pre-existing, untouched by this PR $ pytest tests/test_proxy_vertex_native_integration.py tests/test_vertex_diagnostics.py -q 44 passed, 1 warning in 69.86s # 8 live integration + 36 offline diagnostics, 0 skipped $ pytest tests/ -k "anthropic_messages or handler_anthropic or backend or registry or cli_proxy or vertex or proxy_routes" 853 passed, 49 skipped, 9345 deselected, 2 warnings in 28.41s ``` New tests in `tests/test_vertex_diagnostics.py` (36, no credentials required): status coverage, per-publisher remedy divergence, idempotency, `content-length` consistency after body rewrite, non-JSON and body-less/streaming responses, every backend alias preflighted, other providers unaffected, injected backend bypasses the preflight. ## Real Behavior Proof - Environment: macOS 14, Python 3.11.15, live GCP project (`alanblount-sandbox`) with `aiplatform.googleapis.com` enabled and Claude enabled in Model Garden; ADC via `gcloud auth application-default login` - Exact command / steps: `export GCP_PROJECT_ID=alanblount-sandbox && export GCP_ACCESS_TOKEN=$(gcloud auth application-default print-access-token) && uv run --extra proxy --with google-genai python3 examples/vertex_genai_sdk_demo.py && uv run --extra proxy --with pytest-asyncio pytest tests/test_proxy_vertex_native_integration.py tests/test_vertex_diagnostics.py -q && headroom proxy --backend vertex` (exits 2, then retried with `[proxy,vertex]` extra installed) - Observed result: demo printed `✓ Standard response received successfully! > 1, 2, 3, 4, 5` and `✓ Thinking response received successfully!`; 44 tests passed (8 live integration, 36 diagnostics), 0 skipped; `--backend vertex` exited 2 with the remedy message; same request with the extra installed returned 200; invalid region produced `[headroom] hint:` in the response body and `x-headroom-hint` header; success responses were byte-clean - Not tested: Windows; `us`/`eu` multi-region endpoints and Claude 4.7+ (project cannot serve them); Provisioned Throughput; Rust proxy path; `--backend vertex` dropping URL project/model on native Vertex routes (documented as known gap in Additional Notes) ## 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 - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A — proxy and CLI behavior; terminal output is quoted above. ## Additional Notes - `uv.lock` intentionally not included: the new extra is opt-in and does not change default resolution. - Error-body rewriting is confined to already-failing responses and wrapped so a diagnostic can never turn a clean upstream error into a proxy 500. - The preflight raises where the provider is resolved (`registry.py`) rather than at the CLI, so programmatic embedders get the same guarantee; the CLI only formats it. - Three test files fail to collect on this branch (`test_hermes_passthrough_compression`, `test_observability_metrics`, `test_observability_tracing`). They predate this work and are unrelated, so they were excluded rather than fixed — happy to open a separate issue. - `[vertex]` was chosen over adding the dependency to `[proxy]` after measuring the footprint at ~175 MB. If maintainers prefer it in `[proxy]`, that is a one-line change. ## Runtime Rollout Safety - Rollout-managed feature(s): none; diagnostics annotate already-failing Vertex responses and the backend dependency is opt-in through the vertex extra. - Minimum rollout channel: normal stable release after Vertex diagnostics, route, and backend-path tests pass. - Stable/default behavior changed: successful responses and native passthrough remain unchanged; supported Vertex failures gain an actionable header/message, and selecting the LiteLLM Vertex backend without its SDK now fails once at startup. - Kill switch / disable path: use native Vertex passthrough without the LiteLLM backend, or human-revert the diagnostic/preflight change. - Unsafe override required: none. - Qualification impact: offline diagnostics, native integration, and mocked LiteLLM Vertex request-shaping tests must remain green. - Rollback path: human-revert the PR; no persisted state or migration is involved. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2640" 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 `5d7071f348d2462f666fd7ac1ceb8ac18050169a`, upstream main `2d3ee51846435ef5b320eea4806af14e602b0d8c`. Re-reviewed latest integration head |
||
|
|
ce14271ba8 |
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 |
||
|
|
31dcaf41f7 |
feat(ccr): answer headroom_retrieve on streaming chat completions (#4631)
## Description Streaming `/v1/chat/completions` compresses tool output into retrieval markers but cannot answer `headroom_retrieve`, so the content is lost to the model on this path. Sessions that mix streaming and non-streaming turns also flip the tool in and out of `tools` and bust the prefix each way. Behind a new default-off flag, a streaming turn that carries a marker now runs as `stream: false` upstream through the same code as a non-streaming turn, then goes back as `chat.completion.chunk` frames. Builds on the groundwork in `feat/buffered-ccr-chat-streaming` and the #3816 continuation loop. Part of #3815. Flipping the default stays a separate decision, as the issue asks. ## 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 - `--ccr-buffered-chat-streaming` / `HEADROOM_CCR_BUFFERED_CHAT_STREAMING`, on the CLI too because `headroom proxy` builds its own config. - The non-streaming branch became `_direct_chat_turn()` at the same indent, so usage, the prefix tracker and savings are shared rather than copied. `git diff` shows almost no moved lines there. - Two gates. Eligibility is decided before injection and lets the tool stay resident. Buffering is decided at dispatch from the final body, so a turn with no marker keeps its real stream (the #3071 lesson). - `_buffered_chat_reply_as_sse` wraps the JSON reply: non-200 passes through with its status, a lone leftover retrieval fails closed with the continuation's status. A retrieval next to a client tool follows `handle_response`: a successful continuation replaces the turn, and only a failed one goes back to the client whole. - `stream_options` is dropped upstream since OpenAI answers 400 to it without a stream. The usage chunk follows the same rule as a plain stream. - Frames and the OpenAI continuation now carry other non-empty message fields, and frames keep opaque tool call fields, so `reasoning_content`, `reasoning_details` and Gemini thought signatures survive. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`): see Test Output, no errors in changed files - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest <every file touching the chat route, handle_response, ccr, buffered or settings_store> 3067 passed, 73 skipped $ ruff check . && ruff format --check . All checks passed! 1881 files already formatted $ mypy headroom 2 errors, both in files this PR does not touch (memory/adapters/embedders.py, integrations/langchain/chat_model.py) ``` The full suite did not finish locally (stopped at a time limit about 40% through, no failures to that point), so CI is the full run. `cargo` checks were not run since no Rust changed. `tests/test_openai_chat_buffered_ccr.py` covers the list in the issue: frames ending in `[DONE]`, `finish_reason: tool_calls`, status fidelity inside the grace window, heartbeat past it, identical accounting against a non-streaming turn, byte-stable tools across a mixed session, flag off stays on the plain stream. ## Real Behavior Proof - Environment: macOS 27 arm64, Python 3.13, real `headroom proxy --mode token` in front of a local stub upstream, real `openai` 2.41 SDK client with `stream=True`. No provider keys. - Exact command / steps: `headroom proxy --port 18932 --mode token --openai-api-url http://127.0.0.1:18931 [--ccr-buffered-chat-streaming]`, then one turn with a 1,500 line log as the tool result. It compresses to a `Retrieve more: hash=` marker. The stub calls `headroom_retrieve` when it is offered and a marker is present. - Observed result: flag off, the model only gets the summary. Flag on, the retrieval is answered inside the proxy and the SDK reads a normal stream with usage. ```text flag off upstream: stream=true tools=[list_rows] client: "I can only see a compressed summary." flag on upstream: stream=false tools=[list_rows, headroom_retrieve] reply=tool_call upstream: (continuation) reply=text log: CCR: buffering streaming chat turn (stream:false upstream, resynthesized as chat.completion.chunk) CCR: retrieval tool call on the direct chat path, resolving before replying client: 4 chunks, "Row row-0007 is in the original output.", finish_reason=stop, usage present ``` - Not tested: a real provider, Copilot, xAI, or a gateway with its own strict validation. Windows. ## Runtime Rollout Safety - Rollout-managed feature(s): none, plain opt-in flag - Minimum rollout channel: n/a - Stable/default behavior changed: no - Kill switch / disable path: flag is off by default - Unsafe override required: no - Qualification impact: none while off - Rollback path: unset the flag ## 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 - [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 - Memory tools still only go in on non-streaming turns, so with memory on a mixed session keeps that part of the toggle. A turn with no marker cannot run the memory loop, so I left it. - Turn hooks treat a buffered turn like a stream: stream-safe `on_request` only, no `on_response`. Buffering is decided after hooks run, so anything else would split a hook's two halves. - The issue mentions a ChatGPT-auth exclusion. The chat handler has no such routing, so there was nothing to exclude. - Past the grace window `x-headroom-*` headers are lost, same as the shared wrapper on the other paths. - #3600 picks a marker-free pipeline for streaming chat. If it lands, an eligible turn needs to keep the marker pipeline. --------- Co-authored-by: Tejas Chopra <chopratejas@gmail.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
affd17c5fd |
fix(cli): document that code-aware compression is enabled by default (#4616)
## Description
`headroom proxy --help` says code-aware (AST) compression is off by
default, but the proxy turns it on when no flag is passed. With no
`--code-aware`/`--no-code-aware` flag and `HEADROOM_CODE_AWARE_ENABLED`
unset, `headroom/cli/proxy.py` resolves
`os.environ.get("HEADROOM_CODE_AWARE_ENABLED", "1")` to enabled. That
default came in on purpose with the coding-profile posture (#1893).
`test_code_aware_enabled_defaults_true`, the argparse server path
(`_get_env_bool(..., True)`) and the code-compression docs all treat it
as on. So the behavior is correct and the help text is wrong. The wrong
text matters because it makes `--code-aware` look like the only way to
turn AST compression on, so users don't notice it is already rewriting
code until they read the startup banner.
`headroom install apply --help` repeats the same claim ("Default:
disabled, matching `headroom proxy`"). When the flag is omitted, the
planner adds no argument, so the persistent runtime gets the proxy
default, which is enabled.
This PR changes only the descriptions. The runtime default stays as it
is.
Closes #4604
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- `headroom/cli/proxy.py`: the `--code-aware/--no-code-aware` help now
reads `Default: enabled. Disable with --no-code-aware or
HEADROOM_CODE_AWARE_ENABLED=0.` The resolution comment said both
"default off" and "Default ON"; it now gives step 3 as default ON.
- `headroom/cli/install.py`: the `install apply
--code-aware/--no-code-aware` help now reads `Default: enabled, matching
headroom proxy`.
- `tests/test_cli_proxy_env.py`: new parametrized regression test that
checks the `--code-aware` option help on `proxy` and `install apply`
documents the enabled default. Both cases fail on `main` and pass with
this change.
- Out of scope: `docs/content/docs/proxy.mdx` has the same stale
"disabled"/"off" wording in two table rows. I left it out to keep this
PR to the CLI help and can follow up separately.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
Lint and type checks ran on the changed files only. Commands are below.
### Test Output
```text
$ .venv/bin/python -m pytest tests/test_cli_proxy_env.py -q -p no:cacheprovider -o addopts=
87 passed, 1 skipped in 11.89s
# same new test against the unmodified headroom/ sources
$ .venv/bin/python -m pytest tests/test_cli_proxy_env.py -q -p no:cacheprovider -o addopts= -k help_documents
FAILED tests/test_cli_proxy_env.py::TestCLIProxyEnvVars::test_code_aware_help_documents_enabled_default[path0]
FAILED tests/test_cli_proxy_env.py::TestCLIProxyEnvVars::test_code_aware_help_documents_enabled_default[path1]
2 failed, 86 deselected in 0.76s
$ .venv/bin/ruff check headroom/cli/proxy.py headroom/cli/install.py tests/test_cli_proxy_env.py
All checks passed!
$ .venv/bin/ruff format --check headroom/cli/proxy.py headroom/cli/install.py tests/test_cli_proxy_env.py
3 files already formatted
$ .venv/bin/mypy headroom/cli/proxy.py headroom/cli/install.py --ignore-missing-imports
Success: no issues found in 2 source files
```
## Real Behavior Proof
- Environment: Ubuntu 26.04 x86_64, Python 3.12, offline, no provider
- Exact command / steps: `headroom proxy --help | grep -A4 --
--code-aware` and `headroom install apply --help | grep -A4 --
--code-aware`, run once on unmodified `main` and once with this change.
On both trees I also resolved the default with
`HEADROOM_CODE_AWARE_ENABLED` unset: `env -u HEADROOM_CODE_AWARE_ENABLED
python -c ...` invokes `headroom proxy` through Click's `CliRunner` with
`run_server` and the proxy-extras check patched out, then prints
`config.code_aware_enabled`.
- Observed result: Before, on `main`:
```text
--code-aware / --no-code-aware Enable/disable AST-based code
compression.
Requires the optional tree-sitter
dependency: pip install headroom-ai[code].
Default: disabled. Env:
HEADROOM_CODE_AWARE_ENABLED=1 to enable.
--code-aware / --no-code-aware Enable/disable AST-based code compression
in
the persistent runtime. Requires the
optional tree-sitter dependency: pip install
headroom-ai[code]. Default: disabled,
matching `headroom proxy`.
exit 0 code_aware_enabled = True
```
After, with this change:
```text
--code-aware / --no-code-aware Enable/disable AST-based code
compression.
Requires the optional tree-sitter
dependency: pip install headroom-ai[code].
Default: enabled. Disable with --no-code-
aware or HEADROOM_CODE_AWARE_ENABLED=0.
--code-aware / --no-code-aware Enable/disable AST-based code compression
in
the persistent runtime. Requires the
optional tree-sitter dependency: pip install
headroom-ai[code]. Default: enabled,
matching `headroom proxy`.
exit 0 code_aware_enabled = True
```
The resolved default is `True` on both trees. Only the help text
changed, and it now matches the behavior.
- Not tested: starting a real `headroom proxy` and reading its
`Code-Aware:` startup banner, because this environment lacks the full
`[proxy]` extra (`mcp`). Also not tested: live provider traffic and an
actual `headroom install apply` deployment.
## Runtime Rollout Safety
- Rollout-managed feature(s): none; this changes help text and a code
comment only
- Minimum rollout channel: none needed; no runtime code path changes
- Stable/default behavior changed: no; code-aware still defaults to
enabled, exactly as before
- Kill switch / disable path: unchanged; `--no-code-aware` or
`HEADROOM_CODE_AWARE_ENABLED=0`
- Unsafe override required: no
- Qualification impact: none; no compression, routing or config
resolution logic touched
- Rollback path: revert this commit
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4616"
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 -->
|
||
|
|
f3d240bcae |
fix(cli): say why the proxy failed to start (#4120)
## Description Fixes two proxy startup failures that hid their cause from the user. **1. `headroom proxy` on a port that is already in use.** It printed the full banner, ending in "Press Ctrl+C to stop.", and then about 10 INFO lines. The one line that mattered, uvicorn's `[Errno 48] ... address already in use`, came next. After it came `event=proxy_shutdown reason=signal` and a 10-line zero-valued session summary. The command now checks the port before printing the banner and exits with one clear line: ``` Error: Port 54351 on 127.0.0.1 is already in use by another process (Address already in use). Start this proxy on another port with --port N (env: HEADROOM_PORT). ``` When a Headroom proxy is the process holding the port, the message says so instead. The check asks the address that is actually busy (IPv6 included), so a Headroom proxy on 127.0.0.1:P is never reported as the owner of [::1]:P. When that address cannot be probed (a scoped IPv6 address, an unresolvable name), the message is the generic `already in use (<reason>)`. **2. `headroom wrap <tool>` when the proxy it starts dies during startup.** The error quoted the last 500 characters of the proxy stdio log. That was the wrong part of the log, for two reasons: - The proxy logs its shutdown summary after the error, so the tail was the summary box. - The log is appended to across runs, so the tail could come from an older run. The error also never said where the log was. It now reads only this run's output, at most its first 64 KiB and, when the head has no error, its last 64 KiB (so a runaway log is never read whole, and an error after a long burst of startup output is still found), quotes from the first `ERROR` / `CRITICAL` / `Traceback` line or line-leading Click `Error: ` (otherwise the end of the first non-blank window, so neither a blank head nor a blank tail hides useful startup text), and adds `Full log: <path>`. The timeout error now names the log too. Refs #4136 ## 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 `_tcp_port_in_use` / `_refuse_busy_port`. They run after the bind-policy check and before the banner, and are skipped for `--uds`. The probe mirrors uvicorn's own bind, so it never refuses a bind that uvicorn would accept: - It sets `SO_REUSEADDR`, as both uvicorn paths do. A port in TIME_WAIT after a restart is therefore not reported as busy. - With one worker, it binds every address the host resolves to, with `IPV6_V6ONLY`, the same way asyncio `create_server` does. - With `--workers > 1`, it binds one AF_INET or AF_INET6 socket, as uvicorn's `Config.bind_socket` does. - On Windows, and for any error other than EADDRINUSE, it does nothing and leaves the case to uvicorn, exactly as today. - It returns the busy address. `_probe_host_for` maps it to the address to ask: wildcards go to loopback of the same family (`0.0.0.0` to `127.0.0.1`, `::` to `::1`), a hostname is resolved for IPv4, and a scoped IPv6 address returns None (generic message). - `headroom/cli/port_discovery.py`: `probe_headroom_proxy` takes an optional keyword `host` (default `127.0.0.1`, so existing callers are unchanged) and brackets IPv6 in the URL. - `headroom/cli/wrap.py`: - `_start_proxy` records the stdio log size before spawning the proxy. - New `_proxy_startup_failure_excerpt` picks the error line from this run's output, reading at most the first and last 64 KiB written after the recorded offset. - Both startup errors now end with `Full log: <path>`. - `tests/conftest.py` + `pyproject.toml`: an autouse guard, and its `proxy_port_preflight` marker, turn the new check off unless a test opts in. It follows the existing `proxy_dependency_gate` pattern. - Without it, the 16 test files that invoke `headroom proxy` with a stubbed `run_server` on the default port 8787 would fail whenever a developer has their own proxy running. - Tests: - New `tests/test_cli/test_proxy_port_preflight.py`, which uses real sockets: - busy port with workers 1 and 2; - port held by a Headroom proxy; - free port still starts; - `test_ipv6_conflict_is_identified_on_the_requested_host`: a real fake-Headroom `/livez` on 127.0.0.1:P and a plain listener on [::1]:P; `--host ::1` must say "another process"; - `test_unprobeable_host_gets_the_generic_message`. - New `test_startup_excerpt_reads_at_most_64_kib_of_this_run`. - New `test_start_proxy_exit_quotes_this_runs_error_not_summary_or_old_runs`. - The timeout test now also asserts the log path. - The existing stdio-tail test now writes its log output from the fake `Popen`, as the real child process does. - The new tests fail on the old code (3 preflight tests; the excerpt and timeout tests) and pass now. The three tests added for the review (IPv6 owner, unprobeable host, 64 KiB bound) fail on the PR's previous commit |
||
|
|
ee731d7ea8 |
fix(proxy): refuse token-less non-loopback binds, gate operator routes (#3852)
## Why Four related gaps in the proxy's network gate (findings 01-F1, 01-F2, 01-F5, 01-F9): - **Open bind.** A non-loopback bind with no `HEADROOM_PROXY_TOKEN` only logged a warning, then served the `/v1/*` relay, with the operator's upstream credentials, to every peer that could reach the port. - **Missing peer address.** `is_loopback_host(None)` returned `True`. A Unix-domain socket, an ASGI adapter that leaves `scope["client"]` unset, or a hand-built request therefore turned off the token gate, the `/admin` and `/debug` guards and the WebSocket gate. - **Operator data routes.** `/stats-history` (including CSV export), `/quota`, `/subscription-window` and `/metrics` were served to any network caller. - **WebSocket loopback exemption** checked only the peer IP, not the `Host` header, so it had no DNS-rebinding defence. ## What changes - New `headroom/proxy/bind_policy.py`. A non-loopback bind (`0.0.0.0`, `::`, a LAN address or a hostname) with no token is refused at three places: `create_app` (embedders and the multi-worker factory), `run_server` (one exit with code 2 before uvicorn forks) and the `headroom proxy` CLI (a clear error before the banner, exit code 1). An absent host means uvicorn's default `127.0.0.1`. - `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` acknowledges an open bind when the runtime already restricts reachability, such as a container published on `127.0.0.1`. The `proxy_open_bind` warning is still logged on that path, and the banner says the bind is open. - `is_loopback_host(None)` now returns `False` (fail closed), matching `identity.py`. - `/stats-history`, `/quota` and `/subscription-window` answer only: a non-loopback caller that passed the token gate, a loopback caller (peer and `Host` header both loopback), a trusted dashboard client, or, under an acknowledged token-less bind, the container's own default-gateway TCP peer with a loopback `Host` (the host browser reaching a `127.0.0.1`-published container). Everyone else gets 404, as with `/admin`. Settings writes keep their stricter rule with no token short-cut. - `/metrics` answers a non-loopback caller that passed the token gate, a loopback caller, a connecting peer in `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` (whatever it forwards), or a resolved client in the dashboard CIDRs. For CIDR peers a hostname `Host` is fine, so Prometheus scrapers work; a cross-origin browser request is still refused. - The token short-cut applies only to non-loopback requests. The gate exempts loopback peers without checking `Host`, so a loopback request has not proven it holds the token and must pass the loopback `Host` check. This blocks a DNS-rebound browser on the operator's machine. - The `/dashboard` shell stays ungated. It is a static template, like the already public `/dashboard/static` assets. Gating it would break the dashboard for containers published on host loopback, where the peer is the bridge gateway and `Host` is `localhost`. The data routes behind it are gated. - The WebSocket loopback exemption requires a loopback peer and a loopback `Host` header. A loopback peer with a foreign `Host` can still connect with the token. - Launchers that always publish on `127.0.0.1` set the acknowledgement themselves: `headroom install` (docker preset), `scripts/install.sh` and `scripts/install.ps1` (through one helper that adds the acknowledgement only together with the `127.0.0.1` publication), and `docker/docker-compose.native.yml`. - Docs: `proxy.mdx` documents the new variable and which routes the token also gates; `docker-install` (docs and wiki) and the `docker-compose.yml` comment show the acknowledgement in the loopback-published example. `e2e/docker-bind-security.sh` sets it and checks that the same launch without it refuses to start. ## Behaviour change (breaking) - `headroom proxy --host 0.0.0.0`, or `HEADROOM_HOST` set to any non-loopback address, without `HEADROOM_PROXY_TOKEN` now refuses to start. The error names both remedies. Set a token, bind loopback, or set `HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1` when the port is already confined. Anyone running the image by hand with `--host 0.0.0.0` and no token must add one of these. - Without a token, `/stats-history`, `/quota`, `/subscription-window` and `/metrics` return 404 to non-loopback callers outside a trusted CIDR. Prometheus scrapers on another host must be in `HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS` or send the token. - Code that relied on a request with no peer address being treated as loopback now gets the non-loopback path. - The default loopback run is unchanged. ## Tests - `tests/test_proxy_bind_policy.py`: the refuse/allow matrix (non-loopback, loopback, unset host, token, acknowledgement values), the warning on the acknowledged path, `create_app`, the `run_server` exit before uvicorn, and the CLI (refusal, `HEADROOM_HOST` from env, acknowledged start, offline banner, start with a token). - `tests/test_proxy_loopback_gating.py`: each data route against non-loopback, loopback, trusted-CIDR and token callers; the dashboard shell stays reachable; the host of an acknowledged, loopback-published container reads the data routes while another bridge peer, a forwarded gateway address and a foreign `Host` do not; CSV export is not served to network callers; `/metrics` across loopback, both CIDR lists, out-of-range peers, cross-origin browsers and token callers, including a trusted gateway relaying a scraper outside its own range. A regression test shows that a token on the proxy does not exempt a loopback peer from the `Host` check; it fails without the fix. - `tests/test_proxy_hardening.py`: the HTTP gate with no peer address, WebSocket `Host` cases, `require_loopback` and `/debug` with no peer. - Installer tests: `headroom install` adds the acknowledgement, and the shell and PowerShell wrappers add it only together with the loopback publication. Launcher-level tests start the proxy with the environment and `--host` that `build_runtime_command()` and `docker-compose.native.yml` produce and check that the host browser (bridge-gateway peer) gets `/stats-history` and another container does not. - Tests that bound `0.0.0.0` for unrelated reasons now set a token or the acknowledgement. Tests that read operator routes use an explicit loopback peer. On `main`, 14 of the gating and hardening tests fail and the bind-policy module does not exist. Manual runs: token-less `--host 0.0.0.0` exits with the refusal from both the CLI and `run_server`; with the acknowledgement, the data routes are 404 to a LAN peer and to a loopback peer with a foreign `Host`; with a token, a LAN peer gets 401 without it and 200 with it; the default loopback bind starts as before. Not tested: a real Unix-domain-socket deployment and a real Prometheus scrape (both covered by tests only). ## Merge order Part of a set. Suggested order: #3852 → #3891 → #3849 → #3860 → #3862 → #3863. This PR goes first: it is the gate the others assume, and it is the release-note event. ## Not in this PR - Enforcing the token for loopback callers when one is configured. Revised 2026-10-02 after review: `/metrics` matches gateway CIDRs against the TCP peer, and the operator data routes serve the host of a loopback-published container (bridge-gateway peer under the launchers' bind acknowledgement) so the default Docker dashboard works. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3852" 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 --> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
822c886d79 |
fix(proxy): let an explicit compress-user-messages off beat the profile (#3936)
## Description With the default `coding` savings profile, an operator cannot turn user-message compression off. `HEADROOM_COMPRESS_USER_MESSAGES=0` is ignored: `ProxyConfig.compress_user_messages` was a plain `bool = False`, so an explicit `0` looked the same as "not set", and `proxy_pipeline_kwargs()` could only override the profile upward (`if config.compress_user_messages: kwargs[...] = True`). The startup banner kept reporting `compress_user=True` and plain user text (pasted logs, error output, paths) kept being compressed. This makes the field tri-state, like `compress_system_messages`, `protect_recent` and the other profile knobs: `None` follows the profile, an explicit `True` or `False` overrides it. With the variable unset, nothing changes for any profile. No profile default is changed. Closes #3935 ## 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/proxy/models.py`: `compress_user_messages: bool | None = None` (was `bool = False`). - `headroom/agent_savings.py`: `proxy_pipeline_kwargs()` applies an explicit `True` or `False` over the profile value, the same way `compress_system_messages` is handled a few lines below. - `headroom/proxy/handlers/openai.py` (review follow-up): OpenAI Responses requests (`/v1/responses` over HTTP, the Codex WebSocket path and passthrough Responses) are split into `CompressionUnit`s instead of going through the message pipeline. The unit builder tagged every earlier user message `compress_user="true"` without checking `compress_user_messages`, so this path ignored both the profile and any override. Earlier user turns are now tagged only when the same `proxy_pipeline_kwargs(self.config)` resolution allows it. The newest user message stays protected and tool output routing is unchanged. All three Responses entry points share this one builder, so they get the fix together. Chat completions go through `openai_pipeline.apply(**proxy_pipeline_kwargs(...))` and needed no change there. - `headroom/cli/proxy.py` (`headroom proxy`): parse `HEADROOM_COMPRESS_USER_MESSAGES` with the server's `_get_env_optional_bool`, so an empty value means unset on every entry point (review follow-up). The CLI's own `_get_env_bool_optional` is left as is. Its other three callers (`HEADROOM_SMART_CRUSHER_COMPACTION`, `HEADROOM_COMPRESS_SYSTEM_MESSAGES`, `HEADROOM_PROTECT_ANALYSIS_CONTEXT`) match the `python -m headroom.proxy.server` parsing, which also treats empty as `False`, so changing the helper would split those three between entry points. - `headroom/proxy/server.py`: `python -m headroom.proxy.server` keeps `--compress-user-messages` as force-on and otherwise reads the env var with `_get_env_optional_bool`. The uvicorn factory (`_proxy_config_from_env`) now reads the env var too; it ignored it before. That entry point seeds the profile's own value into the env first, so with nothing set explicitly it resolves to the profile default, as before. - `docs/content/docs/proxy.mdx`: the env table row now gives the default as "profile" and documents `0`. - Tests: - `tests/test_agent_savings.py`: config layer, explicit off vs unset under `coding`. - `tests/test_cli_proxy_env.py`: the `headroom proxy` command with env `0`, empty and missing, and `_proxy_config_from_env` with `0`, empty and missing. - `tests/test_openai_responses_compression_units.py`: Responses unit builder, with a long earlier user message and the flag off vs unset under `coding`. Anthropic `tool_result` blocks and Responses tool outputs still compress with the flag off; the proof below shows both. ## Testing - [x] Unit tests pass (`pytest`): targeted files, listed below - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`): changed modules only, see below - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output New tests for the config fix, on unmodified `main` ( |
||
|
|
7968122658 |
fix(proxy): stop the 0.39.0 TPM limiter from refusing large-context requests forever (#3806)
## Description #3350 (shipped in 0.39.0) started enforcing the token-per-minute bucket, which has two problems for large-context coding agents. 1. **A request larger than the bucket is refused forever.** The bucket never holds more than `rate_limit_tokens_per_minute` (`refilled_tokens` caps it there), so a request whose input is over the limit can never be admitted. The 429's `Retry-After` never comes true, and retrying, or `/compact`, which sends the same large conversation, hits the same 429 again. Once a Claude Code session passes 100k input tokens it is stuck until the proxy is restarted. 2. **The implicit 100k default is now enforced on every proxy.** Before #3350 the token bucket was never consumed, so no one ran into the default. Now a stock `headroom proxy` / `headroom wrap claude` is a 100k tokens/minute throttle, which a single 1M-context turn exceeds on its own. Users see `{"detail":"Token rate limited. Retry after 79.2s"}` straight after upgrading. Fixes: 1. `consume_from_bucket` admits an oversized request once the bucket is full, then charges it in full. The balance goes negative and later requests wait it off, so the configured average rate still holds. A request that fits in the bucket behaves exactly as before. 2. The token limit is opt-in again: `rate_limit_tokens_per_minute` defaults to `None` (no token limit). `--tpm` / `HEADROOM_TPM` still enforce one, which is what #3347 asked for. The request-per-minute limit (default 60) is unchanged. Follows up #3347 / #3350. ## 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 - `rate_limit_policy.consume_from_bucket`: a request larger than the bucket's capacity waits only for a full bucket, then is admitted and charged in full. - `TokenBucketRateLimiter`: `tokens_per_minute=None` never limits and creates no token buckets. - `ProxyConfig.rate_limit_tokens_per_minute`, `headroom proxy --tpm` and the `python -m headroom.proxy.server --tpm` default to `None`. The startup banner prints `unlimited`, and the docs table says so too. - Tests: three policy cases (oversized admitted when full, waits only for a full bucket, debt delays the next request); the four handler integration tests now check that the first oversized request is admitted and charged, and that the second is refused before upstream; the limiter defaults to no token limit; the CLI default is `None`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ uv run --frozen --extra dev pytest tests/test_rate_limit_policy.py tests/test_rate_limiter.py tests/test_proxy_tpm_enforcement.py tests/test_proxy_config_rate_limit.py tests/test_proxy_openai_rate_limit_key.py tests/test_codex_rate_limits.py tests/test_cli_proxy_env.py -q 139 passed, 1 skipped, 1 warning in 4.37s # The same new policy/integration tests on the 0.39.0 consume_from_bucket: $ uv run --frozen --extra dev pytest tests/test_rate_limit_policy.py tests/test_proxy_tpm_enforcement.py -q 6 failed, 6 passed, 1 warning in 2.56s $ uvx ruff check <changed files> All checks passed! $ uvx ruff format --check <changed files> 6 files already formatted $ uv run --frozen --extra dev mypy headroom/proxy/rate_limiter.py headroom/proxy/models.py headroom/cli/proxy.py headroom/proxy/server.py Success: no issues found in 4 source files ``` ## Real Behavior Proof - Environment: macOS 15 (Darwin 24.6.0), Python 3.12. Stock headroom-ai 0.39.0 wheel on port 18902, this branch on port 18901, both `headroom proxy --no-optimize` with default settings. - Exact command / steps: POSTed the same ~435k-input-token `/v1/messages` request (claude-haiku-4-5, invalid API key so the upstream answers 401 instead of running it) twice to each proxy, then repeated against this branch started with `--tpm 100000`. - Observed result: Stock 0.39.0: 429 `Token rate limited. Retry after 200.8s` on both tries, the second in 6 ms, and the same on every retry after that. This branch, default settings: 401 from Anthropic on both tries (forwarded, no token limit). This branch with `--tpm 100000`: the first try was forwarded (401 from Anthropic) and the second got 429 `Retry after 260.6s`, the wait for the 335k-token debt plus a full bucket. That wait now actually ends. - Not tested: A real paid 1M-context session against Anthropic (the upstream 401 is enough to prove the proxy forwarded the request); Gemini and OpenAI Responses live (covered by the handler integration tests only). ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Stable. - Stable/default behavior changed: Yes. The default token-per-minute limit goes back to unlimited, as it effectively was before 0.39.0; an explicit `--tpm` / `HEADROOM_TPM` still enforces one. - Kill switch / disable path: Set `--tpm` / `HEADROOM_TPM` to restore a token limit; `--no-rate-limit` disables rate limiting entirely. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert this PR. ## 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 - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes The two commits can be taken separately. The first alone fixes the permanent 429 for anyone who sets `--tpm`. The second restores the pre-0.39.0 default. Headroom Desktop is working around this for now by launching the proxy with `--no-rate-limit`. --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> |
||
|
|
0d99e5595d |
fix(tests): isolate persisted settings from developer state (#3449)
## Description Clearing `HEADROOM_*` environment variables still leaves the developer's persisted settings active. Tests that construct the proxy or use the settings store can read `~/.headroom/settings.json`, and settings endpoint tests can write back to it. Give each test a temporary settings store through the existing `HEADROOM_SETTINGS_PATH` override. Explicit path-precedence tests can opt out or supply their own path. Extracts the settings-isolation portion of #2524, including the CLI precedence-test opt-outs, with focused regression coverage. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - Set a fresh per-test settings path in `tests/conftest.py` after the shared fixture scrubs developer environment variables. - Keep both CLI settings-precedence tests in `tests/test_cli_proxy_env.py` pointed at their deliberately seeded temporary workspace. - Add `tests/test_settings_isolation.py`: a regression that reads and writes through the real settings store, verifies an empty initial state for each case, and preserves a simulated developer settings file byte-for-byte. ## Testing - [x] Unit tests pass (`pytest`) — 368 targeted cases across settings, paths, proxy endpoints, CLI configuration, and the related frozen-prefix regression - [x] Linting passes (`ruff check .`) — for the three changed files - [x] Type checking passes (`mypy headroom`) — via the full-package mypy commit hook - [x] New tests added for new functionality - [x] Manual testing performed — new regression observed failing before the fixture change ### Test Output ```text python -m pytest tests/test_settings_isolation.py tests/test_proxy_loopback_gating.py tests/test_proxy/test_settings_store.py tests/test_proxy_settings_endpoints.py tests/test_paths.py tests/test_proxy/test_settings_fresh_process_precedence.py -q --tb=short 233 passed python -m pytest tests/test_cli_proxy_env.py tests/test_cli_proxy_improvements.py tests/test_paths_backward_compat.py -k 'not TestMissingProxyDepsError' -q --tb=short 134 passed, 2 deselected python -m pytest tests/test_proxy_anthropic_cache_stability.py -k memory_context_avoids_system_mutation_when_prefix_frozen -q --tb=short 1 passed, 27 deselected python -m pytest tests/test_settings_isolation.py tests/test_proxy_loopback_gating.py::test_settings_post_trusted_gateway_client_same_origin_allowed tests/test_cli_proxy_env.py::TestSettingsFileToEnv -q --tb=short 6 passed ruff check tests/conftest.py tests/test_settings_isolation.py tests/test_cli_proxy_env.py All checks passed! ruff format --check tests/conftest.py tests/test_settings_isolation.py tests/test_cli_proxy_env.py 3 files already formatted git diff --check ``` The broader CLI run encountered two dependency-check failures in `TestMissingProxyDepsError`: those tests mock `builtins.__import__`, while the dependency check uses `importlib.import_module`. The missing-FastAPI case also fails in the unchanged checkout, so both are pre-existing and are excluded from the targeted passing run above. An existing Starlette TestClient deprecation warning remains. ## Real Behavior Proof - Environment: macOS, Python 3.12, existing native extension and installed test dependencies; clean worktree based on `e67b3c8a`. - Exact command / steps: seed a simulated developer home with `{"target_ratio": 0.9}`, run `python -m pytest tests/test_settings_isolation.py -q` against the unchanged fixture, then apply the `tests/conftest.py` change and rerun `python -m pytest tests/test_settings_isolation.py tests/test_proxy_loopback_gating.py::test_settings_post_trusted_gateway_client_same_origin_allowed tests/test_cli_proxy_env.py::TestSettingsFileToEnv -q --tb=short`, followed by the wider targeted runs listed under Test Output. - Observed result: before the fixture change, both regression cases fail because `settings_store.load()` returns the developer's persisted `target_ratio` instead of an empty mapping. After the change, both cases start empty, save and reload their own settings, and leave the simulated developer file byte-for-byte unchanged; the formerly failing settings endpoint test passes and the CLI precedence tests still read their own seeded workspace (6 passed). - Not tested: full repository suite, other operating systems, or live providers. Coverage is limited to persisted settings; tool-home and network isolation are separate follow-ups. ## Runtime Rollout Safety - Rollout-managed feature(s): None. Test-only change under `tests/`; no shipped code path is touched. - Minimum rollout channel: N/A — nothing ships to users from this change. - Stable/default behavior changed: No. Production behavior is unchanged; only the pytest fixture environment gains a per-test `HEADROOM_SETTINGS_PATH`. - Kill switch / disable path: N/A — no runtime feature to disable. Tests that need a specific path opt out of the fixture or set their own `HEADROOM_SETTINGS_PATH`. - Unsafe override required: No. - Qualification impact: None. No new qualification gates; the suite continues to run unchanged apart from stronger isolation. - Rollback path: Revert this commit. ## 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 added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] My changes generate no new warnings - [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 Test-only change: no documentation, dependency, or public configuration updates apply. The two `TestMissingProxyDepsError` failures noted above are pre-existing and unrelated to this fixture change. |
||
|
|
3d3c629a9f |
fix(proxy): write per-port proxy logs so concurrent instances stop truncating each other (#3204)
## Description Every proxy instance wrote the same two fixed files: `~/.headroom/logs/proxy.log` (runtime log, via the `RotatingFileHandler` in `_setup_file_logging`) and `~/.headroom/logs/proxy-stdio.log` (subprocess stdout/stderr from `_start_proxy`). The name is a constant (`paths.py` `_PROXY_LOG_FILE = "proxy.log"`), so N concurrent proxies on different ports (wrapped copilot, droid, claude; plus any persistent `install agent` deployment) run N independent rotating handlers over the *same* file and truncate/rename each other's history. This fix keys both files by port (`proxy-<port>.log`, `proxy-stdio-<port>.log`) so each proxy rotates only its own file. `headroom perf` aggregates every per-port file and still reads a lone legacy `proxy.log` when that is all that exists (backward compat); the `proxy-stdio-*` captures (raw stdout/stderr, not PERF records) are excluded from the parser. This matters more now that wrap-spawned proxies self-exit after an idle grace (orphan-proxy watchdog, #3202): the process is gone, so its per-port log is the only forensic evidence and must survive an unrelated proxy's rotation. Closes #3203 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/paths.py`: `proxy_log_path(port=None)` and new `proxy_stdio_log_path(port=None)` are the single source of truth for the filenames (`proxy-<port>.log` / `proxy-stdio-<port>.log` with a port, legacy names without). The `_PROXY_LOG_FILE` constant stays only as the readers' fallback name. - `headroom/proxy/helpers.py`: `_setup_file_logging(port=None)` targets `proxy_log_path(port)`. The duplicate-handler guard runs BEFORE the `RotatingFileHandler` is constructed (construction opens the file), so a second `create_app` on a different port in one process cannot leave an empty stray `proxy-<port>.log` or leak an fd; a handler pointing at a different port is replaced and closed so per-port keying holds. - `headroom/proxy/server.py`: `create_app` resolves `config` first, then calls `_setup_file_logging(config.port)` (the proxy always knows its own port). - `headroom/cli/wrap.py`: `_get_log_path(port=None)` / `_get_proxy_stdio_log_path(port=None)` are per-port; `_start_proxy` passes its `port`. The stdio filename comes from `paths.proxy_stdio_log_path` (single source) and its directory from `_get_log_path`. - `headroom/perf/analyzer.py`: `parse_log_files` selects PERF logs by a positive filename match (`_PERF_LOG_FILE_RE` = `proxy(-<digits>)?.log(.N)?`) rather than a `proxy-stdio` blacklist, so `proxy-stdio-*.log` and any other `proxy-<word>.log` are never ingested; ordering is deterministic (mtime, then path). - `headroom/cli/perf.py`, `wiki/cli.md`: doc/help text updated for per-port + legacy. - `tests/test_perf_per_port_logs.py` (new): per-port path helpers; a second `_setup_file_logging` on a new port reroutes cleanly with no cross-file leakage (regression for the guard-ordering bug); and `parse_log_files` aggregates per-port + legacy while excluding stdio and other non-PERF `proxy-*.log`. - `tests/test_cli_proxy_env.py`, `tests/test_agent_savings.py`, `tests/test_cli/test_wrap_{codex,claude_vertex_proxy_env,proxy_detach}.py`: the `_get_log_path` monkeypatches take the new optional `port`, and the two stdio-filename assertions/fixtures in `test_cli_proxy_env.py` use the per-port name. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) — plus `ruff format --check` - [x] 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_perf_per_port_logs.py tests/test_cli_proxy_env.py tests/test_agent_savings.py -q -p no:randomly 115 passed, 1 skipped in 4.44s $ .venv/bin/python -m pytest tests/test_cli_perf_format.py tests/test_learn/test_analyzer.py -q 107 passed in 4.16s $ .venv/bin/python -m pytest tests/test_cli/test_wrap_proxy_detach.py tests/test_cli/test_wrap_codex.py tests/test_cli/test_wrap_claude_vertex_proxy_env.py -q 120 passed in 171.19s $ .venv/bin/ruff check <touched> && .venv/bin/ruff format --check <touched> All checks passed! $ .venv/bin/mypy headroom/paths.py headroom/cli/wrap.py headroom/proxy/helpers.py headroom/proxy/server.py headroom/perf/analyzer.py Success: no issues found in 5 source files ``` Rust gate (`cargo clippy/test/fmt`) not run: Python-only change, no crate touched. ## Real Behavior Proof - Environment: macOS 26.5 arm64, Python 3.13, local editable source build. - Exact command / steps: `headroom proxy --port 8890` and `headroom proxy --port 8891` started concurrently; inspected `~/.headroom/logs/`; then `headroom perf --hours 1 --format json`. - Observed result: each proxy wrote its own file (`proxy-8890.log`, `proxy-8891.log`, independent), the pre-existing shared `proxy.log` was not touched, and `headroom perf` reported `log_files_read: 4`, aggregating per-port + legacy with no error. `test_setup_file_logging_reroutes_on_port_change` additionally drives the production helper twice in one process and asserts each port's records land only in its own file. - Not tested: Windows path semantics (filename construction is platform-independent `pathlib`); a legacy `proxy.log` written by an OLD binary running beside a new per-port one end to end (readers handle it, but not exercised live). ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: N/A (no flag; readers accept both layouts). - Stable/default behavior changed: log filenames change from `proxy.log` to `proxy-<port>.log`; `headroom perf` reads both, so history is not orphaned. - Kill switch / disable path: N/A (no flag). - Unsafe override required: no. - Qualification impact: none — readers stay backward compatible with a lone legacy `proxy.log`. - Rollback path: revert; a downgraded binary writes legacy `proxy.log` again and readers still aggregate any per-port files left behind. Disk growth: each per-port family keeps the prior bound (`maxBytes=10 MB × backupCount=5` = 60 MB), but there is now one family per distinct port used instead of one global family. Ports are usually stable (default 8787; wrap auto-selects a nearby free port), so in practice a handful of families; the theoretical worst case is bounded by the port scan (`_find_available_port`, ≤100) → ≤ ~6 GB. No automatic pruning; stale `proxy-<port>.log*` families can be deleted safely (perf reads whatever remains). A retention policy is intentionally out of scope. ## 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 - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A — log-filename change; no UI. ## Additional Notes Follow-up (separate SDK PR, not here): the TypeScript SDK helper `sdk/typescript/src/paths.ts::proxyLogPath()` still returns legacy `proxy.log` with no port argument and is pinned by `paths.test.ts`. It mirrors `paths.py`, so it should gain an optional port argument in an SDK PR (kept separate to stay one-surface, and because that package's vitest suite is the right gate for it). |
||
|
|
e5b3a634df |
fix(proxy): dedupe Codex WS request logging for accurate mixed-provider dashboards (#2189)
## Description Running Claude Code (Anthropic) and Codex (OpenAI) against the **same** Headroom proxy instance on one port produced incorrect, unstable dashboard data. The proxy core is provider-isolated and multi-provider-safe by design; the defect was in the observability layer. The Codex `/v1/responses` **WebSocket** handler was the only path in the proxy that wrote to the request logger by hand instead of through the unified `emit_request_outcome` funnel, and it did so twice per session close: the per-turn funnel record plus an unconditional cumulative session-summary `RequestLog`. This PR removes the duplicate summary log so Codex WS emits exactly one request log per turn, matching the HTTP provider paths. ## 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 - Dropped the duplicate cumulative session-summary `RequestLog` in the Codex WS handler while preserving the per-turn `emit_request_outcome` path. - Preserved gated `request_messages` and `turn_id` on residual outcomes so dashboard telemetry keeps the useful attribution without double-counting tokens. - Ensured explicit `--anyllm-provider` wins over a leaked `HEADROOM_ANYLLM_PROVIDER` environment variable. - Registered retry delay settings that had drifted out of the settings registry. - Hardened tests against developer-shell `HEADROOM_*` / `ANTHROPIC_CUSTOM_HEADERS` leakage and stabilized several focused proxy/wrap test fixtures. ## 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/pytest tests/ -q -p no:cacheprovider 8529 passed, 537 skipped, 5831 warnings in 276.25s (0:04:36) $ .venv/bin/ruff check <touched files> All checks passed! ``` ## Real Behavior Proof - Environment: macOS (Darwin 25.4.0), Python 3.13.14, pytest 9.0.3, ruff via project venv, branch `fix/multi-provider-runtime`. - Exact command / steps: Ran the full test suite without pytest cache provider and Ruff on all touched files; used `git stash` to confirm the stale fake-config failures pre-existed this change. - Observed result: Full suite passed with no failures; Ruff passed; Codex WS now routes end-of-session logging through `emit_request_outcome`, emitting one request log per turn with the same accounting model as Anthropic HTTP turns. - Not tested: Live simultaneous Claude + Codex dashboard run. `mypy headroom` was not run to completion; a scoped run reported one pre-existing `settings_store.py:470` coercion error outside this diff. ## 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 - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A - server-side observability fix; no UI markup changed. ## Additional Notes - The proxy's multi-provider routing, header/auth isolation, and per-model cache keying are already correct and unchanged here; only the WS observability write path was double-counting. - Architectural assessment: `plans/reports/research-260714-0004-multi-provider-upstream-compression-report.md`; root-cause + resolution trail: `plans/reports/debug-assessment-260714-0011-dashboard-instability-mixed-claude-codex-report.md`. - No live simultaneous Claude + Codex dashboard run was performed; validation is from test coverage and code review of the WS logging path. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
4364eb8dc4 |
fix(copilot): refresh wrapped subscription tokens (#2156) (#2182)
## Description `headroom wrap copilot --subscription` currently validates a Copilot subscription credential once at launch, exchanges it once, and then pins that short-lived API token into the proxy as an explicit override. When the token expires, long-lived wrapped sessions start returning `transient_auth_error` and then a final HTTP 401 until the entire wrapped session is restarted. This PR keeps the validated launch token for first-request determinism, carries reusable OAuth refresh material into the proxy, and refreshes inside `CopilotTokenProvider` when the seeded token is expired. The explicit `GITHUB_COPILOT_API_TOKEN` override path stays unchanged when no reusable OAuth token exists. The configured `GITHUB_COPILOT_API_URL` also stays pinned across refresh, matching the current wrap contract. Closes #2156. ## 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 - Extended the Copilot subscription token resolution path to carry reusable OAuth refresh material and expiry metadata instead of discarding it after the wrap-time exchange. - Reworked `CopilotTokenProvider.get_api_token()` so it seeds the wrapper-validated launch token once for the first request, then refreshes through the existing exchange path when that token is expired and reusable OAuth material exists. - Rejected non-finite seeded expiry values such as `inf`, so malformed `GITHUB_COPILOT_API_TOKEN_EXPIRES_AT` inputs cannot pin a stale launch token forever. - Preserved the explicit `GITHUB_COPILOT_API_TOKEN` override path when no reusable OAuth token exists, so non-refreshable overrides keep today's fixed behavior. - Kept explicitly configured `GITHUB_COPILOT_API_URL` values pinned across refresh rather than adopting a refreshed payload's host. - Replaced wrapper-managed seeded `tid_` bearer passthrough with the refresh-aware provider path, so the wrapped CLI no longer bypasses expiry refresh just because it keeps sending the launch token back to the proxy. - Started a dedicated local proxy instance whenever a subscription-seeded session targets a shared or persistent proxy port, so per-session refresh material is not silently dropped on healthy-proxy reuse or cross-wired between concurrent sessions. - Scrubbed inherited Copilot refresh-seed environment variables from both the Copilot child env and the proxy subprocess env before re-injecting the explicit launch-time values. - Added focused auth, wrap, proxy-env, and proxy-reuse regression coverage for expiry refresh, non-finite expiry rejection, session-local proxy isolation, explicit-override preservation, exchange-flag independence, configured API URL pinning, and secret handling. ## Testing - [x] Unit tests pass (`uv run pytest tests/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli_proxy_env.py tests/test_cli/test_wrap_persistent.py -q`) - [x] Linting passes (`uv run ruff check headroom/copilot_auth.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli_proxy_env.py tests/test_cli/test_wrap_persistent.py`) - [x] Formatting passes (`uv run ruff format --check headroom/copilot_auth.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli_proxy_env.py tests/test_cli/test_wrap_persistent.py`) - [x] Type checking passes (`uv run mypy headroom/copilot_auth.py`) - [x] New tests added for new functionality when applicable - [ ] Manual testing performed ### Test Output ```text 195 passed, 1 skipped in 3.14s ``` ```text All checks passed! ``` ```text 6 files already formatted ``` ```text Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: Python 3.12.13, `uv`, no live Copilot credentials. - Exact command / steps: run the focused auth, wrap, proxy-env, and proxy-reuse regression suite after seeding an expired launch token plus reusable OAuth refresh material, then rerun lint and format checks on the touched files. - Observed result: base reproduces the bug because the explicit-token branch never refreshes, accepts non-finite expiry inputs, and shared-proxy reuse can keep the wrong per-session refresh seed alive; head refreshes through the reusable OAuth token, rejects non-finite seeded expiry, replaces the wrapper-managed seeded bearer instead of blindly passing it through, preserves the valid-seed fast path and the fixed override path when no refresh material exists, keeps the configured API URL pinned across refresh, starts a dedicated local proxy when the requested port already belongs to a shared or persistent proxy, and keeps the reusable OAuth token confined to explicit proxy launch env only. The focused suite passed with `195 passed, 1 skipped in 3.14s`. - Not tested: live business-subscription session past the provider's real token-expiry window. ## 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 - [x] I have updated the CHANGELOG.md if applicable ## Additional Notes - Scope stays provider-local. The fix remains inside `headroom/copilot_auth.py` and the Copilot wrap handoff in `headroom/cli/wrap.py`; it does not add generic 401 retry logic to provider-neutral proxy layers. - The line that disables token exchange for the Copilot CLI child env is unchanged because it never reached the proxy env and was not the root cause. - Subscription-seeded sessions now get a dedicated local proxy whenever the requested port already belongs to a shared or persistent proxy; existing shared proxies are left alone to avoid disrupting attached wrappers. - Live provider confirmation still needs maintainer or reporter validation because that truth is owned by GitHub's real subscription APIs, not by local stubs. - Headroom's release pipeline generates changelog entries from conventional commits, so `CHANGELOG.md` is intentionally untouched. |
||
|
|
68676daa50 |
feat: ship the coding profile as Headroom's out-of-box default posture (#1893)
Make a bare `headroom proxy` (and the uvicorn factory / argparse main) default to the cache-mode coding posture instead of requiring users to set a dozen env vars. Profile (agent_savings.py): * "coding" is now the DEFAULT profile (DEFAULT_PROFILE), and it is rewritten for cache mode: proxy_mode="cache" and compress_user_messages=True (cache mode compresses the newest OBSERVATION delta — a user/tool turn — so compress_user must be on or there is nothing to compress; prefix stability is preserved by the delta engine, not by refusing to touch user turns). * AgentSavingsProfile carries the standalone router/handler toggles too (tool_search, cross_turn_dedup, lossless_then_lossy, protect_reads, code_aware, effort_router, lossless, min_chars_for_block); proxy_env() emits them. Defaults preserve current behavior for the other profiles. * coding sets: tool_search=1, dedupe=1, lossless_then_lossy=1, protect_reads=1, code_aware=1, effort_router=0, lossless=0, min_chars_for_block=25. CCR stays ON (no HEADROOM_NO_CCR) so any lossy loss is recoverable. * apply_agent_savings_env_defaults() now honors an explicit HEADROOM_SAVINGS_PROFILE already in the env before falling back to the default. Delivery (pollution-free by construction): * MODE and savings_profile default via INLINE defaults in the config builders (cache / coding) — no global env mutation, so unit tests that build config directly keep clean defaults. * The request-time toggles are seeded into os.environ (setdefault) via seed_proxy_env_defaults() ONLY at the executable/deployment entries — run_server() (before serving) and create_app_from_env() (uvicorn factory) — NOT in the CLI command or any library builder, so CliRunner tests never leak coding defaults into os.environ across tests. * CLI code_aware now defaults ON, matching the argparse server path (degrades to a no-op without tree-sitter). All explicit user env vars / CLI flags still win (setdefault + `or` fallbacks). HEADROOM_LOSSLESS was already 0 by default; unchanged. Tests: coding-profile + CLI-proxy-env tests updated to the new defaults; 1047 passed across the touched areas (only pre-existing memory/env failures remain). ## Description <!-- Briefly explain the change and why it is needed. --> Closes # ## Type of Change - [ ] 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 - ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Paste relevant command output or artifact links here ``` ## Real Behavior Proof - Environment: - Exact command / steps: - Observed result: - Not tested: ## Review Readiness - [ ] I have performed a self-review - [ ] This PR is ready for human review ## Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] 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 - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) Add screenshots to help explain your changes. ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. --> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
|
3a33af1af3 |
fix(cli/proxy): preserve explicit HEADROOM_MIN_TOKENS=0 / MAX_ITEMS=0 (#1886)
## Description
The Click `proxy` command builds two `ProxyConfig` fields like this:
```python
min_tokens_to_crush=_get_env_int_optional("HEADROOM_MIN_TOKENS") or 500,
max_items_after_crush=_get_env_int_optional("HEADROOM_MAX_ITEMS") or 50,
```
`_get_env_int_optional` correctly returns `0` for
`HEADROOM_MIN_TOKENS=0`, but
the trailing `or 500` treats that legitimate `0` as falsy and replaces
it with
the default. `0` is a meaningful setting — `smart_crusher` gates on
`if tokens > self.config.min_tokens_to_crush`, so
`min_tokens_to_crush=0` means
"crush every item with any tokens." The user asking for `0` silently
gets `500`
instead (and `HEADROOM_MAX_ITEMS=0` → `50`).
This is provably unintended: the argparse `headroom proxy` path sets the
**same**
fields via `_get_env_int("HEADROOM_MIN_TOKENS", args.min_tokens)`, a
helper that
preserves `0` — so the two entry points disagree on the identical env
var. And
the adjacent
`protect_recent=_get_env_int_optional("HEADROOM_PROTECT_RECENT")`
line deliberately avoids `or`, showing the distinction was understood.
Closes: no issue filed — found while auditing env-var → config parsing.
## Fix
Add a `_get_env_int(name, default)` helper (mirroring
`headroom.proxy.server._get_env_int`)
that substitutes the default only when the var is unset/empty, and use
it for
both fields:
```python
def _get_env_int(name: str, default: int) -> int:
value = _get_env_int_optional(name)
return default if value is None else value
...
min_tokens_to_crush=_get_env_int("HEADROOM_MIN_TOKENS", 500),
max_items_after_crush=_get_env_int("HEADROOM_MAX_ITEMS", 50),
```
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- `headroom/cli/proxy.py`: add `_get_env_int(name, default)` and use it
for `min_tokens_to_crush` / `max_items_after_crush` instead of `... or
<default>`.
- `tests/test_cli_proxy_env.py`: regression test asserting
`HEADROOM_MIN_TOKENS=0` / `HEADROOM_MAX_ITEMS=0` reach `ProxyConfig` as
`0`.
- `CHANGELOG.md`: Bug Fixes entry under Unreleased.
## Testing
- [x] New regression test added (`tests/test_cli_proxy_env.py`)
- [x] Linting passes (`ruff check`) and formatting is clean (`ruff
format --check`)
- [ ] Full `pytest` deferred to CI (local-OOM reason below).
```text
$ uv run ruff check headroom/cli/proxy.py tests/test_cli_proxy_env.py
All checks passed!
```
## Real Behavior Proof
- Environment: Windows 11, Python 3.12.11, headroom from this branch.
Importing `headroom` loads the torch/transformers stack and a full
`pytest` gets OOM-killed on this box, so I verified the helper logic
with a dependency-free script and left the full pytest to CI.
- Exact command / steps: replicated `_get_env_int_optional` + the new
`_get_env_int` in a standalone script (only stdlib) and ran the env
values `"0"`, `"120"`, unset, and empty through both the old `or 500`
expression and the new helper.
- Observed result: `"0"` now yields `0` (the old `or 500` gave `500`),
`"120"` → `120`, unset/empty → the default:
```text
OK: '0' -> 0 (old `or 500` gave 500)
OK: '120' -> 120
OK: unset -> 500 default
OK: empty -> 500 default
ENV-INT LOGIC VERIFIED
```
- Not tested: booting the full proxy with `HEADROOM_MIN_TOKENS=0`
end-to-end (needs the heavy stack); the value now flows through as `0`
and the regression test exercises the whole `proxy` command with
`run_server` mocked. Full local `pytest` deferred to CI (OOM, per
above).
## 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 — ran
lint + a standalone logic check; full pytest deferred to CI (local OOM,
disclosed above)
- [x] I have updated the CHANGELOG.md if applicable
## Additional Notes
- No new dependencies; a small helper plus two call-site swaps and a
test.
- @JerrettDavis tagging you — tiny, contained parity fix with the
argparse path if you have a moment.
---------
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
|
||
|
|
60af15f96f |
feat(content-router): lossless-first dispatch, cross-turn dedup, and A7 lossy-after-fold (#1818)
## Description <!-- Briefly explain the change and why it is needed. --> Closes # ## Type of Change - [ ] 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 - ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Paste relevant command output or artifact links here ``` ## Real Behavior Proof - Environment: - Exact command / steps: - Observed result: - Not tested: ## Review Readiness - [ ] I have performed a self-review - [ ] This PR is ready for human review ## Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] 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 - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) Add screenshots to help explain your changes. ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. --> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
|
8aab8f22cb |
fix(cli): wire --rpm/--tpm and HEADROOM_RPM/HEADROOM_TPM to the Click proxy command (#1375)
## Description The Click CLI (`headroom proxy`) has no `--rpm` or `--tpm` options and doesn't read `HEADROOM_RPM`/`HEADROOM_TPM` env vars. The proxy always starts with hardcoded defaults (60 RPM / 100k TPM), while the legacy argparse CLI wires both correctly via `server.py:4054-4055` and `server.py:4130-4131`. This PR adds `--rpm` and `--tpm` Click options with `envvar="HEADROOM_RPM"` / `envvar="HEADROOM_TPM"`, using `default=None` + `click.IntRange(min=1)` so unset values fall back to model defaults (60/100000) via ternary in the `ProxyConfig` constructor. The pattern matches the existing `--retry-max-attempts` option. Closes #1350 (Problem 1) ## 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`: add `--rpm` and `--tpm` Click options with `envvar=` bindings and `click.IntRange(min=1)` validation; wire to `ProxyConfig.rate_limit_requests_per_minute` / `rate_limit_tokens_per_minute` with ternary fallback - `CHANGELOG.md`: bug fix entry - `tests/test_cli_proxy_env.py`: five new tests covering default, flag, and env var paths for both RPM and TPM ## Testing - [x] Unit tests pass (`uv run pytest tests/test_cli_proxy_env.py -v`) - [x] Linting passes (`uv run ruff check .`) - [ ] Type checking passes (`uv run mypy headroom`) — N/A: repo does not enforce mypy in CI - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text # paste actual pytest -v output here after running ``` ## Real Behavior Proof - Environment: headroom proxy, Python 3.11+, no provider needed - Exact command / steps: `HEADROOM_RPM=30 headroom proxy` and `headroom proxy --rpm 30 --tpm 50000` - Observed result: proxy starts with the user-specified rate limits instead of hardcoded 60/100000 - Not tested: interaction with `--no-rate-limit` flag; argparse CLI path (unchanged) ## 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 - [x] I have updated the CHANGELOG.md if applicable ## Additional Notes Only `headroom/cli/proxy.py` is modified for the core fix. `models.py` and `server.py` already have the `rate_limit_requests_per_minute` / `rate_limit_tokens_per_minute` fields and argparse wiring; the Click path simply never set them. --------- Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
0c9b42a919 |
fix(ccr): propagate --no-ccr-marker flag to all compressors (#1022) (#1197)
## Description
Propagate `--no-ccr-marker` flag to SearchCompressor, LogCompressor,
DiffCompressor, and CodeAwareCompressor — previously only SmartCrusher
honored the flag. When `ccr_inject_marker` is `False`, the other
compressors still defaulted to `enable_ccr=True`, injecting
`<<ccr:...>>` markers into compressed output.
Closes #1022
## 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/transforms/content_router.py`: pass
`enable_ccr=self.config.ccr_inject_marker` from
`_get_search_compressor`, `_get_log_compressor`, `_get_diff_compressor`,
and `_get_code_compressor` — mirroring what `_get_smart_crusher` already
does with `inject_retrieval_marker`
## Testing
- [x] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
Baseline: 1 pre-existing failure, 2020 pass, 131 skip
Post-fix: 1 pre-existing failure, 2022 pass, 131 skip
No regressions — 5 new tests in TestNoCcrMarkerCompressors, all pass.
```
## TDD verification
- RED check (without fix):
`test_content_router_propagates_ccr_inject_marker_false_to_compressors`
FAILED — `SearchCompressor enable_ccr=True, expected False`
- GREEN check (with fix): all 5 new tests PASS — propagation test
confirms `enable_ccr=False` reaches all compressors; integration tests
confirm no `<<ccr:` markers in compressed output
## Real Behavior Proof
- Environment: Linux, Python 3.13.12, headroom main @
|
||
|
|
f309244a77 |
feat: add --disable-kompress-fallback to restore legacy PASSTHROUGH fallback (#1185)
## Description Follow-up to #1046. That PR stopped `--disable-kompress` from forcing `fallback_strategy = CompressionStrategy.PASSTHROUGH`, so ContentRouter's rule-based passes keep running when the ML model is off. As noted in review, that is a behaviour change for callers who relied on the old passthrough-everything fallback. This adds an opt-in `--disable-kompress-fallback` flag (env `HEADROOM_DISABLE_KOMPRESS_FALLBACK`) that, together with `--disable-kompress`, restores the previous behaviour by routing fall-through content to `PASSTHROUGH`. It defaults to off, so the corrected behaviour from #1046 is unchanged unless a caller explicitly opts back in. The flag is a no-op unless `--disable-kompress` is also set. ## 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 - `headroom/proxy/models.py`: added `disable_kompress_fallback: bool = False` to `ProxyConfig`. - `headroom/proxy/server.py`: when `disable_kompress` and `disable_kompress_fallback` are both set, restore `router_config.fallback_strategy = CompressionStrategy.PASSTHROUGH` (re-adding the `CompressionStrategy` import); wired the new field through the env factory, the `__main__` argparse path (`--disable-kompress-fallback`), and the `/health` config payload. - `headroom/cli/proxy.py`: added the `--disable-kompress-fallback` Click option (with `HEADROOM_DISABLE_KOMPRESS_FALLBACK` envvar) and passed it into `ProxyConfig`. - `tests/test_proxy_disable_kompress.py`: added tests for the flag restoring `PASSTHROUGH`, for it being a no-op without `--disable-kompress`, and for the `/health` config payload exposing the field. - `tests/test_cli_proxy_env.py`: added a test that the env factory honours `HEADROOM_DISABLE_KOMPRESS_FALLBACK`. ## 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 $ pytest tests/test_proxy_disable_kompress.py -v collected 5 items tests/test_proxy_disable_kompress.py::test_disable_kompress_config_keeps_optimization_but_disables_ml_fallback PASSED [ 20%] tests/test_proxy_disable_kompress.py::test_disable_kompress_defaults_to_existing_kompress_behavior PASSED [ 40%] tests/test_proxy_disable_kompress.py::test_health_config_reports_disable_kompress_fallback PASSED [ 60%] tests/test_proxy_disable_kompress.py::test_disable_kompress_fallback_restores_passthrough PASSED [ 80%] tests/test_proxy_disable_kompress.py::test_disable_kompress_fallback_without_disable_kompress_is_noop PASSED [100%] 5 passed $ ruff check headroom/proxy/server.py headroom/proxy/models.py headroom/cli/proxy.py tests/ All checks passed! ``` ## Real Behavior Proof - Environment: local clone, Python 3.13.7 venv, headroom core deps + fastapi/uvicorn/httpx[http2]. - Exact command / steps: booted the app in-process with FastAPI `TestClient` across four flag combinations and inspected both the live `ContentRouter` config and the `/health` config payload. - Observed result: both flags -> enable_kompress=False and fallback_strategy=PASSTHROUGH (/health reports disable_kompress_fallback=true); --disable-kompress alone -> fallback_strategy stays KOMPRESS (the #1046 default, /health reports false); --disable-kompress-fallback alone -> no-op (enable_kompress=True, KOMPRESS); neither flag -> defaults (enable_kompress=True, KOMPRESS). - Not tested: full live-proxy `/stats` run against a real LLM backend. ## 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 - [ ] 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 - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Additional Notes The flag is intentionally a no-op unless `--disable-kompress` is also set, mirroring where the original override lived. Happy to add a short note to the docs/README flag list if you'd like it documented there. Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
959ab0de47 |
fix(wrap): isolate proxy stdio from proxy.log on Windows (#1191)
## Description Fix the Windows `proxy.log` rollover storm by separating wrap-managed subprocess stdio from the proxy's rotating runtime log. `headroom/cli/wrap.py` currently opens `~/.headroom/logs/proxy.log` and hands that file handle to the proxy subprocess, while `headroom/proxy/helpers.py` also rotates that same path at 10 MB with five backups. On Windows, the inherited stdio handle prevents the rename in `RotatingFileHandler.doRollover()`, which matches the repeated `WinError 32` traceback loop documented in `#1184`. This change keeps `proxy.log` as the canonical rotating runtime log and moves wrap-managed stdio into a dedicated sibling file so rollover can succeed without losing startup diagnostics. Closes #1184 The reproduction and split-fix sketch in https://github.com/chopratejas/headroom/issues/1184 materially shaped the chosen scope; this PR follows that root-cause split rather than changing the proxy's rotation policy. ## 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 - redirect wrap-managed proxy subprocess `stdout` and `stderr` into a dedicated sibling log instead of `proxy.log` - keep `proxy.log` as the success-path `Logs:` target and the sole rotating runtime log owned by the proxy - read startup-failure tails from the dedicated stdio log so early crashes remain debuggable - add focused regression coverage around `_start_proxy()` and document the behavior change in `CHANGELOG.md` ## Testing - [x] Unit tests pass (`uv run pytest tests/test_cli_proxy_env.py`) - [x] Linting passes (`uv run ruff check headroom/cli/wrap.py tests/test_cli_proxy_env.py`) - [x] Formatting checks pass (`uv run ruff format headroom/cli/wrap.py tests/test_cli_proxy_env.py --check`) - [ ] Type checking passes (`uv run mypy headroom`) - [x] New tests added for new functionality when applicable - [ ] Manual testing performed ### Test Output ```text uv sync --extra dev uv run pytest tests/test_cli_proxy_env.py # Result: 46 passed in 2.79s uv run ruff check headroom/cli/wrap.py tests/test_cli_proxy_env.py # Result: All checks passed! uv run ruff format headroom/cli/wrap.py tests/test_cli_proxy_env.py --check # Result: 2 files already formatted ``` ## Real Behavior Proof - Environment: Windows, Python 3.12.13, local worktree with no live provider dependency. - Exact command / steps: `uv run pytest tests/test_cli_proxy_env.py -k "start_proxy_redirects_subprocess_stdio_to_standalone_log or start_proxy_tail_reads_standalone_stdio_log_on_process_exit or start_proxy_passes_resolved_copilot_api_url_to_proxy" -q` - Observed result: `3 passed, 43 deselected in 0.37s`; the regression slice proves `_start_proxy()` now routes subprocess `stdout` and `stderr` to `proxy-stdio.log`, still reports `Logs: .../proxy.log` to the user, reads startup-failure tails from `proxy-stdio.log`, and preserves Copilot target URL/token env wiring. - Not tested: a live Windows rollover reproduction with a real proxy process writing enough output to rotate `proxy.log`; `uv run mypy headroom`; the repo-wide suite beyond the focused regression and lint checks. ## 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 - [ ] 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 have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) Not applicable, the proof is command and log behavior rather than a visual change. ## Additional Notes The intended scope stayed narrow: isolate wrap-managed stdio from `proxy.log`, keep runtime logging semantics unchanged, and avoid widening into proxy-side logging policy changes unless the wrap-only fix proves insufficient during implementation. |
||
|
|
85786b33a3 |
feat: add HEADROOM_KEEPALIVE_EXPIRY to keep upstream connections warm (#1124)
## Description The Python proxy's `httpx.AsyncClient` (in `server.py`) sets `max_connections` and `max_keepalive_connections` but never `keepalive_expiry`, so httpx's default of **5 seconds** applies. Idle upstream connections are dropped after 5s, and any request after a >5s gap pays a fresh TCP + TLS handshake — costly on high-RTT upstream paths. The **Rust** `crates/headroom-proxy` reqwest client already hardcodes `pool_idle_timeout(Duration::from_secs(90))`; the Python path silently differs at 5s. This PR closes that gap. Closes # ## 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 - [x] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `ProxyConfig.keepalive_expiry: float = 90.0` (`headroom/proxy/models.py`) - Wired into `httpx.Limits(keepalive_expiry=...)` (`headroom/proxy/server.py`) - `HEADROOM_KEEPALIVE_EXPIRY` env in both env-based config builders (`headroom/proxy/server.py`) - CLI `--keepalive-expiry` (env `HEADROOM_KEEPALIVE_EXPIRY`) following the existing `--max-keepalive` option pattern (`headroom/cli/proxy.py`) - Docs row in `configuration.mdx` + a CLI env test in `tests/test_cli_proxy_env.py` - Default of 90s matches the Rust path; operators can override (e.g. back to `5`). ## Testing - [ ] 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 $ ruff check headroom/proxy/models.py headroom/proxy/server.py headroom/cli/proxy.py tests/test_cli_proxy_env.py All checks passed! $ ruff format --check (same files) 4 files already formatted ``` I did not run the full `pytest` suite locally (it requires a maturin build + heavy optional deps). The added test mirrors the existing `test_cli_proxy_env.py` patterns and the CLI option follows the adjacent `--max-keepalive` exactly. ## Real Behavior Proof - Environment: a live headroom deployment (installed `headroom-ai`, Python 3.11) reaching an upstream over a high-RTT tunnel. - Exact command / steps: applied the same field change, restarted the proxy, then inspected the live config. - Observed result: `ProxyConfig.keepalive_expiry == 90.0` at runtime; proxy serves normally; sparse upstream requests no longer re-handshake within the 90s window (the ~300ms cold-handshake penalty that previously recurred after the 5s default expiry is gone). - Not tested: full `pytest`/`mypy` suite locally (maturin build). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Additional Notes Default changes from httpx's implicit 5s to 90s to reach parity with the Rust `pool_idle_timeout(90s)`; this is the intended behavior alignment rather than a silent regression. CHANGELOG not touched (no entry pattern for proxy knobs observed); happy to add one if preferred. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> |
||
|
|
c0745d4161 |
feat(proxy): add request timeout config (#738)
## Description Add --request-timeout-seconds CLI flag and HEADROOM_REQUEST_TIMEOUT environment variable to the headroom proxy command, allowing users to configure the upstream request timeout (default: 300s). This is useful for slow providers such as local LLM servers (Ollama, vLLM, llama.cpp) where the default timeout may be insufficient. Fixes #737 ## 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 --request-timeout-seconds option to the proxy command with HEADROOM_REQUEST_TIMEOUT envvar support - Passed request_timeout_seconds (default: 300s when not specified) - Added tests for both CLI flag and environment variable paths ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest tests/test_cli_proxy_env.py -q 45 passed in 3.46s $ mypy headroom Success: no issues found in 356 source files $ ruff check . All checks passed! ``` ## Real Behavior Proof - *MISSING* ## 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 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 ## Screenshots (if applicable) Add screenshots to help explain your changes. ## Additional Notes Follows the existing pattern used by --connect-timeout-seconds. Environment variable approach is essential for Docker/Kubernetes deployments where modifying CLI args requires image rebuilds. <!-- headroom-maintainer-template-completion:start --> ## Description This PR prepares `feat(proxy): add request timeout config` for review by documenting the intended change, validation evidence, and remaining merge-readiness context. Linked issues: #737 ## Type of Change - [x] Bug fix - [ ] New feature - [ ] Documentation - [ ] Refactor - [ ] Tests only ## Changes Made - Commit: feat(proxy): add request timeout config - Touches `docs/content/docs/configuration.mdx` - Touches `docs/content/docs/installation.mdx` - Touches `headroom/cli/proxy.py` - Touches `tests/test_cli_proxy_env.py` - Touches `wiki/cli.md` ## Testing - [x] GitHub checks reviewed - [x] Metadata/template validation - [ ] Local functional testing ### Test Output ```text gh pr view 738 --repo chopratejas/headroom --json statusCheckRollup - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE - PR Governance / template: FAILURE ``` ## Real Behavior Proof - Environment: GitHub PR metadata and checks for `chopratejas/headroom` PR #738. - Exact command / steps: Reviewed PR title, commits, changed files, linked issues, labels, and check rollup; appended this maintainer template completion block without replacing the author's original description. - Observed result: PR body now contains all required governance sections, checked readiness fields, and a non-placeholder validation evidence block. - Not tested: This pass updated PR metadata only; code validation remains represented by the linked GitHub checks and any author-provided evidence above. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review <!-- headroom-maintainer-template-completion:end --> |
||
|
|
a14ab45cf0 |
fix(proxy): make budget enforcement actually work (#885)
## Description
`CostTracker._costs` was initialized but never written to, so
`get_period_cost()` always returned `0` and `check_budget()` always
returned "allowed" — the `--budget` flag was a silent no-op.
`_prune_old_costs()` was dead code with zero callers. This makes budget
enforcement actually work: requests are rejected once the configured
limit is reached.
Closes # <!-- no tracked issue; discovered during a proxy-pipeline audit
-->
## 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/proxy/cost.py`** — `record_tokens()` now computes the
request cost via `estimate_cost()` and appends it to `_costs`,
activating `_prune_old_costs()`. When a call site has no API usage
breakdown (cache/uncached all zero), `tokens_sent` is used as the input
count so input cost is not silently dropped. `COST_RETENTION_HOURS` 24 →
744 so retention covers the longest budget period (monthly sums from the
1st; 24h retention would have under-enforced monthly budgets).
- **`headroom/proxy/outcome.py`** — the request funnel passes
`output_tokens` through to `record_tokens()` so costs include output,
for all providers.
- **`headroom/cli/proxy.py`** — added `--budget-period
[hourly|daily|monthly]` (env `HEADROOM_BUDGET_PERIOD`); it existed in
`ProxyConfig` and the server entry point but was unreachable from the
main CLI. Fixed the `--budget` help text that wrongly said "resets at
midnight UTC".
- **`headroom/cli/main.py`** — minor registration/version plumbing.
- Tests: regression coverage for the full `record_tokens →
get_period_cost → check_budget` chain, the `tokens_sent` fallback, and
the `--budget-period` flag/env wiring.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ pytest tests/test_cost_tracker_counterfactual.py tests/test_request_outcome.py -q
40 passed
$ ruff check headroom/proxy/cost.py headroom/proxy/outcome.py headroom/cli/proxy.py
All checks passed!
$ mypy headroom/proxy/cost.py headroom/proxy/outcome.py headroom/cli/proxy.py --ignore-missing-imports
Success: no issues found
```
## Real Behavior Proof
- Environment: local macOS, Python 3.11, branch `fix/budget-enforcement`
at the PR head commit.
- Exact command / steps: `pytest
tests/test_cost_tracker_counterfactual.py::test_budget_enforced_after_recording_costs
-v` — sets `CostTracker(budget_limit_usd=0.0001)`, records ~$1.50 of
Sonnet input, then asserts `check_budget()` returns not-allowed with
`remaining == 0`.
- Observed result: budget is now enforced — `get_period_cost()` reflects
real spend and `check_budget()` rejects once the limit is exceeded (the
proxy returns HTTP 429 on that path). On `main` the same test fails
because `_costs` is never populated and `check_budget()` always returns
allowed.
- Not tested: live end-to-end rejection against a running proxy with
real upstream traffic; the running proxy needs a restart on this version
to pick up the fix.
```text
$ pytest tests/test_cost_tracker_counterfactual.py::test_budget_enforced_after_recording_costs \
tests/test_cost_tracker_counterfactual.py::test_budget_input_cost_counted_without_usage_breakdown -v
2 passed
```
## 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
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Screenshots (if applicable)
N/A — CLI/backend change with no UI surface. See **Test Output** and
**Real Behavior Proof** above for terminal evidence.
## Additional Notes
- The `ci.yml` coverage-upload change originally added here (commit
`120696e5`) was superseded by an equivalent block the maintainer added
to `main`; the merge from main resolved to main's version. Codecov now
reports all modified lines covered.
- N/A checklist items: no docs or CHANGELOG entry — this is an internal
correctness fix to an existing flag.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
|
||
|
|
9b7b436b04 |
fix: wire HEADROOM_EXCLUDE_TOOLS / HEADROOM_TOOL_PROFILES into Click proxy entrypoint (#943)
## Description The Click-based `headroom proxy` entrypoint (`headroom/cli/proxy.py`) constructed `ProxyConfig` without calling `_parse_exclude_tools` or `_parse_tool_profiles`, so `HEADROOM_EXCLUDE_TOOLS` and `HEADROOM_TOOL_PROFILES` were silently ignored for any service launched via `headroom proxy`. The argparse path in `headroom/proxy/server.py` already handled these correctly. This PR imports both helpers into the Click entrypoint and wires their output into `ProxyConfig`. Closes #825 ## 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`: import `_parse_exclude_tools` and `_parse_tool_profiles` alongside `ProxyConfig`/`run_server`; pass their output into the `ProxyConfig(...)` construction (`or None` guard collapses empty set/dict to `None` so unset vars leave `DEFAULT_EXCLUDE_TOOLS` unchanged) - `tests/test_cli_proxy_env.py`: new `TestCLIProxyExcludeToolsEnvVar` class with 5 regression tests ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ### Paste relevant command output or artifact links here ```text ============================= test session starts ============================== platform darwin -- Python 3.13.12, pytest-9.0.3 collected 43 items tests/test_cli_proxy_env.py::TestCLIProxyExcludeToolsEnvVar::test_exclude_tools_single_name_from_env PASSED tests/test_cli_proxy_env.py::TestCLIProxyExcludeToolsEnvVar::test_exclude_tools_multi_name_from_env PASSED tests/test_cli_proxy_env.py::TestCLIProxyExcludeToolsEnvVar::test_exclude_tools_unset_leaves_none PASSED tests/test_cli_proxy_env.py::TestCLIProxyExcludeToolsEnvVar::test_tool_profiles_from_env PASSED tests/test_cli_proxy_env.py::TestCLIProxyExcludeToolsEnvVar::test_tool_profiles_unset_leaves_none PASSED ============================== 43 passed in 8.95s ============================== ruff check headroom/cli/proxy.py tests/test_cli_proxy_env.py All checks passed! ``` ## Real Behavior Proof - Environment: Python 3.13.12, headroom-ai dev install - Exact command / steps: `HEADROOM_EXCLUDE_TOOLS=WebSearch headroom proxy` before fix silently built `ProxyConfig(exclude_tools=None)` despite the env var being set - Observed result: After fix, `ProxyConfig.exclude_tools` contains `{"WebSearch", "websearch"}` as verified by the new unit tests - Not tested: end-to-end proxy run with a live Anthropic endpoint ## 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 - [ ] 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 - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A ## Additional Notes The fix mirrors the exact pattern already used in the argparse path (`_main()` in `headroom/proxy/server.py` lines 3920-3922). The `or None` guard is intentional: `_parse_exclude_tools(None)` returns `set()` when the env var is unset, and `ProxyConfig.exclude_tools=None` means "use `DEFAULT_EXCLUDE_TOOLS` unchanged" — passing an empty set would instead replace the defaults with nothing. Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
|
0b4a4bd483 |
fix: support Copilot Business subscription auth (#641)
## Description Adds a first-party `headroom copilot-auth login` flow for Copilot subscription mode and uses the resulting Copilot OAuth token to perform GitHub's Copilot token exchange before launching the wrapped Copilot CLI. This fixes Business/Enterprise Cloud accounts where a generic GitHub/Copilot token can read Copilot account metadata but is rejected by the Copilot token exchange endpoint. It also avoids treating GitHub.com Enterprise Cloud account URLs such as `github.com/enterprises/acme` as API hostnames. Fixes #635 Related: #488, #610 Builds on #576 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) - [x] Documentation update - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Adds `headroom copilot-auth login` and `headroom copilot-auth status`. - Stores a Headroom-specific Copilot OAuth token under Headroom's state dir. - Exchanges reusable Copilot OAuth tokens with Copilot Chat-compatible headers before subscription-mode launch. - Carries the resolved Copilot API endpoint into `headroom wrap copilot --subscription`. - Handles GitHub.com Enterprise Cloud URLs without synthesizing invalid `api.github.com/enterprises/...` hosts. - Adds focused unit tests and README guidance for subscription login. ## 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 ```console ruff check headroom/copilot_auth.py headroom/cli/copilot_auth.py headroom/cli/main.py headroom/cli/__init__.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_subscription_smoke.py # All checks passed! ruff format --check headroom/copilot_auth.py headroom/cli/copilot_auth.py headroom/cli/main.py headroom/cli/__init__.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_subscription_smoke.py # 9 files already formatted python -m py_compile headroom/copilot_auth.py headroom/cli/copilot_auth.py headroom/cli/main.py headroom/cli/__init__.py headroom/cli/wrap.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_subscription_smoke.py uv run --no-project --with pytest --with pytest-asyncio --with click --with rich --with opentelemetry-api --with pydantic --with tiktoken --with 'litellm==1.82.3' --with fastapi --with uvicorn --with 'httpx[http2]' --with openai --with mcp --with magika --with zstandard --with websockets --with onnxruntime --with transformers --with watchdog --with sqlite-vec pytest tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli_proxy_env.py tests/test_copilot_subscription_smoke.py # 127 passed ``` Local note: `uv run pytest ...` against the project currently fails before running tests because `uv.lock` has an unrelated `gitpython` wheel/version mismatch. ## Manual Validation I tested this with an existing GitHub Copilot Business subscription associated with a GitHub.com Enterprise Cloud account. The Enterprise Cloud value I tested was in the form: ```text github.com/enterprises/<enterprise> ``` The tested flow was: ```text headroom copilot-auth login headroom wrap copilot --subscription -- --model gpt-5.4 ``` This validated that Headroom does not treat github.com/enterprises/<enterprise> as a Copilot API hostname. Instead, token exchange uses GitHub.com and Headroom routes subscription-mode traffic to the Copilot API endpoint returned by GitHub for the signed-in account. I did not test this with GitHub Enterprise Server or a custom enterprise domain such as ghe.example.com. No tokens, request IDs, or organization-specific identifiers are included in this PR. ## Real Behavior Proof - Environment: macOS Darwin, Python 3.12.7, local checkout on `codex/copilot-business-auth`. - Exact command / steps: Ran `headroom copilot-auth login`, then launched `headroom wrap copilot --subscription -- --model gpt-5.4` with a GitHub Copilot Business subscription tied to a GitHub.com Enterprise Cloud account. - Observed result: Headroom did not treat `github.com/enterprises/<enterprise>` as a Copilot API hostname; token exchange used GitHub.com and subscription traffic was routed to the Copilot API endpoint returned for the signed-in account. The latest focused Copilot auth/proxy tests pass locally (`127 passed`). - Not tested: GitHub Enterprise Server or custom enterprise domains such as `ghe.example.com`; Windows Credential Manager integration still needs confirmation from someone on Windows. ## 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 targeted unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A ## Additional Notes Acknowledgement: the OAuth/token-exchange behavior was informed by `anomalyco/opencode-copilot-auth` by Aiden Cline. No tokens are printed by the new login/status commands; only a short SHA-256 fingerprint is displayed for troubleshooting. The interactive login is included because the missing piece is not just an Enterprise URL or routing hint. For GitHub.com Enterprise Cloud accounts, URLs like `github.com/enterprises/acme` identify the enterprise account but are not Copilot API hostnames; token exchange still happens through GitHub.com and then returns the account-specific Copilot API endpoint. A command-line enterprise argument can help for true GitHub Enterprise Server/custom-domain deployments, but it cannot produce the Copilot OAuth token class that the token-exchange endpoint accepts. Ideally, Headroom would avoid an extra interactive login and reuse an existing GitHub/Copilot CLI session everywhere. In practice, some reusable-looking tokens can read Copilot account metadata but are rejected by Copilot token exchange, which leaves Business/Enterprise Cloud users with missing model catalogs. The explicit login command is the smallest independent way to obtain and persist the token needed for that exchange without asking users to pass a secret on the command line. --------- Co-authored-by: jbelanger <your-username@users.noreply.github.com> |
||
|
|
6d3f39f213 |
feat: add dashboard agent usage stats (#814)
## Description Add a clear dashboard view for per-agent token usage so end users can see Cursor, Claude, Codex, and other detected clients with before/after token counts, tokens saved, and savings percentages. The stats API now exposes a stable `agent_usage` object that the dashboard renders near the top of the session view. Fixes # ## 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 ### New Files **Tests:** - `tests/test_dashboard_agent_usage.py` — Covers agent classification, exact per-request aggregation, and aggregate fallback behavior. ### Modified Files - `headroom/proxy/server.py` — Adds per-agent usage aggregation to `/stats` with before tokens, after tokens, output tokens, saved tokens, savings percentage, source, providers, and models. - `headroom/dashboard/templates/dashboard.html` — Adds a prominent Agent Usage panel with totals, coverage status, per-agent token-flow bars, request counts, before/after tokens, saved tokens, and share of savings. ## Testing - [x] Unit tests pass: `.venv312/bin/pytest tests/test_dashboard_agent_usage.py` - [x] Linting passes: `.venv312/bin/ruff check headroom/proxy/server.py tests/test_dashboard_agent_usage.py` - [x] Diff whitespace check passes: `git diff --check origin/main...HEAD` - [x] Dashboard smoke render: local proxy on `127.0.0.1:8790`, captured Chrome headless screenshot of `/dashboard` - [x] New tests added for new functionality ## 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] 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 relevant unit tests pass locally with my changes - [ ] I have made corresponding changes to the documentation - [ ] I have updated the CHANGELOG.md if applicable ## Additional Notes The agent usage panel uses exact request-log data when available. If detailed request logs are empty, it falls back to aggregate provider/model request counts and labels the coverage as aggregate fallback so users are not misled. |
||
|
|
6d30054f82 |
Add option to disable Kompress fallback (#514)
## Summary - add HEADROOM_DISABLE_KOMPRESS / --disable-kompress to disable only Kompress ML fallback - keep the proxy optimization pipeline enabled so structural compressors can still run - expose the setting in proxy health output and direct env config path ## Tests - uv run --with pytest --with fastapi --with click --with httpx --with uvicorn pytest tests/test_cli_proxy_env.py tests/test_proxy_disable_kompress.py - uv run --with ruff ruff check headroom/cli/proxy.py headroom/proxy/models.py headroom/proxy/server.py tests/test_cli_proxy_env.py tests/test_proxy_disable_kompress.py - git diff --check Reviewed by local agent before PR; no blocking findings. |
||
|
|
693d9d20e2 |
feat(proxy): add CLI opt-outs for CCR injection (compression-only mode) (#823)
## What & why Streaming / non-MCP clients can't resolve the injected `headroom_retrieve` (CCR) tool, so CCR injection turns into unresolvable tool calls that error and inflate turn count. Today there's no proxy CLI flag to run **compression-only** — `ccr_inject_tool`, `ccr_inject_marker`, and `ccr_proactive_expansion` are hardcoded `True` defaults — so a faithful compression-only eval requires patching the image. This adds three opt-in `--no-*` flags (with env vars), **all defaulting to current behavior (CCR fully on)**: | flag | env var | effect | |---|---|---| | `--no-ccr-inject-tool` | `HEADROOM_NO_CCR_INJECT_TOOL` | don't inject the retrieve tool | | `--no-ccr-marker` | `HEADROOM_NO_CCR_MARKER` | don't add retrieval markers to compressed content | | `--no-ccr-proactive-expansion` | `HEADROOM_NO_CCR_PROACTIVE_EXPANSION` | disable proactive expansion | `ccr_inject_tool` and `ccr_proactive_expansion` already existed on `ProxyConfig`. `ccr_inject_marker` is added to `ProxyConfig` and threaded into `ContentRouterConfig` in `server.py` (previously it was only ever the router's own default). Per CONTRIBUTING I raised this in #645 first; you accepted the patch offer there. ## Changes to existing behavior None unless a flag is passed. With no flags, all three toggles stay `True` (test `test_ccr_defaults_on`). ## Test plan - `tests/test_cli_proxy_env.py::TestCLICompressionOnlyFlags` — defaults-on, `--no-ccr-inject-tool` in isolation, all three combined, and the `HEADROOM_NO_CCR_MARKER` env path. - `pytest tests/test_cli_proxy_env.py` → 26 passed; `tests/test_proxy_modes.py tests/test_proxy_pipeline_lifecycle.py tests/test_cli_proxy_env.py` → 34 passed. - `ruff check` + `ruff format --check` clean on all changed files. ## Real behavior proof - **Setup:** Linux, Python 3.13.5, `python -m venv .venv && .venv/bin/pip install -e ".[dev]"` at this branch; OpenAI-compatible upstream. - **Ran:** - `headroom proxy --help` → all three flags appear with help text. - Instantiated the live proxy: ```python from headroom.proxy.server import ProxyConfig, HeadroomProxy from headroom.transforms.content_router import ContentRouter cfg = ProxyConfig(host="127.0.0.1", port=1, ccr_inject_tool=False, ccr_inject_marker=False, ccr_proactive_expansion=False) p = HeadroomProxy(cfg) router = [t for t in p.anthropic_pipeline.transforms if isinstance(t, ContentRouter)][0] print(router.config.ccr_inject_marker) # -> False ``` - **Observed:** `router.config.ccr_inject_marker == False`; `cfg.ccr_inject_tool == False`; `cfg.ccr_proactive_expansion == False`. With no flags, all three are `True`. - **Not tested here:** a full live agentic run on this branch. The motivating field evidence (a compression-only run with zero `headroom_retrieve` calls, compression intact) was collected on the v0.23.0 image with these same three defaults flipped — this PR replaces that image patch with first-class flags. Refs #645. |
||
|
|
163677b405 |
fix: make headroom wrap readiness probe timeout configurable for slow ML imports (#581)
## Summary Makes `headroom wrap` wait long enough for slow proxy startups instead of failing at a fixed readiness window, with an ML-aware default and an env-var override. ## Why `headroom wrap` failed when the proxy took longer than a fixed startup window to bind its port. Issue #195 reports that on ML-heavy setups the proxy imports large libraries (torch, sentence_transformers, spacy) at startup and routinely exceeds the hardcoded window, so `wrap` aborts on a working proxy and the failure message gives no way to extend the wait. ## Description `headroom wrap` now lets slow proxy startups finish instead of failing at a fixed window. The readiness probe in `headroom/cli/wrap.py` reads a `HEADROOM_WRAP_PROXY_TIMEOUT` environment variable, and when no value is set it picks the default automatically: 90 seconds when an ML stack (torch, sentence_transformers, spacy) is detected via `importlib.util.find_spec` without importing it, otherwise 45 seconds. The failure message now names the active timeout and the env var to raise it. Fixes #195 ## 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 - Resolve the wrap proxy readiness window from `HEADROOM_WRAP_PROXY_TIMEOUT` in `_start_proxy`, falling back to an ML-aware default. - Detect optional ML extras with `importlib.util.find_spec` so the check itself does not pay the cold-import cost the issue describes. - Include the configured timeout and the env var name in the `RuntimeError` raised when the proxy genuinely never binds the port. ## Testing Describe the tests you ran to verify your changes: - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed New cases in `tests/test_cli_proxy_env.py` cover the default window, an extended window via the env var, an invalid value raising a clear error, and the failure message naming the configured timeout. Covered by the new tests in this PR; full suite runs in CI. ## Test Output ``` # Paste relevant test output here pytest -v tests/test_cli_proxy_env.py ``` The new `tests/test_cli_proxy_env.py` cases pass locally; the full suite runs in CI. ## 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 - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable (N/A: no CHANGELOG.md is maintained in this repo) ## Screenshots (if applicable) N/A. This is a CLI startup-timeout fix with no visual surface. ## Additional Notes The default is conservative: 90s only when an ML stack is detected via `importlib.util.find_spec` (no import cost), otherwise 45s. `HEADROOM_WRAP_PROXY_TIMEOUT` overrides both, and the failure message now names the active timeout and the env var to raise it. Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> |
||
|
|
3c77e52ce4 |
feat: add Vertex AI proxy routing (#793)
## Description Adds first-class GCP Vertex AI proxy routing for publisher REST endpoints so Vertex requests are forwarded to a configurable regional Vertex host instead of falling through to the generic OpenAI/Anthropic/Gemini passthrough selection. Fixes #792 ## Type of Change - [x] New feature (non-breaking change that adds functionality) - [x] Documentation update ## Changes Made - Added a `vertex` provider target with `VERTEX_TARGET_API_URL` and `--vertex-api-url` support. - Registered explicit Vertex publisher routes for Google `generateContent`, `streamGenerateContent`, `countTokens` and Anthropic publisher `rawPredict`, `streamRawPredict` passthrough. - Added startup banner/routing output for Vertex AI. - Added focused tests for provider target resolution, CLI/env config, banner output, and route delegation. - Added `wiki/vertex.md` with usage examples and Google Cloud source links. ## Sources - Vertex AI Gemini inference reference: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference - Google Cloud REST authentication: https://docs.cloud.google.com/docs/authentication/rest - Google Application Default Credentials: https://docs.cloud.google.com/docs/authentication/application-default-credentials ## Testing - [x] Linting passes (`python -m ruff check .`) - [x] New tests added for new functionality - [x] Focused unit tests pass - [ ] Full unit suite completed locally - [ ] Rust tests completed locally - [ ] Type checking passes locally ## Test Output ```text $ python -m ruff check . All checks passed! $ python -m pytest tests/test_provider_registry.py tests/test_provider_proxy_routes.py tests/test_cli_proxy_env.py tests/test_banner_upstream_targets.py -q 57 passed, 1 warning in 13.75s ``` Local limitations: - `python -m pytest tests scripts/tests -q` timed out after 1 hour on this Windows machine before completing. - `cargo test -p headroom-proxy --test integration_vertex_raw_predict` could not run because `cargo` is not installed on PATH in this environment. - The commit hook's `mypy` step fails locally on an existing Windows `fcntl` typing issue in `headroom/subscription/tracker.py`; `ruff`, `ruff-format`, and plugin-version hooks passed, and the commit was made with only `mypy` skipped. ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have made corresponding changes to the documentation - [x] I have added tests that prove the feature works - [ ] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable |
||
|
|
5dd2ac5e51 |
fix(cli): resolve duplicate --code-aware flag breaking proxy import
PR #411 reintroduced an older `--code-aware` is_flag option and a duplicate `code_aware_enabled=` kwarg in the ProxyConfig call, which collided with the canonical tristate `--code-aware/--no-code-aware` introduced in #260. The result: every CLI entry point (`headroom proxy`, `headroom wrap codex`, `headroom wrap claude`, etc.) raised at import time: File ".../headroom/cli/proxy.py", line 575 code_aware_enabled=code_aware or _get_env_bool(...) SyntaxError: keyword argument repeated: code_aware_enabled Removes: - The legacy `@click.option("--code-aware", is_flag=True, ...)` - The legacy `code_aware: bool` function parameter - The duplicate `code_aware_enabled=` kwarg Keeps the tristate `--code-aware/--no-code-aware` > env-var > default-off resolver. Behavior is unchanged for all flag combinations covered by tests/test_cli_proxy_env.py. Test mocks for `run_server` updated to accept `**kwargs` to match the real signature (config plus run-time options like print_banner). Without this the four code-aware tests added in #411 raised TypeError on each invocation. Plugin marketplace/manifest version bump 0.21.5 → 0.21.7 carried in this commit by the sync-plugin-versions pre-commit hook. |
||
|
|
2f982ade0e |
Merge pull request #411 from manorit2001/wip
export code-aware flag in proxy |
||
|
|
265554d4ad |
fix(cli): proxy/perf/wrap UX cleanup + perf --hours correctness
Address user-reported UX gaps across the CLI surface: - code-aware: add --code-aware/--no-code-aware (+ HEADROOM_CODE_AWARE_ENABLED env) to the Click CLI. PR #411 had added these only to the orphaned argparse main; the user-facing CLI couldn't reach the flag. Banner status text "remove --no-code-aware to enable" referenced a flag that didn't exist — fix to point at the actual flag/env. Surface code-aware in the click banner and add print_banner=False plumbing to run_server so the click path doesn't print two banners back-to-back. - --mode: hide alias clutter via metavar=[token|cache] and rewrite help to lead with the two real modes. Legacy aliases (token_mode/token_savings/...) still validate. - perf --hours: was documented but ignored. Records are now actually filtered, the report shows the actual time-range covered, and the count of records filtered out (so users can tell when raising --hours helps). - perf TOIN: replace the hash-keyed pattern dump with a strategy-distribution view + recommendation-eligibility from the live store — actionable signal rather than opaque rows. - code-graph: clarify in --help that it indexes cwd / project root. - wrap: spell out supported tools, wrap-vs-proxy distinction, and that `headroom wrap opencode` isn't a thing (use `proxy` directly for opencode; openclaw is not opencode). - mcp: note that mcp__headroom__headroom_retrieve is correct MCP namespacing, not a doubled-prefix bug. Renaming would break the proxy's tool injection. - LLMLingua cleanup: remove [llmlingua] extra from pyproject (no live code uses it). Delete wiki/llmlingua.md and clean retired flag/class references in 6 other wiki pages. Point at [ml] (Kompress) where ML compression is documented. - init -g openclaw: strip mcpServers from existing plugin entries before re-writing — newer openclaw schemas reject it, leaving stale entries from older installs unhealable. Pinned with regression test. Tests: mock_run_server signatures in two existing tests accept **kwargs (needed for the new print_banner plumbing). New test for the openclaw mcpServers strip. Full suite: 4847 passed, 262 skipped, 0 failed. |
||
|
|
7d99a71285 |
fix: expose code-aware flag
headroom proxy now accepts --code-aware so callers do not need to drop to the lower-level server entrypoint. Keep the existing env fallback so HEADROOM_CODE_AWARE_ENABLED still works when the flag is omitted. Assisted-by: Sisyphus gpt-5.4-mini Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com> |
||
|
|
e2d95614c2 | fix(proxy): support multi-worker Docker env startup | ||
|
|
38b1483a76 |
feat(cli): add Docker-native install flow and parity docs
Add system-native install scripts and host wrappers for running Headroom from Docker while keeping wrapped tools on the host. Document the Docker-native path, add a complete CLI reference with help output and parity details, and add support for root help/version aliases and proxy env-based binding behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> |
||
|
|
d4f6e3938f |
fix(proxy): add fast-fail launch settings
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> |
||
|
|
4bea17ba8a |
Fix proxy backend bugs: env vars, tool forwarding, and provider support
- CLI now reads OPENAI_TARGET_API_URL, GEMINI_TARGET_API_URL, and HEADROOM_ANYLLM_PROVIDER environment variables - Add --openai-api-url and --gemini-api-url CLI flags - Remove --backend choices restriction so litellm-* backends work - Forward tools/tool_choice through LiteLLM and any-llm backends - Parse tool call arguments from JSON string to dict (Anthropic format) - Forward top_p, stop_sequences, tools in streaming paths - Update Vertex AI model map with Claude 3 through 4.6 (from official docs) - Bump version to 0.4.1 |