Commit Graph
174 Commits
Author SHA1 Message Date
Parideboy 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.
2026-11-10 12:35:38 -06:00
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
ecbaf86d78 without changing contributor
selector/ownership logic. Reviewed the current discussion and
integration delta. All 29 focused code-memory/Serena-disable/Gemini
tests pass with one optional skip; Ruff0.17.3 lint/format and whitespace
checks pass. Existing Windows HOME/USERPROFILE fixture isolation remains
intact.

The prior upgrade/runtime qualification requirement remains unresolved:
post-patch real configuration/launch evidence must cover an existing
Headroom-owned Serena entry, a hand-managed entry, explicit opt-in, and
Claude project/user scopes, with commands/results and untested-agent
limits. No new author evidence was found to close it. This pass does not
claim those actual launch/upgrade flows were executed; passing unit
tests and the main sync do not establish that deployment behavior. The
hold is not an inherited-main CI defect. Maintainers handle hosted
checks; no contributor CI execution requested. Nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `0b49a79cb192b294dde7ecb1c72b75fffa2733d5`, upstream main
`8d3e9e5ca7cd645eb73084b848edbea5fc796e1a`.

Clean mechanical sync with upstream
main8d3e9e5ca7cd645eb73084b848edbea5fc796e1a without changing
contributor selector/ownership logic. Current source, author discussion
and Devin findings reviewed.29focused code-memory/Serena-disable/Gemini
tests pass with1optional skip; changed Python Ruff0.17.3check/format and
whitespace pass. Windows HOME/USERPROFILE fixture isolation preserved.

Existing real upgrade/runtime qualification remains missing: existing
Headroom-owned Serena versus hand-managed entry, explicit opt-in, and
Claude project/user scopes need observed configuration/launch results
with explicit untested-agent limits. No new evidence found to close it;
these launch/upgrade paths were not executed in this pass. Passing unit
tests and clean main integration do not establish deployment behavior.
No new provider/native-build claim or inherited-main pipeline
attribution. Maintainers handle hosted checks; nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `30dfb386fa7284c9817bf5d7db0648fb10830055`, upstream main
`7592e681459f14a2041eb5f524a658cb6ad1dd92`.

Clean current-main
sync7592e681459f14a2041eb5f524a658cb6ad1dd92,including HNSW re-index and
memory relation-key fixes after917release-recovery merge. Contributor
selector/ownership logic unchanged; fresh discussion
considered.37wrapper/Serena/memory-regression/Gemini tests pass
with1optional skip;whitespace passes. PriorRuff0.17.3validation applies
to unchanged PR files.

Existing real upgrade/launch evidence hold remains: Headroom-owned
versus hand-managed Serena
entries,explicitoptin,andClaudeproject/userscopes need
observedpostpatchresults. No newevidence closesit;actualupgrade/launch
pathsnotrerun. No freshnativebuild/provider claim.
MaintainershandleCI;nothingmerged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

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

Clean integration with upstream/main
2d3ee51846 after the external 0.43.1
release merge. Exact headroom/crates/tests comparison against previously
reviewed 30dfb386f shows no changes. Re-reviewed generated metadata; 78
release/version/MCP tests pass on this tree and whitespace passes.
Earlier 37 wrapper/Serena/memory/Gemini passes and one optional skip
remain scoped to unchanged inputs.

Existing actual upgrade/launch proof hold remains: Headroom-owned versus
hand-managed Serena entries, explicit opt-in, and Claude project/user
scopes need observed postpatch results. Those runtime paths were not
rerun and no new evidence closes the hold. No contributor ownership
policy changed, no fresh native-build/provider claim. Maintainers handle
checks; nothing merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `173c5739d7357ca9398faa41b4d1ce3b72d6c550`, upstream main
`7877241d84c93b3ec487e07324245838ddae85cc`.

Cleanly integrated upstream/main7877241d84c93b3ec487e07324245838ddae85cc
and re-reviewed the wrapper overlap with Hermes registration and port
discovery.35 selector/Serena-disable/Hermes provider and wrapper tests
pass,1optional skip; Ruff and whitespace pass. Contributor
ownership/default policy is unchanged. Existing actual
upgrade/configuration/launch proof requirement remains open for
Headroom-owned versus user-managed entries, explicit opt-in, and Claude
project/user scopes. No runtime proof is inferred from mocks or
native-build claim made. Maintainers handle hosted checks; nothing
merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `eb1c3d66669cf71f881f1ba06dc049d36b20da7b`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Final post-Dependabot requalification against upstream/main
c01cf07d94. All six Dependabot updates are
now merged. Relative to this branch's freshly tested prepared tree, the
final main sync changes only the three intended Cargo.lock records;
Python/source/test inputs are unchanged. Re-reviewed the integration and
confirmed complete native source/lock/toolchain objects match the tested
combined build and exact fresh native DLL used for this branch's local
tests.

Focused fresh-native qualification: 35 passed, 1 skipped in 2.93s.
Selected real dependency overlays and native DLL paths are recorded in
final4509-fresh-native-tests.log; the DLL provenance/input hashes are in
final-native-artifact-proof.json. No redundant rerun is implied after
this Cargo-only merge. Whitespace passes. Prior source review and scoped
real-behavior evidence remain applicable to unchanged contributor
inputs.

Existing real upgrade/configuration/launch qualification remains open
for Headroom-owned versus user-managed Serena entries, explicit
opt-in/rollback, and Claude project/user scopes. No new author evidence
closes it; contributor ownership/default policy is unchanged.

