mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-23 02:49:17 +08:00
## 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 3aa50128
- Exact command / steps: `python3 -m http.server 8899` as a foreign
listener (its `/health` returns 404); a stub `goose` on PATH that prints
`OPENAI_BASE_URL` and curls `$ANTHROPIC_BASE_URL/health`; then `headroom
wrap goose --port 8899`
- Observed result: main hands the tool the squatter; this branch starts
a real proxy on the next port.
- main: `Proxy already running on port 8899` → child gets
`http://127.0.0.1:8899/v1`, and its `/health` → **404** (the tool is
talking to the squatter)
- this branch: `Port 8899 is in use by a non-Headroom service; selecting
another port...` → proxy starts on 8900, banner and child both show
`http://127.0.0.1:8900/v1`, `/health` → **200**
- Not tested: Windows; a live persistent (`headroom install`) deployment
whose port was taken over (covered by
`test_persistent_manifest_on_foreign_port_falls_through`)
## Runtime Rollout Safety
- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only when a non-Headroom service
holds the wrap port. Wrap used to hand the tool that service; now it
starts a Headroom proxy on the next free port. A real Headroom proxy is
identified by `/health` and reused exactly as before.
- Kill switch / disable path: none needed; pass `--port` to choose a
free port explicitly
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR; no persisted state or format changes
## 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: N/A, no user-facing docs describe port reuse.
- One of three PRs replacing #3366 (see that PR for the split
rationale). Independent of the other two; merges cleanly with them in
either order.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
323 lines
12 KiB
Python
323 lines
12 KiB
Python
"""Tests for `headroom wrap kimi` command."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
import sys
|
|
from pathlib import Path
|
|
from typing import Any
|
|
from unittest.mock import patch
|
|
|
|
import pytest
|
|
from click.testing import CliRunner
|
|
|
|
from headroom.cli import wrap as wrap_mod
|
|
from headroom.cli.main import main
|
|
|
|
|
|
@pytest.fixture
|
|
def runner() -> CliRunner:
|
|
return CliRunner()
|
|
|
|
|
|
def test_managed_route_reproduction(
|
|
runner: CliRunner,
|
|
capfd: pytest.CaptureFixture[str],
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
tmp_path: Path,
|
|
) -> None:
|
|
"""The production launcher passes the managed endpoint to an exact-contract child."""
|
|
direct = "https://api.kimi.com/coding/v1"
|
|
monkeypatch.setenv("KIMI_BASE_URL", direct)
|
|
monkeypatch.setenv("KIMI_TEST_UNRELATED", "preserved")
|
|
monkeypatch.setattr(wrap_mod, "_project_name_from_cwd", lambda: "repo")
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value=sys.executable):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
result = runner.invoke(main, ["wrap", "kimi", "--port", "8787"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
env = captured["env"]
|
|
display = captured["env_vars_display"]
|
|
configure_launch = captured["configure_launch"]
|
|
child_result = tmp_path / "kimi-child.txt"
|
|
child = (
|
|
"import os, sys; from pathlib import Path; Path(r'"
|
|
f"{child_result}"
|
|
"').write_text('CHILD|' + os.environ['KIMI_CODE_BASE_URL'] + '|' + "
|
|
"os.environ['KIMI_BASE_URL'] + '|' + os.environ['KIMI_TEST_UNRELATED'] + '|' + sys.argv[1])"
|
|
)
|
|
|
|
with (
|
|
patch.object(wrap_mod, "_make_cleanup", return_value=lambda: None),
|
|
patch.object(wrap_mod.signal, "signal"),
|
|
patch.object(wrap_mod, "_register_proxy_client"),
|
|
patch.object(wrap_mod, "_ensure_proxy", return_value=(None, 9001)),
|
|
patch.object(wrap_mod, "_unregister_proxy_client"),
|
|
patch.object(wrap_mod, "_push_runtime_env"),
|
|
patch.object(wrap_mod, "_configure_quiet_cli_env", return_value=[]),
|
|
):
|
|
with pytest.raises(SystemExit) as raised:
|
|
wrap_mod._launch_tool(
|
|
binary=os.fspath(Path(sys.executable)),
|
|
args=("-c", child, "child-arg"),
|
|
env=env,
|
|
port=8787,
|
|
no_proxy=False,
|
|
tool_label="KIMI",
|
|
env_vars_display=display,
|
|
configure_launch=configure_launch,
|
|
)
|
|
|
|
assert raised.value.code == 0
|
|
output = result.output + capfd.readouterr().out
|
|
expected = "http://127.0.0.1:9001/p/repo/v1"
|
|
assert f"KIMI_CODE_BASE_URL={expected}" in output
|
|
assert f"KIMI_BASE_URL={expected}" in output
|
|
assert child_result.read_text() == f"CHILD|{expected}|{expected}|preserved|child-arg"
|
|
assert direct not in output
|
|
|
|
|
|
def test_wrap_kimi_launch(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""Kimi launches with correct configuration."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
|
|
result = runner.invoke(
|
|
main, ["wrap", "kimi", "--port", "9000", "--", "-m", "kimi-for-coding"]
|
|
)
|
|
|
|
assert result.exit_code == 0, result.output
|
|
env = captured["env"]
|
|
assert isinstance(env, dict)
|
|
assert captured["tool_label"] == "KIMI"
|
|
assert captured["agent_type"] == "kimi"
|
|
assert captured["args"] == ("-m", "kimi-for-coding")
|
|
assert captured["openai_api_url"] == "https://api.kimi.com/coding/v1"
|
|
assert callable(captured["configure_launch"])
|
|
assert env["KIMI_CODE_BASE_URL"] == "http://127.0.0.1:9000/v1"
|
|
assert env["KIMI_BASE_URL"] == "http://127.0.0.1:9000/v1"
|
|
|
|
|
|
def test_project_name(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""Project name is encoded in both Kimi endpoint variables."""
|
|
project_dir = tmp_path / "my-project"
|
|
project_dir.mkdir()
|
|
monkeypatch.chdir(project_dir)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
result = runner.invoke(main, ["wrap", "kimi", "--port", "7000"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
env = captured["env"]
|
|
assert env["KIMI_CODE_BASE_URL"] == "http://127.0.0.1:7000/p/my-project/v1"
|
|
assert env["KIMI_BASE_URL"] == "http://127.0.0.1:7000/p/my-project/v1"
|
|
|
|
|
|
def test_wrap_kimi_cli_fallback(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""Falls back to the `kimi-cli` binary when `kimi` is not on PATH."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
def fake_which(name: str) -> str | None:
|
|
return "/usr/local/bin/kimi-cli" if name == "kimi-cli" else None
|
|
|
|
with patch.object(wrap_mod.shutil, "which", side_effect=fake_which):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
|
|
result = runner.invoke(main, ["wrap", "kimi"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert captured["binary"] == "/usr/local/bin/kimi-cli"
|
|
|
|
|
|
def test_wrap_kimi_not_found(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""Error message when neither kimi nor kimi-cli is found."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value=None):
|
|
result = runner.invoke(main, ["wrap", "kimi"])
|
|
|
|
assert result.exit_code == 1
|
|
assert "Error: 'kimi' (or 'kimi-cli') not found in PATH" in result.output
|
|
assert "https://github.com/MoonshotAI/kimi-cli" in result.output
|
|
|
|
|
|
def test_port_fallback(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""Custom --port is passed to _launch_tool and appears in both URLs."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
|
|
result = runner.invoke(main, ["wrap", "kimi", "--port", "9999"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert captured["port"] == 9999
|
|
assert captured["env"]["KIMI_CODE_BASE_URL"] == "http://127.0.0.1:9999/v1"
|
|
assert captured["env"]["KIMI_BASE_URL"] == "http://127.0.0.1:9999/v1"
|
|
|
|
|
|
def test_non_kimi_fallback_display_follows_actual_port(
|
|
capfd: pytest.CaptureFixture[str], tmp_path: Path
|
|
) -> None:
|
|
"""A port fallback rewrites the banner too, so it shows the URL the child got."""
|
|
env = {**os.environ, "OTHER_BASE_URL": "http://127.0.0.1:8787/v1"}
|
|
display = ["OTHER_BASE_URL=http://127.0.0.1:8787/v1"]
|
|
child_result = tmp_path / "other-child.txt"
|
|
child = (
|
|
"import os; from pathlib import Path; Path(r'"
|
|
f"{child_result}"
|
|
"').write_text('CHILD|' + os.environ['OTHER_BASE_URL'])"
|
|
)
|
|
|
|
with (
|
|
patch.object(wrap_mod, "_make_cleanup", return_value=lambda: None),
|
|
patch.object(wrap_mod.signal, "signal"),
|
|
patch.object(wrap_mod, "_register_proxy_client"),
|
|
patch.object(wrap_mod, "_ensure_proxy", return_value=(None, 9001)),
|
|
patch.object(wrap_mod, "_unregister_proxy_client"),
|
|
patch.object(wrap_mod, "_push_runtime_env"),
|
|
patch.object(wrap_mod, "_configure_quiet_cli_env", return_value=[]),
|
|
):
|
|
with pytest.raises(SystemExit) as raised:
|
|
wrap_mod._launch_tool(
|
|
binary=os.fspath(Path(sys.executable)),
|
|
args=("-c", child),
|
|
env=env,
|
|
port=8787,
|
|
no_proxy=False,
|
|
tool_label="OTHER",
|
|
env_vars_display=display,
|
|
)
|
|
|
|
assert raised.value.code == 0
|
|
output = capfd.readouterr().out
|
|
assert "OTHER_BASE_URL=http://127.0.0.1:9001/v1" in output
|
|
assert "127.0.0.1:8787" not in output
|
|
assert child_result.read_text() == "CHILD|http://127.0.0.1:9001/v1"
|
|
|
|
|
|
def test_wrap_kimi_custom_api_url(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""--kimi-api-url overrides the upstream endpoint passed to _launch_tool."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
|
|
result = runner.invoke(
|
|
main,
|
|
["wrap", "kimi", "--kimi-api-url", "https://api.moonshot.ai/v1"],
|
|
)
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert captured["openai_api_url"] == "https://api.moonshot.ai/v1"
|
|
|
|
|
|
def test_wrap_kimi_no_proxy(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""--no-proxy flag prevents proxy startup."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
|
|
result = runner.invoke(main, ["wrap", "kimi", "--no-proxy"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert captured["no_proxy"] is True
|
|
|
|
|
|
def test_wrap_kimi_learn_memory(
|
|
runner: CliRunner,
|
|
tmp_path: Path,
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""--learn and --memory flags are passed to _launch_tool."""
|
|
monkeypatch.chdir(tmp_path)
|
|
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
|
|
|
|
captured: dict[str, Any] = {}
|
|
|
|
def fake_launch_tool(**kwargs: Any) -> None: # noqa: ANN003
|
|
captured.update(kwargs)
|
|
|
|
with patch.object(wrap_mod.shutil, "which", return_value="kimi"):
|
|
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
|
|
with patch.object(wrap_mod, "_project_name_from_cwd", return_value=None):
|
|
result = runner.invoke(main, ["wrap", "kimi", "--learn", "--memory"])
|
|
|
|
assert result.exit_code == 0, result.output
|
|
assert captured["learn"] is True
|
|
assert captured["memory"] is True
|