Skip to content

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.

refactor(proxy): extract tool definition serialization (#1998)

JD Davisad6ab48cbb2a
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index 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]) -> byte
follow-up turn must inject byte-equal output to keep the prefix
cache 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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)