Maintainers handle hosted checks; no external-provider claim,
contributor semantic rewrite or non-Dependabot merge.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `43bfea8a164c21ab69793b3905fbf1457fef7bc2`, upstream main
`da6d9736cd82074988c7d0a2360b49d9d8b6c0a0`.

Current-main requalification against
da6d9736cd. All69 integration patches
exactly match c01cf07-to-current-main delta after diff-location
normalization; contributor selector/default/Serena ownership logic
unchanged.162 focused code-memory,Serena disable,Hermes,Windows
supervisor,search-compressor tests pass;3 platform/optional skips. All31
changed Python files pass Ruff lint/format; offline lock and whitespace
pass. Native pr3982 DLL verified against complete tracked native-input
hash proof and artifact checksum; no fresh native-build claim.
Author/Devin discussion checked. Existing real
upgrade/configuration/launch qualification remains open: prior
Headroom-owned Serena entry versus user-managed entry, explicit
opt-in/rollback, Claude project/user scopes. No new author evidence
closes it; this run does not assert actual agent launch or deployment
proof. Maintainers handle hosted checks; no contributor policy rewrite
or merge.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.


### Maintainer current-main requalification

Exact head `56557dc91725422257f90c3cb5c5f04a665e6043`, upstream main
`0ddaa56c21cdc01c4774391fdcc69e987ecc4e5c`.

Clean integration with upstream/main
0ddaa56c21. All 19 integration patches
exactly match the prior-reviewed-main da6d9736 to current-main delta
after diff-location normalization; contributor selector/default/Serena
ownership logic is unchanged. Fresh code-memory/Serena
disable/scope/reconciliation/migration, doctor and incoming
Vertex/backend/CLI tests: 330 passed, 12 skipped, 1 warning. Fourteen
changed Python files pass Ruff lint/format; offline lock and whitespace
checks pass.

Author/Devin discussion read. Existing real upgrade/configuration/launch
qualification remains open: prior Headroom-owned entry versus
user-managed entry, explicit opt-in/rollback, Claude project/user
scopes. This run establishes no actual agent launch or deployment proof.
Static source/test scope and security inspection found no new workflow,
dependency or setup path; the inherited flagged workflow-validation job
is excluded by the exact PR's unchanged workflow paths. Native DLL
reused after complete tracked input-set/hash and artifact-checksum
verification; no fresh build claimed. Maintainers handle exact-head
hosted checks; no PR merged.


Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-09 12:23:08 -06:00
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 e4a60ed7. Resolved the OpenAI passthrough
overlap by retaining main's prepared-request/model/timing parameters and
soft-passthrough guard alongside the contributor's verbatim flag;
generic compression requires both guards to permit it. Re-reviewed
Factory direct-routing/verbatim semantics and existing discussion. All
93 wrapper/runtime/Factory passthrough/socket-decoy tests pass with
existing native extension; changed-file Ruff lint/format and whitespace
checks pass. No contributor routing policy was rewritten.

Independently reran the official Droid1.3.0 CLI with isolated home,
dummy API key, actual Headroom/Uvicorn proxy and controlled LAN HTTP
upstream on this exact combined head. The CLI consumed the controlled
Anthropic SSE reply and exited zero with HEADROOM_QUALIFICATION_OK. The
message request preserved dummy Authorization and forwarded no
x-headroom headers. This is controlled transport/runtime qualification,
not a live Factory subscription or savings benchmark, and not a fresh
native build. Applied shared test-only Gemini fixture repair for
independently established main failures; all ten cases pass. Formal
approval awaits exact-head hosted qualification.


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


### Maintainer current-main requalification

Exact head `7dd0725a9ac4dd8103dedf78552ceca886fc3620`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean mechanical merge with upstream main
c01cf07d94. Re-reviewed current
Factory/Droid routing and author/Devin discussion. Factory inference
retains force_direct to bypass translating backends; Factory passthrough
retains verbatim alongside main's soft-passthrough/prepared-request
guards. Hermes scoped proxy prefixes remain excluded from Factory
dispatch; the existing standalone environment precedence is
intentionally consistent with sibling targets, while Click/wrap retain
flag precedence. No contributor routing policy rewritten.

Fresh wrapper/runtime/Factory passthrough/socket-decoy/Hermes
verification: 100 passed, with test-client/runpy warnings only. All 14
changed Python files pass Ruff lint/format; main-relative whitespace
clean and owned tree clean. Tests use the current-main native DLL for
local startup. Earlier official Droid 1.3.0 controlled-upstream runtime
proof remains scoped to its original run; no fresh official CLI replay,
Factory subscription inference, savings benchmark or branch-native build
is claimed. No new blocker found; approval awaits exact-head hosted
checks. Nothing merged.


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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-07 20:48:53 -06:00
lorenzozaneandJerrettDavis 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
c01cf07d94. The sole conflict was the
inherited Gemini fixture: adopted main's streamed-body helper after
verifying all six test-function ASTs unchanged. No contributor
dependency policy rewritten. The declared breaking change keeps
Torch-backed ml/memory/evals/voice opt-in while preserving the default
CLI/proxy bundle, image capability and main's lean profile. Evaluation
workflows and guides explicitly request removed extras; current
author/Devin discussion considered.

