From d6d121e399938edffce5258697ad5046c84eade3 Mon Sep 17 00:00:00 2001 From: Abhay Singh Date: Thu, 13 Aug 2026 22:15:51 +0530 Subject: [PATCH] fix(ccr): re-inject headroom_retrieve when history references it on the sessionless path (#2440) (#2533) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Description Fixes #2440. `apply_session_sticky_ccr_tool` bypasses the `SessionCcrTracker` when `session_id` is `None` (WS / pre-session paths) and drives injection purely off the per-turn `has_compressed_content_this_turn` flag: ```python if not session_id: if not has_compressed_content_this_turn: ... # skip: tool NOT re-declared return tools_out, False ... ``` If an earlier turn emitted a `headroom_retrieve` tool_use into history but the current turn produced no fresh compression marker, the tool definition is not re-declared in `tools`, while the forwarded history still references it. The provider then rejects the whole request: ``` API Error: 400 Tool reference 'headroom_retrieve' not found in available tools. ``` Without a session the tracker can't remember the earlier turn's CCR, so this is unique to the sessionless path. ## Fix Add `history_references_ccr_tool(messages)` which detects an existing `headroom_retrieve` call in the forwarded messages — both the Anthropic assistant `tool_use` content block and the OpenAI assistant `tool_calls[].function.name` shapes, fully null-guarded. On the sessionless path, injection now fires when `has_compressed_content_this_turn` **or** history already references the tool, so the definition is re-declared and the request validates. The decision is logged as a new `inject_history_reference` outcome. Both handlers pass the signal computed from `optimized_messages` (the bytes actually forwarded). Behavior with a real `session_id` (the sticky tracker path) is unchanged. ## Type of Change - [x] 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 - `headroom/proxy/helpers.py`: add `history_references_ccr_tool`; add a `history_has_ccr_reference` parameter to `apply_session_sticky_ccr_tool` and OR it into the sessionless injection decision. - `headroom/proxy/tool_injection_logging.py`: add the `inject_history_reference` decision literal. - `headroom/proxy/handlers/anthropic.py`, `headroom/proxy/handlers/openai.py`: pass `history_references_ccr_tool(optimized_messages)` into the sticky-tool call. - `tests/test_ccr_tool_always_on.py`: regressions for the detector (both provider shapes + malformed inputs) and for sessionless re-injection when history references the tool. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text $ python -m pytest tests/test_ccr_tool_always_on.py -q 14 passed # with just the `or history_has_ccr_reference` condition reverted, the new # sessionless re-injection test fails (tool not injected -> would 400) $ uvx ruff@0.15.17 check headroom/proxy/helpers.py headroom/proxy/tool_injection_logging.py headroom/proxy/handlers/anthropic.py headroom/proxy/handlers/openai.py tests/test_ccr_tool_always_on.py All checks passed! $ uvx mypy@1.20.2 --ignore-missing-imports headroom/proxy/helpers.py headroom/proxy/tool_injection_logging.py Success: no issues found in 2 source files ``` ## Real Behavior Proof - Environment: Windows 11, Python 3.12, project venv (`uv sync --extra proxy`), `uvx ruff@0.15.17` / `uvx mypy@1.20.2`, pytest in the venv. - Exact command / steps: called `history_references_ccr_tool` on Anthropic `tool_use` and OpenAI `tool_calls` histories (plus null/non-list shapes), and `apply_session_sticky_ccr_tool(session_id=None, has_compressed_content_this_turn=False, history_has_ccr_reference=True)`; then temporarily reverted only the `or history_has_ccr_reference` condition and re-ran the regression. - Observed result: the detector returns `True` for both provider shapes and `False`/no-crash for malformed input; with the fix the sessionless call injects the tool (`was_injected=True`, tool present) even with no fresh compression; with the condition reverted the same call returns `was_injected=False` (the tool is dropped — exactly the 400 path). Ran against the actual module via `tests/test_ccr_tool_always_on.py`. - Not tested: a live sessionless multi-turn WS request reproducing the upstream 400 end to end. ## 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 - [ ] I have made corresponding changes to the documentation - [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 - [ ] I have updated the CHANGELOG.md if applicable Co-authored-by: JD Davis --- headroom/proxy/handlers/anthropic.py | 6 ++- headroom/proxy/handlers/openai.py | 2 + headroom/proxy/helpers.py | 51 +++++++++++++++++-- headroom/proxy/tool_injection_logging.py | 3 ++ tests/test_ccr_tool_always_on.py | 63 ++++++++++++++++++++++++ 5 files changed, 121 insertions(+), 4 deletions(-) diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py index 6d6848c43..52db0a846 100644 --- a/headroom/proxy/handlers/anthropic.py +++ b/headroom/proxy/handlers/anthropic.py @@ -2026,7 +2026,10 @@ class AnthropicHandlerMixin: # dropping the gate cannot start injecting into non-CCR # conversations. if configured_inject_tool: - from headroom.proxy.helpers import apply_session_sticky_ccr_tool + from headroom.proxy.helpers import ( + apply_session_sticky_ccr_tool, + history_references_ccr_tool, + ) # Inject whenever the request carries ANY CCR marker, new or # replayed from the frozen prefix. #1850 narrowed the @@ -2051,6 +2054,7 @@ class AnthropicHandlerMixin: request_id=request_id, existing_tools=tools, has_compressed_content_this_turn=injector.has_compressed_content, + history_has_ccr_reference=history_references_ccr_tool(optimized_messages), ) if ccr_tool_injected: logger.debug( diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py index 79a0fa986..4da3de6a6 100644 --- a/headroom/proxy/handlers/openai.py +++ b/headroom/proxy/handlers/openai.py @@ -3573,6 +3573,7 @@ class OpenAIHandlerMixin: from headroom.proxy.helpers import ( apply_session_sticky_ccr_tool, has_new_ccr_markers, + history_references_ccr_tool, ) # #1850: markers replayed from overlay_cached_prefix are @@ -3591,6 +3592,7 @@ class OpenAIHandlerMixin: request_id=request_id, existing_tools=tools, has_compressed_content_this_turn=has_new_compressed_content, + history_has_ccr_reference=history_references_ccr_tool(optimized_messages), ) if ccr_tool_injected: logger.debug( diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py index cdf7a2021..1092c58a5 100644 --- a/headroom/proxy/helpers.py +++ b/headroom/proxy/helpers.py @@ -2102,6 +2102,43 @@ def has_new_ccr_markers( ) +def history_references_ccr_tool(messages: Any) -> bool: + """True when the request history already contains a ``headroom_retrieve`` call. + + Anthropic emits it as an assistant ``tool_use`` content block; OpenAI as an + assistant ``tool_calls[].function.name``. When such a reference is present in + history but the tool is not re-declared in ``tools``, the provider rejects + the whole request (``400 Tool reference 'headroom_retrieve' not found``, + #2440). Used to force sticky re-injection on the sessionless path. + """ + from headroom.ccr.tool_injection import CCR_TOOL_NAME + + if not isinstance(messages, list): + return False + for msg in messages: + if not isinstance(msg, dict): + continue + content = msg.get("content") + if isinstance(content, list): + for block in content: + if ( + isinstance(block, dict) + and block.get("type") == "tool_use" + and block.get("name") == CCR_TOOL_NAME + ): + return True + tool_calls = msg.get("tool_calls") + if isinstance(tool_calls, list): + for tc in tool_calls: + if not isinstance(tc, dict): + continue + fn = tc.get("function") + name = fn.get("name") if isinstance(fn, dict) else tc.get("name") + if name == CCR_TOOL_NAME: + return True + return False + + def apply_session_sticky_ccr_tool( *, provider: Literal["anthropic", "openai", "google"], @@ -2109,6 +2146,7 @@ def apply_session_sticky_ccr_tool( request_id: str | None, existing_tools: list[dict[str, Any]] | None, has_compressed_content_this_turn: bool, + history_has_ccr_reference: bool = False, ) -> tuple[list[dict[str, Any]], bool]: """Apply sticky-on CCR retrieval-tool injection per :class:`SessionCcrTracker`. @@ -2157,9 +2195,14 @@ def apply_session_sticky_ccr_tool( ) return tools_out, False - # No session_id (e.g. WS path): per-turn decision drives directly. + # No session_id (e.g. WS path): the per-turn flag drives the decision, but + # a headroom_retrieve tool_use already sitting in history must ALSO force + # re-injection. Without a session the tracker can't remember a prior turn's + # CCR, so a later turn with no fresh compression would drop the tool + # definition and the provider rejects the request because history still + # references it (#2440). if not session_id: - if not has_compressed_content_this_turn: + if not (has_compressed_content_this_turn or history_has_ccr_reference): log_tool_injection_decision( provider=provider, session_id=None, @@ -2173,7 +2216,9 @@ def apply_session_sticky_ccr_tool( log_tool_injection_decision( provider=provider, session_id=None, - decision="inject_first_time", + decision="inject_first_time" + if has_compressed_content_this_turn + else "inject_history_reference", tool_definition_bytes_count=len(replay.canonical_bytes), request_id=request_id, ) diff --git a/headroom/proxy/tool_injection_logging.py b/headroom/proxy/tool_injection_logging.py index b6e9baa1d..b400bea7e 100644 --- a/headroom/proxy/tool_injection_logging.py +++ b/headroom/proxy/tool_injection_logging.py @@ -8,6 +8,9 @@ from typing import Literal ToolInjectionDecision = Literal[ "inject_first_time", "inject_sticky_replay", + # Sessionless path: history already references headroom_retrieve, so the + # tool definition is re-injected even without fresh compression (#2440). + "inject_history_reference", "skip", "skip_disabled_via_env", ] diff --git a/tests/test_ccr_tool_always_on.py b/tests/test_ccr_tool_always_on.py index 4bc457b62..60be59c7d 100644 --- a/tests/test_ccr_tool_always_on.py +++ b/tests/test_ccr_tool_always_on.py @@ -30,6 +30,7 @@ from headroom.proxy.helpers import ( _reset_session_ccr_tracker_for_test, apply_session_sticky_ccr_tool, get_session_ccr_tracker, + history_references_ccr_tool, serialize_tool_definition_canonical, ) @@ -228,6 +229,68 @@ def test_no_session_id_falls_back_to_per_turn_decision(): assert _has_ccr_tool(tools) +def test_history_references_ccr_tool_detects_both_provider_shapes(): + # Anthropic: assistant tool_use content block. + anthropic_hist = [ + {"role": "user", "content": "hi"}, + { + "role": "assistant", + "content": [{"type": "tool_use", "name": CCR_TOOL_NAME, "id": "t1", "input": {}}], + }, + ] + assert history_references_ccr_tool(anthropic_hist) is True + + # OpenAI: assistant tool_calls[].function.name. + openai_hist = [ + { + "role": "assistant", + "tool_calls": [{"id": "c1", "function": {"name": CCR_TOOL_NAME, "arguments": "{}"}}], + } + ] + assert history_references_ccr_tool(openai_hist) is True + + # No reference, and malformed shapes must not crash. + assert history_references_ccr_tool([{"role": "user", "content": "hi"}]) is False + assert ( + history_references_ccr_tool([{"content": None}, {"tool_calls": None}, "x", None]) is False + ) + assert history_references_ccr_tool("not-a-list") is False + + +def test_sessionless_history_reference_forces_reinjection(): + """#2440: no session_id + no fresh compression, but history already + references headroom_retrieve → the tool definition MUST be re-injected, + otherwise the provider rejects the request (400 tool not found).""" + history = [ + { + "role": "assistant", + "content": [{"type": "tool_use", "name": CCR_TOOL_NAME, "id": "t1", "input": {}}], + } + ] + + tools, injected = apply_session_sticky_ccr_tool( + provider="anthropic", + session_id=None, + request_id="r3", + existing_tools=None, + has_compressed_content_this_turn=False, + history_has_ccr_reference=history_references_ccr_tool(history), + ) + assert injected is True + assert _has_ccr_tool(tools) + + # No history reference and no fresh compression → still skip. + tools, injected = apply_session_sticky_ccr_tool( + provider="anthropic", + session_id=None, + request_id="r4", + existing_tools=None, + has_compressed_content_this_turn=False, + history_has_ccr_reference=False, + ) + assert injected is False + + # ─── Byte-stable tool definition ───────────────────────────────────────