mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
feat/https-compose-caddy
23
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d6df127d57 |
feat(compress): accept Gemini and Bedrock Converse bodies on the gateway turn (#4679)
## Description
`/v1/compress` in gateway mode (a request with a `gateway` block) now
accepts two more native request bodies:
- Gemini `generateContent`
- Bedrock Converse
It compresses their text slots and returns `body` in the same native
shape. This lets a gateway like LiteLLM compress native Gemini and
Bedrock passthrough traffic, which it couldn't before.
`config.mode: "ccr"` is rejected for these shapes with a 400. Every
other mode is marker-free for them.
(Was stacked on #4617, which has merged; the branch now carries current
`main`.)
## 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
### How
This works the same way `gateway_responses` does for Codex: it builds a
view instead of translating the body.
- Every compressible text slot becomes one chat-shaped pseudo message.
- Compressed text is written back by its path in the body.
- Everything else stays byte-identical: `thoughtSignature`, thought
parts, `functionCall`, `inlineData`, `toolUse`, `cachePoint`,
`reasoningContent`, `tools`/`toolConfig`.
- Tool calls appear in the view, so tool-name rules still apply. `Read`
stays verbatim, for example.
- A JSON slot is only written back if it still parses to the same JSON
type.
- If the compressed list doesn't line up with the slots, the original
transcript is forwarded and a warning is logged.
### CCR on native bodies (review fix)
A native body can't carry `headroom_retrieve`. Its `tools`/`toolConfig`
are forwarded untouched, and `create_ccr_tool_definition` only builds
chat, Anthropic and Responses shapes. It also never gets a re-drive. So
a CCR marker in a native body points at content the model can never
fetch. Before this fix, `config.mode: "ccr"` on a Gemini or Converse
gateway turn did exactly that: log output came back as a marker with
`ccr_hashes: [<hash>]` and `obligations: []`.
- `handle_compress` now answers `ccr` on a native view with `400
invalid_request`. The message names the shape, explains why, and lists
the supported modes.
- The check runs where the mode is chosen, right after `attach_view` has
recorded the shape. That is before any compression, session work or CCR
store write.
- **The rejection does not depend on `gateway.can_redrive`.** Even a
gateway that can re-drive has no way to put the retrieval tool into a
native request, so there is no capability under which native `ccr`
works.
- **Without a `gateway` block nothing changes.** A Gemini body is
already a 400 (no `messages`). A Converse body goes through the plain
messages path, where its untyped blocks are opaque: 0 tokens saved, no
markers in any mode, `ccr` included (checked). So the rule is
consistent: reject `ccr` wherever Headroom reads a native shape.
- The bypass header still returns the body untouched with no
compression, in any mode.
- I checked every other mode on the same marker-producing input
(default, `lossless`, `lossy_inline`, `lossless_then_lossy`): no marker
and no hash in any of them. These modes build pipelines with
`ccr_inject_marker=False, ccr_enabled=False`. Stale-Read notices are
hashless in marker-free modes since #4678.
- **Second defect, same family:** with `HEADROOM_DEDUPE=1`, cross-turn
dedup wrote `[↑NL same as msg 4]` into a Converse tool result. That `4`
counts view messages (system blocks, tool calls, result slots), not the
caller's `messages`, so it named the wrong message. Native views now set
`cross_turn_dedup_recoverable=False`, as `lossless` mode already did.
- The `not self.native_shape` guards on CCR arming and re-drive in
`GatewayTurn.finish` stay as defence in depth.
### Caller contract
**Gemini**
- Send top-level `contents` as a list, with no `messages` or `input`.
- `systemInstruction`/`system_instruction`, `tools` and
`generationConfig` are optional and pass through.
**Converse**
- Send `messages` where every message has role `user` or `assistant`,
and every content block has no `type` key.
- At least one block must use a Converse key: `text`, `toolUse`,
`toolResult`, `cachePoint`, and so on.
- `system` is optional, as a list of blocks.
**Both shapes**
- `config.mode`: omit it (marker-free default), or use `lossless`,
`lossy_inline` or `lossless_then_lossy`. `ccr` is a 400.
- Only gateway turns get a view. Without a `gateway` block the endpoint
behaves exactly as before. A client-sent `_headroom_native_view` key is
dropped, and `BODY_CONTROL_KEYS` strips the real one before the body is
returned.
- `config.frozen_message_count` and `config.protect_recent` count native
messages: Gemini `contents` entries and Converse `messages`.
`session.frozen_message_count` comes back in native units. The
`/v1/usage` reply's `frozen_message_count` still counts view messages,
and the docs say so.
- No re-drive is ever armed, so `obligations` never contains `redrive`,
and request hooks run stream-safe-only. Tool compaction and output
steering are skipped.
- Relayed usage can be:
- Gemini `usageMetadata`, where `promptTokenCount` already includes
`cachedContentTokenCount`.
- Converse `usage`, where `inputTokens` excludes `cacheReadInputTokens`
and `cacheWriteInputTokens`.
- The whole provider response that carries either.
- Every gateway answer, fail-open ones included, carries `wire_shape`:
`gemini`, `converse`, `openai_responses` or `messages`. A caller that
sent a native body and gets anything else, or no field at all, is
talking to an older Headroom and should forward its original body.
- Top-level `messages` in the answer is the Converse list for Converse
and the chat-shaped view for Gemini.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`): no new errors; the 8
reported are in `ccr/mcp_server.py` and `cache/prefix_tracker.py` and
are identical on `main`
- [x] New tests added for new functionality
- [x] Manual testing performed (local replay, below)
New in `tests/gateway/test_native_shapes.py`:
- `test_ccr_mode_is_rejected_for_native_bodies[gemini|converse]`: 400,
`invalid_request`, message asserted.
- `test_other_modes_forward_native_bodies_without_ccr_markers`: 4 modes
x 2 shapes, on log output large enough to produce a marker. Checks no
hash, no marker, the shape echoed, non-message keys byte-identical and
the native list mapped back.
- `test_ccr_still_works_on_a_chat_gateway_turn`: the same log output in
a chat body with `ccr` still carries a marker. This proves the input
above is marker-producing, and that chat `ccr` didn't regress.
- `test_native_bodies_get_no_dedup_pointer_into_view_messages`.
- `test_native_turns_are_never_asked_to_redrive` now runs in the default
mode, because `ccr` is a 400.
### Test Output
```text
# before the fix (new tests only, rest of the file passing)
FAILED tests/gateway/test_native_shapes.py::test_ccr_mode_is_rejected_for_native_bodies[gemini]
FAILED tests/gateway/test_native_shapes.py::test_ccr_mode_is_rejected_for_native_bodies[converse]
FAILED tests/gateway/test_native_shapes.py::test_native_bodies_get_no_dedup_pointer_into_view_messages
3 failed, 25 passed
# after
tests/gateway/test_native_shapes.py: 28 passed
# tests/gateway tests/test_gateway_turn_unit.py tests/test_compress_api.py
# tests/test_proxy_compress_endpoint.py tests/test_compress_session_mode.py
# tests/test_compress_session_shared.py tests/test_compress_passthrough.py tests/test_compress_failure.py
1 failed, 507 passed, 4 skipped
# the one failure, test_lossy_inline_emits_no_ccr_markers[1-json_minifier], fails identically on main
|
||
|
|
33f067a243 |
feat(proxy): add lossless /v1/compress mode and detect provider by wire shape (#4617)
## Description Two gaps stop a gateway from using `/v1/compress` well. Both showed up while fixing LiteLLM's `headroom` guardrail, which is the follow-up PR that needs this one. 1. **No mode compresses messages losslessly without markers.** A gateway with no retrieval loop can't resolve a marker or call `headroom_retrieve`, so it needs a mode with nothing to retrieve. The existing marker-free modes still run lossy compressors. 2. **Hooks guess the provider from the model name.** A gateway can send any client's shape to any model. Claude Code's Anthropic body routed to Gemini looked like OpenAI, so skill condensing found nothing to change. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) ## Changes Made **`config.mode="lossless"`** - Runs format-native folds only, with no markers and no CCR store writes. A registered lossless provider still applies. - Turns off stale-Read pointers, which drop the file body and need the retrieval tool. - Turns off cross-turn dedup pointers, which a client that never numbers its messages can't resolve. - Scope: the guarantee covers message compression (lossless codecs, no CCR). On a gateway turn, tool schema compaction and registered turn hooks still run as configured, as in every other mode; description truncation only happens when an operator sets `HEADROOM_TOOL_DESC_MAX_CHARS`. **`provider_for_body`** - Hooks and the session tracker now use the body's wire shape, and fall back to the model name when the shape proves nothing, such as plain text with no system prompt or tools. - Anthropic's own tool types (server tools such as `web_search_20250305`, client tools such as `bash_20250124`) end in an eight-digit date and count as the Anthropic shape, so a first-turn body whose only tool is a server tool is read correctly. - `route.provider` still follows the model. - The cache breakpoint budget runs when either the shape or the model is Anthropic, and never on a Responses body. - `gateway_response_fields` loses its unused `provider` parameter, and `RESPONSE_RECEIVED` keeps reporting the model's provider. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`, `ruff format --check .`, on the pinned 0.17.0) - [ ] Type checking passes (`mypy headroom`): one error, in `headroom/integrations/langchain/chat_model.py`, which this PR doesn't touch (local mypy 1.19.1) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text pytest tests/test_proxy_compress_endpoint.py tests/gateway tests/test_gateway_turn_unit.py tests/test_compress_route_tokenizer_by_model.py 425 passed, 4 skipped Regression tests with the fixes removed: 8 failed, 7 passed ``` ## Real Behavior Proof - **Environment:** LiteLLM main with the follow-up guardrail change, this branch as the sidecar, and a fake upstream that simulates prompt caching. No real provider API was called. - **Exact command / steps:** replayed a scripted 17-call agent session with exact-duplicate outputs removed, once direct to the fake upstream and once through LiteLLM and `/v1/compress`. - **Observed result:** 0 errors, 0 rewrites of already-sent results, `Read` and `Edit` results unchanged, about 1.3s added in total. | Client | Prompt cost vs direct | |---|---| | Anthropic Messages, Claude Code cache markers | −3.9% | | Chat Completions | −3.8% | | Responses | −4.1% | The script's outputs are synthetic, so treat these as a comparison between setups, not a forecast for real traffic. ## Known limits - The default mode and `lossy_inline` can still return a stale-Read `Retrieve original: hash=` marker, although the docs call them marker-free. This predates the PR and needs a separate fix. Proxy `--lossless` has no read-lifecycle guard either, from reading the code. - With no `ContentRouter`, `_derived_compress_pipeline` falls back to the default pipeline, so `lossless` wouldn't hold. Production always has a router, so only test stubs reach this. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4617" 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 post-merge revisit: main |
||
|
|
8d5dde7765 |
fix(docker): install the redis extra in every image (#4514)
## Description The 0.42 images ship the replica-shared compress session store, but no published variant installs the `redis` client. Setting `HEADROOM_COMPRESS_SESSION_STORE=redis://...` stopped startup with `ConfigurationError`, and `HEADROOM_CCR_BACKEND=redis` degraded to the per-process store. This PR adds the `redis` extra to the Dockerfile default and to all nine `docker-bake.hcl` targets. It locks the invariant with a release test. It also documents the session fields of `/v1/compress` and the shared session store. Closes #4513 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (a fix or feature that changes existing functionality) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `Dockerfile`, `docker-bake.hcl`: `HEADROOM_EXTRAS` gains `redis` in the default and in all nine bake targets. - `tests/test_release_workflows.py`: new `test_every_docker_variant_includes_the_redis_extra` guards the Dockerfile default, the bake targets, and the `pyproject.toml` extra. - `docs/content/docs/installation.mdx`: new `redis` extras row. The Docker tag table shows the new extras. - `docs/content/docs/proxy.mdx`, `wiki/proxy.md`: documented the `session` response fields, `HEADROOM_COMPRESS_SESSION_STORE`, its failure behavior, and the `session_affinity` interaction. ## 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 ```text $ python -m pytest tests/test_release_workflows.py -q Pytest: 55 passed $ uvx ruff@0.17.0 check . All checks passed! ``` ## Real Behavior Proof - Environment: macOS worktree of this repository, Python 3.13. - Exact command / steps: `python -m pytest tests/test_release_workflows.py -q` and `uvx ruff@0.17.0 check .`. - Observed result: 55 tests passed, ruff clean. The new test fails against the pre-change `Dockerfile`, because its `ARG HEADROOM_EXTRAS` line lacked `redis`. - Not tested: the Docker images were not built. The release test asserts the build args statically, as the sibling Bedrock test does. ## Runtime Rollout Safety - Rollout-managed feature(s): none. The change touches build args, docs, and a test. - Minimum rollout channel: not applicable. - Stable/default behavior changed: every published image now installs the `redis` client. With the extra installed, `HEADROOM_COMPRESS_SESSION_STORE=redis://...` starts instead of failing, and `HEADROOM_CCR_BACKEND=redis` uses Redis instead of the per-process fallback. - Kill switch / disable path: drop `redis` from `HEADROOM_EXTRAS` at build time, or unset the two environment variables at runtime. - Unsafe override required: no. - Qualification impact: none. No runtime code path changed. The `redis` import stays lazy, so deployments that do not set the variables are unaffected. - Rollback path: revert this PR and rebuild. ## Review Readiness - [x] I performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I performed a self-review of my code - [x] I commented my code, particularly in hard-to-understand areas - [x] I made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I 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, and a CI guard enforces this. ## Screenshots (if applicable) Not applicable. ## Additional Notes The full test suite and `mypy headroom` were not run. This PR changes no file under `headroom/`, so I ran the affected suite (`tests/test_release_workflows.py`) and lint only. The docs half also answers part of #3184 (documentation of the storage backends). The CI half of #3184 stays open, and PR #3282 covers it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4514" 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 Opus 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> Co-authored-by: Tejas Chopra <tejas@headroomlabs.ai> |
||
|
|
a90421083a |
feat(proxy): report the same tool savings on gateway /v1/compress as the proxy path (#4467)
## Description Gateway-mode `/v1/compress` now reports the same savings as the proxy path. The why is in #4466. Closes #4466 ## 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 ## Changes Made Two commits, one per gap: 1. **`fix(proxy): count tool-schema compaction ...`** - The gateway turn counts the tool definitions before and after compaction. - The handler adds both counts to `tokens_before` / `tokens_after`, with the proxy path's guard (`0 < after < before`). - Tools the client already marked `defer_loading` are skipped. 2. **`feat(proxy): report tool_tokens_saved and tool_tokens_deferred ...`** - Gateway-mode answers add `tool_tokens_saved` (from the tags `/stats` sums) and `tool_tokens_deferred` (the estimated share). - Docs: `proxy.mdx`, `wiki/proxy.md`. Non-gateway and fail-open answers do not change. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`, on the changed files) - [x] Type checking passes (`mypy`, on the changed files) - [x] New tests added for new functionality ```text $ pytest -q tests/gateway/ tests/test_gateway_turn_unit.py tests/test_proxy_compress_endpoint.py 380 passed, 5 skipped ``` The tests also pass on the first commit alone (`tests/gateway/`: 280 passed). The new test for client-deferred tools fails without its fix. ## Real Behavior Proof - Environment: macOS, Python 3.12. Before: image `headroom:0.41.0-nonroot`. After: this branch, `HEADROOM_OFFLINE=1 headroom proxy`. - Exact command / steps: start each build, then send it the same gateway-mode `POST /v1/compress` — one message plus 5 tools whose schemas carry `title` / `examples` / `default` (the annotation keys schema compaction strips), with `"gateway": {"can_redrive": false, "can_relay_response": false}` so the request is a single call. Read `tokens_before`, `tokens_after`, `tokens_saved` and the `tool_*` fields out of the JSON answer. No provider is contacted. - Observed result: same request, same tools. On 0.41.0 the tool definitions are invisible to the counts, so `tokens_saved` is 0 and neither `tool_*` field is present. On this branch the compaction is counted, so `tokens_before` / `tokens_after` carry the tool bytes and `tokens_saved` is the 240 tokens compaction stripped (`tool_tokens_saved` / `tool_tokens_deferred` stay 0 here: no tool-search extension ran, and the extension is what books deferral). ```text 0.41.0: tokens_before 13, tokens_after 13, tokens_saved 0 (no tool_* fields) branch: tokens_before 830, tokens_after 590, tokens_saved 240, tool_tokens_saved 0, tool_tokens_deferred 0 ``` - Not tested: a live run with the headroom-tool-search extension (deferral is covered by unit tests), and Responses-API bodies. ## Runtime Rollout Safety - Rollout-managed feature(s): None gate this change — the gateway `/v1/compress` accounting is not behind a registry feature. One interaction: `proxy_output_shaper` (registry feature, available `stable`, deliberately not default-enabled) consumes the augmented count. `tokens_before` is folded at `headroom/proxy/handlers/openai.py:11064` and then handed to the turn at `:11083`, which passes it as `input_tokens` to `shape_gateway_body` (`headroom/proxy/gateway_extension.py:213`) → `stratum_key` → `input_bucket`. A turn whose tool definitions push it across one of the 2k / 8k / 32k / 128k boundaries therefore lands in a bigger stratum, which picks a different output-savings baseline. The chat path already has this coupling. - Minimum rollout channel: n/a — no channel gate, so the change takes effect wherever gateway mode is served, on every channel. - Stable/default behavior changed: Yes, gateway-mode answers only. `tokens_before` / `tokens_after` now include the tool definitions before and after schema compaction, so `tokens_saved` covers the compaction saving the same way the chat handlers already do, and two fields are added. Non-gateway and fail-open answers are byte-identical. - Kill switch / disable path: None. Without compaction there is nothing to fold, and the two fields are additive on answers; a gateway that does not want them ignores them. - Unsafe override required: No. Nothing crosses a channel boundary. - Qualification impact: None. No registry entry is added, so `registry_digest` and `snapshot_digest` are unchanged. The gateway `tokens_saved` figure itself changes, which a benchmark comparing arms across this commit will see. - Rollback path: Revert the two commits. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] I have made corresponding changes to the documentation - [x] I have added tests that 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` ## Additional Notes - The fields are emitted for any claimed compress turn. Only the gateway extension claims turns today. - If a response-half hook rewrote the tool tags during a re-drive, `/stats` would no longer match the answer. Core has no such hook. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
b0c19a25f0 |
fix(security): reject unauthenticated public proxy binds (#3316)
## Description Headroom's published image and maintained Docker launchers could expose the proxy on every host interface without a proxy token. This change moves the security boundary to the deployment artifacts: published images default to a container-loopback listener, supported local launchers publish only on host loopback, and deliberate public deployments retain explicit token protection. The application factory remains transport-neutral. Closes #3283 ## Type of Change - [x] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Set both published image stages to a container-loopback default while keeping explicit host overrides available. - Changed native Compose and the maintained Bash and PowerShell launchers to use an internal `0.0.0.0` listener with host-loopback publication. - Preserved the top-level Compose token requirement and the existing HTTP and WebSocket credential behavior for deliberate public binds. - Scoped differential-capture token injection to the internal `headroom-proxy` destination and kept sensitive headers redacted in captured records. - Added focused launch-contract, native-core, capture, and Docker publication checks, plus a base/head harness that tolerates a base already containing the fix. - Updated Docker, installer, capture, and mirrored documentation, including an unauthenticated local loopback quickstart and an authenticated deliberate-public example. ## Testing - [x] Focused unit and integration tests pass - [x] Linting and formatting checks pass - [ ] Type checking passes - [x] New tests added for the changed deployment and capture behavior - [ ] Manual testing performed ### Test Output ```text uv run python -m pytest tests/test_proxy_hardening.py tests/test_install/test_native_installers.py tests/test_docker_compose_persistence.py tests/test_network_diff_capture.py tests/test_rust_core_smoke.py -q 76 passed, 1 skipped, 1 warning in 23.45s uv run ruff check tests/test_install/test_native_installers.py tests/test_install/test_runtime.py All checks passed! bash -n e2e/docker-bind-security.sh passed bash e2e/docker-bind-security.sh --base-image headroom-t3283-base --head-image headroom-t3283-head --fixture tests/fixtures/docker-bind-exposure.json --base-ref origin/main base_ref=origin/main ... runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=403 docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed ``` ## Real Behavior Proof - Environment: Windows, Docker Desktop 29.6.2, current `origin/main` base, head image, and a real Docker bridge peer. - Exact command / steps: run the focused security/runtime tests, Compose configuration checks, then `bash e2e/docker-bind-security.sh` against the current base and head image definitions. - Observed result: `76 passed, 1 skipped`; the built-image harness passed base/head health, local completion, non-loopback isolation, authenticated public HTTP/WebSocket controls, loopback runtime-slim configuration, and direct Rust-core loading. - Not tested: runtime-slim proxy service health on this host, because its unrelated ONNXRuntime import path exits with code 139; the full hosted matrix and a future published GHCR image remain CI-owned. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Unsafe override required: no - Minimum rollout channel: next release containing the Docker and launcher changes - Stable/default behavior changed: published images and maintained local Docker launchers now use loopback-safe publication defaults - Kill switch / disable path: revert the deployment-artifact changes before release; deliberate public deployments remain explicitly operator-controlled - Qualification impact: Docker users relying on all-interface default publication must opt into public publication and configure the existing proxy token - Deliberate public deployment: use an explicit public host publication, set `HEADROOM_PROXY_TOKEN`, and send the matching bearer or `X-Headroom-Proxy-Token` credential - Local deployment: use the maintained loopback publication and no mandatory token - Rollback path: revert the deployment-artifact and documentation changes together ## 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 - [x] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [x] I have added tests that prove the behavior is effective - [x] Focused tests pass locally with these changes - [x] I did **not** edit `CHANGELOG.md`; release-please generates release notes from the conventional PR title ## Additional Notes The issue fixture remains provenance for the unauthenticated publication. Native `headroom proxy` defaults and the application-level authentication owners are unchanged. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
aceff2ea9d |
fix(proxy): gateway turn fixes found by benchmarking behind a gateway (#3619)
## Description Fixes five defects found by running real Claude Code sessions through a gateway that uses the `/v1/compress` turn contract (#3605). ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - **Prompt text is never compressed on replaying callers.** The coding profile compresses user messages, and on turn 1 that rewrote a plain agent's task ("Fix this bug in the library source" became "Fix bug in source", and test ids lost their `tests/test_` prefix). When `prefix_replay_guaranteed` is set, `content_router` protects the opening user messages and the newest user message, for string and list content alike. The one exception is a newest user message that answers a fenced shell command in the assistant turn before it: that is a text harness's tool observation and still compresses. Tool results still compress, and cache freeze is unchanged. - **Anthropic's four cache breakpoint limit.** One benchmark request failed with `max 4 cache_control blocks, found 5`. Session turns in the OpenAI handler now re-place markers with `normalize_message_cache_control`. A last-stop guard, `enforce_cache_breakpoint_budget`, runs in the gateway extension for Anthropic bodies: it re-places markers, then drops the oldest extras, and logs `event=cache_breakpoint_budget` when it repairs. - **Failure relay without a body.** `POST /v1/compress/response` rejected an upstream 4xx/5xx without a response body as `missing_response`. A body is now required only on 2xx. - **Usage totals after a re-drive.** The done payload carries `billed_usage` summed across rounds. After one or more re-drives, `response` is never null: it is the hook's replacement or the latest provider response (including when the hook hands back that same object), with `usage` set to the totals in its own key shape (chat or Anthropic). Turns with no re-drive keep `response: null`. Before, the client saw the last round only. - **Cold Kompress stall.** When native Kompress init is deferred at startup, a daemon thread preloads it after a short delay. `HEADROOM_KOMPRESS_WARMUP=0` disables it. It is off under pytest and skipped on glibc < 2.28 (the #1908 segfault hosts). - Docs: `proxy.mdx` and `wiki/proxy.md` describe the 2xx-only body rule and `billed_usage`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) on the changed modules - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest tests/test_transforms_content_router.py tests/test_compress_session_mode.py \ tests/test_compress_route_tokenizer_by_model.py tests/gateway tests/test_proxy \ tests/test_kompress_preload_deferral.py 672 passed, 4 skipped in 228.49s $ uvx ruff@0.16.3 format --check <changed files> && uvx ruff@0.16.3 check <changed files> 12 files already formatted All checks passed! $ mypy <changed modules> Success: no issues found in 6 source files ``` New tests: 5 prompt-protection tests in `test_transforms_content_router.py` (3 fail without the fix), `tests/gateway/test_cache_breakpoint_budget.py`, failure-relay and billed-usage tests in `test_redrive_loop.py`, `billed_usage` in the response-half contract test, `tests/test_proxy/test_kompress_background_warmup.py`. ## Real Behavior Proof - Environment: headroom proxy on this branch behind a gateway, Claude Code with claude-sonnet-5, real Anthropic calls. - Exact command / steps: 8 smoke sessions (32 calls) on SWE-bench-style tasks, with a spend logger recording every provider round. - Observed result: 0 errors. Task statements reached the provider verbatim. On every re-driven call (2 and 3 rounds) the client's usage equalled the sum of the per-round provider usage. Kompress warmed in the background in about 4 s at startup; in a replay of the slow session the first code-aware turn went from 5.4 s to 1.3 s. - Not tested: glibc < 2.28 hosts (warm-up is skipped there by design). The original body behind the 5-breakpoint error was not captured, so the guard is covered by unit tests rather than a live repro. ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: stable. - Stable/default behavior changed: yes. Prompt text on replaying callers is no longer compressed, the done payload adds `billed_usage`, and Kompress preloads in the background when deferred. - Kill switch / disable path: `HEADROOM_KOMPRESS_WARMUP=0` for the warm-up. The other changes are correctness fixes with no switch. - Unsafe override required: no. - Qualification impact: none expected; the breakpoint guard only acts on bodies that would otherwise get a 400. - 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` ## Additional Notes Open follow-up, not in this PR: steady-state code-aware compression falls back to Kompress at 0.3 to 1.3 s per tool result even when it saves nothing. A gate for that is worth a separate change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
d9757dcc6b |
fix(proxy): gateway turn contract for /v1/compress behind a compress-turn seam (#3605)
## Description Adds a gateway turn contract to `POST /v1/compress`, allowing an API gateway to submit a complete provider request and later report the provider response. Requests without a top-level `gateway` object remain unchanged. ## 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 - Adds the request half to `/v1/compress` and the response half at `/v1/compress/response`, including bounded pending turns, idempotent rounds, usage relay, and redrive obligations. - Adds a reusable six-stage compress-turn extension seam and turn-hook priority/provider-header support. - Keeps native tool-schema deferral in the licensed extension while sharing protocol-shape helpers with core. - Accepts Anthropic, OpenAI chat, OpenAI Responses, and Kong-shaped usage payloads. - Documents the gateway contract in `docs/content/docs/proxy.mdx` and `wiki/proxy.md`. ## 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 tests/gateway + gateway unit + turn-hook seam + test_issue_746_tool_search: 358 passed ruff 0.16.3 lint/format and mypy on touched modules: clean Kong 3.9 Docker e2e (HEADROOM_KONG_E2E=1): 4 passed ``` ## Real Behavior Proof - Environment: Kong 3.9 Docker e2e and real-provider Claude Code through Kong on SWE-bench-mini. - Exact command / steps: `HEADROOM_KONG_E2E=1` gateway e2e; real-provider traffic through the gateway contract with usage relay and licensed native deferral. - Observed result: four Kong e2e tests passed; prefix cache remained intact with zero busts; relayed usage matched Anthropic token-for-token; licensed tool-search deferral reduced cache-read tokens per turn by 27–30%. - Not tested: production rollout at scale. ## Runtime Rollout Safety - Rollout-managed feature(s): gateway contract and in-process pending-turn registry. - Minimum rollout channel: controlled gateway deployment before broader enablement. - Stable/default behavior changed: only requests containing a top-level `gateway` object enter the new contract; ordinary `/v1/compress` bodies are unchanged. - Kill switch / disable path: set `HEADROOM_GATEWAY_CONTRACT=0`. - Unsafe override required: no. - Qualification impact: gateway callers must redeem advertised `redrive` and `relay_usage` obligations. - Rollback path: disable the contract with `HEADROOM_GATEWAY_CONTRACT=0` or revert the feature 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) ## Screenshots (if applicable) Not applicable; this is an API contract change. ## Additional Notes Pending turns are process-local and bounded by `HEADROOM_GATEWAY_TURN_TTL_SECONDS`, `HEADROOM_GATEWAY_MAX_PENDING_TURNS`, and `HEADROOM_GATEWAY_MAX_REDRIVES`. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> |
||
|
|
27bdc2a899 |
docs(wiki): correct the unpublished tree, and remove invented telemetry (#3390)
`wiki/` **is not published anywhere.** `.github/workflows/docs.yml` says so in its own header, no mkdocs or sphinx config exists, and `wiki/**` sits in `paths-ignore` for CI — changes there don't even run a build. It survives as pending-migration reference material for contributors. That's why this is separate from the published-site work in #3388: nothing here reaches a user through `docs.headroomlabs.ai`. It still matters, because a contributor migrating a page would carry its errors across, and because the repo is public. ## The finding that justifies this PR on its own `wiki/benchmarks.md` carried an entire **invented "Production Telemetry" section**, presented as real-world fleet data: > real-world production telemetry from 250+ active proxy instances … **52ms median overhead** … **1.4 billion tokens saved** across 249 instances Plus P90/P99 timings, ~$4,000 saved, an OS split, a version-share breakdown, and a dated collection window of March 30 – April 2, 2026. A repo-wide grep for those figures **matches only that one file.** No script, test or fixture produces them. The published benchmarks page never carried the section, so the site owner had already excised it. Removed rather than re-estimated. The per-category ranges hanging off it (4.8%, 40–80%, 83–94%, 85–94%, 60–76%) went with it and now point at the concrete compression table on the same page. The same page also described `HEADROOM_TELEMETRY` as the opt-in switch governing fleet-wide numbers. Fleet data would come from `HEADROOM_BEACON` — a **separate switch that defaults ON**. That note is gone with the section it footnoted; the accurate description of both switches shipped to the live site in #3388. ## Other corrections, each verified against source - **`wiki/agno.md`** constructed `HeadroomAgnoModel(config=...)`; the field is `headroom_config` (`integrations/agno/model.py:135`). The sibling `HeadroomPreHook` genuinely does take `config`, which is how they got conflated. - **`wiki/ccr.md`** documented CLI flags that don't exist, and a dead demo script. - **`wiki/image-compression.md`** had two broken CLI examples. - **`wiki/getting-started.md`** used `plan.transforms_applied`; `SimulationResult` exposes `transforms`. (`CompressResult` really does have `transforms_applied` — two different result types, easy to cross.) - **`wiki/cli.md`** documents 15 of ~27 top-level commands; an audit note now says so rather than implying completeness. ## Disposition, for whoever picks up the migration `wiki/cli.md` is the highest-value page to port — no site page is a full CLI reference, and `docs.yml` names it as the reason `wiki/` still exists. `wiki/integration-guide.md` and `wiki/configuration.md` also cover ground the site doesn't. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
|
ff17961cd7 |
deps: bump ruff from 0.15.22 to 0.16.2 in the pip-minor-patch group across 1 directory (#2962)
Bumps the pip-minor-patch group with 1 update in the / directory: [ruff](https://github.com/astral-sh/ruff). Updates `ruff` from 0.15.22 to 0.16.2 <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/astral-sh/ruff/releases">ruff's releases</a>.</em></p> <blockquote> <h2>0.16.2</h2> <h2>Release Notes</h2> <p>Released on 2026-08-06.</p> <h3>Bug fixes</h3> <ul> <li>[<code>flake8-pyi</code>] Avoid false positives on <code>singledispatch</code> functions (<code>PYI041</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/27335">#27335</a>)</li> </ul> <h3>Server</h3> <ul> <li>Register formatting capabilities dynamically to exclude TOML files (<a href="https://redirect.github.com/astral-sh/ruff/pull/27332">#27332</a>)</li> </ul> <h3>Contributors</h3> <ul> <li><a href="https://github.com/MeGaGiGaGon"><code>@MeGaGiGaGon</code></a></li> <li><a href="https://github.com/charliermarsh"><code>@charliermarsh</code></a></li> <li><a href="https://github.com/epage"><code>@epage</code></a></li> <li><a href="https://github.com/sharkdp"><code>@sharkdp</code></a></li> <li><a href="https://github.com/ntBre"><code>@ntBre</code></a></li> </ul> <h2>Install ruff 0.16.2</h2> <h3>Install prebuilt binaries via shell script</h3> <pre lang="sh"><code>curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-installer.sh | sh </code></pre> <h3>Install prebuilt binaries via powershell script</h3> <pre lang="sh"><code>powershell -ExecutionPolicy Bypass -c "irm https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-installer.ps1 | iex" </code></pre> <h2>Download ruff 0.16.2</h2> <table> <thead> <tr> <th>File</th> <th>Platform</th> <th>Checksum</th> </tr> </thead> <tbody> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-aarch64-apple-darwin.tar.gz">ruff-aarch64-apple-darwin.tar.gz</a></td> <td>Apple Silicon macOS</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-aarch64-apple-darwin.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-x86_64-apple-darwin.tar.gz">ruff-x86_64-apple-darwin.tar.gz</a></td> <td>Intel macOS</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-x86_64-apple-darwin.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-aarch64-pc-windows-msvc.zip">ruff-aarch64-pc-windows-msvc.zip</a></td> <td>ARM64 Windows</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-aarch64-pc-windows-msvc.zip.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-i686-pc-windows-msvc.zip">ruff-i686-pc-windows-msvc.zip</a></td> <td>x86 Windows</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-i686-pc-windows-msvc.zip.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-x86_64-pc-windows-msvc.zip">ruff-x86_64-pc-windows-msvc.zip</a></td> <td>x64 Windows</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-x86_64-pc-windows-msvc.zip.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-aarch64-unknown-linux-gnu.tar.gz">ruff-aarch64-unknown-linux-gnu.tar.gz</a></td> <td>ARM64 Linux</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-aarch64-unknown-linux-gnu.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-i686-unknown-linux-gnu.tar.gz">ruff-i686-unknown-linux-gnu.tar.gz</a></td> <td>x86 Linux</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-i686-unknown-linux-gnu.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-powerpc64-unknown-linux-gnu.tar.gz">ruff-powerpc64-unknown-linux-gnu.tar.gz</a></td> <td>PPC64 Linux</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-powerpc64-unknown-linux-gnu.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-powerpc64le-unknown-linux-gnu.tar.gz">ruff-powerpc64le-unknown-linux-gnu.tar.gz</a></td> <td>PPC64LE Linux</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-powerpc64le-unknown-linux-gnu.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-riscv64gc-unknown-linux-gnu.tar.gz">ruff-riscv64gc-unknown-linux-gnu.tar.gz</a></td> <td>RISCV Linux</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-riscv64gc-unknown-linux-gnu.tar.gz.sha256">checksum</a></td> </tr> <tr> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-s390x-unknown-linux-gnu.tar.gz">ruff-s390x-unknown-linux-gnu.tar.gz</a></td> <td>S390x Linux</td> <td><a href="https://releases.astral.sh/github/ruff/releases/download/0.16.2/ruff-s390x-unknown-linux-gnu.tar.gz.sha256">checksum</a></td> </tr> </tbody> </table> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/astral-sh/ruff/blob/main/CHANGELOG.md">ruff's changelog</a>.</em></p> <blockquote> <h2>0.16.2</h2> <p>Released on 2026-08-06.</p> <h3>Bug fixes</h3> <ul> <li>[<code>flake8-pyi</code>] Avoid false positives on <code>singledispatch</code> functions (<code>PYI041</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/27335">#27335</a>)</li> </ul> <h3>Server</h3> <ul> <li>Register formatting capabilities dynamically to exclude TOML files (<a href="https://redirect.github.com/astral-sh/ruff/pull/27332">#27332</a>)</li> </ul> <h3>Contributors</h3> <ul> <li><a href="https://github.com/MeGaGiGaGon"><code>@MeGaGiGaGon</code></a></li> <li><a href="https://github.com/charliermarsh"><code>@charliermarsh</code></a></li> <li><a href="https://github.com/epage"><code>@epage</code></a></li> <li><a href="https://github.com/sharkdp"><code>@sharkdp</code></a></li> <li><a href="https://github.com/ntBre"><code>@ntBre</code></a></li> </ul> <h2>0.16.1</h2> <p>Released on 2026-07-30.</p> <h3>Preview features</h3> <ul> <li>Add an option to opt out of human-readable names (<a href="https://redirect.github.com/astral-sh/ruff/pull/27160">#27160</a>)</li> <li>[<code>flake8-pytest-style</code>] Make fixes safe by default and unsafe only when comments are present (<code>PT018</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/27201">#27201</a>)</li> <li>[<code>pyupgrade</code>] Skip fix when a defaulted <code>TypeVar</code> precedes a non-defaulted one (<code>UP040</code>, <code>UP046</code>, <code>UP047</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/27133">#27133</a>)</li> <li>[<code>ruff</code>] Fix false positive with unpacked arguments (<code>RUF065</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/26959">#26959</a>)</li> </ul> <h3>Bug fixes</h3> <ul> <li>Bump <code>gen-lsp-types</code> to gracefully handle unknown enumeration values in LSP messages (<a href="https://redirect.github.com/astral-sh/ruff/pull/27230">#27230</a>)</li> <li>[<code>flake8-bugbear</code>] Mark <code>range</code> as immutable (<code>B008</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/27247">#27247</a>)</li> <li>[<code>flake8-comprehensions</code>] NFKC-normalize keyword names in <code>C408</code> fix (<a href="https://redirect.github.com/astral-sh/ruff/pull/26813">#26813</a>)</li> <li>[<code>flake8-return</code>] Fix false positive when variable is read in <code>finally</code> clause (<code>RET504</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/25441">#25441</a>)</li> <li>[<code>pydocstyle</code>] Skip section detection inside RST directive bodies (<code>D214</code>, <code>D405</code>, <code>D413</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/23635">#23635</a>)</li> <li>[<code>refurb</code>] Parenthesize <code>yield</code> arguments in the <code>FURB192</code> fix (<a href="https://redirect.github.com/astral-sh/ruff/pull/27192">#27192</a>)</li> </ul> <h3>Rule changes</h3> <ul> <li>[<code>flake8-pytest-style</code>] Mark <code>PT022</code> fixes as unsafe (<a href="https://redirect.github.com/astral-sh/ruff/pull/26440">#26440</a>)</li> <li>[<code>refurb</code>] Mark fixes that remove unknown separators as unsafe (<code>FURB105</code>) (<a href="https://redirect.github.com/astral-sh/ruff/pull/27200">#27200</a>)</li> </ul> <h3>Server</h3> <ul> <li>Fix indexing of excluded nested Ruff workspaces (<a href="https://redirect.github.com/astral-sh/ruff/pull/27303">#27303</a>)</li> <li>Lint TOML files in the LSP (<a href="https://redirect.github.com/astral-sh/ruff/pull/26862">#26862</a>)</li> </ul> <!-- raw HTML omitted --> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/astral-sh/ruff/commit/5b48a040974781ba90b47c8df628f8fd9b6c95dd"><code>5b48a04</code></a> Bump 0.16.2 (<a href="https://redirect.github.com/astral-sh/ruff/issues/27555">#27555</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/1b9e5fc483b95a01fe02ff104820280b1b32e8ae"><code>1b9e5fc</code></a> Update Swatinem/rust-cache action to v2.9.2 (<a href="https://redirect.github.com/astral-sh/ruff/issues/27568">#27568</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/c4e86fc0394c92a9334ba2eb026c77c21db403be"><code>c4e86fc</code></a> [ty] Add helper extension methods for half-range and equality constraints (<a href="https://redirect.github.com/astral-sh/ruff/issues/2">#2</a>...</li> <li><a href="https://github.com/astral-sh/ruff/commit/17a00de2e298612201a8fe30790e9399204af1b9"><code>17a00de</code></a> [ty] Reuse primer commands in memory reports (<a href="https://redirect.github.com/astral-sh/ruff/issues/27553">#27553</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/6ea296b96923e142eb13af2bc6ad261c280d8eb1"><code>6ea296b</code></a> [ty] Normalize type labels in structured docstrings (<a href="https://redirect.github.com/astral-sh/ruff/issues/26923">#26923</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/2fc445f0053f4ec27c717fae0de3671d73c103be"><code>2fc445f</code></a> [ty] Diagnose invalid <strong>getattr</strong> calls (<a href="https://redirect.github.com/astral-sh/ruff/issues/27502">#27502</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/22c7823c4e8bffcca97688d8438c9b567d6817d8"><code>22c7823</code></a> [ty] Enable (but downrank) auto-import completion suggestions from stub-only ...</li> <li><a href="https://github.com/astral-sh/ruff/commit/05160d507f05345a72db9c28ab4edf7c92334819"><code>05160d5</code></a> [ty] Diagnose invalid descriptor <code>__get__</code> calls (<a href="https://redirect.github.com/astral-sh/ruff/issues/27400">#27400</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/baea3d0dcec6d6f6d1659321940f3725771c5f45"><code>baea3d0</code></a> [ty] Expose strict analysis options in the playground (<a href="https://redirect.github.com/astral-sh/ruff/issues/27543">#27543</a>)</li> <li><a href="https://github.com/astral-sh/ruff/commit/c88946ebeb92be6d276087f0d528cd6471df4ead"><code>c88946e</code></a> [ty] Bump ecosystem-analyzer for strict project settings (<a href="https://redirect.github.com/astral-sh/ruff/issues/27542">#27542</a>)</li> <li>Additional commits viewable in <a href="https://github.com/astral-sh/ruff/compare/0.15.22...0.16.2">compare view</a></li> </ul> </details> <br /> --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
6422a80a58 |
fix(compress): resolve the /v1/compress tokenizer per model, and document the real contract (#2743)
## Description
`/v1/compress` does no format conversion — callers send whichever wire
shape they already use — but the pipeline pinned **one provider's token
counter for the whole route**.
`OpenAITokenCounter.count_message` walks list content for `text` and
`image_url` only and has **no else branch**, so Anthropic content blocks
contributed literally zero. A 599-token `tool_result` scored 8. A
request that really removed 235 characters reported `tokens_saved: 0` —
so a caller gating on `tokens_saved > 0` concludes compression is broken
while it is working.
Prompted by a Kong integration question ("do you support the Anthropic
native format?"). The answer is that we already did — we just reported
zeros for it, and the docs said otherwise.
Closes #
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update
## Changes Made
### Tokenizer resolution (no hardcoded lists)
Build the derived pipelines with `provider=None` so `TransformPipeline`
resolves the tokenizer from the **per-model registry**. Every registry
tokenizer derives from `BaseTokenizer`, whose `_count_content_parts`
ends in a serialize-and-count catch-all, which means:
- No block type counts as zero, and there is **no per-provider
block-type list to keep in sync**. An enumerated set was the first thing
I tried and it already missed `mcp_tool_result`,
`web_search_tool_result`, `document`, and `thinking`.
- Gemini / Mistral / DeepSeek / Kimi stop defaulting to a tiktoken count
when the registry already has a calibrated counter for them.
- Gateway aliases matching no vendor pattern still count correctly.
`mode="ccr"` now runs a derived pipeline too, for the same reason —
sharing `openai_pipeline` pinned its provider. Costs that mode its own
cold compression cache; correct metrics win.
### Tokenizer selection stays separate from context-limit resolution
Deliberately not welded together. `model_limit` feeds `context_pressure
-> min_ratio`, so letting a tokenizer decision pick the limit table
changes compression aggressiveness: `gpt-4-32k` answered by the
Anthropic table is **8,192 instead of 32,768**, a 4× under-estimate.
`test_tokenizer_choice_does_not_move_the_context_limit` pins the
independence.
### Docs, rewritten from the code
- **`proxy.mdx`** — the loopback-only default and **404-not-403**
behavior, previously undocumented *anywhere* in `docs/` despite shipping
in #2458 explicitly for gateway sidecars;
`HEADROOM_COMPRESS_ALLOW_REMOTE`; all four request fields; the whole
`config` object including every `mode` value and `frozen_message_count`;
`transforms_summary`; the 400/401/404/503 contract; and the timeout
fail-open shape (`compression_skipped` / `skip_reason`).
- **Corrected "never calls an LLM"** — accurate about *generative*
provider requests, misleading for a sidecar operator. Kompress (a
ModernBERT **encoder**, classification not generation) and Magika run
**in-process**, and `HEADROOM_KOMPRESS_ENDPOINT` offloads inference over
HTTP — **real egress**. Now stated explicitly, with
`HEADROOM_DISABLE_KOMPRESS=1` as the structural-only option.
- **Both wire formats documented as accepted**, and removed
`anthropic-sdk.mdx`'s claim that OpenAI format is "the compression
engine's native format" — the exact misconception that prompted this
work. The SDK's conversion is now framed as an SDK choice, not an API
requirement.
- **`litellm.mdx`** had no mention of the endpoint at all, despite the
code naming LiteLLM's guardrail as its primary consumer. Added the HTTP
deployment path, the `HEADROOM_COMPRESS_ALLOW_REMOTE` requirement, and
why to leave `config.mode` unset.
- **`index.mdx`** printed `compressionRatio * 100` labelled "Saved …%",
so a 77% saving displayed as **23%**. `api-reference.mdx` already
defined it correctly, so the docs contradicted each other.
- `openai-sdk.mdx`, `wiki/proxy.md`, `wiki/typescript-sdk.md` — same
corrections; dropped "any HTTP client", "Cloud", and a CacheAligner
claim (it is detector-only).
## 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
$ .venv/bin/ruff check headroom/ tests/ --exclude headroom/dashboard/templates
All checks passed!
$ .venv/bin/mypy headroom/
Success: no issues found in 511 source files
$ python -m pytest tests/test_compress_route_tokenizer_by_model.py \
tests/test_proxy_compress_endpoint.py tests/test_compress_api.py \
tests/test_platform_stabilization_functional.py tests/test_proxy_eager_preload_bind.py -q
99 passed, 2 warnings in 47.15s
```
Broader sweep (`-k "compress or litellm or gateway or guardrail"`):
**1625 passed, 4 failed** — all 4 pre-existing, verified by stashing
this diff and re-running on clean `main` (2 strands hook tests, 1 codex
WS semaphore-tail timing test, 1 unrelated local WIP test).
## Real Behavior Proof
- **Environment:** macOS 26.4 arm64, Python 3.12.6, repo `.venv`, branch
rebased on `upstream/main`.
**(1) Before → after, same request** (60-line grep payload in an
Anthropic `tool_result`):
| model | before | after |
| --- | --- | --- |
| `claude-sonnet-4-6` | `before=28 saved=0` | `before=1223 saved=58` |
| `bedrock/anthropic.claude-3-5-sonnet` | `saved=0` | `before=1037
saved=59` |
| `my-gateway/big-model` (alias) | `saved=0` | `before=1037 saved=59` |
| `gemini-2.5-pro` | `saved=0` | `before=1036 saved=59` |
| `gpt-4o` + OpenAI shape | `before=1225 saved=58` | `before=1225
saved=58` (unchanged) |
All three `config.mode` values verified for each. Response shape
preserved: `type=tool_result`, `tool_use_id` intact.
**(2) Counter-level root cause**, 6.8 KB body, `count_message()`:
```text
OpenAITokenCounter string-content -> 1406 tool_result block -> 5
registry (BaseTokenizer) claude tool_result=408 thinking=418 mcp_tool_result=421
web_search_tool_result=421 document=422
```
**(3) Every documented behavior asserted against the running app** — 13
checks, all PASS: 400s for missing `messages`/`model`, invalid
`config.mode`, and all four invalid `frozen_message_count` forms; 200
for valid ones; non-dict `config` ignored; bypass and empty-messages
omit `transforms_summary`; success returns exactly the 8 documented
keys.
- **Not tested:** the docs site was not built (`docs/node_modules`
absent) — MDX was checked for balanced `<Callout>` tags only, so a
reviewer with the site running should eyeball rendering. No live
gateway/Kong request; verification is via `TestClient` against the real
ASGI app.
- **Note:** `HEADROOM_DISABLE_KOMPRESS` is read into `ProxyConfig` at
`server.py:4919` and by the CLI, not by `create_app(ProxyConfig(...))`
directly — I confirmed `disable_kompress=True` does reach the derived
pipeline.
## 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`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||
|
|
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> |
||
|
|
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> |
||
|
|
1fc5e3d4da |
docs(proxy): correct --code-aware default to disabled (#1710)
## Description
The wiki proxy page (`wiki/proxy.md`, which feeds the published docs
site) claimed `--code-aware` defaults to **true**. The CLI deliberately
defaults it to **disabled**: `headroom/cli/proxy.py` resolves the paired
flag to off unless `--code-aware` is passed or
`HEADROOM_CODE_AWARE_ENABLED` is truthy, and the Click help text plus
`docs/content/docs/proxy.mdx` and `wiki/cli.md` already document it as
disabled. This PR aligns the one remaining stale table row and collapses
the self-contradictory separate `--no-code-aware` row into a single
paired-flag entry, matching the style used in
`docs/content/docs/proxy.mdx`.
Fixes #1700
## 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `wiki/proxy.md`: replaced the two flag-table rows claiming
`--code-aware` default `true` / `--no-code-aware` default `false` with
one `--code-aware` / `--no-code-aware` row documenting the actual
default (`disabled`), the `headroom-ai[code]` requirement, and the
`HEADROOM_CODE_AWARE_ENABLED=1` env opt-in.
## Testing
- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ python -c "
from click.testing import CliRunner
from headroom.cli.proxy import proxy
r = CliRunner().invoke(proxy, ['--help'])
print([l.strip() for l in r.output.splitlines() if 'code-aware' in l][0])
"
--code-aware / --no-code-aware Enable/disable AST-based code compression.
$ grep -n "code-aware" wiki/proxy.md
77:| `--code-aware` / `--no-code-aware` | disabled | Enable or disable AST-based code compression. Requires `headroom-ai[code]` (env: HEADROOM_CODE_AWARE_ENABLED=1 to enable) |
```
## Real Behavior Proof
- Environment: Windows 11, local checkout at `upstream/main` (
|
||
|
|
bd76235f5c |
fix(cli): harden all CLI surfaces + fix docs accuracy (#1491)
## Summary
Full CLI audit + documentation accuracy pass. All 5 commits on this
branch:
### CLI Hardening (4 commits)
- **Clean errors instead of tracebacks**: corrupt manifests, missing
Docker, malformed JSONL, bad `--profile`, invalid env-var values all now
raise `click.ClickException` with helpful messages
- **Range validation**: ~25 numeric flags across 10 files now use
`click.IntRange`/`FloatRange` — `--port 0`, `--hours -1`, `--limit 0`
etc. produce clean usage errors instead of silent wrong behavior
- **Flag combination warnings**: conflicting combos (`--no-rate-limit` +
`--rpm`, `--no-optimize` + `--target-ratio`, `--telemetry` +
`--no-telemetry`) emit yellow warnings on stderr
- **`memory --db-path` default fixed**: was resolving to
`headroom_memory.db` (wrong bare file); now uses project store
`./.headroom/memory.db` if present, else `~/.headroom/memory.db`
- **`memory list --search` + filters**: `--scope`/`--session`/`--since`
were silently ignored when `--search` was also set; now filters are
applied to search results
- **`learn --verbosity --apply` now works**: the output shaper is off by
default (`HEADROOM_OUTPUT_SHAPER`); `--apply` now hot-enables it via
`POST /admin/runtime-env` on a running proxy, or prints explicit `export
HEADROOM_OUTPUT_SHAPER=1` instructions when no proxy is running
- **`perf --hours` overflow**: `1e9` hours no longer raises
`OverflowError`; treated as "all data"
- **`evals memory --categories` invalid input**: `abc,1,2` now raises
`BadParameter` instead of a raw `ValueError` traceback
### Documentation (1 commit, 20 files)
Corrected factual errors found by 3 parallel audit agents across root
docs, wiki, and the published Fumadocs site:
**Critical (caused runtime errors or wrong behavior if followed):**
- `simulation.mdx`: `plan.transforms_applied` -> `plan.transforms`;
`plan.savings_percent` -> computed from available fields (both raised
`AttributeError`)
- `shared-context.mdx`: `import { SharedContext } from "headroom"` ->
`"headroom-ai"` (5x `ImportError`)
- `claude-code-azure-foundry.mdx`: `pip install headroom` -> `pip
install headroom-ai`
- `api-reference.mdx` + `configuration.mdx`: `from headroom import
GoogleProvider` -> `from headroom.providers import GoogleProvider`
- `ccr.mdx`: CCR TTL default 300s -> 1800s (30 min)
**Fabricated flags removed:**
- `wiki/proxy.md` + `wiki/cli.md`: `--no-intelligent-context`,
`--no-intelligent-scoring`, `--no-compress-first` (none exist); replaced
with real CCR flags
- `wiki/configuration.md`: `--no-ccr-responses`, `--no-ccr-expansion`
(none exist); replaced with real flags
- `wiki/troubleshooting.md`, `wiki/metrics.md`,
`docs/troubleshooting.mdx`: `headroom proxy --log-level debug` (flag
doesn't exist)
**Stale content corrected:**
- `llms.txt`: telemetry stated as enabled-by-default (it's opt-in); wrap
list had 5 tools (now 11)
- `README.md`: compatibility matrix added 5 missing `wrap` targets;
`unwrap`, `doctor`, `init`/`install`, savings-analytics now mentioned
- `SECURITY.md`: supported version table showed 0.2.x (current: 0.27.x)
- `wiki/learn.md`: 5 missing flags added; verbosity shaper-off behavior
documented
- `wiki/quickstart.md`: "Configuration Reference" linked to `api.md`
(wrong) -> `configuration.md`
- `CacheAlignerConfig.enabled` default corrected: `True` -> `False`
- `opencode.mdx`: `--port` default wrong ("random") -> 8787; `openai`
backend removed
- `CONTRIBUTING.md`: broken Markdown table cell fixed
- `docs/meta.json`: `claude-code-azure-foundry` added to nav (was
unreachable orphan page)
- `configuration.mdx`: SDK modes vs proxy `--mode` now clearly
distinguished
## Test plan
- [x] `python -m pytest tests/ -x -q` — 857 passed, 0 failures
- [x] 41-combination CLI smoke test (all flag combos across 8 commands)
— 0 tracebacks
- [x] `ruff check` on all modified Python files — clean
- [x] Docs changes are removals/corrections of fabricated or stale
content; no new claims introduced
|
||
|
|
b99869778b |
fix(telemetry): switch anonymous telemetry to opt-in (off by default) (#1223)
## Description
Anonymous usage telemetry was **on by default** (opt-out). This flips it
to **opt-in**: nothing is collected or shipped unless the user
explicitly turns it on. Small change, but it makes "no data leaves the
proxy by default" the actual default rather than something users have to
discover and disable.
Closes # <!-- N/A: no tracking issue -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality) — adds
`--telemetry` opt-in flag
- [x] Breaking change (fix or feature that would cause existing
functionality to change) — telemetry no longer runs unless opted in
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `is_telemetry_enabled()` is now **fail-closed**: only explicit
on-values (`on`/`true`/`1`/`yes`/`enable`/`enabled`) enable telemetry;
unset, empty, or unrecognized values stay disabled. This single
predicate gates both the Supabase beacon and the local `/v1/telemetry`
collector.
- Added `--telemetry` opt-in flag to `headroom proxy` and `headroom
install apply`; kept `--no-telemetry` and `HEADROOM_TELEMETRY=off` for
back-compat. If both are passed, opt-out wins.
- Install manifests now write `HEADROOM_TELEMETRY` explicitly
(`on`/`off`) plus the matching flag, so generated systemd/docker/launchd
deployments are unambiguous and don't rely on the runtime default.
- Startup banner and proxy log show `DISABLED` by default and surface
how to opt in.
- Updated tests for opt-in defaults; added coverage for the default-off
banner, the `--telemetry` flag, and the explicit-on manifest path.
- Updated docs
(proxy/configuration/installation/benchmarks/community-savings mdx, spec
011/015, wiki proxy/cli/benchmarks/metrics) and `CHANGELOG.md`.
## Testing
- [x] Unit tests pass (`pytest`) — targeted telemetry + install-planner
suites
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ python -m pytest tests/test_telemetry_warning.py tests/test_telemetry.py tests/test_install/test_planner.py -q
81 passed
$ ruff check <changed source + test files>
All checks passed!
$ mypy headroom/telemetry/beacon.py headroom/cli/proxy.py headroom/cli/install.py \
headroom/install/planner.py headroom/proxy/server.py
Success: no issues found in 5 source files
```
## Real Behavior Proof
- **Environment:** macOS (darwin 25.4.0), project `.venv`, `headroom`
CLI.
- **Exact command / steps:**
```
$ python -c "import os; from headroom.telemetry.beacon import
is_telemetry_enabled; \
os.environ.pop('HEADROOM_TELEMETRY', None); print('unset ->',
is_telemetry_enabled()); \
[ (os.environ.__setitem__('HEADROOM_TELEMETRY', v), print(repr(v), '->',
is_telemetry_enabled())) \
for v in ['on','TRUE','1','yes','off','0','garbage',''] ]"
$ headroom proxy --help | grep -i telemetry
$ headroom install apply --help | grep -i telemetry
```
- **Observed result:**
```
unset -> False # off by default
'on' -> True 'TRUE' -> True '1' -> True 'yes' -> True
'off' -> False '0' -> False
'garbage' -> False '' -> False # fail-closed
proxy: --telemetry Opt in to anonymous usage telemetry — off by default
(env: HEADROOM_TELEMETRY=on)
--no-telemetry Force anonymous usage telemetry off (already the default;
env: HEADROOM_TELEMETRY=off)
install: --telemetry Opt in to anonymous telemetry in the runtime (off
by default).
--no-telemetry Force anonymous telemetry off in the runtime (already the
default).
```
- **Not tested:** live Supabase beacon network round-trip (no opt-in
network call was made); full `pytest` suite was not run — only the
telemetry + install-planner targeted suites.
## 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
- "Breaking change" is checked because the default behavior changes
(telemetry stops running unless opted in). It is **not** an API break —
`--no-telemetry` and `HEADROOM_TELEMETRY=off` still work, so existing
opt-out configs are unaffected.
- No tracking issue, so `Closes #` is left N/A.
|
||
|
|
b9d36db7ea | docs(proxy): document Anthropic API URL overrides | ||
|
|
b1d1f8cd66 | docs(proxy): document ANTHROPIC_TARGET_API_URL | ||
|
|
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. |
||
|
|
c07c72de3c |
docs: surface code-aware proxy flags
Document the proxy-side code-aware flags so the CLI reference matches the current wrapper and server behavior. The wrapper now exposes the positive flag, and the server docs should show both enable/disable forms with the shared env var defaulting behavior. Assisted-by: Sisyphus:openai/gpt-5.4-mini Signed-off-by: Manorit Chawdhry <m-chawdhry@ti.com> |
||
|
|
ea0f024b67 | Compact /stats-history responses by default | ||
|
|
1192f657eb |
docs: document HEADROOM_CONFIG_DIR / HEADROOM_WORKSPACE_DIR filesystem contract
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
|
911eb85a44 | new docs UI + ts doc coverage |