Fresh verification: 25 dependency/Gemini tests pass; offline uv lock
check resolves 253 packages; changed Python lint/format and
main-relative whitespace pass. Actual locked exports evaluated over 12
OS/Python marker environments (Linux/Windows/macOS, Python 3.10–3.13):
all excludes Torch/NVIDIA dependencies, explicit
all+ml+memory+evals+voice retains Torch. This is resolver/export proof,
not a fresh full installation or GPU runtime claim. No new source
blocker found; formal approval awaits exact-head hosted checks. Nothing
merged.


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

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-06 09:23:03 -06:00
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>
2026-11-03 23:37:06 -06:00
Glen JungandJerrett Davis 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>
2026-11-03 22:29:59 -06:00
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>
2026-11-03 22:23:33 -06:00
Tejas ChopraandClaude Opus 5.5 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>
2026-10-28 10:27:33 -07:00
Tejas ChopraandClaude Fable 5.1 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>
2026-10-28 07:28:07 -07:00
danieldutuandJerrettDavis 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>
2026-10-24 08:44:57 -07:00
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
d2f8582f97.

## Real Behavior Proof
- Environment: isolated Windows/Python 3.12.13 maintainer worktree with
actual telemetry/beacon decision logic and proxy fixtures.
- Exact command / steps: run the five pytest suites shown above,
including explicit opt-out, override, and buffered-session regressions.
- Observed result: all 122 selected tests passed after incorporating
current main. Earlier installer-choice regression coverage and the
independent main comparison are recorded in the qualification evidence.
- Not tested: independent maintainer live upload traffic to the
production collector or migration of real persistent installs. The
author's live status/proxy before/after observations are preserved below
and remain attributed to the author.

## Runtime Rollout Safety
- Rollout-managed feature(s): existing telemetry and beacon controls; no
new rollout framework toggle.
- Minimum rollout channel: existing deployment policy applies.
- Stable/default behavior changed: an explicit telemetry opt-out also
disables beacon uploads unless a permissible explicit beacon-on override
is configured. Saved legacy off values remain off; new unspecified
install choices are no longer persisted as off.
- Kill switch / disable path: HEADROOM_BEACON=off, DO_NOT_TRACK=1, or
offline mode under the existing policy.
- Unsafe override required: no.
- Qualification impact: operator intent and existing manifest behavior
must be considered during upgrade; hosted CI and human review remain
required.
- Rollback path: retain the prior qualified release; configure
HEADROOM_BEACON explicitly where appropriate rather than rewriting saved
user intent.

## Review Readiness
- [ ] I have performed a self-review
- [ ] This PR is ready for human review

Maintainer verification is documented above; author readiness
attestations have not been filled on the author's behalf.

## Additional Notes

The original author warning, description, follow-up exclusions, and
supplied evidence are preserved below.
> **Behaviour change for existing installs.** Read this before merging.
Every manifest that `headroom install` saved before this change already
contains `HEADROOM_TELEMETRY=off` and `--no-telemetry`, because the
planner wrote them by default. Those manifests are replayed as-is, so
**existing persistent installs will report the beacon OFF after
upgrading** until they are reinstalled. A loader migration can't tell
those defaults apart from a real opt-out, and turning uploads back on
for people who opted out would be worse, so this PR doesn't migrate. New
installs keep the beacon on by default.

#### The test we ran

A Daytona sandbox running Headroom Enterprise 0.4.3 (core 0.39.1), with
Codex CLI 0.162.1 and Claude Code connected to real GitHub, Context7 and
Fetch MCP servers, working through the workshop tasks.

#### What we found

`headroom telemetry --show` and the README say telemetry can be turned
off, and users reasonably set **`HEADROOM_TELEMETRY=off`** (or pass
`--no-telemetry`). But the anonymous upload beacon was gated only on
`HEADROOM_BEACON` / `DO_NOT_TRACK` / offline mode. With
`HEADROOM_TELEMETRY=off` it kept uploading, and `headroom telemetry`
still printed `Upload beacon: ON (opt-out)`.

#### The fix

- New `beacon_off_reason()` in `headroom/telemetry/beacon.py` names the
setting that turns the beacon off. `is_beacon_enabled()` delegates to
it. The order is:
  1. offline mode;
  2. `DO_NOT_TRACK`;
3. `HEADROOM_BEACON`, whose explicit `on` still wins over local stats
being off;
4. an explicit **`HEADROOM_TELEMETRY` off-value**: off / false / 0 / no
/ disable / disabled, the same `_OFF_VALUES` the module already uses.

`HEADROOM_TELEMETRY=on` still means only "local stats". It never
authorises upload.
- A session buffered before an opt-out is not sent afterwards:
`post_session_event` (heartbeat, idle close) and the exit flush re-check
`is_beacon_enabled()` at send time.
- `headroom telemetry` prints `Upload beacon: OFF
(HEADROOM_TELEMETRY=off)` (or whichever switch is in effect), and the
proxy startup log does the same.
- `headroom install`: since `off` now stops the beacon, the planner
writes `HEADROOM_TELEMETRY` / `--telemetry` / `--no-telemetry` only for
an explicit choice (`telemetry_enabled` is now tri-state, `None` = no
choice). Local stats stay off without the env var because they are
opt-in. `scripts/install.sh` and `install.ps1` already passed
`--no-telemetry` only on an explicit flag.
- Docs: README, proxy, security-model and limitations pages, the
dashboard tooltip, and the `--no-telemetry` help text.
- `test_banner_beacon_default_on_is_surfaced` asserted the old policy
(`--no-telemetry` leaves the beacon on). It now checks the default case
instead.

#### Before / after

