feat(plugins): Hermes agent headroom_retrieve plugin (#824)

## Summary

Implements the Hermes-side retrieval plugin proposed in #796 (as invited
— thanks for the quick response!).

When Hermes routes traffic through `headroom proxy`, compressed markers
are a one-way street: Hermes registers its own tools, so it never gets
the `headroom_retrieve` CCR tool that Claude Code receives via MCP
injection. In practice the model either re-runs the original command or
— observed in the wild — treats `ccr:abc123` as a file path and tries to
`cat` it.

This plugin uses Hermes's user-plugin system (`~/.hermes/plugins/`) to
register a native `headroom_retrieve` tool that calls the proxy's `POST
/v1/retrieve` endpoint.

## What's included

- `plugins/hermes/headroom_retrieve/` — `plugin.yaml` + `__init__.py`
(single-file, httpx, ~100 lines)
- `plugins/hermes/README.md` — install steps and proxy-side
recommendations

## Design notes

- **Both marker formats covered**: Kompress emits `[N items compressed
... hash=KEY]`, SmartCrusher's opaque-blob walker emits
`<<ccr:HASH[,KIND,SIZE]>>`. The tool description teaches both and
explicitly says markers are NOT file paths; the handler normalizes
whole-marker input (`<<ccr:abc,base64,4.5KB>>` → `abc`).
- **Re-compression loop guard**: retrieved originals travel back through
the proxy on the next request and get re-compressed into a fresh marker,
looping forever. README documents
`HEADROOM_EXCLUDE_TOOLS=read_file,headroom_retrieve` as the fix (Hermes
tool names don't match `DEFAULT_EXCLUDE_TOOLS`, which targets Claude
Code's `Read`/`Grep`/...).
- **Actionable failure modes**: 404 (TTL expired / proxy restarted) and
connection-refused both return guidance to re-run the original command
rather than retry.

## Relationship to existing PRs

Complementary to #707 / #556 (`headroom wrap hermes`, proxy-side): those
launch/route Hermes through the proxy; this gives the agent the
retrieval capability once it's routed. Notably #707 disables CCR tool
injection in Hermes mode precisely because Hermes must register its own
tool — this plugin is that registration.

## Testing

Running in production on macOS (headroom 0.23.0, pipx) and Linux
(0.22.4, systemd) for a day. Verified: fresh-marker retrieval roundtrip,
whole-marker hash normalization (6 input shapes), expired-hash 404
messaging, proxy-down messaging, and end-to-end via live Hermes sessions
(fresh ≥500B `read_file` returns original with the documented exclude
config).

Closes #796

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: akb4q <zhunyunjiang@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

plugins/hermes/README.md

@@ -0,0 +1,66 @@
+# Hermes Agent Integration
+
+CCR retrieval plugin for [Hermes Agent](https://hermes-agent.nousresearch.com/) (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:
+
+   ```bash
+   mkdir -p ~/.hermes/plugins
+   cp -r headroom_retrieve ~/.hermes/plugins/
+   ```
+
+2. Enable it in `~/.hermes/config.yaml`:
+
+   ```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).
+
+## 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:
+
+```bash
+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`.
+- Optional `query` parameter filters very large results via the proxy's BM25 search.
+- 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.

plugins/hermes/headroom_retrieve/__init__.py

