Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(cache): enforce Anthropic's 1h-before-5m cache_control ordering before forwarding (#2941)
Parideboy3752458022f7
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 5125c0a01..ac608f4b9 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -199,9 +199,30 @@ class AnthropicHandlerMixin:def _sort_tools_deterministically(cls, tools: list[dict[str, Any]] | None) -> list[dict[str, Any]] | None:- """Return tools in deterministic order to preserve prompt-cache stability."""+ """Return tools in deterministic order to preserve prompt-cache stability.++ Skipped entirely when any tool carries ``cache_control``. A breakpoint on+ a tool means "cache everything up to and including this one", so+ reordering the array changes which tools are inside that prefix -- and+ with two markers of different TTLs it can put the 1h one behind the 5m+ one, which Anthropic rejects outright (#2939). The Rust proxy already+ refuses for the same reason (``any_tool_has_cache_control`` in+ ``crates/headroom-proxy/src/compression/live_zone_anthropic.rs``); this+ is the Python side of that guard.++ Clients that mark no tools -- the common case, and the one the sort was+ written for -- are unaffected, so this costs nobody a cache bust.+ """if not tools:return tools+ marked = sum(1 for t in tools if isinstance(t, dict) and t.get("cache_control"))+ if marked:+ logger.info(+ "event=tool_sort_skipped reason=marker_present tool_count=%d marked=%d",+ len(tools),+ marked,+ )+ return toolsreturn sorted(tools, key=cls._tool_sort_key)@classmethod@@ -754,11 +775,24 @@ class AnthropicHandlerMixin:# transform runs; paired with the outbound count right before# forwarding (event=cache_breakpoints) so a dropped or moved# final breakpoint is self-diagnosing from proxy.log alone.- from headroom.proxy.helpers import count_cache_breakpoints+ from headroom.proxy.helpers import (+ CACHE_TTL_1H,+ cache_control_ttl_lanes,+ count_cache_breakpoints,+ )inbound_breakpoints = count_cache_breakpoints(body.get("system"), messages, body.get("tools"))+ # Which TTL lane did the CLIENT ask for on THIS turn? Claude Code+ # picks 5m or 1h per request (a `/btw` side question drops to 5m and+ # omits the extended-cache-ttl beta header even mid-1h-session), so+ # this cannot be inferred from the session or from config. The+ # pre-forward guard needs it to tell a breakpoint the client asked+ # for from one an earlier turn's replayed bytes dragged in (#2939).+ client_uses_1h = CACHE_TTL_1H in cache_control_ttl_lanes(+ body.get("system"), messages, body.get("tools")+ )# Validate message array sizeif len(messages) > MAX_MESSAGE_ARRAY_LENGTH:@@ -3082,7 +3116,37 @@ class AnthropicHandlerMixin:"upstream request for server-side retrieval handling")- from headroom.proxy.helpers import log_cache_breakpoints+ # Last stop before the wire. Every transform, the tool sort, the+ # tool-search deferral, CCR injection and the pipeline+ # extensions have run, so this is the only place that can see+ # the cache_control markers Anthropic will actually evaluate --+ # and the ordering rule spans tools/system/messages, which no+ # single transform is in a position to check (#2939).+ from headroom.proxy.helpers import (+ enforce_cache_control_ttl_order,+ log_cache_breakpoints,+ )++ (+ _ttl_system,+ _ttl_messages,+ _ttl_tools,+ _ttl_stats,+ ) = enforce_cache_control_ttl_order(+ body.get("system"),+ body.get("messages"),+ body.get("tools"),+ client_uses_1h=client_uses_1h,+ request_id=request_id,+ )+ if _ttl_stats["violation"]:+ if body.get("system") is not None:+ body["system"] = _ttl_system+ body["messages"] = _ttl_messages+ if body.get("tools") is not None:+ body["tools"] = _ttl_tools+ tools = _ttl_tools+ body_mutation_tracker.mark_mutated("cache_control_ttl_order")log_cache_breakpoints(request_id=request_id,diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 31cbe4635..cdf7a2021 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -18,6 +18,7 @@ import reimport threadingimport timefrom collections import OrderedDict+from collections.abc import Callablefrom dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Literal, cast@@ -406,6 +407,289 @@ def count_cache_breakpoints(}+# --------------------------------------------------------------------------+# cache_control TTL lanes (issues #2939, #2767).+#+# Anthropic reads cache breakpoints in ONE global walk -- `tools`, then+# `system`, then `messages` -- and requires every ``ttl="1h"`` marker to appear+# before every 5-minute one. A bare ``{"type": "ephemeral"}`` marker IS 5m. Get+# it wrong and the whole turn dies with+#+# messages.15.content.1.cache_control.ttl: a ttl='1h' cache_control block must+# not come after a ttl='5m' cache_control block.+#+# The rule is already modelled in ``crates/headroom-core/src/cache_control.rs``+# (``TtlOrderingWalk``), but that walker is instantiated once per field list, so+# it only sees violations *within* `tools`, `system` or `messages` -- never+# across them -- and it only warns. The helpers below are the cross-section+# Python counterpart, and they repair rather than warn, because by the time the+# body reaches the forwarder any violation in it is one Headroom introduced.+#+# No Headroom code ever invents a ``ttl`` value: every marker we re-place is+# copied from some client marker. So an outbound 1h marker on a request whose+# client sent none can only have leaked in from an EARLIER turn (via+# ``overlay_cached_prefix`` replaying the previous turn's forwarded bytes), and+# the fix is to drop the leaked ttl rather than to spread it.+# --------------------------------------------------------------------------++CACHE_TTL_1H = "1h"+CACHE_TTL_5M = "5m"+#: Any other ``ttl`` value is a lane we don't model; markers carrying one are+#: reported but never rewritten, so a future Anthropic TTL can't be mangled by+#: guesswork here. Mirrors ``TtlOrderingWalk::observe`` in headroom-core.+CACHE_TTL_OTHER = "other"++_TTL_GUARD_ENV = "HEADROOM_CACHE_CONTROL_TTL_GUARD"+++def cache_control_ttl_lane(marker: Any) -> str:+ """Return ``"1h"``, ``"5m"`` or ``"other"`` for one ``cache_control`` marker.++ A marker with no ``ttl`` key is 5m -- that is Anthropic's default lane, and+ treating it as "unknown" instead would make every ordinary Claude Code+ request look like a violation.+ """+ if not isinstance(marker, dict):+ return CACHE_TTL_OTHER+ ttl = marker.get("ttl")+ if ttl is None:+ return CACHE_TTL_5M+ ttl = str(ttl)+ return ttl if ttl in (CACHE_TTL_1H, CACHE_TTL_5M) else CACHE_TTL_OTHER+++def _revisit_holder(+ holder: Any,+ section: str,+ visit: Callable[[str, dict[str, Any]], dict[str, Any] | None],+) -> tuple[Any, bool]:+ """Offer ``holder``'s marker to ``visit``; return a copy only if replaced."""+ if not isinstance(holder, dict):+ return holder, False+ marker = holder.get("cache_control")+ if not isinstance(marker, dict):+ return holder, False+ replacement = visit(section, marker)+ if replacement is None:+ return holder, False+ return {**holder, "cache_control": replacement}, True+++def walk_cache_control(+ system: Any,+ messages: Any,+ tools: Any,+ visit: Callable[[str, dict[str, Any]], dict[str, Any] | None],+) -> tuple[Any, Any, Any, bool]:+ """Visit every ``cache_control`` marker in Anthropic's evaluation order.++ ``visit(section, marker)`` returns a replacement marker, or ``None`` to+ leave it alone -- so the same traversal serves both a read-only survey and a+ rewrite. Sections are rebuilt copy-on-write and the untouched originals are+ returned by identity: the forwarded body shares structure with the prefix+ tracker's snapshot of what we sent, so mutating a marker in place would+ rewrite history the next turn compares against.++ Traversal matches :func:`count_cache_breakpoints`, nested ``tool_result``+ sub-blocks included, so the guard and the diagnostic can never disagree+ about what counts as a breakpoint.+ """+ changed = False++ new_tools = tools+ if isinstance(tools, list):+ rebuilt_tools: list[Any] = []+ hit = False+ for tool in tools:+ out, did = _revisit_holder(tool, "tools", visit)+ hit = hit or did+ rebuilt_tools.append(out)+ if hit:+ new_tools = rebuilt_tools+ changed = True++ new_system = system+ if isinstance(system, list):+ rebuilt_system: list[Any] = []+ hit = False+ for block in system:+ out, did = _revisit_holder(block, "system", visit)+ hit = hit or did+ rebuilt_system.append(out)+ if hit:+ new_system = rebuilt_system+ changed = True++ new_messages = messages+ if isinstance(messages, list):+ rebuilt_messages: list[Any] = []+ any_message_hit = False+ for msg in messages:+ if not isinstance(msg, dict):+ rebuilt_messages.append(msg)+ continue+ # Message-level markers are non-standard but Headroom's own+ # diagnostics count them, so keep the two traversals in step.+ new_msg, message_hit = _revisit_holder(msg, "messages", visit)+ content = new_msg.get("content")+ if isinstance(content, list):+ rebuilt_blocks: list[Any] = []+ block_hit = False+ for block in content:+ new_block, did = _revisit_holder(block, "messages", visit)+ inner = new_block.get("content") if isinstance(new_block, dict) else None+ if isinstance(inner, list):+ rebuilt_inner: list[Any] = []+ inner_hit = False+ for sub in inner:+ new_sub, sub_did = _revisit_holder(sub, "messages", visit)+ inner_hit = inner_hit or sub_did+ rebuilt_inner.append(new_sub)+ if inner_hit:+ new_block = {**new_block, "content": rebuilt_inner}+ did = True+ block_hit = block_hit or did+ rebuilt_blocks.append(new_block)+ if block_hit:+ new_msg = {**new_msg, "content": rebuilt_blocks}+ message_hit = True+ any_message_hit = any_message_hit or message_hit+ rebuilt_messages.append(new_msg)+ if any_message_hit:+ new_messages = rebuilt_messages+ changed = True++ return new_system, new_messages, new_tools, changed+++def cache_control_ttl_lanes(system: Any, messages: Any, tools: Any) -> set[str]:+ """Return the distinct TTL lanes the request's markers ask for."""+ lanes: set[str] = set()++ def _survey(_section: str, marker: dict[str, Any]) -> None:+ lanes.add(cache_control_ttl_lane(marker))+ return None++ walk_cache_control(system, messages, tools, _survey)+ return lanes+++def enforce_cache_control_ttl_order(+ system: Any,+ messages: Any,+ tools: Any,+ *,+ client_uses_1h: bool,+ request_id: str = "",+) -> tuple[Any, Any, Any, dict[str, Any]]:+ """Make the outbound body satisfy Anthropic's cache_control TTL ordering.++ Two repairs, in this order:++ 1. **Lane containment.** When the client's own request carried no 1h marker+ anywhere (``client_uses_1h`` is False), strip ``ttl`` from every outbound+ 1h marker. Headroom never authors a ttl, so such a marker is a previous+ turn's value replayed into this one -- and a client that did not ask for+ the 1h lane has not sent the ``extended-cache-ttl`` beta header either,+ so promoting the rest of the request to match it is not an option. This+ is the ``/btw`` case in #2939: Claude Code forks a side question into the+ 5m lane, and the replayed prefix drags a 1h marker in behind the fork's+ own 5m ``tools``/``system`` breakpoints.+ 2. **Ordering.** Any 5m marker still sitting before the last 1h marker is+ promoted to 1h. Here the client *is* in the 1h lane, so the beta header+ is present and the promotion is safe. This covers the mirror-image bug+ where a transform downgrades an early breakpoint -- e.g.+ ``inject_tool_search_deferral`` losing a 1h marker off a deferred tool+ (#2767) -- leaving the client's later 1h message breakpoints illegal.++ Demoting the later 1h instead would also make the request legal, but it+ throws away 1h caching the client asked and paid for, which is the exact+ regression #2375 / #2382 / #2651 were filed to stop.++ Returns ``(system, messages, tools, stats)``. When nothing needed repairing+ the three sections are the objects that were passed in.+ """+ stats: dict[str, Any] = {+ "violation": False,+ "demoted": 0,+ "promoted": 0,+ "first_short_section": "",+ "first_long_section": "",+ }+ if os.environ.get(_TTL_GUARD_ENV, "1").strip().lower() in ("0", "false", "no", "off"):+ return system, messages, tools, stats++ if not client_uses_1h:++ def _contain(section: str, marker: dict[str, Any]) -> dict[str, Any] | None:+ if cache_control_ttl_lane(marker) != CACHE_TTL_1H:+ return None+ stats["demoted"] += 1+ if not stats["first_long_section"]:+ stats["first_long_section"] = section+ return {k: v for k, v in marker.items() if k != "ttl"}++ system, messages, tools, contained = walk_cache_control(system, messages, tools, _contain)+ if contained:+ stats["violation"] = True+ logger.warning(+ "event=cache_control_ttl_order request_id=%s repair=lane_containment "+ "demoted=%d leaked_from_section=%s; the client sent no 1h marker, so a "+ "replayed 1h breakpoint would have been rejected upstream",+ request_id,+ stats["demoted"],+ stats["first_long_section"],+ )+ return system, messages, tools, stats++ # Ordering pass. Survey first so we know how far the violation reaches, then+ # rewrite only the markers ahead of the last 1h one.+ lanes: list[tuple[int, str, str]] = []+ index = 0++ def _survey(section: str, marker: dict[str, Any]) -> None:+ nonlocal index+ lanes.append((index, section, cache_control_ttl_lane(marker)))+ index += 1+ return None++ walk_cache_control(system, messages, tools, _survey)++ last_long = max((i for i, _s, lane in lanes if lane == CACHE_TTL_1H), default=-1)+ offenders = [+ (i, section) for i, section, lane in lanes if lane == CACHE_TTL_5M and i < last_long+ ]+ if not offenders:+ return system, messages, tools, stats++ stats["violation"] = True+ stats["first_short_section"] = offenders[0][1]+ stats["first_long_section"] = next(s for i, s, lane in lanes if lane == CACHE_TTL_1H)+ offending_indices = {i for i, _section in offenders}+ cursor = 0++ def _promote(_section: str, marker: dict[str, Any]) -> dict[str, Any] | None:+ nonlocal cursor+ position = cursor+ cursor += 1+ if position not in offending_indices:+ return None+ stats["promoted"] += 1+ return {**marker, "ttl": CACHE_TTL_1H}++ system, messages, tools, _ = walk_cache_control(system, messages, tools, _promote)+ logger.warning(+ "event=cache_control_ttl_order request_id=%s repair=promote_to_1h promoted=%d "+ "first_short_section=%s first_long_section=%s; a 5m breakpoint preceded a 1h one, "+ "which Anthropic rejects outright",+ request_id,+ stats["promoted"],+ stats["first_short_section"],+ stats["first_long_section"],+ )+ return system, messages, tools, stats++def log_cache_breakpoints(*,request_id: str | None,diff --git a/tests/test_cache_control_ttl_order.py b/tests/test_cache_control_ttl_order.pynew file mode 100644index 000000000..74bf146f6--- /dev/null+++ b/tests/test_cache_control_ttl_order.py@@ -0,0 +1,354 @@+"""The forwarded body must satisfy Anthropic's cache_control TTL ordering.++Anthropic evaluates cache breakpoints in one global walk -- ``tools``, then+``system``, then ``messages`` -- and rejects the whole request when a+``ttl="1h"`` marker appears after a 5-minute one (a bare ``{"type":+"ephemeral"}`` marker *is* 5m)::++ 400 messages.15.content.1.cache_control.ttl: a ttl='1h' cache_control block+ must not come after a ttl='5m' cache_control block.++Headroom rewrites markers in several independent places, section by section,+and until #2939 nothing checked the rule that spans them. The failure is a dead+turn rather than a silent cost regression, so it needs tests that pin both+repair directions and, just as importantly, pin that a legal request is passed+through by identity.+"""++from typing import Any++import pytest++from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin+from headroom.proxy.helpers import (+ cache_control_ttl_lane,+ cache_control_ttl_lanes,+ enforce_cache_control_ttl_order,+ inject_tool_search_deferral,+)++TTL_1H: dict[str, Any] = {"type": "ephemeral", "ttl": "1h"}+BARE: dict[str, Any] = {"type": "ephemeral"}+TTL_5M: dict[str, Any] = {"type": "ephemeral", "ttl": "5m"}+++def _text(text: str, marker: dict[str, Any] | None = None) -> dict[str, Any]:+ block: dict[str, Any] = {"type": "text", "text": text}+ if marker is not None:+ block["cache_control"] = marker+ return block+++def _msg(*blocks: dict[str, Any], role: str = "user") -> dict[str, Any]:+ return {"role": role, "content": list(blocks)}+++def _markers(system: Any, messages: Any, tools: Any) -> list[dict[str, Any]]:+ """Every marker in Anthropic's evaluation order."""+ found: list[dict[str, Any]] = []+ for tool in tools or []:+ if isinstance(tool, dict) and isinstance(tool.get("cache_control"), dict):+ found.append(tool["cache_control"])+ for block in system or []:+ if isinstance(block, dict) and isinstance(block.get("cache_control"), dict):+ found.append(block["cache_control"])+ for msg in messages or []:+ if isinstance(msg.get("cache_control"), dict):+ found.append(msg["cache_control"])+ for block in msg.get("content") or []:+ if not isinstance(block, dict):+ continue+ if isinstance(block.get("cache_control"), dict):+ found.append(block["cache_control"])+ for sub in block.get("content") or []:+ if isinstance(sub, dict) and isinstance(sub.get("cache_control"), dict):+ found.append(sub["cache_control"])+ return found+++def _is_legal(system: Any, messages: Any, tools: Any) -> bool:+ """Reimplements the API's rule independently of the code under test."""+ seen_short = False+ for marker in _markers(system, messages, tools):+ lane = cache_control_ttl_lane(marker)+ if lane == "5m":+ seen_short = True+ elif lane == "1h" and seen_short:+ return False+ return True+++# ---------------------------------------------------------------------------+# Lane classification+++ ("marker", "expected"),+ [+ ({"type": "ephemeral"}, "5m"),+ ({"type": "ephemeral", "ttl": "5m"}, "5m"),+ ({"type": "ephemeral", "ttl": "1h"}, "1h"),+ ({"type": "ephemeral", "ttl": "24h"}, "other"),+ ("not-a-dict", "other"),+ ],+)+def test_lane_classification(marker: Any, expected: str) -> None:+ # A bare marker must read as 5m, not "unknown": every ordinary Claude Code+ # request sends bare markers, and calling those unknown would either mask+ # real violations or invent imaginary ones.+ assert cache_control_ttl_lane(marker) == expected+++def test_lanes_survey_covers_all_three_sections() -> None:+ lanes = cache_control_ttl_lanes(+ [_text("sys", BARE)],+ [_msg(_text("hi", TTL_1H))],+ [{"name": "read", "cache_control": {"type": "ephemeral", "ttl": "7d"}}],+ )+ assert lanes == {"5m", "1h", "other"}+++# ---------------------------------------------------------------------------+# Repair 1: lane containment -- the /btw case from #2939+++def test_replayed_1h_is_stripped_when_client_asked_for_5m() -> None:+ # Claude Code's `/btw` forks the conversation as a "side question", which is+ # not on its 1h allowlist: the fork's tools/system breakpoints are bare 5m+ # and it does not send the extended-cache-ttl beta header. Headroom's+ # overlay of the previous turn's forwarded bytes drags a 1h marker into+ # messages behind them, which is exactly the reported 400.+ tools = [{"name": "read", "cache_control": dict(BARE)}]+ system = [_text("sys", dict(BARE))]+ messages = [_msg(_text("old"), _text("replayed", dict(TTL_1H)))]++ system, messages, tools, stats = enforce_cache_control_ttl_order(+ system, messages, tools, client_uses_1h=False+ )++ assert stats["violation"] is True+ assert stats["demoted"] == 1+ assert stats["first_long_section"] == "messages"+ assert _markers(system, messages, tools) == [BARE, BARE, BARE], (+ "the leaked 1h ttl should be dropped, leaving the marker itself in place"+ )+ assert _is_legal(system, messages, tools)+++def test_containment_keeps_non_ttl_marker_fields() -> None:+ # Claude Code also sends `scope` on its markers; only the ttl is at fault.+ scoped = {"type": "ephemeral", "ttl": "1h", "scope": "global"}+ _, messages, _, stats = enforce_cache_control_ttl_order(+ None, [_msg(_text("x", scoped))], None, client_uses_1h=False+ )+ assert stats["demoted"] == 1+ assert messages[0]["content"][0]["cache_control"] == {+ "type": "ephemeral",+ "scope": "global",+ }+++def test_client_1h_is_never_stripped() -> None:+ system = [_text("sys", dict(TTL_1H))]+ messages = [_msg(_text("hi", dict(TTL_1H)))]+ out_system, out_messages, out_tools, stats = enforce_cache_control_ttl_order(+ system, messages, None, client_uses_1h=True+ )+ assert stats["violation"] is False+ assert out_system is system and out_messages is messages and out_tools is None+++# ---------------------------------------------------------------------------+# Repair 2: ordering -- the #2767 case+++def test_5m_in_tools_before_1h_in_messages_is_promoted() -> None:+ # A transform downgraded the tools breakpoint while the client's message+ # breakpoints are still 1h. Promoting restores what the client asked for;+ # demoting would throw away 1h caching it is already paying for.+ tools = [{"name": "read", "cache_control": dict(BARE)}]+ messages = [_msg(_text("hi", dict(TTL_1H)))]++ _, messages, tools, stats = enforce_cache_control_ttl_order(+ None, messages, tools, client_uses_1h=True+ )++ assert stats["promoted"] == 1+ assert stats["first_short_section"] == "tools"+ assert stats["first_long_section"] == "messages"+ assert tools[0]["cache_control"] == TTL_1H+ assert messages[0]["content"][0]["cache_control"] == TTL_1H+ assert _is_legal(None, messages, tools)+++def test_5m_in_system_before_1h_in_messages_is_promoted() -> None:+ system = [_text("sys", dict(TTL_5M))]+ messages = [_msg(_text("hi", dict(TTL_1H)))]++ system, messages, _, stats = enforce_cache_control_ttl_order(+ system, messages, None, client_uses_1h=True+ )++ assert stats["first_short_section"] == "system"+ assert system[0]["cache_control"] == TTL_1H+++def test_violation_within_messages_is_promoted() -> None:+ messages = [+ _msg(_text("a", dict(BARE))),+ _msg(_text("b"), _text("c", dict(TTL_1H))),+ ]+ _, messages, _, stats = enforce_cache_control_ttl_order(+ None, messages, None, client_uses_1h=True+ )+ assert stats["promoted"] == 1+ assert messages[0]["content"][0]["cache_control"] == TTL_1H+++def test_nested_tool_result_markers_participate() -> None:+ # tool_result carries its own content list; a marker hiding in there is+ # still a breakpoint the API walks, so it must count for the ordering.+ messages = [+ _msg(+ {+ "type": "tool_result",+ "tool_use_id": "t1",+ "content": [_text("inner", dict(BARE))],+ }+ ),+ _msg(_text("later", dict(TTL_1H))),+ ]+ _, messages, _, stats = enforce_cache_control_ttl_order(+ None, messages, None, client_uses_1h=True+ )+ assert stats["promoted"] == 1+ assert messages[0]["content"][0]["content"][0]["cache_control"] == TTL_1H+++def test_only_markers_before_the_last_1h_are_promoted() -> None:+ # A 5m marker AFTER every 1h one is legal and must be left alone -- that is+ # the ordering the API documents, not something to normalise away.+ messages = [+ _msg(_text("a", dict(BARE))),+ _msg(_text("b", dict(TTL_1H))),+ _msg(_text("c", dict(BARE))),+ ]+ _, messages, _, stats = enforce_cache_control_ttl_order(+ None, messages, None, client_uses_1h=True+ )+ assert stats["promoted"] == 1+ assert [m["content"][0]["cache_control"] for m in messages] == [TTL_1H, TTL_1H, BARE]+++# ---------------------------------------------------------------------------+# Pass-through cases+++ "markers",+ [+ pytest.param([TTL_1H, TTL_1H], id="all-1h"),+ pytest.param([BARE, BARE], id="all-5m"),+ pytest.param([TTL_1H, BARE], id="1h-then-5m"),+ pytest.param([], id="no-markers"),+ ],+)+def test_legal_requests_are_returned_by_identity(markers: list[dict[str, Any]]) -> None:+ messages = [_msg(_text(f"m{i}", dict(m))) for i, m in enumerate(markers)] or [_msg(_text("m"))]+ out_system, out_messages, out_tools, stats = enforce_cache_control_ttl_order(+ None, messages, None, client_uses_1h=True+ )+ assert stats["violation"] is False+ assert out_messages is messages, "a legal body must not be rebuilt"+ assert out_system is None and out_tools is None+++def test_unknown_ttl_is_left_alone() -> None:+ # Mirrors TtlOrderingWalk::observe in headroom-core: a TTL lane we don't+ # model takes no part in the rule and is never rewritten.+ messages = [_msg(_text("a", {"type": "ephemeral", "ttl": "24h"})), _msg(_text("b", dict(BARE)))]+ _, out, _, stats = enforce_cache_control_ttl_order(None, messages, None, client_uses_1h=False)+ assert stats["violation"] is False+ assert out is messages+++def test_kill_switch_disables_the_guard(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_CACHE_CONTROL_TTL_GUARD", "0")+ tools = [{"name": "read", "cache_control": dict(BARE)}]+ messages = [_msg(_text("hi", dict(TTL_1H)))]+ _, out_messages, out_tools, stats = enforce_cache_control_ttl_order(+ None, messages, tools, client_uses_1h=True+ )+ assert stats["violation"] is False+ assert out_messages is messages and out_tools is tools+++# ---------------------------------------------------------------------------+# Tool sort must not reorder markers+++def _tools(count: int, marked: dict[int, dict[str, Any]] | None = None) -> list[dict[str, Any]]:+ out: list[dict[str, Any]] = []+ for i in range(count):+ # Names descend so an alphabetical sort is guaranteed to reorder them.+ tool: dict[str, Any] = {"name": f"tool_{count - i:02d}", "input_schema": {}}+ if marked and i in marked:+ tool["cache_control"] = dict(marked[i])+ out.append(tool)+ return out+++def test_tool_sort_is_skipped_when_a_tool_carries_a_marker() -> None:+ # A breakpoint on a tool means "cache through here"; sorting changes which+ # tools are inside that prefix, and with two TTLs it can put the 1h marker+ # behind the 5m one. The Rust proxy already refuses for the same reason.+ tools = _tools(4, {1: TTL_1H, 3: BARE})+ assert AnthropicHandlerMixin._sort_tools_deterministically(tools) is tools+++def test_tool_sort_still_sorts_unmarked_tools() -> None:+ tools = _tools(4)+ ordered = AnthropicHandlerMixin._sort_tools_deterministically(tools)+ assert [t["name"] for t in ordered] == sorted(t["name"] for t in tools), (+ "clients that mark no tools must keep the deterministic ordering they rely on"+ )+++def test_tool_sort_would_have_created_the_violation() -> None:+ # Pins the hazard itself: without the guard, the alphabetical sort moves the+ # 5m-marked tool ahead of the 1h-marked one, which is a 400 on its own.+ tools = _tools(4, {1: TTL_1H, 3: BARE})+ assert _is_legal(None, [], tools)+ assert not _is_legal(None, [], sorted(tools, key=AnthropicHandlerMixin._tool_sort_key))+++# ---------------------------------------------------------------------------+# End-to-end regression for #2939 / #2767+++def test_deferral_downgrade_then_guard_yields_a_legal_body() -> None:+ # The #2767 shape: 13 tools, a 1h marker on one deferred tool and a bare+ # marker on a LATER deferred tool. inject_tool_search_deferral keeps the+ # last marker it stripped, so the tools prefix lands at 5m while the+ # client's message breakpoints are still 1h -- a 400. The guard repairs it.+ tools: list[dict[str, Any]] = [{"name": "read", "description": "core", "input_schema": {}}]+ for i in range(12):+ tool: dict[str, Any] = {"name": f"rare_{i}", "description": "rare", "input_schema": {}}+ if i == 4:+ tool["cache_control"] = dict(TTL_1H)+ if i == 9:+ tool["cache_control"] = dict(BARE)+ tools.append(tool)+ messages = [_msg(_text("history")), _msg(_text("newest", dict(TTL_1H)))]++ deferred = inject_tool_search_deferral(tools)+ assert deferred is not tools, "fixture no longer triggers the deferral"+ assert not _is_legal(None, messages, deferred), (+ "expected the downgraded tools breakpoint to make the body illegal"+ )++ _, messages, deferred, stats = enforce_cache_control_ttl_order(+ None, messages, deferred, client_uses_1h=True+ )+ assert stats["violation"] is True+ assert _is_legal(None, messages, deferred)