## 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>
Hermes Agent Integration
CCR retrieval plugin for Hermes Agent (Nous Research). Gives Hermes a native headroom_retrieve tool so compression markers produced by the headroom proxy are no longer a black box — the agent can fetch the original content back on demand instead of guessing or re-running commands.
Why this is needed
When Hermes routes its LLM traffic through headroom proxy, large tool outputs get compressed into markers like:
[1500 items compressed to 50. Retrieve more: hash=abc123] # Kompress path
<<ccr:abc123>> / <<ccr:abc123,base64,4.5KB>> # SmartCrusher opaque-blob path
Claude Code users get the headroom_retrieve MCP tool injected automatically. Hermes registers its own tools, so without this plugin the markers are irreversible from the agent's point of view — in practice the model either re-runs the original command (wasting tokens/time) or, worse, treats ccr:abc123 as a file path and tries to cat it.
This plugin closes the loop by calling the proxy's POST /v1/retrieve HTTP endpoint directly. It complements (does not overlap with) headroom wrap hermes proxy-side support.
Install
-
Copy the plugin into Hermes's user plugin directory:
mkdir -p ~/.hermes/plugins cp -r headroom_retrieve ~/.hermes/plugins/ -
Enable it in
~/.hermes/config.yaml:toolsets: - hermes-cli - web - headroom # add this plugins: enabled: - headroom_retrieveNote: once the
plugins.enabledkey exists it acts as an explicit allowlist — list any other user plugins you already rely on. -
Restart the Hermes gateway / TUI (plugin discovery is cached per process).
Supported Hermes providers
headroom wrap hermes sets ANTHROPIC_BASE_URL and OPENAI_BASE_URL. Hermes uses these only for the anthropic and openai providers. Its default provider (openrouter) and others such as nous call their own endpoints and skip Headroom. You must pick a routed provider with --provider, for example:
headroom wrap hermes -- --provider anthropic
The wrapper stops with an error before it starts the proxy or Hermes when --provider is missing or is not anthropic or openai. This includes a provider set only in ~/.hermes/config.yaml. To use another provider, run hermes directly, without Headroom.
Recommended proxy configuration
Hermes tool names don't match headroom's built-in DEFAULT_EXCLUDE_TOOLS (which protects Claude Code's Read/Grep/Edit/...), so two exclusions are strongly recommended on the proxy side:
HEADROOM_EXCLUDE_TOOLS=read_file,headroom_retrieve
read_file— Hermes's file reads are reference data the agent needs verbatim, same rationale as Claude Code'sRead.headroom_retrieve— without this, retrieved originals get re-compressed on the next request, producing an endless marker→retrieve→marker loop.
Behavior
- Accepts the bare hash or the whole marker —
<<ccr:abc123,base64,4.5KB>>,ccr:abc123, andhash=abc123are all normalized toabc123. - Retrieval is by hash and always returns the full original content.
- Clear, actionable errors: expired hash (TTL) and proxy-unreachable cases both tell the model to re-run the original command instead of retrying blindly.
Requirements
- headroom proxy running on
127.0.0.1:8787(edit_PROXY_URLin__init__.pyotherwise) httpx(already a Hermes dependency)
Tested against headroom 0.22.4 and 0.23.0 with Hermes Agent on macOS and Linux.