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(zcode): skip providers that point at the Headroom proxy itself (#4413)

HetCreep9ac1b52c2762
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 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.py
index 32d921568..a0be73a02 100644
--- a/headroom/providers/zcode/runtime.py
+++ b/headroom/providers/zcode/runtime.py
@@ -6,6 +6,7 @@ import json
import logging
from dataclasses import dataclass
from pathlib import Path
+from urllib.parse import urlsplit
from headroom.install.paths import zcode_config_dir
from 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):
continue
kind = 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.py
index 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 json
from pathlib import Path
from 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 None
assert 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"