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: make headroom wrap readiness probe timeout configurable for slow ML imports (#581)

Matt Van Horn163677b405d7
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index bdfac6ee8..1982a5b56 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -14,6 +14,7 @@ Usage:
from __future__ import annotations
+import importlib.util
import io
import json
import os
@@ -87,6 +88,10 @@ _CONTEXT_TOOL_ENV = "HEADROOM_CONTEXT_TOOL"
_CONTEXT_TOOL_RTK = "rtk"
_CONTEXT_TOOL_LEAN_CTX = "lean-ctx"
_VALID_CONTEXT_TOOLS = {_CONTEXT_TOOL_RTK, _CONTEXT_TOOL_LEAN_CTX}
+_WRAP_PROXY_TIMEOUT_ENV = "HEADROOM_WRAP_PROXY_TIMEOUT"
+_WRAP_PROXY_TIMEOUT_DEFAULT_SECONDS = 45
+_WRAP_PROXY_TIMEOUT_ML_DEFAULT_SECONDS = 90
+_WRAP_PROXY_TIMEOUT_ML_MODULES = ("torch", "sentence_transformers", "spacy")
# Issue #746: Claude Code disables on-demand tool loading (deferral) when
# ANTHROPIC_BASE_URL is a custom host and ENABLE_TOOL_SEARCH is unset, which
@@ -171,6 +176,49 @@ def _selected_context_tool() -> str:
return raw
+def _module_available(module_name: str) -> bool:
+ """Return whether an optional module is installed without importing it."""
+
+ try:
+ return importlib.util.find_spec(module_name) is not None
+ except (ImportError, ModuleNotFoundError, ValueError):
+ return False
+
+
+def _ml_wrap_extras_detected() -> bool:
+ """Detect slow optional ML stacks without triggering their import cost."""
+
+ return any(_module_available(module_name) for module_name in _WRAP_PROXY_TIMEOUT_ML_MODULES)
+
+
+def _default_wrap_proxy_timeout_seconds() -> int:
+ """Return the default wrap proxy startup timeout for this environment."""
+
+ if _ml_wrap_extras_detected():
+ return _WRAP_PROXY_TIMEOUT_ML_DEFAULT_SECONDS
+ return _WRAP_PROXY_TIMEOUT_DEFAULT_SECONDS
+
+
+def _resolve_wrap_proxy_timeout_seconds() -> int:
+ """Resolve the wrap proxy readiness timeout from env or defaults."""
+
+ raw = os.environ.get(_WRAP_PROXY_TIMEOUT_ENV, "").strip()
+ if not raw:
+ return _default_wrap_proxy_timeout_seconds()
+
+ try:
+ timeout_seconds = int(raw)
+ except ValueError:
+ raise RuntimeError(
+ f"{_WRAP_PROXY_TIMEOUT_ENV} must be a positive integer number of seconds (got {raw!r})"
+ ) from None
+ if timeout_seconds <= 0:
+ raise RuntimeError(
+ f"{_WRAP_PROXY_TIMEOUT_ENV} must be a positive integer number of seconds (got {raw!r})"
+ )
+ return timeout_seconds
+
+
def _print_telemetry_notice() -> None:
"""Print a telemetry notice when anonymous telemetry is enabled.
@@ -288,6 +336,7 @@ def _start_proxy(
if anthropic_api_url:
cmd.extend(["--anthropic-api-url", anthropic_api_url])
+ timeout_seconds = _resolve_wrap_proxy_timeout_seconds()
log_path = _get_log_path()
log_file = open(log_path, "a") # noqa: SIM115
@@ -318,10 +367,10 @@ def _start_proxy(
start_new_session=os.name == "posix",
)
- # Wait for proxy to be ready (up to 45 seconds).
+ # Wait for proxy to be ready.
# ML components (Kompress, Magika, Tree-sitter) load synchronously before
# uvicorn binds the port. On slower machines this can take 20-30 seconds.
- for _i in range(45):
+ for _i in range(timeout_seconds):
time.sleep(1)
if _check_proxy(port):
click.echo(f" Logs: {log_path}")
@@ -338,7 +387,10 @@ def _start_proxy(
proc.kill()
log_file.close()
- raise RuntimeError(f"Proxy failed to start on port {port} within 45 seconds")
+ raise RuntimeError(
+ f"Proxy failed to start on port {port} within {timeout_seconds} seconds. "
+ f"Set {_WRAP_PROXY_TIMEOUT_ENV} to a larger number of seconds for slow startup."
+ )
def _setup_rtk(verbose: bool = False) -> Path | None:
diff --git a/tests/test_cli_proxy_env.py b/tests/test_cli_proxy_env.py
index 7636c68f9..289f1700c 100644
--- a/tests/test_cli_proxy_env.py
+++ b/tests/test_cli_proxy_env.py
@@ -3,6 +3,7 @@
Verifies that:
1. Provider target URL env vars are read by `headroom proxy`
2. litellm-* backends are accepted by both CLI and argparse paths
+3. HEADROOM_WRAP_PROXY_TIMEOUT controls `headroom wrap` proxy readiness waits
"""
import os
@@ -15,6 +16,7 @@ pytest.importorskip("fastapi")
from click.testing import CliRunner # noqa: E402
+from headroom.cli import wrap as wrap_mod # noqa: E402
from headroom.cli.main import main # noqa: E402
@@ -23,6 +25,98 @@ def runner():
return CliRunner()
+class _FakeProxyProcess:
+ returncode = None
+
+ def __init__(self):
+ self.killed = False
+
+ def poll(self):
+ return None
+
+ def kill(self):
+ self.killed = True
+
+
+class TestCLIWrapProxyTimeout:
+ """Test wrap proxy readiness timeout configuration."""
+
+ def test_default_timeout_stays_current_without_ml_extras(self, monkeypatch):
+ monkeypatch.delenv(wrap_mod._WRAP_PROXY_TIMEOUT_ENV, raising=False)
+ monkeypatch.setattr(wrap_mod, "_ml_wrap_extras_detected", lambda: False)
+
+ assert (
+ wrap_mod._resolve_wrap_proxy_timeout_seconds()
+ == wrap_mod._WRAP_PROXY_TIMEOUT_DEFAULT_SECONDS
+ )
+
+ def test_default_timeout_is_longer_when_ml_extras_detected(self, monkeypatch):
+ monkeypatch.delenv(wrap_mod._WRAP_PROXY_TIMEOUT_ENV, raising=False)
+ monkeypatch.setattr(wrap_mod, "_ml_wrap_extras_detected", lambda: True)
+
+ assert (
+ wrap_mod._resolve_wrap_proxy_timeout_seconds()
+ == wrap_mod._WRAP_PROXY_TIMEOUT_ML_DEFAULT_SECONDS
+ )
+
+ def test_start_proxy_succeeds_when_ready_within_default_timeout(self, monkeypatch, tmp_path):
+ fake_proc = _FakeProxyProcess()
+ sleeps = []
+
+ monkeypatch.delenv(wrap_mod._WRAP_PROXY_TIMEOUT_ENV, raising=False)
+ monkeypatch.setattr(wrap_mod, "_ml_wrap_extras_detected", lambda: False)
+ monkeypatch.setattr(wrap_mod, "_get_log_path", lambda: tmp_path / "proxy.log")
+ monkeypatch.setattr(wrap_mod, "_check_proxy", lambda _port: True)
+ monkeypatch.setattr(wrap_mod.time, "sleep", lambda seconds: sleeps.append(seconds))
+ monkeypatch.setattr(wrap_mod.subprocess, "Popen", lambda *args, **kwargs: fake_proc)
+
+ proc = wrap_mod._start_proxy(8787, agent_type="codex")
+
+ assert proc is fake_proc
+ assert sleeps == [1]
+ assert fake_proc.killed is False
+
+ def test_env_timeout_allows_slow_start_proxy_to_succeed(self, monkeypatch, tmp_path):
+ fake_proc = _FakeProxyProcess()
+ sleeps = []
+ checks = []
+
+ monkeypatch.setenv(wrap_mod._WRAP_PROXY_TIMEOUT_ENV, "4")
+ monkeypatch.setattr(wrap_mod, "_get_log_path", lambda: tmp_path / "proxy.log")
+ monkeypatch.setattr(wrap_mod.time, "sleep", lambda seconds: sleeps.append(seconds))
+ monkeypatch.setattr(wrap_mod.subprocess, "Popen", lambda *args, **kwargs: fake_proc)
+
+ def ready_on_fourth_check(port):
+ checks.append(port)
+ return len(checks) == 4
+
+ monkeypatch.setattr(wrap_mod, "_check_proxy", ready_on_fourth_check)
+
+ proc = wrap_mod._start_proxy(8787, agent_type="codex")
+
+ assert proc is fake_proc
+ assert checks == [8787, 8787, 8787, 8787]
+ assert sleeps == [1, 1, 1, 1]
+ assert fake_proc.killed is False
+
+ def test_timeout_error_names_configured_timeout_and_env_var(self, monkeypatch, tmp_path):
+ fake_proc = _FakeProxyProcess()
+
+ monkeypatch.setenv(wrap_mod._WRAP_PROXY_TIMEOUT_ENV, "2")
+ monkeypatch.setattr(wrap_mod, "_get_log_path", lambda: tmp_path / "proxy.log")
+ monkeypatch.setattr(wrap_mod, "_check_proxy", lambda _port: False)
+ monkeypatch.setattr(wrap_mod.time, "sleep", lambda _seconds: None)
+ monkeypatch.setattr(wrap_mod.subprocess, "Popen", lambda *args, **kwargs: fake_proc)
+
+ with pytest.raises(RuntimeError) as excinfo:
+ wrap_mod._start_proxy(8787, agent_type="codex")
+
+ message = str(excinfo.value)
+ assert "within 2 seconds" in message
+ assert wrap_mod._WRAP_PROXY_TIMEOUT_ENV in message
+ assert fake_proc.killed is True
+
+
class TestCLIProxyEnvVars:
"""Test that the CLI proxy command reads API URL env vars."""