@@ -0,0 +1,102 @@
+"""Headroom CCR retrieve plugin.
+
+The headroom proxy (127.0.0.1:8787) compresses large tool outputs in LLM
+requests, replacing them with markers like ``[N items compressed ...
+hash=abc123]`` or ``<<ccr:abc123>>``. This plugin gives Hermes a tool to fetch the original
+uncompressed content back from the proxy's compression store, so compressed
+markers are no longer a black box.
+
+Storage is in-memory on the proxy side with a TTL — expired or
+post-proxy-restart hashes return 404 and the tool reports that clearly.
+"""
+
+from __future__ import annotations
+
+import httpx
+from tools.registry import tool_error, tool_result
+
+_PROXY_URL = "http://127.0.0.1:8787"
+
+HEADROOM_RETRIEVE_SCHEMA = {
+    "name": "headroom_retrieve",
+    "description": (
+        "Retrieve the original uncompressed content behind a headroom "
+        "compression marker. Markers look like "
+        "'[N items compressed ... hash=abc123]' OR '<<ccr:abc123>>' OR "
+        "'<<ccr:abc123,base64,4.5KB>>'. They are NOT file paths — never try "
+        "to cat/read them. When you see one in a tool result or in "
+        "conversation history, call this tool with the hash (the hex string "
+        "after 'hash=' or 'ccr:') to read the full original content instead "
+        "of guessing or re-running the command. For very large results, pass "
+        "the optional 'query' to filter to the relevant parts (BM25 search). "
+        "Content expires after a TTL — if expired, re-run the original "
+        "command instead."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "hash": {
+                "type": "string",
+                "description": "Hash from the compression marker, e.g. 'abc123' from '[... hash=abc123]' or '<<ccr:abc123>>'",
+            },
+            "query": {
+                "type": "string",
+                "description": "Optional search query to filter large results to relevant items",
+            },
+        },
+        "required": ["hash"],
+    },
+}
+
+
+def _handle_headroom_retrieve(args: dict, **kw) -> str:
+    hash_key = str(args.get("hash") or "").strip()
+    # Tolerate the model passing the whole marker instead of the bare hash:
+    # '<<ccr:abc123,base64,4.5KB>>' / 'ccr:abc123' / 'hash=abc123' -> 'abc123'
+    hash_key = hash_key.strip("<>").removeprefix("ccr:").removeprefix("hash=")
+    hash_key = hash_key.split(",")[0].strip()
+    if not hash_key:
+        return tool_error(
+            "hash is required (from a '[... hash=abc123]' or '<<ccr:abc123>>' marker)"
+        )
+
+    payload: dict = {"hash": hash_key}
+    query = str(args.get("query") or "").strip()
+    if query:
+        payload["query"] = query
+
+    try:
+        resp = httpx.post(f"{_PROXY_URL}/v1/retrieve", json=payload, timeout=15)
+    except httpx.HTTPError as exc:
+        return tool_error(
+            f"headroom proxy unreachable at {_PROXY_URL} ({type(exc).__name__}). "
+            "The proxy may be down; re-run the original command to get the data."
+        )
+
+    if resp.status_code == 404:
+        return tool_error(
+            "Content not found: expired (TTL passed) or proxy restarted. "
+            "Re-run the original command to regenerate the data."
+        )
+    if resp.status_code != 200:
+        return tool_error(f"headroom proxy returned HTTP {resp.status_code}: {resp.text[:200]}")
+
+    data = resp.json()
+    return tool_result(
+        {
+            "original_content": data.get("original_content", ""),
+            "original_tokens": data.get("original_tokens"),
+            "tool_name": data.get("tool_name"),
+        }
+    )
+
+
+def register(ctx) -> None:
+    """Register the headroom_retrieve tool. Called by the plugin loader."""
+    ctx.register_tool(
+        name="headroom_retrieve",
+        toolset="headroom",
+        schema=HEADROOM_RETRIEVE_SCHEMA,
+        handler=_handle_headroom_retrieve,
+        emoji="🗜️",
+    )

plugins/hermes/headroom_retrieve/plugin.yaml

@@ -0,0 +1,6 @@
+name: headroom_retrieve
+version: 1.0.0
+description: "Retrieve original content compressed by the headroom proxy (CCR markers)"
+author: akb4q
+provides_tools:
+  - headroom_retrieve

tests/test_plugins_hermes_retrieve.py

