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): preserve OpenAI tool block metadata on cached replay (#4334)
Aliciaf1035ac73788
diff --git a/e2e/wrap/Dockerfile b/e2e/wrap/Dockerfileindex e3fa546d7..c3e1e8484 100644--- a/e2e/wrap/Dockerfile+++ b/e2e/wrap/Dockerfile@@ -93,6 +93,10 @@ RUN npm install -g --no-fund --no-audit [email protected]COPY e2e/wrap/tools/package.json e2e/wrap/tools/package-lock.json /opt/wrap-tools/RUN npm ci --prefix /opt/wrap-tools --no-fund --no-audit+# Exercise the installed dependency fixes in both existing wrap-E2E CI callers.+COPY e2e/wrap/tools/dependency-regression.test.cjs /opt/wrap-tools/+RUN npm test --prefix /opt/wrap-tools+WORKDIR /workspace# Bring in the prebuilt manylinux wheel from stage 1.diff --git a/e2e/wrap/tools/README.md b/e2e/wrap/tools/README.mdindex 34ad5f4fc..48b3ff74b 100644--- a/e2e/wrap/tools/README.md+++ b/e2e/wrap/tools/README.md@@ -17,11 +17,18 @@ OpenClaw version no longer supports Node 22):cd e2e/wrap/toolsnpm install --package-lock-only --no-fund --no-auditnpm ci --no-fund --no-audit+npm testcd ../../..docker build -f e2e/wrap/Dockerfile -t headroom-wrap-e2e .docker run --rm headroom-wrap-e2e```+`npm test` runs the Ajv URI and Express body-parser regression checks against+the installed locked dependencies. The Dockerfile runs the same command from+`/opt/wrap-tools` after `npm ci`, so failures stop the image build in both the+existing Wrap E2E workflow and CI's Docker-native wrap E2E job. Their path+filters include `e2e/**`, covering dependency and regression-test updates.+To intentionally refresh transitive versions without changing the pinned CLIversions, use `npm update --package-lock-only --no-fund --no-audit` in thisdirectory instead of `npm install --package-lock-only`, then run the samediff --git a/e2e/wrap/tools/dependency-regression.test.cjs b/e2e/wrap/tools/dependency-regression.test.cjsnew file mode 100644index 000000000..8078e1935--- /dev/null+++ b/e2e/wrap/tools/dependency-regression.test.cjs@@ -0,0 +1,85 @@+'use strict';+// From e2e/wrap/tools after installing its locked dependencies:+// node --test --test-concurrency=1 --test-reporter=tap dependency-regression.test.cjs+const path = require('node:path');+const { createRequire } = require('node:module');+const fromTools = createRequire(path.join(process.cwd(), 'package.json'));++if (process.argv[2] === '--serve') {+ const express = fromTools('express');+ const app = express();+ app.get('/health', (_req, res) => res.json({ ok: true }));+ app.post('/text', express.text({ verify() {} }), (req, res) => res.json(req.body));+ app.use((error, _req, res, _next) => res.status(error.status || 500).json({ type: error.type }));+ const server = app.listen(0, '127.0.0.1', () => process.send({ port: server.address().port }));+ process.on('message', (message) => {+ if (message === 'stop') { server.close(() => process.exit(0)); server.closeAllConnections(); }+ });+} else {+ const test = require('node:test');+ const assert = require('node:assert/strict');+ const http = require('node:http');+ const { fork } = require('node:child_process');++ test('Ajv rejects a percent-encoded scheme instead of aliasing an HTTPS schema', () => {+ const Ajv = fromTools('ajv');+ const ajv = new Ajv();+ ajv.addSchema({ $id: 'https://example.invalid/defs.json', type: 'integer' });+ const valid = ajv.compile({ $ref: 'https://example.invalid/defs.json' });+ assert.equal(valid(42), true);+ assert.equal(valid('42'), false);+ assert.throws(+ () => ajv.compile({ $ref: '%68ttps://example.invalid/defs.json' }),+ { message: 'URI scheme is malformed.' },+ );+ });++ test('unsupported charset with invalid gzip leaves the Express process healthy', async (t) => {+ const child = fork(__filename, ['--serve'], {+ cwd: process.cwd(), env: process.env, execArgv: [], silent: true,+ });+ let stderr = '';+ child.stdout.resume();+ child.stderr.on('data', (chunk) => { stderr += chunk; });+ t.after(async () => {+ t.diagnostic(JSON.stringify({ exitCode: child.exitCode, signal: child.signalCode, stderr }));+ if (child.exitCode !== null || child.signalCode !== null) return;+ await new Promise((resolve) => {+ const timer = setTimeout(() => { child.kill(); resolve(); }, 1000);+ child.once('exit', () => { clearTimeout(timer); resolve(); });+ if (child.connected) child.send('stop'); else child.kill();+ });+ });+ const port = await new Promise((resolve, reject) => {+ const timer = setTimeout(() => reject(new Error('server startup timeout')), 3000);+ child.once('message', (msg) => { clearTimeout(timer); resolve(msg.port); });+ child.once('error', (err) => { clearTimeout(timer); reject(err); });+ child.once('exit', (code) => { clearTimeout(timer); reject(new Error('server exited: ' + code + stderr)); });+ });+ function request(route, body, headers = {}, method = 'POST') {+ return new Promise((resolve, reject) => {+ const req = http.request({ hostname: '127.0.0.1', port, path: route, method, agent: false,+ headers: { ...headers, 'Content-Length': Buffer.byteLength(body) } }, (res) => {+ const chunks = [];+ res.on('data', (chunk) => chunks.push(chunk));+ res.on('error', reject);+ res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString() }));+ });+ req.setTimeout(2000, () => req.destroy(new Error('localhost request timeout')));+ req.on('error', reject);+ req.end(body);+ });+ }+ const response = await request('/text', 'not-gzip', {+ 'Content-Type': 'text/plain; charset=not-a-real-charset', 'Content-Encoding': 'gzip',+ });+ assert.equal(response.status, 415);+ assert.equal(JSON.parse(response.body).type, 'charset.unsupported');+ // Let a pending zlib error surface before checking the child's health.+ await new Promise((resolve) => setTimeout(resolve, 80));+ assert.equal(child.exitCode, null, stderr);+ const health = await request('/health', '', {}, 'GET');+ assert.equal(health.status, 200);+ assert.deepEqual(JSON.parse(health.body), { ok: true });+ });+}diff --git a/e2e/wrap/tools/package.json b/e2e/wrap/tools/package.jsonindex ac7092236..17f6462f6 100644--- a/e2e/wrap/tools/package.json+++ b/e2e/wrap/tools/package.json@@ -3,6 +3,9 @@"version": "1.0.0","private": true,"description": "Locked CLI dependencies for the Docker wrap E2E harness",+ "scripts": {+ "test": "node --test --test-concurrency=1 --test-reporter=tap dependency-regression.test.cjs"+ },"dependencies": {"@openai/codex": "0.163.0","openclaw": "2026.10.6"diff --git a/headroom/cache/compression_cache.py b/headroom/cache/compression_cache.pyindex a135d7b16..4f3ff7d16 100644--- a/headroom/cache/compression_cache.py+++ b/headroom/cache/compression_cache.py@@ -76,6 +76,28 @@ def _extract_tool_result_content(msg: dict) -> str | None:return None+def _can_swap_tool_result_content(msg: dict) -> bool:+ """Whether replacing extracted text preserves the OpenAI content shape.++ A joined replacement cannot be mapped back to multiple blocks without+ losing boundaries, metadata or media. All rewrite callers must check this+ before extraction, transformation or savings accounting. Anthropic's+ existing tool-result rewrite contract is unchanged.+ """+ if msg.get("role") != "tool":+ return True+ content = msg.get("content")+ if isinstance(content, str):+ return True+ return (+ isinstance(content, list)+ and len(content) == 1+ and isinstance(content[0], dict)+ and content[0].get("type") == "text"+ and isinstance(content[0].get("text"), str)+ )++def _carries_tool_result_text(msg: dict) -> bool:"""Whether any tool result in ``msg`` holds text (both formats)."""if msg.get("role") == "tool":@@ -93,11 +115,19 @@ def _carries_tool_result_text(msg: dict) -> bool:def _swap_tool_result_content(msg: dict, new_content: str) -> dict:- """Deep copy msg and replace tool result content with new_content."""+ """Deep copy and rewrite supported content; preserve unsupported layouts."""new_msg = copy.deepcopy(msg)+ if not _can_swap_tool_result_content(msg):+ return new_msg# OpenAI formatif new_msg.get("role") == "tool":- new_msg["content"] = new_content+ content = new_msg.get("content")+ if isinstance(content, list):+ # The shared guard permits only an unambiguous single text block.+ # Keep its shape and metadata, including gateway cache breakpoints.+ content[0]["text"] = new_content+ else:+ new_msg["content"] = new_contentreturn new_msg# Anthropic formatcontent = new_msg.get("content")@@ -310,10 +340,10 @@ class CompressionCache:"""Count consecutive stable messages from the start.A message is stable if it is a plain user/assistant/system message,- an assistant message with tool_use blocks, a tool_result whose- content hash is already in the cache, or a tool_result with no text- (nothing to replay). The first unstable tool_result (cache miss)- stops the count.+ an assistant message with tool_use blocks, an Anthropic tool_result with no text+ (nothing to replay), or a tool_result whose cached text and shape can+ be replayed. A cache miss or unsupported text shape stops the count.+ A joined text hash alone does not prove shape-safe replay.The trailing message is *always* excluded from the frozen prefix(cap of ``len(messages) - 1``). The trailing message represents@@ -331,6 +361,11 @@ class CompressionCache:count = 0for msg in messages:if _is_tool_result_message(msg):+ # A joined-text cache/stable hash cannot prove replay for+ # shapes that apply_cached deliberately leaves untouched.+ # Anthropic textless results retain their no-rewrite path.+ if not _can_swap_tool_result_content(msg):+ breakcontent = _extract_tool_result_content(msg)if content is not None:h = self.content_hash(content)@@ -364,6 +399,9 @@ class CompressionCache:with self._lock:result: list[dict] = []for msg in messages:+ if not _can_swap_tool_result_content(msg):+ result.append(msg)+ continueif _is_tool_result_message(msg):content = _extract_tool_result_content(msg)if content is not None:diff --git a/headroom/proxy/interceptors/base.py b/headroom/proxy/interceptors/base.pyindex 6f9b689a9..9c7244b32 100644--- a/headroom/proxy/interceptors/base.py+++ b/headroom/proxy/interceptors/base.py@@ -9,6 +9,7 @@ from dataclasses import dataclassfrom typing import Any, Protocol, runtime_checkablefrom headroom.cache.compression_cache import (+ _can_swap_tool_result_content,_extract_tool_result_content,_is_tool_result_message,_swap_tool_result_content,@@ -253,6 +254,10 @@ def apply_to_messages(new_messages.append(msg)continue+ if not _can_swap_tool_result_content(msg):+ new_messages.append(msg)+ continue+original = _extract_tool_result_content(msg)if not isinstance(original, str) or not original:new_messages.append(msg)diff --git a/tests/test_cache_replay_shapes.py b/tests/test_cache_replay_shapes.pynew file mode 100644index 000000000..66f27c1bf--- /dev/null+++ b/tests/test_cache_replay_shapes.py@@ -0,0 +1,165 @@+"""Freeze eligibility must match the bytes the cache can actually replay."""++from __future__ import annotations++import copy+import unittest++from headroom.cache.compression_cache import CompressionCache+from headroom.proxy.session_engine import (+ FREEZE_POLICY_CONFIRMED_CLAMP,+ FREEZE_POLICY_REPLAYABLE,+ prepare_turn,+)+++class TestCacheReplayShapes(unittest.TestCase):+ def setUp(self) -> None:+ self.cache = CompressionCache()+ self.cache.store_compressed(self.cache.content_hash("A\nB"), "short", 1)+ self.blocks = [{"type": "text", "text": "A"}, {"type": "text", "text": "B"}]+ self.messages = [+ {"role": "tool", "tool_call_id": "c1", "content": self.blocks},+ {"role": "user", "content": "next"},+ ]++ def test_multiblock_cache_hit_remains_mutable(self) -> None:+ before = copy.deepcopy(self.messages)+ prep = prepare_turn(self.cache, self.messages, policy=FREEZE_POLICY_REPLAYABLE)+ self.assertEqual(prep.frozen_message_count, 0)+ self.assertEqual(prep.pipeline_input, before)+ self.assertEqual(self.messages, before)+ self.assertEqual(self.cache.get_stats()["hits"], 0)+ self.assertNotIn(self.cache.content_hash("A\nB"), self.cache._stable_hashes)++ def test_stable_joined_hash_does_not_prove_shape_replay(self) -> None:+ self.cache.mark_stable(self.cache.content_hash("A\nB"))+ self.assertEqual(self.cache.compute_frozen_count(self.messages), 0)++ def test_prefix_stops_before_unsupported_shape(self) -> None:+ messages = [{"role": "user", "content": "earlier"}, *self.messages]+ self.assertEqual(self.cache.compute_frozen_count(messages), 1)++ def test_confirmed_policy_is_still_clamped_by_replayability(self) -> None:+ prep = prepare_turn(+ self.cache,+ self.messages,+ policy=FREEZE_POLICY_CONFIRMED_CLAMP,+ tracker_frozen=1,+ )+ self.assertEqual(prep.frozen_message_count, 0)++ def test_explicit_caller_pin_still_wins(self) -> None:+ prep = prepare_turn(+ self.cache, self.messages, policy=FREEZE_POLICY_REPLAYABLE, explicit_frozen=1+ )+ self.assertEqual(prep.frozen_message_count, 1)+ self.assertEqual(prep.pipeline_input, self.messages)++ def test_supported_string_and_single_block_replay(self) -> None:+ for content in ["A\nB", [{"type": "text", "text": "A\nB", "custom": [1]}]]:+ with self.subTest(content=content):+ messages = [{"role": "tool", "content": content}, self.messages[-1]]+ prep = prepare_turn(self.cache, messages, policy=FREEZE_POLICY_REPLAYABLE)+ self.assertEqual(prep.frozen_message_count, 1)+ expected = (+ "short"+ if isinstance(content, str)+ else [{"type": "text", "text": "short", "custom": [1]}]+ )+ self.assertEqual(prep.pipeline_input[0]["content"], expected)++ def test_anthropic_replay_contract_is_unchanged(self) -> None:+ content = [{"type": "tool_result", "tool_use_id": "c1", "content": "A\nB"}]+ prep = prepare_turn(+ self.cache,+ [{"role": "user", "content": content}, self.messages[-1]],+ policy=FREEZE_POLICY_REPLAYABLE,+ )+ self.assertEqual(prep.frozen_message_count, 1)+ self.assertEqual(prep.pipeline_input[0]["content"][0]["content"], "short")++ def test_malformed_and_media_shapes_remain_mutable(self) -> None:+ for content in [+ None,+ {},+ [],+ [{"type": "text", "text": 7}],+ [+ {"type": "image_url", "image_url": {"url": "synthetic"}},+ {"type": "text", "text": "A\nB"},+ ],+ ]:+ with self.subTest(content=content):+ messages = [{"role": "tool", "content": content}, self.messages[-1]]+ self.assertEqual(self.cache.compute_frozen_count(messages), 0)++ def test_textless_anthropic_prefix_stops_at_unsupported_openai_shape(self) -> None:+ textless = {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "t0", "content": []}],+ }+ for blocks in [+ self.blocks,+ [+ {"type": "image_url", "image_url": {"url": "synthetic"}},+ {"type": "text", "text": "A\nB"},+ ],+ ]:+ with self.subTest(blocks=blocks):+ messages = [textless, {"role": "tool", "content": blocks}, self.messages[-1]]+ before = copy.deepcopy(messages)+ stats_before = self.cache.get_stats()+ prep = prepare_turn(self.cache, messages, policy=FREEZE_POLICY_REPLAYABLE)+ self.assertEqual(prep.frozen_message_count, 1)+ self.assertEqual(prep.pipeline_input, before)+ self.assertEqual(messages, before)+ self.assertEqual(self.cache.get_stats()["hits"], 0)+ self.assertEqual(+ self.cache.get_stats()["tokens_saved"], stats_before["tokens_saved"]+ )++ def test_textless_anthropic_prefix_still_obeys_confirmed_clamp(self) -> None:+ textless = {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "t0", "content": []}],+ }+ messages = [textless, *self.messages]+ for confirmed in [0, 1, 2]:+ with self.subTest(confirmed=confirmed):+ prep = prepare_turn(+ self.cache,+ messages,+ policy=FREEZE_POLICY_CONFIRMED_CLAMP,+ tracker_frozen=confirmed,+ )+ self.assertEqual(prep.frozen_message_count, min(confirmed, 1))++ def test_cached_text_after_textless_anthropic_result_remains_mutable(self) -> None:+ messages = [+ {+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": "t0", "content": []},+ {"type": "tool_result", "tool_use_id": "t1", "content": "A\nB"},+ ],+ },+ self.messages[-1],+ ]+ before = copy.deepcopy(messages)+ prep = prepare_turn(self.cache, messages, policy=FREEZE_POLICY_REPLAYABLE)+ self.assertEqual(prep.frozen_message_count, 0)+ self.assertEqual(prep.pipeline_input, before)+ self.assertEqual(messages, before)+ self.assertEqual(self.cache.get_stats()["hits"], 0)++ def test_supported_stable_hash_and_trailing_live_zone_are_unchanged(self) -> None:+ cache = CompressionCache()+ cache.mark_stable(cache.content_hash("stable"))+ messages = [{"role": "tool", "content": "stable"}, self.messages[-1]]+ self.assertEqual(cache.compute_frozen_count(messages), 1)+ self.assertEqual(cache.compute_frozen_count(messages[:1]), 0)+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_compression_cache.py b/tests/test_compression_cache.pyindex 4859ff770..9b9022143 100644--- a/tests/test_compression_cache.py+++ b/tests/test_compression_cache.py@@ -455,6 +455,53 @@ class TestCompressionCacheFrozenCount:class TestCompressionCacheApplyAndUpdate:+ @pytest.mark.parametrize(+ "metadata",+ [{}, {"cache_control": {"type": "ephemeral", "ttl": "1h"}}, {"custom": {"nested": [1, 2]}}],+ )+ def test_openai_cached_text_block_preserves_shape_and_metadata(self, metadata: dict) -> None:+ import copy++ cache = CompressionCache()+ original = "synthetic records " * 50+ older = {"role": "tool", "tool_call_id": "old", "content": original}+ cache.update_from_result([older], [{**older, "content": "short output"}])+ message = {+ "role": "tool",+ "tool_call_id": "new",+ "content": [{"type": "text", "text": original, **metadata}],+ }+ snapshot = copy.deepcopy(message)++ result = cache.apply_cached([message])[0]++ assert result == {**message, "content": [{**message["content"][0], "text": "short output"}]}+ assert message == snapshot+ assert result is not message+ assert result["content"][0] is not message["content"][0]++ @pytest.mark.parametrize(+ "extra",+ [+ {"type": "text", "text": "second", "cache_control": {"type": "ephemeral"}},+ {"type": "image_url", "image_url": {"url": "https://example.com/synthetic.png"}},+ {"type": "unknown", "value": "keep me"},+ ],+ )+ def test_openai_cached_multiblock_content_is_not_collapsed(self, extra: dict) -> None:+ import copy++ cache = CompressionCache()+ blocks = [{"type": "text", "text": "first"}, extra]+ text = "first\nsecond" if extra["type"] == "text" else "first"+ cache.store_compressed(cache.content_hash(text), "short", tokens_saved=1)+ message = {"role": "tool", "tool_call_id": "new", "content": blocks}+ snapshot = copy.deepcopy(message)++ assert cache.apply_cached([message]) == [snapshot]+ assert message == snapshot+ assert cache.get_stats()["hits"] == 0+def test_apply_cached_swaps_tool_results(self, cache: CompressionCache) -> None:original_content = "big tool output"h = CompressionCache.content_hash(original_content)@@ -851,3 +898,33 @@ def test_get_compression_cache_returns_same_instance_under_contention() -> None:first = results[0]for c in results[1:]:assert c is first, "Concurrent _get_compression_cache returned different instances"+++ "content",+ [+ [{"type": "text", "text": "first"}, {"type": "text", "text": "second"}],+ [+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}},+ {"type": "text", "text": "second"},+ ],+ [],+ ["not a block"],+ [{"type": "text"}],+ [{"type": "text", "text": 42}],+ ],+)+def test_shared_swap_and_cache_preserve_unsupported_openai_blocks(content):+ from copy import deepcopy++ from headroom.cache.compression_cache import _swap_tool_result_content++ message = {"role": "tool", "content": content}+ original = deepcopy(message)+ assert _swap_tool_result_content(message, "short") == original+ cache = CompressionCache()+ cache.store_compressed(cache.content_hash("first\nsecond"), "short", tokens_saved=10)+ before = cache.get_stats().copy()+ assert cache.apply_cached([message]) == [original]+ assert cache.get_stats() == before+ assert message == originaldiff --git a/tests/test_read_maturation_handler_nobust.py b/tests/test_read_maturation_handler_nobust.pyindex 2ff6cd973..8b5341353 100644--- a/tests/test_read_maturation_handler_nobust.py+++ b/tests/test_read_maturation_handler_nobust.py@@ -367,9 +367,8 @@ DEFERRED_TOOL = {def _tool_search_convo(nquiet: int) -> list[dict]:"""``_busy_convo`` after a ToolSearch whose result holds only tool_reference- blocks, as Claude Code loads deferred tools. The compression cache reads no- text from that result, so its count never passes it, however much of the- later tool output compresses."""+ blocks, as Claude Code loads deferred tools. Such textless results are+ stable; tests must not rely on them stopping the local replay window."""msgs = _busy_convo(nquiet)search = [{@@ -434,23 +433,46 @@ def _record_pipeline_freeze(monkeypatch) -> list[int]:@pytest.mark.parametrize(("convo", "tools", "pipeline_stop"),[- # Nothing compresses, so the compression cache never stores the Read.+ # Both input shapes exercise the same explicitly bounded local cache.(_convo, [READ_TOOL], 2),- # Tool output compresses, but the count stops at the ToolSearch result.(_tool_search_convo, [READ_TOOL, DEFERRED_TOOL], 2),],ids=["quiet", "tool-reference"],)-def test_read_inside_the_cached_prefix_stays_verbatim(monkeypatch, convo, tools, pipeline_stop):[email protected]("cache_hits", [True, False], ids=["provider-cached", "provider-uncached"])+def test_read_inside_the_cached_prefix_stays_verbatim(+ monkeypatch, convo, tools, pipeline_stop, cache_hits+):"""By the time the Read's file quiesces the provider has cached it, somaturing it would re-write the cache from the Read onward. The pipeline'sown freeze stops below the Read here; maturation must follow the- provider-confirmed floor that finalize_turn replays instead."""+ provider-confirmed floor that finalize_turn replays instead. The uncached+ control must still mature, so retaining the Read cannot pass vacuously."""+ from headroom.cache.compression_cache import CompressionCachefrom headroom.cache.compression_store import reset_compression_store+ from headroom.transforms.read_maturation import ReadMaturationManagermonkeypatch.setenv("HEADROOM_CCR_BACKEND", "memory")reset_compression_store()+ # Explicitly model a local replay window shorter than the provider's+ # confirmed prefix (e.g. after local cache eviction). Keep real preparation+ # and tracking; do not depend on any particular tool-result shape being a+ # cache miss. Textless ToolSearch results are legitimately stable now.+ compute_frozen = CompressionCache.compute_frozen_count++ def _bounded_local_replay(self, messages):+ return min(compute_frozen(self, messages), pipeline_stop)++ monkeypatch.setattr(CompressionCache, "compute_frozen_count", _bounded_local_replay)pipeline_freeze = _record_pipeline_freeze(monkeypatch)+ maturation_freeze: list[int] = []+ apply = ReadMaturationManager.apply++ def _recording_apply(self, messages, frozen_message_count=0):+ maturation_freeze.append(frozen_message_count)+ return apply(self, messages, frozen_message_count=frozen_message_count)++ monkeypatch.setattr(ReadMaturationManager, "apply", _recording_apply)config = ProxyConfig(optimize=True,read_maturation=True,@@ -462,12 +484,30 @@ def test_read_inside_the_cached_prefix_stays_verbatim(monkeypatch, convo, tools,)forwarded = _drive_session(- config, n_turns=8, session_id="cached-read-2", convo=convo, tools=tools+ config,+ n_turns=8,+ session_id="cached-read-2",+ convo=convo,+ tools=tools,+ cache_hits=cache_hits,)assert pipeline_freeze and max(pipeline_freeze) <= pipeline_stop, (f"fixture must keep the pipeline freeze below the Read: {pipeline_freeze}")+ assert len(forwarded) == 8, "every turn must reach the upstream"+ read_at = next(i for i, msg in enumerate(convo(0)) if _read_result_content(msg) is not None)+ assert pipeline_stop <= read_at, "the local replay window must exclude the held Read"+ if not cache_hits:+ assert maturation_freeze and not any(maturation_freeze)+ assert _first_matured_turn(forwarded) is not None, "uncached control never matured"+ return+ assert len(maturation_freeze) == 8 and all(f > read_at for f in maturation_freeze[1:]), (+ f"provider-confirmed maturation floor must protect the Read: {maturation_freeze}"+ )+ assert all(_read_result_content(msgs[read_at]) == BIG for msgs in forwarded), (+ "the held Read must remain present and verbatim on every turn"+ )assert _first_matured_turn(forwarded) is None, "a cached Read was matured"assert not _prefix_rewrites(forwarded), "the forwarded cached prefix changed"diff --git a/tests/test_token_headroom_mode.py b/tests/test_token_headroom_mode.pyindex 2198aba39..9bba8d399 100644--- a/tests/test_token_headroom_mode.py+++ b/tests/test_token_headroom_mode.py@@ -528,8 +528,12 @@ class TestSwapToolResultListContent:from headroom.cache.compression_cache import _swap_tool_result_contentmsg = _make_openai_tool_list_content_msg("tc1", ["original"])+ msg["content"][0]["cache_control"] = {"type": "ephemeral"}swapped = _swap_tool_result_content(msg, "compressed")- assert swapped["content"] == "compressed"+ assert swapped["content"] == [+ {"type": "text", "text": "compressed", "cache_control": {"type": "ephemeral"}}+ ]+ assert msg["content"][0]["text"] == "original"def test_swap_does_not_mutate_original(self):"""_swap_tool_result_content performs a deep copy."""diff --git a/tests/test_tool_result_interceptors.py b/tests/test_tool_result_interceptors.pyindex 4fe419355..f606749d7 100644--- a/tests/test_tool_result_interceptors.py+++ b/tests/test_tool_result_interceptors.py@@ -1307,3 +1307,100 @@ def test_proxy_pipeline_excludes_interceptor_when_env_not_set(monkeypatch):for pipeline in (proxy.anthropic_pipeline, proxy.openai_pipeline):transforms = pipeline.transformsassert not any(isinstance(t, ToolResultInterceptorTransform) for t in transforms)+++ "content",+ [+ [+ {"type": "text", "text": "first long block " * 20},+ {"type": "text", "text": "second long block " * 20},+ ],+ [+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,AA=="}},+ {"type": "text", "text": "long text " * 40},+ ],+ [],+ ["not a block"],+ [{"type": "text"}],+ [{"type": "text", "text": 42}],+ ],+)+def test_unsupported_openai_blocks_skip_interceptors_and_savings(content, tokenizer, monkeypatch):+ from copy import deepcopy++ class Shortener:+ name = "shape-regression"+ calls = 0++ def progressive_disclosure_key(self, *_):+ self.calls += 1+ return "same-key"++ def matches(self, *_):+ self.calls += 1+ return True++ def transform(self, *_):+ self.calls += 1+ return "short"++ interceptor = Shortener()+ monkeypatch.setattr("headroom.proxy.interceptors.base.INTERCEPTORS", [interceptor])+ unsupported = {"role": "tool", "tool_call_id": "1", "content": content}+ snapshot = deepcopy(unsupported)+ result = apply_to_messages([unsupported], tokenizer)+ assert result.messages == [snapshot]+ assert result.messages[0] is unsupported+ assert result.spans == []+ assert interceptor.calls == 0+ assert unsupported == snapshot+ pipeline_result = ToolResultInterceptorTransform().apply([unsupported], tokenizer)+ assert pipeline_result.messages == [snapshot]+ assert pipeline_result.transforms_applied == []+ assert pipeline_result.tokens_before == pipeline_result.tokens_after+ assert interceptor.calls == 0++ # A skipped layout must not consume progressive-disclosure state.+ valid = {"role": "tool", "tool_call_id": "2", "content": "long output " * 40}+ result = apply_to_messages([unsupported, valid], tokenizer)+ assert result.messages[0] == snapshot+ assert result.messages[1]["content"] == "short"+ assert len(result.spans) == 1+ assert interceptor.calls == 3+++def test_single_openai_text_block_interceptor_preserves_metadata(tokenizer, monkeypatch):+ from copy import deepcopy++ class Shortener:+ name = "metadata-regression"++ def matches(self, *_):+ return True++ def transform(self, *_):+ return "short"++ monkeypatch.setattr("headroom.proxy.interceptors.base.INTERCEPTORS", [Shortener()])+ message = {+ "role": "tool",+ "tool_call_id": "1",+ "content": [+ {+ "type": "text",+ "text": "long output " * 40,+ "cache_control": {"type": "ephemeral", "ttl": "1h"},+ "metadata": {"nested": [1, 2]},+ }+ ],+ }+ original = deepcopy(message)+ result = apply_to_messages([message], tokenizer)+ expected = deepcopy(message)+ expected["content"][0]["text"] = "short"+ assert result.messages == [expected]+ assert len(result.spans) == 1+ assert result.spans[0].tokens_saved > 0+ result.messages[0]["content"][0]["metadata"]["nested"].append(3)+ assert message == original