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(proxy): keep leading Anthropic system payloads valid (#3671)
lorenzozaned9e29bb2600a
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex f87d01a5e..b983ea245 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -1048,6 +1048,22 @@ _ROLE_SYSTEM = "system"_TEXT_BLOCK_TYPE = "text"+def _coerce_system_block(block: dict[str, Any]) -> dict[str, Any] | None:+ """Return a block representable by Anthropic's top-level ``system`` field."""+ text = block.get("text")+ if isinstance(text, str) and text:+ # Anthropic TextBlockParam accepts these fields only. Image sources+ # and tool IDs/inputs remain invalid even after changing ``type``.+ coerced = {+ key: value+ for key, value in block.items()+ if key in {"type", "text", "cache_control", "citations"}+ }+ coerced["type"] = _TEXT_BLOCK_TYPE+ return coerced+ return None++def _system_message_to_blocks(message: dict[str, Any]) -> list[Any]:"""Convert a ``role="system"`` message into Anthropic system content blocks."""content = message.get("content")@@ -1078,10 +1094,12 @@ def relocate_system_messages_to_top_level(field as the issue-765 last-line wire-contract guard.The relocated content is appended after any existing top-level ``system``- so wire order (system prompt, then conversation) is preserved and no content- is dropped. Only text-shaped content moves: non-text blocks (images,- documents) stay in a mid-conversation system section at their original- position, because top-level `system` accepts text blocks only (issue #3552).+ so wire order (system prompt, then conversation) is preserved. Only+ text-shaped content moves: non-text blocks (images, documents) stay in a+ mid-conversation system section at their original position, because+ top-level `system` accepts text blocks only (issue #3552). A leading system+ section cannot stay in ``messages[0]``; non-text blocks there are dropped+ with a warning because they cannot be represented in either valid location.Returns ``(clean_messages, new_system, changed)``. When no system-rolemessage is present the inputs pass through unchanged (``changed=False``) so@@ -1144,26 +1162,52 @@ def relocate_system_messages_to_top_level(relocated_blocks: list[Any] = []retained: dict[int, dict[str, Any]] = {}+ leading_system_indices: set[int] = set()+ for index, message in enumerate(messages):+ if not isinstance(message, dict) or message.get("role") != _ROLE_SYSTEM:+ break+ leading_system_indices.add(index)for i in sorted(system_indices):message = messages[i]content = message.get("content") if isinstance(message, dict) else Noneif isinstance(content, list):# Only text-shaped content may move into the top-level ``system``# parameter (text blocks and bare strings). Non-text blocks such as- # images or documents stay in place so nothing is dropped and- # upstreams that reject non-text system blocks keep working- # (issue #3552).+ # images or documents stay in mid-conversation sections so nothing+ # is dropped and upstreams that reject non-text system blocks keep+ # working (issue #3552). A leading section cannot remain there+ # without violating Anthropic's message contract.hoisted_from_list: list[Any] = []leftovers: list[Any] = []for block in content:- if isinstance(block, dict) and block.get("type") == _TEXT_BLOCK_TYPE:- hoisted_from_list.append(block)+ if isinstance(block, dict):+ if i in leading_system_indices:+ coerced = _coerce_system_block(block)+ if coerced is not None:+ hoisted_from_list.append(coerced)+ else:+ logger.warning(+ "event=system_relocation_block_dropped block_type=%s "+ "reason=not_representable_as_text",+ block.get("type", "missing"),+ )+ elif block.get("type") == _TEXT_BLOCK_TYPE:+ hoisted_from_list.append(block)+ else:+ leftovers.append(block)elif isinstance(block, str) and block:hoisted_from_list.append({"type": _TEXT_BLOCK_TYPE, "text": block})else:- leftovers.append(block)+ if i in leading_system_indices:+ logger.warning(+ "event=system_relocation_block_dropped block_type=%s "+ "reason=not_representable_as_text",+ "string" if isinstance(block, str) else type(block).__name__,+ )+ else:+ leftovers.append(block)relocated_blocks.extend(hoisted_from_list)- if leftovers:+ if leftovers and i not in leading_system_indices:retained[i] = {**message, "content": leftovers}else:# String (and other) content converts losslessly to text blocks.diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.pyindex 0771745d0..f5ea6a0cf 100644--- a/tests/test_proxy_handler_helpers.py+++ b/tests/test_proxy_handler_helpers.py@@ -492,6 +492,123 @@ def test_relocate_system_messages_image_only_sections_pass_through_unchanged() -assert new_system == system+def test_relocate_system_messages_drops_non_text_from_leading_section(+ caplog: pytest.LogCaptureFixture,+) -> None:+ image_block = {+ "type": "image",+ "source": {"type": "base64", "media_type": "image/png", "data": "aGk="},+ }+ cached_text = {+ "type": "text",+ "text": "leading instruction",+ "cache_control": {"type": "ephemeral"},+ }+ messages: list[dict] = [+ {"role": "system", "content": [cached_text, image_block]},+ {"role": "user", "content": "hi"},+ ]++ caplog.set_level("WARNING", logger="headroom.proxy")+ clean, new_system, changed = relocate_system_messages_to_top_level(+ messages, [{"type": "text", "text": "base"}], "claude-opus-5"+ )++ assert changed is True+ assert clean == [{"role": "user", "content": "hi"}]+ assert new_system == [+ {"type": "text", "text": "base"},+ cached_text,+ ]+ assert "event=system_relocation_block_dropped" in caplog.text+ assert "block_type=image" in caplog.text+++def test_relocate_system_messages_drops_all_non_text_leading_section() -> None:+ image_block = {+ "type": "image",+ "source": {"type": "base64", "media_type": "image/png", "data": "aGk="},+ }+ messages: list[dict] = [+ {"role": "system", "content": [image_block]},+ {"role": "user", "content": "hi"},+ ]++ clean, new_system, changed = relocate_system_messages_to_top_level(+ messages, [{"type": "text", "text": "base"}], "claude-opus-5"+ )++ assert changed is True+ assert clean == [{"role": "user", "content": "hi"}]+ assert new_system == [{"type": "text", "text": "base"}]++[email protected]("block_type", ["text", "image", "tool_use", "tool_result", None])+def test_leading_system_text_uses_only_anthropic_text_block_fields(block_type) -> None:+ from copy import deepcopy++ cache_control = {"type": "ephemeral", "ttl": "1h"}+ citations = [+ {+ "type": "char_location",+ "cited_text": "instruction",+ "document_index": 0,+ "document_title": "source",+ "start_char_index": 0,+ "end_char_index": 11,+ }+ ]+ block = {+ "type": block_type,+ "text": "instruction",+ "cache_control": cache_control,+ "citations": citations,+ "source": {"type": "url", "url": "https://example.invalid/image.png"},+ "id": "tool1",+ "name": "read",+ "input": {"path": "file.txt"},+ "tool_use_id": "tool1",+ "is_error": False,+ }+ messages = [+ {"role": "system", "content": [block]},+ {"role": "user", "content": "hi"},+ ]+ original = deepcopy(messages)+ clean, system, changed = relocate_system_messages_to_top_level(messages, None, None)+ assert changed+ assert clean == [{"role": "user", "content": "hi"}]+ assert system == [+ {+ "type": "text",+ "text": "instruction",+ "cache_control": cache_control,+ "citations": citations,+ }+ ]+ assert messages == original+++def test_all_contiguous_leading_system_sections_are_normalized() -> None:+ image = {"type": "image", "source": {"type": "url", "url": "https://example.invalid/a"}}+ clean, system, changed = relocate_system_messages_to_top_level(+ [+ {"role": "system", "content": "first instruction"},+ {"role": "system", "content": [image]},+ {"role": "system", "content": [{"type": "text", "text": "second instruction"}]},+ {"role": "user", "content": "hi"},+ ],+ None,+ None,+ )+ assert changed+ assert clean == [{"role": "user", "content": "hi"}]+ assert system == [+ {"type": "text", "text": "first instruction"},+ {"type": "text", "text": "second instruction"},+ ]++def test_headroom_bypass_helper_is_transport_neutral() -> None:assert _headroom_bypass_enabled({"x-headroom-bypass": "true"}) is Trueassert _headroom_bypass_enabled({"x-headroom-bypass": " TRUE "}) is True