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.

fix(proxy): compress OpenCode tool schemas and embedded JSON (#1535)

vscunha05932d716567
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index a68d1f475..0fbbfa4b1 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -3189,6 +3189,21 @@ class OpenAIHandlerMixin:
if remembered_event.tools is not None:
tools = remembered_event.tools
+ tool_tokens_before_compaction = 0
+ tool_tokens_after_compaction = 0
+ if _decision.should_compress and not _bypass and tools is not None:
+ try:
+ compacted_tool_payload, tools_modified, _, _ = _compact_openai_responses_tools(
+ {"tools": tools}
+ )
+ if tools_modified and compacted_tool_payload.get("tools") is not None:
+ tool_tokens_before_compaction = tokenizer.count_text(_json_debug_dumps(tools))
+ tools = compacted_tool_payload["tools"]
+ if "openai:chat:tool_schema_compaction" not in transforms_applied:
+ transforms_applied.append("openai:chat:tool_schema_compaction")
+ except Exception as e:
+ logger.debug(f"[{request_id}] tool schema compaction failed: {e}")
+
body["messages"] = optimized_messages
if tools or _original_tools is not None:
body["tools"] = tools
@@ -3213,6 +3228,14 @@ class OpenAIHandlerMixin:
if presend_event.headers is not None:
headers = presend_event.headers
optimized_tokens = tokenizer.count_messages(body["messages"])
+ if tool_tokens_before_compaction > 0:
+ try:
+ tool_tokens_after_compaction = tokenizer.count_text(_json_debug_dumps(tools))
+ except Exception:
+ tool_tokens_after_compaction = tool_tokens_before_compaction
+ if 0 < tool_tokens_after_compaction < tool_tokens_before_compaction:
+ original_tokens += tool_tokens_before_compaction
+ optimized_tokens += tool_tokens_after_compaction
tokens_saved = original_tokens - optimized_tokens
# Turn hooks (opt-in extensions): a registered hook may rewrite the
diff --git a/headroom/transforms/mixed_content.py b/headroom/transforms/mixed_content.py
index bd9387265..6991c1acb 100644
--- a/headroom/transforms/mixed_content.py
+++ b/headroom/transforms/mixed_content.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import json
import re
from dataclasses import dataclass
@@ -36,11 +37,37 @@ def mixed_content_indicators(content: str) -> dict[str, bool]:
return {
"has_code_fences": bool(_CODE_FENCE_PATTERN.search(content)),
"has_json_blocks": bool(_JSON_BLOCK_START.search(content)),
+ "has_embedded_json_with_text": _has_valid_json_block_with_text(content),
"has_prose": len(_PROSE_PATTERN.findall(content)) > 5,
"has_search_results": bool(_SEARCH_RESULT_PATTERN.search(content)),
}
+def _has_valid_json_block_with_text(content: str) -> bool:
+ """Return true when prose or log text wraps a valid JSON block."""
+ lines = content.split("\n")
+
+ for index, line in enumerate(lines):
+ if not line.strip().startswith(("[", "{")):
+ continue
+
+ json_content, end_index = _extract_json_block(lines, index)
+ if json_content is None:
+ continue
+
+ try:
+ json.loads(json_content)
+ except (TypeError, ValueError):
+ continue
+
+ leading_text = "\n".join(lines[:index]).strip()
+ trailing_text = "\n".join(lines[end_index + 1 :]).strip()
+ if leading_text or trailing_text:
+ return True
+
+ return False
+
+
def split_into_sections(content: str) -> list[ContentSection]:
"""Parse mixed content into typed sections."""
sections: list[ContentSection] = []
diff --git a/tests/test_proxy_openai_cache_stability.py b/tests/test_proxy_openai_cache_stability.py
index 4cbd18d5d..813155a3f 100644
--- a/tests/test_proxy_openai_cache_stability.py
+++ b/tests/test_proxy_openai_cache_stability.py
@@ -369,3 +369,86 @@ def test_issue_327_openai_handler_does_not_call_walker_functions() -> None:
# Sanity: the safe positional methods DID fire.
assert "compute_frozen_count" in method_names
assert "apply_cached" in method_names
+
+
+def test_openai_chat_completions_compacts_tools_when_profile_enabled() -> None:
+ captured = {}
+ with _make_proxy_client() as client:
+ proxy = client.app.state.proxy
+ proxy.config.optimize = True
+ proxy.config.mode = "token"
+ proxy.config.savings_profile = "agent-90"
+
+ def _fake_apply(**kwargs): # noqa: ANN003
+ return SimpleNamespace(
+ messages=kwargs["messages"],
+ transforms_applied=[],
+ timing={},
+ tokens_before=10,
+ tokens_after=10,
+ waste_signals=None,
+ )
+
+ proxy.openai_pipeline.apply = _fake_apply
+
+ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
+ captured["body"] = body
+ return httpx.Response(
+ 200,
+ json={
+ "id": "chatcmpl_tools",
+ "choices": [
+ {
+ "index": 0,
+ "message": {"role": "assistant", "content": "ok"},
+ "finish_reason": "stop",
+ }
+ ],
+ "usage": {"prompt_tokens": 500, "completion_tokens": 3, "total_tokens": 503},
+ },
+ )
+
+ proxy._retry_request = _fake_retry
+ verbose_schema_note = "schema annotation repeated for opencode tool definitions " * 50
+ tools = [
+ {
+ "type": "function",
+ "function": {
+ "name": "read_file",
+ "description": "read file helper",
+ "parameters": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "ReadFileParameters",
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string",
+ "title": "Path",
+ "description": verbose_schema_note,
+ "examples": [verbose_schema_note],
+ }
+ },
+ "required": ["path"],
+ },
+ },
+ }
+ ]
+
+ response = client.post(
+ "/v1/chat/completions",
+ headers={"authorization": "Bearer test-key"},
+ json={
+ "model": "gpt-4o-mini",
+ "messages": [{"role": "user", "content": "inspect this file"}],
+ "tools": tools,
+ },
+ )
+
+ assert response.status_code == 200
+ assert "openai:chat:tool_schema_compaction" in response.headers["x-headroom-transforms"]
+ assert int(response.headers["x-headroom-tokens-saved"]) > 0
+ sent_params = captured["body"]["tools"][0]["function"]["parameters"]
+ assert "$schema" not in sent_params
+ assert "title" not in sent_params
+ assert "title" not in sent_params["properties"]["path"]
+ assert "examples" not in sent_params["properties"]["path"]
diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.py
index 8dc439acd..2f333e911 100644
--- a/tests/test_transforms_content_router.py
+++ b/tests/test_transforms_content_router.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import json
from types import SimpleNamespace
import pytest
@@ -191,6 +192,44 @@ def test_mixed_content_section_splitting_and_json_extraction() -> None:
assert _extract_json_block(["{", '"a": 1'], 0) == (None, 0)
+def test_short_instruction_with_embedded_json_compresses_without_kompress() -> None:
+ rows = [
+ {
+ "id": i,
+ "source": "opencode",
+ "status": "ok",
+ "message": "routine event with repeated fields",
+ "needle": "CRITICAL_NEEDLE_42" if i == 17 else "ordinary",
+ }
+ for i in range(40)
+ ]
+ content = "\n".join(
+ [
+ "Compress this OpenCode context. Preserve critical values.",
+ json.dumps(rows, indent=2),
+ "Return a concise answer.",
+ ]
+ )
+ router = ContentRouter(
+ ContentRouterConfig(
+ enable_kompress=False,
+ skip_user_messages=False,
+ )
+ )
+
+ assert is_mixed_content(content) is True
+ assert router._determine_strategy(content) is CompressionStrategy.MIXED
+
+ result = router.compress(content, context="CRITICAL_NEEDLE_42 opencode")
+
+ assert result.strategy_used is CompressionStrategy.MIXED
+ assert result.tokens_saved > 0
+ assert "CRITICAL_NEEDLE_42" in result.compressed
+ assert any(
+ decision.strategy is CompressionStrategy.SMART_CRUSHER for decision in result.routing_log
+ )
+
+
def test_extract_json_block_ignores_brackets_inside_strings() -> None:
"""Brackets/braces inside JSON string values must not end the block early.