| env | `is_beacon_enabled()` on origin/main | this PR | `headroom
telemetry` (this PR) |
|---|---|---|---|
| none | True | True | `ON (opt-out)` |
| `HEADROOM_TELEMETRY=off` | **True** | **False** | `OFF
(HEADROOM_TELEMETRY=off)` |
| `HEADROOM_TELEMETRY=off` + `HEADROOM_BEACON=on` | True | True | `ON
(opt-out)` |
| `HEADROOM_BEACON=off` | False | False | `OFF (HEADROOM_BEACON=off)` |
| `headroom install` with no flag → manifest | `HEADROOM_TELEMETRY=off`
+ `--no-telemetry` | neither written | — |

#### Tests

-
`tests/test_telemetry_warning.py::test_telemetry_off_turns_the_beacon_off_and_says_so`,
parametrized over the 7 off spellings: fails on origin/main, passes
here.
-
`tests/test_telemetry_warning.py::test_beacon_on_overrides_telemetry_off`.
-
`tests/test_telemetry_warning.py::test_buffered_session_is_not_sent_after_telemetry_off`:
fails on the first commit of this PR, passes now.
-
`tests/test_install/test_planner.py::test_install_writes_telemetry_only_when_chosen`,
through the CLI's `_build_deployment_manifest`: the no-flag case fails
on origin/main.
- Related suites pass: install, telemetry warning, beacon schema v2,
install CLI and proxy health (435 passed).
- ruff check, ruff format --check and mypy pass.

#### Follow-ups (not in this PR)

- `headroom init` passes `telemetry_enabled=True`, so its manifests turn
local stats on (`cli/init.py:718`). This doesn't affect the beacon.
- The `--telemetry` help text still says "anonymous telemetry", but the
flag only turns on local stats.

#### Real behavior proof

- **Setup:** macOS 26.7, Python 3.12.13. origin/main and this branch
were run side by side with `HEADROOM_BEACON` and `DO_NOT_TRACK` unset.
- `HEADROOM_TELEMETRY=off headroom telemetry`:
- origin/main: `Upload beacon: ON (opt-out)`, `is_beacon_enabled():
True`
- this branch: `Upload beacon: OFF (HEADROOM_TELEMETRY=off)`,
`is_beacon_enabled(): False`
- `headroom proxy --no-telemetry --no-optimize`, startup log:
- origin/main: `Anonymous upload beacon: ENABLED (default — session
summaries are sent to Headroom Labs). Opt out: HEADROOM_BEACON=off or
DO_NOT_TRACK=1`
- this branch: `Anonymous upload beacon: DISABLED
(HEADROOM_TELEMETRY=off)`
- **Not tested:** a real `headroom install apply` of a persistent
service on this branch; the manifest change is covered through
`_build_deployment_manifest`. Upgrading an existing install was not
tested either; see the warning at the top.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-16 14:32:06 -07:00
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 (e10141c3) with this round's tests
$ pytest tests/test_cli_learn.py -q
FAILED tests/test_cli_learn.py::test_activate_output_shaper_reports_effective_rollout_decision[True-live]
FAILED tests/test_cli_learn.py::test_activate_output_shaper_reports_effective_rollout_decision[False-blocked]
FAILED tests/test_cli_learn.py::test_activate_output_shaper_handles_malformed_response
FAILED tests/test_cli_learn.py::test_verbosity_apply_records_the_pin_it_sets
FAILED tests/test_cli_learn.py::test_verbosity_apply_replaces_the_pin_an_earlier_apply_set
FAILED tests/test_cli_learn.py::test_verbosity_apply_keeps_a_pin_it_cannot_prove_it_set[no-start-time]
FAILED tests/test_cli_learn.py::test_verbosity_pin_record_is_written_with_lf
FAILED tests/test_cli_learn.py::test_verbosity_apply_records_a_pin_the_proxy_applied_while_the_shaper_is_disabled
FAILED tests/test_cli_learn.py::test_verbosity_apply_reports_activation_when_the_pin_cannot_be_recorded
FAILED tests/test_cli_learn.py::test_verbosity_apply_does_not_record_a_pin_without_a_process_identity
10 failed, 31 passed in 0.74s

# After: this branch
$ pytest tests/test_cli_learn.py -q
50 passed in 0.71s

# Offline-egress coverage (failed on e10141c3 in CI shard 3)
$ pytest tests/test_offline_egress_chokepoint.py -k test_every_egress_site_is_guarded_or_allowlisted -q
1 passed, 142 deselected in 2.63s

# Related suites (learn, verbosity, output shaper, runtime-env), with branch coverage of the changed file
$ pytest tests/test_*learn*.py tests/test_*verbosity*.py tests/test_*output_shaper*.py tests/test_*runtime_env*.py -q --cov=headroom.cli.learn --cov-branch
207 passed, 3 warnings in 7.83s
# lines/branches added by this PR in headroom/cli/learn.py that are not covered: none

$ ruff check headroom/cli/learn.py tests/test_cli_learn.py
All checks passed!
$ ruff format --check headroom/cli/learn.py tests/test_cli_learn.py
2 files already formatted
```

## Real Behavior Proof

- Environment: macOS (Apple Silicon), Python 3.11. A real `headroom
proxy --port 8799` in default cache mode from this checkout, with an
isolated `HEADROOM_WORKSPACE_DIR` and `--anthropic-api-url` pointed at a
closed local port, so no request left the machine. `headroom learn
--verbosity --apply` ran over real Claude Code transcripts and learned
level 3. Before = `origin/main`'s `headroom/cli/learn.py`; after = this
branch. A fresh proxy was used for each run.
- Exact command / steps: Start the proxy. Run `HEADROOM_PORT=8799
headroom learn --verbosity --apply --project <repo>`. Send one
`/v1/messages` request through the proxy. Read `/health`
`config.runtime_env` and the proxy's `OutputShaper(...)` log line.
- Observed result: before, the CLI says level 3 is live while the proxy
steers at L2. After, the level is pinned and the proxy steers at L3:

  ```text
  ===== BEFORE (origin/main learn.py), proxy in default cache mode
  >> Recommended verbosity level: 3 (confidence: high)
