mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
feat/https-compose-caddy
174
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
a385ea8e60 |
fix(benchmarks): drop the duplicate protect_recent=0 table from the proof harness (#4754)
## Description `benchmarks/index_proof_table.py` printed two tables, "default (protect_recent=4)" and "full corpus (protect_recent=0)". The committed `benchmarks/results/index_proof_table.txt` showed them identical in every row and in the total, so the second run and its label carried no information — and the comment above them claimed the default "shields almost every tool result", which the output contradicts. They cannot ever differ. `ContentRouter` applies `protect_recent` only to content detected as `SOURCE_CODE`: ```python is_code = detection.content_type == ContentType.SOURCE_CODE if protect_recent > 0 and messages_from_end <= protect_recent and is_code: ``` Every scenario in this harness is a JSON tool payload. All ten payloads detect as `JSON_ARRAY` under **both** backends (pure-Python and `HEADROOM_DETECT_BACKEND=rust`), so the guard never fires at any `protect_recent` value. This is not a stale committed artifact that a rerun would fix. Of the three options on the issue, this takes the first: one table with the limitation stated, rather than a duplicate or a behavior change to the compressor. Closes #4732 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] Documentation update ## Changes Made - `benchmarks/index_proof_table.py`: print one table (the default config) and replace the misleading comment with the actual reason the `protect_recent` comparison is a no-op for JSON payloads. - `benchmarks/results/index_proof_table.txt`: regenerated. The table body is unchanged; the duplicate second table is gone. - `tests/test_index_proof_table.py`: new output-level tests asserting the harness prints exactly one table and that the docs Markdown block states the config it was measured under. Both fail on the base revision and pass with this change. - `tests/test_transforms_content_router.py`: new `test_protect_recent_does_not_shield_non_code_tool_payloads` pins the router reason the two tables could never differ. - `headroom/compress.py`: `CompressConfig.protect_recent` docstring said "Don't compress the last N messages"; it guards recent **code** only. - `docs/content/docs/context-management.mdx`, `docs/content/docs/proxy.mdx`, `docs/content/docs/index.mdx`, `README.md`: same overstatement corrected. The published table now names the configuration it was measured under. ## 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 $ uv run pytest tests/test_index_proof_table.py tests/test_transforms_content_router.py -q 109 passed, 1 warning in 14.83s $ uv run ruff check benchmarks/index_proof_table.py headroom/compress.py \ tests/test_index_proof_table.py tests/test_transforms_content_router.py All checks passed! $ uv run ruff format --check tests/test_index_proof_table.py 1 file already formatted ``` Base-revision check for the new output tests (harness restored to `318e8e08`): ```text $ uv run pytest tests/test_index_proof_table.py -q FAILED tests/test_index_proof_table.py::test_proof_table_prints_exactly_one_table FAILED tests/test_index_proof_table.py::test_proof_markdown_block_is_the_default_config 2 failed in 5.15s ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.13.11, `uv` venv at the branch head `9b7e2f95` (rebased onto `acb58a0c`); content detection ran on the pure-Python backend (no ONNX Runtime 1.24+), and every payload was re-checked under `HEADROOM_DETECT_BACKEND=rust`. - Exact command / steps: `uv run python benchmarks/index_proof_table.py` on the base revision, then the same command on this branch, then `git diff` against the committed `benchmarks/results/index_proof_table.txt`. - Observed result: base revision printed two tables identical in all four rows and in the total (178,024 → 104,261, 41%). This branch prints one table with the same numbers, and its output matches the committed result file byte for byte once the first line is excluded (that line names whichever detector backend the host has). - Not tested: whether the committed numbers would change under the native detector — also left open on the issue. They do not: both backends classify all ten payloads as `JSON_ARRAY`, so detection routes them identically. ## Runtime Rollout Safety - Rollout-managed feature(s): none. Only a benchmark script, its committed output, tests, and docs change. - Minimum rollout channel: stable, no gating. - Stable/default behavior changed: no. `ContentRouter`, `CompressConfig`, and `compress()` behavior are untouched; only a docstring and documentation prose changed. The published table's numbers are identical to before. - Kill switch / disable path: not applicable. `benchmarks/index_proof_table.py` is a manual, offline script with no runtime surface. - Unsafe override required: no. - Qualification impact: none. Serialization, caching, and compression output are unchanged; the new tests are offline and stubbed. - Rollback path: revert this commit. The harness returns to printing the duplicate table; no state or migration is 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 - [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 `mypy headroom` left unchecked: the touched Python files add no type surface beyond a benchmark script and a test module, and mypy was not run locally. Review feedback addressed: the initial version of this PR added only a router-level test, which passes on the base revision and so could not catch the duplicate table returning. The two output-level tests in `tests/test_index_proof_table.py` replace that gap, and the base-revision failure above is their proof. The `context-management.mdx` file-read claim was also too broad — read protection releases confidently non-code data (JSON, CSV/tabular, build/test logs, git diffs, HTML, search output), so the wording now says so. `CHANGELOG.md` is untouched, per CONTRIBUTING. The branch was rebased onto `acb58a0c` (4 upstream commits: #4727, #4728, #4735, #4743) with no file overlap. Re-verified after the rebase: 109 focused tests pass, `ruff check`/`format --check` clean. `benchmarks/index_proof_table.py` is byte-identical between `318e8e08` and `acb58a0c`, so the base-revision failure above still applies unchanged. |
||
|
|
2649835a51 |
feat(wrap): make the Serena code-memory MCP opt-in (#4509)
## What changes `headroom wrap claude|codex|grok|opencode` no longer registers Serena by default. | | Before | After | |---|---|---| | Default | Serena registered | No code-memory MCP | | Opt in | (default) | `--code-memory serena` or `HEADROOM_CODE_MEMORY=serena` (deprecated `--serena` still works) | | Opt out | `--code-memory none` / `--no-serena` | Still accepted | | Upgrading user, Serena installed by Headroom | Kept | Removed on next wrap, with the message "Serena is now off by default; pass --code-memory serena to keep it" | | Upgrading user, Serena added by hand | Kept | Kept, no message (shown only with `--verbose` or an explicit opt-out) | OpenCode now accepts `--code-memory` and uses the same setup path as the other agents. Its `--no-serena` flag is hidden and deprecated. ## Why Measured on 2026-10-27, Serena started exactly as `wrap` registers it: - It adds 22 tools, about 5.9K tokens of tool definitions on every request where tools aren't deferred. Its server instruction tells the model to call `initial_instructions`, which costs another 2K tokens. - Each launch takes about 6 s cold via `uvx`, plus a background `serena project index` that starts language servers. It also writes a `.serena/` folder into the user's repo. - Serena was registered in 6 of our own Claude Code sessions and called 0 times. Separately, an offline replay of about 108K tool calls found that symbol-level reads have little to recover for Claude Code. ## Not in this PR - `headroom.integrations.strands` still defaults `enable_serena_mcp=True`. It's public integration API, so it needs a deprecation step instead of a silent flip. - The opt-in `--serena-instructions` block in CLAUDE.md/AGENTS.md is never removed, by unwrap or anything else. Users who opted into it keep instructions that point at tools no longer registered. This predates this PR and will be fixed separately. - For Claude Code, Serena entries are per project, so removal happens the next time `wrap` or `unwrap` runs in each project. The docs say so. ## Tests - `pytest tests/test_wrap_code_memory.py tests/test_cli tests/test_mcp_registry`: 1368 passed. 5 failed, and those 5 fail the same way on `main` in my local venv: `test_mcp_reconcile.py::test_ordinary_install_does_not_adopt_serena` and 4 in `test_wrap_persistent.py`, all from an environment/install mismatch. - New tests: - The default wrap removes a Serena entry Headroom installed and prints how to keep it. - The default wrap leaves a hand-added Serena alone and prints nothing. - `--serena --no-serena` resolves to none. - `wrap opencode --code-memory serena` registers Serena with the `agent` context. - `ruff check`, `ruff format --check` and `mypy` are clean on the changed files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Real Behavior Proof - **Environment:** macOS (Darwin 27.2), Python 3.12.13, Claude Code 2.1.318, real `claude` CLI doing every `claude mcp add`/`remove`. A temporary `HOME`, so `~/.claude.json` starts empty, and a fresh git repo per case. - **Builds:** "before" = `main` at `12864fc8`; "after" = this PR at `56557dc9`. - **Command:** `headroom wrap claude --no-proxy [flags] -- --version`. Wrap does its full MCP setup, then launches Claude Code, which prints its version and exits, so no model call is made. `state` is read from `~/.claude.json` (user scope and this project's local scope) and the project's `.mcp.json` after each run. ``` == 1. Upgrade: Serena installed by Headroom (project/local scope) $ headroom wrap claude --no-proxy -- --version (cwd=projA, build=12864fc8) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| scoped to this project — pass --code-memory-scope user to register it for every Claude Code session wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projA): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projA, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projA): - | .mcp.json: - == 2. Upgrade: Serena added by hand (claude mcp add) state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projB, build=56557dc9) exit=0 wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy --code-memory none -- --version (cwd=projB, build=56557dc9) exit=0 wrap| Serena MCP is present but user-managed — leaving it in place (Headroom only removes entries it installed) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: - == 3. Explicit opt-in, then rollback to the default $ headroom wrap claude --no-proxy --code-memory serena -- --version (cwd=projC, build=56557dc9) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| scoped to this project — pass --code-memory-scope user to register it for every Claude Code session wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projC, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): - | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projC, build=56557dc9) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| scoped to this project — pass --code-memory-scope user to register it for every Claude Code session wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy --serena -- --version (cwd=projC, build=56557dc9) exit=0 wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: - == 4. User scope: installed by Headroom with --code-memory-scope user $ headroom wrap claude --no-proxy --code-memory-scope user -- --version (cwd=projD, build=12864fc8) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| registered for every Claude Code session on this machine (--code-memory-scope user) wrap| 2.1.318 (Claude Code) state| user: ['headroom', 'serena'] | local(projD): - | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projD, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projD): - | .mcp.json: - == 5. User scope opt-in on the PR build $ headroom wrap claude --no-proxy --code-memory serena --code-memory-scope user -- --version (cwd=projE, build=56557dc9) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| registered for every Claude Code session on this machine (--code-memory-scope user) wrap| 2.1.318 (Claude Code) state| user: ['headroom', 'serena'] | local(projE): - | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projE, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projE): - | .mcp.json: - ``` What this shows: 1. A Serena entry Headroom installed on `main` is removed on the first wrap after upgrading, with the "off by default" message. This holds for both scopes (cases 1 and 4). 2. A hand-added Serena entry is kept, and the default wrap prints nothing. `--code-memory none` keeps it and says it's user-managed (case 2). 3. Opting in works with `--code-memory serena`, `HEADROOM_CODE_MEMORY=serena` and the deprecated `--serena`, at project scope and user scope (cases 3 and 5). Running the default afterwards rolls it back. 4. Project scope here means Claude Code's `local` scope, which is where wrap registers. Wrap never writes `.mcp.json`. Not tested live: `wrap codex|grok|opencode` (unit tests only), Windows, and an interactive Claude session that calls Serena tools. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4509" 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 qualification Published `983b6bb15119a3ecb8f6e20bf014b8bed123e95d` includes upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 19 selector/Serena tests pass,1optional skip; Ruff/format/diff pass. Clean main sync; contributor selector/ownership code unchanged. Existing real upgrade/configuration/launch proof requirement remains; jCodeMunch proposal is unrelated to this source delta. Contributor correctness logic was not rewritten. Existing Changes Requested decision retained without duplicate findings. Scoped Windows validation uses the existing development native extension, not a fresh build. Hosted qualification is handled by maintainers; nothing merged. ### Maintainer current-main requalification Exact head `e8e3011187a2ffdfbb6c9932db26b22ec911ab39`, upstream main `ecbaf86d78cf52d185fbffa306157b9a4cc1b906`. Mechanically updated from upstream/main |
||
|
|
bb8d18a56a |
feat(wrap): add headroom wrap droid for Factory Droid (#4143)
## Description Add `headroom wrap droid` so Factory subscription traffic, including Droid Core, can be compressed on the existing Factory plan. Droid ignores `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` for Factory-served models. It honors `FACTORY_API_BASE_URL`. This wrapper points that at the local proxy and gives the proxy a Factory upstream (`--factory-api-url` / `FACTORY_TARGET_API_URL`, default `https://api.factory.ai`). With a Factory upstream configured the proxy registers: - `POST /api/llm/a/v1/messages` — compressed with the existing Anthropic pipeline and forwarded to `{factory}/api/llm/a/v1/messages`. A client-sent `x-headroom-base-url` is ignored. `x-headroom-*` headers are stripped. Operator Anthropic extra headers are withheld from the untrusted Factory host. - Every other `/api/*` path — forwarded verbatim to Factory, except Hermes Studio's scoped prefixes and requests that name their own `x-headroom-base-url`. Nothing outside `/api/` is sent to Factory. `select_passthrough_base_url` and `upstream_trust` are untouched, so a leftover Codex, Claude, or Copilot config pointed at a Factory-mode proxy keeps its own upstream and credentials. That is the deliberate difference from https://github.com/headroomlabs-ai/headroom/pull/2352, which is still open and which this does not close. #2352 sends every unrouted request on a Factory-mode proxy to Factory. `wrap droid` writes no Droid config. It threads `factory_api_url` through the existing proxy-reuse logic. With `--no-proxy` it refuses unless `/health` shows a Headroom proxy serving the same Factory upstream. OpenAI-shaped `/api/llm/o/*` traffic is forwarded uncompressed. Those routes are deferred. This commit is `74c889fb` rebased onto current `main` (`0dd8e0b5`). The only conflicts were `docs/content/docs/meta.json` (kept both the new `hermes` page and `droid`) and the `--no-proxy` branch in `headroom/cli/wrap.py` (kept upstream's OpenAI upstream check and the Factory check). Refs #2351 ## 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 wrap droid` sets `FACTORY_API_BASE_URL` to the local proxy and resolves the Factory upstream from `--factory-api-url`, then `FACTORY_API_BASE_URL`, then `https://api.factory.ai`. Loopback, credential, query, and fragment URLs are rejected. - Factory inference and `/api/*` passthrough routes are registered only when a Factory upstream is configured. The default proxy is unchanged. - `/health` reports `factory_api_url`. - Docs: `docs/content/docs/droid.mdx`. ## 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 Rebased tree `/home/hermes/workspace/headroom-rebase` at `0dd8e0b5`, importing that tree via `PYTHONPATH` and the existing venv at `/home/hermes/workspace/headroom/.venv` (Python 3.11.16). ```text tests/test_cli/test_wrap_droid.py ............................ [ 31%] tests/test_provider_droid_runtime.py ................................ [ 66%] ``` 60 passed. Those are the wrap launch-env tests and the Factory runtime tests. `tests/test_proxy/test_factory_decoy_proof.py` did not complete in this worktree. The proxy refuses to start because `headroom._core` is not built here (`ModuleNotFoundError`, exit 78). Setting `HEADROOM_REQUIRE_RUST_CORE=false` still did not finish within 180s. The decoy proof (decoy upstream stays silent, Factory stand-in receives the inference request, spoofed `x-headroom-*` headers, REST passthrough, `--no-proxy` refusals) was written for this change and passed in the pre-rebase review session. It was not re-run to a green result after this rebase. `ruff` and `mypy` were not re-run after the rebase. ## Real Behavior Proof - Environment: Linux, Python 3.11.16, rebased commit `0dd8e0b5` on top of `upstream/main` `8c1beb20`. No Factory token. No call to `api.factory.ai`. - Exact command / steps: `PYTHONPATH=/home/hermes/workspace/headroom-rebase /home/hermes/workspace/headroom/.venv/bin/python -m pytest tests/test_cli/test_wrap_droid.py tests/test_provider_droid_runtime.py` - Observed result: 60 passed. - Not tested: a live Factory subscription, `droid` itself, the socket decoy proof on this rebased commit (blocked locally by the missing Rust extension), `ruff`, `mypy`, and CI on GitHub. ## Runtime Rollout Safety - Rollout-managed feature(s): none. Factory routes register only when `factory_api_url` / `--factory-api-url` is set. - Minimum rollout channel: stable. Default proxy behavior is unchanged. - Stable/default behavior changed: no, unless a Factory upstream is configured. - Kill switch / disable path: do not pass `--factory-api-url` and do not set `FACTORY_TARGET_API_URL`. `wrap droid` is opt-in. - Unsafe override required: no. - Qualification impact: none on the default proxy. - Rollback path: revert this commit. No config is written into Droid. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review The pre-rebase commit `74c889fb` was approved by a fresh Claude Opus 5.5 high review with an empty blocking list. This commit is that change rebased onto current main. The two conflict resolutions are described above and have not had a second Opus pass. ## 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 - [ ] 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 Does not close #2352. That PR is the prior attempt. This one is a current-main rebuild with the catch-all leak removed: only `/api/*` is forwarded to Factory. akbarkanso is not a Headroom maintainer. Please do not expect this account to merge. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4143" 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 `e28dfe6422dfcb9b2cbd5ce0fe673196d3b6ad40`, upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. Updated against upstream/main |
||
|
|
a8905214d9 |
fix(packaging)!: keep PyTorch extras out of all (#4067)
<!-- maintainer-current-main -->
## Maintainer latest-main checkpoint
Published `fb146c0663b30488da0a49cfb33624ee82862074` contains current
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 22
dependency/Gemini tests and lock check 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
On Linux, installing `headroom-ai[all]` resolved PyTorch and NVIDIA CUDA
packages even for users who only needed the CLI/proxy profile. The
locked dependency graph included those packages through `ml`, `memory`,
`evals`, and `voice`.
This keeps those PyTorch-backed extras available for explicit
installation while removing them from `[all]`. Image support and the
other CLI/proxy dependencies remain included; dependency metadata cannot
detect installed GPU hardware.
Closes #3339
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- Remove `ml`, `memory`, `evals`, and `voice` from the `[all]` extra
while keeping each separately installable.
- Retain `image` and the other default CLI/proxy capabilities.
- Update README and installation docs to describe the opt-in extras and
CUDA package implications.
- Add a dependency contract assertion for the `[all]` extra.
## 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
Focused dependency contract tests: 3 passed, 5 deselected.
Python 3.13 locked `uv export` exited 0; the fixed export omits torch, CUDA, NVIDIA, sentence-transformers, and datasets. The baseline export contained them.
`uv lock --check`, scoped Ruff check/format, and `git diff --check` exited 0.
The broader dependency test module had 3 passed and 5 import failures because `opentelemetry` is absent from the local environment.
```
## Real Behavior Proof
- Environment: Linux, Python 3.13, locked uv dependency resolution.
- Exact command / steps: `UV_PYTHON_DOWNLOADS=never uv export --python
3.13 --extra all --no-dev --locked --no-hashes --no-emit-project`.
- Observed result: exit 0; the resolved export no longer contains torch,
CUDA, NVIDIA, sentence-transformers, or datasets, all of which were
present in the baseline export.
- Not tested: a full environment install and GPU runtime behavior.
## Runtime Rollout Safety
- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable package release.
- Stable/default behavior changed: Yes; `[all]` no longer installs the
four PyTorch-backed extras.
- Kill switch / disable path: Not applicable; install the desired extras
explicitly.
- Unsafe override required: No.
- Qualification impact: Users of those capabilities must add the
corresponding extras.
- Rollback path: Restore the extras to `[all]` and regenerate `uv.lock`.
## 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 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)
## Screenshots (if applicable)
Not applicable to this dependency-resolution change.
## Additional Notes
The `[all]` install profile intentionally no longer includes
PyTorch-backed optional capabilities; each remains available through its
named extra. The focused regression and locked resolver proof passed,
but the full dependency test module and a full install were not verified
locally.
## Maintainer integration qualification
Published head `3229690b613810d496f015cedd086ca1d7421843` includes
current upstream main `31dcaf41`. The merge preserves main's `lean`
dependency profile and deprecated `sandbox` alias alongside the
contributor's opt-in `[all]` policy. No optional-feature runtime logic
was changed.
- Reconciled the existing macOS dependency test with the declared
policy, retaining the transitive exclusion check and independently
verifying explicit `ml`/`voice` opt-ins on Intel macOS and Linux. All 12
tests across `tests/test_onnx_dependency_contract.py` and
`tests/test_optional_dependencies.py` pass on Windows/Python 3.12.13.
- Evaluation workflow installs now explicitly request `evals`, and the
model-allowed weekly job also requests `ml`, preserving its previous
intended dependencies. The evaluation guide and AI install index
identify those opt-ins. These address the existing Devin workflow/docs
findings.
- `uv lock --check`, touched Python Ruff/format and whitespace checks
pass. All 253 locked package versions are unchanged; only the root
`[all]` dependency metadata/flattened list changes.
- Real resolver commands from this checkout: `uv export --extra all
--no-dev --locked --no-hashes --no-emit-project` and `uv export --extra
all --extra ml --extra voice --extra evals --no-dev --locked --no-hashes
--no-emit-project`. Evaluating their actual requirement markers for
Python 3.12/3.13/3.14 on Linux x86_64, Windows AMD64, macOS arm64 and
macOS x86_64 shows `[all]` excludes torch, sentence-transformers,
datasets and CUDA/NVIDIA packages in all 12 environments. Explicit
opt-ins retain datasets and torch where supported; Intel macOS still
excludes torch.
- Not tested: a fresh full environment install, GPU runtime, live paid
evaluations or a fresh native build. Hosted CI must qualify the
published final head separately.
### Maintainer current-main requalification
Exact head `f1ed1e0019037e7b53ff9ef548843449c3c7a16f`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.
Current-main integration against upstream
|
||
|
|
abed065ed3 |
docs(readme): lead with two front doors and one measured savings claim (#4530)
## Description The README told the app developer, and any agent working in a sandbox, to leave: "good fit if you run coding agents daily", "skip it if you work in a sandbox where local processes can't run". The library needs no local process. In our unbranded sandbox run (Claude Code, "compress tool outputs and chat history before each LLM call") the agent wrote a 300-line trimmer by hand; the three chat engines given the same job recommended tiktoken plus custom code, one saying it was "deliberately not using LLMLingua or similar, they pull in torch". Depends on #4529 for the `/docs/fastapi` link. ## Type of Change - [x] Documentation update ## Changes Made - "Start here" block under the first paragraph: **My app calls an LLM** (`pip install headroom-ai`, `compress()`, no key, no network) first, **I run coding agents** (`headroom wrap`) second. - First paragraph names the install name next to the brand and states the savings claim once, from the Proof table (21–57% on four agent scenarios, 90%+ on repeated JSON and logs, little on prose). - "When to use · when to skip" rewritten from the app developer's view; the sandbox sentence is gone. - Job-word headings: "Proof: measured token savings", "Reduce input tokens in your own app". - Every relative link and image path replaced with an absolute GitHub URL. Mirrors (SourceForge, gitee, instagit scrapes) copy the README verbatim and currently show broken images and a dead `llms.txt` link. ## Testing - [x] Manual testing performed ### Test Output ```text relative refs: none missing anchors: none Start-here snippet on the log example (published 0.42.0 wheel): 20031 -> 95 ``` ## Real Behavior Proof - Environment: the edited file, checked with a small Python script. - Exact command / steps: collect every `](...)`, `src=` and `href=` target; flag any that is not `https://`, `#` or `mailto:`; check every in-page `#anchor` against the GitHub slug of each heading. - Observed result: `relative refs: none`, `missing anchors: none`. The Python snippet in "Start here" was run against the published 0.42.0 wheel: `20031 -> 95` on the 3,000-line log example. - Not tested: rendering on PyPI (a separate PyPI README is in #4534). ## Runtime Rollout Safety - Rollout-managed feature(s): none; documentation and metadata only, no runtime code path changes - Minimum rollout channel: n/a - Stable/default behavior changed: no - Kill switch / disable path: n/a (revert the PR) - Unsafe override required: no - Qualification impact: none - Rollback path: revert the commit ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Additional Notes On the absolute links: the PyPI page gets its own README in #4534, but SourceForge, gitee and instagit mirrors copy this file verbatim and today show broken images and a dead `llms.txt` link, and the "headroom python" query ranks those copies above the docs. Pinning to `main` means a tag or fork renders `main`'s assets; for images and a license that is the intended behaviour. The GitHub repo "About" text still says "20% fewer tokens for coding agents, 60-95% fewer tokens for JSON". Suggested replacement, outside the repo: `gh repo edit headroomlabs-ai/headroom --description "Headroom (headroom-ai): compress tool outputs, logs, JSON and chat history before each LLM call. Fewer input tokens, same answers. Library (no API key), proxy, MCP server."` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
fae1e849cb |
fix(wrap): route OMP OpenAI providers through Headroom (#2755)
## Description `headroom wrap omp` advertised OMP support but only redirected OMP's `anthropic` provider. OMP models under `openai` and `openai-codex`—including the current `openai-codex/gpt-5.6-sol` model—kept their native endpoints and bypassed Headroom. This change adds reversible `models.yml` base URL overrides for both OpenAI provider IDs while preserving the existing Anthropic route, provider credentials/headers, custom models, byte-for-byte backup, and `headroom unwrap omp` behavior. Follow-up to #1811. ## 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 - Route `providers.openai.baseUrl` through the project-prefixed Headroom `/v1` endpoint. - Route `providers.openai-codex.baseUrl` through the same endpoint; OMP appends `/codex/responses`, which Headroom already supports for HTTP and WebSocket traffic. - Preserve all existing provider fields and the established backup/reinject/unwrap contract. - Show all three managed provider routes at launch and document the expanded OMP support. - Extend the existing OMP wrap tests for fresh injection, user-config preservation, reinjection, and CLI display. ## 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 --extra dev pytest -q tests/test_cli/test_wrap_omp.py 15 passed in 0.31s $ uv run --extra dev ruff check . All checks passed! $ uv run --extra dev ruff format --check . 1343 files already formatted $ uv run --extra dev mypy headroom Success: no issues found in 511 source files ``` The full pytest suite was started but not completed: after roughly 17 minutes it was still running unrelated Codex unwrap tests that repeatedly install/index Serena. No failure was observed before cancellation; the affected OMP suite is green. ## Real Behavior Proof - Environment: macOS Darwin 25.4 arm64 (Apple M5 Pro), Python 3.13.13, CLI code from this branch, published Headroom 0.33.0 proxy on port 8787, OMP 17.2.7, `openai-codex/gpt-5.6-sol` with stored ChatGPT/Codex OAuth. - Exact command / steps: Run the command below against the existing proxy, then inspect `/stats` and the managed `models.yml`. 1. Start or reuse the local proxy on `127.0.0.1:8787`. 2. Run: ```bash headroom wrap omp --no-proxy -- -p "Reply with exactly: HEADROOM_OMP_CODEX_OK" \ --model openai-codex/gpt-5.6-sol --no-session --no-tools \ --no-extensions --no-skills --no-rules --thinking off --max-time 30s ``` 3. Inspect `/stats` and the managed `~/.omp/agent/models.yml`. - Observed result: OMP returned the expected sentinel, Headroom recorded one new project request, and all three provider overrides were present. - Wrap printed all three routes: ```text providers.anthropic.baseUrl=http://127.0.0.1:8787/p/headroom providers.openai.baseUrl=http://127.0.0.1:8787/p/headroom/v1 providers.openai-codex.baseUrl=http://127.0.0.1:8787/p/headroom/v1 ``` - OMP returned exactly `HEADROOM_OMP_CODEX_OK`. - Headroom `/stats` recorded the new request under project `headroom` (`requests` increased from 2 to 3; `last_activity_at=2026-08-04T02:14:07Z`). - The managed `models.yml` contained all three overrides; the pristine backup remained the restore source. - The running 0.33.0 proxy does not contain the project-prefixed WebSocket fix from #2379, so this proves fallback-capable request completion rather than a clean WebSocket upgrade. - Not tested: a clean project-prefixed WebSocket upgrade against a release containing #2379; live `openai` API-key request; Windows/Linux; a long interactive or explicitly isolated WebSocket session; completion of the full unrelated pytest suite. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review An independent review pass found no correctness or security findings (confidence 0.96). ## 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 - [ ] New and existing unit tests pass locally with my changes — affected tests pass; full suite did not finish as documented above - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title ## Screenshots (if applicable) N/A — terminal evidence is included above. ## Additional Notes Release prerequisite: Headroom 0.33.0 has a `/p/<project>` WebSocket upgrade bug that returns 403 before routing. It was independently fixed and merged in #2379 (`789a4f3060aa33a5bae82680968c3e367fa2db83`). This PR builds on `main`, which already contains that fix; stable interactive OMP WebSocket routing requires a release/backport containing #2379. The OpenAI API-key provider and ChatGPT/Codex OAuth provider intentionally share the local `/v1` base URL. Headroom distinguishes PAYG API keys from Codex OAuth JWT/account headers and forwards each request to the correct upstream. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2755" 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: Jerrett Davis <mxjerrett@gmail.com> |
||
|
|
4d34680c34 |
fix: Add info about apply to README.md (#1592)
## Description Added into to README about apply command and why it's 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Added into to README about apply command ## 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 - [x] Manual testing performed ### Test Output ```text git diff --check: passed Documentation-only diff: 6 lines ``` ## Real Behavior Proof - Environment: current README and persistent-install documentation on the latest PR head. - Exact command / steps: compared the revised quickstart note with current wrap/deploy/install behavior and ran `git diff --check`. - Observed result: the note now distinguishes session-scoped wrap, turnkey persistent deploy, and lower-level install apply without claiming wrap writes durable config. - Not tested: rendered documentation site or a live persistent installation. ## 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 ## Additional Notes Related to discussion on linkedin. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/1592" 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: JD Davis <jd@jds-macbook-air.tail2a279.ts.net> Co-authored-by: Jerrett Davis <mxjerrett@gmail.com> |
||
|
|
4288fbd903 |
docs(teams): replace the 3-months-free perk with a talk-to-us pitch (#4524)
## Description Removes the "3 months free with a 12-month plan" offer and every headroom-perks.vercel.app link. Each place now says: not seeing the savings you want? Headroom OSS is a framework built to show what's possible, so it saves less; Headroom Enterprise saves more and adds more cost savings, tokens secured, on premise deployment, deep attribution and many more features. Teams and enterprises: talk to us at hello@headroomlabs.ai or https://headroomlabs.ai. ## 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 - README banner (`.github/assets/enterprise-perk.svg`): redrawn simple, in the `hero.svg` type scale (title 42/700, lead 14.5, eyebrow 10.5); no animation or chips. - README "Headroom for teams" section and docs Teams page: the OSS-vs-Enterprise table is replaced by the pitch, feature list and contact. - Docs site banner (`docs/app/layout.tsx`): new copy and link; new banner id so people who dismissed the old one see it. - Local dashboard offer (unlicensed installs only): new copy and link; new localStorage dismissal key (`headroom-teams-contact-dismissed`) so people who dismissed the old offer see the new one. - Release-notes footer (`release.yml`) and `llms.txt`: same pitch, email and site. - `tests/test_dashboard_teams_perk.py`: asserts the contact email instead of the perks URL. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) (no Python source changed) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest -q tests/test_dashboard_teams_perk.py -k "not route" 4 passed, 4 deselected in 0.49s $ ruff check headroom/dashboard tests/test_dashboard_teams_perk.py All checks passed! ``` The 4 `/dashboard` route tests fail locally with `CancelledError` at proxy startup; they fail the same way on unmodified `main` in the same venv, so CI is the judge for those. ## Real Behavior Proof - Environment: macOS, Python venv of this repo, headless Chrome. - Exact command / steps: rendered `get_dashboard_html(licensed=False/True)` and checked the offer block; rendered the banner with `Google Chrome --headless=new --screenshot --window-size=900,220 file://.github/assets/enterprise-perk.svg`; `grep -rn "headroom-perks\|3 months"` over README, docs, llms.txt, headroom/ and .github/. - Observed result: unlicensed: offer shown, contact email present, no perks link, new dismissal key. Licensed: offer removed. Banner renders cleanly within 880×200 with text in the hero font. The grep finds nothing. - Not tested: the docs site build (`docs/`) and the release-notes footer step (runs only on release). ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: only the text and link of the dashboard offer on unlicensed installs - Kill switch / disable path: setting `HEADROOM_LICENSE` removes the offer, as before - 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 - [ ] 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 - [ ] 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 No test was added for the new dismissal key: it is browser localStorage read by Alpine, which the Python tests do not run. Past release notes still carry the old footer; editing them is a separate one-off. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
3c6f82b060 |
deps: require Python 3.11; clear Dependabot alerts in the 3.10 lock fork (#4517)
## Description Vanta/Dependabot report 64 open alerts on this repo. 59 of them are pillow, filelock and virtualenv versions that exist only in the Python 3.10 split of `uv.lock`: the patched releases (pillow 13, filelock 4.2) require Python 3.11, so Dependabot could not open a fix PR. Python 3.10 reached end of life in October 2026 and CI already tests only 3.11, 3.12 and 3.14. The second commit also fixes the two `security.yml` jobs that fail on `main` today: pip-audit (litellm CVE-2026-114612) and the e2e npm audit (three undici advisories published after #4453 for the copy bundled inside npm). ## Type of Change - [x] Breaking change: `pip install headroom-ai` now refuses Python 3.10 - [x] Bug fix: security patches ## Changes Made - `requires-python = ">=3.11"`; drop the 3.10 classifier and the `tomli` backport dependency - pillow override and filelock floor lose their `python_version` markers - mypy `python_version = "3.11"`; the three `tomli` import fallbacks in `headroom/` become plain `import tomllib` - ruff `target-version` stays `py310` with a note: moving it raises 213 pyupgrade findings (UP017/UP036/UP041/UP042), a separate mechanical PR - `uv.lock` re-resolved: pillow 13.0.0, filelock 4.2.4, virtualenv 21.14.13 (single entry each, the 3.10 fork is gone) - gitpython 3.1.62 → 3.2.1, strands-agents 1.24.0 → 1.62.0, litellm 1.101.0 → 1.101.3 - `e2e/wrap/tools/npm-audit-exceptions.json`: three further undici 6.x advisories added at the existing exact path and version, expiry unchanged (2026-11-15) - README, CONTRIBUTING and the Dockerfile comment updated Clears 61 of the 64 Dependabot alerts. The remaining 3 (undici, ip-address) live inside the bundled dependencies of the `npm` package in `e2e/wrap/tools/package-lock.json`; npm 12.2.1 is the newest release and still ships them, so there is no bump available yet. ## Dependencies & supply chain **gitpython 3.1.62 → 3.2.1.** Already a dependency; bumped for a security patch (CVE-2026-114145). Maintained by the gitpython-developers org (Sebastian Thiel), monthly-ish releases, long advisory history with prompt fixes. Install surface unchanged: pure-Python wheel (`py3-none-any`), one runtime dependency (`gitdb`), no native code, no install-time or runtime network of its own. **strands-agents 1.24.0 → 1.62.0.** Already a dependency behind the `[strands]` extra; bumped for a security patch (CVE-2026-115419, fixed in 1.43.0; the lock takes the current release). Maintained by AWS (strands-agents org, `opensource@amazon.com`), weekly releases. Install surface: pure-Python wheel, no native code. Declared dependencies grow by two, `httpx` and `pyyaml`, both already in the lock for other packages, so no new transitive packages are introduced. Runtime network is unchanged: it calls the model provider the user configures, as before. **litellm 1.101.0 → 1.101.3.** Already a core dependency; patch bump for CVE-2026-114612, the smallest fix that keeps the `filelock>=4.2.1` floor resolvable (litellm 1.106 caps filelock <4). No change to maintainers or install surface. **pillow, filelock, virtualenv.** No new packages; the lock now holds the single patched version the 3.11+ fork already had. ## Testing - [x] Linting passes (`ruff check .`, `ruff format --check .`) - [x] Type checking passes (`mypy headroom`): 1 error, identical to main (`langchain/chat_model.py:380`) - [x] Unit tests (targeted, see below) ### Test Output ```text $ pytest -q tests/test_litellm_optional.py tests/test_dependency_overrides.py tests/test_release_workflows.py tests/test_image_decoder_guard.py tests/test_optional_dependencies.py tests/test_onnx_dependency_contract.py 74 passed in 3.07s $ grep -rl -E "headroom\.release_version|headroom\.providers\.codex\.project_context|headroom\.cli\.wrap" tests | xargs pytest -q 4 failed, 1043 passed in 28.03s # same 4 in tests/test_cli/test_wrap_persistent.py fail on main $ uv run --extra strands --extra dev -m pytest -q tests/integrations/test_strands tests/test_strands_tokenizer.py 18 failed, 87 passed in 52.30s # the 18 are *Real classes needing live AWS Bedrock creds; main fails the same 18 on 1.24.0 $ uv export --frozen --no-dev --no-emit-project --no-hashes --extra all --format requirements-txt > requirements-prod.txt $ uvx pip-audit==2.10.1 -r requirements-prod.txt --no-deps --disable-pip No known vulnerabilities found $ cd e2e/wrap/tools && npm audit --package-lock-only --json > audit.json && <security.yml check script> unexpected: [] stale: [] seen: 6 ``` ## Real Behavior Proof - Environment: macOS 27.2 arm64; uv-managed CPython 3.11.16 and 3.10; the lock from this branch. - Exact command / steps: ```text $ uv run --python 3.11 --all-extras python -c "import sys, platform, headroom, PIL, filelock, virtualenv, git, strands, litellm, importlib.metadata as m; ..." $ uv venv -p 3.10 /tmp/py310-venv && uv pip install --python /tmp/py310-venv/bin/python --dry-run . ``` - Observed result: ```text macOS-27.2-arm64-arm-64bit python 3.11.16 pillow 13.0.0 filelock 4.2.4 virtualenv 21.14.13 gitpython 3.2.1 strands-agents 1.62.0 litellm 1.101.3 (3.10) ... headroom-ai==0.42.0 depends on Python>=3.11, we can conclude that headroom-ai==0.42.0 cannot be used. And because only headroom-ai==0.42.0 is available and you require headroom-ai, we can conclude that your requirements are unsatisfiable. ``` - Not tested: Linux and Windows installs (CI wheel matrix covers them); a live Bedrock run of the strands integration; the Docker image build. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: installs on Python 3.10 are refused at resolve time; no runtime behavior change on 3.11+ - Kill switch / disable path: n/a - Unsafe override required: no - Qualification impact: none - Rollback path: revert the 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 made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] New and existing unit tests pass locally with my changes (targeted runs above; pre-existing failures noted) - [x] I did **not** edit `CHANGELOG.md` - [ ] New tests added: n/a, dependency and metadata change; existing contract tests cover the floor and the pillow override ## Additional Notes Follow-ups, not in this PR: - ruff `target-version = "py311"` plus the pyupgrade fixes - remaining `tomli` fallbacks in `tests/` and the `sys.version_info < (3, 11)` branches they guard - `python_version < '3.11'` branches in the onnxruntime markers (now dead but harmless) - `pyo3` `abi3-py310` in `Cargo.toml` could move to `abi3-py311` - the 3 remaining Dependabot alerts (bundled undici/ip-address in npm) until an npm release replaces them 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> |
||
|
|
3a38d0b93b |
docs: drop effort-routing text that #3377 removed (#4449)
## Description <!-- Briefly explain the change and why it is needed. --> `python scripts/eval_output_shaper.py B` raised `AssertionError: []` at `scripts/eval_output_shaper.py:201`. Scenario B asserted `body["output_config"]["effort"] == "low"` after `shape_request`, and `shape_request` returned no labels. Root cause: #3377 (`1390d897`) deleted `output_effort_policy.py` and the `effort_router` config, so the shaper no longer changes `output_config.effort`, `reasoning.effort` or `thinking.budget_tokens`. The text around it was not updated. 17 lines mentioning effort routing remained in 9 files: `README.md:186-192`, `headroom/proxy/output_shaper.py:12-22,103-104,196`, `headroom/proxy/thinking_tokens.py:4`, `headroom/proxy/outcome.py:127,253`, `headroom/proxy/handlers/anthropic.py:124,3651`, `headroom/proxy/handlers/openai.py:834`, `headroom/agent_savings.py:176`, `headroom/proxy/server.py:6511` and the eval script. @HetCreep reported the stale text in #4421 and listed most of these locations. I started from that list and found `agent_savings.py:176`, `server.py:6511` and `anthropic.py:124` by grep. Fix: I removed the effort-routing bullet and the `reasoning_effort` / `output_config.effort` paragraph from the README, and docstring item 2 plus the `output_config.effort` safety rule from `output_shaper.py`. I deleted two cache-mode sentences that said effort routing stays on in cache mode, and reworded the other comments. I dropped Scenario B from the eval script (66 lines). Boundary: no runtime code changed and `CHANGELOG.md` is untouched. I did not re-implement effort routing; #3377 removed it on purpose and the issue asks for docs only. I deleted Scenario B instead of rewriting it to assert that effort stays `xhigh`, because `tests/test_output_shaper.py:185` already asserts that. Question for maintainers: do you want that assertion kept in the script as well? I will split the script change into its own PR if you prefer. Closes #4421 ## 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 - `README.md`: removed the effort-routing bullet and the `reasoning_effort` / `output_config.effort` paragraph. - `headroom/proxy/output_shaper.py`: removed docstring item 2, the `output_config.effort` safety rule and two cache-mode comments. - `headroom/proxy/thinking_tokens.py`, `outcome.py`, `handlers/anthropic.py`, `handlers/openai.py`, `agent_savings.py`, `server.py`: comment and docstring wording only. - `scripts/eval_output_shaper.py`: removed Scenario B. ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) — not run - [ ] New tests added for new functionality — none added, no behavior change - [x] Manual testing performed ### Test Output ```text $ uv run pytest -q tests/test_output_shaper.py tests/test_thinking_tokens.py tests/test_outcome_token_scale.py tests/test_output_shaper_responses.py tests/test_openai_responses_output_shaper.py 117 passed, 1 warning in 21.78s $ uv run ruff check . All checks passed! $ uv run ruff format --check . 1812 files already formatted $ ANTHROPIC_API_KEY=dummy uv run python scripts/eval_output_shaper.py B exit=0 ``` The pytest run covers the five test files that touch the output shaper. I did not run the full suite. The one warning is a Starlette `httpx` deprecation from `fastapi/testclient.py` in site-packages. ## Real Behavior Proof - Environment: macOS 27.0.1, Python 3.12.13, `uv sync --extra dev --extra proxy`, `ANTHROPIC_API_KEY=dummy` (no network call) - Exact command / steps: before the patch (`e995eb9f`) `ANTHROPIC_API_KEY=dummy python scripts/eval_output_shaper.py B` in a venv with `anthropic`; after the patch `ANTHROPIC_API_KEY=dummy uv run python scripts/eval_output_shaper.py B`; after the patch `grep -rniE "effort.rout|effort router|effort-router" README.md headroom scripts` - Observed result: before, `AssertionError: []` at `scripts/eval_output_shaper.py:201`, exit 1; after, exit 0 with the header `model=claude-opus-4-8 trials=2` and an empty table, because `B` now matches no scenario and the script makes no API call; the grep returned 0 lines after the patch and 17 lines at `e995eb9f` - Not tested: a live Anthropic run of Scenario A (no API key), the full pytest suite, `mypy headroom`, Windows and Linux ## Runtime Rollout Safety - Rollout-managed feature(s): none, no runtime code changed - Minimum rollout channel: n/a, no runtime change - Stable/default behavior changed: no, comments, docstrings, README and one eval script only - Kill switch / disable path: n/a, no behavior added - Unsafe override required: no - Qualification impact: none, docs and comments only - Rollback path: `git revert` of the single commit ## Review Readiness - [x] I have performed a self-review - [ ] 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 — no code added - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works — none added, no behavior change - [ ] New and existing unit tests pass locally with my changes — 5 test files ran, full suite not run - [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) None. No UI change. ## Additional Notes The README now states that the shaper applies verbosity steering to `/v1/messages`, `/v1/chat/completions` and `/v1/responses` with the same `output_shaper:*` labels. I kept that sentence from the removed paragraph because it still holds. Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
1a40b3ce67 |
fix(telemetry): let HEADROOM_TELEMETRY=off stop the anonymous beacon (#4235)
## Description
Make an explicit HEADROOM_TELEMETRY=off or --no-telemetry choice stop
the anonymous upload beacon as well as local telemetry, while preserving
the separately configured HEADROOM_BEACON=on override and existing
offline/DO_NOT_TRACK policy.
Existing persistent manifests already contain explicit off values
written by the old installer defaults. Those installs stay opted out
after upgrading unless deliberately reconfigured or reinstalled. The PR
does not guess which saved off values were intentional. New installs
omit an unspecified telemetry choice so they retain the existing default
beacon policy.
## Type of Change
- [x] Bug fix (telemetry opt-out behavior)
- [x] Documentation update
## Changes Made
- Apply an explicit local-telemetry opt-out to the beacon enable
decision and report the reason in telemetry status.
- Recheck enablement before sending buffered session telemetry.
- Preserve unspecified, enabled, and disabled telemetry choices when
generating installation manifests.
- Update operator documentation and regression coverage.
## Testing
- [x] Maintainer telemetry, beacon, and snapshot suites passed after the
current-main sync.
- [x] Whitespace check passed.
### Test Output
```text
python -m pytest tests/test_telemetry_warning.py tests/test_proxy_telemetry_env.py tests/test_beacon_schema_v2.py tests/test_beacon_gzip.py tests/test_original_snapshot_in_place_hook.py -q
122 passed, 1 warning in 21.19s
```
A previous broader installer run also reproduced the persistent-service
embedder assertion on current main independently; that baseline failure
was not attributed to this PR. The other 34 planner tests passed in that
qualification. Hosted CI is qualifying head
|
||
|
|
71663b44e2 |
fix(learn): pin the learned verbosity level on a cache-mode proxy (#4033)
## Description `headroom learn --verbosity --apply` hot-enables the output shaper on a running proxy and prints `level N is live now`. On a proxy in **cache mode**, which is the default, that claim is false. The proxy never reads `verbosity.json` there: `resolve_verbosity_level` returns the startup level (`cache_mode_default`, L2) unless `HEADROOM_VERBOSITY_LEVEL` pins one. A level that can change mid-conversation would bust the prefix cache (#3773). So after `--apply` the shaper is on, but at L2 instead of the learned level, while the CLI reports the learned level as live. This PR makes `--apply` either do what it says or say what it did: - **Cache mode, no pin:** the learned level is pinned through `HEADROOM_VERBOSITY_LEVEL` in the same `/admin/runtime-env` update. That is exactly the stable-pin path #3773 allows in cache mode. - **An existing `HEADROOM_VERBOSITY_LEVEL`:** left alone, and the CLI says which level stays in effect. The one exception is a pin this CLI provably set. When the proxy confirms a pin (its `applied` map), `--apply` records `{port, pid, started_at, level}` in `verbosity_pin.json`. `started_at` is `timestamp - uptime_seconds` from `/health`, because pids are reused. A later `--apply` replaces the pin only while that same proxy process still holds that exact value. Hot overrides die with the process, so a restarted proxy's pin, a reused pid, or a value changed since stays the operator's. - **Mode unreadable:** the shaper is still enabled, but the CLI no longer claims the level is live. - **Token mode:** unchanged. The proxy reads `verbosity.json` per request, so no pin is added (a pin would also shadow the verbosity autotune controller). ## 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/learn.py`: - New `_query_proxy_verbosity()` reads `config.mode` and `config.runtime_env.HEADROOM_VERBOSITY_LEVEL` from the local proxy's `/health`. The proxy includes that config block for loopback callers. The level is read the way `OutputShaperSettings.from_env` reads it (parse, default on garbage, clamp to 0–4), so `9` or `04` compare and print as the level the proxy steers at. - `_proxy_process()`, `_record_pin()` and `_pin_is_ours()` keep the ownership record described above. Recording is best-effort: an `OSError` no longer aborts `--apply`; the CLI reports the activation and notes the pin wasn't recorded. The record is written with `newline="\n"`. - `_activate_output_shaper()` returns `(status, port, applied)`, so a pin the proxy applied while reporting the shaper "blocked" is still recorded. - `_activate_output_shaper()` takes an optional `verbosity_level` and sends it in the same runtime-env request. - The `--apply` messages distinguish the four cases above. The restart hints now include `HEADROOM_VERBOSITY_LEVEL=<level>` for cache mode. - The "learned level is used automatically" wording on the blocked and no-proxy paths no longer claims cache mode reads the level. - Those hints no longer prescribe `HEADROOM_ROLLOUT_CHANNEL=beta`: `proxy_output_shaper` is available on every channel, and beta would also enable unrelated features. "Blocked" now points at `HEADROOM_DISABLE_FEATURES`, the only thing that refuses the hot enable. - `tests/test_cli_learn.py`: - CLI tests run `learn --verbosity --apply` against a stubbed local proxy: cache-mode pin, token mode, an operator pin, an unreadable mode, recording and then replacing this CLI's own pin, and keeping pins it cannot prove it set. That last case covers an operator pin equal to the previously learned level, a record from a restarted proxy, and a value changed since. Also covered: out-of-range pins, re-pinning the same level, and a proxy that disables the shaper. Each asserts both the runtime-env body sent and the message printed. - Further cases: a reused pid, a record without a start time, a pin applied while the shaper is blocked, a failed record write, and a proxy without a pid. - Fallback branches: a non-numeric pin (read as the default level), a `/health` reply without a config object, no usable proxy start time (zero or missing uptime, missing or bad timestamp), and a record that isn't a JSON object. Every new line and branch in `headroom/cli/learn.py` is covered (`pytest --cov=headroom.cli.learn --cov-branch`). - A `windows_newline` test asserts that the ownership record is written with `newline="\n"`. - `tests/test_offline_egress_chokepoint.py`: `cli/learn.py` now has two loopback egress sites (`/health` and `/admin/runtime-env`), recorded in the allowlist with the same wording as `cli/wrap.py`. - The existing `--all --apply` test made a real POST to whatever listened on `127.0.0.1:8787`, which on a developer machine is their own proxy. It now runs against a stubbed `urlopen`. - `README.md`, `wiki/learn.md`: state that cache mode does not read the learned level, and what `--apply` does there. `wiki/learn.md` no longer says the shaper needs the beta channel. ## 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 # Before: origin/main's headroom/cli/learn.py with the new tests $ pytest tests/test_cli_learn.py -k verbosity_apply -q FAILED tests/test_cli_learn.py::test_verbosity_apply_pins_the_level_on_a_cache_mode_proxy FAILED tests/test_cli_learn.py::test_verbosity_apply_leaves_a_token_mode_proxy_reading_the_profile FAILED tests/test_cli_learn.py::test_verbosity_apply_does_not_override_an_explicit_level FAILED tests/test_cli_learn.py::test_verbosity_apply_does_not_claim_live_when_the_mode_is_unknown 4 failed, 22 deselected in 1.04s # Review round 3: the previous head ( |
||
|
|
3604af9bbe |
docs(readme): offer 3 months of Enterprise free via the perks page (#3990)
## Description
This PR promotes the Headroom Enterprise perk (3 months free with a
12-month plan) from the README, for readers who arrive on the repo. The
perk lives at headroom-perks.vercel.app.
No linked issue.
## 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
- **Banner:** under the intro, with the image in
`.github/assets/enterprise-perk.svg` and the link tagged
`utm_content=banner`.
- **Top nav:** a "Headroom for Teams" link.
- **"Headroom for teams" section:** an Open source vs Enterprise table,
then the offer, with email as a fallback (`utm_content=teams`).
- **Table accuracy (review fix):** the table now says what OSS already
ships. OSS has tool search on by default for Anthropic requests, and
opt-in, rule-based model routing (`HEADROOM_MODEL_ROUTES`). Enterprise
adds tool search for every model and automatic routing with a shadow
mode. The old table showed routing as unavailable in OSS.
- **Telemetry opt-out (review fix):** this text named a `--offline` flag
that does not exist (it was already wrong on `main`). The switch is
`HEADROOM_OFFLINE=1`.
## 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
$ curl -s -o /dev/null -w "%{http_code}\n" "https://headroom-perks.vercel.app/?source=github&utm_source=github&utm_medium=readme&utm_content=banner"
200
$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" https://raw.githubusercontent.com/headroomlabs-ai/headroom/docs/readme-enterprise-perk/.github/assets/enterprise-perk.svg
200 image/svg+xml
$ git show origin/docs/readme-enterprise-perk:.github/assets/enterprise-perk.svg | python3 -c "import sys,xml.dom.minidom as m; m.parseString(sys.stdin.read()); print('svg parses')"
svg parses
$ headroom proxy --help | grep -i offline
(no output: there is no --offline flag)
$ pre-commit run --files README.md
check for merge conflicts....Passed ruff format....Passed
```
## Real Behavior Proof
- Environment: macOS 26.6 (arm64), GitHub's README renderer on the
branch, the live perks page.
- Exact command / steps: the README on the branch was viewed on GitHub
(banner, nav link, Teams section and table). Each perk link was opened,
and the curl checks above were run.
- Observed result: the perks page responds 200 and states the same
3-months-with-12-month offer. The banner SVG is served as
`image/svg+xml` and parses. The table rows are true of `main` today:
`HEADROOM_MODEL_ROUTER_ENABLED`/`HEADROOM_MODEL_ROUTES` and
`HEADROOM_TOOL_SEARCH` are documented in
`docs/content/docs/configuration.mdx` and `proxy.mdx`.
- Not tested: dark-mode rendering of the banner in GitHub's mobile app.
## Runtime Rollout Safety
- Rollout-managed feature(s): none; this is README content only.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: no.
- Kill switch / disable path: n/a.
- 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
- [ ] 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)
The banner is `.github/assets/enterprise-perk.svg`; GitHub renders it in
the PR's file view.
## Additional Notes
- Tests are N/A: this is a docs-only change.
- **Review fixes are in `a31629dd`** and address @JerrettDavis's routing
correction and both Devin findings.
- The perks page does not yet record `utm_*`, so until it does, claims
from GitHub are attributed by hand.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
|
||
|
|
0d7d61d5cc |
fix(wrap): let wrap opencode target a third-party OpenAI-compatible upstream (#3125)
## Description
`headroom wrap opencode` had no way to say where OpenAI-compatible
traffic should go. `opencode()` forwarded `openai_api_url` to
`_ensure_proxy` only for `--copilot-subscription`; every other run
inherited the proxy default, `https://api.openai.com/v1`. A user
following the README's agent-wrap table with a DeepSeek key therefore
had that key presented to OpenAI, which rejected it with `401 Incorrect
API key provided` and pointed them at a `platform.openai.com` dashboard
for a key they never had. Meanwhile
`docs/content/docs/opencode-deepseek.mdx` said "Do not use `headroom
wrap`", with nothing reconciling the two.
This adds the missing plumbing (`--openai-api-url` /
`OPENAI_TARGET_API_URL`, mirroring `headroom proxy`) and the
documentation the issue asked for.
Closes #3107
## 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `headroom/cli/wrap.py`: `wrap opencode` gains `--openai-api-url`, with
`envvar="OPENAI_TARGET_API_URL"`, mirroring `headroom proxy
--openai-api-url`. It is passed to `_ensure_proxy`, which already knows
how to start the proxy with it and how to report a mismatch against an
already-running proxy.
- `headroom/cli/wrap.py`: combining `--openai-api-url` with
`--copilot-subscription` raises a `ClickException` before anything is
mutated — the subscription resolves its own upstream, so a manual
override would silently fight it.
- `headroom/cli/wrap.py`: the `opencode` docstring documents the default
upstream and both invocation forms.
- `headroom/cli/wrap.py`: `--no-proxy` combined with an upstream
override now fails closed (review). New
`_require_no_proxy_openai_upstream(port, url)` requires a healthy
Headroom listener whose `/health` config advertises the same
`openai_api_url` after `_normalize_proxy_api_url`; an absent listener, a
listener with no Headroom config, or a mismatched upstream each raise a
`ClickException` that names the exact `headroom proxy --port N
--openai-api-url URL` command to run. The check is opted into via a new
`require_openai_api_url` keyword on `_ensure_proxy_unlocked`, set only
by `wrap opencode`, so wrappers that pass a built-in upstream (`vibe`,
`kimi`, `grok`, `zcode`) keep their existing warn-and-reuse `--no-proxy`
behaviour. On a match wrap prints `Proxy on port N already targets URL`,
warns about a proxy-mode mismatch like the other reuse paths, and
continues. `wrap opencode` runs this check before it touches OpenCode's
config or registers a client marker, so a refused upstream leaves
nothing behind. `--prepare-only` skips it, since it never uses a proxy.
- `headroom/providers/opencode/config.py`:
`inject_opencode_provider_config(port, keep_user_entries=...)` keeps the
user's own `models` and `options` (an `apiKey`, say) under
`provider.headroom` instead of replacing the entry; Headroom still owns
`npm`, `name` and `baseURL`. `wrap opencode` passes `keep_user_entries`
only when `--openai-api-url` (or `OPENAI_TARGET_API_URL`) is set.
Without it the proxy forwards to OpenAI, so a kept third-party key would
be sent there, and wrap writes Headroom's entry as before. OpenCode only
resolves `headroom/<id>` for listed ids, so without this a DeepSeek user
had no DeepSeek model to select (`ProviderModelNotFoundError`) and no
key to send.
- `docs/content/docs/opencode.mdx`: `--openai-api-url` documented on the
canonical OpenCode page (Options block, prose, env-var table), with a
two-form example — wrap starts the proxy, or `headroom proxy
--openai-api-url …` then `wrap --no-proxy --openai-api-url …` — and a
paragraph stating that `--no-proxy` verifies and refuses rather than
re-points.
- `docs/content/docs/opencode-deepseek.mdx`: new "Common issues" entry
for the `Incorrect API key provided` 401 (it comes from OpenAI, not
DeepSeek) and a "When is `headroom wrap opencode` safe?" section — safe
as-is for the default OpenAI/Anthropic upstreams, needs
`--openai-api-url` for any third-party OpenAI-compatible provider, and
that wrap keeps the step 4 `models` and `apiKey` under
`provider.headroom` (DeepSeek needs both). The "Models appear but
requests fail" entry and the "What's NOT in this guide" bullet are
reworded to match, replacing the blanket "do not use `headroom wrap`".
- `README.md`: footnote on the OpenCode row of the agent compatibility
matrix naming the default upstream and the flag/env var.
- `tests/test_cli/test_wrap_opencode.py`: ten tests — the flag, the env
var, the unset default, the `--copilot-subscription` rejection; for
`--no-proxy`: absent, non-Headroom, matching (trailing slash, proving
normalization), and mismatched listeners; that wrappers without
`require_openai_api_url` keep lenient reuse; and that the CLI forwards
the flag. With the fix reverted, 5 of the 6 new tests fail. Review
follow-ups add: `wrap opencode --help` keeps its examples unwrapped and
`wrap.py` has no raw control bytes; a refused `--no-proxy` upstream
exits before any OpenCode config edit or client marker; the
matching-upstream path still warns about a mode mismatch.
- `tests/test_providers_opencode_config.py`: with `keep_user_entries`
the user's `headroom` models and `apiKey` survive re-injection, other
providers are untouched, and Headroom's `npm`/`baseURL` win; without it
they are dropped.
- `tests/test_cli/test_wrap_opencode.py` (second round): through the CLI
the key is kept with `--openai-api-url` and dropped without it, and
`--prepare-only --no-proxy --openai-api-url` writes config with no proxy
listening.
## 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
Four failures in the wider `tests/test_cli` run are pre-existing and
Windows-only — they reproduce identically with this branch's changes
stashed: symlink/settings-path issues in `test_recover_codex.py` and
`test_unwrap_claude.py`, and `signal.SIGHUP` (absent on Windows) in
`test_wrap_stale_marker.py`. They are deselected below.
`tests/test_cli_proxy_improvements.py` and
`tests/test_memory/test_learn_flag.py` cannot run from this source
checkout because the Rust `headroom._core` extension is not built here
(same result on the clean branch); CI builds the wheel.
### Test Output
```text
$ python -m pytest tests/test_cli/test_wrap_opencode.py -q
50 passed, 1 warning in 1.96s
$ python -m pytest tests/test_cli -q --deselect tests/test_cli/test_recover_codex.py --deselect tests/test_cli/test_unwrap_claude.py --deselect "tests/test_cli/test_wrap_stale_marker.py::test_signal_handler_unwinds_so_the_restore_can_run"
706 passed, 1 skipped, 46 deselected, 1 warning in 60.41s
$ git stash push -- headroom/cli/wrap.py && python -m pytest tests/test_cli/test_wrap_opencode.py -q -k no_proxy
5 failed, 2 passed # the new tests fail without the fix; the 2 passing pin unchanged behaviour
$ python -m ruff check .
All checks passed!
$ python -m ruff format --check .
1577 files already formatted
$ python -m mypy headroom
Success: no issues found in 532 source files
$ python -m coverage run --include=headroom/cli/wrap.py -m pytest tests/test_cli/test_wrap_opencode.py -q
50 passed # 17/17 statements added to wrap.py executed, 0 missing
# Review follow-ups (this branch, with current main merged in)
$ pytest tests/test_cli/test_wrap_opencode.py tests/test_providers_opencode_config.py
102 passed, 1 failed # test_build_launch_env_with_project: a known Windows-only path-escaping failure, also on main
# each new test fails on the code before its fix:
test_inject_provider_config_keeps_the_users_models_and_options -> KeyError: 'apiKey'
test_no_proxy_with_openai_api_url_still_warns_about_a_mode_mismatch -> warning missing from output
test_wrap_opencode_no_proxy_rejects_a_mismatched_upstream_before_editing_config -> "MCP retrieve tool: registered", then _ensure_proxy reached
test_wrap_opencode_keeps_the_users_headroom_key_only_for_an_explicit_upstream[no flag] -> key kept (would go to OpenAI)
test_wrap_opencode_prepare_only_does_not_need_the_no_proxy_listener -> "No Headroom proxy is listening on port 9000"
# help test: dropping either no-rewrap marker, or writing a raw 0x08 byte, fails a test (3/3)
$ ruff check / ruff format --check (0.16.8): clean
$ mypy headroom/cli/wrap.py headroom/providers/opencode/config.py --ignore-missing-imports --follow-imports=silent
Success: no issues found in 2 source files
```
## Real Behavior Proof
- Environment: Windows 11, Python 3.11.9, headroom 0.35.0 (`rust_core:
loaded`), with a stub `opencode` on `PATH` that curls the proxy's
`/health` — so the wrapped agent reports the upstream the proxy actually
resolved.
- Exact command / steps: (1) baseline against released 0.35.0 without
this fix on `sys.path` — `python -m headroom.cli wrap opencode --port
8799 --no-mcp --no-serena --openai-api-url https://api.deepseek.com/v1`;
(2) same command on this branch, port 8801; (3) env-var form on this
branch — `OPENAI_TARGET_API_URL=https://api.deepseek.com/v1 python -m
headroom.cli wrap opencode --port 8802 --no-mcp --no-serena`. For the
`--no-proxy` review: `python -m headroom.cli wrap opencode --port <P>
--no-proxy --no-mcp --no-serena --openai-api-url
https://api.deepseek.com/v1` on this branch against (4) nothing on 8811;
(5) `python -m http.server 8812`; (6) a real released-0.35.0 `headroom
proxy --port 8813` (default upstream, `/health` reports
`"openai_api_url": null`); (7) a real `headroom proxy --port 8814
--openai-api-url https://api.deepseek.com/v1`.
- Observed result: step 1 reproduces the bug exactly — wrap prints
`Extra args: --openai-api-url https://api.deepseek.com/v1` (the flag is
swallowed by `ignore_unknown_options` and handed to the agent) and the
proxy it started reports `"openai_api_url": null`, i.e. it would forward
to `api.openai.com`. Step 2 prints no `Extra args` line and the proxy
reports `"openai_api_url": "https://api.deepseek.com/v1"`. Step 3
reports the same. All three runs cleaned up their proxy on exit — no
listener left on 8799/8801/8802. Steps 4–6 each exit 1 before `opencode`
is launched, with: (4) `No Headroom proxy is listening on port 8811 …
Start it separately with `headroom proxy --port 8811 --openai-api-url
https://api.deepseek.com/v1`, or drop --no-proxy …`; (5) `The listener
on port 8812 did not report a Headroom config, so wrap cannot confirm it
forwards to https://api.deepseek.com/v1 …`; (6) `The Headroom proxy on
port 8813 forwards OpenAI-compatible traffic to
https://api.openai.com/v1, not https://api.deepseek.com/v1. Restart it
with …` — and the 8813 proxy is left running, still reporting `null`.
Step 7 prints `Proxy on port 8814 already targets
https://api.deepseek.com/v1` and launches the stub (exit 0). Both
proxies were stopped afterwards; 8811–8814 verified free.
- Real OpenCode (review follow-up): OpenCode 1.18.34 installed from npm
into a scratch directory with an isolated `HOME`, and a local fake
OpenAI-compatible "DeepSeek" upstream on 8792 that records each
request's model and `Authorization` header. The global `opencode.json`
declares `provider.headroom.models.deepseek-chat` and `options.apiKey:
"{env:DEEPSEEK_API_KEY}"`. Command: `headroom wrap opencode --port 8796
--openai-api-url http://127.0.0.1:8792/v1 --no-mcp --no-serena -- run
"say hi" -m headroom/deepseek-chat`.
- before this commit: `ProviderModelNotFoundError: Model not found:
headroom/deepseek-chat.` Nothing reached the upstream, and the config
after wrap held only `gpt-4o` and `gpt-4.1` under `headroom`, with no
`apiKey`.
- after (re-run on the final head
|
||
|
|
8cfeb692ca |
fix(wrap): scope Serena's MCP registration to the wrapped project (#2787) (#2992)
## Description Fixes #2787. Scopes Headroom-installed Serena to the wrapped Claude project by default, containing an upstream MCP failure to that project instead of degrading every Claude Code session on the machine. `--code-memory-scope user` / `HEADROOM_CODE_MEMORY_SCOPE=user` retains the prior machine-wide behavior when explicitly requested. The implementation completes ownership semantics across multiple wrapped projects: - Claude MCP registration, lookup, overwrite, and removal are scope-aware. - Legacy ledger-owned user entries migrate safely; user-managed global Serena remains untouched. - Each project gets an independent ledger ownership key, so wrapping project B no longer overwrites project A's ownership. - Unwrapping project A removes only A plus an independently-owned legacy user entry; it cannot orphan B or delete an unowned global entry. - The migration that retires a legacy machine-wide entry now clears the ledger ownership record along with the config entry (see Changes Made) — an ownership record can no longer outlive the entry it authorized. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/mcp_registry/claude.py`: `ClaudeRegistrar` gained a `scope` argument and reads/writes both `local` (project) and `user` (machine-wide) Claude Code MCP scopes. - `headroom/cli/wrap.py`: `_setup_serena_mcp` registers Serena at `local` scope by default; `--code-memory-scope` (env `HEADROOM_CODE_MEMORY_SCOPE`) restores `user` scope on request. - `headroom/cli/wrap.py`: `_retire_user_scope_serena` migrates a pre-#2787 machine-wide Serena entry on the next wrap, but only when the ledger proves Headroom installed it. - `headroom/cli/wrap.py`: fixed `_retire_user_scope_serena` to clear the ledger's ownership record after removing the migrated entry — previously the record survived the removal, so a user later installing the identical Serena command globally themselves could collide with the stale fingerprint and have their own entry deleted by a later wrap. - `headroom/cli/wrap.py`: `_remove_headroom_installed_serena_mcp` now also clears a scope's ownership record when that scope's live entry is already absent, so a record can't outlive the entry it authorized. - `headroom/mcp_registry/ledger.py`: ledger entries key off a project-scoped `ownership_key` in addition to the legacy global key, so multiple wrapped projects don't clobber each other's ownership records. - Added/extended tests: `tests/test_cli/test_serena_scope.py`, `tests/test_mcp_registry/test_claude_registrar.py`, `tests/test_cli/test_unwrap_claude.py`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality ### Test Output ```text pytest tests/test_cli/test_serena_scope.py -v 13 passed in 19.29s pytest tests/test_mcp_registry/ tests/test_cli/test_unwrap_claude.py -q 137 passed, 2 failed in 2.16s ``` Both failures are pre-existing and unrelated to this change — they reproduce identically with this PR's diff to `headroom/cli/wrap.py` reverted, on a clean checkout of this branch. `test_unwrap_claude_stops_claude_owned_persistent_deployment` was already confirmed pre-existing on `main` by an independent reviewer on this PR (comment from PrakharSrivastav, 2026-08-13). `test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy` fails locally on Windows over a hook-config path-comparison mismatch unrelated to Serena scoping; it is not exercised by this diff. ```text ruff check . All checks passed! ruff format --check . All files already formatted. mypy headroom --ignore-missing-imports Success: no issues found in 522 source files ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.13.11, project `.venv` (pytest 9.0.3, mypy 2.3.1, ruff). - Exact command / steps: `pytest tests/test_cli/test_serena_scope.py -v`, then re-ran the two new regression tests (`test_rewrap_migration_clears_the_ledger_so_a_reinstall_is_never_deleted`, `test_remove_serena_clears_a_stale_ownership_record_with_no_live_entry`) with the `headroom/cli/wrap.py` fix reverted via `git stash`, to confirm they fail on the old code and pass on the fix. - Observed result: both new tests fail with `assert not True` (stale ledger record still present) against the pre-fix code, and pass once the `clear_install(...)` calls are added. Full `test_serena_scope.py` suite: 13/13 passed post-fix. `mypy headroom` and `ruff check .` both clean. - Not tested: a real Claude Code installation end-to-end (these tests drive `ClaudeRegistrar` against a `tmp_path` home directory, per the existing pattern in this file); real macOS/Linux CI runners, which is what the GitHub Actions matrix below covers. ## Runtime Rollout Safety - Rollout-managed feature(s): `headroom wrap claude` Serena MCP registration scope only. - Minimum rollout channel: normal patch release; no staged feature flag required. - Stable/default behavior changed: Serena now registers at Claude Code's `local` (project) scope by default instead of `user` (machine-wide) scope; a pre-existing Headroom-installed machine-wide entry is migrated (removed) on the next wrap, with its ledger record now also cleared. - Kill switch / disable path: `--code-memory-scope user` (or `HEADROOM_CODE_MEMORY_SCOPE=user`) restores the previous machine-wide registration. - Unsafe override required: none. - Qualification impact: `tests/test_cli/test_serena_scope.py`, `tests/test_mcp_registry/test_claude_registrar.py`, and `tests/test_cli/test_unwrap_claude.py` must stay green (module to the two pre-existing, environment-specific failures noted under Testing). - Rollback path: human revert of this PR; `--code-memory-scope user` provides an immediate operational fallback to the old registration scope without a code rollback. ## 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 made corresponding changes to the documentation (`README.md`, `docs/content/docs/proxy.mdx`) - [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 ## Additional Notes Addresses the code-review finding from JerrettDavis (2026-08-14): the ledger's stale ownership record after migration is now cleared, with a regression test that reproduces the exact fingerprint-collision scenario described in that review and fails on the pre-fix code. --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
7ff67693be |
docs(proxy): document cache-mode memory behavior (#3577)
## Description Document the existing cache-mode behavior for users who enable persistent memory. This makes clear that cache mode prioritizes provider prefix stability over memory context injection. Closes #3573 ## 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 - Add a cache-mode memory note to the root README compatibility guidance. - Explain the cache-mode memory limitation beside the `--memory` option in the proxy documentation. ## 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 $ npm exec -- fumadocs-mdx [MDX] generated files in 10.36819700000001ms fumadocs-mdx: passed $ git diff --check git diff --check: passed The file-aware documentation checks found the cache-mode memory note in both README.md and docs/content/docs/proxy.mdx. ``` ## Real Behavior Proof - Environment: Linux, Node.js v22.23.2, Headroom checkout based on upstream main commit `aa4739e54ad46d48dd829f730af359c4824c04c4`. - Exact command / steps: Ran `npm exec -- fumadocs-mdx`, checked each documentation file for its cache-mode memory explanation, and ran `git diff --check`. - Observed result: MDX generation completed successfully, both documentation files contain the cache-mode memory limitation, and the diff has no whitespace errors. - Not tested: The Next.js production build did not finish during the local run; deployed documentation rendering and live proxy requests were not tested. ## Runtime Rollout Safety - Rollout-managed feature(s): None; this change only updates documentation. - Minimum rollout channel: Not applicable. - Stable/default behavior changed: Documentation now states the existing cache-mode memory behavior. - Kill switch / disable path: Not applicable; no runtime behavior changed. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert this documentation-only change. ## 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 - [x] 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 - [x] I did **not** edit `CHANGELOG.md` - it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) --------- Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
66258c40a4 |
fix: make Headroom work behind Zscaler and other TLS-inspecting networks (#3831)
## Description Customers behind **Zscaler** (and Netskope, Palo Alto, Cisco Secure Access, …) report that Headroom "cannot work": every upstream request fails with `CERTIFICATE_VERIFY_FAILED`, and the agent only sees a bare 502. These gateways inspect TLS by re-signing every certificate with a company root. IT installs that root in the **OS certificate store** (macOS Keychain, Windows cert store), which is why browsers, `curl` and Claude Code keep working. Headroom never read that store: - The httpx upstream client trusted certifi only. - On macOS, the stdlib default reads the static file `/etc/ssl/cert.pem`, not the Keychain. - The Rust proxy trusted Mozilla's webpki roots only. Only 3 of about 40 outbound call sites used the shared CA helper. We had been patching one path at a time (#741, #998, #1308, #3244, #3344, #3358, #810, #2029). This PR sets **one trust policy, based on the OS store, used everywhere.** Closes #3358 ## 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 **1. Verify upstream TLS through the OS store by default** (`headroom/proxy/ssl_context.py`) - New `HEADROOM_CERT_STORE`, default `system,bundled` (same shape as Claude Code's `CLAUDE_CODE_CERT_STORE`). It uses [`truststore`](https://truststore.readthedocs.io/), which pip has used by default since 24.2, plus certifi's public roots. - The same policy covers the HTTP upstream client, both WebSocket upstreams, and the `urlopen` paths (Copilot auth). - **The builders now always return a concrete, verifying `SSLContext`**, never a `bool`. The legacy default is built explicitly as httpx's `verify=True` equivalent (certifi). - OS-store contexts are cached per configuration. They set `VERIFY_X509_PARTIAL_CHAIN` so an exported intermediate still works as a trust anchor (matching `create_default_context()` on 3.13). On macOS and Windows the OS verifies the chain, so the Python 3.13 strict-mode rejection (#1308) no longer happens. - `HEADROOM_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS` **add** roots. `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` keep their **replacement** meaning and turn the OS store off. - `HEADROOM_CERT_STORE=bundled` restores the old behavior. The aliases `bundle`, `certifi`, `os` and `native` are also accepted. - `truststore.inject_into_ssl()` (covers `huggingface_hub`, tiktoken and OTEL) runs only in processes the Headroom CLI owns. The CLI marks them with `HEADROOM_PROCESS_TRUST=1`, and proxy workers inherit it. Applications that embed Headroom keep their own process-wide TLS behavior. - `truststore` is added as a core dependency: pure Python, with no dependencies of its own. **2. Errors that say what's wrong** (`headroom/proxy/tls_diagnostics.py`) - When the certificate check fails, the Anthropic, streaming (SSE) and OpenAI passthrough errors now name who signed the certificate and give the fix. For example: *"…The certificate was issued by 'O=Zscaler Inc., CN=Zscaler Intermediate Root CA': Zscaler is inspecting this connection. Fix (pick one): …"* - The issuer comes from a separate handshake that inspects the certificate only: - It sends no data and requires **TLS ≥ 1.2**. - It has a 4-second timeout and is cached for 5 minutes per host. A burst of failures shares a single handshake. - It uses the same environment-variable proxies as the real client. - It targets the host that actually failed. - **Security:** on the request path it skips hosts that resolve to non-public addresses. It also connects to the exact address it checked, instead of looking the host up again. A per-request upstream therefore can't be used to read an internal service's certificate or to rebind DNS. **3. `headroom doctor`** - A new **tls trust** row reports the running proxy's policy, read from `/health`. - A **proxy env** warning appears when `HTTP(S)_PROXY` is set but `NO_PROXY` doesn't exempt loopback. - `--network` (plus a repeatable `--network-url`) probes the provider and model hosts. For each it shows the certificate issuer, whether Headroom trusts it, and whether a gateway block page came back. On failure it prints a paste-ready request for IT. **4. `headroom wrap`** - Merges `NO_PROXY` and `no_proxy`, appends `127.0.0.1,localhost,::1`, and writes the result to both, so a corporate proxy doesn't capture the agent's traffic to Headroom. - The notice goes to stderr, because the JSON that `--prepare-only` prints on stdout is parsed by `install.sh`. **5. Rust proxy** (`crates/headroom-proxy`) - reqwest now enables `rustls-tls-native-roots`, and `HEADROOM_CA_BUNDLE` / `NODE_EXTRA_CA_CERTS` add roots. - **Fixes a bug already on `main`: `wss://` upstreams panicked.** Both ring and aws-lc-rs are compiled into this binary, so `rustls::ClientConfig::builder()`, which `tokio_tungstenite::connect_async` calls, panics with "no process-level CryptoProvider available". WebSocket upstreams now use an explicit config: the ring provider, webpki + OS + additive roots, and ALPN `http/1.1`. **6. Docs** - New page **Corporate Networks**: trust settings, HTTP proxies, a domain table for IT, and notes on Caution/Isolate, SSE buffering, process bypass, tenant restrictions and `HF_ENDPOINT` mirrors. - README section updated, correcting a wrong claim about which trust store the Rust core uses. **7. `uv.lock`** - `main`'s lockfile plus `truststore` only. The diff is 11 lines: the new package entry and two lines in `headroom-ai`'s dependency lists. ## 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_corporate_tls.py tests/test_ssl_context.py tests/test_copilot_auth.py tests/test_cli_doctor.py -q ============================= 278 passed in 2.88s ============================== $ pytest <117 related files: doctor, wrap, streaming, codex, copilot, ssl, upstream, websocket, passthrough> -q ====== 4 failed, 1876 passed, 25 skipped, 7 warnings in 132.42s (0:02:12) ====== # the 4 failures: tests/test_codex_live.py ordering issue, identical on main (see Additional Notes) $ cargo test -p headroom-proxy passed=478 failed=0 suites=37 $ cargo clippy -p headroom-proxy --all-targets -- -D warnings Finished `dev` profile [unoptimized + debuginfo] target(s) $ ruff check . -> All checks passed! $ ruff format --check . -> 1660 files already formatted $ mypy headroom --ignore-missing-imports -> Success: no issues found in 544 source files $ uv export --frozen --no-dev --no-hashes | grep truststore -> truststore==0.10.4 ``` `tests/test_corporate_tls.py` runs a **fake Zscaler** HTTPS server. Its root is `O=Zscaler Inc.` with **non-critical basicConstraints**, like the real 2014 root. The tests check that: - certifi alone rejects it; - the default policy plus `HEADROOM_CA_BUNDLE` or `NODE_EXTRA_CA_CERTS` accepts it; - the probe names Zscaler, and the request path skips private hosts; - a streaming request surfaces the actionable message in a 502 SSE error; - a burst of failures shares one handshake; - the notices and JSON output from `wrap` go to the right streams; - process injection is gated as described. ## Real Behavior Proof - **Environment:** - macOS (Darwin 25.6, Apple Silicon), Python 3.12.13 venv - Python 3.13.15 via `uv run --python 3.13` - Linux `python:3.13-slim` in Docker - Rust proxy built from this branch - **Steps and results:** 1. **Standalone fake-Zscaler script** (same root as above) on Python 3.13: - old stdlib path, `ssl.create_default_context(cafile=root)` → `CERTIFICATE_VERIFY_FAILED: Missing Authority Key Identifier` - new `truststore` context + root → `200` - identical results on macOS and in `python:3.13-slim`. 2. **`headroom doctor --network`** from this branch on an uninspected network: every endpoint shows `reachable, certificate trusted` (api.anthropic.com 401, api.openai.com 401, api.githubcopilot.com 400, huggingface.co 200, openaipublic 404); the tls trust row shows `OS certificate store + certifi`. 3. **Rust `wss://` connection** (temporary test) to `wss://echo.websocket.org`: - `tokio_tungstenite::connect_async` as on `main` → **panic** (no process-level CryptoProvider) - `connect_async_tls_with_config` with the new config → `Ok(())` - **Not tested:** - A real Zscaler, Netskope or Palo Alto tenant. - Windows. `truststore` supports the Windows cert store, but no Windows run was done here. - A root installed into the OS store. That needs admin rights, so the additive-bundle path stood in for it; it goes through the same OS verifier. ## Runtime Rollout Safety - **Rollout-managed feature(s):** none. This is trust-store selection, not a rollout-gated feature. - **Minimum rollout channel:** n/a. - **Stable/default behavior changed:** yes. Upstream TLS now also trusts the OS certificate store; certifi is still loaded, so public endpoints behave the same. The Rust `wss://` upstream no longer panics. - **Kill switch / disable path:** `HEADROOM_CERT_STORE=bundled` restores certifi-only trust. An explicit `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` behaves exactly as before. - **Unsafe override required:** none. Nothing here disables certificate verification. - **Qualification impact:** none expected. Default behavior on uninspected networks is unchanged. - **Rollback path:** revert the PR, or set `HEADROOM_CERT_STORE=bundled`. ## 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 (CLI and proxy behavior). ## Additional Notes **Review response** (@JerrettDavis): - **CodeQL:** the 5 alerts that were still open on `efe173c9` had two causes. - **Certificate-validation alerts:** CodeQL traced a `None` returned by the optional-context helpers through the `configured or default` fallback into `verify=`. All contexts are now built by a single `_build_context()`, and every branch returns a verifying `SSLContext`. `build_httpx_verify()` is typed `-> ssl.SSLContext`. - **TLS-version alerts:** every context the module creates now sets an explicit `minimum_version = TLSv1_2`. That includes the certificate-inspection probe, whose no-validation scope stays confined to that handshake behind the public-address / environment-proxy CONNECT guard. The test server also requires TLS 1.2, and the host assertion in the test is a regex. - **Verified locally with CodeQL 2.27.1** before pushing: - the same 5 alerts reproduce on `efe173c9`, and 0 remain on the fix commit; - `python-security-extended` over every Python file this PR changes finds the same 14 pre-existing alerts on `main`'s versions and on the branch's versions, so the PR adds none. - **`uv.lock`:** rebuilt as `main`'s lockfile plus `truststore` only (11 lines). Re-locking with current uv also rewrites markers across the file, because `main`'s lockfile predates the current `pyproject.toml`. That is left for a separate lock refresh. **Earlier review:** a high-effort code review of this branch produced 10 findings plus 3 minor notes. Commit `fix: address review findings…` resolves 9 of the 10 and two of the notes; the third note (lockfile markers) checked out as a false alarm. The remaining finding is the last follow-up below. **Follow-ups (not in this PR):** - SSE keep-alives and HTTP/1.1 fallback when a gateway buffers a stream. - A `wrap` pre-flight that steps aside when the upstream is unreachable. - The Rust core's fastembed/hf-hub embedding download, which hard-codes WebPki roots (needs an hf-hub patch; BM25 is the fallback, and `HF_ENDPOINT` is documented). - A CI job with a fake root installed in the OS store on macOS and Windows. - Map certificate failures once, in a shared layer, so batch, Gemini and the other handlers get the TLS hint too. **Known unrelated failures:** - 4 `tests/test_codex_live.py` tests fail when run after other files in this set, both on `main` and on this branch. They pass when run on their own. - After merging the latest `main` (thanks for the refresh), `tests/test_cli/test_wrap_helpers.py::test_start_proxy_strips_ambient_worker_configuration` and `::test_start_proxy_timeout_kills_failed_new_process` fail locally with `TypeError: <lambda>() takes 0 positional arguments but 1 was given`. They fail the same way on a clean checkout of current `main`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
76ec363a60 |
docs(readme): list C# and PHP as AST-compressed, drop quarantined Perl (#3225)
## Description The README "What's inside" bullet for CodeCompressor (and the two matching lists in `wiki/transforms.md` plus the module docstring of `headroom/transforms/code_compressor.py`) still read `Python, JS/TS, Go, Rust, Java, C/C++, Perl`. That list predates two changes on `main`: - **C#** (#1664 → #1926) and **PHP** (#201 → #2423) are first-class `LangConfig` entries in `CodeAwareCompressor` (`code_compressor.py:440` and `:469`) but were never added to the lists. - **Perl** has been quarantined from code-aware compression since #2204 (refs #2185): `_get_parser()` refuses the `perl` grammar (`code_compressor.py:106`, `:136`) and `compress()` short-circuits Perl to the Kompress fallback / passthrough (`code_compressor.py:1200`), so "AST-aware for … Perl" is no longer true. All four lists now match the canonical docs site (`docs/content/docs/code-compression.mdx`, which already says `Go, Rust, Java, C, C++, C#, PHP` for Tier 2 and does not list Perl). Closes #201 — PHP support itself landed in #2423 (the PR description mentioned the issue without a closing keyword, so it stayed open); this PR makes it visible in the README. ## 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 - `README.md` — CodeCompressor bullet: add C# and PHP, drop Perl. - `wiki/transforms.md` — "Multi-language support" bullet and the Tier 2 row of the "Supported Languages" table: add C# and PHP. - `headroom/transforms/code_compressor.py` — module docstring, "Supported Languages (Tier 2)": add C# and PHP. Docstring only; no runtime code changes. ## 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 $ git rev-parse --short HEAD |
||
|
|
fc5a09e1b3 |
feat(wrap): support 1m context in vscode claude (#3361)
## Description `headroom wrap vscode-claude` now supports an opt-in `--1m` path. It stores Claude Code's `[1m]` model selector in the existing top-level `model` setting and records the prior value in the reversible settings sidecar. Reconfiguration remains idempotent, malformed sidecars fail with a clear error, and user changes to Headroom-managed values remain protected. The branch also pins npm 11.16.0 in the shared Docker wrap test image. npm 10.9.8 crashed while installing the local OpenClaw plugin with `Cannot read properties of null (reading 'edgesOut')`. Closes #3360 ## 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 `--1m` to `headroom wrap vscode-claude`. - Reused one Claude-specific resolver for standalone and VS Code model selection. - Extended the reversible VS Code sidecar to preserve, validate, and restore the top-level model. - Refreshes fallback-selected models when `HEADROOM_1M_MODEL` changes between repeated `--1m` runs. - Preserved exact prior values and refuses to overwrite user edits. - Added read-only `--no-configure --1m` output for manual settings setup. - Added focused tests for model persistence, fallback refresh, malformed state, conflict handling, and restoration. - Pinned npm 11.16.0 in `e2e/wrap/Dockerfile` for both Docker wrap jobs. - Updated the VS Code Claude documentation. ## Testing - [x] Focused unit and integration tests pass - [x] Linting and formatting checks pass for changed Python files - [ ] Type checking passes - [x] New tests added for the changed behavior - [ ] Manual testing performed ### Test Output ```text uv run pytest tests/test_cli/test_wrap_vscode_claude.py tests/test_provider_claude.py tests/test_provider_claude_vscode_config.py -q 48 passed in 1.15s uv run ruff check headroom/providers/claude/vscode.py headroom/cli/wrap.py tests/test_provider_claude_vscode_config.py All checks passed! uv run ruff format --check headroom/providers/claude/vscode.py headroom/cli/wrap.py tests/test_provider_claude_vscode_config.py 3 files already formatted ``` ## Real Behavior Proof - Environment: Windows, Python development environment, temporary Claude settings file. - Exact command / steps: run `headroom wrap vscode-claude --1m --settings-file <temporary-settings.json>`, inspect the settings and sidecar, then run `headroom unwrap vscode-claude --settings-file <temporary-settings.json>`. - Observed result: the `[1m]` model persisted, the sidecar recorded the prior model, and unwrap restored the exact prior value. Repeated `--1m` runs picked up a changed `HEADROOM_1M_MODEL` fallback when no user model existed. - GitHub CI result: `docker-wrap-e2e`, `docker-native-e2e`, and all other required checks passed after the npm pin. - Not tested: live Claude account entitlement for the 1M context window. ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: next release containing the VS Code Claude wrapper change. - Stable/default behavior changed: `--1m` remains opt-in; default VS Code Claude behavior is unchanged. - Kill switch / disable path: omit `--1m`, run `headroom unwrap vscode-claude`, or revert the change before release. - Unsafe override required: no. - Qualification impact: Claude account entitlement still controls access to the 1M context window. - Rollback path: run `headroom unwrap vscode-claude`, reload VS Code, and revert the release if needed. ## 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 - [x] My changes generate no new warnings - [x] I have added tests that prove the feature works - [x] Focused tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md`; release-please generates it from the conventional PR title. ## Additional Notes Claude Code and Anthropic control model support and account eligibility. Local tests prove persisted configuration and restoration, not access to a live 1M context window. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
b8b222f940 |
fix(deps): install on Python 3.14 from prebuilt wheels only (#3631)
## Description Rolled out Python 3.14 and cannot downgrade. Two problems block a no-compiler install of `headroom-ai[proxy]` on 3.14: 1. **No pricing on 3.14.** litellm is skipped on Python 3.14 (GH #956) because releases before 1.93 rejected it. So 3.14 installs have no LiteLLM, and the dashboard shows $0.00 saved. LiteLLM has supported 3.14 since 1.93.0 (BerriAI/litellm#26343), and **1.96.2** is the first release with prebuilt wheels for Python 3.10 to 3.14 on Linux, macOS and Windows. Between 1.92 and 1.96.0 some platforms only get an sdist, which needs a Rust build. 2. **macOS 3.14 needs a C compiler.** `watchdog` 6.0.0, the latest, has no macOS wheel for Python 3.14 (Linux and Windows have one), so pip compiles it. It only powers the optional `--code-graph` file watcher, which already skips itself when watchdog is missing. But `ensure_proxy_dependencies()` required it, so the proxy wouldn't start without it. Closes # ## 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `pyproject.toml`: `litellm>=1.86.2,<2.0; python_version < '3.14'` becomes `litellm>=1.96.2,<2.0` (core and `dev`) - `pyproject.toml`: `watchdog>=4.0.0` becomes `watchdog>=4.0.0; sys_platform != 'darwin' or python_version < '3.14'` - `headroom/cli/proxy.py`: `watchdog` removed from the proxy startup dependency check - `uv.lock`: refreshed (litellm 1.88.1 to 1.101.0, which moves boto3/botocore/s3transfer/awscrt; watchdog marker) - `tests/test_litellm_optional.py`: replaces the "skipped on 3.14" assertion with tests that litellm applies on every supported Python and platform with a floor that has 3.14 wheels; that watchdog is skipped only on macOS 3.14; that the proxy dependency check never imports watchdog; and that the code graph watcher returns `False` without watchdog - `.github/workflows/ci.yml`: new `python-314-wheels` job (Linux + macOS, runs when packaging changes) that installs `headroom-ai[sandbox]` with `--only-binary=:all:` on Python 3.14, checks proxy deps and LiteLLM pricing, and starts the proxy until `/health` answers - README and `wiki/metrics.md`: removed "pick Python 3.13 for the dollar figure"; comments that described the 3.14 litellm gate updated ## 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_litellm_optional.py tests/test_optional_dependencies.py tests/test_pricing_from_litellm.py 18 passed in 3.07s # new tests without the pyproject/proxy.py change FAILED tests/test_litellm_optional.py::test_litellm_is_required_on_every_supported_python FAILED tests/test_litellm_optional.py::test_litellm_floor_has_wheels_for_python_314 FAILED tests/test_litellm_optional.py::test_watchdog_is_skipped_only_where_it_has_no_wheel FAILED tests/test_litellm_optional.py::test_proxy_starts_without_watchdog # with the change 6 passed in 0.34s $ uvx ruff@0.16.7 check <changed files> && uvx ruff@0.16.7 format --check <changed files> All checks passed! 7 files already formatted $ mypy --ignore-missing-imports headroom/cli/proxy.py headroom/pricing/litellm_pricing.py Success: no issues found in 2 source files $ actionlint .github/workflows/ci.yml (clean) ``` ## Real Behavior Proof - Environment: macOS arm64, Python 3.14.7, fresh venv, `PATH=/usr/bin:/bin` (no cargo, no Homebrew toolchain) - Exact command / steps: 1. took the 0.37.0 wheel and changed only its `Requires-Dist` lines to match this PR (litellm floor, watchdog marker) 2. `pip install --only-binary=:all: "headroom-ai[sandbox] @ file://…whl"` 3. ran this branch's `ensure_proxy_dependencies()` in that env 4. started this branch's proxy in that env: `headroom proxy --port 18931`, then `GET /health` and `GET /stats` - Observed result: - install exit 0, 0 source builds, litellm 1.101.0, watchdog not installed - dependency check passed without watchdog - `/health`: `"status":"healthy","ready":true` - `/stats`: `"litellm_available": true` - Checked separately against PyPI: every one of the 132 to 136 locked `[sandbox]` + enterprise packages has a Python 3.14 wheel on Linux x86-64 and Windows x64. On macOS arm64 the only one missing is `watchdog`, which this PR removes - Earlier, on Python 3.14.7 with litellm 1.101.0, 0.37.0's 1,236 LiteLLM-related tests produced the same result (1,157 passed) as on Python 3.12 with litellm 1.91.5 - Not tested: the new CI job itself (runs on this PR); Intel macOS, Windows on ARM and Alpine, which lack `onnxruntime` or `headroom-ai` wheels for other reasons ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: Python 3.14 installs now get LiteLLM, so USD savings are priced instead of $0.00. macOS on 3.14 no longer installs watchdog, so `--code-graph` live reindexing is off there unless watchdog is installed manually - Kill switch / disable path: n/a (dependency metadata) - Unsafe override required: no - Qualification impact: litellm floor rises from 1.86.2 to 1.96.2 on all Pythons - 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) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> |
||
|
|
7c4d696cf9 |
docs(readme): rebuild the README on the Headroom brand (#3392)
## What this is A visual rebuild of the README, using the **published brand** from [headroomlabs.ai/brand](https://www.headroomlabs.ai/brand) rather than colours invented for the occasion, and restoring the reference material an earlier draft of this branch had cut. ## The hero `.github/assets/hero.svg` — one animated SVG, 880×356. | Token | Hex | Use | |---|---|---| | Headroom Mint | `#00F0B5` | primary accent, the compressed bar, the logomark | | Obsidian Space | `#070A0F` | background | | Midnight Panel | `#0C1118` | the uncompressed bar | | Cyan Glow | `#65D8FF` | the cut line, the sweep | | Slate Muted | `#98A4B3` | secondary type | The logomark is reproduced at its **published geometry**, lifted from `favicon.svg` and scaled — not redrawn, not recoloured, not stretched. It happens to already be the product: two brackets around a long bar and a short one. Brand guidance says to place the mark on dark or high-contrast backgrounds, so there is **one dark hero for both GitHub themes**. The previous `<picture>` light variant would have put a mint mark on white, which the guidelines rule out. Three animations — the removed span fading, a cyan pass over the compressed bar, and both `FATAL` markers pulsing in step — all disabled under `prefers-reduced-motion`. ## Badges - **[Trendshift — #1 Repository Of The Day](https://trendshift.io/repositories/20881)**, restored. It was in the README before and the earlier draft dropped it. The claim is Trendshift's, not ours, which is the right way to make it. - A **live star count** beside it (68.4k at time of writing), in mint. - **No star-history chart.** star-history.com currently renders "GitHub restricted access to star data" in place of the graph, so restoring it would have added a large blank block. Worth revisiting when their API access is back. - **No codecov badge.** Under `headroomlabs-ai` codecov reports **6.7% across 524 files**; the old `chopratejas` project reported **65%**. The uploads have not fully landed since the org migration — a CI configuration issue, not a real drop. The badge goes back when the number is true. ## What came back The earlier draft removed these. All restored, with the long ones inside `<details>`: - **Output token reduction** — verbosity steering, effort routing, `headroom learn --verbosity`, `headroom output-savings` and the holdout control. An entire shipped capability that had gone missing. - **Agent compatibility matrix** — all 18 agents with their per-agent notes. - **Copilot CLI subscription mode**, **Copilot in VS Code**, **Claude Code in VS Code**. - **Corporate networks and SSL inspection** — `CERTIFICATE_VERIFY_FAILED`, the Intel macOS ONNX Runtime workaround (#941), and `HEADROOM_TLS_STRICT`. People arrive at a README searching for exactly this. - **`headroom learn`** and its GIF · **Headroom for teams** · **Integrations** · **What's inside** · **Pipeline internals** · **Updating** · **uv/pipx/MCP PATH notes**. ## Numbers Unchanged from the audited set. The Proof table still cites `benchmarks/index_proof_table.py --seed 20260902`; the accuracy table still cites `python -m headroom.evals suite --tier 1`; TruthfulQA's `+0.030` is still labelled as inside the confidence interval at N=100. Also new: a **Telemetry** section. The README had never disclosed that the beacon is on by default. It does now, with the opt-outs. ## Verification - SVG validated as XML, rendered headless and reviewed. - README rendered through GitHub's own markdown API and reviewed end to end — that is how the broken star-history chart was caught. - All 48 links checked. HuggingFace URLs deliberately stay on the `chopratejas` account, which was not part of the org migration. - HTML tag balance checked: 9 `<details>`, 9 `<summary>`, 3 `<div>`, all closed. 668 lines, 4,104 words — comparable to the 616/4,228 it replaces, but with the depth folded and a page that opens with something to look at. Conflicts with #3389's README hunks; take this version wholesale. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu --------- |
||
|
|
96dfc7005f |
chore: finish the org and docs-domain migration (#3389)
Two stale identities left over from moves that were only half applied. ## GitHub org `install/state.py` already migrated Docker images to `ghcr.io/headroomlabs-ai/headroom` and carries a `_DEPRECATED_IMAGE_REPO` constant that rewrites the old path on load — so this move was decided long ago. Everything else still said `chopratejas/headroom`. Rewritten across packaging (`pyproject.toml`, `Cargo.toml`), both plugin marketplaces, the agent-hooks manifests, install scripts, CI templates, crate docs and tests. **Two deliberate exclusions:** - **`ghcr.io/chopratejas/headroom` is untouched everywhere.** It is the *input* to `_migrate_deprecated_image()` and to the tests covering it. Rewriting it would silently disable the migration. - **`CHANGELOG.md` keeps its 238 historical references.** GitHub's rename redirect resolves them, and rewriting would bury this diff in noise. **HuggingFace model ids are NOT affected and were never in scope.** `chopratejas/kompress-base`, `kompress-v2-base`, `kompress-finance`, `technique-router`, `technique-router-onnx` and `siglip-image-encoder-onnx` are account-scoped identifiers on a different service. All six were validated against the HF API before this change: | Model | HTTP | |---|---| | `kompress-base` | 200 | | `kompress-v2-base` | 200 | | `technique-router` | 200 | | `technique-router-onnx` | 200 | | `siglip-image-encoder-onnx` | 200 | | `kompress-finance` | **401 (private)** | The 401 is unrelated to this migration, but worth knowing: `kompress_compressor.py:1255` references it, so that path is not reachable by an OSS user without access. **One functional fix, not cosmetic:** `_marketplace_source()` (`headroom/cli/init.py`) returned the old org as its fallback, so plugin installs were pointed at the retired repo. ## Docs domain The site moved to `docs.headroomlabs.ai`, but eleven references still named the vercel.app host — including **`llms.txt` (27 links)**, which is served at `docs.headroomlabs.ai/llms.txt` and read by LLM crawlers, the **dashboard's own Documentation link**, and a `headroom wrap` help message. The docs app's canonical-URL fallbacks were fixed separately in #3388. ## Also folded in `RUST_DEV.md` corrections found while verifying the above: - `make build-wheel` points at `Cargo.toml`, not `pyproject.toml` - the Rust toolchain is pinned, not tracking `stable` - `headroom-simulators` was missing from the workspace listing - the Python `CompressionStore` defaults to **SQLite**, not in-memory, when `HEADROOM_CCR_BACKEND` is unset (verified by execution) — this one matters for multi-worker reasoning And the install scripts pointed at `docs/docker-install.md`, a path that no longer exists; they now point at the live docs page. ## Verification 297 tests pass, including the plugin-manifest, install-state and release-workflow suites that assert on these exact strings. `ruff check` clean. Unrelated lockfile churn (`uv.lock`, both `package-lock.json`) is deliberately excluded. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
|
91af73fc04 |
test(copilot): validate authenticated Windows CLI and VS Code E2E (#3311)
## Summary - add a credential-safe live Copilot E2E driver for source builds - cover official Copilot CLI baseline, subscription wrapping, VS Code proxy routing, documented GPT-5.5/5.6 models, settings restoration, and the installed VS Code extension via `code chat` - fix a Windows shutdown race that could orphan a detached dedicated proxy - document current Windows auth behavior and GitHub's canonical response model IDs ## Live Windows validation Environment: - Headroom `0.37.0-dev` built from `27b4e2d1` with `uv sync --extra proxy --extra dev` - GitHub Copilot CLI `1.0.81` - VS Code stable `1.133.0` - dedicated Headroom Copilot OAuth device authorization Command: ```powershell uv run --no-sync python e2e/copilot_live.py --vscode-extension ` --model gpt-5-mini --model gpt-5.5 ` --model gpt-5.6-luna --model gpt-5.6-sol --model gpt-5.6-terra ``` Result: ```text PASS: Copilot baseline, CLI wrap, VS Code routing, model preservation, restore, and installed VS Code extension ``` The installed VS Code extension generated traffic through Headroom after `code chat -m ask`; metrics showed requests and no failures. Real VS Code settings were restored and no proxy listener remained. ## Findings - Headroom's dedicated device-auth flow works on Windows. - Copilot CLI 1.0.81 has a valid native login but does not expose the legacy Credential Manager target Headroom currently probes; users should run `headroom copilot-auth login`. - GitHub may canonicalize a requested alias in response metadata (for example `gpt-5.5` to `gpt-5.5-2026-04-23`). - Before the cleanup fix, Ctrl+C could race `/health` and leave the detached Windows proxy listening as `unidentified`. ## Verification - 225 focused Copilot/wrapper tests passed - Ruff check and format passed - mypy and repository pre-commit hooks passed - staged and committed-range gitleaks scans found no leaks - no credential values, device codes, fingerprints, local auth paths, or account identifiers are included |
||
|
|
eafdf11a2c |
fix(docker): ship Bedrock auth and current registry (#2982)
## Description Fixes #1551 and #1692. Every published Headroom Docker image now installs the existing `bedrock` extra, so `--backend bedrock` can authenticate with temporary STS, SSO, and credential-process credentials instead of failing because `botocore` is absent. Public Docker instructions now consistently use `ghcr.io/headroomlabs-ai/headroom`. Several still pointed at the old personal package, which is frozen at 0.27.0 and caused users to report that no latest image existed. ## Type of Change - [x] Bug fix - [ ] New feature - [ ] Breaking change - [x] Documentation update - [x] Build / CI ## Changes Made - Add `bedrock` to the standalone Dockerfile default extras. - Add `bedrock` to all nine root/code/slim/nonroot bake targets. - Replace obsolete personal GHCR references in README, llms.txt, Compose guidance, testing guidance, and wiki docs. - Add release contract tests for Bedrock dependencies and the current organization registry. ## Testing - [x] Focused Docker release and Bedrock preflight tests pass. - [x] Full updater suites pass: 69 tests. - [x] `uv run ruff check tests/test_release_workflows.py` - [x] `docker buildx bake --print` - [x] `git diff --check` ## Real Behavior Proof Before this change, every published bake target installed only `proxy` or `proxy,code`, so `AWS_SESSION_TOKEN` selected an unavailable botocore path. Public copy-paste commands also referenced `ghcr.io/chopratejas/headroom`, which the existing migration code and changelog identify as frozen at 0.27.0. After this change, all nine parsed bake targets install `bedrock`; the regression resolves that package extra and confirms `boto3` plus `botocore`. Every public Docker instruction covered by the contract names `ghcr.io/headroomlabs-ai/headroom`. ## Runtime Rollout Safety This changes image contents and documentation only; proxy routing and non-Docker installs are unchanged. Static AWS credentials remain unaffected. Existing manifests using the deprecated image continue to be migrated by the established install-state logic. Rollback is a Docker/bake extras and documentation revert. ## Review Readiness - [x] Two related Docker blockers batched in one PR - [x] Regression coverage included - [x] No unrelated lockfile changes - [x] Ready for review |
||
|
|
702a076fc1 |
docs(readme): surface the Serena opt-out in the wrap quickstart (#2790)
## Description The README quickstart announces that `headroom wrap` installs Serena, then stops — it offers no way to decline. The opt-out exists (`--code-memory none`) but was documented only on the docs site at `docs/content/docs/proxy.mdx:78`, which a README reader never reaches. In #2783 a user followed the quickstart verbatim, hit a Serena startup failure, and found the flag via `headroom wrap claude --help` only afterwards, while recovering the machine. Their words: *"a first-time user following the documented `headroom wrap claude` command has no signal that this failure mode exists or how to avoid it."* One line at the point where the install is announced closes that gap. Closes #2788 ## 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 - `README.md` — one sentence after the existing wrap paragraph: > Serena is registered at **user scope** (for Claude Code, in `~/.claude.json`), so it stays available in your other projects until you run `headroom unwrap`. To skip it entirely, wrap with `--code-memory none`. Two facts, both of which the #2783 reporter needed and could not find: the registration is user-scoped (so Serena shows up in projects that were never wrapped, until `unwrap`), and there is a flag to skip it. `docs/content/docs/quickstart.mdx` was checked for the same gap and has no equivalent wrap section — its only `wrap` mention is `vscode-claude` — so there is nothing to mirror. `proxy.mdx` already covers the flag and is unchanged. ## Testing - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [x] Manual testing performed A two-line Markdown addition to `README.md`. No Python, no config, no build inputs — pytest / ruff / mypy have nothing to cover. What was worth checking is that the sentence is *true*, so I verified both claims against the CLI on `main` rather than against the issue text. ### Test Output ```text $ grep -n '"--code-memory"' -A 2 headroom/cli/wrap.py 924: "--code-memory", 925- type=click.Choice([_CODE_MEMORY_SERENA, _CODE_MEMORY_NONE]), 926- default=None, $ headroom wrap claude --help | grep -A3 code-memory headroom wrap claude --code-memory none # No code-memory MCP ... --code-memory [serena|none] Code-memory MCP to register: 'serena' (default) or 'none'. Also set by HEADROOM_CODE_MEMORY. Replaces --serena/--no-serena. ``` ## Real Behavior Proof - **Environment:** macOS (darwin 25.4.0), repo `.venv`, branch cut from `upstream/main` @ `6b63b623`. - **Exact command / steps:** ran `headroom wrap claude --help` against the branch to confirm `none` is a real `click.Choice` value on the `claude` subcommand (not just on `wrap` generally, and not renamed since #2499 retired `--serena`/`--no-serena`). Read `headroom/mcp_registry/claude.py:128` to confirm the scope wording — registration is `claude mcp add <name> -s user`, with a file fallback writing top-level `mcpServers` in `~/.claude.json`, so "user scope" is accurate for Claude Code specifically. Grepped `docs/content/docs/quickstart.mdx` for wrap coverage to decide whether a mirror was needed. - **Observed result:** flag present and spelled as documented; `HEADROOM_CODE_MEMORY` is an equivalent env var (mentioned in `--help`, deliberately left out of the README line to keep it to one sentence); `quickstart.mdx` has no wrap-install paragraph to mirror into. - **Not tested:** did not run a real `headroom wrap claude` — the sentence describes existing behavior this PR does not change, and the registration scope is read from the code path above. Rendering not previewed on github.com; it is plain prose with two inline code spans and one bold span, matching the surrounding paragraphs. ## 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 - [ ] 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 - N/A on the test-related checklist items: prose-only change, nothing to assert. - Deliberately one sentence, not a Serena section. The quickstart should not become a Serena tutorial; it just needs the opt-out to be discoverable at the moment the install happens. - Related, not addressed here: **#2787** asks whether user scope should stay the default at all, since it is what let one failing MCP server degrade every Claude Code session in #2783. If that lands with project scope, this README line needs a one-word update — worth noting so the two do not drift. - The crash that prompted #2783 is already fixed on `main` by #2676 and ships in 0.34.0; this PR only closes the documentation half. |
||
|
|
13a310a00d |
feat(claude): support Claude Code in VS Code (#2752)
## Description Add first-class Headroom support for the official Claude Code extension in VS Code. The new wrapper starts the local proxy, configures the Claude Code user settings consumed by the embedded extension process, preserves authentication and model selection, and provides a conflict-safe reversible unwrap lifecycle. 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Add `headroom wrap vscode-claude` and `headroom unwrap vscode-claude`. - Configure project-scoped `ANTHROPIC_BASE_URL` plus `ENABLE_TOOL_SEARCH=true` in Claude Code user settings while preserving existing values. - Respect `CLAUDE_CONFIG_DIR`, macOS/Linux home paths, Windows `USERPROFILE`, custom `--settings-file`, and `--no-configure`. - Add durable Headroom-owned restore state and refuse malformed settings or conflicting user edits. - Add unit, CLI, and Docker-harness e2e coverage for configuration, real proxy forwarding, and restoration. - Document setup, remote development, undo, and troubleshooting. ## 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_NO_SYNC=1 uv run pytest -q tests/test_provider_claude_vscode_config.py tests/test_cli/test_wrap_vscode_claude.py tests/test_cli/test_wrap_vscode.py tests/test_cli/test_wrap_claude_base_url.py tests/test_provider_copilot_vscode_config.py tests/test_copilot_auth.py 160 passed in 0.45s $ UV_NO_SYNC=1 uv run ruff check . All checks passed! $ UV_NO_SYNC=1 uv run mypy headroom Success: no issues found in 512 source files $ npm run build # from docs/ Compiled successfully; generated 155 static pages ``` ## Real Behavior Proof - Environment: macOS, Python 3.13 editable install, isolated temporary HOME and Claude settings, local mock Anthropic Messages upstream. - Exact command / steps: invoked the new `verify_vscode_claude_wrap` e2e function, which launched real `headroom wrap vscode-claude`, waited for proxy readiness, POSTed an Anthropic `/v1/messages` request through the generated project-scoped URL, stopped the wrapper, then ran `headroom unwrap vscode-claude`. - Observed result: HTTP 200 with the mock Claude response through Headroom; generated settings retained unrelated values and enabled tool deferral; unwrap restored the original Claude settings. - Not tested: real Anthropic account traffic or the full Docker image locally because Docker Desktop was unavailable. The same e2e function is wired into the existing Docker wrap CI job. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project 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 adds CLI configuration and proxy routing without changing VS Code UI. ## Additional Notes The wrapper deliberately leaves the endpoint configured when stopped so requests fail closed instead of silently bypassing Headroom. `headroom unwrap vscode-claude` restores the exact prior managed values and preserves unrelated settings. --------- Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net> |
||
|
|
007446c73a |
feat(copilot): proxy VS Code models transparently (#2687)
## Description Make Headroom a transparent proxy for VS Code GitHub Copilot. Users keep using Copilot's normal model picker—GPT-4.1, Claude Sonnet, Claude Opus, and other models in their entitlement—while Headroom silently forwards the selected model instead of registering or requiring a separate "Headroom" model. This also fixes GitHub's device OAuth exchange by sending form-encoded request bodies, matching the endpoint contract. ## 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 - Add `headroom wrap vscode` to start a Copilot-seeded subscription proxy and safely configure VS Code's shipped Copilot proxy override. - Add `headroom unwrap vscode` for reversible cleanup. - Preserve VS Code's selected model by changing only the proxy URL/auth override; no custom model is registered and no model preference is written. - Support stable VS Code settings locations on macOS, Windows, and Linux, plus `--settings-file` for Insiders, portable, and other installations. - Edit JSONC settings with a marker-owned block while preserving unrelated bytes, comments, ordering, and trailing commas. - Refuse malformed markers, invalid JSONC, or unmanaged existing Copilot overrides instead of overwriting user configuration. - Fix SIGINT cleanup so the managed settings block is removed and normal shutdown exits successfully. - Fix Copilot device OAuth start/poll requests to use `application/x-www-form-urlencoded`. - Add a compatibility matrix, setup/removal flow, credential behavior, remote-development guidance, enterprise notes, troubleshooting, and verification documentation. ## Testing - [ ] 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 $ .venv/bin/pytest -q tests/test_provider_copilot_vscode_config.py tests/test_cli/test_wrap_vscode.py tests/test_cli/test_wrap_helpers.py tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_provider_copilot_wrap.py tests/test_cli/test_wrap_copilot.py tests/test_copilot_provider_label.py tests/test_copilot_subscription_smoke.py 244 passed in 0.59s $ .venv/bin/ruff check <changed Python files and tests> All checks passed! $ .venv/bin/mypy headroom/providers/copilot/vscode.py Success: no issues found in 1 source file $ cd docs && npm run types:check fumadocs-mdx && next typegen && tsc --noEmit # exited 0 $ git diff --check # exited 0 ``` The full 10,179-test suite was also sampled through approximately 83%, but was stopped because of its runtime. It exposed existing failures in `test_recover_codex.py`, `test_wrap_stale_marker.py`, and `test_proxy_health.py`; therefore the broad `pytest`, repository-wide Ruff, and repository-wide mypy boxes are intentionally not checked. ## Real Behavior Proof - Environment: macOS arm64, VS Code 1.131.0, built-in GitHub Copilot 0.59.0, Headroom 0.33.1-dev. - Exact command / steps: 1. Completed `headroom copilot login` with GitHub's device flow. 2. Ran `.venv/bin/headroom wrap vscode --port 8788`. 3. Confirmed VS Code retained its ordinary Copilot model catalog and made `GET /models` through Headroom with `GitHubCopilotChat/0.59.0` and `editor-version: vscode/1.131.0`. 4. Sent native Copilot `/p/headroom/chat/completions` requests through the same endpoint using `gpt-4.1`, `claude-sonnet-4.6`, and `claude-opus-4.7`. - Observed result: - All three completion requests returned HTTP 200. - GPT-4.1 resolved upstream to `gpt-4.1-2025-04-14`; Sonnet and Opus retained their exact selected IDs. - All returned the requested exact marker content. - VS Code's settings contained only the Headroom proxy URL and token auth override—no Headroom model or model-selection setting. - The proxy health endpoint remained ready with `openai_api_url` set to `https://api.githubcopilot.com`. - Not tested: - Physical Windows or Linux hosts (their path/config behavior is covered by unit tests). - WSL, dev containers, SSH remotes, VS Code Insiders, or enterprise Copilot deployments end-to-end. - Every model in the live Copilot catalog. - A fully submitted chat from VS Code's UI automation; the real extension's catalog request and native completion paths were verified separately. ## 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 - [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 integration intentionally has no separate UI or model entry. ## Additional Notes The integration uses VS Code Copilot's shipped advanced/debug proxy endpoint seam. The managed settings block is deliberately narrow and reversible. Remote extension hosts may need their own reachable proxy/configuration as documented. --------- Co-authored-by: JerrettDavis <2610199+JerrettDavis@users.noreply.github.com> |
||
|
|
e0ce4b1d48 |
fix: remove rtk and lean-ctx CLI context tools (#2677)
## Description Removes both third-party CLI context tools — **rtk** and **lean-ctx** — and with them the context-tool selector itself. Headroom no longer downloads, installs or configures either one, and there is no replacement. The previous pass (#2344) gated only three entry points inside `headroom/cli/wrap.py`. That left the feature reachable in practice: | Gap | Effect | |---|---| | `scripts/install.sh:1544`, `install.ps1:1681` | Ran `rtk init --global --auto-patch` from bash/PowerShell, **bypassing the Python gate entirely** — `curl \| sh` still wrote a Claude Code `PreToolUse` hook regardless of `HEADROOM_RTK` | | `wrap.py` `_setup_context_tool_for_agent` | **`wrap openhands` was broken by default**: `rtk_required=True` met a gate returning `None` → `SystemExit(1)`. Invisible because all 8 openhands tests patched `_ensure_rtk_binary` to a fake path | | `proxy/helpers.py`, `subscription/tracker.py` | Proxy shelled out to `rtk gain` from `/stats`, the dashboard and `headroom perf`; the tracker polled it per contribution (`_RTK_WIRING_DEFAULT = "enabled"`) | | No cleanup path | Nothing removed artifacts an earlier default had installed, so a machine that once ran the old default kept rtk in the loop forever (#1669, #1955) | Also worth noting: the rtk binary download had **no SHA or signature verification** — only `rtk --version` as a smoke test. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [x] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [x] Code refactoring (no functional changes) ## Changes Made **Removed** — `headroom/rtk/` and `headroom/lean_ctx/` packages, `headroom/cli/wrap_rtk_metrics.py`, `_selected_context_tool` / `_setup_context_tool_for_agent` / `_VALID_CONTEXT_TOOLS`, the `--rtk` / `--no-rtk` / `--no-project-rtk` / `--keep-rtk` flags across all 18 wrap subcommands, `HEADROOM_RTK*`, the proxy-side `rtk gain` polling, the dashboard CLI-filtering panel (rows + all 8 `cliFiltering*` Alpine getters), `paths.rtk_path()` / `lean_ctx_path()`, the SDK path helpers, `benchmarks/rtk_loop_learn_eval.py`, and the `headroom/rtk/**` CI path filters. **Fails loudly, not silently** — `--context-tool` / `--no-context-tool` / `HEADROOM_CONTEXT_TOOL` are kept solely to error out. They live in shell profiles, aliases and CI jobs, and accepting them as a no-op would read as Headroom having quietly stopped working. The installers reject them too, which matters more than it looks: their arg parsers forward the first unknown flag **and everything after it** to the wrapped tool, so a leftover `--no-rtk` would have silently swallowed a following `--port` and then been ignored downstream. **New `headroom/context_tool_cleanup.py`** — deleting the code cannot help a machine that already ran the old default, since the hooks, binaries and injected guidance are durable on disk. `purge_context_tool_artifacts()` runs once per `wrap`/`unwrap` and removes the registered hook entries, the generated hook scripts, the Headroom-managed `~/.local/bin` symlinks, the vendored `~/.headroom/bin/{rtk,lean-ctx}` binaries, the `lean-ctx` MCP server entry and the marker-fenced instruction blocks. Deliberately conservative: idempotent, **skips** a malformed config rather than overwriting it, and only unlinks a symlink resolving inside Headroom's own bin dir so a user's own build is untouched. It reports on **stderr**, because `wrap/unwrap openclaw --prepare-only` emit machine-readable JSON on stdout as their entire contract. Skipped for `wrap selfheal` (runs from a SessionStart hook; must not race Claude Code's writer for `~/.claude.json`) and for `--help`, which must stay read-only. **Client-config hardening** (discovered while investigating a "corrupted Serena settings file" report) — `wrap.py` reset a settings file to `{}` when an existing file would not parse, then wrote that back. One hand-edited typo or a transient `EACCES`/`EINTR` on a valid file destroyed the user's `permissions`, `env` and `hooks`, on **every `headroom wrap claude`**. It now refuses to write. Separately, `fsutil.write_text` is now atomic (temp file + `fsync` + `os.replace`), fixing all 14 non-atomic client-config writes at once; it follows symlinks rather than replacing them (dotfile managers) and preserves an existing file's mode. **Deliberately kept** — `rtk` stays in the wrapper-peel list in `transforms/content_router.py`. It sits beside `sudo`/`env`/`timeout` as shell-command grammar, so `rtk cat f` is still classified as a file read for anyone running their own rtk install, which the purge intentionally leaves alone. ## 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 $ ruff check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates All checks passed! $ ruff format --check headroom/ tests/ e2e/ --exclude headroom/dashboard/templates 1255 files already formatted $ mypy headroom/ Success: no issues found in 508 source files $ pytest tests/test_context_tool_cleanup.py -q 11 passed $ pytest tests/test_fsutil.py -q 12 passed $ pytest tests/test_cli/test_wrap_codex.py -q # 89 tests 89 passed in 431.68s $ pytest tests/test_cli/test_wrap_opencode.py -q 39 passed in 257.46s $ pytest tests/test_cli/test_wrap_helpers.py -q 45 passed $ pytest tests/test_paths.py -q 75 passed $ pytest tests/test_cli/test_unwrap_claude.py -q 14 passed $ pytest tests/test_proxy_savings_history.py -q 39 passed $ pytest tests/test_cli/test_wrap_copilot.py -q 27 passed $ pytest tests/test_cli/test_wrap_zcode.py -q 20 passed $ pytest tests/test_subscription_tracker.py -q 9 passed $ pytest tests/test_proxy_dashboard_stats_cache.py -q 5 passed, 1 skipped ``` Repo-wide grep for 14 removed symbols (`headroom.rtk`, `headroom.lean_ctx`, `_ensure_rtk_binary`, `_selected_context_tool`, `_get_context_tool_stats`, `rtk_path`, `lean_ctx_path`, `wrap_rtk_metrics`, `HEADROOM_RTK`, `cli_tokens_avoided`, `tokens_saved_rtk`, …) across `*.py`, `*.ts`, `*.sh`, `*.ps1`, `*.yml`, `*.html`: **zero hits**. Notable test changes: `test_wrap_openhands.py` no longer patches `_ensure_rtk_binary` and asserts `wrap openhands --prepare-only` exits 0 unpatched — the regression that was previously masked. `test_wrap_continue.py` and `test_wrap_hintfile_agents.py` were removed (every test drove RTK instruction injection). A new `test_subscription_tracker.py::test_load_state_written_before_cli_context_tools_were_removed` proves a pre-removal `subscription_state.json` still loads. ## Real Behavior Proof - **Environment:** macOS 15.4 (darwin 25.4.0), Python 3.12.6, Headroom @ this branch, real `~/.headroom` and `~/.claude` on the dev machine. - **Exact command / steps and observed result:** ```text # 1. Retired flag fails loudly instead of silently no-op'ing $ headroom wrap codex --prepare-only --context-tool rtk Error: CLI context tools (rtk, lean-ctx) have been removed from Headroom: they rewrote shell commands through a third-party binary Headroom no longer manages. Drop --context-tool / --no-context-tool and unset HEADROOM_CONTEXT_TOOL; `headroom wrap` uninstalls what they left behind on first run. $ HEADROOM_CONTEXT_TOOL=lean-ctx headroom wrap codex --prepare-only Error: CLI context tools (rtk, lean-ctx) have been removed from Headroom: ... # 2. install.sh rejects the retired flags (extracted parse_wrap_args harness) ['--no-rtk', '--port', '9999'] rc=1 ERROR: CLI context tools ... Drop --no-rtk ['--context-tool=rtk'] rc=1 ERROR: CLI context tools ... Drop --context-tool $ bash -n scripts/install.sh # syntax OK # 3. Purge ran against the real machine, which had all the orphaned artifacts $ python -c "from headroom.context_tool_cleanup import purge_context_tool_artifacts; ..." removed ~/.headroom/bin/lean-ctx (51 MB) removed ~/.headroom/bin/rtk (7.7 MB) removed ~/.local/bin/rtk (symlink into ~/.headroom/bin) removed ~/.claude/hooks/rtk-rewrite.sh removed 8 lean-ctx-* hook scripts # ~/.claude.json afterwards: 90 top-level keys, 19 projects, mcpServers unchanged # → ~59 MB reclaimed, no unrelated key touched # 4. stdout stays machine-readable while the purge reports (planted a fake artifact) $ headroom wrap openclaw --prepare-only --gateway-provider-id codex >out 2>err $ cat out {"enabled":true,"config":{"proxyPort":8787,...}} # parses as JSON $ cat err Retired CLI context tool cleanup: removed /Users/tcms/.headroom/bin/rtk # 5. --help is inert (planted artifact survives), a real run purges $ headroom wrap codex --help → artifact survived: CORRECT $ headroom wrap openclaw --prepare-only → purged: CORRECT # 6. MCP purge dry-run against a copy of the real 82 KB ~/.claude.json top-level keys 90 -> 90; projects 19 -> 19; LOST keys: none all content outside mcpServers byte-identical: True ``` Dashboard rendered via the Playwright test after the panel removal: "Token Savings" shows only `Proxy 0 (0.0%)` / `Of total wire: 36.86%`, and "Token Usage" reads Before Compression → Proxy Removed → After Compression with no "Filtered (this session)" row. Nothing below the removed panel broke. - **Not tested:** Windows and Linux (macOS only) — `install.ps1` is verified by brace-balance and inspection, not executed, since no `pwsh` is available locally. The wrap e2e suite (`e2e/wrap/run.py`) was updated but not run; it needs the Docker e2e image. `serena project index` interaction is exercised in the stacked base 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) ## Additional Notes **Stacked on #2676** (`tejas/serena-config-bootstrap`) — please merge that first; this PR's base should then be retargeted to `main`, or it will read as containing that fix too. **Breaking-change migration for users:** - Drop `--rtk`, `--no-rtk`, `--no-project-rtk`, `--keep-rtk`, `--context-tool`, `--no-context-tool` from any alias, script or CI job, and unset `HEADROOM_RTK*` / `HEADROOM_CONTEXT_TOOL`. They now error rather than being ignored, so the failure is immediate and self-explaining. - Previously-installed artifacts are purged automatically on the next `wrap`/`unwrap`; no manual cleanup needed. - `headroom perf --json` no longer carries a `cli_filtering` key, and `/stats` no longer returns a `context_tool` section. **Docs:** `docs/rtk-architecture.md` deleted; RTK/lean-ctx removed from `README.md`, `docs/content/docs/{configuration,opencode,grok-build,docker-install,filesystem-contract}.mdx`, `docs/observability.md` and the matching `wiki/` pages. `REALIGNMENT/09-phase-G-rtk-observability.md` is marked SUPERSEDED rather than deleted, to keep the planning record. **Follow-ups not in scope:** `_emit_wrap_interrupted` was deleted as dead code — its only caller was the `except KeyboardInterrupt` guarding the binary download, so with no download there is nothing slow left to interrupt. |
||
|
|
a6a4def78a |
docs(readme): describe CacheAligner as detector-only (#2598)
## Description
README still described CacheAligner as a component that stabilizes
prefixes for provider KV cache hits. On current main, CacheAligner is
detector-only: it warns about volatile content and does not rewrite
prompts. Prefix stability is already covered by live-zone compression.
Closes #2592
## 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
- Updated the How it works CacheAligner bullet to detector-only
detect/warn wording
- Updated the What's inside CacheAligner bullet the same way
- Left the architecture diagram stage name and live-zone compression
description unchanged
## 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
$ rg -n "CacheAligner" README.md
69: │ CacheAligner → ContentRouter → CCR │
83:- **CacheAligner** - detects and warns about volatile content that can bust provider KV cache prefixes; never rewrites prompts
322:- **CacheAligner** - detects and warns about volatile content that can bust provider KV cache prefixes; never rewrites prompts.
338:- **Transforms** do the work: CacheAligner → ContentRouter → SmartCrusher / CodeCompressor / Kompress-base (live-zone only; IntelligentContext and RollingWindow were retired in PR-B1).
$ rg -n "CacheAligner.*stabilizes prefixes" README.md || echo OLD_CLAIM_ABSENT
OLD_CLAIM_ABSENT
$ git diff --stat
README.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
```
## Real Behavior Proof
- Environment: Linux VPS, Python 3.11.15, sparse checkout of
headroomlabs-ai/headroom main at
|
||
|
|
e4076bbe99 |
fix(grok): preserve business-seat auth while routing only inference (#2514)
## Description `headroom wrap grok` currently routes the whole session through `GROK_CLI_CHAT_PROXY_BASE_URL`. xAI's July 21, 2026 enterprise docs say that host carries both inference and settings, so the wrap displaces the native settings/auth path along with inference. A Grok account whose SuperGrok entitlement lives on a business account can then no longer resolve that seat and falls back to a login screen, even though native `grok` works for the same account. This change retargets the Grok provider slice to the narrower inference-only key, `GROK_MODELS_BASE_URL`, and leaves `GROK_CLI_CHAT_PROXY_BASE_URL` unset. Headroom still intercepts inference and model discovery through the existing `/v1/models` and chat-completions proxy paths, while the native `cli-chat-proxy.grok.com` settings host and `auth.x.ai` auth path stay intact. Closes #2489. ## 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - switch the Grok provider env authority from `GROK_CLI_CHAT_PROXY_BASE_URL` to `GROK_MODELS_BASE_URL` - update the Grok wrap and unwrap docstrings to describe inference-only routing and the preserved native settings/auth path - update the compatibility matrix entry in `README.md` so the public docs match the new Grok routing key - add focused provider and wrap tests that assert the old chat-proxy key is absent and the project-prefixed inference URL is preserved - keep `grok_build` and the existing `/v1/models` proxy route unchanged, using them as preservation boundaries ## Testing - [x] Unit tests pass (`uv run pytest tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py tests/test_provider_grok_build.py -q`) - [x] Linting passes (`uv run ruff check headroom/providers/grok/runtime.py headroom/cli/wrap.py tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py`) - [ ] Type checking passes (`uv run mypy headroom`) - [x] New tests added for new functionality when applicable - [ ] Manual testing performed ### Test Output ```text uv run pytest tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py tests/test_provider_grok_build.py -q uv run ruff check headroom/providers/grok/runtime.py headroom/cli/wrap.py tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py uv run ruff format headroom/providers/grok/runtime.py headroom/cli/wrap.py tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py --check ``` ## Real Behavior Proof - Environment: current Grok CLI plus a focused Headroom worktree - Exact command / steps: capture `grok --version`, re-check xAI's documented Grok env contract, run the focused Grok provider and wrap tests, and if a business-seat account is available locally launch `headroom wrap grok` to confirm the wrapped session no longer falls back to login - Observed result: Headroom emits only the inference-routing key, the old settings/auth key is absent, project prefixing still works, and the focused Grok tests pass - Not tested: local business-seat account on this host ## 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 ## Screenshots (if applicable) N/A - CLI and provider-routing change only. ## Additional Notes - `CHANGELOG.md` stays untouched because Headroom's release automation generates it from conventional commits. - The issue is reporter-only today, so the proof report records the validated `grok --version` and whether a real business-seat retest was reached locally or remains for the reporter. |
||
|
|
5d23a0aec2 |
refactor(wrap): retire tokensave; Serena is the code-memory MCP (#2499)
## Description
`tokensave` was a **downloaded third-party Rust binary**
(`aovestdipaperino/tokensave`) that `headroom wrap` registered as a
code-graph MCP server. This removes it entirely and standardises on
**Serena** as the code-memory MCP — which was already the default in
`wrap`. Serena runs on demand via `uvx`, so Headroom no longer downloads
or executes a binary of its own for code memory.
The change is a *removal + safe transition*, not a behaviour flip:
Serena was already the default, so existing users move over
automatically. This PR also folds in a small README repositioning
(Headroom = the proxy; Serena is the recommended companion; RTK/lean-ctx
are third-party tools we don't control), since it's the same
tooling-stack story.
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)
- [x] Documentation update
- [x] Code refactoring (no functional changes)
## Changes Made
- **Removed the external tool:** `headroom/graph/tokensave_installer.py`
(the download-and-execute path), `build_tokensave_spec`, and the
`_ensure_tokensave_binary` / `_index_tokensave_project` /
`_setup_tokensave_mcp` helpers; dropped the dead `_setup_code_graph`.
- **`--code-memory`** now offers `serena` (default) or `none` — the
`tokensave` choice is gone. The strands `HeadroomBundle` uses Serena as
its (default-on) code-memory MCP.
- **Tombstone / transition (ledger-verified):** `headroom wrap` **and**
`headroom unwrap` remove a previously Headroom-installed `tokensave` MCP
entry so upgrading users stop launching it, and print that the leftover
`~/.local/bin/tokensave` binary and `.tokensave/` folders are safe to
delete. A user-managed `tokensave` entry is left untouched. Mirrors the
existing `codebase-memory-mcp` retirement.
- **Graceful for existing users:** `HEADROOM_CODE_MEMORY=tokensave` and
`--no-tokensave` resolve to Serena instead of erroring; `--no-serena`
now means "no code memory". **No state migration needed** — both tools'
indexes are regenerable caches of the source, so Serena simply
re-indexes.
- **Docs/README:** replaced the "tokensave binary trust model" section
with a Serena note + an "Upgrading from tokensave?" callout; retired the
RTK "first-class part of our stack" framing.
- **Tests:** deleted the tokensave-only test files
(`test_graph_tokensave.py`, `test_cli/test_tokensave_helpers.py`,
`test_cli/test_tokensave_setup.py`), rewrote `test_wrap_code_memory.py`
for the new resolver/dispatch, fixed a codex test that patched a removed
symbol.
Net: **+102 / −1187 lines.**
## Testing
- [x] Unit tests pass (`pytest`) — targeted to the affected areas
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ ruff check headroom/cli/wrap.py headroom/mcp_registry/ headroom/integrations/strands/ tests/test_wrap_code_memory.py tests/test_cli/conftest.py tests/test_cli/test_wrap_codex.py
All checks passed!
$ mypy headroom/cli/wrap.py headroom/mcp_registry headroom/integrations/strands/bundle.py
Success: no issues found in 12 source files
$ pytest tests/test_wrap_code_memory.py tests/test_cli/test_wrap_codex.py \
tests/test_cli/test_wrap_claude_vertex_proxy_env.py \
tests/test_cli/test_wrap_claude_finally_unbound.py -q
======================== 120 passed in 97.86s (0:01:37) ========================
$ pytest tests/test_cli --collect-only -q
========================= 713 tests collected in 1.82s ========================= # no import errors after symbol removal
```
## Real Behavior Proof
- **Environment:** macOS (darwin), Python 3.12.6, local `.venv`, on
branch `tejas/remove-tokensave`.
- **Exact command / steps:**
- `python -c "from headroom.integrations.strands.bundle import
HeadroomBundle; b=HeadroomBundle(enable_headroom_mcp=False,
enable_serena_mcp=False); print(len(b.tools))"` → confirms the module
imports after `build_tokensave_spec` removal (the import that my change
would otherwise break).
- CliRunner-driven `wrap codex --prepare-only` (in `test_wrap_codex.py`)
writes `[mcp_servers.serena]` (with `command = "uvx"`, `"--context",
"codex"`) to the codex config and **no** tokensave entry.
- `_resolve_code_memory` unit tests confirm: default → `serena`;
`HEADROOM_CODE_MEMORY=tokensave` → `serena`; `--no-serena` → `none`;
`--code-memory bogus` → `ClickException`.
- **Observed result:** import OK (`tools: 0`); Serena registered,
tokensave absent; resolver behaves as above; 120/120 tests pass.
- **Not tested:** a live `headroom wrap` against a real agent on a
machine with a *previously-installed* tokensave MCP entry — the
tombstone-removal path is covered by unit tests with a fake
registrar/ledger, not an end-to-end run.
## 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
## Additional Notes
- `--no-tokensave` / `--serena` / `--no-serena` are retained as hidden,
deprecated flags (no-ops or mapped) so existing scripts don't break.
- `--code-graph` is unchanged — it's the proxy's live file-watcher flag
and was never the tokensave MCP; only the dead tokensave hook behind it
was removed.
- `CHANGELOG.md` intentionally left untouched.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||
|
|
eac49656a1 |
feat(wrap): add headroom wrap kimi for Kimi CLI (#1426)
## Description Adds `headroom wrap kimi`, routing Kimi CLI through the Headroom proxy. Kimi CLI speaks an OpenAI-compatible `/chat/completions` API (its `kosong` backend wraps `AsyncOpenAI`) and lets the base URL be overridden via `KIMI_BASE_URL`. This wrapper points it at the local proxy. Kimi's own OAuth bearer is forwarded upstream unchanged, so — unlike the Copilot subscription path — no extra login or token exchange is needed. ## Type of Change - [x] New feature (non-breaking change that adds functionality) ## Changes Made - `headroom/providers/kimi/`: new slice; `build_launch_env` sets `KIMI_BASE_URL` with the per-project base-URL prefix, mirroring the aider/vibe slices. - `headroom/cli/wrap.py`: `kimi` subcommand; falls back to the `kimi-cli` binary when `kimi` is not on `PATH`; `--kimi-api-url` overrides the upstream coding endpoint (default `https://api.kimi.com/coding/v1`). - `tests/test_cli/test_wrap_kimi.py`: 8 tests for the wrap command. - `README.md`: Kimi CLI row in the agent-compatibility matrix. ## 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_cli/test_wrap_kimi.py -q ........ [100%] 8 passed in 0.36s $ ruff check headroom/providers/kimi headroom/cli/wrap.py tests/test_cli/test_wrap_kimi.py All checks passed! $ ruff format --check headroom/providers/kimi headroom/cli/wrap.py tests/test_cli/test_wrap_kimi.py 4 files already formatted ``` ## Real Behavior Proof - Environment: macOS; Kimi CLI (`kimi` / `kimi-cli`); `headroom proxy` started with `--openai-api-url https://api.kimi.com/coding/v1`. - Exact command / steps: start `headroom proxy --port 8787 --openai-api-url https://api.kimi.com/coding/v1`, then `curl -s http://localhost:8787/v1/chat/completions` with the Kimi OAuth bearer and a one-line `kimi-for-coding` chat request (`"Reply with exactly: PONG"`). - Observed result: `HTTP 200`; `choices[0].message.content == "PONG"` from `kimi-for-coding`; the OAuth bearer was forwarded and accepted upstream; the per-project path `/p/<name>/v1/chat/completions` also returned `HTTP 200`. - Not tested: Windows/Linux PATH discovery; the `--learn` / `--memory` live paths beyond flag wiring. ## 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 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 ## Additional Notes - `ruff check` and `ruff format --check` pass locally; `mypy` was run on the new `headroom/providers/kimi` slice only (clean), so the full-tree `mypy headroom` box is left unchecked and is left to CI. - The slice deliberately reuses `codex.proxy_base_url` and `with_project_prefix`, identical to the aider/vibe wrappers, so per-project savings attribution works without Kimi sending custom headers. - Kimi's separate search/fetch services are out of scope for `KIMI_BASE_URL` and continue to hit Kimi directly; only the LLM `/chat/completions` traffic is compressed. Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
5424e99a65 |
Clarify uv tool install path on macOS (#1196)
## Description Clarifies the recommended install path for the Headroom CLI on macOS Apple Silicon and Linux. The docs now prefer `uv tool install --python 3.13 "headroom-ai[all]"` for host-level CLI use, keep `pip install` scoped to Python project environments, and call out absolute executable paths for MCP clients that do not inherit interactive shell `PATH`. ## 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 - Added `uv tool install --python 3.13` guidance to the README, docs install page, quickstarts, and wiki install pages. - Documented `uv tool update-shell` for shells that cannot find the installed `headroom` command. - Clarified absolute MCP server command paths for clients that do not inherit the interactive shell `PATH`. - Pointed Intel macOS users at the Docker-native install path until native wheel support lands. ## Testing Describe the tests you ran to verify your changes: - [ ] Unit tests pass (`pytest`) - not run; docs-only change. - [ ] Linting passes (`ruff check .`) - not run; docs-only change. - [ ] Type checking passes (`mypy headroom`) - not run; docs-only change. - [ ] New tests added for new functionality - not applicable. - [x] Manual testing performed - [x] `git diff --check upstream/main...HEAD` ## Real Behavior Proof ```bash $ git diff --check upstream/main...HEAD # exits 0; no whitespace errors ``` `npm --prefix docs run types:check` was also attempted. It regenerated MDX and route types successfully, then failed in existing docs app code because `@/lib/...` imports cannot resolve from files such as `app/(home)/layout.tsx`, `app/api/search/route.ts`, and `components/button.tsx`. This PR only changes `README.md`, `docs/content/docs/installation.mdx`, `docs/content/docs/quickstart.mdx`, and `wiki/*.md` files. ## Review Readiness - [x] Draft PR; docs wording and install-path accuracy are ready for review. - [x] No code or runtime files changed. - [x] Known docs type-check blocker is documented above. ## Test Output ```bash $ git diff --check upstream/main...HEAD # no output ``` ```text $ npm --prefix docs run types:check [MDX] generated files ✓ Types generated successfully app/(home)/layout.tsx(2,29): error TS2307: Cannot find module @/lib/layout.shared or its corresponding type declarations. ... components/button.tsx(4,20): error TS2307: Cannot find module @/lib/cn or its corresponding type declarations. ``` ## 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 - not applicable; docs-only change. - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - not applicable; docs-only change. - [ ] New and existing unit tests pass locally with my changes - not run; docs-only change. - [ ] I have updated the CHANGELOG.md if applicable - not applicable. ## Screenshots (if applicable) Not applicable. ## Additional Notes The PR remains a draft while docs verification is limited by the existing docs app `@/lib/*` resolution issue. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
fcf455a7eb |
feat(wrap): add omp target (Oh My Pi) with models.yml override and unwrap (#1811)
## Description Adds `headroom wrap omp` / `headroom unwrap omp` — a one-command wrap for [Oh My Pi](https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent) (`omp`), the pi-mono-lineage coding agent, as proposed in #1149. One honest correction to the issue: #1149 proposed reusing the `ANTHROPIC_BASE_URL` redirect from `wrap claude`. During implementation I probed that empirically and it turned out to be wrong — omp only reads `ANTHROPIC_BASE_URL` in its web-search helper; its **chat** endpoint comes from the model registry (`providers.anthropic.baseUrl` in `~/.omp/agent/models.yml`). With the env var pointed at a local probe server, omp's chat traffic still went straight to the real endpoint (0 probe hits); with a `models.yml` same-ID override, every request arrived at the probe (9/9 hits on `/v1/messages`). A same-ID override keeps omp's bundled Anthropic model catalog and stored credentials (both keyed by provider id `anthropic`), so only the endpoint moves. The wrap therefore injects a marker-fenced `providers.anthropic.baseUrl` override into `models.yml`, snapshotting the pre-wrap file **byte-for-byte** first, and `headroom unwrap omp` restores it exactly (or removes the file when the wrap created it) — the same durable-wrap + backup + unwrap contract `wrap codex` uses for `config.toml`. Closes #1149 ## 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/providers/omp/` (new provider slice): `models_yml_path()` (honors `PI_CODING_AGENT_DIR`), `inject_models_override()` (yaml-merge preserving user providers; pristine byte-for-byte backup, never re-snapshotted while managed), `restore_models_override()` (`restored` / `removed` / `noop`; never touches an unmanaged file), `build_launch_env()` - `headroom/cli/wrap.py`: `wrap omp` (mirrors the aider/vibe `_launch_tool` shape; rtk instructions into the project's `AGENTS.md`, which omp reads natively) and `unwrap omp` (restore models.yml + scrub rtk block + stop proxy) - `headroom/telemetry/context.py`: `omp` added to `_KNOWN_WRAP_AGENTS` so the stack slug reports `wrap_omp` instead of `unknown` - `README.md` (agent matrix row + unwrap list), `llms.txt`, `CHANGELOG.md` - `tests/test_cli/test_wrap_omp.py`: 16 tests (injection fresh/merge/re-inject, restore statuses incl. unmanaged-file safety, env passthrough, CLI wiring, unwrap flows) ## Testing - [ ] Unit tests pass (`pytest`) — all new + `test_cli` tests pass; the full suite carries **3 pre-existing failures** that reproduce identically on unmodified `origin/main` (same set, same asserts — see Test Output and the rebase-validation comment) - [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 pytest -q # post-rebase, base |
||
|
|
cb388f6af2 |
feat(wrap): add first-class Grok CLI support (#1823)
## Description
Adds first-class Grok CLI integration so Headroom can wrap, compress,
and learn from Grok sessions the same way it does for Claude Code and
Codex.
Grok routes inference through `GROK_CLI_CHAT_PROXY_BASE_URL`; Headroom
sets that to the local proxy so chat traffic is compressed before
forwarding to xAI. MCP retrieval and session learning follow the same
patterns as Codex.
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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- Add `headroom/providers/grok/` provider slice (`runtime.py`,
`install.py`) with `GROK_CLI_CHAT_PROXY_BASE_URL` routing and project
attribution prefix
- Add `headroom wrap grok` and `headroom unwrap grok` CLI commands (MCP
registration, RTK/context-tool setup, proxy launch)
- Add `GrokRegistrar` for marker-delimited `[mcp_servers.headroom]`
injection in `~/.grok/config.toml`
- Add `headroom learn --agent grok` plugin parsing
`~/.grok/sessions/*/updates.jsonl` and `GrokWriter` targeting `GROK.md`
- Register Grok in install planner, install registry, MCP install list,
and agent savings tracking
- Update README agent compatibility matrix and unwrap support list
- Add unit tests for provider, wrap CLI, MCP registrar, and learn plugin
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed
### Test Output
```text
$ uv run pytest tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py tests/test_mcp_registry_grok.py tests/test_learn_grok_plugin.py -q
============================== 10 passed in 0.15s ==============================
$ uv run ruff check headroom/providers/grok headroom/mcp_registry/grok.py headroom/learn/plugins/grok.py headroom/cli/wrap.py headroom/learn/writer.py
All checks passed!
$ uv run mypy headroom/providers/grok headroom/mcp_registry/grok.py headroom/learn/plugins/grok.py
Success: no issues found in 5 source files
```
## Real Behavior Proof
- Environment: macOS (darwin), Python 3.13.14 via `uv`, repo at
`/Users/s/dev/headroom`, Grok CLI at `/Users/s/.grok/bin/grok`
- Exact command / steps: `cd /Users/s/dev/headroom && uv run pytest
tests/test_provider_grok.py tests/test_cli/test_wrap_grok.py
tests/test_mcp_registry_grok.py tests/test_learn_grok_plugin.py -q`; `uv
run ruff check headroom/providers/grok headroom/mcp_registry/grok.py
headroom/learn/plugins/grok.py`; `uv run python -c "from
headroom.providers.grok import build_launch_env; env, display =
build_launch_env(8787, environ={}); print(display[0])"`; `uv run python
-c "from pathlib import Path; import tempfile; from
headroom.mcp_registry.grok import GrokRegistrar; from
headroom.mcp_registry.install import build_headroom_spec;
td=tempfile.mkdtemp(); reg=GrokRegistrar(home_dir=Path(td));
print(reg.register_server(build_headroom_spec('http://127.0.0.1:8787'),
force=True).status.value)"`
- Observed result: pytest reported `10 passed`; ruff reported `All
checks passed!`; `build_launch_env` printed
`GROK_CLI_CHAT_PROXY_BASE_URL=http://127.0.0.1:8787/v1`; MCP registrar
returned `registered` and wrote the Headroom marker block to
`config.toml`
- Not tested: live `headroom wrap grok` session with authenticated Grok
API traffic through a running Headroom proxy (requires maintainer
environment with active `grok login`)
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Screenshots (if applicable)
N/A — CLI/integration change only.
## Additional Notes
- Follows the provider-slice pattern from `b17c6d81` / `93a1f211`
(Codex/Cursor/Aider extraction).
- Routing uses the session env var only (not `config.toml` endpoint
override) so `grok login` session auth continues to work.
- Manual E2E wrap/unwrap with real Grok sessions is left for maintainer
verification.
---------
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
|
||
|
|
560ffae103 |
feat(deploy): Add turnkey deploy command (#1404)
## Description Adds `headroom deploy` as the turnkey, zero-config local deployment entrypoint. The command chooses the most capable deployment path it can verify on the current host, configures detected tools through the existing persistent-install machinery, starts the proxy, and preserves the existing rollback behavior if an update fails. The selection order favors performance first: NVIDIA Docker GPU passthrough when `nvidia-smi` and Docker's NVIDIA runtime are available, then plain Docker, then native scheduled recovery, then a detached Python runtime fallback. ## 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 - [x] Performance improvement - [x] Code refactoring (no functional changes) ## Changes Made - Added the top-level `headroom deploy` command and reused the existing install manifest/apply/start/rollback path. - Added conservative runtime selection for GPU Docker, plain Docker, native schedulers, and detached Python fallback. - Added Docker runtime support for manifest-driven `--gpus all` passthrough. - Added tests for Docker selection, GPU Docker selection, detached fallback, GPU command rendering, and subprocess wrapper compliance. - Updated README and persistent-install docs to present the turnkey deployment flow and performance-first GPU behavior. - Allowed documented `opencode` targets through `headroom install apply --target`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check`) - [x] Formatting passes (`ruff format --check`) - [x] Type checking passes in local pre-commit and CI - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text uv run --with pytest --with pytest-asyncio python -m pytest tests/test_cli/test_subprocess_utf8_encoding.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py::test_build_runtime_command_for_docker_includes_gpu_passthrough tests/test_install/test_planner.py -q 47 passed in 1.57s uvx --from ruff==0.15.17 ruff check headroom/cli/install.py headroom/install/runtime.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py --output-format concise All checks passed! uvx --from ruff==0.15.17 ruff format --check headroom/cli/install.py headroom/install/runtime.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py 4 files already formatted ``` GitHub checks are green on the current head. ## Real Behavior Proof - Environment: Windows local worktree `C:\git\headroom`, Python 3.13 via `uv`; GitHub Actions Ubuntu/macOS/Windows runners for full PR CI. - Exact command / steps: Ran the focused deploy/install tests above, checked the touched Python files with the CI-pinned Ruff version, and confirmed the current PR head is mergeable with green GitHub checks. - Observed result: The deploy command, runtime selection, Docker GPU command rendering, install CLI behavior, and subprocess encoding coverage all pass locally; the branch is no longer conflicted. - Not tested: Actual RTX 4090 hardware passthrough on a physical NVIDIA workstation; the PR tests conservative detection and Docker command rendering without requiring GPU hardware in CI. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) N/A - CLI/runtime behavior only. ## Additional Notes CHANGELOG update is not included because this is an unreleased feature PR and the repository's release tooling owns release notes from conventional commits. |
||
|
|
2a954b69b4 |
feat(wrap): add ZCode desktop app support (#1845)
## Description Add `headroom wrap zcode` and `headroom unwrap zcode` commands for the ZCode desktop app (zcode.z.ai). ZCode is a desktop Electron IDE built by Z.AI, optimized for GLM-5.2 models. It has no CLI binary, so this follows the Pattern-B (proxy-only, print instructions) approach — same as Cursor, Cline, and Continue. **Upstream auto-detection:** `headroom wrap zcode` now reads `~/.zcode/v2/config.json` to detect the enabled provider and automatically configures the proxy upstream — no manual flags needed. Closes #1844 ## 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 module: `headroom/providers/zcode/__init__.py` and `runtime.py` (ZCodeProxyTargets, ZCodeUpstream, build_proxy_targets, detect_upstream, upstream_to_proxy_urls, render_setup_lines) - New CLI command: `headroom wrap zcode` in `headroom/cli/wrap.py:4815` — starts proxy, injects RTK into AGENTS.md, prints Base URL setup instructions - New CLI command: `headroom unwrap zcode` in `headroom/cli/wrap.py:5960` — removes RTK markers, stops proxy - New helper: `zcode_config_dir()` in `headroom/install/paths.py` - Updated `_run_proxy_only_watcher` to accept `anthropic_api_url`/`openai_api_url` params - Updated README.md: ZCode row in compatibility matrix, unwrap list, wrap command list - Updated CHANGELOG.md: entry under [Unreleased] > Added ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) — pre-existing numpy type stubs issue prevents full mypy run - [x] New tests added for new functionality (24 tests in `tests/test_cli/test_wrap_zcode.py`) - [x] Manual testing performed ### Test Output ```text tests/test_cli/test_wrap_zcode.py ........................ [100%] 24 passed, 1 warning in 0.22s ``` ## Real Behavior Proof - Environment: macOS 15.5, Python 3.12.13, headroom installed via `pip install -e .[dev]` - Exact command / steps: `headroom wrap zcode --port 9000` then `headroom unwrap zcode --port 9000` - Observed result: Wrap detects provider from `~/.zcode/v2/config.json` (e.g. "Z.ai Coding"), starts proxy with correct upstream on port 9000, injects RTK into AGENTS.md, prints detected provider + upstream + Base URL setup instructions. Unwrap removes RTK markers, deletes empty AGENTS.md, stops proxy. - Not tested: Actual ZCode app integration (ZCode is a desktop Electron app; Base URL configuration is manual in Settings > Model Settings) ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project style guidelines - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas — N/A: code follows existing patterns - [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 ## Screenshots (if applicable) N/A — CLI-only changes ## Additional Notes - **Pattern-B approach:** ZCode is a desktop Electron app with no CLI binary. Same pattern as Cursor, Cline, and Continue — proxy-only, print instructions. - **Upstream auto-detection:** Reads `~/.zcode/v2/config.json`, finds the enabled provider, and passes its `baseURL` to the proxy. Falls back to Z.ai Anthropic endpoint if no config found. - **httpProxy investigation:** ZCode has an `httpProxy` setting in `~/.zcode/v2/setting.json`, but it is an Electron-level forward proxy (CONNECT tunneling), incompatible with headroom reverse proxy. The Base URL approach in Model Settings is the correct integration point. - **No dependencies added:** This PR adds zero new dependencies. --------- Co-authored-by: Epicism <epicism@Epiphanie.local> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> Co-authored-by: Tejas Chopra <chopratejas@gmail.com> |
||
|
|
5dbe3314a1 |
fix(auth): support GitHub Enterprise Copilot OAuth domain (#2192)
## Description Adds GitHub Enterprise OAuth domain support for Copilot auth. When `GITHUB_COPILOT_ENTERPRISE_URL` is set, the default OAuth domain resolves to that enterprise host; explicit `--domain` values still take precedence. Closes #1152 ## 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) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/copilot_auth.py`: derive the default OAuth domain from `GITHUB_COPILOT_ENTERPRISE_URL` when present, falling back to `github.com` for unset or blank values. - `headroom/cli/copilot_auth.py`: keep explicit CLI domain overrides authoritative even when the enterprise env var is set. - `README.md`: document the enterprise OAuth environment setting and precedence. - Added regression tests for enterprise URL handling, blank/unset fallback, and explicit CLI override precedence. ## 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 uv run pytest tests/test_copilot_auth.py tests/test_cli/test_copilot_auth.py -q 69 passed in 1.05s uvx ruff@0.15.17 check headroom/cli/copilot_auth.py headroom/copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_copilot_auth.py All checks passed! uvx ruff@0.15.17 format --check headroom/cli/copilot_auth.py headroom/copilot_auth.py tests/test_cli/test_copilot_auth.py tests/test_copilot_auth.py 4 files already formatted ``` ## Real Behavior Proof - Environment: Windows 11 development checkout, Python 3.13.3, with focused Copilot auth tests using monkeypatched enterprise env vars. - Exact command / steps: ran the Copilot auth unit/CLI tests plus ruff check and format-check against the touched auth files and tests. - Observed result: `GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com` resolves `default_oauth_domain()` to `ghe.example.com`; unset/blank enterprise env vars fall back to `github.com`; and `headroom copilot-auth login --domain github.com` still honors the explicit override when enterprise env vars are set. - Not tested: live OAuth against a real GitHub Enterprise Server instance. ## 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 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 - CLI/auth behavior and README update. ## Additional Notes `GITHUB_COPILOT_ENTERPRISE_URL` takes precedence over `GITHUB_COPILOT_ENTERPRISE_DOMAIN`; explicit `--domain` remains authoritative for the login command. --------- Co-authored-by: JerrettDavis <mxjerrett@gmail.com> Co-authored-by: Tejas Chopra <chopratejas@gmail.com> |
||
|
|
1590913bb7 |
fix(build): support Intel macOS (x86_64-apple-darwin) via ort-load-dynamic (fixes #941) (#1797)
## Problem `headroom-ai` fails to build from source on Intel macOS (`x86_64-apple-darwin`), both with and without the `[all]` extra: ``` error: ort-sys@2.0.0-rc.12: ort does not provide prebuilt binaries for the target `x86_64-apple-darwin` with feature set (no features). ``` Reported in #941. `ort-sys`'s `download-binaries` strategy (used by the `ort-download-binaries-rustls-tls` fastembed feature that `headroom-core` depends on for all non-Windows targets) only ships prebuilt ONNX Runtime binaries for Windows, Linux (x86_64/aarch64), and macOS **Apple Silicon**. There's currently no way to install this package from source on an Intel Mac at all — with or without `[all]`, since the ONNX dependency lives in `headroom-core` itself, not behind a pip extra. ## Root cause `crates/headroom-core/Cargo.toml` already has a working fallback for this *exact* class of problem — for Windows, it swaps `fastembed`'s `ort-download-binaries-rustls-tls` feature for `ort-load-dynamic`, which dlopen's a system-provided ONNX Runtime at runtime instead of requiring a bundled prebuilt binary for the exact target triple. Intel macOS just never got the same treatment. ## Fix Extends the existing `ort-load-dynamic` branch to also cover `target_os = "macos", target_arch = "x86_64"`. ## Documentation Also adds an Intel-macOS subsection next to the existing "Corporate / SSL-inspection environments" section, since the `ORT_STRATEGY=system` + `ORT_LIB_LOCATION` mechanism documented there for a different reason is *also* a fully working, no-source-patch workaround available today: ```bash brew install onnxruntime ORT_STRATEGY=system \ ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \ ORT_PREFER_DYNAMIC_LINK=1 \ pip install "headroom-ai[all]" export ORT_DYLIB_PATH="$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib" ``` Two things cost real debugging time and seemed worth documenting either way: `ORT_LIB_LOCATION` must point at the `lib/` subdirectory specifically (the Homebrew keg has no single-file library at the prefix root — pointing at the bare prefix gets a *different*, more confusing error: "could not link to the ONNX Runtime build"), and `ORT_PREFER_DYNAMIC_LINK=1` is required — without it, `ORT_STRATEGY=system` still attempts static linking, which the Homebrew keg doesn't provide. ## Testing - `cargo check -p headroom-core` and a full `maturin build --release` succeed on Intel macOS (macOS 26.5.1) with this patch and `ORT_DYLIB_PATH` pointed at a Homebrew onnxruntime 1.27.0. - Verified beyond just compiling: loaded the built wheel's `_core.abi3.so` directly and called `detect_content_type` (the magika/ONNX-backed classifier, which shares the ONNX Runtime instance per the comment in `headroom-core/Cargo.toml`). Ran successfully, no dyld/link errors. - Independently verified the doc-only workaround builds a working wheel through the **unmodified** sdist via `pip wheel` — no Cargo.toml changes needed for that path at all. - Not tested on Apple Silicon or Linux; the `cfg()` predicate is scoped to `(target_os = "macos", target_arch = "x86_64")` so it shouldn't affect either. Happy to split this into two PRs (code fix / doc fix) if that's easier to review. ## Note I noticed a branch, `fix-wheel-matrix-vendored-openssl-and-drop-intel-mac`, that appears to drop Intel macOS from the release wheel matrix rather than fix source builds for it. It looked stale relative to `main` (interleaved with much older history) when I checked, so I wasn't sure whether it reflects current intent — if the project has already decided to drop Intel macOS support rather than fix it, feel free to close this instead, no worries either way. Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
e9e9cd55b7 |
feat(mcp): publish canonical server.json (#1510)
## Description Headroom can launch its MCP server, but did not publish a canonical `server.json` that registries and MCP hosts can consume directly. This PR adds a shared descriptor builder, commits a root `server.json`, parity-tests that artifact against the builder and existing runtime spec, and updates docs so registry authors do not need to reconstruct `headroom mcp serve` from prose. Closes #929. ## 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 - Added a shared `server_json.py` descriptor builder for Headroom MCP publication metadata. - Published a canonical root `server.json` and parity-tested it against the builder. - Encoded the publishable uvx contract as `headroom-ai[mcp]` plus `headroom mcp serve`. - Updated README and MCP docs to point registry authors at the canonical descriptor. - Added the README ownership marker used by MCP Registry verification. - Kept existing registrars and `headroom mcp install` behavior unchanged. ## Testing - [x] Unit tests pass - [x] Linting passes - [x] Type checking passes - [x] New tests added for new functionality when applicable - [x] Manual testing performed ### Test Output ```text Focused registry/server-json tests and reviewer approval were completed on this PR before the governance body cleanup. The current body update is documentation-only metadata for PR governance. ``` ## Real Behavior Proof - Environment: Headroom development checkout with MCP test dependencies. - Exact command / steps: Inspected the generated `server.json` contract and parity coverage against the descriptor builder and runtime MCP spec. - Observed result: The committed descriptor matches the builder/runtime contract and advertises the intended `headroom-ai[mcp]` / `headroom mcp serve` launch path. - Not tested: live publication to third-party registries ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Additional Notes This body was normalized by a maintainer after approval so the governance parser reflects the already-reviewed PR state. |
||
|
|
e65b9b3f92 |
feat(proxy): apply output shaper to OpenAI-compatible endpoints (#1725)
## Description
Extend the output shaper (verbosity steering + effort routing) to run on
OpenAI-compatible traffic.
Before this PR, the shaper was Anthropic-only by construction:
`shape_request()`'s implementation hard-coded Anthropic wire shapes
(`body["system"]` blocks, `output_config.effort`,
`thinking.budget_tokens`), and only `handlers/anthropic.py:1949` called
it. Setting `HEADROOM_OUTPUT_SHAPER=1` was silently a no-op for
OpenAI-compatible requests (OpenRouter, GitHub Copilot subscription
mode, direct OpenAI or `gpt-5`-class Chat Completions).
This PR:
- adds a `provider="anthropic"|"openai"` dispatch axis to
`classify_turn`, `apply_verbosity_steering`, `route_effort`, and
`shape_request` — default stays `"anthropic"` so existing callers
(`headroom/learn/verbosity.py`, `handlers/anthropic.py:1949`) keep
working unchanged.
- wires the shaper into `handlers/openai.py` for both
`/v1/chat/completions` (verbosity + effort) and `/v1/responses` (effort
only for this pass; the `body["input"]` item-list steering is a
follow-up).
- keeps the emitted label vocabulary (`output_shaper:*`) byte-identical
across providers so the savings ledger (`output_savings.py`) and outcome
funnel (`outcome.py`) remain provider-agnostic.
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)
- [x] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)
## Changes Made
- **`headroom/proxy/output_shaper.py`** — provider-dispatched core:
- `_classify_turn_openai()` inspects `role=="tool"` messages, detecting
errors structurally: `Error:` / `error:` / `ERROR:` / `Traceback` string
prefixes, or `{"error": ...}` / `{"is_error": ...}` / `{"exception":
...}` keys in dict or list-of-parts content. Same "no keyword regex over
arbitrary text" invariant as the Anthropic classifier.
- `_apply_verbosity_steering_openai()` inserts a trailing
`{"role":"system", "content": steering_text(level)}` immediately after
the leading system-message block, preserving prefix-cache-critical
bytes. Idempotent at same level; replaces-in-place on mid-session level
change.
- `_route_effort_openai()` clamps `body["reasoning_effort"]` (Chat
Completions) and `body["reasoning"]["effort"]` (Responses) on
`MECHANICAL_CONTINUATION` turns. Clamp-only invariant: never injects a
value the client didn't send. `_EFFORT_RANK` expanded to include
`"minimal"` (OpenAI's canonical low-end value).
- **`headroom/proxy/handlers/openai.py`** — two insertion sites:
- `/v1/chat/completions`: mirrors `handlers/anthropic.py:1937-1993`
right after `PRE_SEND` emit, before `optimized_tokens` recount. Same
`HEADROOM_OUTPUT_HOLDOUT` A/B, same `stratum_label` /
`transforms_applied` bookkeeping.
- `/v1/responses`: scoped effort-only variant after the compression
block, reusing the `_responses_input_to_waste_messages` helper to derive
OpenAI-shape messages for turn classification.
- **`tests/test_output_shaper.py`** — 34 new tests across four classes
covering classification, steering, effort routing, and end-to-end
shape_request for the OpenAI path. Includes a **label-vocabulary parity
test** that pins the emitted label sequence identical between Anthropic
and OpenAI on matched-turn bodies.
- **`README.md`** — one paragraph in the "Output token reduction"
section noting the shaper now covers `/v1/messages`,
`/v1/chat/completions`, and `/v1/responses`, with the effort-lever
difference (`reasoning_effort` vs `thinking.budget_tokens`).
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) — not run locally;
downstream CI will exercise it
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ pytest tests/test_output_shaper.py tests/test_runtime_env.py \
tests/test_output_savings.py tests/test_output_savings_cli.py \
tests/test_verbosity_controller.py tests/test_verbosity_learn.py \
tests/test_request_outcome.py tests/test_handler_outcome_tag_invariant.py -q
============================= test session starts ==============================
platform linux -- Python 3.12.12, pytest-9.1.1, pluggy-1.6.0
collected 185 items
tests/test_output_shaper.py ............................................ [ 23%]
........................ [ 36%]
tests/test_runtime_env.py ................ [ 45%]
tests/test_output_savings.py ................................... [ 64%]
tests/test_output_savings_cli.py ... [ 65%]
tests/test_verbosity_controller.py ............ [ 72%]
tests/test_verbosity_learn.py ............... [ 80%]
tests/test_request_outcome.py ................................. [ 98%]
tests/test_handler_outcome_tag_invariant.py ... [100%]
======================== 185 passed, 1 warning in 1.03s ========================
$ pytest tests/test_proxy_openai_responses_bypass.py \
tests/test_proxy_openai_responses_integration.py \
tests/test_openai_responses_compression_units.py \
tests/test_openai_responses_context_compaction.py \
tests/test_openai_beta_session_sticky.py \
tests/test_openai_codex_routing.py \
tests/test_codex_openai_contract_parity.py \
tests/test_codex_responses_waste_signals.py -q
================== 82 passed, 14 skipped, 1 warning in 13.00s ==================
$ pytest tests/test_anthropic_beta_session_sticky.py \
tests/test_anthropic_pre_upstream_backpressure.py \
tests/test_anthropic_stage_timings.py \
tests/test_proxy_anthropic_cache_stability.py \
tests/test_proxy_anthropic_compression_diagnostics.py \
tests/test_proxy_handler_helpers.py \
tests/test_proxy_handlers_batch.py -q
======================== 123 passed, 1 warning in 6.69s ========================
$ ruff check headroom/proxy/output_shaper.py headroom/proxy/handlers/openai.py \
tests/test_output_shaper.py
All checks passed!
```
## Real Behavior Proof
- **Environment**: Ubuntu 24.04, Python 3.12.12, `uv`-managed venv,
`headroom-ai` editable install from this branch (`uv pip install -e
".[dev]"`).
- **Exact command / steps**:
1. Create a mechanical-continuation OpenAI Chat Completions body:
```python
body = {
"messages": [
{"role": "user", "content": "fix the bug in foo.py"},
{"role": "assistant", "content": None, "tool_calls": [
{"id": "call_01", "type": "function",
"function": {"name": "read_file", "arguments": "{}"}}]},
{"role": "tool", "tool_call_id": "call_01", "content": "file
contents..."},
],
"reasoning_effort": "high",
}
```
2. Call `shape_request(body, OutputShaperSettings(enabled=True),
provider="openai")`.
- **Observed result**:
- Return value: `ShapeResult(changed=True,
labels=["output_shaper:verbosity:L2",
"output_shaper:effort:high->low"])`.
- `body["reasoning_effort"] == "low"` (clamped from `"high"`).
- `body["messages"][0] == {"role": "system", "content":
"<headroom_output_shaping>\n…\n</headroom_output_shaping>"}` — inserted
before the user turn since there was no leading system message. Steering
text byte-identical to Anthropic path (same `_VERBOSITY_LEVELS` table).
- Replacing the tool content with `"Error: file not found"` reclassifies
the turn as `ERROR_CONTINUATION`: `reasoning_effort` stays `"high"`,
only verbosity steering applied (label list is
`["output_shaper:verbosity:L2"]`).
- Same body under `provider="anthropic"` — after adapting `messages` to
Anthropic `tool_result` block shape and swapping `reasoning_effort` for
`output_config.effort` — emits an identical label list
(`test_label_vocabulary_matches_anthropic`), confirming the
savings-ledger / outcome-funnel contract holds.
- **Not tested**:
- End-to-end against a real OpenAI upstream. The shaper is a
request-side mutation and its correctness is defined by the emitted body
+ label vocabulary, both fully covered by unit tests. The receiving
OpenAI API's behavior on the shaped body (whether it honors
`reasoning_effort: low`, whether the trailing system message steers
verbosity as designed) is a downstream property, not a shaper property.
- `mypy headroom` — not run locally (project `[dev]` extra installed,
but type-checking wasn't part of the local iteration loop). Ruff is
clean and the new code carries full type hints.
- Verbosity steering for the Responses API's `body["input"]` item list.
Deferred by design — see the comment at the `/v1/responses` insertion
site in `handlers/openai.py`. Effort routing on the Responses path is
covered.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable — `CHANGELOG.md`
exists but appears release-managed; happy to add an `## Unreleased`
entry if that's the desired convention.
## Additional Notes
- **Backward compatibility**: `classify_turn`,
`apply_verbosity_steering`, `route_effort`, and `shape_request` all
default to `provider="anthropic"`, so `headroom/learn/verbosity.py:37`
and `handlers/anthropic.py:1949-1953` (the only external callers) keep
working with zero changes.
- **Follow-up scope** (happy to file as a separate PR if wanted):
1. Verbosity steering for the Responses API's `body["input"]` item list
— requires handling `message` vs `tool_output` vs `reasoning` item types
uniformly.
2. `max_completion_tokens` cap on mechanical turns as a third effort
lever — kept out of scope here because it's behavior-changing beyond
"clamp existing effort".
3. Extend the label-vocabulary parity test into a property-based fixture
that fuzzes matched Anthropic ↔ OpenAI bodies.
- **Deployment story on my side**: I'm running this on Raspberry Pi 5
via Ansible; the pinned commit will get installed as
`git+https://github.com/dylanrussellmd/headroom.git@<sha>` until this
merges upstream and lands in a `headroom-ai` release. I mention this
only because it exercises the change in a real proxy against real
OpenAI-compatible upstream traffic; happy to report savings numbers back
once the deployment stabilizes.
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
|
||
|
|
b4d4f641f3 |
docs: add Claude Code status-line indicator to Community (#1790)
## Description Adds a single **Community projects** entry to the `## Community` section of the README, linking a community-built Claude Code plugin ([`Ship-Wright/headroom-plugin`](https://github.com/Ship-Wright/headroom-plugin)) that surfaces Headroom usage in the editor status line. Docs-only; no code, config, or dependencies change. Context: headroomlabs-ai/headroom discussion #1789. Closes # (N/A — documentation addition, no linked issue) ## 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 - Added a `### Community projects` subsection under `## Community` in `README.md` with one bullet linking `Ship-Wright/headroom-plugin` and a one-line description of what it shows. ## Testing <!-- Docs-only change: no Python code paths touched, so the code test suite is not applicable. --> - [ ] Unit tests pass (`pytest`) — N/A (no code changed) - [ ] Linting passes (`ruff check .`) — N/A (no code changed) - [ ] Type checking passes (`mypy headroom`) — N/A (no code changed) - [ ] New tests added for new functionality — N/A (documentation) - [x] Manual testing performed (rendered the Markdown diff; verified the link resolves) ### Test Output ```text $ git diff --stat main README.md | 4 ++++ 1 file changed, 4 insertions(+) # Rendered diff: a new "### Community projects" heading + one bullet appears under "## Community". # Link check: https://github.com/Ship-Wright/headroom-plugin → 200 OK, public, MIT-licensed. ``` ## Real Behavior Proof - Environment: GitHub-flavored Markdown (README preview), macOS. - Exact command / steps: edited `README.md`, `git diff` to confirm a 4-line addition, previewed the rendered section, and opened the linked repo URL to confirm it is public and installable. - Observed result: the new `### Community projects` bullet renders correctly under `## Community`; the link points to a working, public plugin repo. - Not tested: nothing in the Python package changed, so `pytest` / `ruff` / `mypy` were not run (no applicable code paths). ## 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 (matches existing Community bullet formatting) - [x] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas — N/A (docs) - [x] I have made corresponding changes to the documentation (this PR is the documentation change) - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works — N/A (docs) - [ ] New and existing unit tests pass locally with my changes — N/A (no code changed) - [ ] I have updated the CHANGELOG.md if applicable — N/A (README-only community link) ## Screenshots (if applicable) N/A — a one-line text addition; see the diff. ## Additional Notes This is a minimal, opt-in community link — totally fine to reword, relocate, or decline. Several checklist/testing items are marked N/A because the change is documentation-only and touches no Python code. Happy to adjust the wording or move it elsewhere in the README if you'd prefer. Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
c707de4691 |
docs: retire IntelligentContext from README and installation guide (#1445)
## Description Public README and installation guide still marketed **IntelligentContext** and score-based history dropping after PR-B1 retired those stages in favor of live-zone-only compression. This updates the two first-touch docs so new users see the current pipeline: compress fresh tool output and new turns only; frozen prefix preserved; history never dropped. Closes #1444 ## 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 - **README.md** — replace IntelligentContext marketing bullet with **live-zone compression** (new bytes only; frozen prefix preserved; history never dropped) - **README.md** — pipeline internals list current transforms and note IntelligentContext / RollingWindow retirement (PR-B1) - **docs/content/docs/installation.mdx** — core package description matches live-zone ContentRouter - **docs/content/docs/installation.mdx** — add PR-B1 retirement note for IntelligentContext / RollingWindow ## 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 $ rg -n 'IntelligentContext' README.md docs/content/docs/installation.mdx README.md:289:- **Transforms** do the work: ... (live-zone only; IntelligentContext and RollingWindow were retired in PR-B1). docs/content/docs/installation.mdx:31:> **Note:** IntelligentContext / RollingWindow ... were retired in PR-B1. $ rg -n 'live-zone|Live-zone' README.md docs/content/docs/installation.mdx README.md:274:- **Live-zone compression** — compresses only new bytes ... README.md:289:- **Transforms** do the work: ... (live-zone only; ...) docs/content/docs/installation.mdx:29:The core package includes ... live-zone ContentRouter compression. ``` ## Real Behavior Proof - Environment: macOS (darwin 25.5.0), branch `docs/retire-intelligentcontext-readme` in `/Users/bhavya/Desktop/Headroom-upstream` - Exact command / steps: `rg -n 'IntelligentContext' README.md docs/content/docs/installation.mdx` and `rg -n 'live-zone|Live-zone' README.md docs/content/docs/installation.mdx`; read updated README pipeline section and installation.mdx core-package blurb - Observed result: IntelligentContext appears only in retirement notes (not as an active feature); live-zone compression is the primary marketed behavior in README and installation guide - Not tested: Wiki pages (tracked as follow-up in #1444); docs site build (`npm run build` in docs/) ## 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 - [x] 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 ## Additional Notes Wiki still has extensive IntelligentContext docs — out of scope here; follow-up tracked in #1444. CHANGELOG N/A (docs-only, no release note required). Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
4d433592de |
Install using uv tool globally (#1829)
Resolves headroomlabs-ai/headroom#768 ## Description Explain how to install using `uv tool` as a global tool. This should be the preferred option for installation so that headroom is setup as a global tool within a self-contained virtual env and the binary on the user's path. That way, a wrapped coding agent can correctly invoke headroom within the virtual env to avoid python package import issues. For example, `~/.claude.json`: ```json "mcpServers": { "headroom": { "type": "stdio", "command": "/Users/USERNAME/.local/bin/headroom", "args": [ "mcp", "serve" ], "env": {} }, ``` uses the command path based on `command -v headroom`. ## 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 - Updated README.md ## 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 - [x] Manual testing performed ### Test Output ```sh uv tool install "headroom-ai[all]" ``` ```sh command -v headroom /Users/dustin/.local/bin/headroom ``` ```sh headroom wrap claude ╔═══════════════════════════════════════════════╗ ║ HEADROOM WRAP: CLAUDE ║ ╚═══════════════════════════════════════════════╝ Starting Headroom proxy on port 8787... Logs: /Users/dustin/.headroom/logs/proxy.log Proxy ready on http://127.0.0.1:8787 Dashboard: http://127.0.0.1:8787/dashboard Setting up rtk... Code graph: indexed (tokensave) Launching Claude Code (API routed through Headroom)... ANTHROPIC_BASE_URL=http://127.0.0.1:8787 Remote Control: Claude Code may hide the Remote Control menu while ANTHROPIC_BASE_URL points at a custom endpoint (the wrapped Claude session's ANTHROPIC_BASE_URL); launch Claude without Headroom for sessions that need this feature. ENABLE_TOOL_SEARCH=true (on-demand tool loading kept on; issue #746) ``` ## Real Behavior Proof - Environment: See below - Exact command / steps: See test output section above - Observed result: Headroom installed as expected, Claude coding agent successfully had headroom MCP available - Not tested: Coding agents other than Claude. OS other than Mac. ```sh uname -a Darwin mac.lan 25.5.0 Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:26 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T8132 arm64 claude --version 2.1.201 (Claude Code) headroom --version headroom, version 0.30.0 ``` ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [ ] My code follows the project's style guidelines - [x] I have performed a self-review - [ ] 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 - [ ] 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) N/A ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. --> |
||
|
|
84ecca770e |
docs(readme): update lean-ctx comparison row (#1711)
## Description
The README "Compared to" table listed lean-ctx as `Scope: CLI commands,
MCP tools, editor rules · Deploy: CLI wrapper · MCP · Reversible: No`.
The lean-ctx maintainer reported in the issue that the project ships
five reversibility mechanisms (`ctx_expand`, `ctx_retrieve`, proxy CCR
tee store with file-path handles, in-band `<lc_expand:HASH>` markers,
and a `GET /v1/references/{id}` HTTP endpoint), plus a wire-level
transparent proxy, a `compress(messages, model)` Py/TS SDK, and
middleware hooks (LiteLLM, Vercel AI SDK). This PR updates the row to
the wording suggested in the issue so the comparison stays accurate.
Fixes #1675
## 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
- `README.md` ("Compared to" table): lean-ctx row updated to `Scope:
Tool output, files, shell, history · Deploy: Proxy · library ·
middleware · MCP · CLI · Local: Yes · Reversible: Yes`.
## 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
$ grep -n "lean-ctx" README.md | head -1
447:| [lean-ctx](https://github.com/yvgude/lean-ctx) | Tool output, files, shell, history | Proxy · library · middleware · MCP · CLI | Yes | Yes |
```
## Real Behavior Proof
- Environment: Windows 11, local checkout at `upstream/main` (
|
||
|
|
a7721b2f38 |
[codex] docs: add Codex install note (#1757)
## Description README lacked a practical note for Codex and other MCP clients that cannot reliably inherit a shell PATH. That makes `command = "headroom"` brittle for uv-installed setups. Closes #1757 ## Type of Change - [x] Documentation update ## Changes Made - Added a short Codex/global-install section to README. - Documented `uv tool install "headroom-ai[all]"` and `command -v headroom`. - Showed the absolute-path MCP config pattern. ## 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 Docs-only verification: - Reviewed README diff for command syntax and placement. - Cross-checked the documented flow against the existing uv install pattern and absolute-path MCP config example. ``` ## Real Behavior Proof - Environment: GitHub PR diff review for docs-only install guidance. - Exact command / steps: Compared new README note against documented `uv` tool install flow and absolute-path MCP launch pattern. - Observed result: Docs now give Codex/MCP users a stable binary-path setup instead of relying on ambient PATH inheritance. - Not tested: Fresh uv install on a clean machine in this verification pass. ## 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 - [x] 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 Co-authored-by: Your Name <you@example.com> |
||
|
|
9c203ddbcc |
[codex] docs: remove retired IntelligentContext copy (#1756)
## Description Public README and installation guide still described retired IntelligentContext / RollingWindow as active features. Pipeline now uses live-zone compression only. Closes #1756 ## Type of Change - [x] Documentation update ## Changes Made - Reworded README feature bullets to describe live-zone compression and live-zone pipeline stages. - Updated installation guide copy to match current core package behavior. ## 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 Docs-only verification: - Reviewed PR diff in GitHub Files changed. - Confirmed touched README / install copy no longer advertises retired IntelligentContext or RollingWindow behavior. ``` ## Real Behavior Proof - Environment: GitHub PR diff review for docs-only change. - Exact command / steps: Compared updated README and installation docs text against current live-zone compression behavior described elsewhere in repo. - Observed result: Public docs no longer claim retired IntelligentContext / RollingWindow paths are active. - Not tested: Runtime commands; docs-only change. ## 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 - [x] 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 |
||
|
|
a031055a2d |
docs(readme): correct lean-ctx comparison row (#1754)
## Description Correct the `lean-ctx` row in the README comparison table. The upstream project documents reversible recovery paths and broader deployment surfaces than the table previously reflected. Closes #1754 ## Type of Change - [x] Documentation update ## Changes Made - `README.md`: updated `lean-ctx` comparison row to match current documented capabilities and reversible behavior. ## 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 Docs-only verification: - Reviewed rendered README diff for the comparison row. - Cross-checked updated row against current public lean-ctx docs covering deployment surfaces and reversible behavior. ``` ## Real Behavior Proof - Environment: GitHub PR diff review for docs-only comparison-table update. - Exact command / steps: Compared new README row wording against current public lean-ctx documentation. - Observed result: Comparison row now matches documented capabilities instead of understating recovery and deployment support. - Not tested: Runtime commands; docs-only change. ## 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 - [x] 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 Co-authored-by: Your Name <you@example.com> |
||
|
|
32ce99e4b4 |
fix(build): enable Intel macOS pip installs via ort-load-dynamic (#1538)
## Description
Fix `pip install headroom-ai` on Intel Mac (`x86_64-apple-darwin`).
Source installs failed because `ort-sys 2.0.0-rc.12` (transitive via
`fastembed`) does not ship prebuilt ONNX Runtime binaries for that
target, causing maturin/cargo to exit during the wheel build.
This PR mirrors the existing Windows fix: build the Rust core with
`ort-load-dynamic`, pin `ORT_DYLIB_PATH` to the pip `onnxruntime` native
library at import time, and publish Intel macOS wheels from CI.
Closes #
## 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `crates/headroom-core/Cargo.toml`: use `ort-load-dynamic` for
`x86_64-apple-darwin` instead of `ort-download-binaries-rustls-tls`.
- `headroom/_ort.py`: extend the ORT dylib pin hook to Intel macOS
(`darwin` + `x86_64`), resolving `libonnxruntime*.dylib` from the pip
`onnxruntime` package.
- `.github/workflows/release.yml` and `.github/workflows/rust.yml`: add
`macos-15-intel` / `x86_64-apple-darwin` wheel matrix entries.
- `tests/test_release_workflows.py` and
`tests/test_transforms/test_ort_dylib.py`: update/add coverage for the
new target and dylib pin behavior.
- `README.md`: note that prebuilt wheels are published for Intel macOS.
## 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
$ pytest tests/test_transforms/test_ort_dylib.py \
tests/test_release_workflows.py::test_fastembed_uses_dynamic_ort_on_windows \
tests/test_release_workflows.py::test_build_wheels_matrix_includes_intel_macos_with_dynamic_ort -q
.......................... [100%]
10 passed in 0.18s
$ maturin build --release -o /tmp/headroom-dist
📦 Built wheel for abi3 Python ≥ 3.10 to /tmp/headroom-dist/headroom_ai-0.27.0-cp310-abi3-macosx_10_12_x86_64.whl
$ python3.11 -m venv /tmp/hr-venv && /tmp/hr-venv/bin/pip install .
Successfully built headroom-ai
Successfully installed headroom-ai-0.27.0
$ cd /tmp && /tmp/hr-venv/bin/python -c "import headroom; import headroom._core; print('ok')"
version 0.27.0
_core ok
```
## Real Behavior Proof
- Environment: macOS `x86_64-apple-darwin`, Python 3.11.5, Rust 1.95.0
- Exact command / steps: Reproduced the reported failure with `pip
install headroom-ai` (sdist build dies in `ort-sys` for
`x86_64-apple-darwin`); after this patch ran `maturin build --release`,
then `pip install .` in a clean venv, then `python -c "import
headroom._core"`.
- Observed result: Before fix, cargo/maturin exit 101 on missing ORT
prebuilts; after fix, wheel build succeeds and `headroom._core` imports
cleanly (`version 0.27.0`, `_core ok`).
- Not tested: `macos-15-intel` GitHub Actions wheel matrix row (will be
validated by CI after merge).
## 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
- [ ] 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
- ML features (magika detection, fastembed embeddings) still require
`onnxruntime` at runtime on Intel Mac. Users should install
`headroom-ai[proxy]` or `pip install onnxruntime`; `_ort.py` auto-pins
`ORT_DYLIB_PATH` when that package is present.
- Apple Silicon (`aarch64-apple-darwin`) behavior is unchanged: it
continues to bundle ORT via `ort-download-binaries-rustls-tls`.
- Lint/mypy not re-run locally in this pass; targeted pytest +
maturin/pip install proof covers the changed surface.
---------
Co-authored-by: Bor <you@example.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
|
||
|
|
7208792ee8 | Fix formatting in README.md |