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: restore Windows mypy compatibility
JerrettDavis5884f7fb4157
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.pyindex 5541f7bb0..a2172e4ef 100644--- a/headroom/ccr/mcp_server.py+++ b/headroom/ccr/mcp_server.py@@ -32,10 +32,13 @@ from dataclasses import dataclass, fieldfrom pathlib import Pathfrom typing import Any-# fcntl is Unix-only; on Windows we skip file locking (stats are best-effort)+# 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.+fcntl: Any = Nonetry:- import fcntl+ import fcntl as _fcntl+ fcntl = _fcntl_HAS_FCNTL = Trueexcept ImportError:_HAS_FCNTL = False@@ -329,10 +332,10 @@ class HeadroomMCPServer:# File read cache: path → (content_hash, ccr_hash, line_count, token_count)self._file_cache: dict[str, tuple[str, str, int, int]] = {}- if not MCP_AVAILABLE:+ if not MCP_AVAILABLE or Server is None:raise ImportError("MCP SDK not installed. Install with: pip install mcp")- self.server = Server("headroom")+ self.server: Server = Server("headroom")self._setup_handlers()def _get_local_store(self) -> Any:diff --git a/headroom/integrations/langchain/retriever.py b/headroom/integrations/langchain/retriever.pyindex 15d0c1023..0f287046b 100644--- a/headroom/integrations/langchain/retriever.py+++ b/headroom/integrations/langchain/retriever.py@@ -30,35 +30,50 @@ import loggingimport refrom collections.abc import Sequencefrom dataclasses import dataclass-from typing import Any+from typing import TYPE_CHECKING, Any-# LangChain imports - these are optional dependencies-try:+if TYPE_CHECKING:from langchain_core.callbacks import Callbacksfrom langchain_core.documents import Document- # BaseDocumentCompressor location varies by langchain version+ LANGCHAIN_AVAILABLE = True++ class BaseDocumentCompressor:+ """Type-checking stub for LangChain's document compressor base."""++ def compress_documents(+ self, documents: Sequence[Any], query: str, callbacks: Any = None+ ) -> Sequence[Any]:+ raise NotImplementedError++# LangChain imports - these are optional dependencies+else:try:- from langchain.retrievers.document_compressors import BaseDocumentCompressor- except ImportError:+ from langchain_core.callbacks import Callbacks+ from langchain_core.documents import Document++ # BaseDocumentCompressor location varies by langchain versiontry:- from langchain_core.documents.compressors import BaseDocumentCompressor+ from langchain.retrievers.document_compressors import BaseDocumentCompressorexcept ImportError:- # Fallback: create a minimal base class- class BaseDocumentCompressor: # type: ignore[no-redef]- """Minimal base class for document compression."""-- def compress_documents(- self, documents: Sequence[Any], query: str, callbacks: Any = None- ) -> Sequence[Any]:- raise NotImplementedError-- LANGCHAIN_AVAILABLE = True-except ImportError:- LANGCHAIN_AVAILABLE = False- BaseDocumentCompressor = object # type: ignore[misc,assignment]- Document = object # type: ignore[misc,assignment]- Callbacks = None # type: ignore[misc,assignment]+ try:+ from langchain_core.documents.compressors import BaseDocumentCompressor+ except ImportError:+ # Fallback: create a minimal base class+ class BaseDocumentCompressor:+ """Minimal base class for document compression."""++ def compress_documents(+ self, documents: Sequence[Any], query: str, callbacks: Any = None+ ) -> Sequence[Any]:+ raise NotImplementedError++ LANGCHAIN_AVAILABLE = True+ except ImportError:+ LANGCHAIN_AVAILABLE = False+ BaseDocumentCompressor = object # type: ignore[misc,assignment]+ Document = object # type: ignore[misc,assignment]+ Callbacks = None # type: ignore[misc,assignment]logger = logging.getLogger(__name__)diff --git a/headroom/memory/adapters/embedders.py b/headroom/memory/adapters/embedders.pyindex 50c6b94f5..bafc57261 100644--- a/headroom/memory/adapters/embedders.py+++ b/headroom/memory/adapters/embedders.py@@ -55,7 +55,8 @@ def _normalize_embeddings_batch(embeddings: np.ndarray) -> np.ndarray:norms = np.linalg.norm(embeddings, axis=1, keepdims=True)# Avoid division by zeronorms = np.where(norms > 0, norms, 1.0)- return (embeddings / norms).astype(np.float32)+ result: np.ndarray = (embeddings / norms).astype(np.float32)+ return result# =============================================================================diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 036c1e980..0a7452332 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -144,6 +144,15 @@ from headroom.transforms import (is_tree_sitter_available,)+fcntl: Any = None+try:+ import fcntl as _fcntl++ fcntl = _fcntl+ HAS_FCNTL = True+except ImportError:+ HAS_FCNTL = False+_build_prefix_cache_stats = build_prefix_cache_stats_build_session_summary = build_session_summary_merge_cost_stats = merge_cost_stats@@ -921,34 +930,30 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:Returns True if this process is the beacon owner."""+ if not HAS_FCNTL:+ return True++ fd = Nonetry:_beacon_lock_path.parent.mkdir(parents=True, exist_ok=True)- import fcntl-fd = open(_beacon_lock_path, "w") # noqa: SIM115fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)fd.write(str(os.getpid()))fd.flush()_beacon_lock_fd[0] = fdreturn True- except (OSError, ImportError):- # Lock held by another worker, or fcntl not available (Windows)- # On Windows, skip locking — workers are rare on Windows anyway- try:- import fcntl # noqa: F811-- return False # Lock held by another worker- except ImportError:- return True # Windows: no fcntl, just allow it+ except OSError:+ if fd is not None:+ fd.close()+ return Falsedef _release_beacon_lock() -> None:"""Release the beacon file lock."""fd = _beacon_lock_fd[0]if fd:try:- import fcntl-- fcntl.flock(fd, fcntl.LOCK_UN)+ if HAS_FCNTL:+ fcntl.flock(fd, fcntl.LOCK_UN)fd.close()except Exception:passdiff --git a/tests/test_ccr_mcp_server.py b/tests/test_ccr_mcp_server.pynew file mode 100644index 000000000..303ada944--- /dev/null+++ b/tests/test_ccr_mcp_server.py@@ -0,0 +1,24 @@+from __future__ import annotations++import json++from headroom.ccr import mcp_server+++def test_shared_stats_work_without_fcntl(monkeypatch, tmp_path) -> None:+ monkeypatch.setattr(mcp_server, "_HAS_FCNTL", False)+ monkeypatch.setattr(mcp_server, "fcntl", None)+ monkeypatch.setattr(mcp_server, "SHARED_STATS_DIR", tmp_path)+ monkeypatch.setattr(mcp_server, "SHARED_STATS_FILE", tmp_path / "session_stats.jsonl")+ monkeypatch.setattr(mcp_server.os, "getpid", lambda: 4242)+ monkeypatch.setattr(mcp_server.time, "time", lambda: 1001.0)++ event = {"type": "compress", "timestamp": 1000.0}+ mcp_server._append_shared_event(event)++ raw_lines = mcp_server.SHARED_STATS_FILE.read_text(encoding="utf-8").splitlines()+ assert len(raw_lines) == 1+ assert json.loads(raw_lines[0]) == {"type": "compress", "timestamp": 1000.0, "pid": 4242}++ events = mcp_server._read_shared_events(window_seconds=60)+ assert events == [{"type": "compress", "timestamp": 1000.0, "pid": 4242}]