From 058bcedab838f3b34ac8e38853e1924329efd820 Mon Sep 17 00:00:00 2001 From: jimu Date: Fri, 12 Jun 2026 07:43:10 +0800 Subject: [PATCH] feat(plugins): Hermes agent headroom_retrieve plugin (#824) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 `<>`. The tool description teaches both and explicitly says markers are NOT file paths; the handler normalizes whole-marker input (`<>` → `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 Co-authored-by: Claude Fable 5 --- plugins/hermes/README.md | 66 +++++++ plugins/hermes/headroom_retrieve/__init__.py | 102 +++++++++++ plugins/hermes/headroom_retrieve/plugin.yaml | 6 + tests/test_plugins_hermes_retrieve.py | 183 +++++++++++++++++++ 4 files changed, 357 insertions(+) create mode 100644 plugins/hermes/README.md create mode 100644 plugins/hermes/headroom_retrieve/__init__.py create mode 100644 plugins/hermes/headroom_retrieve/plugin.yaml create mode 100644 tests/test_plugins_hermes_retrieve.py diff --git a/plugins/hermes/README.md b/plugins/hermes/README.md new file mode 100644 index 000000000..6f2ab2be5 --- /dev/null +++ b/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 +<> / <> # 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`, 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. diff --git a/plugins/hermes/headroom_retrieve/__init__.py b/plugins/hermes/headroom_retrieve/__init__.py new file mode 100644 index 000000000..812b0e12b --- /dev/null +++ b/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 ``<>``. 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 '<>' OR " + "'<>'. 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 '<>'", + }, + "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' / '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 '<>' 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="🗜️", + ) diff --git a/plugins/hermes/headroom_retrieve/plugin.yaml b/plugins/hermes/headroom_retrieve/plugin.yaml new file mode 100644 index 000000000..45f60c2ab --- /dev/null +++ b/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 diff --git a/tests/test_plugins_hermes_retrieve.py b/tests/test_plugins_hermes_retrieve.py new file mode 100644 index 000000000..226e2d198 --- /dev/null +++ b/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"), + ("<>", "abc123"), + ("<>", "abc123"), + ("hash=abc123", "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 "<