✓ Output shaper enabled on the running proxy (port 8799); level 3 is
live now (while HEADROOM_VERBOSITY_LEVEL is unset).
To keep it on across restarts: export HEADROOM_ROLLOUT_CHANNEL=beta and
HEADROOM_OUTPUT_SHAPER=1 before `headroom wrap ...`.
proxy /health: {"mode": "cache", "HEADROOM_OUTPUT_SHAPER": "1",
"HEADROOM_VERBOSITY_LEVEL": null}
  proxy log: OutputShaper(L2/cache_mode_default)

  ===== AFTER (this branch), proxy in default cache mode
  >> Recommended verbosity level: 3 (confidence: high)
✓ Output shaper enabled on the running proxy (port 8799); level 3 is
live now (pinned with HEADROOM_VERBOSITY_LEVEL: cache mode does not read
the learned level).
Conversations already open re-cache their prompt once, because the
steering text changed.
To keep it on across restarts: export HEADROOM_OUTPUT_SHAPER=1
HEADROOM_VERBOSITY_LEVEL=3 before `headroom wrap ...` or `headroom
proxy`.
  --- verbosity_pin.json: {"port": 8799, "pid": 25345, "level": 3}
  --- second --apply against the same proxy:
✓ Output shaper enabled on the running proxy (port 8799); level 3 is
live now (pinned with HEADROOM_VERBOSITY_LEVEL: cache mode does not read
the learned level).
proxy /health: {"mode": "cache", "HEADROOM_OUTPUT_SHAPER": "1",
"HEADROOM_VERBOSITY_LEVEL": "3"}
  proxy log: OutputShaper(L3/env_pinned)
  ```
- Not tested: a real token-mode proxy, one with an operator-set
`HEADROOM_VERBOSITY_LEVEL`, and a second `--apply` that learns a
*different* level (all covered by the CLI tests against a stubbed proxy;
the real run above re-learns the same level 3); multi-worker proxies,
which reject `/admin/runtime-env` before and after this change; Windows
(the record write is covered by a `windows_newline` test).

## Runtime Rollout Safety

- Rollout-managed feature(s): `proxy_output_shaper` (unchanged). This PR
only changes what the `headroom learn` CLI sends to and prints about a
running proxy.
- Minimum rollout channel: stable.
- Stable/default behavior changed: only `learn --verbosity --apply`
against a running cache-mode proxy with no `HEADROOM_VERBOSITY_LEVEL`.
It now also pins that variable to the learned level, which is what the
CLI already claimed. The proxy itself is unchanged.
- Kill switch / disable path: run `learn --verbosity` without `--apply`;
or POST `{"HEADROOM_VERBOSITY_LEVEL": ""}` / restart the proxy to drop
the hot override.
- Unsafe override required: no.
- Qualification impact: none expected.
- Rollback path: revert this commit.

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have 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

- Type checking was not run locally.
- Pin ownership: `/health` cannot say whether `HEADROOM_VERBOSITY_LEVEL`
came from startup env or a hot override, so `--apply` keeps its own
record. The process start time is derived from `/health` rather than
adding an instance id to the proxy, which keeps this PR CLI-only. The
one remaining ambiguity is an operator hot-POSTing the *same* value to
the *same* proxy process after `--apply` pinned it. That pin would be
treated as ours, but its value is the one `--apply` set anyway.
- Locally, 5 OTLP/Langfuse tests in `test_offline_egress_chokepoint.py`
fail on both `origin/main` and this branch because the dev venv lacks
`opentelemetry-exporter`; they pass in CI.


## Maintainer follow-up at 8c3eba8919

Ownership now compares the exact raw `HEADROOM_VERBOSITY_LEVEL` value
from the same health snapshot as process identity. A changed operator
value is preserved even when it clamps to the same effective level as a
previous CLI pin (for example, CLI4 followed by operator8). The display
still reports the effective clamped level. The new regression fails on
the preceding head and passes here; existing CLI ownership/restart/error
behavior remains covered.

Fresh validation:140 CLI/verbosity/output-shaper/runtime-env tests pass
with one existing warning; Ruff lint/format and Linux-platform mypy
over566files pass. Actual proxy/CLI proof additionally covers learning3,
re-learning1, preserving an operator8 pin, and the
changed-raw/same-clamped-level ownership case. The last case fails
before this follow-up and passes afterward.

Exact commands and full runnable Windows/Python3.12 script: [maintainer
evidence](https://github.com/headroomlabs-ai/headroom/pull/4033#issuecomment-6063120923).
Save the script as `verify_learn_pin.py` in the checkout root and run
`python verify_learn_pin.py` with proxy dependencies installed.
Synthetic Claude transcripts are processed by the real analyzer; no live
LLM judge or provider request is made. Hosted CI and fresh review must
qualify this new head before approval.

---------

Co-authored-by: Kenneth Wong <17061293+KennethWKZ@users.noreply.github.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-08 10:48:59 -05:00
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>
2026-10-07 10:58:59 -05:00
Ayush Kumar JhaandJerrett Davis 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 e8754b61): OpenCode printed `> build ·
deepseek-chat` and `hello from fake deepseek`. The upstream logged
`{"path": "/v1/chat/completions", "model": "deepseek-chat", "auth":
"Bearer sk-fa...", "stream": true}`. The config kept `apiKey` and
`deepseek-chat` alongside Headroom's `baseURL` and defaults.
- Not tested: a live request against `api.deepseek.com` with a real key,
since none is available here. The real-OpenCode run above uses a local
fake upstream instead, so it proves model selection, key forwarding and
routing through Headroom but not DeepSeek's own API. The
`--copilot-subscription` rejection was exercised as a unit test, not
against a real Copilot subscription.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — a CLI option and its plumbing, not
gated by the rollout-channel machinery.
- Minimum rollout channel: n/a, not rollout-gated.
- Stable/default behavior changed: no — without the flag and without
`OPENAI_TARGET_API_URL`, `openai_api_url` stays `None` and the proxy
resolves its upstream exactly as before; a test pins this.
- Kill switch / disable path: omit the flag and leave
`OPENAI_TARGET_API_URL` unset — behavior is identical to the previous
default.
- Unsafe override required: no.
- Qualification impact: none — no change to compression, routing, or the
proxy request path; the option only chooses which upstream URL the proxy
is started with.
- Rollback path: revert this commit — no config, cache, or on-disk state
is written by the new option, so a revert needs no cleanup.

## 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 docs change.

## Additional Notes

- The `x-headroom-base-url` header workaround from the issue is
deliberately left out of the DeepSeek guide. With `--openai-api-url` the
proxy targets the right upstream directly, so the header is no longer
needed for this case. It stays documented where it belongs, in
`configuration.mdx` and `pipeline-extensions.mdx`, as a per-request
override.
- Scope is intentionally limited to `wrap opencode`, the command named
in the issue. Other `wrap` subcommands that hardcode an upstream
(`mistral`, `kimi`, `grok`) or detect one (`zcode`) are unaffected;
giving the whole wrap family a uniform upstream override is a reasonable
follow-up, not this fix.

---------

Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
2026-10-06 08:45:54 -05:00
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>
2026-10-01 00:09:27 -05:00
AxelRayandJD Davis 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>
2026-09-30 22:42:26 -05:00
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>
2026-09-28 18:06:09 -07:00
Yevhen KovalandJerrettDavis 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
5a323bd8

$ grep -n "CodeCompressor\*\* — AST-aware" README.md
368:- **CodeCompressor** — AST-aware for Python, JS/TS, Go, Rust, Java, C/C++, C#, PHP.

$ grep -n "Multi-language support\|^| 2 |" wiki/transforms.md
158:- **Multi-language support** — Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, PHP
231:| 2 | Go, Rust, Java, C, C++, C#, PHP | Function body compression |
354:| 2 | SmartCrusher | Compress JSON tool outputs |

$ sed -n "18,19p" headroom/transforms/code_compressor.py
Supported Languages (Tier 2):
- Go, Rust, Java, C, C++, C#, PHP

$ grep -n "Perl" README.md wiki/transforms.md || echo PERL_ABSENT_FROM_LISTS
PERL_ABSENT_FROM_LISTS

$ grep -n "_UNSAFE_TREE_SITTER_LANGUAGES" headroom/transforms/code_compressor.py
106:_UNSAFE_TREE_SITTER_LANGUAGES: frozenset[str] = frozenset({"perl"})
136:    if language in _UNSAFE_TREE_SITTER_LANGUAGES:

$ grep -n "CSHARP = \|PHP = \|CodeLanguage.CSHARP: LangConfig\|CodeLanguage.PHP: LangConfig" headroom/transforms/code_compressor.py
225:    CSHARP = "csharp"
226:    PHP = "php"
440:    CodeLanguage.CSHARP: LangConfig(
469:    CodeLanguage.PHP: LangConfig(

$ python3 -m py_compile headroom/transforms/code_compressor.py && echo PY_COMPILE_OK
PY_COMPILE_OK

$ git log -1 --format=%B | npx -y -p @commitlint/cli -p @commitlint/config-conventional commitlint --config .commitlintrc.json
(exit 0)

$ git diff --stat main..HEAD
 README.md                              | 2 +-
 headroom/transforms/code_compressor.py | 2 +-
 wiki/transforms.md                     | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)
```