@@ -0,0 +1,183 @@
+"""Tests for the Hermes headroom_retrieve plugin (plugins/hermes/).
+
+The plugin targets the Hermes Agent runtime, which provides a
+``tools.registry`` module. That module does not exist inside the headroom
+codebase, so these tests stub it before loading the plugin file directly
+via importlib.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+import types
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+
+PLUGIN_PATH = (
+    Path(__file__).resolve().parent.parent
+    / "plugins"
+    / "hermes"
+    / "headroom_retrieve"
+    / "__init__.py"
+)
+
+
+def _load_plugin() -> types.ModuleType:
+    """Load the plugin file with a stubbed Hermes ``tools.registry``."""
+    registry = types.ModuleType("tools.registry")
+    registry.tool_error = lambda msg: json.dumps({"error": msg})  # type: ignore[attr-defined]
+    registry.tool_result = lambda data: json.dumps({"result": data})  # type: ignore[attr-defined]
+    tools_pkg = types.ModuleType("tools")
+    tools_pkg.registry = registry  # type: ignore[attr-defined]
+    sys.modules.setdefault("tools", tools_pkg)
+    sys.modules["tools.registry"] = registry
+
+    spec = importlib.util.spec_from_file_location("hermes_headroom_retrieve", PLUGIN_PATH)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int, payload: dict[str, Any] | None = None) -> None:
+        self.status_code = status_code
+        self._payload = payload or {}
+        self.text = json.dumps(self._payload)
+
+    def json(self) -> dict[str, Any]:
+        return self._payload
+
+
+@pytest.fixture()
+def plugin() -> types.ModuleType:
+    return _load_plugin()
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("abc123", "abc123"),
+        ("ccr:abc123", "abc123"),
+        ("<<ccr:abc123>>", "abc123"),
+        ("<<ccr:abc123,base64,4.5KB>>", "abc123"),
+        ("hash=abc123", "abc123"),
+        ("  <<ccr:abc123>>  ", "abc123"),
+    ],
+)
+def test_handler_normalizes_marker_shapes_to_bare_hash(
+    plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch, raw: str, expected: str
+) -> None:
+    # Arrange
+    seen: dict[str, Any] = {}
+
+    def fake_post(url: str, json: dict[str, Any], timeout: int) -> _FakeResponse:  # noqa: A002
+        seen["payload"] = json
+        return _FakeResponse(200, {"original_content": "data", "original_tokens": 1})
+
+    monkeypatch.setattr(plugin.httpx, "post", fake_post)
+
+    # Act
+    plugin._handle_headroom_retrieve({"hash": raw})
+
+    # Assert
+    assert seen["payload"]["hash"] == expected
+
+
+def test_handler_passes_optional_query_through(
+    plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Arrange
+    seen: dict[str, Any] = {}
+
+    def fake_post(url: str, json: dict[str, Any], timeout: int) -> _FakeResponse:  # noqa: A002
+        seen["payload"] = json
+        return _FakeResponse(200, {"original_content": "data"})
+
+    monkeypatch.setattr(plugin.httpx, "post", fake_post)
+
+    # Act
+    plugin._handle_headroom_retrieve({"hash": "abc123", "query": "error lines"})
+
+    # Assert
+    assert seen["payload"] == {"hash": "abc123", "query": "error lines"}
+
+
+def test_handler_returns_original_content_on_200(
+    plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Arrange
+    payload = {"original_content": "full text", "original_tokens": 42, "tool_name": "read_file"}
+    monkeypatch.setattr(plugin.httpx, "post", lambda *a, **kw: _FakeResponse(200, payload))
+
+    # Act
+    out = json.loads(plugin._handle_headroom_retrieve({"hash": "abc123"}))
+
+    # Assert
+    assert out["result"]["original_content"] == "full text"
+    assert out["result"]["original_tokens"] == 42
+    assert out["result"]["tool_name"] == "read_file"
+
+
+def test_handler_reports_expired_entry_on_404(
+    plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Arrange
+    monkeypatch.setattr(plugin.httpx, "post", lambda *a, **kw: _FakeResponse(404))
+
+    # Act
+    out = json.loads(plugin._handle_headroom_retrieve({"hash": "deadbeef"}))
+
+    # Assert: actionable message, not a bare error
+    assert "expired" in out["error"]
+    assert "re-run" in out["error"].lower()
+
+
+def test_handler_reports_unreachable_proxy_on_connection_error(
+    plugin: types.ModuleType, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Arrange
+    def raise_connect_error(*a: Any, **kw: Any) -> None:
+        raise httpx.ConnectError("connection refused")
+
+    monkeypatch.setattr(plugin.httpx, "post", raise_connect_error)
+
+    # Act
+    out = json.loads(plugin._handle_headroom_retrieve({"hash": "abc123"}))
+
+    # Assert
+    assert "unreachable" in out["error"]
+
+
+def test_handler_rejects_empty_hash(plugin: types.ModuleType) -> None:
+    # Act
+    out = json.loads(plugin._handle_headroom_retrieve({"hash": "   "}))
+
+    # Assert
+    assert "required" in out["error"]
+
+
+def test_register_exposes_tool_with_marker_aware_schema(plugin: types.ModuleType) -> None:
+    # Arrange
+    registered: dict[str, Any] = {}
+
+    class FakeCtx:
+        def register_tool(self, **kwargs: Any) -> None:
+            registered.update(kwargs)
+
+    # Act
+    plugin.register(FakeCtx())
+
+    # Assert
+    assert registered["name"] == "headroom_retrieve"
+    assert registered["toolset"] == "headroom"
+    assert registered["schema"]["parameters"]["required"] == ["hash"]
+    # The description must teach both marker formats so the model recognizes them.
+    description = registered["schema"]["description"]
+    assert "<<ccr:" in description
+    assert "hash=" in description