Files
headroom/tests/test_tool_name_aliases.py
RyrenzandJD Davis 1b9d296c19 fix(proxy): preserve Cline headroom__headroom_retrieve results from recompression (#4586)
## Description

Cline names MCP tools `<server>__<tool>`, so with the default `headroom`
server the retrieval tool reaches the proxy as
`headroom__headroom_retrieve`. `_tool_name_aliases()` in
`headroom/config.py` maps OpenCode's single-underscore
`headroom_headroom_retrieve` and the `mcp__` / `mcp_` wrappers to
`headroom_retrieve`, but not the double-underscore form.
`is_tool_excluded()` therefore returns `False` for it, so both the
ContentRouter `ccr_retrieve` guard and the OpenAI handler's
`headroom_retrieve_call_ids` miss the call. The retrieved content then
goes through normal compression again, which produces the retrieval loop
described in the issue.

This follows #3782: the double-underscore spelling now gets the same
exact-name alias as the single-underscore one. I kept it an exact match
on the default server name, not a generic `*__headroom_retrieve` suffix
rule, so the change doesn't widen matching for other exclusion entries.
The content-based guard suggested in the issue (detecting a `hash` +
`original_content` payload whatever the tool name is) is a larger
behavior change, and this PR leaves it out.

Closes #4585

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `headroom/config.py`: `_tool_name_aliases()` now maps
`headroom__headroom_retrieve` (case-insensitive) to `headroom_retrieve`,
alongside the existing OpenCode spelling.
- `tests/test_tool_name_aliases.py`: adds the Cline spelling to the
parametrized exclusion test.
- `tests/test_transforms/test_content_router_ccr_retrieve_exemption.py`:
new test that sends an OpenAI-shaped `headroom__headroom_retrieve` call
and result through `ContentRouter.apply()` and asserts the result passes
through unchanged with `router:excluded:ccr_retrieve`.

## Testing

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

Both new test cases fail on unmodified `main` (`2 failed, 16 passed`)
and pass with the fix. Lint, format and mypy were run on the changed
files only.

### Test Output

```text
$ .venv/bin/python -m pytest tests/test_tool_name_aliases.py tests/test_transforms/test_content_router_ccr_retrieve_exemption.py tests/test_ccr_tool_injection_cache_stability.py tests/test_hermes_tool_call_unwrap.py tests/test_openai_responses_compression_units.py -q -p no:cacheprovider -o addopts=
125 passed, 1 warning in 6.16s

# same two files on unmodified main (headroom/config.py reverted):
FAILED tests/test_tool_name_aliases.py::test_retrieve_tool_aliases_are_excluded[headroom__headroom_retrieve]
FAILED tests/test_transforms/test_content_router_ccr_retrieve_exemption.py::TestContentRouterCcrRetrieveExemption::test_cline_server_tool_mcp_name_not_recompressed
2 failed, 16 passed in 3.38s

$ .venv/bin/ruff check headroom/config.py tests/test_tool_name_aliases.py tests/test_transforms/test_content_router_ccr_retrieve_exemption.py
All checks passed!
$ .venv/bin/ruff format --check headroom/config.py tests/test_tool_name_aliases.py tests/test_transforms/test_content_router_ccr_retrieve_exemption.py
3 files already formatted
$ .venv/bin/mypy headroom/config.py --ignore-missing-imports
Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: Ubuntu 26.04 x86_64, Python 3.12, offline, no provider
- Exact command / steps: `.venv/bin/python proof.py`, a standalone
script outside pytest. It prints `is_tool_excluded(name,
DEFAULT_EXCLUDE_TOOLS)` for the three retrieve spellings, then runs
`ContentRouter(ContentRouterConfig(min_section_tokens=10)).apply()` on
an OpenAI-shaped assistant `tool_calls` entry named
`headroom__headroom_retrieve` followed by a 3,680-char JSON tool result,
and prints the output size and the transforms that were applied.
- Observed result: on unmodified `main`, the Cline name is not excluded
and the retrieve result is crushed:

  ```text
  is_tool_excluded('headroom_retrieve') = True
  is_tool_excluded('headroom_headroom_retrieve') = True
  is_tool_excluded('headroom__headroom_retrieve') = False
input chars=3680 output chars=1861 unchanged=False new_ccr_marker=False
  transforms: ['router:smart_crusher:0.40']
  ```

  With this branch, the result passes through byte-for-byte:

  ```text
  is_tool_excluded('headroom_retrieve') = True
  is_tool_excluded('headroom_headroom_retrieve') = True
  is_tool_excluded('headroom__headroom_retrieve') = True
  input chars=3680 output chars=3680 unchanged=True new_ccr_marker=False
  transforms: ['router:excluded:ccr_retrieve']
  ```

- Not tested: a live Cline session and real provider traffic through the
proxy, and Cline's hashed-name fallback for tool names over 64
characters (not reachable with the default `headroom` server name, which
gives a 27-character tool name).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; this is the default tool-exclusion
code path, with no flag
- Minimum rollout channel: stable; the only effect is that one more
tool-name spelling is excluded from compression
- Stable/default behavior changed: yes, but only for tools named exactly
`headroom__headroom_retrieve` (case-insensitive), whose results are now
kept verbatim instead of compressed
- Kill switch / disable path: none added; the change is a one-line alias
in `_tool_name_aliases()`
- Unsafe override required: no
- Qualification impact: none; other tool names keep their current
exclusion behavior
- Rollback path: revert this commit

## 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/4586"
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 -->

Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-04 08:41:57 -06:00

27 lines
764 B
Python

"""Tests for normalizing client-specific tool names."""
from __future__ import annotations
import pytest
from headroom.config import DEFAULT_EXCLUDE_TOOLS, is_tool_excluded
@pytest.mark.parametrize(
"name",
[
"headroom_retrieve",
"mcp__headroom__headroom_retrieve",
"mcp_headroom_headroom_retrieve",
"headroom_headroom_retrieve",
"headroom__headroom_retrieve",
],
)
def test_retrieve_tool_aliases_are_excluded(name: str) -> None:
assert is_tool_excluded(name, DEFAULT_EXCLUDE_TOOLS)
def test_unrelated_underscored_tool_names_are_not_excluded() -> None:
assert not is_tool_excluded("my_headroom_retrieve", DEFAULT_EXCLUDE_TOOLS)
assert not is_tool_excluded("other_Read", DEFAULT_EXCLUDE_TOOLS)