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
"""Tests for `headroom wrap zcode` and `headroom unwrap zcode` commands.
ZCode is a desktop Electron app (zcode.z.ai) with no CLI binary. The wrap
command follows the Pattern-B (proxy-only watcher) approach: it starts the
proxy and prints the ZCode settings the user should configure in the app's
settings UI.
"""
from __future__ import annotations
import json
from pathlib import Path
from unittest.mock import patch
import pytest
from click.testing import CliRunner
from headroom.cli import wrap as wrap_mod
from headroom.cli.main import main
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
# ---------------------------------------------------------------------------
# Wrap: setup instructions output
# ---------------------------------------------------------------------------
def test_wrap_prints_proxy_urls(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""The wrap command must print the proxy URLs for ZCode configuration."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
def fake_watcher(**kwargs): # noqa: ANN003
print_fn = kwargs.get("print_setup_lines")
if callable(print_fn):
print_fn(kwargs["port"])
with patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=fake_watcher):
result = runner.invoke(main, ["wrap", "zcode", "--port", "9000"])
assert result.exit_code == 0, result.output
assert "http://127.0.0.1:9000/v1" in result.output
assert "http://127.0.0.1:9000" in result.output
assert "Settings > Model Settings" in result.output
# ---------------------------------------------------------------------------
# Runtime: proxy targets
# ---------------------------------------------------------------------------
def test_build_proxy_targets() -> None:
"""build_proxy_targets returns correct OpenAI and Anthropic URLs."""
from headroom.providers.zcode.runtime import build_proxy_targets
targets = build_proxy_targets(8787)
assert targets.openai_base_url == "http://127.0.0.1:8787/v1"
assert targets.anthropic_base_url == "http://127.0.0.1:8787"
def test_build_proxy_targets_custom_port() -> None:
"""build_proxy_targets respects custom port."""
from headroom.providers.zcode.runtime import build_proxy_targets
targets = build_proxy_targets(9999)
assert targets.openai_base_url == "http://127.0.0.1:9999/v1"
assert targets.anthropic_base_url == "http://127.0.0.1:9999"
def test_render_setup_lines_includes_mcp_instruction() -> None:
"""render_setup_lines includes the MCP paste JSON for user convenience."""
from headroom.providers.zcode.runtime import render_setup_lines
lines = render_setup_lines(8787)
joined = "\n".join(lines)
assert "headroom" in joined.lower()
assert "MCP" in joined
assert '"stdio"' in joined
# ---------------------------------------------------------------------------
# Runtime: upstream detection
# ---------------------------------------------------------------------------
def test_detect_upstream_from_config(tmp_path: Path) -> None:
"""detect_upstream reads config.json and returns the enabled provider."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
'{"provider": {"zai": {"name": "Z.ai", "kind": "anthropic", '
'"enabled": true, "options": {"baseURL": "https://api.z.ai/api/anthropic"}}}}',
encoding="utf-8",
)
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
assert upstream.kind == "anthropic"
def test_detect_upstream_openai_compatible(tmp_path: Path) -> None:
"""detect_upstream handles OpenAI-compatible providers."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
'{"provider": {"custom": {"name": "Custom", "kind": "openai", '
'"enabled": true, "options": {"baseURL": "https://my-api.example.com/v1"}}}}',
encoding="utf-8",
)
upstream = detect_upstream(config)
assert upstream.kind == "openai"
assert upstream.base_url == "https://my-api.example.com/v1"
def test_detect_upstream_disabled_provider_ignored(tmp_path: Path) -> None:
"""detect_upstream skips disabled providers."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
'{"provider": {"zai": {"name": "Z.ai", "kind": "anthropic", '
'"enabled": false, "options": {"baseURL": "https://api.z.ai/api/anthropic"}}}}',
encoding="utf-8",
)
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
def test_detect_upstream_no_baseurl_skips(tmp_path: Path) -> None:
"""detect_upstream skips providers with empty or missing baseURL."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
'{"provider": {"zai": {"name": "Z.ai", "kind": "anthropic", '
'"enabled": true, "options": {"baseURL": ""}}}}',
encoding="utf-8",
)
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
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"
@pytest.mark.parametrize("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",
[
None,
[],
42,
"just a string",
],
ids=["null", "list", "int", "string"],
)
def test_detect_upstream_malformed_options_skips(tmp_path: Path, bad_options: object) -> None:
"""detect_upstream falls back when provider options is not a dict."""
import json as _json
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text(
_json.dumps(
{
"provider": {
"bad": {
"name": "Bad Provider",
"kind": "anthropic",
"enabled": True,
"options": bad_options,
}
}
}
),
encoding="utf-8",
)
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
def test_detect_upstream_missing_file_fallback(tmp_path: Path) -> None:
"""detect_upstream falls back to default when config file is missing."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "nonexistent.json"
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
assert upstream.kind == "anthropic"
def test_detect_upstream_invalid_json_fallback(tmp_path: Path) -> None:
"""detect_upstream falls back to default on malformed JSON."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text("not json at all", encoding="utf-8")
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
def test_detect_upstream_no_providers_fallback(tmp_path: Path) -> None:
"""detect_upstream falls back when config has no provider section."""
from headroom.providers.zcode.runtime import detect_upstream
config = tmp_path / "config.json"
config.write_text('{"settings": {}}', encoding="utf-8")
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai (default)"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
# ---------------------------------------------------------------------------
# Runtime: upstream to proxy URLs
# ---------------------------------------------------------------------------
def test_upstream_to_proxy_urls_anthropic() -> None:
"""upstream_to_proxy_urls returns (url, None) for anthropic upstream."""
from headroom.providers.zcode.runtime import ZCodeUpstream, upstream_to_proxy_urls
upstream = ZCodeUpstream(
provider_name="Z.ai", base_url="https://api.z.ai/api/anthropic", kind="anthropic"
)
anthropic_url, openai_url = upstream_to_proxy_urls(upstream)
assert anthropic_url == "https://api.z.ai/api/anthropic"
assert openai_url is None
def test_upstream_to_proxy_urls_openai() -> None:
"""upstream_to_proxy_urls returns (None, url) for openai-compatible upstream."""
from headroom.providers.zcode.runtime import ZCodeUpstream, upstream_to_proxy_urls
upstream = ZCodeUpstream(
provider_name="Custom",
base_url="https://my-api.example.com/v1",
kind="openai",
)
anthropic_url, openai_url = upstream_to_proxy_urls(upstream)
assert anthropic_url is None
assert openai_url == "https://my-api.example.com/v1"
# ---------------------------------------------------------------------------
# Wrap: upstream detection integration
# ---------------------------------------------------------------------------
def test_wrap_zcode_detects_upstream(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""wrap zcode detects upstream and prints detected provider in setup."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
config = tmp_path / "config.json"
config.write_text(
'{"provider": {"zai": {"name": "Z.ai Coding", "kind": "anthropic", '
'"enabled": true, "options": {"baseURL": "https://api.z.ai/api/anthropic"}}}}',
encoding="utf-8",
)
from headroom.providers.zcode.runtime import detect_upstream, upstream_to_proxy_urls
upstream = detect_upstream(config)
assert upstream.provider_name == "Z.ai Coding"
assert upstream.base_url == "https://api.z.ai/api/anthropic"
anthropic_url, openai_url = upstream_to_proxy_urls(upstream)
assert anthropic_url == "https://api.z.ai/api/anthropic"
assert openai_url is None
def test_wrap_zcode_passes_upstream_to_watcher(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""wrap zcode forwards detected upstream URLs to _run_proxy_only_watcher."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
from headroom.providers.zcode.runtime import ZCodeUpstream
captured: dict[str, object] = {}
def fake_watcher(**kwargs): # noqa: ANN003
captured.update(kwargs)
fake_upstream = ZCodeUpstream(
provider_name="Z.ai", base_url="https://api.z.ai/api/anthropic", kind="anthropic"
)
with patch.object(wrap_mod, "_detect_zcode_upstream", return_value=fake_upstream):
with patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=fake_watcher):
runner.invoke(main, ["wrap", "zcode", "--port", "9000"])
assert captured.get("anthropic_api_url") == "https://api.z.ai/api/anthropic"
assert captured.get("openai_api_url") is None
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,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""wrap zcode forwards OpenAI-compatible upstream URLs correctly."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
from headroom.providers.zcode.runtime import ZCodeUpstream
captured: dict[str, object] = {}
def fake_watcher(**kwargs): # noqa: ANN003
captured.update(kwargs)
fake_upstream = ZCodeUpstream(
provider_name="Custom", base_url="https://my-api.example.com/v1", kind="openai"
)
with patch.object(wrap_mod, "_detect_zcode_upstream", return_value=fake_upstream):
with patch.object(wrap_mod, "_run_proxy_only_watcher", side_effect=fake_watcher):
runner.invoke(main, ["wrap", "zcode", "--port", "9000"])
assert captured.get("anthropic_api_url") is None
assert captured.get("openai_api_url") == "https://my-api.example.com/v1"
@pytest.mark.parametrize("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"