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.

Add Read Lifecycle: event-driven stale/superseded Read detection

chopratejasbc2d4bd6b6c9
diff --git a/headroom/config.py b/headroom/config.py
index 56d28178f..081fe5eef 100644
--- a/headroom/config.py
+++ b/headroom/config.py
@@ -365,6 +365,34 @@ DEFAULT_EXCLUDE_TOOLS: frozenset[str] = frozenset(
}
)
+# Tool names recognized as Read/Edit/Write for lifecycle tracking
+_READ_TOOL_NAMES: frozenset[str] = frozenset({"Read", "read"})
+_EDIT_TOOL_NAMES: frozenset[str] = frozenset({"Edit", "edit"})
+_WRITE_TOOL_NAMES: frozenset[str] = frozenset({"Write", "write"})
+_MUTATING_TOOL_NAMES: frozenset[str] = _EDIT_TOOL_NAMES | _WRITE_TOOL_NAMES
+
+
+@dataclass
+class ReadLifecycleConfig:
+ """Event-driven Read lifecycle management.
+
+ Detects stale and superseded Read outputs in the conversation and replaces
+ them with compact markers + CCR hashes. Fresh Reads are never touched.
+
+ A Read is STALE when the file was subsequently edited (content is factually
+ wrong). A Read is SUPERSEDED when the file was subsequently re-Read (content
+ is redundant). Both are provably safe to compress.
+
+ Operates as a pre-processing pass before ContentRouter, independent of
+ tool exclusion logic. Read remains in DEFAULT_EXCLUDE_TOOLS — fresh Read
+ outputs still bypass ContentRouter compression.
+ """
+
+ enabled: bool = False # Opt-in; default preserves backward-compatible behavior
+ compress_stale: bool = True # Replace Reads of files that were later edited
+ compress_superseded: bool = True # Replace Reads of files that were later re-Read
+ min_size_bytes: int = 512 # Skip tiny Read outputs (not worth the overhead)
+
@dataclass
class CompressionProfile:
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 93a1ad6ea..f1d4231d9 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -42,7 +42,7 @@ from dataclasses import dataclass, field
from enum import Enum
from typing import Any
-from ..config import DEFAULT_EXCLUDE_TOOLS, TransformResult
+from ..config import DEFAULT_EXCLUDE_TOOLS, ReadLifecycleConfig, TransformResult
from ..tokenizer import Tokenizer
from .base import Transform
from .content_detector import ContentType, DetectionResult, detect_content_type
@@ -292,6 +292,9 @@ class ContentRouterConfig:
# Set to None to use DEFAULT_EXCLUDE_TOOLS, or provide custom set
exclude_tools: set[str] | None = None
+ # Read lifecycle management (stale/superseded detection)
+ read_lifecycle: ReadLifecycleConfig = field(default_factory=ReadLifecycleConfig)
+
# Per-tool compression profiles (tool_name → CompressionProfile)
# Set to None to use DEFAULT_TOOL_PROFILES from config
tool_profiles: dict[str, Any] | None = None
@@ -1171,6 +1174,23 @@ class ContentRouter(Transform):
Returns:
TransformResult with routed and compressed messages.
"""
+ # Pre-process: Read lifecycle management (stale/superseded detection)
+ if self.config.read_lifecycle.enabled:
+ from .read_lifecycle import ReadLifecycleManager
+
+ lifecycle_mgr = ReadLifecycleManager(
+ self.config.read_lifecycle,
+ compression_store=kwargs.get("compression_store"),
+ )
+ lifecycle_result = lifecycle_mgr.apply(messages)
+ messages = lifecycle_result.messages
+ # lifecycle transforms tracked separately, merged at the end
+ lifecycle_transforms = lifecycle_result.transforms_applied
+ lifecycle_ccr_hashes = lifecycle_result.ccr_hashes
+ else:
+ lifecycle_transforms = []
+ lifecycle_ccr_hashes = []
+
tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)
context = kwargs.get("context", "")
hook_biases: dict[int, float] = kwargs.get("biases") or {}
@@ -1284,11 +1304,13 @@ class ContentRouter(Transform):
tokenizer.count_text(str(m.get("content", ""))) for m in transformed_messages
)
+ all_transforms = lifecycle_transforms + transforms_applied
return TransformResult(
messages=transformed_messages,
tokens_before=tokens_before,
tokens_after=tokens_after,
- transforms_applied=transforms_applied if transforms_applied else ["router:noop"],
+ transforms_applied=all_transforms if all_transforms else ["router:noop"],
+ markers_inserted=lifecycle_ccr_hashes,
warnings=warnings,
)
diff --git a/headroom/transforms/read_lifecycle.py b/headroom/transforms/read_lifecycle.py
new file mode 100644
index 000000000..e83d91ce2
--- /dev/null
+++ b/headroom/transforms/read_lifecycle.py
@@ -0,0 +1,421 @@
+"""Event-driven Read lifecycle management.
+
+Detects stale and superseded Read tool outputs in conversation messages and
+replaces them with compact markers + CCR hashes. Fresh Reads are never touched.
+
+A Read becomes STALE when its file is subsequently edited — the content in
+context is factually wrong. A Read becomes SUPERSEDED when the same file is
+re-Read — the content is redundant. Both are provably safe to replace.
+
+Real-world data shows 75% of Read output bytes fall into these two categories:
+- 67% stale (file edited after Read)
+- 12% superseded (file re-Read later)
+- Only 20% are fresh (untouched)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from collections import defaultdict
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from ..config import (
+ _MUTATING_TOOL_NAMES,
+ _READ_TOOL_NAMES,
+ ReadLifecycleConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ReadState(str, Enum):
+ """Lifecycle state of a Read output."""
+
+ FRESH = "fresh" # Latest read, no subsequent edit — leave untouched
+ STALE = "stale" # File was edited after this Read — content is wrong
+ SUPERSEDED = "superseded" # File was re-Read after this Read — content is redundant
+
+
+@dataclass
+class FileOperation:
+ """A single file operation observed in the conversation."""
+
+ msg_index: int # Position in messages[]
+ tool_call_id: str
+ tool_name: str
+ file_path: str
+ operation: str # "read" | "edit" | "write"
+ content_size: int = 0 # Size of tool_result content (for reads only)
+
+
+@dataclass
+class ReadClassification:
+ """Classification of a single Read output."""
+
+ msg_index: int
+ tool_call_id: str
+ file_path: str
+ state: ReadState
+ content_size: int
+
+
+@dataclass
+class ReadLifecycleResult:
+ """Output of lifecycle management pass."""
+
+ messages: list[dict[str, Any]]
+ reads_total: int = 0
+ reads_stale: int = 0
+ reads_superseded: int = 0
+ reads_fresh: int = 0
+ bytes_before: int = 0
+ bytes_after: int = 0
+ transforms_applied: list[str] = field(default_factory=list)
+ ccr_hashes: list[str] = field(default_factory=list)
+
+
+class ReadLifecycleManager:
+ """Event-driven Read lifecycle management.
+
+ Pre-processes messages[] to identify and replace stale/superseded Read outputs.
+ Operates before ContentRouter, independent of tool exclusion logic.
+ """
+
+ def __init__(
+ self,
+ config: ReadLifecycleConfig,
+ compression_store: Any | None = None,
+ ):
+ self.config = config
+ self.store = compression_store
+
+ def apply(self, messages: list[dict[str, Any]]) -> ReadLifecycleResult:
+ """Apply lifecycle management to messages.
+
+ Single-pass analysis, targeted replacement of stale/superseded Reads.
+ """
+ if not self.config.enabled:
+ return ReadLifecycleResult(messages=messages)
+
+ # Phase 1: Build tool metadata and file operation index
+ tool_metadata = self._build_tool_metadata(messages)
+ file_ops = self._build_file_operation_index(messages, tool_metadata)
+
+ # Phase 2: Classify each Read
+ classifications = self._classify_reads(file_ops)
+
+ if not classifications:
+ return ReadLifecycleResult(messages=messages)
+
+ # Phase 3: Replace stale/superseded content
+ return self._apply_lifecycle(messages, classifications)
+
+ def _build_tool_metadata(
+ self, messages: list[dict[str, Any]]
+ ) -> dict[str, tuple[str, str | None]]:
+ """Build tool_call_id → (tool_name, file_path) mapping.
+
+ Scans assistant messages for tool calls, extracts name and file_path
+ from tool inputs. Handles both OpenAI and Anthropic formats.
+ """
+ metadata: dict[str, tuple[str, str | None]] = {}
+
+ for msg in messages:
+ if msg.get("role") != "assistant":
+ continue
+
+ # OpenAI format: tool_calls array
+ for tc in msg.get("tool_calls", []):
+ if not isinstance(tc, dict):
+ continue
+ tc_id = tc.get("id", "")
+ func = tc.get("function", {})
+ name = func.get("name", "")
+ if not tc_id or not name:
+ continue
+
+ file_path = None
+ try:
+ args = json.loads(func.get("arguments", "{}"))
+ file_path = args.get("file_path") or args.get("path")
+ except (json.JSONDecodeError, TypeError):
+ pass
+ metadata[tc_id] = (name, file_path)
+
+ # Anthropic format: content blocks with type=tool_use
+ content = msg.get("content", [])
+ if not isinstance(content, list):
+ continue
+ for block in content:
+ if not isinstance(block, dict) or block.get("type") != "tool_use":
+ continue
+ tc_id = block.get("id", "")
+ name = block.get("name", "")
+ if not tc_id or not name:
+ continue
+
+ inp = block.get("input", {})
+ file_path = None
+ if isinstance(inp, dict):
+ file_path = inp.get("file_path") or inp.get("path")
+ metadata[tc_id] = (name, file_path)
+
+ return metadata
+
+ def _build_file_operation_index(
+ self,
+ messages: list[dict[str, Any]],
+ tool_metadata: dict[str, tuple[str, str | None]],
+ ) -> dict[str, list[FileOperation]]:
+ """Build file_path → [FileOperation] index in a single pass.
+
+ Groups all Read/Edit/Write operations by file_path for lifecycle analysis.
+ """
+ file_ops: dict[str, list[FileOperation]] = defaultdict(list)
+
+ for tc_id, (name, file_path) in tool_metadata.items():
+ if not file_path:
+ continue
+
+ if name in _READ_TOOL_NAMES:
+ operation = "read"
+ elif name in _MUTATING_TOOL_NAMES:
+ operation = "edit"
+ else:
+ continue
+
+ # Find the message index where this tool_call appears
+ msg_idx = self._find_tool_call_msg_index(messages, tc_id)
+ if msg_idx is None:
+ continue
+
+ file_ops[file_path].append(
+ FileOperation(
+ msg_index=msg_idx,
+ tool_call_id=tc_id,
+ tool_name=name,
+ file_path=file_path,
+ operation=operation,
+ )
+ )
+
+ return dict(file_ops)
+
+ def _find_tool_call_msg_index(
+ self, messages: list[dict[str, Any]], tool_call_id: str
+ ) -> int | None:
+ """Find the message index containing a specific tool_call_id."""
+ for i, msg in enumerate(messages):
+ if msg.get("role") != "assistant":
+ continue
+
+ # OpenAI format
+ for tc in msg.get("tool_calls", []):
+ if isinstance(tc, dict) and tc.get("id") == tool_call_id:
+ return i
+
+ # Anthropic format
+ content = msg.get("content", [])
+ if isinstance(content, list):
+ for block in content:
+ if (
+ isinstance(block, dict)
+ and block.get("type") == "tool_use"
+ and block.get("id") == tool_call_id
+ ):
+ return i
+
+ return None
+
+ def _classify_reads(self, file_ops: dict[str, list[FileOperation]]) -> list[ReadClassification]:
+ """Classify each Read as fresh, stale, or superseded."""
+ classifications: list[ReadClassification] = []
+
+ for file_path, ops in file_ops.items():
+ reads = [op for op in ops if op.operation == "read"]
+ edits = [op for op in ops if op.operation == "edit"]
+
+ if not reads:
+ continue
+
+ for read_op in reads:
+ # Check stale: any edit/write of this file AFTER this read?
+ is_stale = self.config.compress_stale and any(
+ e.msg_index > read_op.msg_index for e in edits
+ )
+
+ # Check superseded: any later read of this file?
+ is_superseded = self.config.compress_superseded and any(
+ r.msg_index > read_op.msg_index for r in reads
+ )
+
+ if is_stale:
+ state = ReadState.STALE
+ elif is_superseded:
+ state = ReadState.SUPERSEDED
+ else:
+ state = ReadState.FRESH
+
+ classifications.append(
+ ReadClassification(
+ msg_index=read_op.msg_index,
+ tool_call_id=read_op.tool_call_id,
+ file_path=file_path,
+ state=state,
+ content_size=read_op.content_size,
+ )
+ )
+
+ return classifications
+
+ def _apply_lifecycle(
+ self,
+ messages: list[dict[str, Any]],
+ classifications: list[ReadClassification],
+ ) -> ReadLifecycleResult:
+ """Replace stale/superseded Read content with markers."""
+ # Build lookup: tool_call_id → classification (for non-fresh reads)
+ replacements: dict[str, ReadClassification] = {
+ c.tool_call_id: c for c in classifications if c.state != ReadState.FRESH
+ }
+
+ if not replacements:
+ return ReadLifecycleResult(
+ messages=messages,
+ reads_total=len(classifications),
+ reads_fresh=len(classifications),
+ )
+
+ result_messages: list[dict[str, Any]] = []
+ transforms: list[str] = []
+ ccr_hashes: list[str] = []
+ bytes_before = 0
+ bytes_after = 0
+ counts = {ReadState.FRESH: 0, ReadState.STALE: 0, ReadState.SUPERSEDED: 0}
+
+ for c in classifications:
+ counts[c.state] += 1
+
+ for msg in messages:
+ role = msg.get("role", "")
+ content = msg.get("content", "")
+
+ # OpenAI format: role=tool with tool_call_id
+ if role == "tool":
+ tc_id = msg.get("tool_call_id", "")
+ classification = replacements.get(tc_id)
+ if classification and isinstance(content, str):
+ replaced, marker, ccr_hash = self._replace_content(content, classification)
+ if replaced:
+ result_messages.append({**msg, "content": marker})
+ transforms.append(f"read_lifecycle:{classification.state.value}")
+ if ccr_hash:
+ ccr_hashes.append(ccr_hash)
+ bytes_before += len(content.encode("utf-8"))
+ bytes_after += len(marker.encode("utf-8"))
+ continue
+
+ # Anthropic format: content blocks list
+ if isinstance(content, list):
+ new_blocks, block_replaced = self._process_anthropic_blocks(
+ content, replacements, transforms, ccr_hashes
+ )
+ if block_replaced:
+ result_messages.append({**msg, "content": new_blocks})
+ continue
+
+ result_messages.append(msg)
+
+ return ReadLifecycleResult(
+ messages=result_messages,
+ reads_total=len(classifications),
+ reads_stale=counts[ReadState.STALE],
+ reads_superseded=counts[ReadState.SUPERSEDED],
+ reads_fresh=counts[ReadState.FRESH],
+ bytes_before=bytes_before,
+ bytes_after=bytes_after,
+ transforms_applied=transforms,
+ ccr_hashes=ccr_hashes,
+ )
+
+ def _process_anthropic_blocks(
+ self,
+ content_blocks: list[Any],
+ replacements: dict[str, ReadClassification],
+ transforms: list[str],
+ ccr_hashes: list[str],
+ ) -> tuple[list[Any], bool]:
+ """Process Anthropic-format content blocks for lifecycle replacement."""
+ new_blocks = []
+ any_replaced = False
+
+ for block in content_blocks:
+ if not isinstance(block, dict) or block.get("type") != "tool_result":
+ new_blocks.append(block)
+ continue
+
+ tc_id = block.get("tool_use_id", "")
+ classification = replacements.get(tc_id)
+ tool_content = block.get("content", "")
+
+ if classification and isinstance(tool_content, str):
+ replaced, marker, ccr_hash = self._replace_content(tool_content, classification)
+ if replaced:
+ new_blocks.append({**block, "content": marker})
+ transforms.append(f"read_lifecycle:{classification.state.value}")
+ if ccr_hash:
+ ccr_hashes.append(ccr_hash)
+ any_replaced = True
+ continue
+
+ new_blocks.append(block)
+
+ return new_blocks, any_replaced
+
+ def _replace_content(
+ self, content: str, classification: ReadClassification
+ ) -> tuple[bool, str, str | None]:
+ """Replace Read content with a lifecycle marker.
+
+ Returns (was_replaced, marker_text, ccr_hash).
+ """
+ content_bytes = len(content.encode("utf-8"))
+
+ # Skip tiny outputs
+ if content_bytes < self.config.min_size_bytes:
+ return False, content, None
+
+ # Store original in CCR if available
+ ccr_hash = None
+ if self.store is not None:
+ ccr_hash = self.store.store(
+ original=content,
+ compressed="",
+ tool_name="Read",
+ tool_call_id=classification.tool_call_id,
+ compression_strategy=f"read_lifecycle:{classification.state.value}",
+ )
+
+ # Generate marker
+ if ccr_hash is None:
+ # No CCR store — generate a content hash for reference
+ ccr_hash = hashlib.sha256(content.encode()).hexdigest()[:24]
+
+ file_display = classification.file_path or "unknown"
+
+ if classification.state == ReadState.STALE:
+ marker = (
+ f"[Read content stale: {file_display} was modified after this read. "
+ f"Retrieve original: hash={ccr_hash}]"
+ )
+ else: # SUPERSEDED
+ marker = (
+ f"[Read content superseded: {file_display} was re-read later. "
+ f"Retrieve original: hash={ccr_hash}]"
+ )
+
+ return True, marker, ccr_hash
diff --git a/tests/test_transforms/test_read_lifecycle.py b/tests/test_transforms/test_read_lifecycle.py
new file mode 100644
index 000000000..b92875fd4
--- /dev/null
+++ b/tests/test_transforms/test_read_lifecycle.py
@@ -0,0 +1,533 @@
+"""Tests for ReadLifecycleManager - event-driven Read lifecycle management.
+
+Tests covering:
+- Disabled by default (backward compatibility)
+- Stale detection (file edited after Read)
+- Superseded detection (file re-Read)
+- Fresh Reads untouched
+- Multiple files and complex chains
+- OpenAI and Anthropic message formats
+- CCR store integration
+- Size gating
+"""
+
+import json
+
+from headroom.config import ReadLifecycleConfig
+from headroom.transforms.read_lifecycle import (
+ ReadLifecycleManager,
+)
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_openai_read(tool_call_id: str, file_path: str) -> dict:
+ """Create an OpenAI-format assistant message with a Read tool call."""
+ return {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": tool_call_id,
+ "type": "function",
+ "function": {
+ "name": "Read",
+ "arguments": json.dumps({"file_path": file_path}),
+ },
+ }
+ ],
+ }
+
+
+def make_openai_edit(tool_call_id: str, file_path: str) -> dict:
+ """Create an OpenAI-format assistant message with an Edit tool call."""
+ return {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": tool_call_id,
+ "type": "function",
+ "function": {
+ "name": "Edit",
+ "arguments": json.dumps(
+ {
+ "file_path": file_path,
+ "old_string": "old",
+ "new_string": "new",
+ }
+ ),
+ },
+ }
+ ],
+ }
+
+
+def make_openai_write(tool_call_id: str, file_path: str) -> dict:
+ """Create an OpenAI-format assistant message with a Write tool call."""
+ return {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": tool_call_id,
+ "type": "function",
+ "function": {
+ "name": "Write",
+ "arguments": json.dumps({"file_path": file_path, "content": "new content"}),
+ },
+ }
+ ],
+ }
+
+
+def make_openai_tool_result(tool_call_id: str, content: str) -> dict:
+ """Create an OpenAI-format tool result message."""
+ return {
+ "role": "tool",
+ "tool_call_id": tool_call_id,
+ "content": content,
+ }
+
+
+def make_anthropic_read(tool_call_id: str, file_path: str) -> dict:
+ """Create an Anthropic-format assistant message with a Read tool call."""
+ return {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": tool_call_id,
+ "name": "Read",
+ "input": {"file_path": file_path},
+ }
+ ],
+ }
+
+
+def make_anthropic_edit(tool_call_id: str, file_path: str) -> dict:
+ """Create an Anthropic-format assistant message with an Edit tool call."""
+ return {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": tool_call_id,
+ "name": "Edit",
+ "input": {
+ "file_path": file_path,
+ "old_string": "old",
+ "new_string": "new",
+ },
+ }
+ ],
+ }
+
+
+def make_anthropic_tool_result(tool_call_id: str, content: str) -> dict:
+ """Create an Anthropic-format user message with a tool_result block."""
+ return {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": tool_call_id,
+ "content": content,
+ }
+ ],
+ }
+
+
+LARGE_CONTENT = "x" * 2000 # Well above min_size_bytes
+SMALL_CONTENT = "tiny" # Below min_size_bytes
+
+
+# =============================================================================
+# Tests
+# =============================================================================
+
+
+class TestReadLifecycleDisabled:
+ """Verify backward compatibility when disabled."""
+
+ def test_disabled_by_default(self):
+ """Default config: no changes to messages."""
+ config = ReadLifecycleConfig()
+ assert config.enabled is False
+
+ mgr = ReadLifecycleManager(config)
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.messages is messages # Same object, not copied
+ assert result.reads_total == 0
+ assert result.transforms_applied == []
+
+
+class TestStaleDetection:
+ """Read outputs become stale when the file is subsequently edited."""
+
+ def test_read_then_edit_makes_stale(self):
+ """Read(A) → Edit(A): Read becomes stale."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_stale == 1
+ assert result.reads_fresh == 0
+ # Read content should be replaced with marker
+ tool_result = result.messages[1]
+ assert "stale" in tool_result["content"].lower()
+ assert "/src/app.py" in tool_result["content"]
+ assert "hash=" in tool_result["content"]
+
+ def test_write_makes_read_stale(self):
+ """Read(A) → Write(A): Read becomes stale."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_write("w1", "/src/app.py"),
+ make_openai_tool_result("w1", "write success"),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_stale == 1
+ assert "stale" in result.messages[1]["content"].lower()
+
+ def test_edit_different_file_not_stale(self):
+ """Read(A) → Edit(B): Read(A) stays fresh."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/other.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_stale == 0
+ assert result.reads_fresh == 1
+ assert result.messages[1]["content"] == LARGE_CONTENT
+
+ def test_multiple_reads_all_stale(self):
+ """Read(A) × 3 → Edit(A): all 3 Reads become stale."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_read("r2", "/src/app.py"),
+ make_openai_tool_result("r2", LARGE_CONTENT + "_v2"),
+ make_openai_read("r3", "/src/app.py"),
+ make_openai_tool_result("r3", LARGE_CONTENT + "_v3"),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ # All 3 reads are stale (edit happened after all of them)
+ assert result.reads_stale == 3
+ assert result.reads_fresh == 0
+
+ def test_compress_stale_disabled(self):
+ """compress_stale=False: stale Reads are not replaced."""
+ config = ReadLifecycleConfig(enabled=True, compress_stale=False)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ # With compress_stale=False but compress_superseded=True,
+ # Read is superseded by nothing (only one read), and not stale → fresh
+ assert result.reads_fresh == 1
+ assert result.messages[1]["content"] == LARGE_CONTENT
+
+
+class TestSupersededDetection:
+ """Read outputs become superseded when the same file is re-Read."""
+
+ def test_reread_makes_superseded(self):
+ """Read(A) → Read(A): first Read becomes superseded."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_read("r2", "/src/app.py"),
+ make_openai_tool_result("r2", LARGE_CONTENT + "_updated"),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_superseded == 1
+ assert result.reads_fresh == 1
+ # First read replaced, second read untouched
+ assert "superseded" in result.messages[1]["content"].lower()
+ assert result.messages[3]["content"] == LARGE_CONTENT + "_updated"
+
+ def test_compress_superseded_disabled(self):
+ """compress_superseded=False: superseded Reads not replaced."""
+ config = ReadLifecycleConfig(enabled=True, compress_superseded=False)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_read("r2", "/src/app.py"),
+ make_openai_tool_result("r2", LARGE_CONTENT + "_updated"),
+ ]
+
+ result = mgr.apply(messages)
+ # Both reads are fresh (superseded detection disabled)
+ assert result.reads_fresh == 2
+ assert result.messages[1]["content"] == LARGE_CONTENT
+
+
+class TestFreshReads:
+ """Fresh Reads must never be modified."""
+
+ def test_single_read_stays_fresh(self):
+ """One Read, no Edit: stays fresh."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_fresh == 1
+ assert result.reads_stale == 0
+ assert result.reads_superseded == 0
+ assert result.messages[1]["content"] == LARGE_CONTENT
+
+ def test_read_edit_read_chain(self):
+ """Read(A) → Edit(A) → Read(A): first stale, second fresh."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ make_openai_read("r2", "/src/app.py"),
+ make_openai_tool_result("r2", LARGE_CONTENT + "_v2"),
+ ]
+
+ result = mgr.apply(messages)
+ # First read: stale (edit happened after) AND superseded (re-read after)
+ # → classified as stale (stale takes priority)
+ assert result.reads_stale == 1
+ # Second read: fresh (latest, no edit after)
+ assert result.reads_fresh == 1
+ assert "stale" in result.messages[1]["content"].lower()
+ assert result.messages[5]["content"] == LARGE_CONTENT + "_v2"
+
+
+class TestMultipleFiles:
+ """Lifecycle management across multiple files."""
+
+ def test_independent_files(self):
+ """Read(A) → Edit(A) → Read(B): A stale, B fresh."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ make_openai_read("r2", "/src/utils.py"),
+ make_openai_tool_result("r2", LARGE_CONTENT + "_utils"),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_stale == 1
+ assert result.reads_fresh == 1
+ assert "stale" in result.messages[1]["content"].lower()
+ assert result.messages[5]["content"] == LARGE_CONTENT + "_utils"
+
+
+class TestSizeGating:
+ """Small Read outputs should be skipped."""
+
+ def test_small_read_not_replaced(self):
+ """Read output below min_size_bytes: not replaced even if stale."""
+ config = ReadLifecycleConfig(enabled=True, min_size_bytes=512)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", SMALL_CONTENT), # 4 bytes
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ # Stale but too small to replace
+ assert result.messages[1]["content"] == SMALL_CONTENT
+
+
+class TestAnthropicFormat:
+ """Lifecycle works with Anthropic message format."""
+
+ def test_anthropic_stale_read(self):
+ """Anthropic format: Read(A) → Edit(A): Read becomes stale."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_anthropic_read("r1", "/src/app.py"),
+ make_anthropic_tool_result("r1", LARGE_CONTENT),
+ make_anthropic_edit("e1", "/src/app.py"),
+ make_anthropic_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_stale == 1
+ # Check the tool_result block inside the user message was replaced
+ user_msg = result.messages[1]
+ tool_result_block = user_msg["content"][0]
+ assert "stale" in tool_result_block["content"].lower()
+ assert "hash=" in tool_result_block["content"]
+
+ def test_anthropic_fresh_read(self):
+ """Anthropic format: single Read stays fresh."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_anthropic_read("r1", "/src/app.py"),
+ make_anthropic_tool_result("r1", LARGE_CONTENT),
+ ]
+
+ result = mgr.apply(messages)
+ assert result.reads_fresh == 1
+ user_msg = result.messages[1]
+ assert user_msg["content"][0]["content"] == LARGE_CONTENT
+
+
+class TestCCRStoreIntegration:
+ """Lifecycle manager stores originals in CCR."""
+
+ def test_original_stored_in_ccr(self):
+ """When a Read is replaced, original content is stored in CCR."""
+
+ class MockStore:
+ def __init__(self):
+ self.stored = []
+
+ def store(self, **kwargs):
+ self.stored.append(kwargs)
+ return "mock_hash_1234567890ab"
+
+ mock_store = MockStore()
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config, compression_store=mock_store)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ assert len(mock_store.stored) == 1
+ assert mock_store.stored[0]["original"] == LARGE_CONTENT
+ assert mock_store.stored[0]["tool_name"] == "Read"
+ assert "mock_hash_1234567890ab" in result.messages[1]["content"]
+ assert result.ccr_hashes == ["mock_hash_1234567890ab"]
+
+ def test_no_store_uses_content_hash(self):
+ """Without CCR store, marker uses content-derived hash."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config, compression_store=None)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "edit success"),
+ ]
+
+ result = mgr.apply(messages)
+ assert "hash=" in result.messages[1]["content"]
+
+
+class TestTransformTracking:
+ """Lifecycle transforms are tracked correctly."""
+
+ def test_transforms_recorded(self):
+ """Each replacement generates a transform entry."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ make_openai_read("r1", "/src/app.py"),
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_read("r2", "/src/app.py"),
+ make_openai_tool_result("r2", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "done"),
+ ]
+
+ result = mgr.apply(messages)
+ stale_transforms = [t for t in result.transforms_applied if "stale" in t]
+ assert len(stale_transforms) == 2 # Both reads are stale
+
+
+class TestNoFilePathHandling:
+ """Reads without parseable file_path should be left alone."""
+
+ def test_read_without_file_path(self):
+ """Read with no file_path in arguments: treated as unknown, not matched."""
+ config = ReadLifecycleConfig(enabled=True)
+ mgr = ReadLifecycleManager(config)
+
+ messages = [
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "r1",
+ "type": "function",
+ "function": {"name": "Read", "arguments": "{}"},
+ }
+ ],
+ },
+ make_openai_tool_result("r1", LARGE_CONTENT),
+ make_openai_edit("e1", "/src/app.py"),
+ make_openai_tool_result("e1", "done"),
+ ]
+
+ result = mgr.apply(messages)
+ # Can't match file_path, so Read is not classified at all
+ assert result.reads_total == 0
+ assert result.messages[1]["content"] == LARGE_CONTENT