Files
headroom/tests/test_cli/test_wrap_hermes.py
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>
2026-11-05 21:11:37 -06:00

114 lines
3.6 KiB
Python

"""Tests for `headroom wrap hermes` command."""
from __future__ import annotations
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_wrap_hermes_sets_provider_envs(
runner: CliRunner,
tmp_path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""OPENAI_BASE_URL and ANTHROPIC_BASE_URL are set on launch."""
monkeypatch.chdir(tmp_path)
captured: dict[str, object] = {}
def fake_launch_tool(**kwargs): # noqa: ANN003
captured.update(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="hermes"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
result = runner.invoke(
main, ["wrap", "hermes", "--port", "9000", "--", "--provider", "anthropic"]
)
assert result.exit_code == 0, result.output
env = captured["env"]
assert isinstance(env, dict)
assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9000/v1"
assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9000"
assert captured["tool_label"] == "HERMES"
assert captured["agent_type"] == "hermes"
assert captured["args"] == ("--provider", "anthropic")
def test_wrap_hermes_missing_binary_errors_clearly(
runner: CliRunner,
tmp_path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""If the hermes binary is missing, fail with a clear error."""
monkeypatch.chdir(tmp_path)
with patch.object(wrap_mod.shutil, "which", return_value=None):
result = runner.invoke(main, ["wrap", "hermes"])
assert result.exit_code == 1
assert result.output == (
"Error: 'hermes' not found in PATH.\n"
"Install Hermes: https://hermes-agent.nousresearch.com/\n"
)
def test_wrap_hermes_prepare_only_exits_cleanly(
runner: CliRunner,
tmp_path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""--prepare-only must not attempt to launch Hermes."""
monkeypatch.chdir(tmp_path)
with patch.object(wrap_mod, "_launch_tool") as launch_tool:
result = runner.invoke(main, ["wrap", "hermes", "--prepare-only"])
assert result.exit_code == 0, result.output
launch_tool.assert_not_called()
@pytest.mark.parametrize(
"hermes_args",
[(), ("--provider", "openrouter"), ("--provider=nous",), ("--provider", "custom")],
)
def test_wrap_hermes_rejects_unrouted_provider_before_launch(
runner: CliRunner,
tmp_path,
monkeypatch: pytest.MonkeyPatch,
hermes_args: tuple[str, ...],
) -> None:
monkeypatch.chdir(tmp_path)
with patch.object(wrap_mod.shutil, "which", return_value="hermes"):
with patch.object(wrap_mod, "_launch_tool") as launch:
result = runner.invoke(main, ["wrap", "hermes", "--", *hermes_args])
assert result.exit_code == 1
assert "cannot route" in result.output
assert "routed through Headroom" not in result.output
launch.assert_not_called()
@pytest.mark.parametrize("provider", ["anthropic", "openai"])
def test_wrap_hermes_launches_routed_provider(
runner: CliRunner,
tmp_path,
monkeypatch: pytest.MonkeyPatch,
provider: str,
) -> None:
monkeypatch.chdir(tmp_path)
with patch.object(wrap_mod.shutil, "which", return_value="hermes"):
with patch.object(wrap_mod, "_launch_tool") as launch:
result = runner.invoke(main, ["wrap", "hermes", "--", "--provider", provider])
assert result.exit_code == 0, result.output
launch.assert_called_once()
assert launch.call_args.kwargs["args"] == ("--provider", provider)