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(ccr): make expired retrieve misses terminal (#1781)

Rod Boev9cbdba4dc1f3
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.py
index e016b6ca4..8fd719051 100644
--- a/headroom/ccr/mcp_server.py
+++ b/headroom/ccr/mcp_server.py
@@ -34,6 +34,7 @@ from typing import Any
from headroom import paths as _paths
from headroom import savings_ledger
+from headroom.cache.compression_store import format_retrieval_miss_detail
# fcntl is Unix-only; on Windows we skip file locking (stats are best-effort).
# Keep the module typed as Any so Windows mypy runs don't try to resolve Unix-only attrs.
@@ -440,7 +441,9 @@ class HeadroomMCPServer:
"""
# Check local store first
store = self._get_local_store()
+ entry_status = store.get_entry_status(hash_key, clean_expired=False)
entry = store.retrieve(hash_key)
+ expired_entry_status = None
if entry:
self._stats.record_retrieval(hash_key)
return {
@@ -451,6 +454,19 @@ class HeadroomMCPServer:
"compressed_item_count": entry.compressed_item_count,
"retrieval_count": entry.retrieval_count,
}
+ if entry_status.get("status") == "expired":
+ expired_entry_status = entry_status
+ elif entry_status.get("status") == "available":
+ created_at = entry_status.get("created_at")
+ ttl_seconds = entry_status.get("ttl_seconds")
+ if isinstance(created_at, (int, float)) and isinstance(ttl_seconds, (int, float)):
+ age_seconds = time.time() - created_at
+ if age_seconds > ttl_seconds:
+ expired_entry_status = {
+ **entry_status,
+ "status": "expired",
+ "age_seconds": age_seconds,
+ }
# Fall back to proxy if available
if self.check_proxy and HTTPX_AVAILABLE:
@@ -463,6 +479,26 @@ class HeadroomMCPServer:
except Exception:
pass # Proxy unavailable, that's fine
+ if expired_entry_status:
+ ttl_seconds = expired_entry_status.get(
+ "ttl_seconds",
+ expired_entry_status["default_ttl_seconds"],
+ )
+ return {
+ "error": (
+ f"{format_retrieval_miss_detail(expired_entry_status)}. "
+ "Do not retry the same hash. Re-run the source command or re-read the source file."
+ ),
+ "hash": hash_key,
+ "status": "expired",
+ "ttl_seconds": ttl_seconds,
+ "age_seconds": expired_entry_status.get("age_seconds"),
+ "hint": (
+ "Use the source of truth to regenerate fresh content. "
+ "Re-run the command or re-read the file."
+ ),
+ }
+
return {
"error": "Content not found. It may have expired or the hash may be incorrect.",
"hash": hash_key,
diff --git a/tests/test_ccr_mcp_server.py b/tests/test_ccr_mcp_server.py
index 4b92715ff..c84e58243 100644
--- a/tests/test_ccr_mcp_server.py
+++ b/tests/test_ccr_mcp_server.py
@@ -5,6 +5,7 @@ import json
import pytest
+from headroom.cache import compression_store as compression_store_module
from headroom.cache.compression_store import (
get_compression_store,
reset_compression_store,
@@ -105,11 +106,132 @@ def test_mcp_retrieve_returns_full_content(fresh_store) -> None:
assert result["original_content"] == original
+def test_mcp_retrieve_expired_hash_returns_terminal_guidance(
+ monkeypatch,
+ fresh_store,
+) -> None:
+ """An expired local hash should say it expired and tell the agent to stop retrying."""
+ current_time = [1000.0]
+
+ def fake_time() -> float:
+ return current_time[0]
+
+ monkeypatch.setattr(mcp_server.time, "time", fake_time)
+ monkeypatch.setattr(compression_store_module.time, "time", fake_time)
+
+ store = get_compression_store()
+ hash_key = store.store("expired content", "<<small>>", ttl=1)
+ current_time[0] = 1002.0
+
+ server = mcp_server.HeadroomMCPServer(check_proxy=False)
+ result = asyncio.run(server._retrieve_content(hash_key))
+
+ assert result["status"] == "expired"
+ assert result["ttl_seconds"] == 1
+ assert result["age_seconds"] == pytest.approx(2.0)
+ assert "Entry expired" in result["error"]
+ assert "do not retry the same hash" in result["error"].lower()
+ assert "re-run the command" in result["hint"].lower()
+
+
+def test_mcp_retrieve_hash_expiring_during_lookup_returns_terminal_guidance(
+ monkeypatch,
+ fresh_store,
+) -> None:
+ phase = "store"
+ status_seen = False
+
+ def fake_time() -> float:
+ if phase == "store":
+ return 1000.0
+ return 1001.1 if status_seen else 1000.5
+
+ monkeypatch.setattr(mcp_server.time, "time", fake_time)
+ monkeypatch.setattr(compression_store_module.time, "time", fake_time)
+
+ store = get_compression_store()
+ hash_key = store.store("expired during retrieve", "<<small>>", ttl=1)
+ phase = "retrieve"
+
+ original_get_entry_status = store.get_entry_status
+ original_retrieve = store.retrieve
+
+ def get_entry_status_then_expire(*args, **kwargs):
+ nonlocal status_seen
+ result = original_get_entry_status(*args, **kwargs)
+ status_seen = True
+ return result
+
+ monkeypatch.setattr(store, "get_entry_status", get_entry_status_then_expire)
+ monkeypatch.setattr(store, "retrieve", original_retrieve)
+
+ server = mcp_server.HeadroomMCPServer(check_proxy=False)
+ result = asyncio.run(server._retrieve_content(hash_key))
+
+ assert result["status"] == "expired"
+ assert result["ttl_seconds"] == 1
+ assert result["age_seconds"] == pytest.approx(1.1)
+ assert "Entry expired" in result["error"]
+ assert "do not retry the same hash" in result["error"].lower()
+
+
+def test_mcp_retrieve_missing_local_hash_can_still_hit_proxy(
+ monkeypatch,
+ fresh_store,
+) -> None:
+ monkeypatch.setattr(mcp_server, "HTTPX_AVAILABLE", True)
+ server = mcp_server.HeadroomMCPServer(check_proxy=True)
+
+ async def retrieve_via_proxy(hash_key: str) -> dict[str, object]:
+ return {"hash": hash_key, "original_content": "from proxy"}
+
+ server._retrieve_via_proxy = retrieve_via_proxy
+
+ result = asyncio.run(server._retrieve_content("proxy_hash"))
+
+ assert result["source"] == "proxy"
+ assert result["hash"] == "proxy_hash"
+ assert result["original_content"] == "from proxy"
+
+
+def test_mcp_retrieve_expired_local_hash_can_still_hit_proxy(
+ monkeypatch,
+ fresh_store,
+) -> None:
+ current_time = [1000.0]
+
+ def fake_time() -> float:
+ return current_time[0]
+
+ monkeypatch.setattr(mcp_server, "HTTPX_AVAILABLE", True)
+ monkeypatch.setattr(mcp_server.time, "time", fake_time)
+ monkeypatch.setattr(compression_store_module.time, "time", fake_time)
+
+ store = get_compression_store()
+ hash_key = store.store("expired local content", "<<small>>", ttl=1)
+ current_time[0] = 1002.0
+
+ server = mcp_server.HeadroomMCPServer(check_proxy=True)
+
+ async def retrieve_via_proxy(proxy_hash_key: str) -> dict[str, object]:
+ return {"hash": proxy_hash_key, "original_content": "from proxy"}
+
+ server._retrieve_via_proxy = retrieve_via_proxy
+
+ result = asyncio.run(server._retrieve_content(hash_key))
+
+ assert result["source"] == "proxy"
+ assert result["hash"] == hash_key
+ assert result["original_content"] == "from proxy"
+
+
def test_mcp_retrieve_missing_hash_still_errors(fresh_store) -> None:
- """A genuinely missing hash must still report "Content not found"."""
+ """A never-stored hash must stay on the generic missing path, not expired guidance."""
server = mcp_server.HeadroomMCPServer(check_proxy=False)
result = asyncio.run(server._retrieve_content("nonexistent_hash"))
- assert "Content not found" in result.get("error", "")
+ assert result.get("status") is None
+ assert result["error"] == "Content not found. It may have expired or the hash may be incorrect."
+ assert "do not retry the same hash" not in result.get("hint", "").lower()
def test_handle_stats_session_output_is_window_scoped() -> None: