Commit Graph
3 Commits
Author SHA1 Message Date
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
Tejas Chopra c2fc4d3753 fix(ccr): make headroom_retrieve a hash-only full-content lookup (#1532)
The optional `query` parameter on headroom_retrieve routed retrieval
through CompressionStore.search(), which BM25-scored the items inside a
single cached blob and dropped everything below a 0.3 relevance floor.
On small per-blob corpora with conversational queries this returned an
empty result the large majority of the time, so the LLM saw "nothing
found" for content that was actually present — pushing users to turn
compression off entirely.

Retrieval is fundamentally a hash lookup (this already matches the Rust
proxy's CCR store, which is put/get only — "no BM25 search"). Remove the
query/search path end to end and always return the full original
content:

Core (Python proxy):
- tool schemas (anthropic/openai/google) drop the `query` property
- parse_tool_call returns the hash (str | None) instead of (hash, query)
- response handler, proxy POST/GET/tool-call handlers, the MCP retrieve
tool, and the streaming feedback recorders retrieve by hash only
- proactive context-tracker expansion always restores full content
- delete CompressionStore.search() and its BM25 machinery (the bm25
module stays — it is still used by relevance/)
- CCRToolCall.query, CCRToolResult.was_search, and
ExpansionRecommendation.expand_full/search_query are removed

Plugins (advertised a now-defunct query param to the LLM):
- hermes (Python), openclaw + opencode (TypeScript) retrieve tools drop
`query` from their schemas, signatures, request URLs, and tests

Benchmarks/docs:
- ccr_regression + adversarial benchmarks switch from store.search() to
full hash retrieval (search input-injection tests repurposed to the
hash, the only remaining input surface)
- wiki/ARCHITECTURE.md, wiki/ccr.md, docs/content/docs/ccr.mdx,
config.py and store docstrings updated to describe hash-only retrieval

Tests updated to assert full-content retrieval and guard the removed
surface; the full CCR/proxy/store/TOIN suite passes. ruff + mypy clean.

## Description

<!-- Briefly explain the change and why it is needed. -->

Closes #

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- 

## Testing

<!-- Check what you actually ran, then paste the real command output
below. -->

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
# Paste relevant command output or artifact links here
```

## Real Behavior Proof

- Environment:
- Exact command / steps:
- Observed result:
- Not tested:

## Review Readiness

- [ ] I have performed a self-review
- [ ] This PR is ready for human review

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Screenshots (if applicable)

Add screenshots to help explain your changes.

## Additional Notes

<!-- Mention any N/A checklist items, tradeoffs, follow-ups, or
maintainer context. -->
2026-06-28 10:32:43 -07:00
058bcedab8 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>
2026-06-11 18:43:10 -05:00