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(mcp_registry): atomic config writes, no traceback on non-UTF-8 configs, log failed removals (#4130)
Tejas Chopraf2153fec2b8d
diff --git a/headroom/mcp_registry/claude.py b/headroom/mcp_registry/claude.pyindex 64a9afab4..d27d09362 100644--- a/headroom/mcp_registry/claude.py+++ b/headroom/mcp_registry/claude.py@@ -34,6 +34,7 @@ import shutilfrom pathlib import Pathfrom typing import Any+from headroom import fsutilfrom headroom._subprocess import runfrom .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec@@ -184,6 +185,10 @@ class ClaudeRegistrar(MCPRegistrar):raise ClaudeConfigMutationError(f"could not read Claude config {config_path}: {exc}") from exc+ except UnicodeDecodeError as exc:+ raise ClaudeConfigMutationError(+ f"Claude config {config_path} is not valid UTF-8; refusing to mutate"+ ) from exctry:config = json.loads(raw)except json.JSONDecodeError as exc:@@ -321,27 +326,22 @@ class ClaudeRegistrar(MCPRegistrar):def _remove_from_file(self, path: Path, server_name: str, scope: str) -> bool:if not path.exists():return False- try:- config = _read_json(path)- except OSError:- return False+ config = _read_json(path)servers = self._servers_map(config, scope)if servers is None or server_name not in servers:return Falsedel servers[server_name]try:_write_json(path, config)- except OSError:+ except OSError as exc:+ logger.warning("could not remove %r from %s: %s", server_name, path, exc)return Falsereturn Truedef _read_server_entry(self, path: Path, server_name: str, scope: str) -> ServerSpec | None:if not path.exists():return None- try:- config = _read_json(path)- except OSError:- return None+ config = _read_json(path)servers = self._servers_map(config, scope)if servers is None:return None@@ -498,7 +498,7 @@ def _read_json(path: Path) -> dict[str, Any]:try:with open(path, encoding="utf-8") as f:data = json.load(f)- except (OSError, json.JSONDecodeError):+ except (OSError, json.JSONDecodeError, UnicodeDecodeError):return {}if not isinstance(data, dict):return {}@@ -561,7 +561,10 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:"""if not path.exists():return {}- raw = path.read_text(encoding="utf-8") # OSError propagates to the caller+ try:+ raw = path.read_text(encoding="utf-8") # OSError propagates to the caller+ except UnicodeDecodeError as exc:+ raise _MalformedConfigError(f"not valid UTF-8: {exc}") from excif not raw.strip():return {}try:@@ -575,9 +578,7 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:def _write_json(path: Path, data: dict[str, Any]) -> None:path.parent.mkdir(parents=True, exist_ok=True)- with open(path, "w", encoding="utf-8") as f:- json.dump(data, f, indent=2)- f.write("\n")+ fsutil.write_text(path, json.dumps(data, indent=2) + "\n")def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:diff --git a/headroom/mcp_registry/codex.py b/headroom/mcp_registry/codex.pyindex 923ee0571..4405ea399 100644--- a/headroom/mcp_registry/codex.py+++ b/headroom/mcp_registry/codex.py@@ -234,7 +234,8 @@ class CodexRegistrar(MCPRegistrar):return Falsetry:fsutil.write_text(self._config_file, new_content)- except OSError:+ except OSError as exc:+ logger.warning("could not remove %r from %s: %s", server_name, self._config_file, exc)return Falsereturn Truediff --git a/headroom/mcp_registry/grok.py b/headroom/mcp_registry/grok.pyindex d1fe203c6..a2e888117 100644--- a/headroom/mcp_registry/grok.py+++ b/headroom/mcp_registry/grok.py@@ -131,7 +131,8 @@ class GrokRegistrar(MCPRegistrar):return Falsetry:fsutil.write_text(self._config_file, new_content)- except OSError:+ except OSError as exc:+ logger.warning("could not remove %r from %s: %s", server_name, self._config_file, exc)return Falsereturn Truediff --git a/headroom/mcp_registry/ledger.py b/headroom/mcp_registry/ledger.pyindex af1d1b634..3a0bcf86a 100644--- a/headroom/mcp_registry/ledger.py+++ b/headroom/mcp_registry/ledger.py@@ -14,7 +14,7 @@ from datetime import datetime, timezonefrom pathlib import Pathfrom typing import Any-from headroom import paths+from headroom import fsutil, pathsfrom .base import ServerSpec@@ -129,6 +129,10 @@ def _read_ledger(path: Path, *, for_mutation: bool = False) -> dict[str, Any]:if for_mutation:raise LedgerMutationError(f"MCP install ledger is unreadable: {path}") from excreturn {}+ except UnicodeDecodeError as exc:+ if for_mutation:+ raise LedgerMutationError(f"MCP install ledger is not valid UTF-8: {path}") from exc+ return {}try:data = json.loads(raw)except json.JSONDecodeError as exc:@@ -137,7 +141,7 @@ def _read_ledger(path: Path, *, for_mutation: bool = False) -> dict[str, Any]:return {}if not isinstance(data, dict):if for_mutation:- raise LedgerMutationError("MCP install ledger must contain a JSON object")+ raise LedgerMutationError(f"MCP install ledger must contain a JSON object: {path}")return {}if for_mutation:for section in ("agents",):@@ -168,4 +172,4 @@ def _read_ledger(path: Path, *, for_mutation: bool = False) -> dict[str, Any]:def _write_ledger(path: Path, data: dict[str, Any]) -> None:path.parent.mkdir(parents=True, exist_ok=True)- path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")+ fsutil.write_text(path, json.dumps(data, indent=2, sort_keys=True) + "\n")diff --git a/headroom/mcp_registry/opencode.py b/headroom/mcp_registry/opencode.pyindex 1b0928d62..6cd470104 100644--- a/headroom/mcp_registry/opencode.py+++ b/headroom/mcp_registry/opencode.py@@ -14,6 +14,7 @@ import shutilfrom pathlib import Pathfrom typing import Any+from headroom import fsutilfrom headroom.install.paths import opencode_config_pathfrom .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec@@ -57,7 +58,7 @@ def _read_json(path: Path) -> dict[str, Any]:return {}try:raw = path.read_text(encoding="utf-8")- except OSError:+ except (OSError, UnicodeDecodeError):return {}return _parse_json_loose(raw) or {}@@ -84,7 +85,10 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:"""if not path.exists():return {}- raw = path.read_text(encoding="utf-8") # OSError propagates to the caller+ try:+ raw = path.read_text(encoding="utf-8") # OSError propagates to the caller+ except UnicodeDecodeError as exc:+ raise _MalformedConfigError(f"not valid UTF-8: {exc}") from excif not raw.strip():return {}data = _parse_json_loose(raw)@@ -95,9 +99,7 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:def _write_json(path: Path, data: dict[str, Any]) -> None:path.parent.mkdir(parents=True, exist_ok=True)- with open(path, "w", encoding="utf-8") as f:- json.dump(data, f, indent=2)- f.write("\n")+ fsutil.write_text(path, json.dumps(data, indent=2) + "\n")def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:diff --git a/tests/test_mcp_registry/test_claude_registrar.py b/tests/test_mcp_registry/test_claude_registrar.pyindex 5caa1e28c..adf9d5bd4 100644--- a/tests/test_mcp_registry/test_claude_registrar.py+++ b/tests/test_mcp_registry/test_claude_registrar.py@@ -3,6 +3,8 @@from __future__ import annotationsimport json+import os+import statimport subprocessfrom pathlib import Pathfrom unittest.mock import patch@@ -492,6 +494,55 @@ def test_register_via_file_preserves_malformed_config(tmp_path: Path, contents:assert cfg.read_text(encoding="utf-8") == contents+def test_non_utf8_config_fails_cleanly_and_is_left_untouched(tmp_path: Path) -> None:+ """A ~/.claude.json saved in a non-UTF-8 locale encoding (GBK here) must not+ crash register/unregister/validate with a raw UnicodeDecodeError; it is+ treated as malformed and never rewritten."""+ from headroom.mcp_registry.claude import ClaudeConfigMutationError++ cfg = tmp_path / ".claude.json"+ original = '{"projects": {"/项目": {}}}'.encode("gbk")+ cfg.write_bytes(original)+ reg = _make_registrar(tmp_path, cli=None)++ result = reg.register_server(_spec())+ assert result.status == RegisterStatus.FAILED+ assert "not valid JSON" in result.detail+ assert reg.unregister_server("headroom") is False+ with pytest.raises(ClaudeConfigMutationError, match="not valid UTF-8"):+ reg.validate_configs_for_mutation()+ assert cfg.read_bytes() == original++[email protected](os.name == "nt", reason="POSIX file modes")+def test_failed_write_leaves_claude_json_intact(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """~/.claude.json holds OAuth state; a write that fails mid-way (ENOSPC at+ fsync here) must leave the original bytes and mode, and no temp file."""+ cfg = tmp_path / ".claude.json"+ original = json.dumps({"oauthAccount": {"emailAddress": "[email protected]"}, "mcpServers": {}})+ cfg.write_text(original, encoding="utf-8")+ cfg.chmod(0o600)+ reg = _make_registrar(tmp_path, cli=None)++ def no_space(fd: int) -> None:+ raise OSError(28, "No space left on device")++ monkeypatch.setattr("headroom.fsutil.os.fsync", no_space)+ result = reg.register_server(_spec())+ assert result.status == RegisterStatus.FAILED+ assert "No space left" in result.detail++ assert cfg.read_text(encoding="utf-8") == original+ assert sorted(p.name for p in tmp_path.iterdir()) == [".claude.json"]++ monkeypatch.undo()+ assert reg.register_server(_spec()).status == RegisterStatus.REGISTERED+ assert stat.S_IMODE(cfg.stat().st_mode) == 0o600+ assert json.loads(cfg.read_text(encoding="utf-8"))["oauthAccount"]++def test_register_via_file_merges_into_existing_valid_config(tmp_path: Path) -> None:"""The happy path still merges: unrelated keys are preserved and mcpServersgains the headroom entry."""diff --git a/tests/test_mcp_registry/test_ledger.py b/tests/test_mcp_registry/test_ledger.pyindex 406fefca5..ece90cf9f 100644--- a/tests/test_mcp_registry/test_ledger.py+++ b/tests/test_mcp_registry/test_ledger.py@@ -117,3 +117,20 @@ def test_record_install_recovers_from_unsafe_ledger_shape(tmp_path, contents):record_install("claude", _spec(), path=ledger)assert headroom_installed_matching("claude", _spec(), path=ledger)+++def test_failed_ledger_write_keeps_the_previous_ledger(monkeypatch, tmp_path):+ """ENOSPC mid-write must not truncate the ledger or leave a temp file."""+ ledger = tmp_path / "mcp_installs.json"+ record_install("claude", _spec(), path=ledger)+ before = ledger.read_bytes()++ def no_space(fd: int) -> None:+ raise OSError(28, "No space left on device")++ monkeypatch.setattr("headroom.fsutil.os.fsync", no_space)+ with pytest.raises(OSError, match="No space left"):+ clear_install("claude", "serena", path=ledger)++ assert ledger.read_bytes() == before+ assert [p.name for p in tmp_path.iterdir()] == ["mcp_installs.json"]diff --git a/tests/test_mcp_registry/test_removal_failures.py b/tests/test_mcp_registry/test_removal_failures.pynew file mode 100644index 000000000..345746324--- /dev/null+++ b/tests/test_mcp_registry/test_removal_failures.py@@ -0,0 +1,68 @@+"""A removal whose config write fails returns False and says why, per registrar."""++from __future__ import annotations++import logging+from pathlib import Path++import pytest++from headroom.mcp_registry.base import MCPRegistrar, RegisterStatus, ServerSpec+from headroom.mcp_registry.claude import ClaudeRegistrar+from headroom.mcp_registry.codex import CodexRegistrar+from headroom.mcp_registry.grok import GrokRegistrar+++def _no_space(fd: int) -> None:+ raise OSError(28, "No space left on device")+++ ("make", "config", "logger_name"),+ [+ (+ lambda home: ClaudeRegistrar(claude_cli=None, home_dir=home),+ ".claude.json",+ "headroom.mcp_registry.claude",+ ),+ (+ lambda home: CodexRegistrar(home_dir=home),+ ".codex/config.toml",+ "headroom.mcp_registry.codex",+ ),+ (+ lambda home: GrokRegistrar(home_dir=home),+ ".grok/config.toml",+ "headroom.mcp_registry.grok",+ ),+ ],+ ids=["claude", "codex", "grok"],+)+def test_failed_removal_keeps_the_config_and_logs_why(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ caplog: pytest.LogCaptureFixture,+ make,+ config: str,+ logger_name: str,+) -> None:+ monkeypatch.delenv("GROK_HOME", raising=False)+ monkeypatch.delenv("CODEX_HOME", raising=False)+ monkeypatch.chdir(tmp_path)+ registrar: MCPRegistrar = make(tmp_path)+ spec = ServerSpec(name="headroom", command="/usr/bin/python", args=("-m", "headroom.cli"))+ assert registrar.register_server(spec).status == RegisterStatus.REGISTERED+ path = tmp_path / config+ before = path.read_bytes()++ monkeypatch.setattr("headroom.fsutil.os.fsync", _no_space)+ with caplog.at_level(logging.WARNING, logger=logger_name):+ assert registrar.unregister_server("headroom") is False++ assert path.read_bytes() == before+ messages = [r.getMessage() for r in caplog.records if r.name == logger_name]+ assert messages+ assert all(+ m.startswith(f"could not remove 'headroom' from {path}") and "No space left" in m+ for m in messages+ )diff --git a/tests/test_mcp_registry_opencode.py b/tests/test_mcp_registry_opencode.pyindex 766a5ebd2..004aea04b 100644--- a/tests/test_mcp_registry_opencode.py+++ b/tests/test_mcp_registry_opencode.py@@ -170,6 +170,26 @@ def test_register_server_preserves_malformed_config(tmp_path: Path, contents: stassert config_path.read_text(encoding="utf-8") == contents+def test_non_utf8_config_fails_cleanly_and_is_left_untouched(tmp_path: Path) -> None:+ """An opencode.json saved in a non-UTF-8 locale encoding (GBK here) must not+ crash with a raw UnicodeDecodeError; it is treated as malformed and never+ rewritten."""+ from headroom.mcp_registry.base import ServerSpec++ config_path = tmp_path / "opencode.json"+ original = '{"theme": "主题"}'.encode("gbk")+ config_path.write_bytes(original)+ registrar = _registrar(tmp_path)++ spec = ServerSpec(name="headroom", command="headroom", args=("mcp", "serve"))+ result = registrar.register_server(spec)++ assert result.status == RegisterStatus.FAILED+ assert "not valid JSON" in result.detail+ assert registrar.unregister_server("headroom") is False+ assert config_path.read_bytes() == original++def test_register_server_preserves_other_keys(tmp_path: Path) -> None:"""The happy path merges: theme/model and an existing MCP server survive."""from headroom.mcp_registry.base import ServerSpec