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(zcode): skip providers that point at the Headroom proxy itself (#4413)
HetCreep9ac1b52c2762
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex c51c3f4f6..e3cc4ebf8 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -8110,7 +8110,15 @@ def zcode(if prepare_only:return- upstream = _detect_zcode_upstream()+ # _ensure_proxy moves to another port when the requested one is held by a+ # non-Headroom service. Resolve that port first so the upstream is chosen+ # against the port the proxy will actually bind.+ if not no_proxy and not (_check_proxy(port) and not _foreign_listener(port)):+ try:+ port = _find_available_port(port)+ except (OSError, RuntimeError):+ pass # _ensure_proxy reports the same error+ upstream = _detect_zcode_upstream(proxy_port=port)anthropic_url, openai_url = _zcode_upstream_to_urls(upstream)def _print_zcode_setup(actual_port: int = port) -> None:diff --git a/headroom/providers/zcode/runtime.py b/headroom/providers/zcode/runtime.pyindex 32d921568..a0be73a02 100644--- a/headroom/providers/zcode/runtime.py+++ b/headroom/providers/zcode/runtime.py@@ -6,6 +6,7 @@ import jsonimport loggingfrom dataclasses import dataclassfrom pathlib import Path+from urllib.parse import urlsplitfrom headroom.install.paths import zcode_config_dirfrom headroom.providers.claude import proxy_base_url as _claude_proxy_base_url@@ -40,11 +41,30 @@ def build_proxy_targets(port: int) -> ZCodeProxyTargets:)-def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:+def _points_at_proxy(base_url: str, proxy_port: int | None) -> bool:+ """True when *base_url* names the Headroom proxy: its advertised host and port.++ Policy: the proxy is advertised on ``127.0.0.1`` (see ``build_proxy_targets``)+ and ``localhost`` is treated as that same host. ``[::1]`` is a different+ socket, so an IPv6 provider on the same port is a real upstream, not the proxy.+ """+ if proxy_port is None:+ return False+ try:+ parts = urlsplit(base_url)+ return parts.hostname in ("127.0.0.1", "localhost") and parts.port == proxy_port+ except ValueError:+ return False+++def detect_upstream(+ config_path: Path | None = None, proxy_port: int | None = None+) -> ZCodeUpstream:"""Read ZCode config.json and find the enabled provider's upstream URL.Resolution order:- 1. First provider with ``enabled=True`` and a non-empty ``baseURL``.+ 1. First provider with ``enabled=True`` and a non-empty ``baseURL`` that+ does not point at the Headroom proxy itself (``proxy_port``).2. Fallback: Z.ai Anthropic endpoint.Parameters@@ -52,6 +72,10 @@ def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:config_path:Override for the config file path. When *None* the default``~/.zcode/v2/config.json`` is used.+ proxy_port:+ Port of the local Headroom proxy. A provider whose ``baseURL`` is a+ loopback URL on this port is skipped, because ZCode users are told to+ point a provider at the proxy and using it as the upstream would loop."""if config_path is None:config_path = zcode_config_dir() / "v2" / "config.json"@@ -83,8 +107,11 @@ def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:opts = provider.get("options", {})if not isinstance(opts, dict):continue- base_url = opts.get("baseURL", "").strip()- if not base_url:+ base_url = opts.get("baseURL")+ if not isinstance(base_url, str):+ continue+ base_url = base_url.strip()+ if not base_url or _points_at_proxy(base_url, proxy_port):continuekind = provider.get("kind", "anthropic")name = provider.get("name", "ZCode provider")diff --git a/tests/test_cli/test_wrap_zcode.py b/tests/test_cli/test_wrap_zcode.pyindex c82f7c275..382132180 100644--- a/tests/test_cli/test_wrap_zcode.py+++ b/tests/test_cli/test_wrap_zcode.py@@ -8,6 +8,7 @@ settings UI.from __future__ import annotations+import jsonfrom pathlib import Pathfrom unittest.mock import patch@@ -151,6 +152,113 @@ def test_detect_upstream_no_baseurl_skips(tmp_path: Path) -> None:assert upstream.base_url == "https://api.z.ai/api/anthropic"+def test_detect_upstream_skips_provider_pointing_at_proxy(tmp_path: Path) -> None:+ """A provider set to the Headroom proxy itself must not become the upstream."""+ import json as _json++ from headroom.providers.zcode.runtime import detect_upstream++ config = tmp_path / "config.json"+ config.write_text(+ _json.dumps(+ {+ "provider": {+ "headroom": {+ "name": "Headroom",+ "kind": "anthropic",+ "enabled": True,+ "options": {"baseURL": "http://127.0.0.1:8787"},+ },+ "local": {+ "name": "Local",+ "kind": "openai",+ "enabled": True,+ "options": {"baseURL": "http://localhost:8787/v1"},+ },+ "other-port": {+ "name": "Other",+ "kind": "openai",+ "enabled": True,+ "options": {"baseURL": "http://127.0.0.1:9999/v1"},+ },+ }+ }+ ),+ encoding="utf-8",+ )+ upstream = detect_upstream(config, proxy_port=8787)+ assert upstream.provider_name == "Other"+ assert upstream.base_url == "http://127.0.0.1:9999/v1"+++def test_detect_upstream_only_proxy_provider_falls_back(tmp_path: Path) -> None:+ """With only a proxy-pointing provider the Z.ai default is used."""+ from headroom.providers.zcode.runtime import detect_upstream++ config = tmp_path / "config.json"+ config.write_text(+ '{"provider": {"headroom": {"name": "Headroom", "kind": "anthropic", '+ '"enabled": true, "options": {"baseURL": "http://127.0.0.1:8787"}}}}',+ encoding="utf-8",+ )+ upstream = detect_upstream(config, proxy_port=8787)+ assert upstream.provider_name == "Z.ai (default)"+++def test_detect_upstream_keeps_ipv6_provider_when_proxy_is_ipv4(tmp_path: Path) -> None:+ """[::1] is a different socket from the 127.0.0.1 proxy, so it stays selectable."""+ import json as _json++ from headroom.providers.zcode.runtime import detect_upstream++ config = tmp_path / "config.json"+ config.write_text(+ _json.dumps(+ {+ "provider": {+ "v6": {+ "name": "Local v6",+ "kind": "anthropic",+ "enabled": True,+ "options": {"baseURL": "http://[::1]:8787"},+ }+ }+ }+ ),+ encoding="utf-8",+ )+ upstream = detect_upstream(config, proxy_port=8787)+ assert upstream.provider_name == "Local v6"+ assert upstream.base_url == "http://[::1]:8787"++[email protected]("base_url", [None, 42, ["x"]], ids=["null", "int", "list"])+def test_detect_upstream_non_string_baseurl_skips(tmp_path: Path, base_url: object) -> None:+ """detect_upstream falls back instead of raising when baseURL is not a string."""+ import json as _json++ from headroom.providers.zcode.runtime import detect_upstream++ config = tmp_path / "config.json"+ config.write_text(+ _json.dumps(+ {+ "provider": {+ "zai": {+ "name": "Z.ai",+ "kind": "anthropic",+ "enabled": True,+ "options": {"baseURL": base_url},+ }+ }+ }+ ),+ encoding="utf-8",+ )+ upstream = detect_upstream(config)+ assert upstream.provider_name == "Z.ai (default)"++@pytest.mark.parametrize("bad_options",[@@ -313,6 +421,74 @@ def test_wrap_zcode_passes_upstream_to_watcher(assert captured.get("port") == 9000+def _zcode_config_with(tmp_path: Path, base_url: str) -> Path:+ home = tmp_path / "zhome"+ (home / "v2").mkdir(parents=True)+ (home / "v2" / "config.json").write_text(+ json.dumps(+ {+ "provider": {+ "p": {+ "name": "P",+ "kind": "anthropic",+ "enabled": True,+ "options": {"baseURL": base_url},+ }+ }+ }+ ),+ encoding="utf-8",+ )+ return home+++def _run_zcode_with_port_busy(+ runner: CliRunner, tmp_path: Path, base_url: str, *, busy: bool+) -> dict[str, object]:+ """Run ``wrap zcode --port 8787``; port 8787 is held by a foreign service when *busy*."""+ captured: dict[str, object] = {}+ home = _zcode_config_with(tmp_path, base_url)+ with (+ patch("headroom.providers.zcode.runtime.zcode_config_dir", return_value=home),+ patch.object(wrap_mod, "_check_proxy", return_value=busy),+ patch.object(wrap_mod, "_foreign_listener", return_value=busy),+ patch.object(wrap_mod, "_find_available_port", return_value=8788 if busy else 8787),+ patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=captured.update),+ ):+ runner.invoke(main, ["wrap", "zcode", "--port", "8787"])+ return captured+++def test_wrap_zcode_port_fallback_keeps_backend_on_busy_port(+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """A backend on the occupied port stays a valid upstream; the proxy moves to 8788."""+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ captured = _run_zcode_with_port_busy(runner, tmp_path, "http://127.0.0.1:8787", busy=True)+ assert captured["port"] == 8788+ assert captured["anthropic_api_url"] == "http://127.0.0.1:8787"+++def test_wrap_zcode_port_fallback_skips_provider_on_replacement_port(+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """A provider pointing at the replacement port is the proxy itself, not an upstream."""+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ captured = _run_zcode_with_port_busy(runner, tmp_path, "http://127.0.0.1:8788", busy=True)+ assert captured["port"] == 8788+ assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"+++def test_wrap_zcode_free_port_unchanged(+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """With the requested port free, a provider on it is still skipped as the proxy."""+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ captured = _run_zcode_with_port_busy(runner, tmp_path, "http://127.0.0.1:8787", busy=False)+ assert captured["port"] == 8787+ assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"++def test_wrap_zcode_passes_openai_upstream(runner: CliRunner,tmp_path: Path,@@ -339,3 +515,69 @@ def test_wrap_zcode_passes_openai_upstream(assert captured.get("anthropic_api_url") is Noneassert captured.get("openai_api_url") == "https://my-api.example.com/v1"++[email protected]("base_url", ["http://127.0.0.1:99999", "http://127.0.0.1:abc"])+def test_detect_upstream_keeps_provider_with_unparseable_port(+ tmp_path: Path, base_url: str+) -> None:+ """A port urlsplit cannot read is not the proxy's port, so the provider stays selectable."""+ from headroom.providers.zcode.runtime import detect_upstream++ config = tmp_path / "config.json"+ config.write_text(+ json.dumps(+ {+ "provider": {+ "odd": {+ "name": "Odd port",+ "kind": "anthropic",+ "enabled": True,+ "options": {"baseURL": base_url},+ }+ }+ }+ ),+ encoding="utf-8",+ )+ upstream = detect_upstream(config, proxy_port=8787)+ assert upstream.provider_name == "Odd port"+++def test_wrap_zcode_keeps_requested_port_when_no_free_port_is_found(+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """If the free-port search fails, the upstream is chosen against the requested port."""+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ captured: dict[str, object] = {}+ home = _zcode_config_with(tmp_path, "http://127.0.0.1:8787")+ with (+ patch("headroom.providers.zcode.runtime.zcode_config_dir", return_value=home),+ patch.object(wrap_mod, "_check_proxy", return_value=False),+ patch.object(wrap_mod, "_foreign_listener", return_value=False),+ patch.object(wrap_mod, "_find_available_port", side_effect=RuntimeError("no port")),+ patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=captured.update),+ ):+ runner.invoke(main, ["wrap", "zcode", "--port", "8787"])+ assert captured["port"] == 8787+ assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"+++def test_wrap_zcode_reuses_running_headroom_proxy_port(+ runner: CliRunner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """A Headroom proxy already on the port is reused; no other port is searched for."""+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ captured: dict[str, object] = {}+ home = _zcode_config_with(tmp_path, "http://127.0.0.1:8787")+ with (+ patch("headroom.providers.zcode.runtime.zcode_config_dir", return_value=home),+ patch.object(wrap_mod, "_check_proxy", return_value=True),+ patch.object(wrap_mod, "_foreign_listener", return_value=False),+ patch.object(wrap_mod, "_find_available_port") as find_port,+ patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=captured.update),+ ):+ runner.invoke(main, ["wrap", "zcode", "--port", "8787"])+ find_port.assert_not_called()+ assert captured["port"] == 8787+ assert captured["anthropic_api_url"] == "https://api.z.ai/api/anthropic"