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(wrap): report unbindable proxy ports (#602)
oxura6dfcaa839f11
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 0959a602f..3e51e0eb3 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -141,6 +141,29 @@ def _check_proxy(port: int) -> bool:return False+def _port_bind_error(port: int) -> OSError | None:+ """Return the bind error for a local proxy port, or None when it is usable."""+ try:+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:+ s.bind(("127.0.0.1", port))+ except OSError as exc:+ return exc+ return None+++def _format_unbindable_port_error(port: int, error: OSError, agent_type: str) -> str:+ """Build an actionable message for ports that fail before uvicorn can bind."""+ command = "headroom proxy"+ if agent_type != "unknown":+ command = f"headroom wrap {agent_type}"+ suggested_port = port + 1+ return (+ f"Port {port} is unavailable on 127.0.0.1 before the proxy can start: {error}. "+ "On Windows this can happen when the port is in an excluded or reserved range. "+ f"Rerun with a different port, for example `{command} --port {suggested_port}`."+ )++def _get_log_path() -> Path:"""Get path for proxy log file."""from headroom import paths as _paths@@ -1740,6 +1763,12 @@ def _ensure_proxy(return None# Start (or restart) the proxy with the requested flags+ bind_error = helpers._port_bind_error(port)+ if bind_error is not None:+ raise click.ClickException(+ helpers._format_unbindable_port_error(port, bind_error, agent_type)+ )+click.echo(f" Starting Headroom proxy on port {port}...")try:proc = cast(diff --git a/tests/test_cli/test_wrap_persistent.py b/tests/test_cli/test_wrap_persistent.pyindex 83503a1e9..4531e5d73 100644--- a/tests/test_cli/test_wrap_persistent.py+++ b/tests/test_cli/test_wrap_persistent.py@@ -88,6 +88,31 @@ def test_ensure_proxy_falls_back_when_persistent_manifest_is_stale(monkeypatch)assert calls == ["start"]+def test_ensure_proxy_reports_unbindable_port_before_starting_subprocess(monkeypatch) -> None:+ calls: list[str] = []++ monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: False)+ monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)+ monkeypatch.setattr(+ wrap_cli,+ "_port_bind_error",+ lambda port: PermissionError(10013, "access denied by OS port reservation"),+ )+ monkeypatch.setattr(wrap_cli, "_start_proxy", lambda *args, **kwargs: calls.append("start"))++ try:+ wrap_cli._ensure_proxy(8787, False, agent_type="cursor")+ except click.ClickException as exc:+ message = str(exc)+ else:+ raise AssertionError("expected unbindable port to raise before starting proxy")++ assert "Port 8787 is unavailable" in message+ assert "Windows" in message+ assert "headroom wrap cursor --port 8788" in message+ assert calls == []++def test_ensure_proxy_restarts_idle_stale_persistent_deployment(monkeypatch) -> None:calls: list[str] = []health = {