mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description This PR fixes two problems that cost Headroom users money on Claude Code. A live benchmark (`benchmarks/tool_search_vs_native/`) found both. **1. Cache mode broke when Claude Code re-serialized its last reply.** Headroom records the model's raw reply as the last message of the previous turn. Claude Code sends that reply back edited: - it strips a leading `cd <cwd> &&` from Bash commands; - it drops `caller`. The history then read as `relation=diverged` (`cache_mode_prefix_mismatch`). Cache mode forwarded the raw originals over every earlier compressed message, and the whole conversation was written to cache again: 66.8K tokens on every long-task run. The fix: when only the recorded reply differs, and it is the same turn, Headroom replays the forwarded prefix and takes the client's version of the reply. That reply was never part of a cached prefix. "Same turn" means the same block kinds and the same `tool_use` ids. **2. Small MCP results were compressed.** The Jira ticket (a few hundred tokens) lost its description. The model called `headroom_retrieve` and then re-fetched the ticket, which cost two extra turns and about +15% on the long task. MCP results under `HEADROOM_MCP_RESULT_MIN_CHARS` (default 4000) are now forwarded verbatim. This covers both Anthropic `tool_result` blocks and OpenAI `role: "tool"` messages. No linked issue. ## 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 - [x] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - **`headroom/cache/prefix_tracker.py`:** adds `_client_rewrote_reply_delta`, tried on `RELATION_DIVERGED` after `_replaced_system_tail_delta`. A change earlier in the history still diverges. - **`headroom/transforms/content_router.py`:** adds `_is_small_mcp_result`, applied in `_process_content_blocks` (Anthropic) and on the `role: "tool"` branch (OpenAI). It recognises the `mcp__`, `mcp_` and `mcp--` name prefixes. `HEADROOM_MCP_RESULT_MIN_CHARS=0` restores the old behaviour. - **`headroom/proxy/handlers/anthropic.py`:** adds an opt-in `HEADROOM_DEBUG_PREFIX_MISMATCH=<dir>`. It logs the first diverging message and dumps both histories, with the directory created `0700` and the file `0600`, because the dump holds the full conversation. - **`tests/test_cache_mode_delta_marker.py`:** `test_tool_use_different_input_still_falls_back` becomes `..._forwards_the_clients_version`, because the client's copy of the last reply is what gets forwarded and never the recorded one. A new test keeps the divergence for an edit earlier in the history. - **New tests:** - `tests/test_prefix_tracker_client_rewrote_reply.py`; - `tests/test_content_router_mcp_small_result.py`, which covers both wire formats and three MCP prefixes. - **`benchmarks/tool_search_vs_native/`:** a live A/B harness. It runs isolated `claude -p` sessions against six fake MCP servers and a fixture repo, and reads billed usage from Claude Code's transcripts. A run passes only if Claude Code exits 0, the tests pass, and the four MCP actions happened (`get_issue` counts as reading the ticket; a search does not). ## 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 ### Test Output ```text $ pytest -q tests/test_prefix_tracker_client_rewrote_reply.py tests/test_content_router_mcp_small_result.py tests/test_cache_mode_delta_marker.py ============================== 20 passed in 3.42s ============================== $ pytest -q tests -k "content_router or router or prefix or cache_mode or delta" ========= 1 failed, 983 passed, 15147 deselected in 222.61s (0:03:42) ========== # the 1 failure is test_content_router_single_item_deadline.py::test_single_cache_miss_fails_open_at_deadline, # a wall-clock assertion (0.126s vs < 0.12s). It fails identically on origin/main on this machine. $ ruff check . (ruff 0.16.8, CI's pinned version) All checks passed! $ ruff format --check . 1757 files already formatted $ mypy headroom/proxy/handlers/anthropic.py headroom/transforms/content_router.py headroom/cache/prefix_tracker.py --ignore-missing-imports Success: no issues found ``` ## Real Behavior Proof - Environment: macOS 26.6 (arm64), Python 3.12.13 (the repo's `.venv`), Claude Code 2.1.290, `claude-sonnet-5-5`, real Anthropic API calls, with the proxy started from this branch. - Exact command / steps: `python3 benchmarks/tool_search_vs_native/run.py --arms native,hr_hot,hr_client --reps 3 --warmup`, then the same with `--context-kb 200` for the long task. - Observed result: median of 3 runs after a warmup; every run passed (table below). Before the fix, `HEADROOM_DEBUG_PREFIX_MISMATCH` showed `relation=diverged first_diff_index=8`: the Bash `tool_use` with `cd … &&` stripped and `caller` dropped. - Not tested: harnesses other than Claude Code (the OpenAI-format MCP path is unit-tested only), Bedrock and Vertex upstreams, real (larger) MCP server catalogs, models other than Sonnet 5.5. | | native Claude Code | Headroom + CC ToolSearch | Headroom, routine tools resident | |---|---|---|---| | long task, before | $0.283 | $0.323 | $0.426 (66.8K-token cache re-write every run) | | long task, after | $0.284 | **$0.284** | **$0.255** (6 API calls vs native's 7) | | short task, after | $0.061 | $0.062 | **$0.046** | ## Runtime Rollout Safety - Rollout-managed feature(s): none; both changes are in the always-on cache-mode and compression paths. - Minimum rollout channel: stable. - Stable/default behavior changed: yes. A re-serialized last reply no longer drops cache mode to raw forwarding, and MCP results under 4000 characters are no longer compressed, giving up a few tokens of savings on those results. - Kill switch / disable path: `HEADROOM_MCP_RESULT_MIN_CHARS=0` for the MCP floor. The prefix fix has no flag, because it only applies where the old code forwarded raw. - Unsafe override required: no. - Qualification impact: less compression on small MCP results; fewer cache writes and extra turns. - Rollback path: revert this PR. ## 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] 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 - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes - **Devin review follow-ups are in `d043bd5e`:** - the OpenAI-format MCP floor; - owner-only debug dumps; - exit-code and `get_issue` scoring; - the environment and commands in the README. - **The two `npm audit` failures** (docs, e2e/wrap/tools) also fail on `main`. - **`tests/test_cli_proxy_improvements.py` hangs** when the whole file runs locally, also on `main`. That is pre-existing and not touched here. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
219 lines
8.3 KiB
Python
219 lines
8.3 KiB
Python
"""fix-3: the cache-mode delta path must ignore moved cache_control markers.
|
|
|
|
Cache mode replays the exact previously-forwarded bytes for history and
|
|
compresses ONLY the newly appended delta (compress-once-then-freeze). The gate
|
|
is ``AnthropicHandler._extract_cache_stable_delta``: it only engages when the
|
|
prior original request is a message-prefix of the current one.
|
|
|
|
Real clients (litellm, Claude Code) move the ephemeral cache_control breakpoint
|
|
to the newest message every turn, so a historical message carries the marker on
|
|
one turn and not the next. The original raw-dict prefix compare therefore failed
|
|
every turn, dropping cache mode to RAW (uncompressed) forwarding -- byte-stable
|
|
(0 busts) but 0% compression. Observed directly on the mini-swe-agent cache-mode
|
|
run: avg_compression_pct=0.0 on every instance, orig==opt on every turn.
|
|
|
|
These tests pin the scenario against the real handler method and prove the
|
|
cache_control-agnostic compare lets the delta engage while the replayed prefix
|
|
stays byte-identical (so the provider prefix still hits).
|
|
"""
|
|
|
|
import copy
|
|
|
|
from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
|
|
|
|
delta = AnthropicHandlerMixin._extract_cache_stable_delta
|
|
|
|
|
|
def B(role, text, cc=False):
|
|
"""Anthropic block-style message; cache_control lives on a content block."""
|
|
blk = {"type": "text", "text": text}
|
|
if cc:
|
|
blk["cache_control"] = {"type": "ephemeral"}
|
|
return {"role": role, "content": [blk]}
|
|
|
|
|
|
# Turn t: client marked the (then-newest) msg2. We forwarded it verbatim.
|
|
PREV_ORIG = [B("user", "sys+task"), B("assistant", "ok"), B("user", "obs-1", cc=True)]
|
|
PREV_FWD = copy.deepcopy(PREV_ORIG)
|
|
# Turn t+1: appended act-2 + obs-2 and MOVED the marker off msg2 onto the newest.
|
|
CUR = [
|
|
B("user", "sys+task"),
|
|
B("assistant", "ok"),
|
|
B("user", "obs-1"), # marker gone
|
|
B("assistant", "act-2"),
|
|
B("user", "obs-2", cc=True), # marker moved here
|
|
]
|
|
|
|
|
|
def test_moved_marker_engages_delta_not_raw_fallback():
|
|
out = delta(CUR, PREV_ORIG, PREV_FWD)
|
|
assert out is not None, "moved marker must NOT force raw fallback"
|
|
stable_prefix, appended = out
|
|
# The replayed prefix is byte-identical to what we forwarded (and the
|
|
# provider cached) last turn -> the prefix hits instead of busting.
|
|
assert stable_prefix == PREV_FWD
|
|
# Only the two newly appended messages are handed to compression.
|
|
assert len(appended) == 2
|
|
assert appended[0]["content"][0]["text"] == "act-2"
|
|
assert appended[1]["content"][0]["text"] == "obs-2"
|
|
|
|
|
|
def test_control_marker_not_moved_also_engages():
|
|
# Same append, marker left on the historical msg2: engages either way.
|
|
cur = [
|
|
B("user", "sys+task"),
|
|
B("assistant", "ok"),
|
|
B("user", "obs-1", cc=True),
|
|
B("assistant", "act-2"),
|
|
B("user", "obs-2"),
|
|
]
|
|
assert delta(cur, PREV_ORIG, PREV_FWD) is not None
|
|
|
|
|
|
def test_real_content_divergence_still_falls_back():
|
|
# Safety preserved: a genuinely different historical message (not just a
|
|
# moved marker) must still bail to raw -- we never replay stale content.
|
|
cur = [
|
|
B("user", "sys+task"),
|
|
B("assistant", "DIFFERENT"), # content actually changed
|
|
B("user", "obs-1"),
|
|
B("assistant", "act-2"),
|
|
]
|
|
assert delta(cur, PREV_ORIG, PREV_FWD) is None
|
|
|
|
|
|
def test_cold_start_returns_none():
|
|
assert delta(CUR, None, None) is None
|
|
assert delta(CUR, [], []) is None
|
|
|
|
|
|
def test_shorter_current_returns_none():
|
|
assert delta([B("user", "sys+task")], PREV_ORIG, PREV_FWD) is None
|
|
|
|
|
|
# ── fix-4: tool_result content shape (string <-> [{type:text}]) ────────────────
|
|
def _tr(tool_use_id, text, as_string):
|
|
content = text if as_string else [{"type": "text", "text": text}]
|
|
return {
|
|
"role": "user",
|
|
"content": [{"type": "tool_result", "tool_use_id": tool_use_id, "content": content}],
|
|
}
|
|
|
|
|
|
def test_tool_result_string_vs_block_engages():
|
|
# Stored previous_original holds the block-list form; client resends the SAME
|
|
# tool_result as a bare string. These are Anthropic-equivalent -> must engage.
|
|
prev_orig = [
|
|
B("user", "task"),
|
|
_tr("t1", "<returncode>0</returncode>\n<output>\n</output>", as_string=False),
|
|
]
|
|
prev_fwd = copy.deepcopy(prev_orig)
|
|
cur = [
|
|
B("user", "task"),
|
|
_tr("t1", "<returncode>0</returncode>\n<output>\n</output>", as_string=True), # string form
|
|
B("assistant", "next-action"),
|
|
_tr("t2", "<output>done</output>", as_string=True),
|
|
]
|
|
out = delta(cur, prev_orig, prev_fwd)
|
|
assert out is not None, "tool_result string-vs-block must NOT force raw fallback"
|
|
stable_prefix, appended = out
|
|
assert stable_prefix == prev_fwd # replay the byte-identical cached prefix
|
|
assert len(appended) == 2 # only the new assistant + tool_result are the delta
|
|
|
|
|
|
def test_tool_result_different_text_still_falls_back():
|
|
# Safety: same shape-normalization must NOT hide a genuine content change.
|
|
prev_orig = [B("user", "task"), _tr("t1", "OUTPUT-A", as_string=False)]
|
|
prev_fwd = copy.deepcopy(prev_orig)
|
|
cur = [B("user", "task"), _tr("t1", "OUTPUT-B", as_string=True), B("assistant", "x")]
|
|
assert delta(cur, prev_orig, prev_fwd) is None
|
|
|
|
|
|
def test_tool_use_caller_annotation_ignored():
|
|
# mini-swe-agent/litellm adds a non-semantic `caller` tag to tool_use blocks
|
|
# on the stored copy but not on the re-sent wire message -> must still engage.
|
|
def _asst(with_caller):
|
|
tu = {"type": "tool_use", "id": "tu1", "name": "bash", "input": {"command": "ls"}}
|
|
if with_caller:
|
|
tu["caller"] = {"type": "direct"}
|
|
return {"role": "assistant", "content": [tu]}
|
|
|
|
prev_orig = [B("user", "task"), _asst(with_caller=True)] # stored: has caller
|
|
prev_fwd = copy.deepcopy(prev_orig)
|
|
cur = [
|
|
B("user", "task"),
|
|
_asst(with_caller=False),
|
|
_tr("t1", "out", as_string=True),
|
|
] # wire: no caller
|
|
out = delta(cur, prev_orig, prev_fwd)
|
|
assert out is not None, "a client-only `caller` annotation must not force raw fallback"
|
|
assert out[0] == prev_fwd
|
|
assert len(out[1]) == 1
|
|
|
|
|
|
def test_tool_use_different_input_forwards_the_clients_version():
|
|
# The last recorded message is the model's raw reply, which clients re-serialize
|
|
# (Claude Code strips "cd <cwd> &&" from Bash). The client's version is what gets
|
|
# forwarded, never the recorded one, so a changed command reaches the provider
|
|
# exactly as the client sent it.
|
|
def _asst(cmd):
|
|
return {
|
|
"role": "assistant",
|
|
"content": [
|
|
{"type": "tool_use", "id": "tu1", "name": "bash", "input": {"command": cmd}}
|
|
],
|
|
}
|
|
|
|
prev_orig = [B("user", "task"), _asst("ls")]
|
|
prev_fwd = copy.deepcopy(prev_orig)
|
|
cur = [B("user", "task"), _asst("rm -rf /"), _tr("t1", "out", as_string=True)]
|
|
out = delta(cur, prev_orig, prev_fwd)
|
|
assert out is not None
|
|
assert out[0][-1] == cur[1]
|
|
assert out[1] == cur[2:]
|
|
|
|
|
|
def test_tool_use_changed_earlier_in_history_still_falls_back():
|
|
# A change BEFORE the last recorded reply is a real divergence.
|
|
def _asst(cmd):
|
|
return {
|
|
"role": "assistant",
|
|
"content": [
|
|
{"type": "tool_use", "id": "tu1", "name": "bash", "input": {"command": cmd}}
|
|
],
|
|
}
|
|
|
|
prev_orig = [
|
|
B("user", "task"),
|
|
_asst("ls"),
|
|
_tr("tu1", "out", as_string=True),
|
|
B("assistant", "done"),
|
|
]
|
|
prev_fwd = copy.deepcopy(prev_orig)
|
|
cur = [
|
|
B("user", "task"),
|
|
_asst("rm -rf /"),
|
|
_tr("tu1", "out", as_string=True),
|
|
B("assistant", "done"),
|
|
B("user", "next"),
|
|
]
|
|
assert delta(cur, prev_orig, prev_fwd) is None
|
|
|
|
|
|
def test_combined_marker_move_and_tool_result_shape_engages():
|
|
# The real mini-swe-agent situation: marker moved AND tool_result shape differs.
|
|
prev_orig = [
|
|
B("user", "task", cc=True),
|
|
_tr("t1", "obs-1", as_string=False),
|
|
]
|
|
prev_fwd = copy.deepcopy(prev_orig)
|
|
cur = [
|
|
B("user", "task"), # marker gone
|
|
_tr("t1", "obs-1", as_string=True), # shape flipped to string
|
|
B("assistant", "act", cc=True), # marker moved to newest
|
|
]
|
|
out = delta(cur, prev_orig, prev_fwd)
|
|
assert out is not None
|
|
assert out[0] == prev_fwd
|
|
assert len(out[1]) == 1
|