## Real Behavior Proof

- Environment: Linux 6.18 (CachyOS), system Python 3.14.7, checkout of
`headroomlabs-ai/headroom` `main` at 34a55175 (v0.36.5), branch
`docs/readme-code-languages`. No `uv`/dev venv on this machine.
- Exact command / steps: the `grep` / `sed` / `py_compile` /
`commitlint` / `git diff --stat` commands pasted above, run after the
patch.
- Observed result: all four language lists name C# and PHP; Perl is
absent from README and wiki; the quarantine guard and the C#/PHP
`LangConfig` entries exist at the quoted lines on current `main`; the
module still byte-compiles; the commit message passes the repo's
commitlint config; diff is 4 lines across 3 files, docs/docstring only.
- Not tested: `uv run pytest` / `ruff` / `mypy` / `make ci-precheck` —
not run locally (no dev environment here); no runtime path is touched,
so the compressor's behavior is unchanged by construction. The docs site
(`docs/`) is untouched because it was already correct.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A (documentation 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 the commit

## Review Readiness

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

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] 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)

## Screenshots (if applicable)

N/A

## Additional Notes

- N/A checklist items: no code comments / tests to add for a docs-only
change; the test suite was not run locally (see "Not tested").
- `wiki/transforms.md`: per #2784 the wiki is unpublished markdown that
"needs no syncing". I still aligned its two lists because they were
factually wrong in the same way and the file was deliberately kept as a
migration backlog — happy to drop that hunk if you'd rather keep the PR
to README + docstring.
- Perl removal: if the quarantine is ever lifted (the upstream
tree-sitter-perl scanner wedge from #2185), Perl can be re-added to
these lists alongside the code change.
- Already correct and untouched: the `Supported: …` error string in
`_get_parser()` (`code_compressor.py:170`) and the docs site table.

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-09-25 10:37:14 -05:00
Rod BoevandJerrettDavis 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>
2026-09-24 23:50:27 -05:00
Tejas ChopraandClaude Opus 5 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>
2026-09-17 10:42:13 -07:00
Tejas Chopra 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

---------
2026-09-02 16:40:34 +05:30
Tejas ChopraandClaude Opus 5 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>
2026-09-02 15:53:35 +05:30
JD Davis 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
2026-08-27 12:26:22 -07:00
JD Davis 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
2026-08-13 15:06:21 -05:00
Tejas Chopra 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.
2026-08-04 19:22:42 -07:00
JD DavisandJD Davis 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>
2026-08-03 20:14:13 -07:00
JD DavisandJerrettDavis 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>
2026-08-03 04:42:48 -07:00
Tejas Chopra 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.
2026-07-30 22:59:41 -07:00
AxelRayandaxelray-dev 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 f74d874, branch
fix/readme-cache-aligner-detector-only-2592
- Exact command / steps: `rg -n "CacheAligner" README.md`; `rg -n
"CacheAligner.*stabilizes prefixes" README.md || echo OLD_CLAIM_ABSENT`;
`git diff --stat`
- Observed result: both README CacheAligner bullets use detector-only
wording; old "stabilizes prefixes" claim for CacheAligner is absent;
diff is README.md only (+2/-2)
- Not tested: docs-site marketing.tsx and wiki/index.md still carry
older CacheAligner marketing copy (out of scope for this README issue);
no runtime proxy/pytest path (docs-only)

## 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)

## Screenshots (if applicable)

N/A

## Additional Notes

- Scope is README only for #2592. Marketing site / wiki wording can be a
follow-up if maintainers want the same detector-only language there.

Co-authored-by: axelray-dev <axelray-dev@users.noreply.github.com>
2026-07-27 06:42:17 -07:00
Rod Boev 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.
2026-07-23 15:43:03 -07:00
Tejas Chopra 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)
2026-07-22 20:59:24 -07:00
kazandJerrettDavis 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>
2026-07-15 21:40:58 +00:00
Dávid BalatoniandJerrettDavis 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>
2026-07-15 21:06:30 +00:00
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 4f22cbb0
3 failed, 7723 passed, 515 skipped in 262.64s
  FAILED tests/test_cli/test_wrap_claude_base_url.py::test_wrap_marker_is_stale_when_pid_reused
  FAILED tests/test_rtk_session_savings.py::test_rtk_reader_returns_none_on_nonzero_exit
  FAILED tests/test_rtk_session_savings.py::test_lean_ctx_reader_returns_none_on_failure_and_logs
  → all three reproduce identically on unmodified origin/main (4f22cbb0), run the
    same way (same worktree + venv, sources switched): 3 failed, 7707 passed —
    this branch = baseline + the 16 new tests, nothing else changes.
    (The pre-rebase run against e8151f05 showed the same shape: one order-dependent
    flake that also reproduced on its baseline; these are env/order-dependent.)

