fix(ccr): recognize client-owned MCP retrieval aliases (#4165)

## Description

Fixes #4159.

OpenCode exposes `headroom_headroom_retrieve`, but the proxy only checks
the bare `headroom_retrieve` when deciding whether the client already
owns retrieval. It therefore adds a second, unavailable client tool.
Retrieval-only proxy turns can be intercepted internally; mixed
retrieval + Read turns are forwarded to the client, which cannot execute
the bare spelling.

## Type of Change

- [x] Bug fix
- [x] Documentation update

## Changes Made

- Share one ownership selector between session-sticky injection and the
per-request `CCRToolInjector` fallback. Accept the bare canonical name
and the three supported default-Headroom-server client spellings.
- Do not treat another MCP server's `headroom_retrieve` suffix as
ownership of Headroom's cache. Existing broader compression-exclusion
matching is unchanged.
- Optional system instructions use the executable registered retrieval
name in the legacy path and both Anthropic/OpenAI handlers.
- Preserve client-owned aliases and bare-only proxy interception; do not
alter mixed-tool response handling or add execution of client tools.
- Add namespace/provider regressions across cold, compressed and later
turns, plus real-store instruction and foreign-server boundaries.
- Delete the incidental tool-description-size assertion and
error-message wording pin, retaining real eager/lazy/cache-stability
validation.
- Document default-server ownership, alias-only forwarding and
mixed-call behavior explicitly.

## Testing

- [x] Relevant CCR/API tests pass: 161 cases across the seven suites
below
- [x] Changed Python source/test Ruff format and check pass
- [x] Failing-before/passing-after behavioral regressions added
- [x] Actual CLI/HTTP/native before-and-after smoke performed

### Test Output

All **6** initial alias/provider regressions fail against exact upstream
main `976aa714ef3e19174dc0cb586cee7b20d064e4ef` because unavailable bare
retrieval is injected. All **10** first review regressions and **2**
additional actual-API regressions fail against immutable first-PR commit
`7601252be7e8b02297e342e2775bb153927e2fe9`: instructions name an
unavailable tool, or a foreign MCP server displaces proxy retrieval.
Current fixed result: **161 passed, 1 existing Starlette TestClient
deprecation warning** across:

```text
tests/test_ccr_tool_injection_cache_stability.py
tests/test_ccr_tool_always_on.py
tests/test_ccr_tool_injection.py
tests/test_issue_728_empty_tools_injection.py
tests/test_corrupt_golden_bytes_recovery.py
tests/test_proxy_anthropic_cache_stability.py
tests/test_proxy_openai_cache_stability.py
```

Ruff format/check passed for the four changed Python sources and three
regression files. A genuine-module-preloaded, coverage-instrumented CCR
run passed all 110 cases (four warnings); an additional instrumented API
run passed both new API regressions and measured both changed handler
instruction calls as executed. Import-time coverage is incomplete in
those local runs, so they are not whole-package or CI patch-coverage
claims. Whole-repository pytest and whole-package mypy are not claimed
by these scoped results.

## Real Behavior Proof

- Environment: Linux x86_64, Python 3.13.14; genuine installed
development/proxy extras and editable Rust extension, actual ONNX
Runtime 1.26.0 via `ORT_DYLIB_PATH`. Independent baseline/fixed
worktrees. Beacon off, isolated settings, stateless proxy, no live
credentials. Provider is a controlled local Anthropic-shaped HTTP
upstream; request model string is `claude-sonnet-4-20250514`, not a live
model run.

- Exact command / steps: start `headroom proxy --port 18858` for
baseline and `--port 18859` for fixed source, each with
`--anthropic-api-url http://127.0.0.1:45111` and:

```text
--stateless --no-cache --no-rate-limit --no-subscription-tracking
--disable-kompress --disable-kompress-fallback --no-read-lifecycle --no-telemetry
```

Optimization and CCR remain enabled. Both genuine CLI startups report
`event=rust_core_loaded`. POST the same `/v1/messages` request to each
with model above, `max_tokens: 128`, `system: "Use the available
tools."`, user text `Retrieve the original compressed data and read the
related file.`, and these client tool schemas:

```json
[
  {"name":"headroom_headroom_retrieve","description":"Retrieve original Headroom content through the client MCP server","input_schema":{"type":"object","properties":{"hash":{"type":"string"}},"required":["hash"]}},
  {"name":"Read","description":"Read a local file","input_schema":{"type":"object","properties":{"file_path":{"type":"string"}},"required":["file_path"]}}
]
```

The controlled upstream observes the actual advertised tools, selects
bare retrieval if advertised (otherwise the available alias), and
returns a mixed retrieval + Read response.

**Observed before:** upstream tools are `Read`,
`headroom_headroom_retrieve`, **`headroom_retrieve`**. HTTP 200 forwards
mixed `headroom_retrieve` + `Read`, leaving one returned tool
unavailable in the client's registry.

- Observed result: after the fix, upstream tools are only `Read`,
`headroom_headroom_retrieve`. HTTP 200 forwards mixed
**`headroom_headroom_retrieve`** + `Read`; zero unavailable returned
names. No mixed-call suppression or response rewriting hides the
problem.

- Not tested: live Anthropic, installed OpenCode end-to-end, actual CCR
hash/payload recovery, Windows or native Gemini HTTP. Per-request
fallback is exercised directly by regressions. Controlled-upstream
behavior alone is not offered as proof: this ran the real baseline/fixed
proxy CLI, HTTP path and native extension.

### Additional review behavior proof

The first PR SHA and corrected source each ran the actual proxy app
through its full lifespan, with the genuine native extension loaded,
actual `CompressionStore` and real HTTP to a controlled upstream at
`127.0.0.1:45112`. Requests entered the genuine Anthropic and OpenAI
ASGI routes, not patched handlers; this additional check was not an
external CLI socket or live-provider run.

Construct `ProxyConfig` with `ccr_inject_system_instructions=True`,
`stateless=True`, no caching/rate limiting/subscription tracking/read
lifecycle/Kompress, Anthropic URL `http://127.0.0.1:45112`, and OpenAI
URL `http://127.0.0.1:45112/v1`. After startup, store
original/compressed content in the actual in-memory store and use its
returned hash in `<<ccr:HASH 1_rows_offloaded>>`. Send a valid assistant
tool call and matching tool result to each provider endpoint, once with
only `headroom_headroom_retrieve` registered and once with only
`mcp__other__headroom_retrieve` registered. Anthropic uses
tool-use/tool-result blocks and model `claude-sonnet-4-20250514`; OpenAI
uses function tool-calls/tool messages and model `gpt-4o`. The upstream
records advertised names and names invoked by the actual injected system
instructions, then returns a normal final text response.

All eight before/after requests returned HTTP 200. Before: both
providers instructed bare `headroom_retrieve` while neither registry
contained it. After: the Headroom alias is retained alone and
instructions invoke it; a foreign server's tool is retained alongside
proxy-owned bare retrieval and instructions invoke the bare tool. **Zero
unavailable instruction names** in all four corrected requests. The
upstream and both apps were stopped afterwards.

The permanent API regressions reuse the existing full-lifespan provider
`TestClient` fixtures and a real isolated in-memory store. Only the
upstream response boundary supplies fixed provider-shaped JSON; the CCR
injector, instruction generation and ownership selector are real. Both
tests fail on the first PR SHA because the instructions name unavailable
bare retrieval, then pass after the fix. They assert executable-name and
real-hash invariants, not that a helper received forwarded arguments.
Scoped coverage measured the previously untested instruction calls in
both handlers as executed.

## Runtime Rollout Safety

- Rollout-managed feature(s): existing CCR tool-injection paths and
opt-in retrieval instructions; tool ownership and instruction naming
only.
- Minimum rollout channel: unchanged; no feature is enabled by this
patch.
- Stable/default behavior changed: stop injecting a duplicate bare
schema when the client already owns a supported retrieval alias.
- Kill switch / disable path: existing controls unchanged; no new
switch.
- Unsafe override required: none.
- Qualification impact: alias/provider/cold-to-compressed regressions,
foreign-server and actual-store boundaries, CLI/native proof and
both-provider ASGI/native/HTTP proof above; no widened rollout.
- Rollback path: revert this Python bug fix.

## Review Readiness

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

## Checklist

- [x] One shared ownership selector, broader compression exclusions
unchanged, no new dependency
- [x] Documentation updated
- [x] Consumer-visible failing-before/passing-after regressions included
- [x] Relevant new and existing tests pass locally
- [x] Did not edit generated `CHANGELOG.md`

## Mandatory Local Push Gates

Normal `git push fork fix/issue-4159-client-retrieval-alias-20261011`
executed the installed pre-push hook and **`make ci-precheck` passed**:

- `cargo fmt --all -- --check`
- `cargo clippy --workspace -- -D warnings`
- `cargo test --workspace`
- Genuine editable Rust extension build, install and import verification
- Critical Python/native parity suite: **177 passed, 4 skipped, 1
warning**
- Conventional commit validation through commitlint

The warning is the existing no-client Anthropic tokenizer approximation
reported by `test_relevance_with_query_context`; it was not suppressed.
The earlier cold-build push timed out. Retrying with the real shared
Cargo
build cache and two build jobs completed all gates and pushed normally;
no bypass flag or skipped hook was used.

The review update `440fd96aaa11c0ea9263d9628ccc2b5f8b3865d4` also
passed every normal pre-push gate above, including 177 critical Python
tests. This run used `RUST_TEST_THREADS=2`: the preceding
default-parallel
attempt failed the unchanged native
`expired_get_does_not_wipe_concurrent_refresh` test's final-live
assertion
with a 20 ms TTL. Baseline/current native source hashes are identical.
No Rust fix is claimed; no tests or gates were filtered or bypassed.

The API regression update `c5c36ba0e7074cbd815498d00ee8f394bd7287bc`
again passed all normal local push gates above with the same bounded
test/build concurrency, genuine native rebuild/import and 177 critical
Python tests. The two additional API regressions and complete
seven-suite
161-test run are separate measured verification, not mocked CCR
plumbing.

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Mansurshakh Japarov
2026-10-24 08:45:20 -07:00
committed by GitHub
co-authored by JD Davis
parent bebe24c5ff
commit 89545fbdf3
7 changed files with 171 additions and 25 deletions
+16 -1
View File
@@ -62,6 +62,19 @@ Headroom injects a `headroom_retrieve` tool into the LLM's available tools:
The LLM sees this tool alongside your application's tools and can call it whenever the compressed data is insufficient.
If your client already registers retrieval through MCP, Headroom keeps that
client-owned tool instead of adding a second bare `headroom_retrieve`.
Supported spellings include OpenCode's `headroom_headroom_retrieve` and MCP
wrappers such as `mcp__headroom__headroom_retrieve` and
`mcp_Headroom_headroom_retrieve`. The same rule applies to session-aware
injection and the per-request fallback, so Headroom does not advertise an
unavailable bare retrieval tool alongside the client's executable alias.
These ownership aliases are limited to the default `headroom` MCP server
name. An unrelated server such as `mcp__other__headroom_retrieve` does not
replace the proxy's retrieval tool. Optional CCR system instructions use
the executable name selected from the available tool definitions.
## Phase 3: Response Handler
When the LLM calls `headroom_retrieve`:
@@ -71,7 +84,9 @@ When the LLM calls `headroom_retrieve`:
3. The result is added to the conversation
4. The API call continues automatically
The client never sees CCR tool calls on the Anthropic and OpenAI proxy paths; Headroom resolves them transparently there.
On the Anthropic and OpenAI proxy paths, only retrieval-only responses naming
the proxy's bare `headroom_retrieve` are resolved server-side. Mixed responses
and all MCP-registered retrieval aliases are forwarded for the client to execute.
<Callout type="warning" title="Gemini CCR boundary">
Buffered native Gemini requests resolve `headroom_retrieve` server-side and
+22
View File
@@ -5,8 +5,18 @@ from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from headroom.proxy.tool_name_policy import extract_tool_name
from .tool_injection import CCR_TOOL_NAME, parse_tool_call
_CLIENT_CCR_TOOL_ALIASES = frozenset(
{
"headroom_headroom_retrieve",
"mcp__headroom__headroom_retrieve",
"mcp_headroom_headroom_retrieve",
}
)
@dataclass
class CCRToolCall:
@@ -128,6 +138,18 @@ def has_ccr_retrieve_tool(tools: Any) -> bool:
return False
def client_retrieval_tool_name(tools: list[dict[str, Any]] | None) -> str | None:
"""Select the canonical retrieval tool, or a default Headroom MCP alias."""
alias = None
for tool in tools or ():
name = extract_tool_name(tool)
if name == CCR_TOOL_NAME:
return name
if alias is None and isinstance(name, str) and name.lower() in _CLIENT_CCR_TOOL_ALIASES:
alias = name
return alias
def has_ccr_tool_calls(response: dict[str, Any], provider: str) -> bool:
"""Return true when ``response`` contains at least one CCR tool call."""
return any(is_ccr_tool_call(tool_call) for tool_call in extract_tool_calls(response, provider))
+15 -8
View File
@@ -154,6 +154,8 @@ def create_ccr_tool_definition(
def create_system_instructions(
hashes: list[str],
retrieval_endpoint: str = "/v1/retrieve",
*,
retrieval_tool_name: str = CCR_TOOL_NAME,
) -> str:
"""Create system message instructions for CCR retrieval.
@@ -163,6 +165,7 @@ def create_system_instructions(
Args:
hashes: List of hash keys for compressed content in this context.
retrieval_endpoint: The endpoint path for retrieval.
retrieval_tool_name: Executable tool name from the client's registry.
Returns:
Instruction text to append to system message.
@@ -173,10 +176,10 @@ def create_system_instructions(
## Compressed Context Available
Some tool outputs have been compressed to reduce context size. If you need
the full uncompressed data, you can retrieve it using the `{CCR_TOOL_NAME}` tool.
the full uncompressed data, you can retrieve it using the `{retrieval_tool_name}` tool.
**How to retrieve:**
- Call `{CCR_TOOL_NAME}(hash="<hash>")` to get the full original content back
- Call `{retrieval_tool_name}(hash="<hash>")` to get the full original content back
**Available hashes:** {hash_list}
@@ -456,11 +459,10 @@ class CCRToolInjector:
tools = tools or []
# Check if already present (e.g., from MCP server)
for tool in tools:
tool_name = tool.get("name") or tool.get("function", {}).get("name")
if tool_name == CCR_TOOL_NAME:
return tools, False # Already present, skip injection
from .tool_calls import client_retrieval_tool_name
if client_retrieval_tool_name(tools):
return tools, False # Already present, skip injection
# Add CCR tool
ccr_tool = create_ccr_tool_definition(self.provider)
@@ -469,11 +471,13 @@ class CCRToolInjector:
def inject_into_system_message(
self,
messages: list[dict[str, Any]],
tools: list[dict[str, Any]] | None = None,
) -> list[dict[str, Any]]:
"""Inject retrieval instructions into system message.
Args:
messages: List of messages.
tools: Available tool definitions for selecting an executable retrieval name.
Returns:
Updated messages with instructions added to system message.
@@ -481,9 +485,12 @@ class CCRToolInjector:
if not self.inject_system_instructions or not self.has_compressed_content:
return messages
from .tool_calls import client_retrieval_tool_name
instructions = create_system_instructions(
self._detected_hashes,
self.retrieval_endpoint,
retrieval_tool_name=client_retrieval_tool_name(tools) or CCR_TOOL_NAME,
)
# Find and update system message
@@ -567,7 +574,7 @@ class CCRToolInjector:
updated_tools, was_injected = self.inject_tool_definition(
tools, session_has_done_ccr=session_has_done_ccr
)
updated_messages = self.inject_into_system_message(messages)
updated_messages = self.inject_into_system_message(messages, tools=updated_tools)
return updated_messages, updated_tools if updated_tools else None, was_injected
+3 -1
View File
@@ -2742,7 +2742,9 @@ class AnthropicHandlerMixin:
# they can drive tool injection (issue #2836).
ccr_present_hashes = injector.verify_ownership()
if inject_system_instructions and injector.has_compressed_content:
optimized_messages = injector.inject_into_system_message(optimized_messages)
optimized_messages = injector.inject_into_system_message(
optimized_messages, tools=tools
)
# Sticky-on tool registration (PR-B7): always inject the
# retrieval tool once a session has done CCR, regardless
+3 -1
View File
@@ -4245,7 +4245,9 @@ class OpenAIHandlerMixin:
and not stream
and injector.has_compressed_content
):
optimized_messages = injector.inject_into_system_message(optimized_messages)
optimized_messages = injector.inject_into_system_message(
optimized_messages, tools=tools
)
if can_inject_ccr_tool:
from headroom.proxy.helpers import (
+5 -12
View File
@@ -2909,27 +2909,20 @@ def apply_session_sticky_ccr_tool(
* Otherwise, inject only when this turn produced compressed content.
The first injection records the golden bytes for future turns.
Tools whose name already equals ``CCR_TOOL_NAME`` (e.g. the client
pre-registered it via MCP) are not re-appended; the client's bytes
win.
Tools registered under ``CCR_TOOL_NAME`` or a supported client/MCP alias
are not re-appended; the client's executable name and definition win.
Returns ``(updated_tools, was_injected)``. ``updated_tools`` is a
fresh list (caller-safe).
"""
from headroom.ccr.tool_injection import CCR_TOOL_NAME
from headroom.ccr.tool_calls import client_retrieval_tool_name
if provider not in ("anthropic", "openai", "google"):
raise ValueError(f"unsupported provider: {provider!r}")
tools_out: list[dict[str, Any]] = list(existing_tools) if existing_tools else []
existing_names: set[str] = set()
for t in tools_out:
n = _extract_tool_name(t)
if n:
existing_names.add(n)
# Client (or MCP) already provided a tool by this name — don't double up.
if CCR_TOOL_NAME in existing_names:
# Only default Headroom aliases claim ownership, not arbitrary MCP servers.
if client_retrieval_tool_name(tools_out):
log_tool_injection_decision(
provider=provider,
session_id=session_id,
@@ -18,10 +18,12 @@ prefix is still cold, and the array never changes again.
from __future__ import annotations
import json
import re
import pytest
from headroom.ccr.tool_injection import CCR_TOOL_NAME, create_ccr_tool_definition
from headroom.cache.compression_store import CompressionStore
from headroom.ccr.tool_injection import CCR_TOOL_NAME, CCRToolInjector, create_ccr_tool_definition
from headroom.proxy.helpers import (
_reset_session_ccr_tracker_for_test,
apply_session_sticky_ccr_tool,
@@ -104,7 +106,7 @@ def test_the_tool_is_present_from_the_very_first_request(provider):
def test_the_tool_definition_is_small_enough_that_eager_is_obviously_right():
"""Guards the premise: if this ever grows large, revisit the trade."""
"""Bound the cold-prefix overhead that justifies eager injection."""
size = len(json.dumps(create_ccr_tool_definition()))
assert size < 2000, (
f"headroom_retrieve is now {size} bytes; eager injection was justified "
@@ -175,6 +177,109 @@ def test_a_client_provided_tool_still_wins(monkeypatch):
assert _names(tools).count(CCR_TOOL_NAME) == 1
@pytest.mark.parametrize("provider", ["anthropic", "openai"])
@pytest.mark.parametrize(
"alias",
[
"headroom_headroom_retrieve",
"mcp__headroom__headroom_retrieve",
"mcp_Headroom_headroom_retrieve",
],
)
def test_client_retrieval_alias_never_advertises_an_unavailable_tool(provider, alias):
"""Mixed-tool turns must only offer retrieval names the client can execute."""
retrieval = create_ccr_tool_definition(provider)
if provider == "openai":
retrieval["function"]["name"] = alias
read_tool = {"type": "function", "function": {"name": "Read", "parameters": {}}}
else:
retrieval["name"] = alias
read_tool = CLIENT_TOOLS[0]
client_tools = [retrieval, read_tool]
session_id = f"sess-client-alias-{provider}-{alias}"
# A cold request, actual compression, and later replay all retain a usable
# retrieval tool without introducing the unavailable bare proxy spelling.
for compressed in (False, True, False):
tools, injected = apply_session_sticky_ccr_tool(
provider=provider,
session_id=session_id,
request_id="req-client-alias",
existing_tools=client_tools,
has_compressed_content_this_turn=compressed,
allow_eager=True,
)
assert not injected
assert alias in _names(tools)
assert CCR_TOOL_NAME not in _names(tools)
# The no-session library/Google fallback must obey the same client registry.
injector = CCRToolInjector(provider=provider, inject_tool=True)
tools, injected = injector.inject_tool_definition(client_tools, session_has_done_ccr=True)
assert not injected
assert alias in _names(tools)
assert CCR_TOOL_NAME not in _names(tools)
@pytest.mark.parametrize("provider", ["anthropic", "openai"])
@pytest.mark.parametrize("alias", ["mcp__other__headroom_retrieve", "mcp_Other_headroom_retrieve"])
def test_unrelated_mcp_server_cannot_displace_proxy_retrieval(provider, alias):
retrieval = create_ccr_tool_definition(provider)
if provider == "openai":
retrieval["function"]["name"] = alias
else:
retrieval["name"] = alias
client_tools = [retrieval]
tools, _ = apply_session_sticky_ccr_tool(
provider=provider,
session_id=None,
request_id="req-unrelated-mcp",
existing_tools=client_tools,
has_compressed_content_this_turn=True,
)
assert CCR_TOOL_NAME in _names(tools)
assert alias in _names(tools)
injector = CCRToolInjector(provider=provider)
fallback_tools, _ = injector.inject_tool_definition(client_tools, session_has_done_ccr=True)
assert CCR_TOOL_NAME in _names(fallback_tools)
assert alias in _names(fallback_tools)
@pytest.mark.parametrize("provider", ["anthropic", "openai"])
@pytest.mark.parametrize(
"alias",
[
"headroom_headroom_retrieve",
"mcp__headroom__headroom_retrieve",
"mcp_Headroom_headroom_retrieve",
],
)
def test_retrieval_instructions_name_an_executable_client_tool(provider, alias):
store = CompressionStore(enable_feedback=False)
hash_key = store.store(original='{"value":42}', compressed="compressed")
messages = [
{"role": "system", "content": "Use the available tools."},
{"role": "tool", "content": f"<<ccr:{hash_key} 1_rows_offloaded>>"},
]
retrieval = create_ccr_tool_definition(provider)
if provider == "openai":
retrieval["function"]["name"] = alias
else:
retrieval["name"] = alias
injector = CCRToolInjector(
provider=provider,
inject_system_instructions=True,
compression_store=store,
)
updated_messages, updated_tools, _ = injector.process_request(messages, [retrieval])
instructions = updated_messages[0]["content"]
call_names = re.findall(r"`([^`]+)\(hash=", instructions)
assert call_names == [alias]
assert set(call_names).issubset(_names(updated_tools))
assert hash_key in instructions
def test_sticky_replay_is_byte_identical_to_the_eager_injection():
"""Later turns replay the golden bytes recorded by the eager injection."""
session = "sess-golden"