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(wrap): carry the shared proxy's extensions over to a dedicated Copilot proxy (#4154)

Tejas Choprafeea130f8195
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index abf824b72..a7ece946a 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -763,6 +763,7 @@ def _start_proxy(
copilot_api_token: str | None = None,
copilot_refresh_oauth_token: str | None = None,
copilot_api_token_expires_at: float | None = None,
+ proxy_extensions: list[str] | None = None,
) -> subprocess.Popen:
"""Start Headroom proxy as a background subprocess.
@@ -824,6 +825,13 @@ def _start_proxy(
if vertex_api_url:
cmd.extend(["--vertex-api-url", vertex_api_url])
+ # Extensions carried over from the proxy this one replaces (see
+ # ``_dedicated_proxy_extensions``). The flag outranks the envvar in click,
+ # so callers must not pass this when HEADROOM_PROXY_EXTENSIONS is set;
+ # ``_ensure_proxy_unlocked`` checks that before asking.
+ if proxy_extensions:
+ cmd.extend(["--proxy-extension", ",".join(proxy_extensions)])
+
timeout_seconds = _resolve_wrap_proxy_timeout_seconds()
log_path = _get_log_path(port)
stdio_log_path = _get_proxy_stdio_log_path(port)
@@ -4584,6 +4592,68 @@ def _echo_unwrap_proxy_stop_status(status: str, port: int) -> None:
click.echo(f" Warning: failed to stop Headroom proxy on port {port}; stop it manually.")
+def _manifest_proxy_extensions(manifest: Any) -> list[str] | None:
+ """Extension names a persistent deployment was installed with.
+
+ Two places in the manifest can say: ``--proxy-extension`` flags in
+ ``proxy_args``, which the runtime passes to the proxy verbatim (an operator
+ who edited the manifest by hand), and ``HEADROOM_PROXY_EXTENSIONS`` in
+ ``base_env`` (``headroom install --env ...``, the only form the installer
+ writes). They are read the way the proxy reads them: click lets the flag
+ outrank the environment variable, so when ``proxy_args`` names any
+ extension that list is the whole answer and ``base_env`` is ignored.
+ A manifest with neither is no evidence either way: the deployment's
+ runtime env is layered on the launch environment, so the proxy may still
+ have inherited a set. Only an explicit value (possibly empty) is an answer.
+ """
+ flags: list[str] = []
+ args = getattr(manifest, "proxy_args", None)
+ if isinstance(args, (list, tuple)):
+ for i, arg in enumerate(args):
+ if arg == "--proxy-extension" and i + 1 < len(args):
+ flags.append(str(args[i + 1]))
+ elif isinstance(arg, str) and arg.startswith("--proxy-extension="):
+ flags.append(arg.partition("=")[2])
+ if flags:
+ values = flags
+ else:
+ base_env = getattr(manifest, "base_env", None)
+ configured = (
+ base_env.get("HEADROOM_PROXY_EXTENSIONS") if isinstance(base_env, dict) else None
+ )
+ if not isinstance(configured, str):
+ return None
+ values = [configured]
+ return sorted({name.strip() for value in values for name in value.split(",") if name.strip()})
+
+
+def _dedicated_proxy_extensions(port: int, manifest: Any) -> list[str] | None:
+ """Extensions the proxy owning *port* runs with, for a dedicated proxy to carry.
+
+ A wrap that cannot reuse the proxy on its port (a Copilot subscription
+ seed, or a persistent deployment with other routing) starts a dedicated
+ proxy from the shell environment alone. An enterprise install enables its
+ savings sinks on the shared proxy as ``--proxy-extension``, so without
+ this the dedicated proxy would report nothing upstream while its local
+ dashboard fills (#3716). Prefers the running proxy's own answer over the
+ manifest. Returns ``None`` when neither says, so the caller warns rather
+ than start bare on a guess.
+ """
+ helpers = _live_wrap_module()
+ payload = helpers._query_proxy_health(port)
+ if payload is not None and not helpers._is_headroom_health(payload):
+ return [] # a foreign service holds the port; it ran no extensions
+ running = helpers._proxy_health_config(payload)
+ found = running.get("proxy_extensions") if running is not None else None
+ if isinstance(found, list):
+ return sorted(str(name) for name in found)
+ # No config, or a proxy too old to report the field: the manifest is the
+ # next best witness.
+ if manifest is not None:
+ return _manifest_proxy_extensions(manifest)
+ return None
+
+
def _find_persistent_manifest(port: int) -> Any:
"""Return a matching persistent deployment manifest for the requested port."""
from headroom.install.state import list_manifests
@@ -5015,13 +5085,13 @@ def _ensure_proxy_unlocked(
f" Port {port} is in use by a non-Headroom service; selecting another port..."
)
proxy_listener = False
+ # Set False when the running proxy must not serve this session at all
+ # (unverifiable config, or a routing-level mismatch with live clients
+ # attached): fall through to a fresh start on a different port.
+ reuse_running = True
if proxy_listener:
# Proxy is running — check if it has the features we need
needs_restart = False
- # Set False when the running proxy must not serve this session at
- # all (routing-level mismatch with live clients attached): fall
- # through to a fresh start on a different port.
- reuse_running = True
routing_mismatches = (
None
if running_config is None
@@ -5223,6 +5293,30 @@ def _ensure_proxy_unlocked(
else:
click.echo(f" Port {port} is in use, using port {actual_port} instead.")
+ # This start leaves a running proxy on `port` in place and serves the
+ # session from `actual_port` beside it. Whatever that proxy reports
+ # through (an enterprise install's extensions) must come along, or the
+ # session's traffic vanishes from the team's dashboard while the local
+ # one fills (#3716).
+ replaces_running_proxy = (
+ isolated_copilot_subscription_proxy
+ or persistent_routing_mismatch
+ or (proxy_listener and not reuse_running)
+ )
+ proxy_extensions: list[str] | None = None
+ if replaces_running_proxy and "HEADROOM_PROXY_EXTENSIONS" not in os.environ:
+ proxy_extensions = helpers._dedicated_proxy_extensions(port, manifest)
+ if proxy_extensions is None:
+ click.echo(
+ f" Warning: could not read the extensions of the proxy on port {port}; "
+ f"the dedicated proxy on port {actual_port} starts without any. "
+ "Set HEADROOM_PROXY_EXTENSIONS=<names> to carry them."
+ )
+ elif proxy_extensions:
+ click.echo(
+ f" Extensions carried over from the proxy on port {port}: "
+ f"{','.join(proxy_extensions)}"
+ )
click.echo(f" Starting Headroom proxy on port {actual_port}...")
try:
proc = cast(
@@ -5243,6 +5337,7 @@ def _ensure_proxy_unlocked(
copilot_api_token=copilot_api_token,
copilot_refresh_oauth_token=copilot_refresh_oauth_token,
copilot_api_token_expires_at=copilot_api_token_expires_at,
+ proxy_extensions=proxy_extensions,
),
)
click.echo(_proxy_status_line("Proxy ready", actual_port))
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index e07abfc8f..1ac5fd80f 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -3772,6 +3772,10 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"cloudcode_api_url": config.cloudcode_api_url,
"vertex_api_url": config.vertex_api_url,
"savings_profile": config.savings_profile,
+ # Enabled extension names only (no plugin state): `headroom
+ # wrap` carries them over when it has to start a dedicated
+ # proxy beside this one, so an enterprise sink is not lost.
+ "proxy_extensions": sorted(config.proxy_extensions or []),
"target_ratio": effective_target_ratio,
"target_savings_percent": (
round(max(0.0, min(1.0, 1.0 - float(effective_target_ratio))) * 100, 1)
diff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.py
index 973584e5b..223608831 100644
--- a/tests/test_cli/test_wrap_helpers.py
+++ b/tests/test_cli/test_wrap_helpers.py
@@ -1175,3 +1175,33 @@ def test_missing_binary_error_goes_to_stderr_only(
assert result.exit_code == 1
assert result.stdout == ""
assert result.stderr.startswith(expected)
+
+
+def test_start_proxy_passes_carried_extensions_as_a_flag(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ captured: dict[str, object] = {}
+ proc = _FakeProxyProc()
+
+ def fake_popen(command: list[str], **kwargs: object) -> _FakeProxyProc:
+ captured["command"] = command
+ return proc
+
+ monkeypatch.setattr(wrap_mod.subprocess, "Popen", fake_popen)
+ monkeypatch.setattr(wrap_mod, "_check_proxy", lambda port: True)
+ monkeypatch.setattr(wrap_mod, "_get_log_path", lambda port=None: tmp_path / "proxy.log")
+ monkeypatch.setattr(
+ wrap_mod,
+ "_get_proxy_stdio_log_path",
+ lambda port=None: tmp_path / "proxy-stdio.log",
+ )
+ monkeypatch.setattr(wrap_mod.time, "sleep", lambda seconds: None)
+
+ wrap_mod._start_proxy(8788, proxy_extensions=["observability", "routemegood"])
+ command = captured["command"]
+ assert isinstance(command, list)
+ assert command[command.index("--proxy-extension") + 1] == "observability,routemegood"
+
+ wrap_mod._start_proxy(8788)
+ assert "--proxy-extension" not in captured["command"]
diff --git a/tests/test_cli/test_wrap_persistent.py b/tests/test_cli/test_wrap_persistent.py
index 828e84abb..7b36a8950 100644
--- a/tests/test_cli/test_wrap_persistent.py
+++ b/tests/test_cli/test_wrap_persistent.py
@@ -1151,6 +1151,7 @@ def test_ensure_proxy_starts_isolated_ephemeral_proxy_for_copilot_subscription_s
monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: port == 8787)
+ monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: None)
monkeypatch.setattr(
wrap_cli,
"_find_available_port",
@@ -1192,6 +1193,7 @@ def test_ensure_proxy_isolates_copilot_subscription_seed_with_api_token_only(mon
monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)
monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: port == 8787)
+ monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: None)
monkeypatch.setattr(
wrap_cli,
"_find_available_port",
@@ -1841,3 +1843,217 @@ def test_ensure_proxy_recovered_feature_restart_failure_raises(monkeypatch) -> N
with pytest.raises(click.ClickException, match="could not be restarted"):
wrap_cli._ensure_proxy(8787, False, memory=True)
+
+
+def _dedicated_start(monkeypatch, *, health, manifest=None):
+ """Drive a Copilot-seeded wrap that must start a dedicated proxy beside port 8787."""
+ calls: list[object] = []
+ monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: manifest)
+ monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: port == 8787)
+ monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: health)
+ monkeypatch.setattr(wrap_cli, "_find_available_port", lambda start_port, **kw: 8788)
+ monkeypatch.setattr(
+ wrap_cli, "_start_proxy", lambda *args, **kwargs: calls.append(("start", args, kwargs))
+ )
+ wrap_cli._ensure_proxy(8787, False, copilot_api_token="tid-session-token")
+ assert calls and calls[0][0] == "start"
+ return calls[0][2]
+
+
+def test_dedicated_copilot_proxy_carries_the_shared_proxys_extensions(monkeypatch, capsys) -> None:
+ """An enterprise shared proxy enables its savings sinks with --proxy-extension;
+ the dedicated proxy a Copilot seed forces must keep reporting through them."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+ health = {"config": {"pid": "1", "proxy_extensions": ["routemegood", "observability"]}}
+
+ kwargs = _dedicated_start(monkeypatch, health=health)
+
+ assert kwargs["proxy_extensions"] == ["observability", "routemegood"]
+ assert "Extensions carried over from the proxy on port 8787: observability,routemegood" in (
+ capsys.readouterr().out
+ )
+
+
[email protected]("configured", ["teams", ""])
+def test_dedicated_copilot_proxy_env_extensions_win(monkeypatch, capsys, configured) -> None:
+ """The env var is inherited by the subprocess and outranks the carry-over;
+ an empty value is the documented way to start a bare dedicated proxy."""
+ monkeypatch.setenv("HEADROOM_PROXY_EXTENSIONS", configured)
+ health = {"config": {"pid": "1", "proxy_extensions": ["observability"]}}
+
+ kwargs = _dedicated_start(monkeypatch, health=health)
+
+ assert kwargs["proxy_extensions"] is None
+ out = capsys.readouterr().out
+ assert "carried over" not in out
+ assert "could not read the extensions" not in out
+
+
+def test_dedicated_copilot_proxy_ignores_a_foreign_port_holder(monkeypatch, capsys) -> None:
+ """A non-Headroom service on the port ran no extensions: nothing to carry, no warning."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ kwargs = _dedicated_start(monkeypatch, health={"status": "ok"})
+
+ assert not kwargs["proxy_extensions"]
+ assert "could not read the extensions" not in capsys.readouterr().out
+
+
+def test_dedicated_copilot_proxy_warns_when_the_shared_proxy_hides_its_extensions(
+ monkeypatch, capsys
+) -> None:
+ """A proxy that predates the /health field cannot be read; say so instead of
+ silently starting bare."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ kwargs = _dedicated_start(monkeypatch, health={"config": {"pid": "1"}})
+
+ assert kwargs["proxy_extensions"] is None
+ out = capsys.readouterr().out
+ assert "Warning: could not read the extensions of the proxy on port 8787" in out
+ assert "HEADROOM_PROXY_EXTENSIONS=<names>" in out
+
+
+def test_dedicated_copilot_proxy_reads_extensions_from_the_manifest(monkeypatch) -> None:
+ """With no reachable /health, the manifest's recorded environment says what ran."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ class _ExtManifest(_Manifest):
+ base_env = {"HEADROOM_PROXY_EXTENSIONS": "observability, lossless_guard"}
+
+ kwargs = _dedicated_start(monkeypatch, health=None, manifest=_ExtManifest())
+
+ assert kwargs["proxy_extensions"] == ["lossless_guard", "observability"]
+
+
+def test_dedicated_copilot_proxy_reads_extensions_from_the_manifest_proxy_args(monkeypatch) -> None:
+ """A manifest edited by hand can enable extensions as ``--proxy-extension``
+ flags in ``proxy_args``; the runtime passes them to the proxy verbatim, so
+ they count, in both flag forms. Click lets the flag outrank
+ ``HEADROOM_PROXY_EXTENSIONS``, so a ``base_env`` value next to the flags is
+ not something the shared proxy ran and must not be carried."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ class _ArgsManifest(_Manifest):
+ base_env = {"HEADROOM_PROXY_EXTENSIONS": "skill_search"}
+ proxy_args = [
+ "--host",
+ "127.0.0.1",
+ "--proxy-extension",
+ "observability,control_plane",
+ "--proxy-extension=lossless_guard",
+ ]
+
+ kwargs = _dedicated_start(monkeypatch, health=None, manifest=_ArgsManifest())
+
+ assert kwargs["proxy_extensions"] == ["control_plane", "lossless_guard", "observability"]
+
+
+def test_dedicated_copilot_proxy_falls_back_to_the_manifest_for_an_older_proxy(
+ monkeypatch, capsys
+) -> None:
+ """A running proxy that predates the /health field is not the last word when
+ the deployment's manifest records what it was installed with."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ class _ExtManifest(_Manifest):
+ base_env = {"HEADROOM_PROXY_EXTENSIONS": "control_plane"}
+
+ kwargs = _dedicated_start(monkeypatch, health={"config": {"pid": "1"}}, manifest=_ExtManifest())
+
+ assert kwargs["proxy_extensions"] == ["control_plane"]
+ assert "could not read the extensions" not in capsys.readouterr().out
+
+
+def test_dedicated_copilot_proxy_warns_for_an_older_proxy_whose_manifest_is_silent(
+ monkeypatch, capsys
+) -> None:
+ """A manifest without HEADROOM_PROXY_EXTENSIONS does not prove the running
+ proxy has none (its runtime env layers on the launch environment), so an
+ older proxy plus a silent manifest is unknown and warns."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ class _SilentManifest(_Manifest):
+ base_env = {"ANTHROPIC_API_KEY": "sk-ant-redacted"}
+
+ kwargs = _dedicated_start(
+ monkeypatch, health={"config": {"pid": "1"}}, manifest=_SilentManifest()
+ )
+
+ assert kwargs["proxy_extensions"] is None
+ assert "Warning: could not read the extensions of the proxy on port 8787" in (
+ capsys.readouterr().out
+ )
+
+
+def test_dedicated_copilot_proxy_trusts_an_explicitly_empty_manifest_value(
+ monkeypatch, capsys
+) -> None:
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+
+ class _BareManifest(_Manifest):
+ base_env = {"HEADROOM_PROXY_EXTENSIONS": ""}
+
+ kwargs = _dedicated_start(monkeypatch, health=None, manifest=_BareManifest())
+
+ assert not kwargs["proxy_extensions"]
+ assert "could not read the extensions" not in capsys.readouterr().out
+
+
+def test_attached_routing_mismatch_carries_the_shared_proxys_extensions(
+ monkeypatch, capsys
+) -> None:
+ """The non-persistent shared proxy with live clients and other routing is
+ left running; the dedicated proxy started beside it keeps its extensions."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+ calls: list[object] = []
+ health = {
+ "version": wrap_cli._HEADROOM_VERSION,
+ "runtime": {"websocket_sessions": {"active_sessions": 0, "active_relay_tasks": 0}},
+ "config": {
+ "pid": "12345",
+ "backend": "anthropic",
+ "augment_api_url": "https://xlb.api.augmentcode.com",
+ "proxy_extensions": ["control_plane", "observability"],
+ },
+ }
+ monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)
+ monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: port == 8787)
+ monkeypatch.setattr(wrap_cli, "_query_proxy_health", lambda port: health)
+ monkeypatch.setattr(wrap_cli, "_live_proxy_clients", lambda *a, **kw: [999])
+ monkeypatch.setattr(wrap_cli, "_find_available_port", lambda start_port, **kw: 8799)
+ monkeypatch.setattr(
+ wrap_cli,
+ "_kill_proxy_by_pid",
+ lambda *args, **kwargs: (_ for _ in ()).throw(AssertionError("must not be killed")),
+ )
+ monkeypatch.setattr(
+ wrap_cli, "_start_proxy", lambda *args, **kwargs: calls.append(("start", args, kwargs))
+ )
+
+ proc, actual_port = wrap_cli._ensure_proxy(8787, False)
+
+ assert (proc, actual_port) == (None, 8799)
+ assert calls[0][2]["proxy_extensions"] == ["control_plane", "observability"]
+ assert "Extensions carried over from the proxy on port 8787" in capsys.readouterr().out
+
+
+def test_plain_start_passes_no_extensions(monkeypatch) -> None:
+ """Nothing owns the port: the proxy starts from the shell env as before."""
+ monkeypatch.delenv("HEADROOM_PROXY_EXTENSIONS", raising=False)
+ calls: list[object] = []
+ monkeypatch.setattr(wrap_cli, "_find_persistent_manifest", lambda port: None)
+ monkeypatch.setattr(wrap_cli, "_check_proxy", lambda port: False)
+ monkeypatch.setattr(
+ wrap_cli,
+ "_query_proxy_health",
+ lambda port: (_ for _ in ()).throw(AssertionError("no proxy to ask")),
+ )
+ monkeypatch.setattr(wrap_cli, "_find_available_port", lambda start_port, **kw: 8787)
+ monkeypatch.setattr(
+ wrap_cli, "_start_proxy", lambda *args, **kwargs: calls.append(("start", args, kwargs))
+ )
+
+ wrap_cli._ensure_proxy(8787, False)
+
+ assert calls[0][2]["proxy_extensions"] is None
diff --git a/tests/test_proxy_healthchecks.py b/tests/test_proxy_healthchecks.py
index 82b165f5f..046d55993 100644
--- a/tests/test_proxy_healthchecks.py
+++ b/tests/test_proxy_healthchecks.py
@@ -333,3 +333,21 @@ def test_health_includes_upstream_check_result(monkeypatch):
assert "enabled" in upstream
assert "ready" in upstream
assert "status" in upstream
+
+
+def test_health_reports_enabled_proxy_extensions():
+ """`headroom wrap` reads this to carry the shared proxy's extensions over to a
+ dedicated proxy it has to start beside it."""
+ config = ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ proxy_extensions=["routemegood", "observability"],
+ )
+ app = create_app(config)
+
+ with TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)) as client:
+ reported = client.get("/health").json()["config"]
+
+ assert reported["proxy_extensions"] == ["observability", "routemegood"]