$ uv run pytest tests/test_cli/ -q     # post-rebase
542 passed + 1 of the pre-existing failures above   # includes the 16 new test_wrap_omp.py tests

$ uv run ruff check . ; echo ruff-check-exit:$?
All checks passed!
ruff-check-exit:0

$ uv run ruff format --check .         # post-rebase
1 pre-existing violation: headroom/proxy/handlers/anthropic.py — flagged identically
on unmodified origin/main (not touched by this PR); every file this PR touches is clean

$ uv run mypy headroom               # post-rebase; output redirected to file; exit captured
Success: no issues found in 409 source files
mypy-exit:0
```

## Real Behavior Proof

- Environment: macOS 15 (arm64, M1 Pro), Python 3.12.13 (uv venv,
editable install incl. Rust `_core`), headroom @ this branch, base
extras only (no `[ml]`), Anthropic account signed into omp. Initial
proof ran on base e8151f05 with omp 16.3.6 (`@oh-my-pi/pi-coding-agent`
via bun); re-validated after the rebase onto 4f22cbb0 with omp 16.3.11 —
fresh numbers in the rebase-validation comment.

- Exact command / steps: four scenarios, run in this order —
1. Mechanism probe (why models.yml, not env): local HTTP probe server on
`127.0.0.1:18999`; ran `omp -p "say ok" --model claude-fable-5
--no-session --no-tools` once with
`ANTHROPIC_BASE_URL=http://127.0.0.1:18999`, once with
`~/.omp/agent/models.yml` containing `providers.anthropic.baseUrl:
http://127.0.0.1:18999`.
2. One-command path: `headroom wrap omp --no-rtk --port 8790 -- -p "Read
CHANGELOG.md and count how many '### Fixed' headings it contains. Answer
with just the number." --model claude-fable-5 --no-session --max-time
180`
3. Routing stats: separate proxy on :8788, wrap with `--no-proxy`, then
`GET /stats`.
4. Restore: `headroom unwrap omp`, plus an isolated
`PI_CODING_AGENT_DIR=/tmp/omp-agent-test` run with a pre-existing user
`models.yml`, then `cmp` against the original.

