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(toin): retain pending changes after filesystem save failures (#4568)

Yuchuan He8b15a1579989
diff --git a/headroom/telemetry/backends/filesystem.py b/headroom/telemetry/backends/filesystem.py
index 8c5d52691..51841f4b1 100644
--- a/headroom/telemetry/backends/filesystem.py
+++ b/headroom/telemetry/backends/filesystem.py
@@ -68,6 +68,9 @@ class FileSystemTOINBackend:
Args:
data: Serialized TOIN data to persist.
+
+ Raises:
+ OSError: If persistence fails, so the caller can retain pending changes.
"""
try:
self._path.parent.mkdir(parents=True, exist_ok=True)
@@ -89,3 +92,4 @@ class FileSystemTOINBackend:
except OSError as e:
logger.warning("Failed to save TOIN data to %s: %s", self._path, e)
+ raise
diff --git a/headroom/telemetry/toin.py b/headroom/telemetry/toin.py
index acabba41c..a62a53484 100644
--- a/headroom/telemetry/toin.py
+++ b/headroom/telemetry/toin.py
@@ -578,6 +578,7 @@ class ToolIntelligenceNetwork:
# Tracking
self._last_save_time = time.time()
+ self._last_auto_save_attempt = 0.0
self._dirty = False
# Load existing data from backend
@@ -1760,8 +1761,12 @@ class ToolIntelligenceNetwork:
if not self._dirty:
return
- elapsed = time.time() - self._last_save_time
+ now = time.time()
+ elapsed = now - max(self._last_save_time, self._last_auto_save_attempt)
if elapsed >= self._config.auto_save_interval:
+ # Failed saves retain dirty state, but must not turn every
+ # observation into synchronous disk I/O and another warning.
+ self._last_auto_save_attempt = now
# save() uses the same RLock, so this is safe
self.save()
diff --git a/tests/test_toin_retention.py b/tests/test_toin_retention.py
index 75f54a324..f71a1fc88 100644
--- a/tests/test_toin_retention.py
+++ b/tests/test_toin_retention.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import json
import logging
+from types import SimpleNamespace
import pytest
@@ -12,6 +13,125 @@ from headroom.telemetry.models import ToolSignature
from headroom.telemetry.toin import TOINConfig, ToolIntelligenceNetwork
+def test_failed_auto_saves_respect_interval_and_retry_pending_data(tmp_path, caplog, monkeypatch):
+ import headroom.telemetry.toin as toin_module
+
+ clock = [10000.0]
+ monkeypatch.setattr(toin_module, "time", SimpleNamespace(time=lambda: clock[0]))
+ parent = tmp_path / "state"
+ parent.write_text("blocked", encoding="utf-8", newline="\n")
+ path = parent / "toin.json"
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=60))
+ clock[0] += 60
+ with caplog.at_level(logging.WARNING):
+ for _ in range(4):
+ toin.record_compression(
+ tool_signature=_signature(456),
+ original_count=10,
+ compressed_count=5,
+ original_tokens=100,
+ compressed_tokens=50,
+ strategy="test",
+ )
+ failures = [
+ record for record in caplog.records if getattr(record, "event", None) == "toin_save_failed"
+ ]
+ assert len(failures) == 1
+ assert toin._dirty is True
+
+ parent.unlink()
+ clock[0] += 60
+ toin._maybe_auto_save()
+ restored = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path)))
+ assert restored.get_pattern(_signature(456).structure_hash).total_compressions == 4
+ assert toin._dirty is False
+
+
+def test_manual_save_can_retry_before_auto_save_interval(tmp_path):
+ parent = tmp_path / "state"
+ parent.write_text("blocked", encoding="utf-8", newline="\n")
+ path = parent / "toin.json"
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=3600))
+ toin.record_compression(
+ tool_signature=_signature(789),
+ original_count=10,
+ compressed_count=5,
+ original_tokens=100,
+ compressed_tokens=50,
+ strategy="test",
+ )
+ toin._last_save_time = 0
+ toin._maybe_auto_save()
+ assert toin._dirty is True
+ parent.unlink()
+
+ toin.save()
+
+ assert path.is_file()
+ assert toin._dirty is False
+
+
+def test_filesystem_save_reports_parent_directory_failure(tmp_path) -> None:
+ blocked = tmp_path / "blocked"
+ blocked.write_text("not a directory", encoding="utf-8", newline="\n")
+ backend = FileSystemTOINBackend(str(blocked / "toin.json"))
+
+ with pytest.raises(OSError):
+ backend.save({"patterns": {}})
+
+
+def test_failed_replace_preserves_store_and_cleans_temporary_file(tmp_path, monkeypatch) -> None:
+ from pathlib import Path
+
+ path = tmp_path / "toin.json"
+ backend = FileSystemTOINBackend(str(path))
+ backend.save({"patterns": {"original": {}}})
+ original = path.read_bytes()
+
+ def fail_replace(self, target):
+ raise OSError("replace unavailable")
+
+ monkeypatch.setattr(Path, "replace", fail_replace)
+ with pytest.raises(OSError, match="replace unavailable"):
+ backend.save({"patterns": {"new": {}}})
+
+ assert path.read_bytes() == original
+ assert not list(tmp_path.glob(".toin_*.tmp"))
+
+
+def test_filesystem_failure_keeps_toin_dirty_for_automatic_retry(tmp_path, caplog) -> None:
+ parent = tmp_path / "state"
+ path = parent / "toin.json"
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=3600))
+ toin.record_compression(
+ tool_signature=_signature(123),
+ original_count=10,
+ compressed_count=5,
+ original_tokens=100,
+ compressed_tokens=50,
+ strategy="test",
+ )
+ toin._last_save_time = 0
+ parent.write_text("temporarily blocked", encoding="utf-8", newline="\n")
+
+ with caplog.at_level(logging.WARNING):
+ toin.save()
+
+ assert toin._dirty is True
+ assert toin._last_save_time == 0
+ assert any(getattr(record, "event", None) == "toin_save_failed" for record in caplog.records)
+
+ parent.unlink()
+ toin._maybe_auto_save()
+
+ assert toin._dirty is False
+ assert toin._last_save_time > 0
+ restored = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path)))
+ pattern = restored.get_pattern(_signature(123).structure_hash)
+ assert pattern is not None
+ assert pattern.total_compressions == 1
+
+
def _signature(index: int) -> ToolSignature:
return ToolSignature.from_items([{f"field_{index}": "x"}])