mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
feat/https-compose-caddy
259
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
0d203db6b8 |
fix(copilot): keep new VS Code chats on the Local harness so they reach the proxy (#4899)
## Description
VS Code can run a Copilot chat on its "Copilot harness" (Agent Host, the
bundled Copilot SDK runtime) instead of the Local harness. That runtime
ignores `github.copilot.advanced.debug.overrideCapiUrl` /
`overrideProxyUrl`, so the chat goes straight to GitHub. Copilot's small
background calls (title, intent) still reach the proxy, so the proxy
looks connected while the main conversation never arrives. The harness
default (`chat.defaultToCopilotHarness`,
`chat.editor.preferCopilotHarness`) is tagged `experiment: startup` in
VS Code, so it can be flipped per user by rollout.
`headroom wrap vscode` now pins new chats to the Local harness.
## 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/providers/copilot/vscode.py`: the managed block also writes
`"chat.defaultToCopilotHarness": false` and
`"chat.editor.preferCopilotHarness": false`. Because they sit inside the
marker block, `headroom unwrap vscode` removes them. A harness setting
the user already set outside the block is left alone (no duplicate key).
New helper `copilot_harness_settings_enabled(path)` reports a user value
of `true`.
- `headroom/cli/wrap.py`: one line saying new chats stay on the Local
harness and existing chats keep their engine; a warning instead when the
user's own setting is `true`. `--no-configure` prints the two extra
settings.
- `docs/content/docs/vscode-copilot.mdx`: documents the harness settings
and the troubleshooting case.
- Blocks written by older versions (including ones with
`overrideAuthType`) are replaced by marker as before.
## 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
tests/test_provider_copilot_vscode_config.py + tests/test_cli/test_wrap_vscode.py: 32 passed.
Against origin/main source: 7 of those fail (block contents, old-block upgrade, user-set key [True]/[False], wrap output, --no-configure output).
ruff 0.17.4 check + format --check on the 5 changed Python files: clean.
mypy on the changed source files: 8 errors, all in headroom/cache/prefix_tracker.py and headroom/ccr/mcp_server.py, identical on origin/main; none in changed files.
```
## Real Behavior Proof
- Environment: macOS 27.2.1, Python 3.12.13, VS Code 1.145.2 with GitHub
Copilot signed in, core run from this branch, real GitHub Copilot
upstream. Real user `settings.json` (backed up and restored afterwards).
- Exact command / steps:
1. `headroom wrap vscode -p 8795` from this branch.
2. `code chat -n -m agent "Reply with the single word OK and nothing
else."` (opens a new VS Code window and sends one Agent-mode chat).
3. Read the proxy's `/stats`, VS Code's `agenthost.log`, then `headroom
unwrap vscode`.
- Observed result:
```text
VS Code Copilot proxy settings updated: ~/Library/Application
Support/Code/User/settings.json
Keep using Copilot's normal model picker; the selected model is
preserved.
New chats stay on VS Code's Local harness; a chat keeps the engine it
started with, so start a new chat.
settings.json after wrap:
{
// --- Headroom Copilot proxy ---
"github.copilot.advanced.debug.overrideProxyUrl":
"http://127.0.0.1:8795/p/win-local",
"github.copilot.advanced.debug.overrideCapiUrl":
"http://127.0.0.1:8795/p/win-local",
"chat.defaultToCopilotHarness": false,
"chat.editor.preferCopilotHarness": false
// --- end Headroom Copilot proxy ---
}
proxy requests before chat: 0 {}
proxy requests after one Agent-mode chat in a new VS Code window: 4
{'gpt-4o-mini-2024-07-18': 3, 'claude-opus-5.5': 1}
agent host turns during the chat: 0
Removed Headroom Copilot proxy settings from ~/Library/Application
Support/Code/User/settings.json
settings.json after unwrap:
{
}
```
Separately, on the same machine with the settings edited by hand (same
VS Code, same proxy, new window each time):
`"chat.defaultToCopilotHarness": true` -> the Agent-mode chat ran in the
Agent Host (provider `copilotcli`) and 0 requests reached the proxy;
`"chat.defaultToCopilotHarness": false` +
`"chat.editor.preferCopilotHarness": false` -> Local harness, 4 requests
reached the proxy including the main `/v1/messages` call.
`"chat.temporaryDefaultToLocalHarness": true` as a user setting had no
effect, so it is not written.
- Not tested: a VS Code where Microsoft's rollout has flipped the
default (the explicit user value is expected to win, but that could not
be reproduced); an organization that enforces managed sandbox settings,
where VS Code can require the Copilot harness regardless; VS Code
profiles, workspace-level settings, Insiders/VSCodium; Windows and
Linux; the persistent `headroom start --persistent --vscode` path in the
Enterprise client.
## Runtime Rollout Safety
- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: `headroom wrap vscode` writes two
more VS Code user settings inside its managed block. No proxy behaviour
changes.
- Kill switch / disable path: `headroom unwrap vscode` removes them; a
user who sets either key themselves keeps their value.
- Unsafe override required: no.
- Qualification impact: none expected.
- Rollback path: revert this commit; `unwrap` removes blocks of either
format.
## 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
- This keeps users off the Copilot harness; it does not route that
harness through Headroom. Supporting it is separate work.
- Only the configured settings file is checked for a user value. A
`true` in workspace settings, another profile, or policy is not
detected.
- After `unwrap` the keys return to VS Code's default, which a rollout
may move to the Copilot harness.
- Existing chats keep the harness they started with; the wrap output
says to start a new chat.
- `e2e/copilot_live.py` and `e2e/wrap/run.py` were not run.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4899"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
|
||
|
|
66e0086952 |
feat(opencode): add repeatable --extra-model flag for custom wrap-time models (#2364)
## Description
`headroom wrap opencode` injects a hardcoded model list
(`HEADROOM_OPENCODE_MODELS`) into the `headroom` provider block of
`opencode.json`. There's no way to add custom models (for example a
free-tier DeepSeek) at wrap time. Hand-patching `opencode.json` is the
only workaround, and the next wrap overwrites it.
This PR adds a repeatable `--extra-model` flag and a
`HEADROOM_OPENCODE_EXTRA_MODELS` env var. Both take
`id[=name[=context_window[=output_limit]]]` specs. Extra models are
merged into the injected provider block alongside the built-ins, and
flag specs win over env specs on id collision. `name` defaults to the
id, `context_window` to 200000, and `output_limit` to `min(16384,
context_window)`.
Fields are separated by `=` rather than `:` because model ids routinely
contain `:`. Ollama ids are `name:tag` (`qwen2.5-coder:7b`), and
OpenRouter free-tier ids end in `:free`. With a `:` separator those were
silently cut down to a different id (Devin review, 2026-10-03).
The PR also fixes the wrap/unwrap lifecycle the flag depends on. A wrap
that starts without an `opencode.json` used to write the file with no
backup and no record of what Headroom put in it, so `headroom unwrap
opencode` left the injected models and the proxy base URL behind while
reporting that OpenCode was no longer routed through Headroom, and a
re-wrap under `--openai-api-url` kept an extra model Headroom had
injected but no longer advertised. Wrap now records what it owns in
`opencode.json.headroom-managed.json`, and unwrap uses that record: it
removes the model ids and the base URL Headroom wrote, keeps everything
else in the file, drops an extra model that is no longer requested, and
deletes the config file when Headroom created it and nothing else is
left in it.
Closes #2359
## Type of Change
- [x] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [x] Documentation update
- [ ] Refactoring (no functional changes)
## Changes Made
- `headroom/providers/opencode/config.py`:
- New `parse_extra_model_spec()`, which splits on `=` with an optional
fourth `output_limit` field and raises `ValueError` on an empty id or a
non-integer / non-positive limit.
- New `extra_models_from_env()`, which reads comma-separated specs from
`HEADROOM_OPENCODE_EXTRA_MODELS`.
- An `extra_models` parameter threaded through
`headroom_provider_entry()`, `_render_provider_block()` and
`inject_opencode_provider_config()`.
- With `keep_user_entries` (#3125's `--openai-api-url` gate),
`--extra-model` entries win over a kept user entry with the same id.
- New managed-state sidecar (`opencode.json.headroom-managed.json`)
recording the model ids and base URL Headroom injected and whether
Headroom created the config file. `inject_opencode_provider_config()`
writes it on every injection; `record_opencode_config_origin()` marks a
config that Headroom creates because none existed.
- `remove_managed_opencode_provider()` drops the recorded model ids, the
recorded base URL, and the provider block once nothing else is left in
it. Entries the user added or edited are preserved.
- `_drop_stale_managed_models()` prunes an extra model Headroom injected
but no longer advertises, including an extra that overrode a built-in id
and is dropped again, so a re-wrap without the flag restores the
built-in defaults rather than keeping the old override.
- `snapshot_opencode_config_if_unwrapped()` no longer snapshots a config
Headroom wrote itself as pre-wrap content.
- `headroom/providers/opencode/runtime.py`: extras also reach the
launch-time `OPENCODE_CONFIG_CONTENT`.
- `headroom/cli/wrap.py`:
- A repeatable `--extra-model` option on `wrap opencode`. Env and flag
specs are parsed up front, and a malformed spec raises
`click.BadParameter`. The merged dict goes to both
`inject_opencode_provider_config` call sites (prepare-only and launch)
and to the launch env. Also adds a help text and docstring example.
- `wrap opencode` records the config origin before the first config
mutation.
- `unwrap opencode` undoes the recorded provider entries when there is
no pre-wrap backup, keeps the rest of the file, and removes a config
Headroom created once nothing Headroom-owned is left in it.
- `docs/content/docs/opencode.mdx`: new "Adding models" subsection
(format, defaults, Ollama/OpenRouter example, built-in id override, the
env var's no-comma limitation) and an env-var table row. The subsection
and the "How It Works Under The Hood" unwrap step now describe the
managed-state record and the automatic cleanup it enables.
- Tests:
- Spec parsing: full spec with output, defaults, the output cap at small
contexts, colon-bearing ids (`qwen2.5-coder:7b`,
`deepseek/deepseek-chat:free`, a name containing `:`), and invalid specs
including a bad output limit.
- Env parsing, provider-entry merge, and end-to-end inject. Also
@JerrettDavis's collision test across both `keep_user_entries` values.
- CLI: the flag reaches `opencode.json`, the env var persists, both
reach `OPENCODE_CONFIG_CONTENT` on launch, the flag wins over a kept
user entry under `--openai-api-url`, and a malformed spec exits with a
usage error.
- Managed state: the sidecar records the injected ids and base URL, a
config the user already had is not marked as Headroom-created, a re-wrap
does not snapshot Headroom's own config, a dropped extra model is pruned
(including an override of a built-in id, which returns to the built-in
defaults), a user model and a user-edited model survive, and the
provider removal keeps unrelated user entries.
- Lifecycle: a fresh wrap followed by an unwrap removes the config file
again (with and without the MCP entry), user content added after a fresh
wrap survives the unwrap, a re-wrap without the extra model drops the
stale one, and a directly injected provider entry is undone by the
unwrap callback as well.
- A user setting that is false, zero or an empty string is content, not
an empty section: such a setting survives the unwrap instead of costing
the user the whole file.
## Testing
- [x] Unit tests pass locally
- [x] Lint/format/type checks pass locally
- [x] New tests added for new functionality
The new parsing tests fail against the previous `:`-based parser:
```text
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_keeps_colons_in_ids[qwen2.5-coder:7b-...]
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_keeps_colons_in_ids[deepseek/deepseek-chat:free=DeepSeek Free-...]
FAILED tests/test_providers_opencode_config.py::test_parse_extra_model_spec_full
...
================ 21 failed, 2 passed, 103 deselected in 0.86s =================
```
With this branch (head
|
||
|
|
aa2093b4a0 |
fix(wrap): route Claude Code's Bedrock mode through Headroom (#4316)
## Why
`headroom wrap claude` silently bypassed Headroom for every Claude Code
user on Bedrock.
With `CLAUDE_CODE_USE_BEDROCK=1`, Claude Code ignores
`ANTHROPIC_BASE_URL` and calls AWS itself. wrap only sets
`ANTHROPIC_BASE_URL`, so it started a proxy that saw no traffic: no
error, no savings.
The flag usually lives in `~/.claude/settings.json`, which Claude Code
obeys over the shell, so exporting `CLAUDE_CODE_USE_BEDROCK=0` didn't
help either. A customer hit exactly this and needed a call to find it.
## What
When Bedrock mode is on, wrap routes it through Headroom using the path
that already works with the proxy's Bedrock backend:
- **Read the flag the way Claude Code does:** shell → user → project →
project-local settings → managed settings.
- **Proxy:** started with `--backend bedrock`, in the region Claude Code
would use, with the AWS settings it would read. Settings-file values are
copied in, and keys a settings file clears are cleared.
- **Claude Code:** launched in Anthropic mode against the proxy, with
`--settings '{"env":{"CLAUDE_CODE_USE_BEDROCK":"0"}}'`, which outranks
the settings files. A placeholder credential is added only if none is
configured. The proxy calls Bedrock with the user's AWS credentials.
- **Bedrock wins over Vertex and Foundry,** as it does in Claude Code
(checked: with both flags set, Claude Code calls the Bedrock endpoint).
- **Project-local settings aren't written in Bedrock mode,** since
daemon workers read them without the override.
Where routing isn't safe, wrap leaves the session alone and **says
Headroom is bypassed, and why**:
- the flag is in managed settings (they outrank `--settings`);
- a Bedrock gateway (`ANTHROPIC_BEDROCK_BASE_URL` /
`CLAUDE_CODE_SKIP_BEDROCK_AUTH`);
- `--no-proxy`;
- a non-Bedrock `--backend` / `HEADROOM_BACKEND`;
- the user's own `--settings`.
Also:
- **Managed settings are read tolerantly.** An unreadable file is
reported and skipped instead of stopping every `wrap claude`.
- **The env overlay moves to `providers/claude/runtime.py`**
(`claude_effective_env`) and is shared with the auth-conflict check.
That check now uses the same shell-first order, so settings files
outrank the shell as they do in Claude Code.
## Testing
- **Verified against Claude Code 2.1.304** with a loopback recorder:
- `settings.json` `env` beats the shell;
- `--settings` beats `settings.json`;
- Bedrock beats Vertex.
- **Unit:** 44 tests in `test_wrap_claude_vertex_proxy_env.py`, one per
case above, including the bypass reasons, the unreadable managed file,
region precedence, and the AWS profile reaching the proxy. A conftest
fixture keeps the host's managed-settings file out of CLI tests.
- **Wider suites:** `tests/test_cli`, the Claude provider and doctor
suites pass, except 5 tests that already fail on `main` on macOS:
- 4 in `test_wrap_persistent.py`: the fake `_Manifest` lacks
`runtime_kind`, which the darwin-only branch reads;
- `test_mcp_reconcile::test_ordinary_install_does_not_adopt_serena`,
which depends on whether `headroom` is on PATH.
- **Live, real Bedrock** (Sonnet 4.6, us-east-1), with this change on
core 0.41.0. Customer setup: `CLAUDE_CODE_USE_BEDROCK=1` only in
`~/.claude/settings.json`, plain `headroom wrap claude`:
- routed through Headroom: 13 requests, 0 failed;
- first request 18,312 tokens vs 22,648 sent straight to Bedrock (−19%,
with the tool-search and skill-search plugins).
## Related
- **#1220** routes Bedrock differently: it points
`ANTHROPIC_BEDROCK_BASE_URL` at the proxy and re-signs requests with
SigV4. In a live test it compressed nothing (Bedrock-mode bodies reach a
handler that runs no compression or hooks), and one stream hung for over
5 minutes. This PR uses the Anthropic-mode path the Bedrock backend
already serves.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4316"
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 `f1f11da91d481e48e57526a784187810f762c209` incorporates
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 44 existing
handoff tests pass; both existing effective-client probes fail:
competing Vertex flag remains enabled and user-settings remote base URL
wins over launched proxy URL. Ruff/format/diff pass; clean main sync, no
routing rewrite. Existing Changes Requested decision remains applicable;
unchanged findings are not reposted. Scoped Windows probes use the real
CLI configuration harness or actual metrics object, not live
cloud-provider traffic. Contributor correctness logic was not rewritten;
hosted checks are handled by maintainers. Nothing merged.
### Maintainer current-main requalification
Exact head `79b861ef2351bd321900b221f6cf99ad5cbedf27`, upstream main
`ecbaf86d78cf52d185fbffa306157b9a4cc1b906`.
Mechanically updated from upstream/main
|
||
|
|
2649835a51 |
feat(wrap): make the Serena code-memory MCP opt-in (#4509)
## What changes `headroom wrap claude|codex|grok|opencode` no longer registers Serena by default. | | Before | After | |---|---|---| | Default | Serena registered | No code-memory MCP | | Opt in | (default) | `--code-memory serena` or `HEADROOM_CODE_MEMORY=serena` (deprecated `--serena` still works) | | Opt out | `--code-memory none` / `--no-serena` | Still accepted | | Upgrading user, Serena installed by Headroom | Kept | Removed on next wrap, with the message "Serena is now off by default; pass --code-memory serena to keep it" | | Upgrading user, Serena added by hand | Kept | Kept, no message (shown only with `--verbose` or an explicit opt-out) | OpenCode now accepts `--code-memory` and uses the same setup path as the other agents. Its `--no-serena` flag is hidden and deprecated. ## Why Measured on 2026-10-27, Serena started exactly as `wrap` registers it: - It adds 22 tools, about 5.9K tokens of tool definitions on every request where tools aren't deferred. Its server instruction tells the model to call `initial_instructions`, which costs another 2K tokens. - Each launch takes about 6 s cold via `uvx`, plus a background `serena project index` that starts language servers. It also writes a `.serena/` folder into the user's repo. - Serena was registered in 6 of our own Claude Code sessions and called 0 times. Separately, an offline replay of about 108K tool calls found that symbol-level reads have little to recover for Claude Code. ## Not in this PR - `headroom.integrations.strands` still defaults `enable_serena_mcp=True`. It's public integration API, so it needs a deprecation step instead of a silent flip. - The opt-in `--serena-instructions` block in CLAUDE.md/AGENTS.md is never removed, by unwrap or anything else. Users who opted into it keep instructions that point at tools no longer registered. This predates this PR and will be fixed separately. - For Claude Code, Serena entries are per project, so removal happens the next time `wrap` or `unwrap` runs in each project. The docs say so. ## Tests - `pytest tests/test_wrap_code_memory.py tests/test_cli tests/test_mcp_registry`: 1368 passed. 5 failed, and those 5 fail the same way on `main` in my local venv: `test_mcp_reconcile.py::test_ordinary_install_does_not_adopt_serena` and 4 in `test_wrap_persistent.py`, all from an environment/install mismatch. - New tests: - The default wrap removes a Serena entry Headroom installed and prints how to keep it. - The default wrap leaves a hand-added Serena alone and prints nothing. - `--serena --no-serena` resolves to none. - `wrap opencode --code-memory serena` registers Serena with the `agent` context. - `ruff check`, `ruff format --check` and `mypy` are clean on the changed files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Real Behavior Proof - **Environment:** macOS (Darwin 27.2), Python 3.12.13, Claude Code 2.1.318, real `claude` CLI doing every `claude mcp add`/`remove`. A temporary `HOME`, so `~/.claude.json` starts empty, and a fresh git repo per case. - **Builds:** "before" = `main` at `12864fc8`; "after" = this PR at `56557dc9`. - **Command:** `headroom wrap claude --no-proxy [flags] -- --version`. Wrap does its full MCP setup, then launches Claude Code, which prints its version and exits, so no model call is made. `state` is read from `~/.claude.json` (user scope and this project's local scope) and the project's `.mcp.json` after each run. ``` == 1. Upgrade: Serena installed by Headroom (project/local scope) $ headroom wrap claude --no-proxy -- --version (cwd=projA, build=12864fc8) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| scoped to this project — pass --code-memory-scope user to register it for every Claude Code session wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projA): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projA, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projA): - | .mcp.json: - == 2. Upgrade: Serena added by hand (claude mcp add) state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projB, build=56557dc9) exit=0 wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy --code-memory none -- --version (cwd=projB, build=56557dc9) exit=0 wrap| Serena MCP is present but user-managed — leaving it in place (Headroom only removes entries it installed) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projB): ['serena'] | .mcp.json: - == 3. Explicit opt-in, then rollback to the default $ headroom wrap claude --no-proxy --code-memory serena -- --version (cwd=projC, build=56557dc9) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| scoped to this project — pass --code-memory-scope user to register it for every Claude Code session wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projC, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): - | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projC, build=56557dc9) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| scoped to this project — pass --code-memory-scope user to register it for every Claude Code session wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: - $ headroom wrap claude --no-proxy --serena -- --version (cwd=projC, build=56557dc9) exit=0 wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projC): ['serena'] | .mcp.json: - == 4. User scope: installed by Headroom with --code-memory-scope user $ headroom wrap claude --no-proxy --code-memory-scope user -- --version (cwd=projD, build=12864fc8) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| registered for every Claude Code session on this machine (--code-memory-scope user) wrap| 2.1.318 (Claude Code) state| user: ['headroom', 'serena'] | local(projD): - | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projD, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projD): - | .mcp.json: - == 5. User scope opt-in on the PR build $ headroom wrap claude --no-proxy --code-memory serena --code-memory-scope user -- --version (cwd=projE, build=56557dc9) exit=0 wrap| Serena MCP: registered (restart Claude Code if it was already running) wrap| registered for every Claude Code session on this machine (--code-memory-scope user) wrap| 2.1.318 (Claude Code) state| user: ['headroom', 'serena'] | local(projE): - | .mcp.json: - $ headroom wrap claude --no-proxy -- --version (cwd=projE, build=56557dc9) exit=0 wrap| Removed previously-installed Serena MCP (Serena is now off by default; pass --code-memory serena to keep it) wrap| 2.1.318 (Claude Code) state| user: ['headroom'] | local(projE): - | .mcp.json: - ``` What this shows: 1. A Serena entry Headroom installed on `main` is removed on the first wrap after upgrading, with the "off by default" message. This holds for both scopes (cases 1 and 4). 2. A hand-added Serena entry is kept, and the default wrap prints nothing. `--code-memory none` keeps it and says it's user-managed (case 2). 3. Opting in works with `--code-memory serena`, `HEADROOM_CODE_MEMORY=serena` and the deprecated `--serena`, at project scope and user scope (cases 3 and 5). Running the default afterwards rolls it back. 4. Project scope here means Claude Code's `local` scope, which is where wrap registers. Wrap never writes `.mcp.json`. Not tested live: `wrap codex|grok|opencode` (unit tests only), Windows, and an interactive Claude session that calls Serena tools. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4509" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> ## Maintainer post-merge qualification Published `983b6bb15119a3ecb8f6e20bf014b8bed123e95d` includes upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 19 selector/Serena tests pass,1optional skip; Ruff/format/diff pass. Clean main sync; contributor selector/ownership code unchanged. Existing real upgrade/configuration/launch proof requirement remains; jCodeMunch proposal is unrelated to this source delta. Contributor correctness logic was not rewritten. Existing Changes Requested decision retained without duplicate findings. Scoped Windows validation uses the existing development native extension, not a fresh build. Hosted qualification is handled by maintainers; nothing merged. ### Maintainer current-main requalification Exact head `e8e3011187a2ffdfbb6c9932db26b22ec911ab39`, upstream main `ecbaf86d78cf52d185fbffa306157b9a4cc1b906`. Mechanically updated from upstream/main |
||
|
|
bb8d18a56a |
feat(wrap): add headroom wrap droid for Factory Droid (#4143)
## Description Add `headroom wrap droid` so Factory subscription traffic, including Droid Core, can be compressed on the existing Factory plan. Droid ignores `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL` for Factory-served models. It honors `FACTORY_API_BASE_URL`. This wrapper points that at the local proxy and gives the proxy a Factory upstream (`--factory-api-url` / `FACTORY_TARGET_API_URL`, default `https://api.factory.ai`). With a Factory upstream configured the proxy registers: - `POST /api/llm/a/v1/messages` — compressed with the existing Anthropic pipeline and forwarded to `{factory}/api/llm/a/v1/messages`. A client-sent `x-headroom-base-url` is ignored. `x-headroom-*` headers are stripped. Operator Anthropic extra headers are withheld from the untrusted Factory host. - Every other `/api/*` path — forwarded verbatim to Factory, except Hermes Studio's scoped prefixes and requests that name their own `x-headroom-base-url`. Nothing outside `/api/` is sent to Factory. `select_passthrough_base_url` and `upstream_trust` are untouched, so a leftover Codex, Claude, or Copilot config pointed at a Factory-mode proxy keeps its own upstream and credentials. That is the deliberate difference from https://github.com/headroomlabs-ai/headroom/pull/2352, which is still open and which this does not close. #2352 sends every unrouted request on a Factory-mode proxy to Factory. `wrap droid` writes no Droid config. It threads `factory_api_url` through the existing proxy-reuse logic. With `--no-proxy` it refuses unless `/health` shows a Headroom proxy serving the same Factory upstream. OpenAI-shaped `/api/llm/o/*` traffic is forwarded uncompressed. Those routes are deferred. This commit is `74c889fb` rebased onto current `main` (`0dd8e0b5`). The only conflicts were `docs/content/docs/meta.json` (kept both the new `hermes` page and `droid`) and the `--no-proxy` branch in `headroom/cli/wrap.py` (kept upstream's OpenAI upstream check and the Factory check). Refs #2351 ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom wrap droid` sets `FACTORY_API_BASE_URL` to the local proxy and resolves the Factory upstream from `--factory-api-url`, then `FACTORY_API_BASE_URL`, then `https://api.factory.ai`. Loopback, credential, query, and fragment URLs are rejected. - Factory inference and `/api/*` passthrough routes are registered only when a Factory upstream is configured. The default proxy is unchanged. - `/health` reports `factory_api_url`. - Docs: `docs/content/docs/droid.mdx`. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output Rebased tree `/home/hermes/workspace/headroom-rebase` at `0dd8e0b5`, importing that tree via `PYTHONPATH` and the existing venv at `/home/hermes/workspace/headroom/.venv` (Python 3.11.16). ```text tests/test_cli/test_wrap_droid.py ............................ [ 31%] tests/test_provider_droid_runtime.py ................................ [ 66%] ``` 60 passed. Those are the wrap launch-env tests and the Factory runtime tests. `tests/test_proxy/test_factory_decoy_proof.py` did not complete in this worktree. The proxy refuses to start because `headroom._core` is not built here (`ModuleNotFoundError`, exit 78). Setting `HEADROOM_REQUIRE_RUST_CORE=false` still did not finish within 180s. The decoy proof (decoy upstream stays silent, Factory stand-in receives the inference request, spoofed `x-headroom-*` headers, REST passthrough, `--no-proxy` refusals) was written for this change and passed in the pre-rebase review session. It was not re-run to a green result after this rebase. `ruff` and `mypy` were not re-run after the rebase. ## Real Behavior Proof - Environment: Linux, Python 3.11.16, rebased commit `0dd8e0b5` on top of `upstream/main` `8c1beb20`. No Factory token. No call to `api.factory.ai`. - Exact command / steps: `PYTHONPATH=/home/hermes/workspace/headroom-rebase /home/hermes/workspace/headroom/.venv/bin/python -m pytest tests/test_cli/test_wrap_droid.py tests/test_provider_droid_runtime.py` - Observed result: 60 passed. - Not tested: a live Factory subscription, `droid` itself, the socket decoy proof on this rebased commit (blocked locally by the missing Rust extension), `ruff`, `mypy`, and CI on GitHub. ## Runtime Rollout Safety - Rollout-managed feature(s): none. Factory routes register only when `factory_api_url` / `--factory-api-url` is set. - Minimum rollout channel: stable. Default proxy behavior is unchanged. - Stable/default behavior changed: no, unless a Factory upstream is configured. - Kill switch / disable path: do not pass `--factory-api-url` and do not set `FACTORY_TARGET_API_URL`. `wrap droid` is opt-in. - Unsafe override required: no. - Qualification impact: none on the default proxy. - Rollback path: revert this commit. No config is written into Droid. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review The pre-rebase commit `74c889fb` was approved by a fresh Claude Opus 5.5 high review with an empty blocking list. This commit is that change rebased onto current main. The two conflict resolutions are described above and have not had a second Opus pass. ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes Does not close #2352. That PR is the prior attempt. This one is a current-main rebuild with the catch-all leak removed: only `/api/*` is forwarded to Factory. akbarkanso is not a Headroom maintainer. Please do not expect this account to merge. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4143" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> ### Maintainer current-main requalification Exact head `e28dfe6422dfcb9b2cbd5ce0fe673196d3b6ad40`, upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. Updated against upstream/main |
||
|
|
8f50884bd5 |
fix(init): handle non-UTF-8 directory names when deriving the init profile (#4673)
## Description
`headroom init` derives a profile id in `_local_profile` with
`sha1(str(root).encode("utf-8"))`. On POSIX a directory name can hold
bytes that are not valid UTF-8; pathlib represents them as surrogate
escapes, and `.encode("utf-8")` raises `UnicodeEncodeError`. The fix
falls back to `os.fsencode(root)` only when UTF-8 encoding fails, so
existing profile ids for normal paths are unchanged and distinct byte
names stay distinct.
Closes #4267
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- `headroom/cli/init.py`: UTF-8 first, `os.fsencode` fallback in
`_local_profile`.
- `tests/test_cli/test_init_cli.py`: regression test using two distinct
non-UTF-8 byte names (POSIX only; fails on `main`, passes now).
## Testing
- [x] Unit tests pass: `tests/test_cli/test_init_cli.py`, 97 passed (1
failed on `main` with the new test)
- [x] Linting passes (`ruff check` / `ruff format --check` on touched
files)
- [ ] Type checking (`mypy headroom`): not run
- [x] New tests added
## Real Behavior Proof
- Environment: macOS, Python 3.12.
- Exact command / steps: called `headroom.cli.init._local_profile` on
`Path(os.fsdecode(b"/nonexistent/proj-\xff"))`, `...\xfe`, and a normal
UTF-8 name.
- Observed result: before, `UnicodeEncodeError: 'utf-8' codec can't
encode character '\udcff'`; after, three valid, distinct
`init-proj-<hash>` ids.
- Not tested: the actual `headroom init hook ensure` command in a real
non-UTF-8 directory (macOS/APFS cannot create such a directory, so the
paths above do not exist on disk), Linux, Windows, mypy, full suite,
pre-push hooks.
## Test Output
Author-reported results (not rerun by the maintainer for this body
clarification): `tests/test_cli/test_init_cli.py`: 97 passed; the new
regression failed on main before the fix. Scoped Ruff check and format
check passed. The Real Behavior Proof section above records the
helper-level before/after result and its untested scope.
## Runtime Rollout Safety
- Rollout-managed feature(s): none; this is a profile-ID derivation bug
fix in `headroom init`.
- Minimum rollout channel: no new rollout channel or gate.
- Stable/default behavior changed: paths that can be encoded as UTF-8
retain the existing digest input. Only `UnicodeEncodeError` selects
filesystem bytes for the digest.
- Kill switch / disable path: revert the fallback change; this restores
the previous error for the affected non-UTF-8 paths.
- Unsafe override required: no.
- Qualification impact: the reported helper regression covers distinct
surrogate-escaped byte names. Actual init/hook execution in a real
non-UTF-8 directory and broader platform behavior remain outside the
reported proof.
- Rollback path: revert the fallback change. This PR does not migrate
existing profiles or rewrite stored profile IDs.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] I did **not** edit `CHANGELOG.md`
This change was prepared with AI assistance (Claude Code).
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4673"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
|
||
|
|
7877241d84 |
feat(providers): add Hermes agent wrap support (#934)
## Description Adds first-class Hermes Agent support to `headroom wrap` while preserving the current provider architecture. The wrapper prepares both OpenAI- and Anthropic-compatible environment variables, supports argument forwarding and `--prepare-only`, and reports a clear installation error when the Hermes binary is unavailable. This update also changes the missing-binary test to assert the complete CLI output, resolving CodeQL's URL-substring sanitization false positive without weakening coverage. ## Changes Made - integrate Hermes launch-environment construction into the existing provider module - route OpenAI and Anthropic endpoints through Headroom - support Hermes argument forwarding and prepare-only setup - cover missing-binary, launch, and compression/passthrough behavior - use an exact expected error message in the CLI test for CodeQL compatibility **Provider contract:** `headroom wrap hermes` requires `--provider anthropic` or `--provider openai`. Any other selection, or no flag, exits with code 1 before the proxy or Hermes starts. ## Testing - [x] Unit tests pass - [x] Linting and formatting pass - [x] New tests added ### Test Output ```text 20 focused Hermes tests passed ruff check: passed ruff format --check: passed git diff --check: passed ``` - `uv run --extra dev pytest tests/test_providers/test_hermes.py tests/test_cli/test_wrap_hermes.py tests/test_hermes_passthrough_compression.py -q` (20 passed) - `uv run --extra dev ruff check tests/test_cli/test_wrap_hermes.py` - `uv run --extra dev ruff format --check tests/test_cli/test_wrap_hermes.py` - `git diff --check` ## UI evidence Not applicable. This PR changes CLI/provider behavior and tests; it does not alter a graphical UI. ## Checklist - [x] Tests added or updated - [x] Focused tests pass locally - [x] Formatting and lint checks pass - [x] No UI screenshots required - [x] No changelog entry required for this focused provider integration ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Breaking change - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring ## Real Behavior Proof - Environment: current Hermes provider/wrapper test environment. - Exact command / steps: ran the Hermes provider, CLI wrapper, and passthrough/compression suites plus Ruff, formatting, and diff checks. - Observed result: 20 focused tests pass; OpenAI and Anthropic endpoints route through Headroom, arguments and prepare-only work, and missing binaries produce the exact expected error. - Not tested: a live Hermes Agent session against production providers. ## Runtime Rollout Safety - Rollout-managed feature(s): None. This adds a new opt-in `headroom wrap hermes` command. - Minimum rollout channel: N/A - Stable/default behavior changed: No. Other wrap commands and proxy behavior do not change. - Kill switch / disable path: Do not run `headroom wrap hermes`. Hermes can also be started without the wrapper. - 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 <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/934" 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 `ef4c2c11cd6359aaf4239f9cc394c28c23985c15`, upstream main `2d3ee51846435ef5b320eea4806af14e602b0d8c`. Clean mechanical synchronization with upstream main 2d3ee51846435ef5b320eea4806af14e602b0d8c; contributor routing policy unchanged. Current author replies and Devin findings reviewed. The previous default-routing blocker is addressed: the wrapper rejects absent/unsupported provider flags before calling _launch_tool, and permits explicitly selected anthropic/openai providers. The launch-boundary regressions exercise both rejected/default and supported paths. Explicit empty environments remain isolated, and the shared port callback is retained. Hermes/provider/port-alignment tests pass; changed-file Ruff lint/format and main-relative whitespace checks pass. Existing native extension supports Python startup, not a fresh native build. The author's Hermes0.22.2 WSL rejected/default and explicit-provider startup evidence is considered; this round does not claim live authenticated provider traffic. Project attribution, retrieval-plugin setup and a possible registry consolidation remain separate follow-ups rather than claims that the wrapper installs the plugin or supports other providers. No remaining finding in the previously requested provider-guard scope. Formal approval awaits exact-head hosted qualification, handled by maintainers. Author readiness state preserved; 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 Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
02c4e922f7 |
fix(cli): resolve active proxy port for read commands (#3522)
## Description `headroom wrap copilot` can intentionally start a dedicated proxy on port 8788 (or fall forward when 8787 is busy), but read-only CLI commands previously defaulted directly to 8787. As a result, `headroom dashboard` could open a dead or unrelated dashboard even though the wrapped session reported its proxy on 8788. This change extends the shared `headroom/cli/port_discovery.py` resolver (introduced by #3855) to include live wrap-client markers, preferring the newest healthy session while preserving explicit `--port` and `HEADROOM_PORT` overrides. Closes: N/A (no matching open issue found) ## 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 - Extended the shared port discovery module from #3855 with live wrap-client marker validation (PID liveness and reuse checks), newest-session ordering, and `/health` verification. - Updated `dashboard`, `inspect`, and the runtime probe used by `learn` to follow the newest healthy live wrap session after explicit and `HEADROOM_PORT` overrides. - Kept `doctor`'s requested-port behavior; it now reports a healthy proxy discovered from wrap-client markers elsewhere, with a `--port` hint. - Added a warning when `dashboard` cannot reach the resolved port. - Exported the actual proxy port as `HEADROOM_PORT` into every wrapped agent environment. - Reused #3855's port-discovery module rather than introducing a parallel resolver. - Added regression coverage for stale/recycled markers, multiple sessions, explicit/environment overrides, dashboard output, doctor diagnostics, inspect/learn routing, and wrapped child environments. - Documented automatic discovery and wrong-port 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 run pytest tests/test_cli/test_proxy_port_discovery.py \ tests/test_cli/test_dashboard_port_discovery.py \ tests/test_cli/test_port_alignment.py \ tests/test_cli/test_wrap_helpers.py \ tests/test_cli_doctor.py tests/test_cli_inspect.py tests/test_cli_learn.py -q 267 passed in 5.49s $ uv run ruff check . All checks passed! $ uv run ruff format --check . 1677 files already formatted $ uv run mypy headroom/cli/port_discovery.py headroom/cli/proxy.py \ headroom/cli/doctor.py headroom/cli/inspect.py headroom/cli/learn.py Success: no issues found in 5 source files $ uv run pre-commit run --all-files Sync plugin versions.....................................................Passed Verify Ruff version alignment............................................Passed check for merge conflicts................................................Passed ruff (legacy alias)......................................................Passed ruff format..............................................................Passed mypy.....................................................................Passed ``` After the first rebase, `make ci-precheck` completed `cargo fmt --check` and `cargo clippy --workspace -- -D warnings`, then stalled in the existing Rust Magika/detection tests (multiple tests exceeded 60 seconds). The same stall recurred during the push hook; it was stopped after confirming the affected suite. The final rebase onto #3883 was followed by the Python/CLI regression suite and all repository pre-commit gates above, but not another Rust test run. ## Real Behavior Proof - Environment: Ubuntu 22.04.5 LTS x86_64; Python 3.10.12; uv 0.12.10; Headroom proxy 0.40.0-dev, started on isolated port 18788 with an isolated live-client marker. - Exact command / steps: Started an isolated process that wrote its live PID marker and launched `headroom proxy --port 18788` under a temporary workspace, with `HEADROOM_PORT` unset; then ran `env -u HEADROOM_PORT -u HEADROOM_PORT_DISCOVERY HEADROOM_WORKSPACE_DIR=/tmp/headroom-port-discovery-proof-20260930/workspace ./.venv/bin/headroom dashboard --no-open` and curled `http://127.0.0.1:18788/dashboard`. ```text $ env -u HEADROOM_PORT -u HEADROOM_PORT_DISCOVERY \ HEADROOM_WORKSPACE_DIR=/tmp/headroom-port-discovery-proof-20260930/workspace \ ./.venv/bin/headroom dashboard --no-open Detected live proxy on port 18788 Dashboard: http://127.0.0.1:18788/dashboard $ curl --max-time 5 -sS -o /dev/null -w '%{http_code}\n' \ http://127.0.0.1:18788/dashboard 200 # Proxy health before discovery returned: service=headroom-proxy status=healthy ready=true ``` - Observed result: With `HEADROOM_PORT` unset, the CLI selected the marker-associated healthy proxy on 18788, printed the matching dashboard URL, and the endpoint returned HTTP 200. The earlier manual run with a real wrapped Copilot session also confirmed discovery on 8788 before this rebase. - Not tested: Starting a new interactive `wrap copilot` session after this rebase (avoided launching an agent); Windows/macOS PID-identity behavior; multiple simultaneous real proxies; browser UI launch. Unit tests cover marker ordering, PID reuse, and explicit/environment overrides. ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: N/A. - Stable/default behavior changed: `dashboard`, `inspect`, and `learn` now follow the newest healthy live wrap proxy when no port override is set; `doctor` remains on the requested/default port and reports a live proxy elsewhere. - Kill switch / disable path: Pass `--port`, set `HEADROOM_PORT`, or set `HEADROOM_PORT_DISCOVERY=0` to bypass automatic discovery. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert this commit; commands return to the fixed 8787 default. ## 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 ## Screenshots (if applicable) N/A — terminal output above captures the behavior. ## Additional Notes Port discovery is integrated into #3855's shared `port_discovery.py`; candidates are accepted only when `/health` identifies `service: headroom-proxy`, so an unrelated local JSON service cannot be mistaken for a Headroom proxy. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3522" 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 `e66a6393f83278aa07e9965f5b87fed820603677`, upstream main `2d3ee51846435ef5b320eea4806af14e602b0d8c`. Re-reviewed latest integration head |
||
|
|
05431b264f |
fix(install): make install status agree with doctor when the proxy is reachable (#3072) (#3141)
## Description `headroom install status` could report `Status: stopped` next to `Healthy: yes`, while `headroom doctor` reported the same proxy as running (#3072, bug 2). The commands used independent process views: `install status` trusted PID/container bookkeeping for `Status`, while both commands used the live HTTP health endpoints to establish health. This change treats a successful `/readyz` probe as authoritative evidence that the deployment is running. If the proxy is not ready, `runtime_status` still distinguishes a running-but-unhealthy process from a stopped process. The PR also adds a focused macOS pytest lane for CLI and install code, closing the Darwin test-coverage gap described in #3065 without duplicating the full four-shard Linux suite. Bug 1 from #3072 (`HEADROOM_PORT` being ignored by `install apply` and `deploy`) was already fixed on `main` by #3085 and is not reimplemented here. Closes #3072 Closes #3065 ## 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 - Updated `headroom/cli/install.py` so `install_status` performs one readiness probe and reports `Status: running` whenever `/readyz` is healthy. - Kept `runtime_status` as the fallback when the proxy is not ready, preserving the distinction between running-but-unhealthy and stopped. - Added regression coverage for the formerly contradictory `Status: stopped` plus `Healthy: yes` output. - Added regression coverage for the not-ready case where process status must still come from `runtime_status`. - Added a `test-macos` CI job that runs the CLI/install pytest subset on `macos-latest`. ## 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 --frozen --extra dev pytest tests/test_cli/test_install_cli.py -q ============================= test session starts ============================== platform darwin -- Python 3.11.15, pytest-9.0.3, pluggy-1.6.0 collected 42 items tests/test_cli/test_install_cli.py ..................................... [ 88%] ..... [100%] ============================== 42 passed in 1.79s ============================== $ uv run --frozen ruff check headroom/cli/install.py tests/test_cli/test_install_cli.py All checks passed! $ uv run --frozen ruff format --check headroom/cli/install.py tests/test_cli/test_install_cli.py 2 files already formatted $ uv run --frozen mypy headroom/cli/install.py --ignore-missing-imports Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: macOS (Apple Silicon), CPython 3.11.15 via `uv`, pytest 9.0.3. - Exact command / steps: ran `uv run --frozen --extra dev pytest tests/test_cli/test_install_cli.py -q`. The new regression test invokes `headroom install status` through Click's `CliRunner` with `/readyz` returning healthy while PID/runtime bookkeeping returns `stopped`. - Observed result: the command exits successfully and prints `Status: running` with `Healthy: yes`; `Status: stopped` is absent. A second test verifies that when readiness is false, a live runtime still prints `Status: running` with `Healthy: no`. - Not tested: an end-to-end persistent-service installation with a real OS supervisor or Docker daemon. The new macOS CI job itself will be exercised by GitHub Actions rather than locally. ## Runtime Rollout Safety - Rollout-managed feature(s): none; this changes diagnostic display logic and CI coverage only. - Minimum rollout channel: stable/default patch release. - Stable/default behavior changed: yes; `install status` now reports a ready deployment as running even if PID/container bookkeeping says stopped. Unready deployments retain the existing runtime-status behavior. - Kill switch / disable path: no runtime flag; revert this PR if the readiness precedence causes an unforeseen regression. - Unsafe override required: none. - Qualification impact: `tests/test_cli/test_install_cli.py` and the new `test-macos` CI job must remain green. - Rollback path: revert commit `f3ae269b`; no persisted state, schema, manifest, or configuration 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 - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) Not applicable; this is terminal status output and CI configuration. ## Additional Notes - Documentation was not changed because no command, option, configuration contract, or documented workflow changed; this corrects contradictory diagnostic output. - #2787 was also reviewed as an urgent author-reported issue, but it already has active implementation PR #2992. This PR deliberately avoids duplicating or conflicting with that work. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3141" 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 `f550bf1d05873b20b773d935aa7cb93025b63262`, upstream main `2d3ee51846435ef5b320eea4806af14e602b0d8c`. Re-reviewed latest integration head |
||
|
|
2892214881 |
fix(packaging): use direct CLI module entry point (#2665)
## Description Corrects the packaged `headroom` console-script entry point so it loads the concrete Click command from `headroom.cli.main:main` instead of relying on the package-level `headroom.cli:main` re-export. ## 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 - Updated `[project.scripts] headroom` in `pyproject.toml` from `headroom.cli:main` to `headroom.cli.main:main`. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - not needed for this metadata-only packaging target change - [ ] Type checking passes (`mypy headroom`) - not needed for this metadata-only packaging target change - [ ] New tests added for new functionality - not applicable; this points the existing console script at the existing CLI command - [x] Manual testing performed ### Test Output ```text .\.venv\Scripts\python.exe -c "from importlib.metadata import EntryPoint; ep=EntryPoint(name='headroom', value='headroom.cli.main:main', group='console_scripts'); obj=ep.load(); import click; assert isinstance(obj, click.core.Command); print(obj.name)" main .\.venv\Scripts\python.exe -m headroom.cli --help # exited successfully .\.venv\Scripts\python.exe -m pytest tests/test_cli/test_main_help_version.py -q 5 passed ``` ## Real Behavior Proof - Environment: Windows checkout using the repository `.venv`. - Exact command / steps: Loaded the proposed console-script entry point with `importlib.metadata.EntryPoint`, verified it resolves to a Click command, checked `python -m headroom.cli --help`, and ran the focused CLI help/version tests. - Observed result: `headroom.cli.main:main` resolves successfully to the CLI command, module help still works, and the focused CLI tests pass. - Not tested: rebuilding and installing a wheel from this branch; GitHub package checks have not run because only governance checks are currently present on 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 performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - not applicable for this one-line entry-point change - [ ] I have made corresponding changes to the documentation - not applicable; user-facing CLI behavior is unchanged - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - existing CLI tests cover the command surface - [x] New and existing relevant tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Screenshots (if applicable) N/A - packaging entry-point change only. ## Additional Notes This PR changes only the console-script target in `pyproject.toml`; it does not change CLI behavior or command implementation. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2665" 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 <mxjerrett@gmail.com> Co-authored-by: jd <jd@headroomlabs.ai> Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> |
||
|
|
fae1e849cb |
fix(wrap): route OMP OpenAI providers through Headroom (#2755)
## Description `headroom wrap omp` advertised OMP support but only redirected OMP's `anthropic` provider. OMP models under `openai` and `openai-codex`—including the current `openai-codex/gpt-5.6-sol` model—kept their native endpoints and bypassed Headroom. This change adds reversible `models.yml` base URL overrides for both OpenAI provider IDs while preserving the existing Anthropic route, provider credentials/headers, custom models, byte-for-byte backup, and `headroom unwrap omp` behavior. Follow-up to #1811. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Route `providers.openai.baseUrl` through the project-prefixed Headroom `/v1` endpoint. - Route `providers.openai-codex.baseUrl` through the same endpoint; OMP appends `/codex/responses`, which Headroom already supports for HTTP and WebSocket traffic. - Preserve all existing provider fields and the established backup/reinject/unwrap contract. - Show all three managed provider routes at launch and document the expanded OMP support. - Extend the existing OMP wrap tests for fresh injection, user-config preservation, reinjection, and CLI display. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ uv run --extra dev pytest -q tests/test_cli/test_wrap_omp.py 15 passed in 0.31s $ uv run --extra dev ruff check . All checks passed! $ uv run --extra dev ruff format --check . 1343 files already formatted $ uv run --extra dev mypy headroom Success: no issues found in 511 source files ``` The full pytest suite was started but not completed: after roughly 17 minutes it was still running unrelated Codex unwrap tests that repeatedly install/index Serena. No failure was observed before cancellation; the affected OMP suite is green. ## Real Behavior Proof - Environment: macOS Darwin 25.4 arm64 (Apple M5 Pro), Python 3.13.13, CLI code from this branch, published Headroom 0.33.0 proxy on port 8787, OMP 17.2.7, `openai-codex/gpt-5.6-sol` with stored ChatGPT/Codex OAuth. - Exact command / steps: Run the command below against the existing proxy, then inspect `/stats` and the managed `models.yml`. 1. Start or reuse the local proxy on `127.0.0.1:8787`. 2. Run: ```bash headroom wrap omp --no-proxy -- -p "Reply with exactly: HEADROOM_OMP_CODEX_OK" \ --model openai-codex/gpt-5.6-sol --no-session --no-tools \ --no-extensions --no-skills --no-rules --thinking off --max-time 30s ``` 3. Inspect `/stats` and the managed `~/.omp/agent/models.yml`. - Observed result: OMP returned the expected sentinel, Headroom recorded one new project request, and all three provider overrides were present. - Wrap printed all three routes: ```text providers.anthropic.baseUrl=http://127.0.0.1:8787/p/headroom providers.openai.baseUrl=http://127.0.0.1:8787/p/headroom/v1 providers.openai-codex.baseUrl=http://127.0.0.1:8787/p/headroom/v1 ``` - OMP returned exactly `HEADROOM_OMP_CODEX_OK`. - Headroom `/stats` recorded the new request under project `headroom` (`requests` increased from 2 to 3; `last_activity_at=2026-08-04T02:14:07Z`). - The managed `models.yml` contained all three overrides; the pristine backup remained the restore source. - The running 0.33.0 proxy does not contain the project-prefixed WebSocket fix from #2379, so this proves fallback-capable request completion rather than a clean WebSocket upgrade. - Not tested: a clean project-prefixed WebSocket upgrade against a release containing #2379; live `openai` API-key request; Windows/Linux; a long interactive or explicitly isolated WebSocket session; completion of the full unrelated pytest suite. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review An independent review pass found no correctness or security findings (confidence 0.96). ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes — affected tests pass; full suite did not finish as documented above - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title ## Screenshots (if applicable) N/A — terminal evidence is included above. ## Additional Notes Release prerequisite: Headroom 0.33.0 has a `/p/<project>` WebSocket upgrade bug that returns 403 before routing. It was independently fixed and merged in #2379 (`789a4f3060aa33a5bae82680968c3e367fa2db83`). This PR builds on `main`, which already contains that fix; stable interactive OMP WebSocket routing requires a release/backport containing #2379. The OpenAI API-key provider and ChatGPT/Codex OAuth provider intentionally share the local `/v1` base URL. Headroom distinguishes PAYG API keys from Codex OAuth JWT/account headers and forwards each request to the correct upstream. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/2755" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> Co-authored-by: Jerrett Davis <mxjerrett@gmail.com> |
||
|
|
342c495ea5 |
test(wrap): isolate two auth-precedence tests from the caller's ANTHROPIC_* env (#4601)
## Description
Two tests in `tests/test_cli/test_wrap_claude_vertex_proxy_env.py` fail
whenever the shell running pytest has `ANTHROPIC_AUTH_TOKEN` set:
- `test_wrap_claude_rejects_conflicting_auth_before_proxy_mutation`
- `test_wrap_claude_includes_shared_project_settings_in_auth_precedence`
Both came in with #2993. They put `ANTHROPIC_AUTH_TOKEN` in a settings
file and expect `headroom wrap claude` to name that file as the
conflicting source. Unlike the other tests in the module, they don't
call `_clear_claude_mode_env(monkeypatch)`. `CliRunner.invoke(env=...)`
adds to `os.environ` and doesn't replace it, so a shell-level token wins
the precedence check and the error names `shell environment` instead of
the settings file. Gateways and local routers that front Claude Code
(for example a local proxy or account switcher) commonly export
`ANTHROPIC_AUTH_TOKEN`, so on those machines the tests fail on clean
`main`.
The fix calls the module's existing helper at the start of both tests,
as the other tests already do. Nothing outside the tests changes.
## 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
- `tests/test_cli/test_wrap_claude_vertex_proxy_env.py`: call
`_clear_claude_mode_env(monkeypatch)` first in the two tests above. The
helper already clears `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`,
`ANTHROPIC_BASE_URL` and the other Claude-mode variables (2 lines
added).
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
# shell has ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL exported (values not shown)
$ HOME=$(mktemp -d) pytest -q tests/test_cli/test_wrap_claude_vertex_proxy_env.py # main
|
||
|
|
2643f34a54 |
fix(wrap): overwrite drifted selfheal hook command instead of skipping it (#2723)
## Description <!-- Briefly explain the change and why it is needed. --> Retain two originally published self-heal regression tests. Current `main` already contains the stronger runtime repair, so this refreshed proposal is test-only and does not replace or reintroduce the superseded runtime implementation. Related issue: headroomlabs-ai/headroom#2221. ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) Existing regression coverage only; the template has no test-only category. ## Changes Made - Preserve coverage for removing an empty Headroom-owned environment section and retaining unrelated user environment values. - Pin the retained fixture writes to LF. - Leave the current upstream self-heal runtime implementation unchanged. ## 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`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text env -u OPENAI_API_KEY -u ANTHROPIC_API_KEY -u GEMINI_API_KEY -u GOOGLE_API_KEY HF_HUB_OFFLINE=1 uv run --no-sync pytest tests/test_cli/test_wrap_dead_marker_selfheal.py -q 22 passed uv run --no-sync ruff check . All checks passed! uv run --no-sync ruff format --check . 1869 files already formatted uv run --no-sync mypy headroom 2 existing errors: memory/adapters/embedders.py:389 and integrations/langchain/chat_model.py:380 ``` The test-related checkboxes refer to retained regression coverage, not new runtime functionality or a claim that the global baseline is green. ## Real Behavior Proof - Environment: macOS arm64, Python 3.14.5, actual temporary settings files and an actual bound TCP listener; no mocked liveness function. - Exact command / steps: ran `uv run --no-sync python` with the following script, then let its temporary directory clean itself up. ```python import json import socket import tempfile from pathlib import Path from headroom.cli import wrap with tempfile.TemporaryDirectory(prefix="headroom-selfheal-runtime-") as home: settings = Path(home) / ".claude" / "settings.local.json" settings.parent.mkdir() settings.write_text(json.dumps({"env": {"KEEP": "preserved"}}), encoding="utf-8", newline="\n") with socket.socket() as listener: listener.bind(("127.0.0.1", 0)) listener.listen() port = listener.getsockname()[1] wrap._write_claude_wrap_base_url(f"http://127.0.0.1:{port}", settings_path=settings) wrap._write_wrap_marker(settings, port=port, key="ANTHROPIC_BASE_URL", previous="https://previous.example") before = settings.read_bytes() wrap._check_and_clear_dead_wrap_marker(settings, key="ANTHROPIC_BASE_URL") assert settings.read_bytes() == before wrap._check_and_clear_dead_wrap_marker(settings, key="ANTHROPIC_BASE_URL") payload = json.loads(settings.read_text()) assert payload["env"] == {"KEEP": "preserved", "ANTHROPIC_BASE_URL": "https://previous.example"} assert not wrap._wrap_marker_path(settings).exists() repaired = settings.read_bytes() wrap._check_and_clear_dead_wrap_marker(settings, key="ANTHROPIC_BASE_URL") assert settings.read_bytes() == repaired ``` - Observed result: live-listener settings and ownership marker were preserved. After closing that listener, the previous URL was restored, the unrelated value survived, and the marker disappeared. Repeating repair was a byte-identical no-op. - Not tested: a real Claude session, paid inference, Windows runtime execution, or a fresh complete repository suite. This demonstrates current upstream runtime behavior with the retained coverage, not a new runtime fix in this PR. ## Runtime Rollout Safety - Rollout-managed feature(s): none; tests only. - Minimum rollout channel: not applicable. - Stable/default behavior changed: no. - Kill switch / disable path: no runtime feature is introduced. - Unsafe override required: no. - Qualification impact: retained regressions and actual filesystem/liveness behavior were checked. - Rollback path: revert the test-only delta; runtime remains unchanged. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] 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; filesystem/runtime evidence is recorded above. ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. --> The supersession feedback is correct. There is no request to replace the stronger implementation already in `main`, and no new test-only PR was opened to chase a known main failure. The unchecked documentation item is not applicable to retaining these two tests. Maintainers can decide whether this remaining coverage is useful or redundant. |
||
|
|
222f2d1df3 |
fix(doctor): detect root openai_base_url Codex routing and agent-configured proxy ports (#4490)
## Description `headroom doctor` gives two false negatives on machines where the proxy is healthy (reported by a Headroom Desktop user on Windows 11; reproduced on macOS): 1. **Codex "not routed" when Codex routes through a root `openai_base_url`.** `check_codex_routing` only reads `[model_providers.<active>].base_url`. Codex also routes its built-in `openai` provider (the default when `model_provider` is unset) through a root `openai_base_url`. Headroom Desktop writes that layout, because the ChatGPT desktop app hides Dots, dictation and voice for any other `model_provider` (`openai/codex#55783`). Doctor now reads the root key for the `openai` provider and for configs with no `model_provider`, where it wins over a leftover `[model_providers.headroom]` table. Both keys only count at the TOML root (before the first table header): a `model_provider` under `[profiles.*]` applies only when that profile is selected, so it no longer hides the default session's route. 2. **A bare `headroom doctor` can't find a proxy on a port only the agents know about.** Without `--port`, discovery probes 8787, `HEADROOM_PORT`, deployment manifests and the wrap marker. Headroom Desktop (port 6767) and `wrap --port N` leave none of these, so the proxy row read "not reachable at 8787" with no hint. Discovery now also probes the loopback ports in Claude Code's `ANTHROPIC_BASE_URL` and Codex's active base URL, read from the same project and user configs as the routing rows (`.claude/settings.local.json`, `.claude/settings.json`, `.codex/config.toml`, then the user files), through the existing `extra=` hook of `find_live_proxy_elsewhere`. It still never adopts a port silently: the proxy row names the live port, as it already does for manifest ports. `codex_active_base_url` is shared with `init`'s port-alignment warning, which now sees the same routing. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/cli/doctor.py`: `codex_active_base_url` reads `model_provider` and `openai_base_url` from the TOML root only; with no root `model_provider` (or `"openai"`), a root `openai_base_url` wins, else the active provider table, else the legacy `[model_providers.headroom]` table. - `headroom/cli/doctor.py`: new `_configured_client_ports(claude_paths, codex_paths)` feeds the project and user Claude/Codex loopback ports to `find_live_proxy_elsewhere(extra=...)`. - `tests/test_cli_doctor.py`: root `openai_base_url` passes (with and without `model_provider`), beats an inactive `[model_providers.headroom]` table, is not hidden by a `[profiles.work] model_provider`; an `openai_base_url` inside a table is not root; a bare `doctor` names a live proxy on the port a user config, a project `.codex/config.toml` or a project `.claude/settings.local.json` routes to. - `tests/test_cli/test_port_alignment.py`: `init`'s alignment warning reads the root `openai_base_url` over an inactive `[model_providers.headroom]` table. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py -q 167 passed in 0.99s $ uv run --frozen --extra dev pytest tests/test_cli_doctor.py tests/test_cli/test_init_cli.py tests/test_cli/test_port_alignment.py tests/test_cli/test_wrap_stale_marker.py tests/test_corporate_tls.py tests/test_install/test_codex_install.py tests/test_offline_egress_chokepoint.py -q 477 passed, 2 skipped in 81.50s $ uvx ruff@0.17.0 check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py All checks passed! $ uvx ruff@0.17.0 format --check headroom/cli/doctor.py tests/test_cli_doctor.py tests/test_cli/test_port_alignment.py 3 files already formatted $ uv run --frozen --extra dev mypy headroom/cli/doctor.py Success: no issues found in 1 source file ``` ## Real Behavior Proof - Environment: macOS, Headroom Desktop proxy (wheel 0.41.0) live on 127.0.0.1:6767, `~/.codex/config.toml` with root `model_provider = "openai"` + `openai_base_url = "http://127.0.0.1:6767/v1"`, Claude `ANTHROPIC_BASE_URL=http://127.0.0.1:6767` in `~/.claude/settings.json`. - Exact command / steps: `headroom doctor --json` and `headroom doctor --port 6767 --json`, once with the installed 0.41.0 wheel and once from this branch (`uv run --frozen headroom doctor`). - Observed result: The branch reports Codex as routed and names the live 6767 proxy, where 0.41.0 reported Codex as not routed and gave no hint. ```text 0.41.0, no --port: proxy fail not reachable at http://127.0.0.1:8787 codex warn not routed (no active provider base_url in config.toml) 0.41.0, --port 6767: codex warn not routed (no active provider base_url in config.toml) branch, no --port: proxy fail not reachable at http://127.0.0.1:8787; a Headroom proxy IS running on port 6767 codex warn routed to port 6767, but doctor probed port 8787 (~/.codex/config.toml) branch, --port 6767: proxy pass running at http://127.0.0.1:6767 claude pass routed via ~/.claude/settings.json codex pass routed via ~/.codex/config.toml ``` Review follow-up ( |
||
|
|
4a851ed254 |
fix(codex): accept multi-line inline tables in Codex config.toml (#4436)
## Description
Codex accepts an inline table split across lines, with a trailing comma,
in `~/.codex/config.toml`:
```toml
env = {
DINGTALK_Client_ID = "**********",
}
```
That is TOML 1.1 syntax. Headroom reads the Codex config with the
standard library `tomllib`, which only implements TOML 1.0 before Python
3.15, so it rejects the file with `Invalid initial character for a key
part`. The result is what the issue shows: `headroom wrap codex` and
`headroom mcp install` refuse to register MCP servers ("is not valid
TOML ... refusing to overwrite") and session routing fails with "could
not read Codex config for session routing", even though Codex itself is
happy with the file.
`tomlkit` is already a runtime dependency (used for Codex config
recovery) and parses this syntax from 0.15.0. 0.13.3 and 0.14.0 both
fail on it (`Empty key at line 1 col 7`).
The fix adds one helper, `loads_codex_config()`, that parses with
`tomllib` first and only on `TOMLDecodeError` retries with `tomlkit`. If
`tomlkit` rejects the text too, it re-raises the original
`tomllib.TOMLDecodeError`, so every caller keeps its existing `except
tomllib.TOMLDecodeError` handling and its error messages unchanged. All
places that parse the user's Codex config now go through it.
The follow-up commit (`dc193870`) fixes a problem the first commit
exposed: once a multi-line inline table parses, a `profiles = {` table
can carry per-profile `model_provider` / `openai_base_url` keys on their
own indented lines, and the line-based "root key" edits in init, the
provider-scope install and persistent wrap mistook those nested lines
for root assignments. Init and install deleted the profile's provider,
and wrap rewrote it to `headroom` and then skipped adding a real root
`model_provider`. Those edits now only touch lines that are actual root
assignments.
Fixes #4378
## 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/providers/codex/config_toml.py` (new):
`loads_codex_config(content)`, `tomllib` first, `tomlkit` fallback,
original `tomllib` error if both fail.
- Routed the Codex config parse sites through it (15 call sites, 16
parse calls):
- `headroom/cli/wrap.py`: session routing read, the user-content check
and its fallback in `_inject_codex_provider_config`, and the two "never
write a malformed candidate" checks.
- `headroom/cli/init.py`: provider snapshot check, the candidate check
in `_ensure_codex_provider`, and `_codex_features`.
- `headroom/providers/codex/install.py`: `_codex_credential_store`,
`codex_auth_helper_is_referenced`, and the merged-config check before
writing.
- `headroom/providers/codex/project_context.py`: the `sqlite_home`
lookup.
- `headroom/mcp_registry/codex.py`: `_load_toml`, `_unmergeable_reason`,
and both sides of `_only_server_changed`. This registrar class is shared
with Grok, so a Grok `config.toml` with the same syntax is accepted too.
- Left on `tomllib` on purpose: `_table_path` (parses a single `[table]`
header line) and the auth snippet check in `build_codex_auth_config`
(validates text Headroom generates itself).
- `pyproject.toml` / `uv.lock`: raise the `tomlkit` minimum from
`>=0.13.0` to `>=0.15.0`, the first release that parses multi-line
inline tables. The lock already resolved 0.15.0, so `uv lock` only
changed the specifier line.
- Write paths: the user's text is never re-serialized by this change.
The registrar and the wrap/init injectors still append or splice marker
blocks as text, and the existing `tomlkit` round-trip in wrap keeps the
multi-line table byte for byte (checked below).
- Tests:
- `tests/test_provider_codex_config_toml.py`: the helper on the exact
shape from the issue (multi-line, trailing comma, whitespace-only line,
indented `}`), and that invalid TOML still raises
`tomllib.TOMLDecodeError`.
-
`tests/test_mcp_registry/test_codex_registrar.py::test_register_accepts_multiline_inline_table`:
registering into that config succeeds and the user's text is kept as a
byte-for-byte prefix.
-
`tests/test_cli/test_wrap_codex.py::test_codex_session_launch_settings_accept_multiline_inline_table`:
session routing reads that config and leaves the file untouched.
- Follow-up commit `dc193870` (multi-line inline profile overrides):
- `headroom/providers/codex/config_toml.py`:
`root_assignment_lines(content)` returns the indexes of lines that start
a key/value pair at the document root. It stops at the first table
header and skips lines inside a multi-line inline table, array or
string, with a small scanner that tracks quotes, comments and bracket
depth.
- `headroom/cli/init.py` (`_ensure_codex_provider`) and
`headroom/providers/codex/install.py`
(`_strip_root_provider_assignments`) only drop `model_provider` /
`openai_base_url` lines that are root assignments.
- `headroom/cli/wrap.py`: `_redirect_existing_top_level_keys` and
`_has_redirectable_top_level_key` only look at root assignments. Before,
they matched the key on any line, so a `[profiles.work]` section
override was also rewritten to `headroom` and counted as a root key;
that now stays the user's, matching how init, install and
`_strip_codex_headroom_blocks` already treat `[profiles.*]`.
- Tests:
`test_root_assignment_lines_skip_keys_nested_in_multiline_inline_table`,
`test_ensure_codex_provider_preserves_multiline_inline_profile_overrides`
(init),
`test_provider_scope_preserves_multiline_inline_profile_overrides`
(install) and `test_inject_preserves_multiline_inline_profile_overrides`
(wrap).
## Testing
- [x] Unit tests pass (`pytest`) - Codex, MCP registry, init and Grok
suites: 774 passed, 2 failed (the 2 failures are in
`tests/test_codex_responses_passthrough_bytes.py` and fail the same way
on `main` without this change)
- [x] Linting passes (`ruff check .`) - `ruff check` and `ruff format
--check` on the 9 changed Python files
- [x] Type checking passes (`mypy headroom`) - `mypy` on the 6 changed
source files, no issues
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
New end-to-end tests on `main` (fix stashed):
```text
$ pytest tests/test_mcp_registry/test_codex_registrar.py::test_register_accepts_multiline_inline_table tests/test_cli/test_wrap_codex.py::test_codex_session_launch_settings_accept_multiline_inline_table -q
E AssertionError: .../.codex/config.toml is not valid TOML (Invalid initial character for a key part (at line 3, column 8)); refusing to overwrite. Fix or remove the file, then re-run.
E click.exceptions.ClickException: could not read Codex config for session routing: Invalid initial character for a key part (at line 5, column 8)
============================== 2 failed in 0.38s ===============================
```
(`tests/test_provider_codex_config_toml.py` cannot import on `main`
because the helper does not exist yet.)
With the fix:
```text
$ pytest tests/test_provider_codex_config_toml.py tests/test_mcp_registry/test_codex_registrar.py::test_register_accepts_multiline_inline_table tests/test_cli/test_wrap_codex.py::test_codex_session_launch_settings_accept_multiline_inline_table -q
============================== 4 passed in 0.56s ===============================
$ pytest tests/test_provider_codex_config_toml.py tests/test_mcp_registry tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py tests/test_install/test_codex_install.py tests/test_provider_codex*.py tests/test_provider_grok*.py tests/test_codex*.py -q
FAILED tests/test_codex_responses_passthrough_bytes.py::test_unmutated_zstd_post_forwards_decoded_bytes_and_strips_content_encoding - concurrent.futures._base.CancelledError
FAILED tests/test_codex_responses_passthrough_bytes.py::test_unmutated_plain_post_passes_original_bytes_through - concurrent.futures._base.CancelledError
================== 2 failed, 774 passed, 8 warnings in 50.43s ==================
$ pytest tests/test_codex_responses_passthrough_bytes.py -q # on main, without this change
========================= 2 failed, 1 warning in 4.09s =========================
$ mypy headroom/cli/init.py headroom/cli/wrap.py headroom/mcp_registry/codex.py headroom/providers/codex/install.py headroom/providers/codex/project_context.py headroom/providers/codex/config_toml.py
Success: no issues found in 6 source files
```
Follow-up commit, the three new write-path tests on the first commit
(`dfe93720`, source changes reverted):
```text
$ pytest tests/test_cli/test_init_cli.py tests/test_install/test_codex_install.py tests/test_cli/test_wrap_codex.py -k multiline_inline_profile -q
FAILED tests/test_cli/test_init_cli.py::test_ensure_codex_provider_preserves_multiline_inline_profile_overrides - AssertionError: assert {} == {'model_provi...y.example/v1'}
FAILED tests/test_install/test_codex_install.py::test_provider_scope_preserves_multiline_inline_profile_overrides - AssertionError: assert {} == {'model_provider': 'company'}
FAILED tests/test_cli/test_wrap_codex.py::TestSubscriptionRouting::test_inject_preserves_multiline_inline_profile_overrides - KeyError: 'model_provider'
====================== 3 failed, 220 deselected in 0.56s =======================
```
With `dc193870`:
```text
$ pytest tests/test_provider_codex_config_toml.py tests/test_cli/test_init_cli.py tests/test_install/test_codex_install.py tests/test_cli/test_wrap_codex.py -k "multiline_inline_profile or root_assignment" -q
======================= 4 passed, 222 deselected in 0.27s =======================
$ pytest tests/test_provider_codex_config_toml.py tests/test_cli/test_init_cli.py tests/test_install/ -q
================== 346 passed, 13 skipped, 1 warning in 3.94s ==================
$ pytest tests/test_cli/test_wrap_codex.py tests/test_cli/test_port_alignment.py -q
============================= 167 passed in 6.01s ==============================
$ pytest tests/test_mcp_registry/ tests/test_provider_codex_install.py tests/test_cli/test_install_cli.py tests/test_cli/test_recover_codex.py -q
============================= 364 passed in 4.71s ==============================
$ pytest tests/test_cli/test_wrap_persistent.py tests/test_codex_project_context.py tests/test_cli/test_wrap_stale_marker.py tests/test_cli/test_wrap_dead_marker_selfheal.py tests/test_provider_codex_runtime.py tests/test_install_tool_env_reconcile.py -q
======================== 4 failed, 261 passed in 9.01s =========================
```
The 4 failures are in `tests/test_cli/test_wrap_persistent.py`
(`AttributeError: '_Manifest' object has no attribute 'runtime_kind'`)
and fail the same way with this PR's changes stashed. `ruff check`,
`ruff format --check` (8 files) and `mypy` on the 4 changed source files
are clean.
tomlkit versions on the issue's snippet:
```text
0.13.3 FAIL Empty key at line 1 col 7
0.14.0 FAIL Empty key at line 1 col 7
0.15.0 {'env': {'A': 'x'}}
```
## Real Behavior Proof
- Environment: macOS 26.2 (Apple Silicon), Python 3.14.7, repo venv with
the `mcp` package installed, a throwaway `HOME`/`CODEX_HOME` whose
`config.toml` holds the issue's config:
```toml
[mcp_servers.dingtalk]
command = "npx"
env = {
DINGTALK_Client_ID = "**********",
}
```
- Exact command / steps: `HOME=<tmp>/home CODEX_HOME=<tmp>/home/.codex
python -m headroom.cli mcp install --agent codex`, then compare the
start of the resulting file with the original bytes and count
`[mcp_servers.headroom]` tables. Also called
`wrap._inject_codex_provider_config(8787)` and
`init._ensure_codex_provider(path, 8787)` on the same config to check
the write paths.
- Observed result: before (`main`):
```text
codex: install failed (failed): <tmp>/home/.codex/config.toml is not
valid TOML (Invalid initial character for a key part (at line 3, column
8)); refusing to overwrite. Fix or remove the file, then re-run.
```
After:
```text
codex: registered (restart the agent if it was already running)
```
The user's original bytes are an exact prefix of the new file and one
`[mcp_servers.headroom]` table was appended. The wrap injector printed
`Codex config: injected Headroom provider (WS + HTTP)`, and in both the
wrap and init outputs the user's multi-line table is still present
verbatim, the file parses, `env` is `{'DINGTALK_Client_ID':
'**********'}` and `model_provider` is `headroom`.
- Follow-up commit: with a throwaway `HOME`/`CODEX_HOME` holding
```toml
model_provider = "openai"
profiles = {
work = {
model_provider = "company",
},
}
```
I ran `init._ensure_codex_provider`, `install.apply_provider_scope`
(provider scope) and `wrap._inject_codex_provider_config` (same config
without the root key) and parsed the result:
```text
== before (
|
||
|
|
9ac1b52c27 |
fix(zcode): skip providers that point at the Headroom proxy itself (#4413)
## Description `detect_upstream` returned the first enabled ZCode provider with a `baseURL`, even when that URL is the Headroom proxy (the URL the setup lines tell the user to configure), so `headroom wrap zcode` started the proxy with itself as upstream. A provider with `"baseURL": null` also raised `AttributeError` instead of falling back. `wrap zcode` now resolves the port the proxy will bind (the requested port, or the next free one when a non-Headroom service holds it) and passes it to `detect_upstream`, which skips URLs whose host is the proxy's advertised host (`127.0.0.1`, or `localhost` treated as the same host) on that port. `[::1]` is not treated as the proxy: it is a different socket, so an IPv6 provider on the same port stays selectable. Non-string `baseURL` values are skipped. Fixes #4409 ## 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 - `detect_upstream(config_path=None, proxy_port=None)`: new optional `proxy_port`; skip providers whose `baseURL` host is `127.0.0.1` or `localhost` on that port (not `[::1]`, review round 2); skip non-string `baseURL`. - `wrap zcode` resolves the port first (`_find_available_port` when the requested port is free or held by a non-Headroom listener; unchanged when a Headroom proxy already runs there or with `--no-proxy`) and passes it as `proxy_port`. Without this, `_ensure_proxy` could move the proxy after the upstream was chosen: a backend on the occupied port was skipped, and a provider on the replacement port (the proxy itself) could be picked. - Seven new tests in `tests/test_cli/test_wrap_zcode.py` (four for `detect_upstream`, three for the port fallback). The new one, `test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4`, drives `detect_upstream` with an enabled provider at `http://[::1]:8787` and `proxy_port=8787` and asserts that provider is selected. ## 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 # new tests, source change reverted FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_skips_provider_pointing_at_proxy FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_only_proxy_provider_falls_back FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[null] FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[int] FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_non_string_baseurl_skips[list] 5 failed, 20 passed # port-fallback tests (second commit), source change reverted FAILED tests/test_cli/test_wrap_zcode.py::test_wrap_zcode_port_fallback_keeps_backend_on_busy_port FAILED tests/test_cli/test_wrap_zcode.py::test_wrap_zcode_port_fallback_skips_provider_on_replacement_port 2 failed, 26 passed # review round 2 ([::1] regression), source change reverted FAILED tests/test_cli/test_wrap_zcode.py::test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4 1 failed, 28 passed # with the fix tests/test_cli/test_wrap_zcode.py: 29 passed tests/test_cli/test_wrap_zcode.py test_wrap_antigravity.py test_wrap_bob.py: 108 passed ruff check: All checks passed! ruff format --check: 2 files already formatted (the two files touched in round 2) ``` ## Real Behavior Proof - Environment: Ubuntu (WSL2), Python 3.12.15, upstream main |
||
|
|
4c7acba593 |
docs: correct Antigravity IDE setup instructions (no third-party model providers) (#4258)
## Description Follow-up to the merged #3817. As flagged in the post-merge thread, the Antigravity IDE doesn’t expose third-party model-provider settings, so the setup text was telling users to add a custom model provider in a panel that doesn’t exist. The instructions now describe what the integration actually covers (MCP registration and the `/v1internal:streamGenerateContent` endpoint for `google-antigravity` clients) and distinguish the IDE from the Antigravity CLI (`agy`), which is the surface that accepts a custom endpoint via `GOOGLE_GEMINI_BASE_URL`. Follow-up fix (Devin review on this PR): the `agy` note mentioned `GOOGLE_GEMINI_BASE_URL` but only printed the OpenAI-compatible URL. It now prints the Gemini-compatible base URL (scheme://host, the Gemini API convention) as an explicit `GOOGLE_GEMINI_BASE_URL=...` assignment, and the OpenAI block is labeled for OpenAI-speaking clients. ## 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 - `headroom wrap antigravity` help text and printed setup instructions no longer reference IDE model-provider settings; they point at MCP registration and the native endpoint, and name the CLI separately. - The `agy` note now shows the Gemini-compatible base URL explicitly (`GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:<port>`), with the project prefix (`/p/<name>`) applied like the other URLs. - `docs/content/docs/proxy.mdx` Antigravity section corrected the same way. - Tests updated to assert the corrected wording. ## Testing - [x] Unit tests pass (`pytest`) ### Test Output ```text $ pytest tests/test_provider_antigravity.py -q 12 passed, 1 warning in 2.07s $ pytest tests/test_mcp_registry/test_antigravity_registrar.py -q 25 passed, 1 warning in 0.82s ``` (`test_cli/test_wrap_antigravity.py` was not run locally — `typer` is not installed in this environment; CI covers it.) ## Real Behavior Proof - Environment: docs/string-only change; no runtime behavior affected. - What was checked: the removed claim ("add a custom OpenAI-compatible model provider in Antigravity’s model-provider settings") was verified false three ways — the reporter’s own `~/.gemini/settings.json` has no model-provider keys; Antigravity IDE 2.5.5 exposes no third-party model-provider settings panel (upstream report plus current docs); and the `google-antigravity` clients the new text names really do speak Cloud Code Assist (`POST /v1internal:streamGenerateContent` is served by the proxy — see `CLOUDCODE_HANDLER_ROUTES` in `route_specs.py`). - Observed result: `render_setup_lines(8787)` now prints the corrected IDE/MCP/native-traffic text, `GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8787` for `agy`, and the OpenAI block labeled for OpenAI-speaking clients; the 37 tests above pass. - Not tested: a live Antigravity IDE run — no Mac with the IDE installed in this environment, and nothing in this change touches a runtime path, so there is no behavior to smoke-test. ## Runtime Rollout Safety - Rollout-managed feature(s): none — documentation/strings only. - Minimum rollout channel: n/a. - Stable/default behavior changed: no; rendered CLI text only. - Kill switch / disable path: n/a. - Unsafe override required: n/a. - 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 - [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 Docs-only PR; the remaining `wrap` CLI test module is covered by CI. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4258" 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-dark.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> |
||
|
|
1dc7a183f5 |
fix(copilot): honour GitHub's advertised Business/Enterprise host by default (#4155)
## Description
Supersedes #3403 (parked, stacked on the conflicting #3402) as a
standalone change on `main`.
GitHub's token exchange advertises a per-plan chat host in
`endpoints.api`: `api.business.githubcopilot.com` for Business seats and
`api.enterprise.githubcopilot.com` for Enterprise seats, and GitHub's
own clients route with it. Since #2441 Headroom has folded both into the
generic `api.githubcopilot.com`, because the segmented hosts lagged on
newer Claude models at the time.
That fold breaks enterprises on GitHub's [subscription-based network
routing](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-access/manage-network-access):
their firewall allows only the plan host, the generic host is
unreachable, and the failure looks like a random connection error. It
also made the VS Code guide's Enterprise section wrong, which said
Headroom uses the advertised URL.
This PR honours the Business and Enterprise advertised hosts by default
and adds `GITHUB_COPILOT_USE_ADVERTISED_HOST=0` (also
`false`/`no`/`off`) to restore the generic-host fold for seats where the
segmented host still lags. An explicit `GITHUB_COPILOT_API_URL` or
enterprise domain still wins over both. The individual host keeps being
folded (#610 is unchanged).
Refs #2441, #610, #3352 (an Enterprise seat behind a corporate firewall;
the inline-completions 401 there is #4144).
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update
## Changes Made
- `headroom/copilot_auth.py`:
`_subscription_api_url_from_user_info_payload` returns the advertised
host for the two plan hosts unless `GITHUB_COPILOT_USE_ADVERTISED_HOST`
opts out, and logs the chosen host with the opt-out next to it. That
line is emitted where the host is resolved: the `wrap` process for the
subscription lanes, which does not write to `proxy.log`. The dedicated
proxy's `/health` (`config.openai_api_url`) is where the chosen host
shows up. The generic and individual hosts still normalize to
`DEFAULT_API_URL`. `resolve_copilot_api_url`'s docstring no longer
claims the advertised host is ignored on purpose. Every subscription
lane (`wrap vscode`, `wrap copilot --subscription`, OpenCode
`--copilot-subscription`) already pins `resolution.api_url` into the
dedicated proxy as `--openai-api-url` and `GITHUB_COPILOT_API_URL`, so
they pick this up without changes; `is_copilot_api_url`,
`copilot_completions_base_url` and `_github_host` already treat
`*.githubcopilot.com` as a public Copilot host (verified by an
independent review of the diff).
- `headroom/cli/wrap.py`: `wrap copilot` help text describes the
per-plan routing for `--subscription`; the implicit OAuth lane still
uses the generic host (it performs no token exchange), which the text
now says.
- Docs: `docs/content/docs/vscode-copilot.mdx` Enterprise section is now
true and names the opt-out and the firewall case;
`docs/content/docs/corporate-networks.mdx` lists the plan hosts;
`TESTING-copilot-subscription.md` host section split by lane:
`--subscription` / `wrap vscode` / OpenCode honour the plan host, the
implicit OAuth `wrap copilot` lane is explicitly generic-host (it
performs no token exchange at launch, and `resolve_copilot_api_url` is
pinned network-free by an existing test), and its "open an issue for
auto-detection" paragraph removed.
- Tests: Business and Enterprise honoured; individual and generic still
folded; opt-out restores the fold; explicit pin wins; `wrap copilot
--subscription` pins the advertised host; the implicit OAuth lane stays
on the generic host even when user-info advertises the Enterprise host;
OpenCode subscription lane expectation updated. Three existing tests
that asserted the fold were updated to the new contract.
Follow-ups, not in this PR: `headroom doctor --network` still probes
only `api.githubcopilot.com` (it should probe the resolved plan host);
the implicit OAuth `wrap copilot` lane could resolve the plan host
through the token exchange too.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed (live Copilot Business seat, 2026-10-13;
see Live verification)
### Test Output
```text
$ pytest tests/test_copilot_auth.py tests/test_cli/test_wrap_copilot.py tests/test_cli/test_wrap_vscode.py \
tests/test_copilot_vscode_completions_routing.py tests/test_provider_copilot_vscode_config.py \
tests/test_cli/test_wrap_opencode.py tests/test_proxy_copilot_auth_hooks.py tests/test_provider_proxy_routes.py \
tests/test_copilot_integration_id_hmac.py tests/test_proxy/test_anthropic_copilot_upstream_auth.py \
tests/test_copilot_native_mode.py tests/test_copilot_subscription_smoke.py tests/test_cli/test_copilot_auth.py \
tests/test_cli/test_wrap_persistent.py
449 passed, 4 deselected
# the 4 deselected tests (test_wrap_persistent.py::*recover*) fail identically on the base commit
|
||
|
|
feea130f81 |
fix(wrap): carry the shared proxy's extensions over to a dedicated Copilot proxy (#4154)
## Description A wrap that cannot reuse the proxy on its port starts a dedicated proxy from the shell environment alone. That happens for every Copilot subscription seed (`headroom wrap vscode`, `wrap copilot --subscription`) and for a persistent deployment with other routing: `_ensure_proxy_unlocked` prints "starting a dedicated local proxy instance" and `_start_proxy` spawns `python -m headroom.cli proxy --port N` with `os.environ.copy()` only. An enterprise install enables its savings sinks on the shared proxy as `--proxy-extension control_plane,observability,...` (`headroom start --daemon`, `headroom-start.sh`). Nothing forwarded that flag, so the dedicated proxy came up with no extensions: the local dashboard filled while the team's dashboard stayed empty, with no error anywhere. This is the shape a customer on VS Code Copilot Enterprise reported this week, and one of the explanations for #3716. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature - [ ] Breaking change - [ ] Documentation update ## Changes Made - `headroom/proxy/server.py`: the loopback `/health` config block now lists `proxy_extensions` (the enabled names only, sorted; no plugin state). - `headroom/cli/wrap.py`: - `_dedicated_proxy_extensions(port, manifest)` reads the extension set of the proxy that owns the requested port: the running proxy's `/health` first, else the `HEADROOM_PROXY_EXTENSIONS` recorded in the persistent manifest's `base_env` (`_manifest_proxy_extensions`; the installer has no extension flag, so that is the only form a manifest records). A running proxy that predates the field falls through to the manifest, and a manifest without the entry is unknown rather than empty (the deployment's runtime env layers on the launch environment). Returns `[]` only for a non-Headroom port holder, a live `/health` reporting an empty list, or an explicitly empty manifest value; `None` otherwise, which triggers the warning. - At the dedicated start, whenever this start leaves a running proxy on the port in place (one `replaces_running_proxy` flag: Copilot seed isolation, persistent routing mismatch, the attached non-persistent routing mismatch, and the unknown-config branch) and `HEADROOM_PROXY_EXTENSIONS` is absent from the environment (an empty value counts as set: it is the way to start a bare dedicated proxy, and click lets the flag outrank the envvar, so wrap must not pass the flag then), the carried set is passed to `_start_proxy(proxy_extensions=...)`, which adds `--proxy-extension <csv>`. The banner prints `Extensions carried over from the proxy on port N: ...`, or one `Warning:` line with the remedy (`HEADROOM_PROXY_EXTENSIONS=<names>`) when the set could not be read. - An explicit `HEADROOM_PROXY_EXTENSIONS` in the environment is inherited by the subprocess and wins; nothing changes when no proxy owns the port. - Tests: `tests/test_cli/test_wrap_persistent.py` (carry-over from `/health`, env wins for both a value and an empty string, warning when unreadable, no warning for a foreign port holder, manifest fallback, older proxy falling through to the manifest, older proxy with a silent manifest warning, explicitly empty manifest value trusted, the attached routing-mismatch branch, plain start unchanged; the two existing isolated-seed tests now stub `_query_proxy_health` so they stay hermetic), `tests/test_cli/test_wrap_helpers.py` (`_start_proxy` emits the flag), `tests/test_proxy_healthchecks.py` (`/health` reports the names). ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for the fix - [x] Manual testing performed (live run below) ### Test Output ```text $ pytest -q tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_helpers.py \ tests/test_proxy_healthchecks.py tests/test_cli/test_wrap_vscode.py \ tests/test_cli/test_wrap_copilot.py tests/test_proxy_extensions.py 4 failed, 193 passed in 7.25s # The 4 failures are on clean main too (same files, patch reverted): # tests/test_cli/test_wrap_persistent.py::test_{ensure_proxy_recovers_matching_persistent_deployment, # ensure_proxy_recovers_persistent_deployment_when_socket_is_bound, # recover_persistent_proxy_reuses_healthy_deployment,recover_persistent_proxy_warns_for_task_deployment} # AttributeError: '_Manifest' object has no attribute 'runtime_kind' (install/runtime.py:241, since #4123) $ uvx ruff@0.16.8 check <touched files> && uvx ruff@0.16.8 format --check <touched files> All checks passed! / 5 files already formatted $ mypy headroom/cli/wrap.py headroom/proxy/server.py --ignore-missing-imports Success: no issues found in 2 source files ``` ## Real Behavior Proof - Environment: macOS, Python 3.12, repo venv with the branch on `PYTHONPATH`, native core present, `HEADROOM_WORKSPACE_DIR` pointed at a scratch directory so the developer's `settings.json` (which already enables `teams`) and client markers stay out of the run. No credentials involved; nothing redacted. - Exact command / steps: ```text # 1. shared proxy with two extensions (the shape `headroom start --daemon` / headroom-start.sh produce) $ python -m headroom.cli proxy --port 18903 --proxy-extension skill_search,lossless_guard --workers 1 Extensions: ENABLED lossless_guard,skill_search (available: foresight,kiro,lossless_guard,output_pro,routemegood,skill_search,teams,tool_search) $ curl -s 127.0.0.1:18903/health # config excerpt { "backend": "anthropic", "openai_api_url": null, "proxy_extensions": ["lossless_guard", "skill_search"], "pid": 81870 } # 2. another wrap client attached to it (marker under <workspace>/clients/18903/<pid>.json) $ python -c "import time; from headroom.cli.wrap import _register_proxy_client; _register_proxy_client(18903); time.sleep(400)" & # 3. a wrap that requests a different backend -> attached routing mismatch -> dedicated proxy $ HEADROOM_BACKEND=openai python -m headroom.cli wrap cursor --port 18903 Proxy on port 18903 has incompatible routing config (backend), but live session(s) are attached. Starting a dedicated proxy on a different port instead of reusing or disrupting it. Port 18903 is in use, using port 18904 instead. Extensions carried over from the proxy on port 18903: lossless_guard,skill_search Starting Headroom proxy on port 18904... Proxy ready — dashboard: http://127.0.0.1:18904/dashboard $ curl -s 127.0.0.1:18904/health # config excerpt { "backend": "openai", "openai_api_url": null, "proxy_extensions": ["lossless_guard", "skill_search"], "pid": 82266 } ``` - Observed result: the dedicated proxy on the next port runs the same two extensions as the shared proxy it was started beside, and the wrap banner says so. The shared proxy was neither restarted nor killed. - Control run worth knowing about: the same flow with the developer's real `settings.json` (which stores `proxy_extensions: "teams"`) showed no "carried over" line and the dedicated proxy ran `teams`: `settings.json` is applied to the environment before the guard, so a persisted `HEADROOM_PROXY_EXTENSIONS` takes the env-wins path by design. - Unit coverage adds the Copilot-seed, persistent-manifest, older-proxy and env-wins cases that the live run did not exercise. - Live Copilot run (2026-10-13, Copilot Business seat, branch merged with #4155 on current `main`): a shared proxy on 8898 with `--proxy-extension e2e_probe` (a probe extension recording which proxy loaded it and every request it saw, standing in for `control_plane`), then `headroom wrap vscode -p 8898`. Banner: `Extensions carried over from the proxy on port 8898: e2e_probe`; dedicated proxy args `--port 8899 --openai-api-url https://api.business.githubcopilot.com --proxy-extension e2e_probe`. The probe saw every request on the dedicated proxy: a 36-request model sweep plus real VS Code chat, Claude, and Agent-mode turns, all 200. Same scenario with `main`'s `wrap.py`: dedicated proxy args have no `--proxy-extension`, `/health` `proxy_extensions: []`. Also checked live: `HEADROOM_PROXY_EXTENSIONS=` → bare proxy; `HEADROOM_PROXY_EXTENSIONS=control_plane` → env wins; shared proxy with no extensions → none, no warning; no shared proxy → wrap owns the port, nothing carried. - Not tested: the portal heartbeat leg (`headroom login` + `control_plane` reporting to the dashboard). The 4 pre-existing `_Manifest` test failures named under Testing are unrelated. ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: stable. - Stable/default behavior changed: a dedicated proxy started beside a shared one now starts with that proxy's extensions instead of none. A user who wanted a bare dedicated proxy sets `HEADROOM_PROXY_EXTENSIONS=` explicitly. - Kill switch / disable path: `HEADROOM_PROXY_EXTENSIONS=` (empty) starts a bare dedicated proxy; revert the commit. - Unsafe override required: no. - Qualification impact: wrap proxy-lifecycle and health suites. - Rollback path: revert. ## 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 added tests that prove my fix is effective - [x] New and existing unit tests pass locally with my changes (except the 4 pre-existing failures named above) - [x] I did **not** edit `CHANGELOG.md` Refs #3716 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
f3d240bcae |
fix(cli): say why the proxy failed to start (#4120)
## Description Fixes two proxy startup failures that hid their cause from the user. **1. `headroom proxy` on a port that is already in use.** It printed the full banner, ending in "Press Ctrl+C to stop.", and then about 10 INFO lines. The one line that mattered, uvicorn's `[Errno 48] ... address already in use`, came next. After it came `event=proxy_shutdown reason=signal` and a 10-line zero-valued session summary. The command now checks the port before printing the banner and exits with one clear line: ``` Error: Port 54351 on 127.0.0.1 is already in use by another process (Address already in use). Start this proxy on another port with --port N (env: HEADROOM_PORT). ``` When a Headroom proxy is the process holding the port, the message says so instead. The check asks the address that is actually busy (IPv6 included), so a Headroom proxy on 127.0.0.1:P is never reported as the owner of [::1]:P. When that address cannot be probed (a scoped IPv6 address, an unresolvable name), the message is the generic `already in use (<reason>)`. **2. `headroom wrap <tool>` when the proxy it starts dies during startup.** The error quoted the last 500 characters of the proxy stdio log. That was the wrong part of the log, for two reasons: - The proxy logs its shutdown summary after the error, so the tail was the summary box. - The log is appended to across runs, so the tail could come from an older run. The error also never said where the log was. It now reads only this run's output, at most its first 64 KiB and, when the head has no error, its last 64 KiB (so a runaway log is never read whole, and an error after a long burst of startup output is still found), quotes from the first `ERROR` / `CRITICAL` / `Traceback` line or line-leading Click `Error: ` (otherwise the end of the first non-blank window, so neither a blank head nor a blank tail hides useful startup text), and adds `Full log: <path>`. The timeout error now names the log too. Refs #4136 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - `headroom/cli/proxy.py`: new `_tcp_port_in_use` / `_refuse_busy_port`. They run after the bind-policy check and before the banner, and are skipped for `--uds`. The probe mirrors uvicorn's own bind, so it never refuses a bind that uvicorn would accept: - It sets `SO_REUSEADDR`, as both uvicorn paths do. A port in TIME_WAIT after a restart is therefore not reported as busy. - With one worker, it binds every address the host resolves to, with `IPV6_V6ONLY`, the same way asyncio `create_server` does. - With `--workers > 1`, it binds one AF_INET or AF_INET6 socket, as uvicorn's `Config.bind_socket` does. - On Windows, and for any error other than EADDRINUSE, it does nothing and leaves the case to uvicorn, exactly as today. - It returns the busy address. `_probe_host_for` maps it to the address to ask: wildcards go to loopback of the same family (`0.0.0.0` to `127.0.0.1`, `::` to `::1`), a hostname is resolved for IPv4, and a scoped IPv6 address returns None (generic message). - `headroom/cli/port_discovery.py`: `probe_headroom_proxy` takes an optional keyword `host` (default `127.0.0.1`, so existing callers are unchanged) and brackets IPv6 in the URL. - `headroom/cli/wrap.py`: - `_start_proxy` records the stdio log size before spawning the proxy. - New `_proxy_startup_failure_excerpt` picks the error line from this run's output, reading at most the first and last 64 KiB written after the recorded offset. - Both startup errors now end with `Full log: <path>`. - `tests/conftest.py` + `pyproject.toml`: an autouse guard, and its `proxy_port_preflight` marker, turn the new check off unless a test opts in. It follows the existing `proxy_dependency_gate` pattern. - Without it, the 16 test files that invoke `headroom proxy` with a stubbed `run_server` on the default port 8787 would fail whenever a developer has their own proxy running. - Tests: - New `tests/test_cli/test_proxy_port_preflight.py`, which uses real sockets: - busy port with workers 1 and 2; - port held by a Headroom proxy; - free port still starts; - `test_ipv6_conflict_is_identified_on_the_requested_host`: a real fake-Headroom `/livez` on 127.0.0.1:P and a plain listener on [::1]:P; `--host ::1` must say "another process"; - `test_unprobeable_host_gets_the_generic_message`. - New `test_startup_excerpt_reads_at_most_64_kib_of_this_run`. - New `test_start_proxy_exit_quotes_this_runs_error_not_summary_or_old_runs`. - The timeout test now also asserts the log path. - The existing stdio-tail test now writes its log output from the fake `Popen`, as the real child process does. - The new tests fail on the old code (3 preflight tests; the excerpt and timeout tests) and pass now. The three tests added for the review (IPv6 owner, unprobeable host, 64 KiB bound) fail on the PR's previous commit |
||
|
|
976aa714ef |
fix(cli): name the broken Codex config, write init configs atomically, keep the identity check (#4129)
## Description
This PR fixes four small CLI problems.
1. **`wrap codex` with a broken `~/.codex/config.toml`.** The warning
looked like this:
```
Warning: could not update Codex config: Invalid value (at line 6, column
10)
```
The line number pointed into Headroom's own merged text, not the user's
file, and the file was never named. The warning now names the file,
gives the parse error in the user's own lines, and says what to do. The
generic Codex and Grok config warnings now also name the file.
2. **`headroom init` truncated config files while rewriting them.** It
rewrote `~/.claude/settings.json`, Codex `hooks.json` and
`~/.codex/config.toml` with `Path.write_text`. That truncates the file
before writing, so a crash or ENOSPC mid-write left a half-written file.
`init` now uses `fsutil.write_text`, the atomic writer `wrap` already
uses for these same files.
3. **The runtime identity check could be silently skipped.** `init` and
`wrap` each had a `_wait_for_runtime_ready` wrapper. It caught
`TypeError` "for test doubles" and then retried `wait_ready` without
`require_identity=True`. So any real `TypeError` inside `wait_ready`
dropped the runtime identity check. Both wrappers are removed, and
callers now pass `require_identity=True` directly.
4. **A failed hook recovery left no trace.** `_ensure_profile_running`
(the init hook's recovery path) ended in `except Exception: return`. It
now catches only what the start paths raise (`click.ClickException`,
`RuntimeError`, `OSError`, `subprocess.SubprocessError`) and logs one
WARNING after the suppressed-output block: `headroom: could not start
persistent proxy '<profile>': <error>. Check it with `headroom install
status --profile <profile>`.` A start that succeeds but never becomes
ready within 45s logs the same line with `it did not become ready within
45s` as the reason. It goes to stderr; stdout stays clean for the hook.
Any other exception is a bug and now surfaces.
Refs #4136
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `headroom/cli/wrap.py` `_inject_codex_provider_config`: it now parses
the user's own content, with Headroom blocks stripped, before building
the candidate.
- If that content does not parse, it warns `could not update Codex
config <path>: it is not valid TOML (<user's own parse error>); Codex
WebSocket traffic will bypass Headroom. Fix or remove the file, then
re-run.`
- If the content parses only once the Headroom block is removed, the old
repair path runs instead.
- The snapshot still happens first, so `unwrap codex` restores the file
exactly as before.
- `headroom/cli/wrap.py`: the generic Codex and Grok config warnings now
include the file path (`grok_config_paths()`).
- `headroom/cli/init.py`: `_write_json`, `_ensure_codex_provider` and
the Codex feature-block writer now call `fsutil.write_text`.
- `headroom/cli/init.py` and `headroom/cli/wrap.py`: removed
`_wait_for_runtime_ready`; callers call `wait_ready(...,
require_identity=True)` directly.
- `headroom/cli/init.py` `_ensure_profile_running`: narrowed `except
Exception: return` to the start-path exceptions and log the failure
once, as above.
- Tests:
- New `test_invalid_user_config_is_named_and_left_untouched` in
`test_wrap_codex.py`.
- New `test_write_json_keeps_the_existing_file_when_the_write_fails` in
`test_init_cli.py`. It simulates ENOSPC at fsync and checks that the
original file survives and no temp file is left.
- New
`test_ensure_profile_running_never_retries_wait_ready_without_identity`:
its `wait_ready` double raises `TypeError` whenever `require_identity`
is passed. It asserts the error propagates and `wait_ready` was called
once, with `require_identity=True`. It fails if the fallback comes back.
- New `test_ensure_profile_running_logs_a_failed_recovery`: no log on a
clean start; exactly the one WARNING above when `start_supervisor`
raises.
- New
`test_ensure_profile_running_logs_a_recovery_that_never_becomes_ready`:
the start succeeds, the 45s `wait_ready` returns False, and the WARNING
names that reason.
- The `wait_ready` doubles in `test_init_cli.py` and
`test_wrap_persistent.py` now accept, or assert, `require_identity`;
`test_recover_persistent_proxy_routes_docker_task_to_docker_supervisor`
asserts `require_identity=True`.
- All four new tests fail on origin/main and pass here.
## 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 -q -p no:cacheprovider tests/test_cli/test_init_cli.py tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_codex.py tests/test_cli/test_wrap_grok.py tests/test_cli/test_init_enable_tool_search.py tests/test_cli/test_install_cli.py tests/test_install/test_providers.py tests/test_install/test_runtime.py tests/test_plugin_manifests.py tests/test_cli/test_wrap_helpers.py tests/test_cli/test_port_alignment.py
4 failed, 595 passed in 29.13s
# The 4 failures are in tests/test_cli/test_wrap_persistent.py ("'_Manifest' object has no attribute 'runtime_kind'"). They are pre-existing: clean origin/main gives "4 failed, 59 passed" for that file.
# The new tests against origin/main code:
test_invalid_user_config_is_named_and_left_untouched: 1 failed (old message names no file)
test_write_json_keeps_the_existing_file_when_the_write_fails: 1 failed (DID NOT RAISE: the old write_text never fsyncs and overwrote the file)
test_ensure_profile_running_never_retries_wait_ready_without_identity: 1 failed (DID NOT RAISE: the fallback retried without require_identity)
test_ensure_profile_running_logs_a_failed_recovery: 1 failed (no log record)
$ uvx ruff@0.16.8 check headroom/cli/init.py headroom/cli/wrap.py tests/test_cli/test_init_cli.py tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_codex.py
All checks passed!
$ mypy headroom/cli/init.py headroom/cli/wrap.py --ignore-missing-imports
Success: no issues found in 2 source files
```
## Real Behavior Proof
- Environment: macOS 25.6, Python 3.12, repo `.venv`.
- Exact command / steps:
1. Ran `python -m headroom.cli wrap codex --prepare-only` with a scratch
`HOME` whose `.codex/config.toml` is `model = [unterminated`. This is
the audit's reproduction, and the new test covers it.
2. Called `_recover_persistent_proxy` and `_restart_persistent_proxy`
directly, with the supervisor and `wait_ready` stubbed, and recorded the
arguments `wait_ready` received.
- Observed result:
1. Before: `Warning: could not update Codex config: Invalid value (at
line 6, column 10)`. After: the warning names
`<HOME>/.codex/config.toml`, reports the error at line 1 (the user's
line), and tells the user to fix or remove the file.
2. Both calls passed `{'timeout_seconds': 45, 'require_identity':
True}`.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):
```text
branch: cleanup/cli-integrations-config-errors-atomic-init @
|
||
|
|
2c2357ad34 |
refactor(cli): one missing-binary error for every wrap command (#4122)
## Description
Ten `headroom wrap <tool>` commands each repeated the same four-line
block for a missing binary: `shutil.which`, `click.echo("Error: '<x>'
not found in PATH.")`, then an install hint, then `SystemExit(1)`. The
messages went to **stdout**, while `wrap openclaw` and `headroom init`
already used `click.ClickException`, which writes to stderr.
This PR replaces the ten copies with one helper, `_require_binary`. It
also folds three identical copies of the hidden legacy code-memory flags
into one decorator.
Refs #4136
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)
## Changes Made
- `headroom/cli/wrap.py`: new `_require_binary(*names,
install_hint=...)`.
- It returns the first name found on PATH, or raises
`click.ClickException("'<x>' not found in PATH.\n<hint>")`.
- It replaces the blocks in `claude`, `copilot`, `codex`, `aider`,
`vibe`, `kimi`, `grok`, `opencode` and `omp`, and in the
registry-generated commands (goose, openhands, openclaude, bob).
- `kimi` keeps its `'kimi' (or 'kimi-cli')` wording.
- The output is the same `Error: ...` text, followed by the hint, with
exit code 1. The one difference is that it now goes to stderr.
- `headroom/cli/wrap.py`: new `_legacy_code_memory_options` decorator.
- It replaces the three identical hidden `--no-tokensave` / `--serena` /
`--no-serena` declarations on `wrap claude`, `wrap codex` and `wrap
grok`.
- It sits next to the existing `_code_memory_option`, the module's idiom
for shared options.
- The option order is preserved.
- `tests/test_cli/test_wrap_helpers.py`: new
`test_missing_binary_error_goes_to_stderr_only`, for `wrap aider`
(hand-written), `wrap goose` (registry) and `wrap kimi` (two names). It
reads stdout and stderr separately: exit 1, empty stdout, the error on
stderr, and no proxy start. It fails on origin/main, where the message
went to stdout.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ pytest -q -p no:cacheprovider tests/test_cli/test_wrap_*.py tests/test_cli/test_tokensave_scope.py tests/test_cli/test_serena_disable.py tests/test_cli/test_serena_migrate.py tests/test_cli/test_serena_reconcile.py tests/test_cli/test_serena_scope.py tests/test_cli/test_unwrap_claude.py tests/test_cli/test_port_alignment.py
4 failed, 837 passed, 1 skipped in 23.28s
# The 4 failures are in tests/test_cli/test_wrap_persistent.py ("'_Manifest' object has no attribute 'runtime_kind'"). They are pre-existing: clean origin/main gives "4 failed, 59 passed" for that file.
# Every wrap/unwrap command's params (name, opts, hidden, help, default), dumped before and after:
267 lines, diff IDENTICAL
$ uvx ruff@0.16.8 check headroom/cli/wrap.py
All checks passed!
$ mypy headroom/cli/wrap.py --ignore-missing-imports
Success: no issues found in 1 source file
```
## Real Behavior Proof
- Environment: macOS 25.6, Python 3.12, repo `.venv`,
`PATH=/usr/bin:/bin`, and a scratch `HOME`.
- Exact command / steps: `python -m headroom.cli wrap claude`, `wrap
kimi` and `wrap goose`, with stdout and stderr captured separately.
- Observed result: each exits rc=1 with empty stdout. Stderr shows, for
example, `Error: 'claude' not found in PATH.` followed by `Install
Claude Code: https://docs.anthropic.com/en/docs/claude-code`. For kimi
it is `Error: 'kimi' (or 'kimi-cli') not found in PATH.` followed by
`Install Kimi CLI: ...`.
- Smoke harness (real proxy started from this checkout against a local
fake upstream; temp HOME and workspace, offline):
```text
branch: cleanup/cli-integrations-wrap-missing-binary @
|
||
|
|
9266b0300d |
test(cli): parametrize the registry-target wrap tests (#4119)
## Description `headroom wrap goose`, `wrap openhands`, `wrap openclaude` and `wrap bob` are all generated from one `WrapTarget` factory (`_make_registry_command`). Despite that, goose, openhands and openclaude each had their own near-identical test file, checking a missing binary, env fan-out and `--prepare-only`. This PR folds those three files into parametrized tests in `test_wrap_registry.py`, keyed on the registry. The missing-binary, `--prepare-only` and launch-env checks now also cover `bob`. Refs #4136 ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [x] Code refactoring (no functional changes) ## Changes Made - Deleted `tests/test_cli/test_wrap_goose.py`, `test_wrap_openhands.py` and `test_wrap_openclaude.py`. - Added three tests to `tests/test_cli/test_wrap_registry.py`: - `test_missing_binary_fails_with_install_hint`, run for every target. It checks exit code 1, the `'<binary>' not found in PATH` text and the target's install hint. - `test_prepare_only_succeeds_unpatched`, run for every target. - `test_launch_routes_tool_env_through_proxy`, run for all four targets: bob, goose, openhands and openclaude. The bob case asserts `BOB_GATEWAY_URL` is the bare proxy origin with the `/p/<project>` prefix. The other cases keep the exact env values the old files asserted (including goose's `ANTHROPIC_HOST`, openhands' `LLM_BASE_URL` and openclaude's `/p/<project>` prefix), plus the tool label, agent type and passthrough args. - `test_wrap_bob.py` is unchanged. It covers Bob's gateway preflight, which only Bob has. - No product code changes. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ pytest -q -p no:cacheprovider tests/test_cli/test_wrap_registry.py tests/test_cli/test_wrap_bob.py 90 passed in 2.70s $ pytest --collect-only -q tests/test_cli/test_wrap_registry.py 16 tests collected $ uvx ruff@0.16.8 check tests/test_cli/test_wrap_registry.py All checks passed! ``` ## Real Behavior Proof - Environment: macOS 25.6, Python 3.12, repo `.venv`, branch cut from origin/main at |
||
|
|
73f59a32cc |
refactor(cli): remove test-only and dead helpers from wrap, proxy and mcp (#4118)
## Description Removes private CLI helpers that no product code calls any more. Each one lost its last caller in an earlier rewrite, so only its own unit tests still called it. The tests that pinned the dead code go with it. Refs #4136 ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [x] Code refactoring (no functional changes) ## Changes Made - `headroom/cli/wrap.py`: removed six dead helpers and constants. - `_wrap_marker_proxy_is_dead`: the self-heal path now calls `_wrap_proxy_alive` inline. - `_agent_savings_config_mismatches` and `_AGENT_SAVINGS_TARGET_AGENTS`: the live restart check only compares `savings_profile`. - The `_normalize_openclaw_gateway_provider_ids` forwarder and its import alias. - A dead copy of `_opencode_home_dir`; the real one lives in `providers/opencode/config.py`. - The unused `_CONTEXT_1M_SUFFIX` and `_OPENCLAUDE_INSTRUCTIONS_FILE` constants. - `headroom/cli/proxy.py`: removed `_get_env_float_optional`, which had no callers. - `headroom/cli/mcp.py`: removed `get_headroom_command`, `load_mcp_config`, `save_mcp_config`, `find_headroom_registration` and the `CLAUDE_CONFIG_DIR` / `MCP_CONFIG_PATH` / `CLAUDE_JSON_PATH` constants. - `mcp install`, `mcp status` and `mcp uninstall` all go through `headroom.mcp_registry` registrars now. - `load_mcp_config` returned `{}` on corrupt JSON, and `save_mcp_config` would then overwrite the file. That data-loss path goes away with them. - Tests removed, because they only exercised the deleted code: - `tests/test_cli/test_mcp_status.py`, all of which tested `find_headroom_registration`; - `TestMCPConfigFunctions` and its path fixtures in `tests/test_cli/test_mcp.py`; - 3 `_wrap_marker_proxy_is_dead` tests; - 5 `_agent_savings_config_mismatches` tests; - 1 forwarder test. - The remaining `mcp uninstall` / `mcp status` tests already patch the registrars. They no longer take the path fixture. Evidence: `rg -n -w '<name>' headroom crates plugins sdk examples benchmarks scripts e2e docs wiki .github pyproject.toml tests <consumer repos>` for each name finds only the definition and the removed tests. Live behaviour stays covered: - `test_wrap_dead_marker_selfheal.py`: `test_dead_port_*`, `test_live_port_is_never_cleared` and the `_wrap_proxy_alive` tests; - `tests/test_provider_openclaw_wrap.py`; - `test_mcp.py::TestMCPStatusCommand` / `TestMCPUninstallCommand`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ pytest -q -p no:cacheprovider tests/test_cli/test_wrap_dead_marker_selfheal.py tests/test_agent_savings.py tests/test_cli/test_wrap_openclaw.py tests/test_cli/test_wrap_opencode.py tests/test_cli/test_mcp.py tests/test_cli/test_wrap_helpers.py tests/test_provider_openclaw_wrap.py tests/test_cli/test_main_help_version.py 253 passed in 33.08s $ uvx ruff@0.16.8 check headroom/cli tests/test_cli tests/test_agent_savings.py All checks passed! $ mypy headroom/cli/wrap.py headroom/cli/mcp.py headroom/cli/proxy.py --ignore-missing-imports Success: no issues found in 3 source files ``` ## Real Behavior Proof - Environment: macOS, Python 3.12, repo `.venv`, branch cut from `origin/main` at |
||
|
|
07b4511537 |
[codex] Make Claude project settings injection opt in (#1600)
## Description Closes #1599 `headroom wrap claude` now applies routing in the child environment by default, leaving project-local settings untouched. `--project-settings` or `HEADROOM_CLAUDE_PROJECT_SETTINGS=1` explicitly enables project-local routing writes. This prevents ordinary wraps from leaving routing state that affects daemon-spawned workers or later direct Claude sessions. Existing opt-in ownership, selected-port routing, Foundry/Vertex behavior, and cleanup are retained. Opted-in cleanup ownership is recorded immediately after the base-URL write. If self-heal hook installation fails afterward, the original base URL and user settings are restored and the session marker cleared. The runtime settings lock file is removed from version control and ignored. ## Validation ### Test Output ```text 132 focused tests passed 63 related lifecycle/Foundry tests passed; 1 SIGHUP-only case excluded on Windows Ruff lint/format and whitespace: pass Linux-target mypy: Success: no issues found in 566 source files REAL CLI opt_in=False: child process used proxy URL; user base URL restored; session marker absent. REAL CLI opt_in=True: child process used proxy URL; user base URL restored; session marker absent. ``` The exception regression performs real settings-file writes. The runtime smoke launches a real local fake-Claude child process; default mode preserves settings byte-for-byte, and opt-in restores the user base URL. Fresh hosted CI and review remain pending at `b6999e0b566093e767474cd44d3143c8da506e91`. ## Runtime Rollout Safety Project writes require explicit opt-in. Default mode scopes routing to the launched child and preserves project state. Opted-in writes retain ownership-aware restoration, including the hook-install failure path, with Vertex and Foundry routing covered by regressions. ### Current validation (2026-10-08, |
||
|
|
1fb4cbaea0 |
fix(proxy): astgrep disk verify truncation (#3192)
## Description `_detect_truncation()` currently relies on client-specific truncation banners in `tool_result` text. This works for clients that emit a recognizable line-count banner, but not for clients such as Cursor (byte-based, direction-reversed truncation) and OpenCode (placeholder + external file pointer). Because `headroom proxy` runs alongside the client it wraps, it can optionally verify the returned content against the actual file on disk. If the `tool_result` is a strict prefix of the file, we can identify truncation without depending on client-specific output formatting. This adds disk verification as an opt-in fallback: the existing banner-based detection always runs first, and disk verification is only attempted when no banner is found. All disk-verification failures or ambiguous cases return `UNKNOWN` rather than guessing. Following review, the verifier is also constrained to a trusted, confined workspace root rather than trusting caller-supplied input directly — see the last four bullets under Changes Made. **Current scope:** the session-token workspace binding this fallback requires is wired for `headroom wrap claude` and plugin-loaded `headroom wrap opencode` only. Cursor remains unsupported/not tested — it has no header-injection surface today to transmit an authoritative session token, so disk verification stays `UNKNOWN` for it; extending Cursor support needs a separate, safe transport design. Related to #2430 Closes #2421 ## 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) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Added optional disk-based Read truncation verification behind `HEADROOM_VERIFY_TRUNCATION_ON_DISK`. - Disk verification compares the visible `tool_result` against the file on disk and distinguishes `COMPLETE`, `TRUNCATED`, and `UNKNOWN`. - Disk verification only runs when the existing `_detect_truncation()` banner check finds no truncation marker, avoiding unnecessary file I/O when the client already provides a signal. - Added a `current_cwd` contextvar populated from `x-headroom-cwd` so relative Read paths can be resolved against the client's working directory. - Registered `HEADROOM_VERIFY_TRUNCATION_ON_DISK` as a hot-reloadable runtime setting. - Gated verification on a new `is_current_request_trusted` contextvar, set from `is_loopback_host(request.client.host)` — a server-observed fact, not the caller-supplied header — so `x-headroom-cwd` is never sufficient authority on its own. - Confined all path resolution strictly under the canonicalized `cwd` (`.resolve()` + `relative_to()`), rejecting `..` traversal, absolute-path escapes, and post-resolution symlink escapes. - Required the resolved target to be a regular file and under a byte cap (new `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` knob, default 5MB), both checked via `fstat` on the open fd before any read. - Opened with `O_NONBLOCK` so a non-regular/special file can't park the read indefinitely; disk I/O already runs off the event loop via the existing compression thread pool. - Added unit and integration tests covering successful verification, missing/unreadable paths, relative paths, content races, feature gating, banner precedence, and the adversarial cases below. ## 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_tool_result_interceptors.py -v 51 passed in 2.21s (includes TestVerifyReadAgainstDisk::* [14 cases, incl. absolute-path escape, `..` traversal, symlink escape, sibling-prefix boundary, non-regular file, oversized file, and untrusted-request-touches-no-disk], plus the end-to-end disk-verification and banner-precedence cases) $ pytest tests/test_proxy_loopback_gating.py -k trusted 16 passed (includes test_record_headroom_stack_binds_trusted_true_for_loopback_client and ..._false_for_non_loopback_client — proves a spoofed x-headroom-cwd from a non-loopback peer does not bind trust) $ ruff check headroom/proxy/interceptors/astgrep.py headroom/proxy/project_context.py \ headroom/proxy/server.py headroom/proxy/runtime_env.py \ tests/test_tool_result_interceptors.py tests/test_proxy_loopback_gating.py All checks passed! $ mypy headroom/proxy/interceptors/astgrep.py headroom/proxy/project_context.py \ headroom/proxy/server.py headroom/proxy/runtime_env.py Success: no issues found in 4 source files ``` ## Real Behavior Proof - Environment: Mac OS local dev machine, no live proxy/network involved. Exercised the real interceptor pipeline (`apply_to_messages`) directly against an actual file on disk, using the same fixture and cwd-binding path a live proxy request would use. - Exact command / steps: wrote a 9-function Python fixture to a temp file, built a client-truncated `tool_result` (first 8 functions, cut mid-file, **no truncation banner text anywhere**), bound `x-headroom-cwd` to the temp directory via `set_current_cwd()`, then called `apply_to_messages()` once with `HEADROOM_VERIFY_TRUNCATION_ON_DISK` unset and once with it set to `1`. - Observed result: With disk verification disabled, the existing ast-grep interceptor produced its normal header without indicating that the input was truncated. With HEADROOM_VERIFY_TRUNCATION_ON_DISK=1, disk verification detected that the 50-line tool_result was a strict prefix of the 59-line file and produced: ```text === HEADROOM_VERIFY_TRUNCATION_ON_DISK unset (default) === [headroom: outlined by ast-grep — 8 definition(s); bodies elided. Re-read the file with a line range to see a specific body.] === HEADROOM_VERIFY_TRUNCATION_ON_DISK=1, x-headroom-cwd bound to the real directory === [headroom: outlined by ast-grep — 8 definition(s) in the visible portion; input was truncated upstream (showing through line 50 of 59 total). Bodies elided. Re-read remaining lines to see more.] ``` **Trust-gate behavior:** same fixture and disk layout, `HEADROOM_VERIFY_TRUNCATION_ON_DISK=1`, but the request context's trust flag left at its default (`False`, simulating a non-loopback caller) instead of being marked trusted. ```text === trusted context (loopback) === [headroom: outlined by ast-grep — 8 definition(s) in the visible portion; input was truncated upstream ...] === untrusted context (non-loopback) — same file, same cwd header, same tool_result === [headroom: outlined by ast-grep — 8 definition(s); bodies elided. Re-read the file with a line range to see a specific body.] (no disk read attempted — verified via a call-recording wrapper around os.open asserting zero invocations) ``` Also verified at the HTTP-middleware level with `TestClient(..., client=("100.90.0.5", 12345))`: a request carrying a spoofed `x-headroom-cwd` header from a non-loopback client IP does not bind trust, regardless of header content. - Not tested: a live `headroom proxy` session with a real coding-agent client; the WebSocket/Codex responses-WS path. ## Runtime Rollout Safety - Rollout-managed feature(s): None. The feature is gated by `HEADROOM_VERIFY_TRUNCATION_ON_DISK` - Minimum rollout channel: N/A. `--intercept-tool-results` must already be enabled for the ast-grep interceptor to run. - Stable/default behavior changed: no - Kill switch / disable path: Unset `HEADROOM_VERIFY_TRUNCATION_ON_DISK`; the setting is hot-reloadable and does not require a restart. - Unsafe override required: no - Qualification impact: none - Rollback path: revert the commit, or unset the env var on a running proxy (takes effect immediately, no restart). ## 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 this branch is based on `fix/astgrep-truncation-marker` #2430 not main <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3192" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
a6523b1967 |
fix(codex): preserve auth.json API keys through Headroom (#3355)
## Description Closes #3354. When Codex uses an OpenAI API key stored in auth.json, Headroom's generated provider block did not configure authentication. Codex therefore sent requests to the local Headroom proxy without an Authorization header and received 401 Missing bearer. This is separate from #3206: that issue covers ChatGPT OAuth authentication, while this change covers file-backed API-key authentication. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature - [ ] Breaking change - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring ## Changes Made - Resolve API-key and OAuth credentials from `codex_home_dir()` for both project and user configurations, honoring `CODEX_HOME`. - Generate a private, config-specific helper beside `auth.json`; API keys stay out of generated TOML and Headroom environment variables. - Configure Codex's supported `auth.command` field for persistent install, init, and wrap. - Serialize command and argument paths with literal Unicode and validate generated TOML before writing provider configurations. - Abort provider updates with an actionable error if a helper collides with another file/symlink or cannot be created. - Use exclusive creation, 0600 permissions on Unix, and content checks for helper ownership. - Give project and user configurations independent helper lifetimes. Retain legacy shared helpers and helpers referenced by restored/remaining providers or unparseable configurations. - Preserve unrelated files and the original provider config when authentication setup fails. - Remove an unused config-specific helper on uninstall/unwrap. ## Testing - [x] Focused unit and integration tests pass - [x] Linting and formatting pass - [ ] Type checking - [x] New regression tests added - [x] Manual runtime testing performed ### Test Output ```text $ .venv/bin/python -m pytest tests/test_provider_codex_install.py tests/test_install/test_codex_install.py tests/test_cli/test_init_cli.py tests/test_install/test_providers.py tests/test_cli/test_wrap_codex.py -q 284 passed $ .venv/bin/ruff check . All checks passed! $ .venv/bin/ruff format --check . 1744 files already formatted ``` Ruff 0.16.8 matches this branch's CI pin. A focused coverage run reports 93% line/branch coverage for `headroom/providers/codex/install.py` and covers 44/45 newly added executable lines across the three production files in this follow-up. This is local focused coverage, not a claim about the hosted Codecov aggregate. Before the follow-up implementation, the added local-init/Unicode/helper-isolation regressions produced 6 failures while 118 existing tests passed. ## Real Behavior Proof - Environment: macOS 26.6.2, Apple Silicon arm64, Python 3.12.11, Headroom source from this PR, Codex CLI 0.160.0, Sub2API OpenAI-compatible provider, model `gpt-6-luna`, existing API key in the user's Codex `auth.json`. - Setup: start an isolated Headroom proxy on an unused loopback port with `ProxyConfig(optimize=False, cache_enabled=False, rate_limit_enabled=False, openai_api_url=<existing upstream>)`. Generate a temporary provider config with `_ensure_codex_provider(config_path, port)` while credentials resolve from the user's Codex home. Add `model = "gpt-6-luna"` and `model_reasoning_effort = "low"` at the document root. Run the child with its own temporary `CODEX_HOME` and no `OPENAI_API_KEY` or `OPENAI_BASE_URL` environment variable; its home contains the generated config, not a copied credential file. - Exact child command: ```sh CODEX_HOME=<temporary-home> codex exec --ephemeral --skip-git-repo-check --sandbox read-only --json -C <temporary-workspace> 'Reply with exactly OK. Do not call tools.' ``` Captured after-fix output on 2026-10-07: ```text Headroom test proxy: ready (optimization disabled) Codex: 0.160.0; model: gpt-6-luna; auth: generated command, no API-key environment variable codex exec exit: 0 agent messages: ['OK'] Responses bearer matches auth.json: True ``` The last line comes from an ASGI wrapper that compares the HTTP/WebSocket Responses request bearer with the file-backed key without logging either value. The command completed against the real upstream; no mocked model response was used. The temporary provider config/helper and test proxy were removed after validation. - Observed limitation: this upstream rejects WebSocket negotiation with HTTP 426, so Headroom's existing HTTP streaming fallback completed the request. This run proves file-backed command authentication and successful proxy routing, not a successful upstream WebSocket session. - Not tested in this follow-up: a new Windows/Linux runtime run, full test suite, native-extension rebuild, or optimization behavior. The focused Python suite reused the existing local native extension; no Rust code changed. ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: N/A. - Stable/default behavior changed: Yes, only when Codex has a file-backed API key and Headroom writes a provider block. - Kill switch / disable path: Remove the Headroom-managed provider block or run the existing Codex unwrap command. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert the generated provider block; auth.json is unchanged. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of the code - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective - [x] New and existing unit tests pass locally with my changes - [x] I did not edit CHANGELOG.md ## Additional Notes Helpers contain no credential value and read the user's existing credential file at runtime, so key rotation does not require reinstalling. Helper names now include a hash of the owning config's canonical path. Legacy fixed-name helpers are retained conservatively because other project configurations may still use them. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3355" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
79f2c2781a |
fix(install): distinguish protocol targets in status (#4040)
## Description Closes #2615. `headroom install status` labelled the default backend as the generic `Backend`, even when an OpenAI target was configured independently. This made a healthy OpenAI-only deployment look like an Anthropic-only deployment. ## Type of Change - [x] Bug fix - [x] Documentation update ## Changes Made - Label the fallback/backend choice as `Default backend`. - Show `Anthropic target` and `OpenAI target` separately as `configured` or `default`, based on the existing live loopback health configuration. - Do not print upstream target URLs or their embedded credentials. - Preserve the existing non-dict health-config guard and all lifecycle/routing behavior. - Document the distinction in the existing persistent-installs page. - Cover configured/default/unknown targets, missing/non-dict/partial/malformed health configuration, manifest fallback, credential withholding, and actual HTTP status probes. ## Testing - Complete install/CLI owner suites: **296 passed, 5 skipped**, one existing Starlette/httpx deprecation warning. - Ruff lint and format checks for both changed Python files: passed. - `mypy headroom/cli/install.py`: passed, one source file checked. - Installed commit hooks: passed (including whole-project mirrored mypy and commit lint). - Required `make ci-precheck`, run by the actual pre-push hook: passed — Rust fmt, strict Clippy, full workspace tests, native extension build/import, **177 Python passed / 4 skipped** (one existing provider-counting warning), and commitlint. - First pre-push attempt hit the unchanged native `first_dispatch_never_blocks_on_model_init` 500 ms bound at 592.8 ms. The isolated test and then the complete unchanged gate passed. No threshold, test, native source, or gate was modified or skipped. - Independent installed-LangChain whole-project typing failure at `chat_model.py:394` is tracked in #4039; this changed CLI file's scoped check passes. No claim that the CLI change fixes that separate error. - Hosted Codecov's automated advisory reports 0% patch coverage for the three display lines. The real CLI before/after runs above exercise them; no wording-only mock test was added to manufacture coverage. At the observed SHA, there is no failing Codecov check; remaining hosted jobs were still in progress. ## Real Behavior Proof Linux x86_64, Python 3.13.14; base `3c418f6f0b190ad1060413c0eadd77f20ab3cf46`. Created a real manifest with the production planner and atomic persistence API, then ran the actual `headroom install agent run` and `headroom install status` CLI. HOME, canonical workspace/config roots, profiles, logs, and ports were isolated under the project verification directory. No system supervisor or provider configuration was installed or modified. Compression/caching were disabled through supported raw proxy flags because this is status-display proof, not compression proof; the anonymous beacon was disabled. Before, live `/health` reports `backend=anthropic`, a configured OpenAI URL, and no configured Anthropic URL; status is running/healthy but ends with `Backend: anthropic` only. After, the same configuration reports: ```text Default backend: anthropic Anthropic target: default OpenAI target: configured ``` A second actual run with both protocol URLs configured reports both targets as configured. The intentionally unreachable Anthropic test endpoint reports `Healthy: no` there; configured is not misrepresented as reachable/healthy. A fake secret embedded in each verification URL does not appear in status output. Agents were explicitly terminated after each observation; no graceful-exit claim. Not tested: paid upstream requests, a running compression workload, macOS, Windows, or a real platform supervisor installation. ## Runtime Rollout Safety No channel, feature flag, routing, auth, or persisted-data format changes. Only operator display changes. Revert this commit to restore the old display; deployment profiles remain valid. ## Review Readiness - [x] Changed consumers and existing health-config contract reviewed - [x] Actual before/after CLI surface verified ## Checklist - [x] Existing documentation updated - [x] No warnings introduced in the changed Python files - [x] No CHANGELOG edit (release-please owns it) AI-assisted: omp / GPT-6.1 Sol, without subagents. No hosted-CI claim. ## Follow-up qualification at |
||
|
|
326079517b |
fix(codex): make unwrap codex remove headroom init routing (#3920)
## Description `headroom init -g codex` writes a block into `~/.codex/config.toml` that points Codex at the local proxy: ```toml # --- Headroom init provider --- model_provider = "headroom" openai_base_url = "http://127.0.0.1:8787/v1" ... # --- end Headroom init provider --- ``` There was no command to take it out again. `headroom unwrap codex` only recognises the markers that `headroom wrap codex` writes, so on an init-written config it prints "Nothing to undo" and then "✓ Codex is no longer routed through the Headroom proxy." The routing is still there. This matters most on Windows. `init` relies on Codex session hooks to start the proxy, and those hooks are disabled upstream on Windows (init already prints a warning about that). So after a reboot or a proxy crash, Codex keeps calling `127.0.0.1:8787`, nothing restarts the proxy, and the obvious undo command claims it worked. That matches the symptom in #3749: Codex stuck on a dead local proxy until the override was deleted by hand. This PR makes `unwrap codex` remove the init block. It also makes the Windows warning say what it means for the user, and documents how to remove init routing. Refs #3749. It doesn't close the issue, which also asks wider questions about the Windows lifecycle; I'll answer those on the issue. ## 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` (`_restore_codex_provider_config`): if the config contains the `# --- Headroom init provider ---` marker, strip it with the existing (already tested) `init._strip_codex_init_block` before the usual wrap cleanup. The existing `cleaned` / `removed` / thread re-tag flow then runs unchanged. `_codex_config_has_headroom_markers` is deliberately not changed, because wrap's pre-wrap backup logic also uses it. - `headroom/cli/wrap.py` (`_restore_codex_provider_config`, backup branch): a pre-wrap snapshot taken *after* `headroom init codex` carries init's block, so restoring it verbatim left Codex pinned to the proxy while unwrap printed "Restored". The snapshot is now passed through `_strip_codex_init_block` too (and the config removed if nothing else is left). The snapshot is read first and deleted only after the config has been written, so a failed write leaves it in place for a retry instead of losing it. Review findings from @JerrettDavis / Devin. - `headroom/cli/init.py` (new `_strip_codex_root_routing_orphans`): the orphan-key safety net (`model_provider = "headroom"`, loopback `openai_base_url`) in both `_strip_codex_init_block` and wrap's `_strip_codex_headroom_blocks` used to match anywhere in the file, so a newly-reachable unwrap would delete user-owned `[profiles.*]` overrides. It now only touches the document root, using the same first-table split `_ensure_codex_provider` already uses. Neither writer ever puts these keys inside a table. Review finding from @JerrettDavis / Devin. - `headroom/cli/init.py` (`_init_codex`): on Windows, after the existing hook warning, add one message. It says nothing starts the proxy there, and points to `headroom install apply` for a supervised proxy and to `headroom unwrap codex` (or deleting the project block) to remove the routing. - `docs/content/docs/proxy.mdx`: the "routing is persistent until you remove it" sentence now says how to remove it, that unwrap leaves init's Codex `SessionStart` hook in `hooks.json` (routing only), plus the Windows caveat. - Tests: five new `unwrap codex` cases: init block plus user content (user content preserved), init-only file (file removed), init → `wrap codex --prepare-only` → unwrap (snapshot restored without init routing), the same sequence with the first unwrap's config write failing (snapshot kept, a second unwrap restores it cleanly), and init → unwrap with a `[profiles.work]` that sets `model_provider = "headroom"` + a loopback `openai_base_url` (profile survives). One assertion added to the existing Windows init warning test. `TestSubscriptionRouting::test_strip_cleans_orphaned_openai_base_url` used a key inside `[profiles.default]` as its "orphan"; it now puts the orphan at the root and asserts a profile-level key survives. ## 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 Both new tests fail on `main`; the failure reproduces the bug: ```text tests/test_cli/test_wrap_codex.py FF E AssertionError: assert 'Nothing to undo' not in '...' E Nothing to undo: ...\.codex\config.toml has no Headroom wrap markers. E ✓ Codex is no longer routed through the Headroom proxy. FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_removes_init_provider_routing FAILED tests/test_cli/test_wrap_codex.py::test_unwrap_codex_removes_init_only_config_file ``` With this branch: ```text $ pytest tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py tests/test_cli/test_wrap_opencode.py -q -n 4 228 passed in 7.50s $ ruff check . All checks passed! $ ruff format --check headroom/cli/wrap.py headroom/cli/init.py tests/test_cli/test_wrap_codex.py tests/test_cli/test_init_cli.py 4 files already formatted $ mypy headroom --ignore-missing-imports --no-site-packages headroom\fileperms.py:71: error: Module has no attribute "fchmod" [attr-defined] Found 1 error in 1 file (checked 554 source files) ``` The mypy error is the Windows-only `os.fchmod` false positive in an untouched file; it passes on Linux CI. The full `tests/test_cli` suite on Windows: 907 passed, 12 failed. Five of those also fail on a clean `upstream/main` worktree with the same environment (`test_recover_codex` ×2, `test_wrap_stale_marker`, `test_unwrap_claude` ×2), so they're pre-existing Windows issues. The other seven (`test_wrap_persistent`, `test_install_apply_announces_windows_service_fallback`) only failed under `-n 6` and pass when run serially on this branch (63 passed). ### Review round (rebased on `upstream/main` |
||
|
|
944eafc6d4 |
fix(wrap): reject saved bob gateway URLs the proxy would not route (#3975)
## Description Follow-up to #3801, promised on its Devin threads ([path shape](https://github.com/headroomlabs-ai/headroom/pull/3801#discussion_r4175286291), [invalid port](https://github.com/headroomlabs-ai/headroom/pull/3801#discussion_r4175286403)). Both findings landed after that PR was approved, so they ship here rather than resetting its review. `bob_preflight` guards against a saved `~/.bob/settings/settings.json` `gatewayUrl`, which bobshell resolves over `BOB_GATEWAY_URL` at startup. It compared only scheme/host/port, so two classes of saved URL got through or crashed it: - A proxy URL with an extra path segment, query or fragment (`http://127.0.0.1:8787/p/work/v1`, `…/p/work?team=a`) passed. Bob then appended `/inference/v1/...` to it; `split_project_path` strips only one `/p/<project>` segment, so the request arrived as `/v1/inference/v1/...` and matched nothing. The wrap launched and Bob failed. - A non-numeric port (`http://127.0.0.1:not-a-port`) made `urlsplit(...).port` raise outside the parse `try`, so the user got a traceback instead of the guidance. Two helpers now answer the two questions separately: `_origin` gives (scheme, host, port) or None for an unparsable value; `_routable_proxy_path` is true only for a bare origin or exactly one `/p/<project>` prefix (reusing `split_project_path`, the router's own grammar), checked on the **decoded** path the ASGI server hands the router (so `%2F` in the project segment counts as the extra segment it becomes, while the `%20` that `with_project_prefix` itself emits is fine) and with no `?`/`#` anywhere, even bare, since Bob appends to the string. The abort message names the real problem: "could not be parsed" / "is not a URL the proxy can route" when it points at the proxy with a bad shape / "would bypass the Headroom proxy" for any foreign host, regardless of its path. A trailing slash remains accepted: bobshell's `AJ()` collapses repeated slashes and strips a trailing one before appending paths (verified in 2.0.5). Closes # (no issue; follow-up to #3801) ## 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/providers/wrap_registry.py`: `_origin_key` → `_origin` + `_routable_proxy_path`; `bob_preflight` passes only when the saved origin equals the proxy's and the path is routable, and picks the message by cause. `split_project_path` is imported from `headroom.proxy.project_context` alongside the existing `with_project_prefix`. - `tests/test_cli/test_wrap_bob.py`: `TestBobPreflight::test_fails_on_non_proxy_shapes` (12 rejected shapes, each asserting its reason: bypass / unroutable / unparsable) and `test_unparsable_env_url_never_matches` (two `None` identities must not compare equal). Passing cases now also cover `/p/my%20proj` and `HTTP://LOCALHOST:8787/`. ## 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 $ PYTHONPATH=$PWD python -m pytest -q -p no:cacheprovider tests/test_cli/ 981 passed, 1 skipped, 17 warnings in 19.79s $ git stash push headroom/ # previous head's wrap_registry, new tests $ pytest tests/test_cli/test_wrap_bob.py -k "non_proxy_shapes or unparsable_env" 5 failed, 3 passed # the two cases already rejected by #3801 plus one message-only case pass; all new shapes fail $ uvx ruff@0.16.8 check headroom/providers/wrap_registry.py tests/test_cli/test_wrap_bob.py All checks passed! $ uvx ruff@0.16.8 format --check ... 2 files already formatted $ uvx mypy==1.20.2 headroom --ignore-missing-imports Success: no issues found in 556 source files ``` ## Real Behavior Proof - Environment: macOS, bobshell 2.0.5, isolated `HOME` whose `.bob/settings/settings.json` holds `{"gatewayUrl":"http://127.0.0.1:8788/p/work/v1"}`; proxy code from each head via `PYTHONPATH`. - Exact command / steps: `HOME=<fakehome> PYTHONPATH=<checkout> python -m headroom.cli wrap bob --port 8788 -- --version`, once on `upstream/main` (`befdb52f`, contains #3801) and once on this branch. - Observed result: main launched Bob; this branch aborted before the spawn. Details: - main: `Launching BOB (API routed through Headroom)... BOB_GATEWAY_URL=http://127.0.0.1:8788/p/scratchpad` then Bob prints `2.0.5` — the guard passed and Bob would have used the saved `/p/work/v1` URL. - this branch: `Error: Bob's saved gatewayUrl (http://127.0.0.1:8788/p/work/v1) is not a URL the proxy can route (use the bare proxy origin, optionally with one /p/<project> prefix). Remove the gatewayUrl entry from <fakehome>/.bob/settings/settings.json ...` — Bob never spawned. - Not tested: a full Bob inference round trip (this change only alters the pre-launch guard; the account's IBM plan is suspended, see #3801). ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: only `headroom wrap bob` on a machine whose saved Bob `gatewayUrl` points at the proxy with an extra path/query/fragment, or is unparsable. Those launches used to proceed (and then fail inside Bob) or crash with a traceback; they now abort with guidance. - Kill switch / disable path: remove `gatewayUrl` from Bob's settings (the message says so); no other wrap target has a preflight. - 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 - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I 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 - Documentation: n/a, the guard's behavior is explained by its own error message. - Self-review found and fixed, beyond the two Devin findings: query/fragment acceptance, scheme-less/host-less URLs comparing equal to an unparsable env URL, and the "bypass" wording being wrong for proxy-pointing URLs. - Deliberately unchanged: `localhost`→`127.0.0.1` normalization does not cover `[::1]`/`0.0.0.0` (pre-existing; `with_project_prefix` only ever emits `127.0.0.1`). 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3975" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
1d4b357ca7 |
feat(opencode): support the OpenCode 2.x plugin API (#3999)
## Description Takeover of #3719 by @laurence-diack-pk, who has been unavailable since Sep 23 and whose branch was left conflicted with `main`. The original commit is preserved and @laurence-diack-pk remains its author; this branch adds follow-up commits addressing @JerrettDavis's review and the findings from live OpenCode 2.x testing. It makes the OpenCode plugin and `headroom wrap opencode` work on both OpenCode 1.x and 2.x. On 2.x the 1.x function plugin was silently dropped (the loader requires a `{ id, setup }` default export loaded from a directory), and Effect's `FetchHttpClient` keeps its own `fetch` reference from before plugins load — so `wrap opencode` loaded no plugin and routed nothing. Closes #3669. Supersedes #3719. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) ## Changes Made Carried from #3719: - One plugin for both versions: default export `{ id: "headroom", server, setup }`; 1.x calls `server`, 2.x calls `setup`. - 2.x `setup`: registers `headroom_retrieve` via `ctx.tool.transform` (`codemode: false`), sets `HEADROOM_*` shell env through the `create.before` hook, and returns a cleanup that releases the refcounted transport so hot reloads do not stack interceptors. - 2.x model routing: `ctx.model.transform` points remote OpenAI-wire models at the proxy with `x-headroom-base-url` / `x-headroom-original-path` headers, since 2.x keeps its own `fetch` reference and the transport patch alone misses model traffic. - Wheel ships the bundle as `_dist/index.js`; `headroom_opencode_plugin_path()` returns the directory; `wrap opencode` adds `--standalone` on 2.x so the private server sees `OPENCODE_CONFIG_CONTENT`. Follow-up commits (review from #3719 + live testing): - Rebased on current `main` (0.40.0). Fixed the routing-contract conflict: replaced `routesThroughProxy` (TS2554 against `shouldRoute`'s 3-arg signature) with `modelBaseRoutesThroughProxy`, a deliberate model-base eligibility check that keeps the shared protocol / loopback / proxy-origin / excluded-host contract but drops the endpoint-suffix requirement, since 2.x hands us model base URLs (e.g. `/v1`), not inference endpoints. - `setup` now resolves the effective `excludeHosts` once (option over `HEADROOM_OPENCODE_EXCLUDE_HOSTS`) and applies it to both the transport install and the model rewrite, with new tests for both paths. - Fixed `test_build_launch_env_with_project` to decode `OPENCODE_CONFIG_CONTENT` instead of substring-matching the raw path, which JSON backslash escaping makes impossible on Windows. - `opencode_major_version` now reads the `v2` channel marker in dev builds (`opencode v0.0.0-v2-<stamp>`), which previously parsed as major 0, so `wrap` skips `--standalone` and the private server never loads Headroom's config. - Rebuilt `_dist/index.js` and `hook-shim/handler.js`; drift check clean. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .` — run on the changed paths) - [x] Type checking passes (`mypy headroom` — run on the changed paths) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text # plugins/opencode $ npm ci && npm run typecheck && npm run build:standalone && npm test tsc: clean (no TS2554) vitest: Test Files 3 passed (3) | Tests 45 passed (45) $ cmp dist-standalone/index.js ../../headroom/providers/opencode/_dist/index.js # identical $ cmp dist-standalone/hook-shim/handler.js ../../headroom/providers/opencode/hook-shim/handler.js # identical # focused Python suites (same set as #3719, plus the 2.x dev-build version case) $ pytest tests/test_providers_opencode_plugin_path.py tests/test_providers_opencode_config.py \ tests/test_providers_opencode_install.py tests/test_cli/test_wrap_opencode.py \ tests/test_mcp_registry_opencode.py tests/test_learn/test_opencode_scanner.py -q 193 passed in 1.10s $ ruff check / ruff format --check on changed paths: clean $ mypy headroom/providers/opencode headroom/cli/wrap.py: Success: no issues found ``` ## Real Behavior Proof - Environment: macOS arm64, Node v26.10.0, Python 3.13, headroom from this branch (0.41.0-dev). Tested against two real OpenCode 2.x clients, each in throwaway XDG dirs with its own proxy port: - `opencode 2.0.19` (official 2.x binary); - OpenCode 2.x head built from `anomalyco/opencode@v2` (`0.0.0-v2-202610061051`, Bun 1.4.2, `bun run script/build.ts --single` in `packages/cli`). - Exact command / steps: throwaway XDG dirs and a dedicated proxy port; fake key first (routing proof), then the real key (end-to-end proof): ```bash # fake key first (routing proof), then the real key (end-to-end proof) OPENCODE_API_KEY=<key> headroom wrap opencode --port 8799 --no-serena -- \ run -m opencode-go/deepseek-v4.1-flash "reply with the single word ok" # exclusion check HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai OPENCODE_API_KEY=<key> headroom wrap opencode ... ``` (`opencode-go` declares `OPENCODE_API_KEY` as its env credential in the catalog, so no interactive login is needed.) - Observed result: routed 401 with the fake key and 200 with the real key through the proxy, `--standalone` added automatically, exclusion honored — details: - **Fake key** — proxy log: `proxy_inbound_request POST /v1/chat/completions` with `user-agent: opencode/latest/2.0.19/cli` (and `opencode/v2/0.0.0-v2-202610061051/cli` for the head), headers `x-headroom-base-url: https://opencode.ai` and `x-headroom-original-path: /zen/go/v1/chat/completions`; forwarded upstream, `401` from the fake key — routed through Headroom. - **Real key** — the model answered `ok`; proxy `status=200` with upstream `https://opencode.ai/inference/go/openai/v1/chat/completions`. - `wrap` added `--standalone` automatically on 2.0.19, and again on the v2 head after the dev-build version fix (explicit `--standalone` also works, per the kill-switch path). - **Exclusion** — with `HEADROOM_OPENCODE_EXCLUDE_HOSTS=opencode.ai` the model still answered while the proxy saw **zero** new chat requests: the 2.x model transform honors the exclusion list. - Not tested: Windows; OpenAI "responses"-wire against a live 2.x server; Anthropic-wire custom providers on 2.x; loading the plugin by npm name (`headroom-opencode`), which needs a published release; OpenCode 1.x older than 1.2.20. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: on OpenCode 2.x, `wrap opencode` launches with `--standalone` (a private server per session); on 1.x behaviour is unchanged apart from the plugin path now being a directory. - Kill switch / disable path: pass `--server <url>` or `--standalone` explicitly; `HEADROOM_OPENCODE_PLUGIN_PATH` still overrides the plugin location. - Unsafe override required: no - Qualification impact: none - Rollback path: revert this PR; the wheel bundle and plugin path revert with it. ## 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 @laurence-diack-pk — thank you for the original implementation; the commit is preserved verbatim at the base of this branch. @JerrettDavis — this addresses the routing-contract conflict you described in #3719 (the missing `excludeHosts` argument and the model-base vs endpoint mismatch), the Windows assertion, and a dev-build version-detection gap found while validating on macOS. Live 2.x validation is done on both 2.0.19 and today's `v2` head; details above. --------- Co-authored-by: laurence <laurence.diack@peekrobotics.co.nz> Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
40955b0eef |
fix(install): preserve OpenCode edits during reactivation (#4022)
## Description Reapply, restart, and automatic recovery temporarily remove the Headroom provider before reactivating it. They must not restore the original backup and erase user configuration added after installation. Final removal must still restore the original snapshot. Closes #4016. ## Type of Change - [x] Bug fix - [x] Documentation update ## Changes Made - Separate transient provider deactivation from final backup restoration, and propagate the intent through the existing install registry/manifest lifecycle. - During reactivation and activation rollback, remove only Headroom's provider; retain unrelated providers, MCP settings, theme, and the original backup. - On true removal, restore and delete the original backup as before. - Associate backups with the actual selected `opencode.json` or `opencode.jsonc` filename, and pin edited writes to LF. - Persist snapshot ownership independently of active mutations, including activation persistence failures and stop/reload/final-remove. - Migrate historical JSONC backup names (including custom config names) before snapshotting/restoration in installer and wrapper callers; do not claim a sibling JSON installation's backup. - Accept JSONC comments/trailing commas without erasing user settings; retain quoted URLs and delimiters. - Restore the snapshot when a successful replacement drops OpenCode, but retain it on replacement failure. - Document preservation during reapply/restart/recovery and original-snapshot behavior on final removal. ## Testing - [x] Unit tests pass (`pytest`), including JSON/JSONC and all three reactivation paths. - [x] Changed-file lint, configured pre-commit mypy and manual real-filesystem checks pass. ### Test Output Real filesystem smoke output for both config suffixes: ```json [{"final_removal_deletes_backup": true, "final_removal_restores_original": true, "headroom_reactivated": true, "original_backup_unchanged": true, "suffix": ".json", "theme": "edited-after-install", "user_mcp_preserved": true, "user_provider_preserved": true}, {"final_removal_deletes_backup": true, "final_removal_restores_original": true, "headroom_reactivated": true, "original_backup_unchanged": true, "suffix": ".jsonc", "theme": "edited-after-install", "user_mcp_preserved": true, "user_provider_preserved": true}] ``` The mandatory pre-push `make ci-precheck` passed: workspace Rust fmt/clippy/tests, native extension build/import verification, the complete configured Python gate, and Commitlint. The native gate explicitly used the installed CPU `libonnxruntime.so.1.26.0` via `ORT_DYLIB_PATH`, with cached-model assertions enabled. ```text [build_rust_extension] headroom._core build + install + verify: OK ================== 177 passed, 4 skipped, 1 warning in 6.31s =================== ✅ ci-precheck PASSED — safe to push. ``` ```sh python -m pytest -q tests/test_providers_opencode_install.py tests/test_cli/test_install_cli.py tests/test_install/test_providers.py ``` Original lifecycle suite: **121 passed**. After the review corrections, the combined provider/config/wrapper/install-CLI/recovery suite passed **240 tests in 8.32s**: ```sh python -m pytest -q tests/test_providers_opencode_install.py tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py tests/test_cli/test_install_cli.py tests/test_install/test_providers.py tests/test_install_tool_env_reconcile.py ``` The regression suite checks real original bytes and persisted recovery ownership, not mocked call order or incidental error wording. The obsolete JSONC-trailing-comma rejection expectation was removed. Changed-file Ruff, formatting, installed pre-commit `mypy headroom`, and Commitlint hooks passed. Full-tree Ruff remains blocked locally by executable permissions on five unchanged OAuth2 plugin files (tracked 100644). A separate full dev-environment mypy run found an unchanged optional LangChain `truthy-function` error; the configured isolated pre-commit hook passed. Unrelated code/permissions were not modified. ## Real Behavior Proof - Environment: Linux x86_64, CPython 3.13.14; unchanged `dea9092e19385f286b7f67a64f4d85de2708d756` and this branch, real temporary config files and real installer mutation helpers, no mocked file mutation or service installed on the workstation. - Exact command / steps: for each suffix `.json` and `.jsonc`, write an original theme/provider/MCP config; activate a provider-scoped OpenCode manifest with `_activate_deployment_mutations`; edit the theme and add a user provider plus remote MCP; call `_deactivate_deployment_mutations` then `_activate_deployment_mutations`; inspect real files and the original backup; finally invoke `revert_mutations(..., restore_backup=True)`. - Before: theme reset to `original`; added provider and MCP disappeared. JSONC's actual-name backup was absent. - Observed result: after the fix, theme remains `edited-after-install`; both user additions survive; Headroom is active again; both actual-name backups remain byte-identical to the original. Final removal restores the original bytes and deletes the backup for both suffixes. - Review correction proof against published head `4bc8e50c`: actual temporary files and persisted manifests cover stop/reload/final-remove for JSON and JSONC, legacy backup migration for default and custom filenames, JSONC trailing commas and quoted `//`/`,}` text, successful target removal, and activation-persistence failure followed by reload/removal. All eight scenario outcomes pass after the correction; the published baseline leaves or consumes the wrong snapshots and loses JSONC edits. The actual `headroom unwrap opencode --no-stop-proxy` command also restores the historical JSONC snapshot byte-for-byte and consumes its backup. Only external process/service management and the explicit persistence-fault boundary are substituted; config, manifest and snapshot IO are real. - Second review correction against `1c0855c4`: all four new findings reproduced on real temporary config/backup files and persisted manifests. After the fix, failed addition consumes its newly created snapshot (a later install restores the later user edit); changed config selection restores the recorded original path; an existing canonical JSONC snapshot wins without deleting the ambiguous legacy backup; and restoration failure retains ownership in the active replacement so a retry after reload finishes restoration. Seven permanent boundary cases initially gave **6 failures and 1 passing control**; the complete affected suite now gives **247 passed**. OS supervisor calls and explicit persistence/restoration faults are the only substituted boundaries. - Not tested: a real launchd/systemd supervisor or Windows process on this Linux host. CLI regression tests exercise apply/restart/recovery boundaries while replacing service management; the filesystem mutation smoke uses real production helpers. ## Runtime Rollout Safety - Rollout-managed feature(s): none; lifecycle data-preservation fix. - Minimum rollout channel: stable; no rollout-managed feature is enabled. - Stable/default behavior changed: transient reactivation stops reverting unrelated user edits. Final uninstall still restores the original snapshot. - Kill switch / disable path: remove the persistent OpenCode installation using its existing removal flow; no new flag. - Unsafe override required: no. - Qualification impact: provider-scoped OpenCode configuration only; other providers retain their existing removal semantics. - Rollback path: revert the commits; no deployment manifest schema change. Backup ownership uses the existing artifact record, and legacy JSONC snapshots migrate to the selected config's canonical filename. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] Existing registry/lifecycle interfaces reused; persistent-install docs updated. - [x] Consumer-visible regressions cover edits, original-backup invariants, both config suffixes, three reactivation paths, and final removal. - [x] `CHANGELOG.md` not edited; Conventional Commit title supplied. Remote CI results are reported by GitHub, not assumed from local tests. --------- Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
278bbc8771 |
fix(wrap): warn when reused proxy ignores compression settings (#4019)
## Description A healthy shared proxy is intentionally not restarted: doing so would interrupt other clients. Explicit startup compression settings must not be silently ignored when a wrapper reuses it. This implements the issue's warning-on-reuse alternative. Closes #3588. ## Type of Change - [x] Bug fix - [x] Documentation update ## Changes Made - Expose the effective tool exclusions alongside the existing effective minimum-token setting in `/health`. - Warn when explicitly supplied `HEADROOM_MIN_TOKENS` or `HEADROOM_EXCLUDE_TOOLS` differs from the running configuration. - Compare tool names case-insensitively and include built-in exclusions on both sides. Skip comparisons when older health responses lack the setting or the requested integer is invalid. - Preserve the existing mode warning and shared-proxy lifecycle. Document startup-only configuration and the restart/separate-port remedies. - Query the running settings for explicit compression environment variables even with `--no-proxy` and no explicit `HEADROOM_MODE`. ## Testing - [x] Focused unit tests: `python -m pytest -q tests/test_cli/test_wrap_bob.py` — **59 passed**. With current main's dashboard-license tests: **67 passed**. - [x] New consumer-visible warning regressions: **4 failed on unchanged baseline**; the additional no-start/MODE-unset cases produced **2 failures before the final fix**, passing afterwards. - [x] Changed-file Ruff and formatting checks; installed pre-commit hooks, including `mypy headroom` and Commitlint, passed. - [x] Manual testing performed. - [ ] Full-tree `ruff check .`: blocked locally by EXE002 on five unchanged OAuth2 plugin files checked out with executable filesystem permissions (Git tracks them as 100644). No unrelated plugin files or permissions changed. - [ ] Separate full dev-environment `mypy headroom`: found one `truthy-function` error in unchanged `headroom/integrations/langchain/chat_model.py:394`. The file is byte-identical to baseline (SHA256 `701a9fe8457907406a2b2810211c1534bc9dfcacf3d841ec4c27d56897209bc7`); the project's isolated pre-commit mypy environment passed. The mandatory pre-push `make ci-precheck` completed: workspace Rust fmt/clippy/tests, native extension build/import verification, Python gate **177 passed / 4 skipped**, and Commitlint all passed. The native model gate used `ORT_DYLIB_PATH` pointing to the installed CPU `libonnxruntime.so.1.26.0`; the cached Kompress parity suite matched **21 fixtures byte-for-byte**. Implicit runtime selection did not finish and was cancelled, not reported as a pass; explicit CPU runtime qualification completed without skipping the cached-model assertions. ### Test Output ```text [build_rust_extension] headroom._core build + install + verify: OK ================== 177 passed, 4 skipped, 1 warning in 7.29s =================== ✅ ci-precheck PASSED — safe to push. ``` ## Real Behavior Proof - Environment: Linux x86_64, CPython 3.13.14; original baseline `dea9092e19385f286b7f67a64f4d85de2708d756` and final fix rebased onto current main `1ad92f0cbc3dea27676e253588100f64a2af6994`; real CLI proxy and real health endpoint. - Exact command / steps: start the real proxy, then reuse it with `HEADROOM_MODE` unset and conflicting compression settings without starting/restarting it; commands below. ```sh HEADROOM_BEACON=off HEADROOM_MIN_TOKENS=120 HEADROOM_EXCLUDE_TOOLS='' \ headroom proxy --host 127.0.0.1 --port 18795 --stateless --no-optimize \ --no-cache --no-rate-limit --no-subscription-tracking --disable-kompress ``` - With `HEADROOM_MODE` unset, reuse it without starting/restarting a proxy: ```sh HEADROOM_MIN_TOKENS=2000 HEADROOM_EXCLUDE_TOOLS=Bash,Read,Grep,Glob \ python -c 'from headroom.cli.wrap import _ensure_proxy; print("RESULT", _ensure_proxy(18795, True))' ``` - Before the final no-start-path fix: only `RESULT (None, 18795)`; both explicit settings were silent. The original baseline was also silent. - Observed result: both explicit-setting warnings appeared after the fix; the same PID and running configuration remained unchanged. Output: ```text Warning: this session requested HEADROOM_MIN_TOKENS=2000 (running: 120); HEADROOM_EXCLUDE_TOOLS=['bash', 'glob', 'grep', 'read'] (running: []), but those settings are fixed at proxy startup. Restart the proxy, or use --port for a separate one. RESULT (None, 18795) {"proxy_pid_before": 1231619, "proxy_pid_after": 1231619, "min_tokens": 120, "exclude_tools": [], "no_proxy": true, "explicit_mode": null} ``` - Not tested: an external interactive agent session or paid upstream model request. The actual proxy process, health response, and wrapper reuse path were exercised. ## Runtime Rollout Safety - Rollout-managed feature(s): none; diagnostic-only wrapper fix. - Minimum rollout channel: stable; no rollout-managed feature is enabled. - Stable/default behavior changed: a warning only when explicit settings conflict with the running proxy; no configuration mutation or forced restart. - Kill switch / disable path: remove the conflicting explicit environment setting, or revert the commit; no new switch. - Unsafe override required: no. - Qualification impact: wrapper diagnostics only; no model/compression rollout change. - Rollback path: revert this commit; the extra health field is additive. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] Existing conventions reused; documentation updated. - [x] Regression tests cover mismatches, matching settings, built-in exclusions, missing fields, and invalid integers. - [x] `CHANGELOG.md` not edited; Conventional Commit title supplied for release-please. The intentional warning is the requested behavior, not a new unsolicited runtime warning. Full remote CI results will be reported by GitHub, not inferred from local checks. |
||
|
|
cd4367b040 |
feat(antigravity): add native Google Antigravity IDE integration (#3817)
## Description Native Google Antigravity IDE integration for Headroom. Antigravity reads its model endpoints from its own model-provider settings (not env vars), so this follows the existing proxy-only `wrap` pattern: start the Headroom proxy and print the custom OpenAI-compatible provider settings to add in the IDE. A new MCP registrar installs Headroom into Antigravity's global `mcp_config.json`. Closes #727 ## Type of Change - [x] New feature (non-breaking change that adds functionality) ## Changes Made - `headroom wrap antigravity` — starts the proxy and prints the custom OpenAI-compatible model-provider settings for Antigravity (same proxy-only pattern as `wrap cursor`; per-project `/p/<name>` base-URL prefixes for dashboard attribution). - `headroom mcp install --agent antigravity` — new `AntigravityRegistrar` for the global `mcp_config.json` under `~/.gemini/`. Prefers an already-existing config location, refuses to overwrite unparseable JSON, clears Antigravity's per-surface MCP cache dirs on uninstall. - Registers the `antigravity` slice in the persistent install env registry. - Docs: `proxy.mdx` gains an Antigravity IDE section covering `wrap`, `mcp install`, and the existing `/v1internal:streamGenerateContent` Cloud Code compatibility endpoint for native google-antigravity clients. ## 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_antigravity.py \ tests/test_mcp_registry/test_antigravity_registrar.py \ tests/test_provider_antigravity.py 34 passed, 1 warning in 0.75s (the warning is a pre-existing `asyncio_mode` config notice, unrelated) $ ruff check <changed files> All checks passed! $ ruff format --check <changed files> 7 files already formatted ``` ## Real Behavior Proof - Environment: Linux, Python 3.12, branch `fix/727-antigravity-integration` - Exact command / steps: `wrap --help` (lists `antigravity`, exit 0); `wrap antigravity --help` (prints the Antigravity IDE setup instructions for the custom OpenAI-compatible model-provider flow); `wrap antigravity --prepare-only` (exit 0). - Observed result: the new command is wired into the CLI and its help text documents the custom-provider setup flow. - Not tested: end-to-end `mcp install` against a real Antigravity IDE (the MCP SDK extra is not installed in this environment; registrar behavior is covered by its unit tests); live proxy traffic from an actual Antigravity client. ## Runtime Rollout Safety - Rollout-managed feature(s): none (new additive commands only) - Minimum rollout channel: n/a - Stable/default behavior changed: no — existing `wrap` / `mcp install` flows are untouched - Kill switch / disable path: do not run the new commands; `headroom mcp uninstall --agent antigravity` removes the MCP registration - Unsafe override required: no - Qualification impact: none - Rollback path: revert the single 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 ## Additional Notes - `mypy` was not run (not installed in this environment); `ruff check` and `ruff format` are clean on all changed files. - Antigravity reads endpoints from its model-provider settings, not env vars, so `wrap antigravity` prints setup instructions instead of launching the IDE. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3817" 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: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
0d7d61d5cc |
fix(wrap): let wrap opencode target a third-party OpenAI-compatible upstream (#3125)
## Description
`headroom wrap opencode` had no way to say where OpenAI-compatible
traffic should go. `opencode()` forwarded `openai_api_url` to
`_ensure_proxy` only for `--copilot-subscription`; every other run
inherited the proxy default, `https://api.openai.com/v1`. A user
following the README's agent-wrap table with a DeepSeek key therefore
had that key presented to OpenAI, which rejected it with `401 Incorrect
API key provided` and pointed them at a `platform.openai.com` dashboard
for a key they never had. Meanwhile
`docs/content/docs/opencode-deepseek.mdx` said "Do not use `headroom
wrap`", with nothing reconciling the two.
This adds the missing plumbing (`--openai-api-url` /
`OPENAI_TARGET_API_URL`, mirroring `headroom proxy`) and the
documentation the issue asked for.
Closes #3107
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- `headroom/cli/wrap.py`: `wrap opencode` gains `--openai-api-url`, with
`envvar="OPENAI_TARGET_API_URL"`, mirroring `headroom proxy
--openai-api-url`. It is passed to `_ensure_proxy`, which already knows
how to start the proxy with it and how to report a mismatch against an
already-running proxy.
- `headroom/cli/wrap.py`: combining `--openai-api-url` with
`--copilot-subscription` raises a `ClickException` before anything is
mutated — the subscription resolves its own upstream, so a manual
override would silently fight it.
- `headroom/cli/wrap.py`: the `opencode` docstring documents the default
upstream and both invocation forms.
- `headroom/cli/wrap.py`: `--no-proxy` combined with an upstream
override now fails closed (review). New
`_require_no_proxy_openai_upstream(port, url)` requires a healthy
Headroom listener whose `/health` config advertises the same
`openai_api_url` after `_normalize_proxy_api_url`; an absent listener, a
listener with no Headroom config, or a mismatched upstream each raise a
`ClickException` that names the exact `headroom proxy --port N
--openai-api-url URL` command to run. The check is opted into via a new
`require_openai_api_url` keyword on `_ensure_proxy_unlocked`, set only
by `wrap opencode`, so wrappers that pass a built-in upstream (`vibe`,
`kimi`, `grok`, `zcode`) keep their existing warn-and-reuse `--no-proxy`
behaviour. On a match wrap prints `Proxy on port N already targets URL`,
warns about a proxy-mode mismatch like the other reuse paths, and
continues. `wrap opencode` runs this check before it touches OpenCode's
config or registers a client marker, so a refused upstream leaves
nothing behind. `--prepare-only` skips it, since it never uses a proxy.
- `headroom/providers/opencode/config.py`:
`inject_opencode_provider_config(port, keep_user_entries=...)` keeps the
user's own `models` and `options` (an `apiKey`, say) under
`provider.headroom` instead of replacing the entry; Headroom still owns
`npm`, `name` and `baseURL`. `wrap opencode` passes `keep_user_entries`
only when `--openai-api-url` (or `OPENAI_TARGET_API_URL`) is set.
Without it the proxy forwards to OpenAI, so a kept third-party key would
be sent there, and wrap writes Headroom's entry as before. OpenCode only
resolves `headroom/<id>` for listed ids, so without this a DeepSeek user
had no DeepSeek model to select (`ProviderModelNotFoundError`) and no
key to send.
- `docs/content/docs/opencode.mdx`: `--openai-api-url` documented on the
canonical OpenCode page (Options block, prose, env-var table), with a
two-form example — wrap starts the proxy, or `headroom proxy
--openai-api-url …` then `wrap --no-proxy --openai-api-url …` — and a
paragraph stating that `--no-proxy` verifies and refuses rather than
re-points.
- `docs/content/docs/opencode-deepseek.mdx`: new "Common issues" entry
for the `Incorrect API key provided` 401 (it comes from OpenAI, not
DeepSeek) and a "When is `headroom wrap opencode` safe?" section — safe
as-is for the default OpenAI/Anthropic upstreams, needs
`--openai-api-url` for any third-party OpenAI-compatible provider, and
that wrap keeps the step 4 `models` and `apiKey` under
`provider.headroom` (DeepSeek needs both). The "Models appear but
requests fail" entry and the "What's NOT in this guide" bullet are
reworded to match, replacing the blanket "do not use `headroom wrap`".
- `README.md`: footnote on the OpenCode row of the agent compatibility
matrix naming the default upstream and the flag/env var.
- `tests/test_cli/test_wrap_opencode.py`: ten tests — the flag, the env
var, the unset default, the `--copilot-subscription` rejection; for
`--no-proxy`: absent, non-Headroom, matching (trailing slash, proving
normalization), and mismatched listeners; that wrappers without
`require_openai_api_url` keep lenient reuse; and that the CLI forwards
the flag. With the fix reverted, 5 of the 6 new tests fail. Review
follow-ups add: `wrap opencode --help` keeps its examples unwrapped and
`wrap.py` has no raw control bytes; a refused `--no-proxy` upstream
exits before any OpenCode config edit or client marker; the
matching-upstream path still warns about a mode mismatch.
- `tests/test_providers_opencode_config.py`: with `keep_user_entries`
the user's `headroom` models and `apiKey` survive re-injection, other
providers are untouched, and Headroom's `npm`/`baseURL` win; without it
they are dropped.
- `tests/test_cli/test_wrap_opencode.py` (second round): through the CLI
the key is kept with `--openai-api-url` and dropped without it, and
`--prepare-only --no-proxy --openai-api-url` writes config with no proxy
listening.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
Four failures in the wider `tests/test_cli` run are pre-existing and
Windows-only — they reproduce identically with this branch's changes
stashed: symlink/settings-path issues in `test_recover_codex.py` and
`test_unwrap_claude.py`, and `signal.SIGHUP` (absent on Windows) in
`test_wrap_stale_marker.py`. They are deselected below.
`tests/test_cli_proxy_improvements.py` and
`tests/test_memory/test_learn_flag.py` cannot run from this source
checkout because the Rust `headroom._core` extension is not built here
(same result on the clean branch); CI builds the wheel.
### Test Output
```text
$ python -m pytest tests/test_cli/test_wrap_opencode.py -q
50 passed, 1 warning in 1.96s
$ python -m pytest tests/test_cli -q --deselect tests/test_cli/test_recover_codex.py --deselect tests/test_cli/test_unwrap_claude.py --deselect "tests/test_cli/test_wrap_stale_marker.py::test_signal_handler_unwinds_so_the_restore_can_run"
706 passed, 1 skipped, 46 deselected, 1 warning in 60.41s
$ git stash push -- headroom/cli/wrap.py && python -m pytest tests/test_cli/test_wrap_opencode.py -q -k no_proxy
5 failed, 2 passed # the new tests fail without the fix; the 2 passing pin unchanged behaviour
$ python -m ruff check .
All checks passed!
$ python -m ruff format --check .
1577 files already formatted
$ python -m mypy headroom
Success: no issues found in 532 source files
$ python -m coverage run --include=headroom/cli/wrap.py -m pytest tests/test_cli/test_wrap_opencode.py -q
50 passed # 17/17 statements added to wrap.py executed, 0 missing
# Review follow-ups (this branch, with current main merged in)
$ pytest tests/test_cli/test_wrap_opencode.py tests/test_providers_opencode_config.py
102 passed, 1 failed # test_build_launch_env_with_project: a known Windows-only path-escaping failure, also on main
# each new test fails on the code before its fix:
test_inject_provider_config_keeps_the_users_models_and_options -> KeyError: 'apiKey'
test_no_proxy_with_openai_api_url_still_warns_about_a_mode_mismatch -> warning missing from output
test_wrap_opencode_no_proxy_rejects_a_mismatched_upstream_before_editing_config -> "MCP retrieve tool: registered", then _ensure_proxy reached
test_wrap_opencode_keeps_the_users_headroom_key_only_for_an_explicit_upstream[no flag] -> key kept (would go to OpenAI)
test_wrap_opencode_prepare_only_does_not_need_the_no_proxy_listener -> "No Headroom proxy is listening on port 9000"
# help test: dropping either no-rewrap marker, or writing a raw 0x08 byte, fails a test (3/3)
$ ruff check / ruff format --check (0.16.8): clean
$ mypy headroom/cli/wrap.py headroom/providers/opencode/config.py --ignore-missing-imports --follow-imports=silent
Success: no issues found in 2 source files
```
## Real Behavior Proof
- Environment: Windows 11, Python 3.11.9, headroom 0.35.0 (`rust_core:
loaded`), with a stub `opencode` on `PATH` that curls the proxy's
`/health` — so the wrapped agent reports the upstream the proxy actually
resolved.
- Exact command / steps: (1) baseline against released 0.35.0 without
this fix on `sys.path` — `python -m headroom.cli wrap opencode --port
8799 --no-mcp --no-serena --openai-api-url https://api.deepseek.com/v1`;
(2) same command on this branch, port 8801; (3) env-var form on this
branch — `OPENAI_TARGET_API_URL=https://api.deepseek.com/v1 python -m
headroom.cli wrap opencode --port 8802 --no-mcp --no-serena`. For the
`--no-proxy` review: `python -m headroom.cli wrap opencode --port <P>
--no-proxy --no-mcp --no-serena --openai-api-url
https://api.deepseek.com/v1` on this branch against (4) nothing on 8811;
(5) `python -m http.server 8812`; (6) a real released-0.35.0 `headroom
proxy --port 8813` (default upstream, `/health` reports
`"openai_api_url": null`); (7) a real `headroom proxy --port 8814
--openai-api-url https://api.deepseek.com/v1`.
- Observed result: step 1 reproduces the bug exactly — wrap prints
`Extra args: --openai-api-url https://api.deepseek.com/v1` (the flag is
swallowed by `ignore_unknown_options` and handed to the agent) and the
proxy it started reports `"openai_api_url": null`, i.e. it would forward
to `api.openai.com`. Step 2 prints no `Extra args` line and the proxy
reports `"openai_api_url": "https://api.deepseek.com/v1"`. Step 3
reports the same. All three runs cleaned up their proxy on exit — no
listener left on 8799/8801/8802. Steps 4–6 each exit 1 before `opencode`
is launched, with: (4) `No Headroom proxy is listening on port 8811 …
Start it separately with `headroom proxy --port 8811 --openai-api-url
https://api.deepseek.com/v1`, or drop --no-proxy …`; (5) `The listener
on port 8812 did not report a Headroom config, so wrap cannot confirm it
forwards to https://api.deepseek.com/v1 …`; (6) `The Headroom proxy on
port 8813 forwards OpenAI-compatible traffic to
https://api.openai.com/v1, not https://api.deepseek.com/v1. Restart it
with …` — and the 8813 proxy is left running, still reporting `null`.
Step 7 prints `Proxy on port 8814 already targets
https://api.deepseek.com/v1` and launches the stub (exit 0). Both
proxies were stopped afterwards; 8811–8814 verified free.
- Real OpenCode (review follow-up): OpenCode 1.18.34 installed from npm
into a scratch directory with an isolated `HOME`, and a local fake
OpenAI-compatible "DeepSeek" upstream on 8792 that records each
request's model and `Authorization` header. The global `opencode.json`
declares `provider.headroom.models.deepseek-chat` and `options.apiKey:
"{env:DEEPSEEK_API_KEY}"`. Command: `headroom wrap opencode --port 8796
--openai-api-url http://127.0.0.1:8792/v1 --no-mcp --no-serena -- run
"say hi" -m headroom/deepseek-chat`.
- before this commit: `ProviderModelNotFoundError: Model not found:
headroom/deepseek-chat.` Nothing reached the upstream, and the config
after wrap held only `gpt-4o` and `gpt-4.1` under `headroom`, with no
`apiKey`.
- after (re-run on the final head
|
||
|
|
aba75cbf6d |
fix(wrap): trim the wrap claude startup banner (#3900)
## Description Implements the three banner cleanups from #3426. Routing, tool-search and Remote Control behavior are unchanged; this only changes what the banner prints. 1. **`127.0.0.1:<port>` repetition.** The "Proxy ready/already running on …" line and the `Dashboard:` line are now one line that names host:port once: `Proxy ready — dashboard: http://127.0.0.1:8787/dashboard`. This applies to all three `_ensure_proxy` sites. `ANTHROPIC_BASE_URL=…` stays, since it's what the session actually uses. 2. **Remote Control notice.** By default this is now one actionable line. It keeps the #1779 accuracy rule: it states the disable as fact for a detected gated version, and names the `2.1.196+` threshold when the version is unknown. `-v` restores the full explanation and the session-accurate #746/#1158 sibling note. 3. **On-demand tool loading line.** By default this prints `On-demand tool loading: kept on (this session)` or `… off (this session)`. `-v` restores `ENABLE_TOOL_SEARCH=… (…; issue #746)`. The compact "off" wording doesn't say "per your setting", because Foundry turns deferral off by default without any `--tool-search` flag. Closes #3426 ## 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/providers/claude/runtime.py`: new `remote_control_gate_short_message(version=...)`, which follows the same version-accuracy rule as `remote_control_gate_message`. It's exported from `headroom.providers.claude`. - `headroom/cli/wrap.py`: new `_proxy_status_line()` used at the three proxy status sites. `wrap claude` prints the compact RC and tool-search lines unless `-v`/`--verbose` is set, in which case it prints the existing full lines unchanged. - Tests: the existing full-wording assertions in `test_wrap_claude_vertex_proxy_env.py` now run with `-v`. New tests cover the compact default banner, the compact "off" line (including Foundry's default-off), and both short-message version branches in `test_issue_1779_remote_control_gate.py`. `doctor` still uses the full message and is untouched. ## Testing - [x] Unit tests pass (`pytest`), with one unrelated failure noted below - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`): not run successfully. My local mypy stops on an unrelated numpy stub syntax error in this env - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest tests/test_cli tests/test_issue_1779_remote_control_gate.py tests/test_cli_doctor.py -q FAILED tests/test_cli/test_wrap_sighup_proxy_leak.py::test_sighup_on_launch_tool_releases_the_proxy 1 failed, 1067 passed, 1 skipped in 21.45s ``` `test_sighup_on_launch_tool_releases_the_proxy` fails identically on unmodified `main` in my environment (checked with the change stashed), so it's unrelated. ## Real Behavior Proof - Environment: macOS, Python 3.12, Claude Code 2.1.290, branch head `f971660d` - Exact command / steps: live launch against a real proxy (no mocks). The proxy was started by `wrap` on a free port, and `--version` makes the real Claude Code binary exit right after the banner: ```text headroom wrap claude --port 8799 --no-mcp --code-memory none -- --version headroom wrap claude -v --port 8799 --no-mcp --code-memory none -- --version ``` - Observed result: by default the banner shows one Remote Control line and one tool-loading line, and the proxy status and dashboard share one line. `-v` prints the previous full RC and tool-search wording unchanged. Default (fresh proxy start): ```text Starting Headroom proxy on port 8799... Logs: ~/.headroom/logs/proxy-8799.log Proxy ready — dashboard: http://127.0.0.1:8799/dashboard Launching Claude Code (API routed through Headroom)... ANTHROPIC_BASE_URL=http://127.0.0.1:8799 Remote Control (/rc) is disabled while routed through Headroom — run `claude` directly (no wrap) for sessions that need it. Extra args: --version Telemetry: anonymous usage counters — never prompts, code, or file paths. See: headroom telemetry --show | Off: HEADROOM_BEACON=off On-demand tool loading: kept on (this session) 2.1.290 (Claude Code) ``` With `-v` (reusing the running proxy): ```text Proxy already running — dashboard: http://127.0.0.1:8799/dashboard Skipping MCP retrieve tool (--no-mcp) Skipping Serena MCP (--code-memory none) Launching Claude Code (API routed through Headroom)... ANTHROPIC_BASE_URL=http://127.0.0.1:8799 Remote Control: Claude Code 2.1.290 disables the /remote-control (/rc) command while ANTHROPIC_BASE_URL points at a custom endpoint (the wrapped Claude session's ANTHROPIC_BASE_URL). Headroom cannot override this client-side gate — run Claude without Headroom for sessions that need Remote Control. Same base-URL gate also affects on-demand tool loading (#746 — Headroom keeps it on for this session) and the 1M context window (#1158 — restore with `headroom wrap claude --1m`). Extra args: --version Telemetry: anonymous usage counters — never prompts, code, or file paths. See: headroom telemetry --show | Off: HEADROOM_BEACON=off ENABLE_TOOL_SEARCH=true (on-demand tool loading kept on; issue #746) 2.1.290 (Claude Code) ``` - Not tested: a full interactive session. The launch exits at `--version` once the banner prints. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: N/A - Stable/default behavior changed: Only the banner text. No routing or env changes. - Kill switch / disable path: `-v` shows the previous full lines - 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 - [ ] I have made corresponding changes to the documentation: N/A, the docs don't quote these banner lines - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes In the default mode, the `--1m` hint from the sibling note now only appears under `-v`. If maintainers want that hint visible by default, a short `(1M context: --1m)` suffix on the tool-loading line would be a cheap way to keep it. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3900" 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 <mxjerrett@gmail.com> |
||
|
|
c07fad0f37 |
fix(wrap): set ANTHROPIC_HOST so wrap goose actually proxies Anthropic (#2619)
## Description
`headroom wrap goose` never proxied Anthropic traffic. Goose's Anthropic
provider reads `ANTHROPIC_HOST`, not `ANTHROPIC_BASE_URL`, so the
wrapper started the proxy, printed the banner, and then sent every
request straight to `api.anthropic.com` — silently, with no error and
zero compression.
`ANTHROPIC_BASE_URL` appears in no `.rs` file in the goose repo. The
provider reads `ANTHROPIC_HOST` at
[`crates/goose/src/providers/anthropic_def.rs#L38-L40`](https://github.com/block/goose/blob/main/crates/goose/src/providers/anthropic_def.rs#L38-L40)
and appends `/v1/messages` itself, so `_claude_proxy_base_url(port)` is
already the correct value.
Note the README currently advertises `headroom wrap goose -- --provider
anthropic` as an example — that is the exact invocation that bypasses
the proxy. The OpenAI path was unaffected: goose does honour
`OPENAI_BASE_URL`.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- Set `ANTHROPIC_HOST` alongside the existing vars in `wrap goose`
(`headroom/cli/wrap.py`), and show it in the launch banner.
- Extend `test_wrap_goose_sets_provider_envs` to assert the value. This
test **fails before** the change with a `KeyError`.
- Update the command docstring.
## 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
# Test A - the env vars `wrap goose` sets today (ANTHROPIC_HOST explicitly unset)
$ env -u ANTHROPIC_HOST ANTHROPIC_API_KEY=*** \
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 \
OPENAI_API_BASE=http://127.0.0.1:8787/v1 \
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 \
goose run --no-session -t "Reply with exactly: PONG"
● new session · anthropic claude-haiku-4-5
PONG
===== LISTENER HITS =====
(hit count: 0)
# Test B - same, plus ANTHROPIC_HOST (this change)
(hit count: 7)
2026-07-27T12:13:09.381232 HIT POST /v1/messages host=127.0.0.1:8787
2026-07-27T12:13:09.382744 HIT POST /v1/messages host=127.0.0.1:8787
2026-07-27T12:13:10.245477 HIT POST /v1/messages host=127.0.0.1:8787
...
# Test C - OpenAI path, unchanged env (confirms scope is Anthropic-only)
(hit count: 8) POST /v1/chat/completions
```
## Real Behavior Proof
- Environment: macOS 15 arm64, goose v1.44.0 built from source, headroom
main @
|
||
|
|
7b68fc263a |
fix(copilot): warn when a VS Code profile cannot see the proxy settings (#3919)
## Description `headroom wrap vscode` writes Copilot's two endpoint overrides into the Default profile's `settings.json` and reports success. A VS Code window that uses a profile with its own settings reads only `User/profiles/<id>/settings.json`, and Copilot takes these overrides from user settings alone. In that window Copilot keeps talking to GitHub directly: Copilot works, Headroom records nothing, and setup said it succeeded. That is exactly what #3716 describes. The reporter hasn't confirmed yet that they use a profile (I asked on the issue), so this says "Refs" rather than "Closes". After writing a VS Code user directory's `settings.json`, `wrap vscode` now reads the profiles VS Code records in that directory's `globalStorage/storage.json`. That file is either the Default one or one named with `--settings-file`. For each profile that keeps its own settings and doesn't define both overrides as live settings, it prints a warning with the exact `--settings-file` command that routes it. Nothing is written to profile files automatically. The docs already scope profile-specific settings to `--settings-file`, and the block persists and fails closed after the proxy stops. Routing every profile silently would therefore change Copilot in profiles the user never meant to proxy. Refs #3716 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made - `headroom/providers/copilot/vscode.py`: `unrouted_vscode_profiles(user_dir)` returns `(name, settings.json)` for each stored profile that has its own settings (`useDefaultFlags.settings` unset) and doesn't define both endpoint overrides as live settings. - It parses the profile's JSONC with `_parse_settings`, split out of `_validate_settings` so both share one parser. As a result, a marker or keys that exist only in comments don't count. - It accepts only a local folder name as a location (VS Code uses `hash(uuid).toString(16)`, which can be negative). That skips remote URIs and rules out path traversal. - Missing or unexpected VS Code state produces no warning. - `headroom/cli/wrap.py`: after writing the settings file, `wrap vscode` prints one `Warning:` line per such profile of the user directory that holds that file. - A profile's own `settings.json` has no profile state beside it, so running the printed remedy produces no warning. - A `--settings-file` in another user directory (Insiders, VSCodium, portable) gets that directory's profiles checked. - There's no warning with `--no-configure`. - `headroom/providers/copilot/__init__.py`: exports the helper alongside the other VS Code helpers. - `docs/content/docs/vscode-copilot.mdx`: adds a troubleshooting entry for "no requests while Copilot keeps working". - `tests/test_cli/test_wrap_vscode.py`: `test_wrap_vscode_names_profiles_that_ignore_default_settings` walks the whole flow. It warns by default and when the Default file is named explicitly, stays silent for a shared-settings profile, and goes silent once the printed remedy has run. `test_wrap_vscode_checks_the_profiles_of_the_user_dir_it_configures` covers another user directory. - `tests/test_provider_copilot_vscode_config.py` covers: - own versus shared settings - a negative-hash folder - traversal and remote locations - profiles that override both endpoints, whether managed or hand-written - a marker-only file, commented-out keys, a single key, and unparseable settings - a missing or malformed `storage.json` ## 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 # The new tests against the code before each commit. # main ( |
||
|
|
1b7977cecd |
fix: honor configured port in container startup and healthcheck (#2436)
## Description Deploying on a non-default port produced a working proxy that the surrounding tooling reported as broken. Tracing the probe turned up a second defect upstream of it: the container could not change its port via `HEADROOM_PORT` at all. `headroom proxy --port` is a click option with `envvar="HEADROOM_PORT"`, and an explicit CLI argument beats the envvar. The Dockerfile baked `--port 8787` into CMD, so `HEADROOM_PORT` was inert for a plain `docker run` — while `docker-compose.yml` already passes `command: ["--host", "0.0.0.0"]` with no port, which is the intended shape. The Dockerfile was the outlier. The two halves have to move together. An earlier revision of this change fixed only the HEALTHCHECK; that made the probe follow `HEADROOM_PORT` while the listener stayed pinned to 8787, and the container went from misleadingly healthy to genuinely unhealthy. Evidence in Real Behavior Proof below. Closes #2432 ## 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 - `Dockerfile`, both runtime stages: dropped the baked `--port` from CMD so `HEADROOM_PORT` stays authoritative. `docker run` with no env still binds 8787 (click's default), so the published default is unchanged. - `Dockerfile` (`runtime-slim-base`): shell-form HEALTHCHECK so `${HEADROOM_PORT:-8787}` expands at probe time. - `Dockerfile` (`runtime-slim`): distroless, no shell — the port is resolved inside Python instead, keeping exec form. - `headroom/cli/doctor.py`: added `resolve_probe_port()`. `--port` / `HEADROOM_PORT` wins, then an unambiguous deployment manifest (`default` profile, or a lone named profile), then 8787. `headroom deploy --port N` writes N into the deployment's environment, not into the shell `doctor` runs in, which is why the manifest tier is needed; with several named profiles and no explicit request there is no non-arbitrary pick, so it stays on the default and the existing per-deployment section reports each one. `list_manifests()` is now read once and shared with that check. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom --ignore-missing-imports`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output Full suite, run inside this repo's own builder image so the maturin-compiled Rust core is the one under test: ```text 9 failed, 9248 passed, 853 skipped, 2230 warnings in 384.56s (0:06:24) ``` All 9 failures reproduce unchanged on `origin/main` ( |
||
|
|
44db755ee6 |
fix(install): replace the launchd wrapper with the proxy listener (#3224)
## Description The persistent service path can leave a wrapper, listener, native supervisor, or Docker container with conflicting ownership. Rebuild runtime ownership so launchd directly owns Python, Docker owns Docker across service/task presets, status and stop require deployment identity, readiness cannot be health-only, and failed cleanup preserves rollback state. Closes #3208 ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (feature that would cause existing behavior to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Make the launchd-owned Python service exec the listener in place. - Classify Docker ownership from both runtime and preset, with no competing native supervisor. - Route Docker service/task start, restart, recovery, and teardown through the Docker owner. - Verify exact process command, port, deployment profile, and runtime before status or stop. - Add POSIX, macOS, and Windows process identity fallbacks without requiring psutil. - Require identity on readiness and fail closed when cleanup cannot prove the new owner stopped. - Persist an inactive previous-deployment snapshot, keep active state durable before owner start, and make environment/provider mutation activation transactional. - Surface cleanup, persistence, supervisor, Docker, and recovery-snapshot deletion failures with actionable recovery guidance. ## Testing - [x] Unit tests pass (`uv run --locked pytest tests/test_provider_package_init.py::test_install_registry_apply_provider_scope_mutations_skips_missing_and_none tests/test_install/test_providers.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py tests/test_install/test_supervisors.py tests/test_install/test_paths.py tests/test_install/test_state.py -q`) - [x] Linting passes (`uv run --locked ruff check` on changed install, provider, supervisor, and focused test files) - [x] Type checking passes (`uv run --locked mypy headroom --ignore-missing-imports`) - [x] New tests added for the regression - [ ] Manual testing performed through live process/supervisor environments ### Test Output ```text uv run --locked pytest tests/test_provider_package_init.py::test_install_registry_apply_provider_scope_mutations_skips_missing_and_none tests/test_install/test_providers.py tests/test_cli/test_install_cli.py tests/test_install/test_runtime.py tests/test_install/test_supervisors.py tests/test_install/test_paths.py tests/test_install/test_state.py -q ============================= 197 passed in 1.07s ============================= uv run --locked ruff check . All checks passed! uv run --locked ruff format --check . 1534 files already formatted uv run --locked mypy headroom --ignore-missing-imports Success: no issues found in 527 source files git diff --check passed; the only worktree change is the pre-existing unstaged uv.lock line-ending change ``` ## Real Behavior Proof - Environment: Windows focused process and supervisor tests, with platform-specific launchd and Docker owner paths represented by fakes. - Exact command / steps: run the focused lifecycle and state suite listed above, targeted Ruff and format checks, and the full-head mypy check. - Observed result: each persistent mode has one owner; mismatched, malformed, or unavailable identity cannot authorize cleanup; active state is durable before owner start; failed cleanup retains recovery state; mutation rollback preserves unreverted records. - Not tested: owner-level POSIX exec, a live macOS launchd job, and a Docker daemon ## Runtime Rollout Safety - Rollout-managed feature(s): None. This changes the default persistent install and recovery ownership paths. - Minimum rollout channel: Stable, after platform-specific CI and maintainer review. - Stable/default behavior changed: Yes. Persistent Python service ownership and Docker supervisor routing change. - Kill switch / disable path: `headroom uninstall` removes the managed deployment; users can reinstall with another supported preset or runtime. - Unsafe override required: No. - Qualification impact: launchd, Docker, and Windows identity paths require their platform-owned environments; local proof uses focused tests and process/supervisor fakes. - Rollback path: Revert the rollback-ordering commits in this PR, then reinstall the prior deployment if needed. Uncertain cleanup retains the active new manifest and inactive previous snapshot until the new owner is removed and recovery is completed. ## 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] My changes generate no new warnings - [x] I have added tests that prove my fix is effective - [x] New and existing unit tests pass locally with my changes - [x] I have updated the CHANGELOG.md if applicable ## Additional Notes The changelog is generated by the release pipeline. Live launchd and Docker-owner behavior remains platform-owned proof; local tests do not claim those owner environments. Final implementation head: `4004e4a5`. <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3224" 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 <mxjerrett@gmail.com> |
||
|
|
6df4a963ae |
fix(codex): preserve remote compaction in init config (#3410)
## Description Closes #3407. `headroom init codex` writes a custom provider named `Headroom init proxy`. Codex 0.152.1 derives remote-compaction capability from the provider display name, so this configuration routes ordinary Responses traffic through Headroom but silently falls back to local compaction. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (breaking change that changes existing functionality) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Keep the `headroom` provider id and loopback URLs unchanged for routing. - Emit the built-in `OpenAI` provider display name so Codex retains its remote-compaction capability detection. - Add a regression assertion covering the generated Codex configuration. ## Testing - [x] Focused unit tests pass (`tests/test_cli/test_init_cli.py`) - [x] Focused linting passes (`ruff check`) - [x] Focused formatting passes (`ruff format --check`) - [x] New regression coverage added - [ ] Full test suite - [ ] Live Codex 0.152.1 compaction run ### Test Output ```text PYTHONPATH=. python -m pytest tests/test_cli/test_init_cli.py -q 73 passed in 22.15s ruff check headroom/cli/init.py tests/test_cli/test_init_cli.py All checks passed! ruff format --check headroom/cli/init.py tests/test_cli/test_init_cli.py 2 files already formatted ``` The repository's documented `uv run --frozen --extra dev` setup was also attempted, but dependency resolution stopped while building `hnswlib==0.8.0`: its build environment raised `AttributeError: module 'pkgutil' has no attribute 'ImpImporter'`. The focused tests and checks ran successfully with the already-installed Python 3.11 environment. ## Real Behavior Proof - Environment: Windows 10, Python 3.11.9, generated temporary Codex configuration. - Exact command / steps: invoked `_ensure_codex_provider` against a temporary config with port `8787`, parsed the result with Python `tomllib`, and checked the provider id, display name, and loopback base URL. - Observed result: the generated `[model_providers.headroom]` section contains `name = "OpenAI"`, `base_url = "http://127.0.0.1:8787/v1"`, and `supports_websockets = true`; the root `model_provider` remains `headroom`. - Not tested: a live Codex 0.152.1 session against `/v1/responses/compact`, because Codex 0.152.1 is not installed in this environment. ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Stable; this only changes the generated display name for new or regenerated init configurations. - Stable/default behavior changed: Codex-initialized Headroom configurations now advertise the OpenAI-compatible capability name expected by Codex while preserving the existing Headroom routing id and URLs. - Kill switch / disable path: Run `headroom unwrap codex` or revert the generated config. - Unsafe override required: No. - Qualification impact: Existing generated configs need to be regenerated with `headroom init codex` to receive the corrected name. - 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 - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [x] I have added tests that prove my fix is effective - [x] Focused unit tests pass locally - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes The provider remains registered as `headroom`; only its display name changes. This preserves Headroom's proxy URLs, WebSocket setting, and conditional `requires_openai_auth` behavior for both ChatGPT OAuth and API-key users. --------- Co-authored-by: UniversePeak <UniversePeak@users.noreply.github.com> |
||
|
|
0b7dab47c6 |
feat(wrap): add headroom wrap bob for IBM Bob CLI (#3801)
## Description Adds `headroom wrap bob` for the IBM Bob CLI as a wrap-registry target. `BOB_GATEWAY_URL` points Bob at the proxy, and the proxy forwards to `https://api.us-east.bob.ibm.com/inference/v1`. Bob's own `Authorization: apikey …` credential and `~/.bob/settings` are left untouched. **Stacked on #3800.** Until that merges, this diff also contains its commit. The Bob change is the last commit only (`feat(wrap): add headroom wrap bob …`). Bob's gateway needs three proxy seams, each declared on the target: - **`extra_chat_routes`**: Bob posts to `/inference/v1/chat/completions`. Without a real route that matches only the catch-all and is forwarded **uncompressed**. - **`origin_passthrough_prefixes`** (`/inference/`, `/admin/`, `/rag/`, `/metrics-forwarder/`): Bob builds these paths itself against the bare origin (inference and model info, profile and budget, the IBM docs-search tools, telemetry). Joining them onto the `/inference` base produces doubled or misrooted URLs (`…/inference/inference/v1/model/info`, `…/inference/admin/v1/profile`) that IBM's edge rejects with 403. - **`origin_passthrough_strip_json_keys`**: Bob 2.0.1 through 2.0.5 rewrites its gateway host from `region_domain` in the `/admin/v1/profile` response while keeping the proxy's port, so every later request goes to an unreachable `api.<region>:<proxy-port>`. The proxy removes that key. Bob bills flat per token, so the target defaults `HEADROOM_MODE` to `token`; an explicit `HEADROOM_MODE` still wins. `/health` now reports the proxy's `mode`, and `headroom wrap` warns when it reuses a proxy running a different mode than the session asked for. The warning applies to every harness. Replaces the Bob part of #3366, without its `wrap_targets.json` overlay, and supersedes #3323. Closes # ## Type of Change - [x] New feature (non-breaking change that adds functionality) ## Changes Made - `headroom/providers/wrap_registry.py`: `bare_origin` URL style; `openai_api_url`, `extra_chat_routes`, `origin_passthrough_prefixes`, `origin_passthrough_strip_json_keys`, `default_mode`, `preflight` fields; the `bob` target; `bob_preflight`, which aborts the wrap when a saved `~/.bob/settings/settings.json` `gatewayUrl` would override `BOB_GATEWAY_URL` (bobshell re-resolves `settings.gatewayUrl ?? policy.GatewayUrl ?? env` at startup, verified in 2.0.5); `resolve_origin_passthrough_url` / `strip_origin_passthrough_response_keys` over a host-keyed index built once from the static registry - `headroom/providers/route_specs.py`: `OPENAI_HANDLER_ROUTES` gains the registry's `extra_chat_routes`, built from static code data (no user-file read) - `headroom/proxy/handlers/openai.py`: catch-all passthrough uses the origin-rooted URL for declared paths and strips declared keys from 200 JSON responses - `headroom/proxy/server.py`: `/health` config block adds `mode` - `headroom/cli/wrap.py`: generated commands export `default_mode` and pass `openai_api_url`; new `_warn_proxy_mode_mismatch` on both proxy-reuse paths - `tests/test_cli/test_wrap_bob.py` (22 tests), including a handler-level test that fails without the `openai.py` wiring ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest tests/test_cli/ tests/test_provider_route_specs.py tests/test_agent_savings.py \ tests/test_custom_base_passthrough_telemetry.py tests/test_compress_passthrough.py 878 passed, 1 skipped $ pytest tests/test_cli/test_wrap_bob.py -k handler # with openai.py reverted to the parent commit 1 failed (upstream URL was not origin-rooted) # -> the test guards the wiring $ mypy headroom/cli/wrap.py headroom/providers/wrap_registry.py headroom/providers/route_specs.py Success: no issues found in 3 source files ``` Locally, `tests/test_proxy_healthchecks.py` (where I added the `mode` assertion) and two `tests/test_proxy_openai.py` cases fail identically on `main`, because of a Starlette `TestClient` version mismatch in my environment. So I checked `/health` separately through `httpx.ASGITransport` from a loopback client: `ProxyConfig(mode="token")` → `"mode": "token"`, `ProxyConfig(mode="cache")` → `"mode": "cache"`. ## Real Behavior Proof - Environment: macOS (darwin 25.6.0), Python 3.13, this branch; the real IBM gateway, no Bob credentials - Exact command / steps: a stub `bob` on PATH reads `/health` through `BOB_GATEWAY_URL` and sends uncredentialed requests for Bob's three paths; `headroom wrap bob --port 8911 -- run "fix it"` with `HEADROOM_MODE` unset. For comparison, the same GETs sent straight to IBM at the correct URLs and at the misrooted ones. - Observed result: all three paths reach the correct IBM URLs. - The child gets `BOB_GATEWAY_URL=http://127.0.0.1:8911/p/run` and `argv=run fix it`. The proxy reports `mode: token`. - The chat POST is logged as `outbound_request … path=https://api.us-east.bob.ibm.com/inference/v1/chat/completions`. Cloudflare rejects it with 403 because there are no credentials. - `/admin/v1/profile` returns **401**, which matches the origin-rooted URL (direct GET → 401). The misrooted `/inference/admin/v1/profile` returns **403**. - Not tested: a credentialed, live Bob session on this branch (it spends IBM credits). That ran end to end on #3366, which shares these code paths except for the removed overlay. `/inference/v1/model/info` can't be told apart without credentials (403 either way); the handler and unit tests cover it. ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: two changes reach every proxy: - The route `POST /inference/v1/chat/completions` is added. It previously matched the catch-all. - Catch-all passthrough changes only for requests whose OpenAI upstream is the Bob gateway host. `/health` gains a `mode` field. Other clients behave the same. - Kill switch / disable path: don't use `wrap bob`; the passthrough rules only fire for the Bob gateway host - Unsafe override required: no - Qualification impact: none - Rollback path: revert this PR; no persisted state. What to monitor: 403s on `/inference` or `/admin` paths in the proxy log for Bob sessions. ## 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 - Documentation: `headroom wrap bob --help` documents usage and the mode default. There's no separate docs page, matching the other env-var wrap targets. - Known limitations, deliberate in this PR: - The saved-`gatewayUrl` guard runs from `configure_launch`, after the proxy is up, because it must see the actual port. A misconfigured machine pays one proxy start/teardown (~2 s) before the abort; an earlier requested-port check reintroduces the "rejected too early" case. - Registry commands have no `--openai-api-url`; a non-us-east Bob account needs a hand-started `headroom proxy --openai-api-url https://api.<region>.bob.ibm.com/inference/v1` plus `--no-proxy`. The passthrough rules now key on `.bob.ibm.com`, so that setup gets the same path rooting and `region_domain` strip. - `default_mode` is delivered through `HEADROOM_MODE` in the wrapper's environment; that is the documented mode interface and what `_start_proxy` already reads. It is also visible to the child process. - `/inference/v1/chat/completions` is a static route on every proxy, not gated on the upstream; no other upstream serves that path. - After a persistent restart the mode warning queries the restarted proxy's config; the "recovered but nothing listening" return stays silent because there is no proxy to compare. - Known limitation, unchanged by this PR: one proxy has one OpenAI-family upstream and one mode. When Bob joins a shared proxy started without the IBM upstream, wrap restarts it and repoints OpenAI traffic for every attached client (kimi and vibe behave the same way). Give Bob its own `--port` when running several harnesses. - One of three PRs replacing #3366. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3801" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a> <!-- devin-review-badge-end --> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
bb1ab6afd3 |
fix(wrap): preserve pre-set ANTHROPIC_BASE_URL as proxy upstream (#1358)
## Description Issue #1353: when the user already has `ANTHROPIC_BASE_URL` pointing at a LiteLLM (or any custom Anthropic-compatible) gateway, `headroom wrap claude` overwrote it with the local proxy URL and silently forwarded to `api.anthropic.com`. `wrap claude` now treats a pre-existing non-self-pointing `ANTHROPIC_BASE_URL` as the proxy's upstream (passed as `ANTHROPIC_TARGET_API_URL`) so compression layers on top of the user's gateway instead of replacing it. Explicit `ANTHROPIC_TARGET_API_URL`, Foundry and Vertex paths still win. Closes #1353 ## 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 - Add `_detect_inbound_anthropic_upstream(proxy_port)` to `headroom/cli/wrap.py`: returns a pre-set `ANTHROPIC_BASE_URL` as the proxy upstream, ignoring unset/blank values and self-pointing localhost URLs on the proxy port. - Wire it into `wrap claude` so a user's custom gateway is preserved as `ANTHROPIC_TARGET_API_URL` instead of being overwritten. - Precedence unchanged: explicit `ANTHROPIC_TARGET_API_URL`, Foundry, and Vertex still take priority. - Add `tests/test_cli/test_wrap_claude_inbound_upstream.py` (8 cases) covering detection, blank/unset, self-pointing URLs, and a different-port upstream. ## Testing - [x] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text tests/test_cli/test_wrap_claude_inbound_upstream.py::test_detects_custom_litellm_upstream PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_when_unset PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_when_blank PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://127.0.0.1:8787] PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://localhost:8787] PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://127.0.0.1:8787/] PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_none_for_self_pointing_url[http://LOCALHOST:8787/v1] PASSED tests/test_cli/test_wrap_claude_inbound_upstream.py::test_returns_localhost_on_different_port PASSED ============================== 8 passed in 0.25s =============================== ``` ## Real Behavior Proof - Observed result: eight focused detection cases fail without the helper and pass with it; custom non-self-pointing gateways are preserved while blank or self-pointing values fall through safely. - Environment: Python 3.13, local checkout, pytest 9.0.3 - Exact command / steps: `pytest tests/test_cli/test_wrap_claude_inbound_upstream.py -v` on the patched branch, then with the production fix reverted. - Observed result (RED → GREEN): - **RED** — with the fix reverted, all 8 tests fail: `AttributeError: module 'headroom.cli.wrap' has no attribute '_detect_inbound_anthropic_upstream'` (`8 failed in 0.37s`). - **GREEN** — with the fix applied, all 8 pass (`8 passed in 0.25s`). - Not tested: end-to-end live LiteLLM gateway round-trip (covered indirectly by the upstream-URL detection unit tests). ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Additional Notes Docs/CHANGELOG checklist items left unchecked as N/A: this is a behavioral bug fix to existing `wrap claude` upstream handling with no new public surface to document. ## Real Behavior Proof - Environment: headroom 0.28.0 dev checkout (branch `fix/issue-1353`), `.venv`, proxy port 8787. - Exact command / steps: invoked the real detection path used by `wrap claude` (`_detect_inbound_anthropic_upstream`) across representative `ANTHROPIC_BASE_URL` values: ``` python -c "from headroom.cli.wrap import _detect_inbound_anthropic_upstream as d; ..." ``` - Observed result: ``` custom LiteLLM gateway -> 'https://litellm.mycorp.internal/v1' unset -> None blank -> None self-pointing localhost:8787 -> None self-pointing LOCALHOST/v1 -> None different port (real upstream)-> 'http://10.0.0.5:4000' ``` A pre-set, non-self-pointing `ANTHROPIC_BASE_URL` is returned as the proxy upstream (wired to `ANTHROPIC_TARGET_API_URL`), so compression layers on top of the user's gateway. Unset / blank / self-pointing values fall through to `None`, so the proxy default applies and no self-forwarding loop is created. - Not tested: full `wrap claude` launch end-to-end against a live LiteLLM gateway (needs the external gateway + Claude Code); the wiring from `custom_upstream` to `ANTHROPIC_TARGET_API_URL` is covered by the unit suite. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
1982b3a773 |
fix(codex): explain why wrapped Codex runs without the shared server (#3899)
## Description `headroom wrap codex` passes proxy routing as a `--config` override (`openai_base_url=…`, or `model_providers.<id>.base_url=…` for custom providers). This keeps routing scoped to the launched process and leaves `~/.codex/config.toml` untouched, by design (#1507, #2160). Codex 0.159 runs any session that has command-line overrides in embedded mode, so wrapped sessions always print `Running without the shared background server` and never use Codex's shared background server. Env-only routing can't replace the override. ChatGPT-subscription Codex ignores `OPENAI_BASE_URL` (see |
||
|
|
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> |
||
|
|
bd0296b5e7 |
fix(wrap): strip -dev from running proxy version in restart check (#3200)
## Description
`headroom wrap` is supposed to restart an already-running proxy whose
Headroom version differs from the CLI's. The check,
`_proxy_needs_version_restart`, strips the `-dev` suffix only from the
CLI's own version. A source-built proxy reporting e.g. `0.34.0-dev`
fails the `^v?\d+\.\d+\.\d+$` release regex, normalizes to `None`, and
the check silently never fires — so any stale dev-built proxy is reused
forever. The docstring already claims the opposite behavior ("a dev CLI
still restarts a stale proxy on a real version difference"); this PR
makes the code match it.
Observed in production on a maintainer machine: a 21-day-old
`0.34.0-dev` proxy (zero attached clients) was silently reused by a
`0.37.0-dev` wrap, which then also inherited its incompatible routing
config (see linked companion PR for the routing half).
Closes #3197
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- `headroom/cli/wrap.py`: `_proxy_needs_version_restart` now strips
`-dev` from the *running* proxy version before normalization (mirroring
the CLI side), with a comment pinning the version scheme (`<base>-dev`
from `get_version`) so future suffix styles get stripped too.
- `tests/test_cli/test_wrap_persistent.py`: regression tests — dev proxy
vs dev CLI with different base releases restarts; same base does not;
release proxy vs dev CLI restarts; unparseable/missing versions still
never restart.
## 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 pytest tests/test_cli/test_wrap_persistent.py -q
32 passed in 0.63s
$ uv run pytest tests/test_cli/test_wrap_persistent.py tests/test_cli/test_wrap_helpers.py -q
90 passed in 0.57s
$ uv run ruff format headroom/cli/wrap.py tests/test_cli/test_wrap_persistent.py
2 files left unchanged
$ uv run ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_persistent.py
All checks passed!
$ uv run mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```
## Real Behavior Proof
- Environment: macOS 26.5 arm64, Python 3.13, local source build
0.37.0-dev (integration overlay), live stale proxy: `headroom proxy
--port 8789` running 0.34.0-dev for 21 days with zero attached wrap
clients.
- Exact command / steps: `GET http://127.0.0.1:8789/health` before and
after; then from the fixed build, `python -c "from headroom.cli import
wrap as w; w._ensure_proxy(8789, False, agent_type='codex')"`.
- Observed result: before fix the same call printed "Proxy already
running" (reused). After fix: `/health` before = `version 0.34.0-dev,
pid 63454, augment_api_url set`; the call killed PID 63454 and started a
fresh proxy; `/health` after = `version 0.37.0-dev, pid 48365,
augment_api_url None`. Against a second stale proxy (port 8788) with one
live wrapper attached, the check correctly deferred ("Leaving it running
because 1 attached wrapper(s)") instead of killing a live session's
proxy.
- Not tested: the persistent-deployment variant of the version-restart
path (unit-tested only); Windows (code path is platform-independent
string handling).
## Runtime Rollout Safety
- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: yes — wraps now actually restart
stale dev-built proxies instead of reusing them. Release-built proxies
(no `-dev` suffix) are byte-identical in behavior.
- Kill switch / disable path: none needed; stopping the old proxy
manually restores prior behavior.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit; reuse of stale dev proxies resumes.
## 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
Adversarially reviewed by a second model (glm-5.2, high reasoning)
before submission; verdict ready, one nit (version-scheme comment)
accepted and applied. Companion PRs (same incident): routing-config
reuse check, orphan-proxy watchdog.
Co-authored-by: JD Davis <mxjerrett@gmail.com>
|
||
|
|
08dda4cb0b |
fix(cli): strip unmarked headroom_memory TOML table before injecting (#3490)
## Description
`_inject_memory_mcp_config` (used by `headroom wrap codex`) only guards
against a duplicate `[mcp_servers.headroom_memory]` table via the
`_MEMORY_MCP_MARKER`/`_MEMORY_MCP_END` comment pair it writes. If that
table already exists in a user's `~/.codex/config.toml` **without**
those markers — e.g. hand-copied from the usage example in
`headroom/memory/mcp_server.py`, or left over from before this table
was marker-guarded — the injector appends a second
`[mcp_servers.headroom_memory]` table instead of replacing the
existing one. Two tables sharing the same key is invalid TOML, and
silently breaks Codex's MCP config parsing on startup.
This PR adds a helper that strips any unmarked
`[mcp_servers.headroom_memory]` table before the marker-wrapped
section is appended, mirroring the pattern already used for
`[model_providers.headroom]`.
No issue number to close (found while reviewing the Codex wrap flow).
## 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
- Added `_strip_existing_codex_memory_mcp_table()` in
`headroom/cli/wrap.py`, mirroring the existing
`_strip_existing_codex_headroom_provider_table()` helper: it
regex-matches an unmarked `[mcp_servers.headroom_memory]` table and
removes it.
- Called this new helper from `_inject_memory_mcp_config()` right before
appending the marker-wrapped `headroom_memory` section, in the branch
that runs when no `_MEMORY_MCP_MARKER` is found in the existing config.
- Added a regression test, `test_inject_replaces_unmarked_memory_block`,
in `tests/test_cli/test_wrap_codex.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
- [ ] Manual testing performed
### Test Output
```text
$ .venv/bin/python -m pytest tests/test_cli/test_wrap_codex.py -q
============================= test session starts ==============================
platform linux -- Python 3.13.15, pytest-9.0.3, pluggy-1.6.0
rootdir: /home/bitter/development/oss/headroom
configfile: pyproject.toml
plugins: anyio-4.12.1, cov-7.0.0, langsmith-0.9.3, respx-0.23.1, asyncio-1.3.0
collected 93 items
tests/test_cli/test_wrap_codex.py ...................................... [ 40%]
....................................................... [100%]
======================== 93 passed in 66.82s (0:01:06) =========================
$ .venv/bin/python -m pytest tests/test_cli/ -q
[...]
734 passed, 4 skipped, 1 failed in 92.84s (0:01:32)
FAILED tests/test_cli/test_unwrap_claude.py::test_unwrap_claude_stops_claude_owned_persistent_deployment
```
This one failure is pre-existing on a clean `main` checkout (verified
via `git stash` + rerun before making any change here) and is
unrelated to this PR — it's an assertion on unwrap-claude output
messaging, not touched by this diff.
```text
$ .venv/bin/python -m ruff check headroom/cli/wrap.py tests/test_cli/test_wrap_codex.py
All checks passed!
$ .venv/bin/python -m mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```
## Real Behavior Proof
- Environment: local dev checkout, Python 3.13.15, `.venv` from repo
(`pytest 9.0.3`, `ruff`, `mypy`).
- Exact command / steps: Ran `.venv/bin/python -m pytest
tests/test_cli/test_wrap_codex.py::TestCodexMemoryMcpConfig::test_inject_replaces_unmarked_memory_block
-q`, which (1) seeds `~/.codex/config.toml` with an unmarked
`[mcp_servers.headroom_memory]` table plus `[profiles.default]` and an
unrelated `[mcp_servers.other]` table, (2) calls
`_inject_memory_mcp_config("codex-user")` — the same function `headroom
wrap codex` invokes — and (3) reads the resulting `config.toml` back and
parses it with `tomllib.loads`.
- Observed result: With the fix applied, the test passes — exactly one
`[mcp_servers.headroom_memory]` table remains in the file, wrapped in
the `_MEMORY_MCP_MARKER`/`_MEMORY_MCP_END` comments, with the updated
`--user codex-user` value; `[profiles.default]` and
`[mcp_servers.other]` are byte-for-byte untouched;
`tomllib.loads(content)` succeeds and
`parsed["mcp_servers"]["headroom_memory"]["args"][-1] == "codex-user"`.
I additionally reverted just `headroom/cli/wrap.py` to its pre-fix state
(`git checkout
|
||
|
|
b1b005a9a8 |
fix(memory): align project routing with wrap headers (#3603)
## Description When `headroom wrap claude` runs from two directories named `api`, both requests currently send `X-Headroom-Project: api`. Using that label as a memory or CCR identity can make the two workspaces share history. This keeps `X-Headroom-Project` as the human-readable savings label and adds `X-Headroom-Cwd`, derived from the canonical launch directory, for routing. The resolver now ignores the label when it is the only project signal. Closes #3597 ## 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 - Keep `X-Headroom-Project` for savings attribution only. - Add a percent-encoded `X-Headroom-Cwd` header containing the canonical launch directory. - Hash the decoded cwd for memory and CCR routing, while retaining the basename as the display label. - Preserve user-supplied project and cwd headers without duplicating or overwriting them. - Add regressions for same-basename directories, label-only fail-closed behavior, and an explicit user-supplied label collision. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text 216 passed, 1 warning in 4.80s 7 files already formatted All checks passed! git diff --check: clean ``` ## Real Behavior Proof - Environment: Ubuntu 24.04 VPS, Python 3.12.3, Rust extension built in the test environment. - Exact command / steps: Wrapped two temporary directories with the same basename (`api`), using the same explicit `X-Headroom-Project` value, then resolved both memory and CCR workspaces. - Observed result: Both requests retained the same display label but produced different cwd headers and different memory and CCR keys. A request containing only the display label returned the fail-closed result. - Not tested: A live request to an external Claude provider. ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Stable. - Stable/default behavior changed: `headroom wrap claude` now sends a second `X-Headroom-Cwd` routing header; `X-Headroom-Project` remains a savings label. - Kill switch / disable path: Remove the generated routing header or disable project-scoped memory/CCR using the existing configuration. - Unsafe override required: No. - Qualification impact: Requests with only the savings label remain unscoped and fail closed; requests with a cwd identity retain project-scoped memory and CCR. - Rollback path: Revert commit `101b332`. ## 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 - [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: Tejas Chopra <chopratejas@gmail.com> Co-authored-by: JerrettDavis <mxjerrett@gmail.com> |
||
|
|
3ffa57ec25 |
fix(wrap): never reuse a non-Headroom listener on the proxy port (#3799)
## Description
`headroom wrap` decided a proxy was running with `_check_proxy`, which
is a bare TCP connect. Any service listening on the wrap port passed
that check. When something other than Headroom held the port (seen in
practice: a caveman gateway on 8787), wrap would:
- reuse it and route the tool at it
- wait on it as a persistent deployment
- treat it as a live session in the dead-marker self-heal
A listener now counts as Headroom only if its `/health` payload carries
Headroom identity: `service: "headroom-proxy"` (reported by both the
Python and Rust proxies) or a `config` block. Generic JSON such as
`{"status": "ok"}` is foreign. Otherwise wrap uses the existing port
search.
Split out of #3366. These fixes apply to every harness and don't depend
on the wrap-target registry.
Closes #
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- `headroom/cli/wrap.py`:
- `_is_headroom_health(payload)`: the identity rule above.
- `_foreign_listener(port)`: TCP accepts, but `/health` does not
identify Headroom.
- `_ensure_proxy_unlocked`: a foreign listener is never reused. The port
search takes over, and a persistent manifest on a foreign-held port
falls through to a fresh proxy instead of raising "not healthy".
- `_check_and_clear_dead_wrap_marker`: a foreign listener on a dead
wrapper's port no longer counts as a live session (the marker is kept
while the writer PID is alive).
- `_launch_tool`: on port fallback the launch banner is rewritten too,
so it shows the URL the child actually got (the env already was).
- `wrap claude`: the marker/owner claim records `actual_port` instead of
the requested port.
- `_ensure_claude_wrap_selfheal_hook`: a marker-bearing hook whose
command drifted (hand edit, moved binary) is rewritten in place instead
of skipped.
- `tests/test_cli/test_wrap_claude_vertex_proxy_env.py`: runs in an
isolated cwd so it can't write a selfheal hook into the repo's
`.claude/settings.local.json`. Also gitignored
`.claude/.headroom_wrap_*.json`.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ pytest tests/test_cli/
792 passed, 1 skipped
$ ruff check headroom/cli/wrap.py tests/test_cli/ && ruff format --check headroom/cli/wrap.py tests/test_cli/
All checks passed!
$ mypy headroom/cli/wrap.py
Success: no issues found in 1 source file
```
New: `tests/test_cli/test_wrap_foreign_listener.py` (12 tests, including
a generic-JSON `/health` server and the Rust-proxy `/health` shape),
`test_wrap_selfheal_hook_repairs_stale_command`. Updated:
`test_wrap_kimi.py::test_non_kimi_fallback_display_follows_actual_port`
(asserted the old stale banner), plus two `test_wrap_persistent.py`
tests that now identify the listener as Headroom via `/health`.
## Real Behavior Proof
- Environment: macOS (darwin 25.6.0), Python 3.13, this branch vs `main`
at
|
||
|
|
5bf6612326 |
fix(cli): honor CODEX_HOME and align wrap/init/doctor with the live proxy port (#3855)
## Description Closes several CLI usability gaps where `wrap`, `init` and `doctor` disagreed about *where* things are: 1. **CODEX_HOME was ignored by `doctor` / `install` / `init -g codex` hooks.** `codex_config_path()` hardcoded `~/.codex/config.toml`, while `wrap` and the MCP registrar honored `CODEX_HOME`. With a relocated Codex home, `doctor` reported "not routed" for a correctly wrapped Codex (and `install apply` edited the wrong file). 2. **Hard-coded 8787.** `wrap <tool> --port` (~20 subcommands) and `init --port` ignored `HEADROOM_PORT` and never noticed a proxy already running on another port, so they would start a second proxy or point the agent at a dead port. 3. **`init hook ensure` output was fully suppressed**, so an agent whose `base_url` drifted from the managed proxy's port failed silently every session. 4. **`doctor`** only probed `/livez`, did not check the hooks `init` installs, and did not notice a live proxy on another port. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) ## Changes Made **CODEX_HOME (one helper, reused everywhere)** - `headroom.install.paths`: new `codex_home_dir()` (`CODEX_HOME`, blank-safe, else `~/.codex`), `codex_hooks_path()`, `codex_project_config_path()`; `codex_config_path()` now goes through it. - Reused by `wrap._codex_home_dir`, `CodexRegistrar`, `recover codex`, `init` (`-g` config **and** `hooks.json`), `install` (via `codex_config_path`), and `doctor`. - `doctor`'s `codex` check consults the project `.codex/config.toml` first (Codex layers it over the user config; `init codex` without `-g` writes there), then `$CODEX_HOME/config.toml`, and names the file that supplied the routing. The "no config" summary now names the real path instead of `~/.codex/config.toml`. **Port resolution (`headroom/cli/port_discovery.py`)** - Every `wrap` subcommand's `--port` / `--proxy-port` (shared `proxy_port_option`) and `init --port`: - explicit `--port` -> honored as-is, no discovery; - `HEADROOM_PORT` -> honored as-is, no discovery; - otherwise default 8787 **plus** cheap discovery: candidates are the requested port, `HEADROOM_PORT`, 8787, deployment-manifest ports and the project's wrap marker (max 8, de-duplicated), probed **concurrently** on loopback `/livez` with a 0.5 s timeout. A port counts only if `/livez` identifies `service: headroom-proxy` (unrelated local servers are ignored). No port-range scanning. - If the requested port has no Headroom proxy but another candidate does: - **TTY (stdin and stdout)**: prompt `Connect to the running proxy on N [c], keep port 8787 [k], or abort [a]?` (default `c`); - **non-interactive**: keep the requested port (nothing is adopted silently) and print to stderr the live port and the exact `--port N` / `HEADROOM_PORT=N` to use it. - `init hook ...` never runs discovery (hooks must stay silent/fast). - Kill switch: `HEADROOM_PORT_DISCOVERY=0`. - Before `wrap codex` / `init codex` rewrite an existing `[model_providers.headroom]` whose loopback `base_url` port differs, a warning names the old and new port and how to keep the old one. **`init hook ensure` alignment warning** - After the (still suppressed) ensure step, for Claude/Codex hooks on **SessionStart only** (event read from the hook's stdin JSON with a 0.5 s bound), compare the agent's configured base URL port -- Claude: `settings.local.json` > `settings.json` > `~/.claude/settings.json` > env; Codex: project `.codex/config.toml` > `$CODEX_HOME/config.toml` -- with the managed manifest's port. On mismatch it prints hook JSON: `systemMessage` (user) + `hookSpecificOutput.additionalContext` (agent), including the fix command (`headroom init [-g] --port N <agent>`; N = the configured port if a Headroom proxy is live there, else the managed port). PreToolUse / Copilot stay silent. Wrapped in a catch-all: never raises, never blocks. **`doctor`** - New `readiness` row: probes `/readyz` (3 s) when `/livez` answered; live-but-not-ready is a WARN. - New `hooks` row: for each `init` manifest in scope (`init-user`, or this project's profile), checks the Claude settings / Codex `hooks.json` (CODEX_HOME-aware) still contain the Headroom hook and that the hook's program still resolves; WARN with the exact `headroom init ...` re-install command. SKIP when no init hooks are expected. - When the probed port is down, discovery (same bounded candidates) names a live proxy on another port in the `proxy` row with `headroom doctor --port N` and the matching `wrap`/`init --port N` commands. Exit-code semantics unchanged (still 2 when the probed proxy is down). **`wrap selfheal`** - After clearing a dead wrap route, if a live Headroom proxy exists elsewhere it prints `headroom wrap claude --port N` to stderr. Deliberately **warn-only** (no automatic repoint): adopting another session's proxy could silently change backend/mode/owner. **Tests** - `tests/test_cli/test_port_alignment.py` (47 tests): CODEX_HOME helpers + consumers, doctor CODEX_HOME/project precedence, port candidates/bounds/identity/disable switch, TTY prompt c/k/a, non-TTY warning, click option source handling (default vs `--port` vs `HEADROOM_PORT`), all wrap subcommands wired to the shared option, init port resolution (incl. hook skip), Codex provider repoint warning, hook JSON on SessionStart / silent on PreToolUse / never raises, doctor readiness/hooks/live-elsewhere, selfheal warning. All homes/cwd/workspace under `tmp_path`, probes injected -- no real `~/.codex`, `~/.headroom`, or proxy. - `tests/conftest.py`: autouse sets `HEADROOM_PORT_DISCOVERY=0` and unsets `CODEX_HOME` so a developer's running proxy / Codex home can't leak into CLI tests (tests that need discovery re-enable it). ## Testing - [x] Unit tests pass (`pytest`) -- affected suites, see below - [x] Linting passes (`ruff check .`, `ruff format --check`) - [x] Type checking passes (`mypy headroom`) -- no new errors - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ python -m pytest tests/test_cli/test_port_alignment.py -q 47 passed in 1.61s $ python -m pytest tests/test_cli tests/test_cli_doctor.py tests/test_install tests/test_mcp_registry tests/test_provider_codex_runtime.py -q 2 failed, 1314 passed, 8 skipped FAILED tests/test_cli/test_unwrap_claude.py::test_unwrap_claude_removes_mcp_purges_retired_hook_and_stops_proxy FAILED tests/test_cli/test_wrap_stale_marker.py::test_signal_handler_unwinds_so_the_restore_can_run # both fail identically on unmodified upstream/main on Windows (signal.SIGHUP missing; retired rtk hook cleanup) -- pre-existing, unrelated $ ruff check headroom tests/... && ruff format --check ... All checks passed! $ mypy headroom headroom/fileperms.py:71 (os.fchmod on Windows) and headroom/integrations/langchain/chat_model.py:394 -- both pre-existing, files untouched ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12.13, worktree checkout. Fully sandboxed: `HOME`/`USERPROFILE`/`APPDATA`, `CODEX_HOME` and `HEADROOM_WORKSPACE_DIR` pointed at a scratch dir; a stand-in server answering only `/livez` with `service: headroom-proxy` on port 47311; a hand-written deployment manifest on 47311 and an `init-user` manifest on 8787; Claude settings and `$CODEX_HOME/config.toml` routed to 47311. - Exact command / steps: run each `$` command below in the sandboxed environment (doctor, init hook alignment, port reconcile, codex provider repoint). - Observed result: each command's output is shown directly beneath it; doctor names the live proxy on 47311 and honors CODEX_HOME, the hook warns on port mismatch, and non-interactive reconcile keeps the requested port. ```text $ headroom doctor --port 47399 --json (rows) proxy fail | not reachable at http://127.0.0.1:47399; a Headroom proxy IS running on port 47311 | re-run with: headroom doctor --port 47311 (or export HEADROOM_PORT=47311); to use port 47311 from agents, re-run `headroom wrap <agent> --port 47311` / `headroom init --port 47311 <agent>` codex warn | routed to port 47311, but doctor probed port 47399 (<scratch>\codex\config.toml) | re-run with: headroom doctor --port 47311 $ headroom doctor --port 47311 --json (rows) proxy pass | running at http://127.0.0.1:47311 (up, demo) readiness warn | proxy is live but /readyz is not ready (upstream unreachable or still starting) codex pass | routed via <scratch>\codex\config.toml <- CODEX_HOME honored hooks warn | claude (user): no Headroom hook in <scratch>\home\.claude\settings.json; codex (user): no Headroom hook in <scratch>\codex\hooks.json | re-install with: headroom init -g claude && headroom init -g codex $ echo '{"hook_event_name":"SessionStart"}' | <init hook alignment, marker headroom-init-claude, profile init-user> {"systemMessage": "Headroom: Claude Code is configured for http://127.0.0.1:47311 but the Headroom proxy managed by `headroom init` (init-user) uses port 8787; a Headroom proxy is running on 47311, not the managed one. Fix: headroom init -g --port 47311 claude", "hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}} (same for codex via CODEX_HOME; PreToolUse -> no output) $ non-interactive default-port reconcile (requested 47398) headroom: no Headroom proxy on port 47398, but one is running on port 47311. headroom: continuing with port 47398. To use the running proxy, pass --port 47311 (or set HEADROOM_PORT=47311). $ codex provider repoint headroom: warning: cfg.toml routes Codex's [model_providers.headroom] to port 47311; repointing it to port 8787. Pass --port 47311 to keep the existing route. ``` - Not tested: the interactive TTY prompt end-to-end in a real terminal (covered by unit tests with a stubbed prompt); a full `wrap <agent>` launch against a real proxy; the hook JSON as rendered inside a live Claude Code / Codex session (Codex's acceptance of `hookSpecificOutput.additionalContext` for SessionStart is assumed to mirror Claude's schema); Linux/macOS. ## Runtime Rollout Safety - Rollout-managed feature(s): none (CLI only; proxy runtime untouched). - Minimum rollout channel: Stable. - Stable/default behavior changed: default `wrap`/`init` port now follows `HEADROOM_PORT`; discovery only warns or prompts, never switches ports non-interactively. - Kill switch / disable path: `HEADROOM_PORT_DISCOVERY=0`; explicit `--port` bypasses discovery. - Unsafe override required: No. - Qualification impact: None (CLI only; no proxy runtime or qualification-gated behavior touched). - Rollback path: revert this PR. ## 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 - [x] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation (CLI help text updated; no docs pages changed) - [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 (2 pre-existing Windows-only failures noted above) - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes Design points for review: - `HEADROOM_PORT` is treated as an explicit choice (no discovery/prompt), same as `--port`. - The TTY prompt defaults to *connect* to the live proxy; non-TTY never adopts. - `unwrap` commands were intentionally left on their old `--port` default: discovering a port there could stop a proxy the user did not target. - `wrap` subcommand `--port` now also reads `HEADROOM_PORT` via Click's envvar, so an invalid `HEADROOM_PORT` is a usage error for `wrap` (init/hook ignore invalid values). - The hook reads stdin for `hook_event_name` in a daemon thread bounded to 0.5 s so a host that never closes stdin cannot stall session start. |