- Observed result: end-to-end routing through the proxy proven for every
scenario —
- Probe: env-var run → **0 probe hits**, omp answered normally
(bypassed). models.yml run → **9 hits on `/v1/messages?beta=true`** with
real Messages bodies. This is the routing mechanism the wrap uses.
- One-command run: wrap started the proxy ("Proxy ready on
http://127.0.0.1:8790"), wrote the override (`models.yml:
providers.anthropic.baseUrl=http://127.0.0.1:8790/p/headroom-wrap-omp`),
launched omp, and omp answered **"7"** (correct — real `read` tool work
through the proxy). Proxy log for the session (3 requests,
`anthropic_messages` path):
    ```
PERF model=claude-fable-5 msgs=1 tok_before=36 cache_read=0
cache_write=61939 cache_hit_pct=0
PERF model=claude-fable-5 msgs=3 tok_before=796 cache_read=0
cache_write=63308 cache_hit_pct=0
PERF model=claude-fable-5 msgs=5 tok_before=935 cache_read=63308
cache_write=215 cache_hit_pct=100
    ```
    Prompt caching survives the proxy (100% hit on the follow-up turn).
- Routing stats (:8788 session): `requests.total: 2, by_provider:
{"anthropic": 2}, by_model: {"claude-fable-5": 2}`, per-project prefix
`/p/headroom-wrap-omp` attributed.
- Unwrap: `Removed wrap-created models.yml` (file gone); isolated
pre-existing-file run: backup created, user's `my-gw` provider preserved
in the managed file, and after `unwrap omp` the restored file is
**byte-identical** (`cmp` clean).
- Compression: **not observed in this environment** — `tok_saved=0`,
`transforms=router:noop` / `too_small`. Honest reading: omp minimizes
its own tool outputs client-side (a 300-item JSON tool result reached
the proxy at only ~657 tokens) and the `[ml]` text compressor wasn't
installed; small print-mode payloads sit below crush thresholds, and
passthrough-by-default is the documented safety contract. The wrap's
value here is proven at the routing/lifecycle/cache layer; compression
numbers will match whatever the proxy does for a given content mix.

- Not tested: Windows / Linux; lean-ctx mode with omp
(`HEADROOM_CONTEXT_TOOL=lean-ctx` — `lean-ctx init --agent omp` depends
on lean-ctx recognizing the agent; failure degrades with a warning by
design); long interactive (non `-p`) sessions; `--memory` / `--learn` /
`--code-graph` flags combined with omp; OAuth-vs-API-key matrix beyond
my local account.

## 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
- [ ] New and existing unit tests pass locally with my changes — all
except the 3 documented pre-existing failures, which fail identically on
unmodified origin/main
- [x] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A — terminal evidence inline above.

## Additional Notes

- The models.yml override is regenerated from the pristine backup on
every wrap, so re-running with a different `--port` updates the endpoint
idempotently and the backup is never clobbered.
- Scope note from #1149 stands: this routes omp's **Anthropic** provider
family. omp's other providers (OpenAI-direct, Gemini, ...) resolve their
endpoints from their own registry entries; users can already point those
at Headroom with their own custom provider in `models.yml`.
- `headroom/providers/omp/` deliberately contains no install-time / MCP
pieces — this is the thin wrap + unwrap slice only.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Tejas Chopra <chopratejas@gmail.com>
2026-07-15 19:30:19 +00:00
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>
2026-07-15 18:51:38 +00:00
JD Davis 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.
2026-07-15 18:37:20 +00:00
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>
2026-07-14 16:07:39 -04:00
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>
2026-07-14 16:07:17 -04:00
Gregory R. WarnesandJD Davis 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>
2026-07-14 13:25:37 -04:00
Rod Boev 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.
2026-07-14 13:25:29 -04:00
Dylan Russell, MDandJerrettDavis 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>
2026-07-14 13:25:21 -04:00
Ship-WrightandJerrettDavis 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>
2026-07-14 13:25:14 -04:00
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>
2026-07-08 09:16:11 -05:00
Dustin Burke 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. -->
2026-07-07 23:27:56 -05:00
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` (9fbd47ba).
- Exact command / steps: reviewed the reversibility docs and code
referenced in the issue (lean-ctx
`docs/comparisons/vs-headroom.md#reversibility`,
`rust/src/proxy/ccr.rs`); edited the single table row; rendered the
Markdown table locally to confirm column alignment.
- Observed result: row now matches lean-ctx's documented scope, deploy
surfaces, and reversibility; table renders with the same five columns as
the surrounding rows.
- Not tested: independent runtime verification of every lean-ctx
recovery path (claims are per the lean-ctx maintainer's issue report and
linked docs/source).

## Review Readiness

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

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-07-07 23:06:04 -05:00
KET ⚡andYour Name 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>
2026-07-07 12:51:22 -05:00
KET ⚡ 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
2026-07-07 12:51:02 -05:00
KET ⚡andYour Name 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>
2026-07-07 12:50:33 -05:00
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>
2026-07-06 18:33:34 -05:00
Tejas Chopra 7208792ee8 Fix formatting in README.md 2026-07-06 09:07:54 -07:00