1 commit

Author	SHA1	Message	Date
pgjh	a97b82413b	fix(proxy): unwrap Hermes tool_call bridge in tool name map (#2717) ... ## Description Hermes Agent (NousResearch/hermes-agent) loads on-demand ("deferred") tools via a `tool_search` → `tool_describe` → `tool_call` indirection. On the wire, the emitted tool call is named **`tool_call`**, and the REAL tool name lives inside the arguments payload: ```json { "id": "call_abc123", "type": "function", "function": { "name": "tool_call", "arguments": "{\"name\": \"read_file\", \"arguments\": {\"path\": \"/etc/hostname\"}}" } } ``` `ContentRouter._build_tool_name_map` only reads `tool_calls[].function.name`, so it maps `tool_call` → `"tool_call"` instead of the real tool name. **Consequence**: `HEADROOM_EXCLUDE_TOOLS` / `HEADROOM_PROTECT_TOOL_RESULTS` silently no-op for **ALL** deferred tools (`read_file`, `write_file`, `search_files`, `mcp__*`, `headroom_retrieve`, etc.). Their outputs get lossy-compressed even when explicitly whitelisted, and `headroom_retrieve` falls into an endless re-compression loop (`<<ccr:hash>>` → retrieve → re-compress → `original_tokens: 0`). ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) ## Changes Made Add an `unwrap_tool_call_name(name, arguments)` helper in `config.py` (beside the existing `_tool_name_aliases`) and apply it at the **3 sites** where the tool_call_id → tool_name map is built: 1. **OpenAI chat path** — `content_router.py` `_build_tool_name_map` (`tool_calls[].function`) 2. **Anthropic path** — `content_router.py` `_build_tool_name_map` (`tool_use` blocks) 3. **Responses API path** — `openai.py` `_compress_openai_responses_live_text_units_with_router` (`function_call` items) The helper: - Passes non-wrapper names through unchanged - Parses the arguments payload (JSON string or dict) and extracts the inner `name` - Fails open (returns the wrapper name) on malformed/unparseable payloads — safe for all other clients After unwrap, `is_tool_excluded()`/protect-list matching sees the real tool name, so whitelists work for deferred tools exactly as they already did for classic tools. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] New tests added for new functionality - [x] Manual testing performed `tests/test_hermes_tool_call_unwrap.py` — **14 tests**, all pass: - Helper unit tests: passthrough, None/bad-JSON/missing-name fail-open, unwrap (web_search, read_file, mcp__*, dict-args form) - Whitelist activation: unwrapped name + `is_tool_excluded` against `DEFAULT_EXCLUDE_TOOLS` - Integration: `_build_tool_name_map` with OpenAI-format `tool_call` wrapper and Anthropic-format `tool_use` wrapper - Regression guard: documents that `tool_call` itself is NOT in `DEFAULT_EXCLUDE_TOOLS` (the pre-fix failure mode) ### Test Output ```text $ uv run pytest tests/test_hermes_tool_call_unwrap.py tests/test_content_router_exclude_tools.py tests/test_config.py -q 56 passed in 1.24s $ uv run ruff check . All checks passed! $ uv run ruff format --check . All checks passed! ``` ## Real Behavior Proof - Environment: Ubuntu 24.04 (kernel 7.0.0-28), Python 3.11.15, headroom built from source at `v0.33.0-5-g6d5516dc` via `uv sync` (maturin), Rust 1.95.0 toolchain. Headroom proxy 0.34.0-dev running as a systemd user service, `HEADROOM_PROTECT_TOOL_RESULTS=read_file,headroom_retrieve`, mode=token. Upstream: local new-api-compatible gateway (deepseek-v4-pro / GLM-5.2). - Exact command / steps: Client = Hermes Agent (fresh session via `hermes chat -q --provider newapi2`, traffic routed through the headroom proxy at 127.0.0.1:8788). Trigger a deferred `read_file` tool call and observe `/stats` → `recent_requests`. - Observed result: After fix, live traffic evidence shows request `hr_1785683282_000016` (GLM-5.2 session) with `transforms_applied: ["router:excluded:tool", "openai:chat:tool_schema_compaction"]` — the deferred `read_file` tool was recognized and excluded (whitelist hit), 21918 → 17218 input tokens. Before the fix this request showed no `router:excluded:tool` for deferred tools — they were compressed. E2E unit-level proof (`test_build_tool_name_map_exclusion_after_unwrap` + standalone pipeline run): a `tool_call`-wrapped `read_file` output (~9KB, 100 lines) passed through `ContentRouter.apply()` **verbatim** (byte-identical), while a non-whitelisted tool (Bash) in the same pipeline was compressed — proving the whitelist now works and the pipeline still compresses normally. - Not tested: Anthropic native clients (Claude Code) and Responses-API clients (Codex) end-to-end — the patch sites for those paths are covered by unit tests only. No new dependencies; no public API changes. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes No documentation changes needed (no public API change; behavior is internal to the proxy tool-name map). Follow-up: end-to-end verification with Anthropic/Responses-API clients once maintainers can run the proxy CI on those paths. Co-authored-by: pgjh <pgjh@users.noreply.github.com>	2026-08-04 22:16:46 -05:00