Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(plugins): Hermes agent headroom_retrieve plugin (#824)
jimu058bcedab838
diff --git a/plugins/hermes/README.md b/plugins/hermes/README.mdnew file mode 100644index 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+<<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.diff --git a/plugins/hermes/headroom_retrieve/__init__.py b/plugins/hermes/headroom_retrieve/__init__.pynew file mode 100644index 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 ``<<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="🗜️",+ )diff --git a/plugins/hermes/headroom_retrieve/plugin.yaml b/plugins/hermes/headroom_retrieve/plugin.yamlnew file mode 100644index 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_retrievediff --git a/tests/test_plugins_hermes_retrieve.py b/tests/test_plugins_hermes_retrieve.pynew file mode 100644index 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+++def plugin() -> types.ModuleType:+ return _load_plugin()+++ ("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