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
refactor(proxy): extract tool definition serialization (#1998)
JD Davisad6ab48cbb2a
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 9ef60455b..c6250adf1 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -64,7 +64,9 @@ from headroom.proxy.body_forwarding import (from headroom.proxy.body_forwarding import (prepare_outbound_body_bytes as prepare_outbound_body_bytes, # noqa: F401 - compatibility export)-from headroom.proxy.body_forwarding import serialize_body_canonical+from headroom.proxy.body_forwarding import (+ serialize_body_canonical as serialize_body_canonical, # noqa: F401 - compatibility export+)from headroom.proxy.ccr_golden_policy import (create_fresh_ccr_tool_definition,replay_golden_ccr_tool_definition,@@ -88,6 +90,9 @@ from headroom.proxy.memory_golden_policy import (replay_golden_memory_tool_definition,serialize_memory_tool_definition_canonical,)+from headroom.proxy.tool_definition_serialization import (+ serialize_tool_definition_canonical as _serialize_tool_definition_canonical,+)from headroom.proxy.tool_injection_config import (ToolInjectionStickyMode,)@@ -1856,7 +1861,7 @@ def serialize_tool_definition_canonical(tool_definition: dict[str, Any]) -> bytefollow-up turn must inject byte-equal output to keep the prefixcache hot."""- return serialize_body_canonical(tool_definition)+ return _serialize_tool_definition_canonical(tool_definition)class SessionToolTracker(_SessionToolTracker):diff --git a/headroom/proxy/tool_definition_serialization.py b/headroom/proxy/tool_definition_serialization.pynew file mode 100644index 000000000..a2b7fe4fa--- /dev/null+++ b/headroom/proxy/tool_definition_serialization.py@@ -0,0 +1,16 @@+"""Canonical byte serialization for sticky memory tool definitions."""++from __future__ import annotations++import json+from typing import Any+++def serialize_tool_definition_canonical(tool_definition: dict[str, Any]) -> bytes:+ """Serialize a tool definition to deterministic compact UTF-8 JSON bytes."""++ return json.dumps(+ tool_definition,+ ensure_ascii=False,+ separators=(",", ":"),+ ).encode("utf-8")diff --git a/tests/test_tool_definition_serialization.py b/tests/test_tool_definition_serialization.pynew file mode 100644index 000000000..82337228c--- /dev/null+++ b/tests/test_tool_definition_serialization.py@@ -0,0 +1,32 @@+from __future__ import annotations++from headroom.proxy.body_forwarding import serialize_body_canonical+from headroom.proxy.tool_definition_serialization import serialize_tool_definition_canonical+++def test_serialize_tool_definition_canonical_uses_compact_separators() -> None:+ tool = {"name": "memory_save", "input_schema": {"type": "object"}}++ assert serialize_tool_definition_canonical(tool) == (+ b'{"name":"memory_save","input_schema":{"type":"object"}}'+ )+++def test_serialize_tool_definition_canonical_preserves_unicode() -> None:+ tool = {"name": "memory_save", "description": "remember cafe notes"}+ tool["description"] = "remember caf\u00e9 notes"++ assert b"caf\xc3\xa9" in serialize_tool_definition_canonical(tool)+++def test_serialize_tool_definition_canonical_preserves_insertion_order() -> None:+ first = {"name": "memory_save", "description": "desc"}+ second = {"description": "desc", "name": "memory_save"}++ assert serialize_tool_definition_canonical(first) != serialize_tool_definition_canonical(second)+++def test_serialize_tool_definition_canonical_matches_body_canonicalizer() -> None:+ tool = {"name": "memory_save", "input_schema": {"type": "object"}}++ assert serialize_tool_definition_canonical(tool) == serialize_body_canonical(tool)