Files
headroom/plugins/hermes/README.md
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

3.5 KiB

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

  1. Copy the plugin into Hermes's user plugin directory:

    mkdir -p ~/.hermes/plugins
    cp -r headroom_retrieve ~/.hermes/plugins/
    
  2. Enable it in ~/.hermes/config.yaml:

    toolsets:
      - hermes-cli
      - web
      - headroom        # add this
    
    plugins:
      enabled:
        - headroom_retrieve
    

    Note: once the plugins.enabled key exists it acts as an explicit allowlist — list any other user plugins you already rely on.

  3. 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.

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's Read.
  • 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, and hash=abc123 are all normalized to abc123.
  • 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_URL in __init__.py otherwise)
  • httpx (already a Hermes dependency)

Tested against headroom 0.22.4 and 0.23.0 with Hermes Agent on macOS and Linux.