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(install): apply managed env vars added after a deployment was installed (#3740)
Tejas Chopraa4cb2bc02144
diff --git a/headroom/cli/install.py b/headroom/cli/install.pyindex a81a7d941..195e220e4 100644--- a/headroom/cli/install.py+++ b/headroom/cli/install.py@@ -23,7 +23,7 @@ from headroom.install.models import (RuntimeKind,SupervisorKind,)-from headroom.install.planner import build_manifest+from headroom.install.planner import build_manifest, build_tool_envsfrom headroom.install.providers import apply_mutations, revert_mutationsfrom headroom.install.runtime import (acquire_runtime_start_lock,@@ -204,7 +204,77 @@ def _deactivate_deployment_mutations(save_manifest(manifest)+def _reconcile_tool_envs(manifest: DeploymentManifest) -> dict[str, list[str]]:+ """Add managed env vars introduced since this manifest was written.++ ``tool_envs`` is built once, by ``build_manifest`` during ``headroom+ install``, and then stored. Every later lifecycle command re-applies the+ STORED map, so a variable added to a provider's install env afterwards never+ reaches a deployment that already exists -- not on ``start``, not on+ ``restart``, and not on a Headroom upgrade. The only cure was reinstalling,+ which nobody does for a proxy that is working.++ That is not hypothetical. ``ENABLE_TOOL_SEARCH`` was added to Claude's+ install env on 2026-06-19 to stop Claude Code inlining every MCP schema when+ it sees a custom ``ANTHROPIC_BASE_URL`` (GH #746). A deployment installed+ before that date keeps getting the base URL written without it, so the+ client is pointed at the proxy AND has its own tool-schema deferral switched+ off -- the expensive half of the change with none of the mitigation.++ Missing keys are ADDED; existing values are never overwritten. The stored+ value may legitimately differ from a fresh build (a hand-edited port, a+ deployment pinned to something specific), and healing an omission is a much+ smaller claim than re-deciding a setting the manifest already records.+ Returns the names added per target, for reporting.+ """++ added: dict[str, list[str]] = {}+ for target, values in pending_tool_envs(manifest).items():+ stored = manifest.tool_envs.get(target)+ if not isinstance(stored, dict):+ # Absent, or hand-edited into something that is not a mapping. Either+ # way the managed values are what this deployment should have, and+ # ``stored.update`` on a string would crash a lifecycle command.+ manifest.tool_envs[target] = dict(values)+ else:+ stored.update(values)+ added[target] = sorted(values)+ return added+++def pending_tool_envs(manifest: DeploymentManifest) -> dict[str, dict[str, str]]:+ """Managed env vars this manifest is missing, WITHOUT mutating it.++ Split out so a lifecycle command can ask "is there anything to apply?"+ before deciding to re-apply mutations. ``install start`` skips activation+ entirely for a deployment that is already healthy and already has mutations+ recorded -- which is every normally-installed working deployment, i.e.+ exactly the population that needs reconciling. Asking first is what lets it+ re-apply only when something is genuinely missing.++ Targets whose managed env is empty are omitted, so a no-op reconcile does+ not rewrite the manifest and bump ``updated_at`` for no visible reason.+ """++ current = build_tool_envs(manifest.port, manifest.backend, list(manifest.targets))+ pending: dict[str, dict[str, str]] = {}+ for target, values in current.items():+ if not values:+ continue+ stored = manifest.tool_envs.get(target)+ missing = (+ dict(values)+ if not isinstance(stored, dict)+ else {name: value for name, value in values.items() if name not in stored}+ )+ if missing:+ pending[target] = missing+ return pending++def _activate_deployment_mutations(manifest: DeploymentManifest) -> None:+ for target, names in sorted(_reconcile_tool_envs(manifest).items()):+ click.echo(f"Applying newer managed settings for {target}: {', '.join(names)}")manifest.mutations = apply_mutations(manifest)save_manifest(manifest)@@ -842,7 +912,10 @@ def install_start(profile: str) -> None:if not probe_ready(manifest.health_url):_deactivate_deployment_mutations(manifest)_start_deployment(manifest)- if probe_ready(manifest.health_url) and not manifest.mutations:+ # ``not manifest.mutations`` alone skipped activation for every healthy,+ # normally-installed deployment -- which is precisely the population whose+ # stored env is stale. Re-apply when reconciliation has something to add.+ if probe_ready(manifest.health_url) and (not manifest.mutations or pending_tool_envs(manifest)):_activate_deployment_mutations(manifest)click.echo(f"Started deployment '{profile}'.")diff --git a/tests/test_cli/test_install_cli.py b/tests/test_cli/test_install_cli.pyindex 1817312f0..750fb89ee 100644--- a/tests/test_cli/test_install_cli.py+++ b/tests/test_cli/test_install_cli.py@@ -8,6 +8,7 @@ from click.testing import CliRunnerfrom headroom.cli import install as instfrom headroom.cli.main import main+from headroom.install.planner import build_tool_envsdef test_require_manifest_resolves_single_profile_when_default_missing(monkeypatch):@@ -124,6 +125,9 @@ def test_install_apply_starts_service_supervisor(monkeypatch) -> None:calls: list[str] = []class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -177,6 +181,9 @@ def test_install_apply_announces_windows_service_fallback(monkeypatch) -> None:calls: list[str] = []class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-task"runtime_kind = "python"@@ -215,6 +222,9 @@ def test_install_apply_forwards_no_http2_to_build_manifest(monkeypatch) -> None:captured: dict[str, object] = {}class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -254,6 +264,9 @@ def _patch_apply_pipeline(monkeypatch, captured: dict[str, object]):"""Stub out the apply side effects and capture ``build_manifest`` kwargs."""class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -376,6 +389,9 @@ def _apply_capturing_build_manifest(monkeypatch) -> dict[str, object]:captured: dict[str, object] = {}class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -433,6 +449,8 @@ def test_install_status_includes_backend_from_health_probe(monkeypatch) -> None:runner = CliRunner()class Manifest:+ targets = ["claude"]+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -464,6 +482,8 @@ def test_install_status_survives_non_dict_config(monkeypatch) -> None:runner = CliRunner()class Manifest:+ targets = ["claude"]+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -490,6 +510,10 @@ def test_install_restart_uses_internal_helpers(monkeypatch) -> None:calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -541,6 +565,10 @@ def test_install_start_noops_when_already_healthy(monkeypatch) -> None:calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = build_tool_envs(8787, "anthropic", ["claude"])profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -566,6 +594,10 @@ def test_install_start_noops_for_healthy_docker_without_docker_on_path(monkeypatrunner = CliRunner()class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = build_tool_envs(8787, "anthropic", ["claude"])profile = "default"preset = "persistent-docker"runtime_kind = "docker"@@ -589,6 +621,10 @@ def test_install_start_does_not_spawn_when_start_lock_is_contended(monkeypatch)calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -623,6 +659,10 @@ def test_install_start_restarts_wedged_runtime_under_single_lock(monkeypatch) ->calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -688,6 +728,9 @@ def test_install_apply_accepts_opencode_target(monkeypatch) -> None:captured: dict[str, object] = {}class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -739,6 +782,11 @@ def test_install_apply_restores_previous_deployment_after_failed_update(monkeypacalls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}+def __init__(self, profile: str, targets: list[str]) -> None:self.profile = profileself.preset = "persistent-service"@@ -825,6 +873,10 @@ def test_install_start_rejects_task_lifecycle(monkeypatch) -> None:runner = CliRunner()class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-task"runtime_kind = "python"@@ -845,6 +897,9 @@ def test_install_apply_uses_docker_runtime_for_persistent_docker(monkeypatch) ->calls: list[str] = []class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-docker"runtime_kind = "docker"@@ -902,6 +957,9 @@ def test_deploy_prefers_docker_when_available(monkeypatch) -> None:calls: list[str] = []class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-docker"runtime_kind = "docker"@@ -961,6 +1019,9 @@ def test_deploy_prefers_gpu_docker_when_available(monkeypatch) -> None:captured: dict[str, object] = {}class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-docker"runtime_kind = "docker"@@ -1018,6 +1079,9 @@ def test_deploy_falls_back_to_detached_python_without_supervisor(monkeypatch) ->calls: list[str] = []class Manifest:+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-task"runtime_kind = "python"@@ -1070,6 +1134,10 @@ def test_install_remove_continues_when_runtime_teardown_errors(monkeypatch) -> Ncalls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"preset = "persistent-service"runtime_kind = "python"@@ -1107,6 +1175,10 @@ def test_install_agent_ensure_reports_already_healthy(monkeypatch) -> None:runner = CliRunner()class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"@@ -1123,6 +1195,10 @@ def test_install_agent_run_exits_with_foreground_status(monkeypatch) -> None:runner = CliRunner()class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"@@ -1140,6 +1216,10 @@ def test_install_agent_ensure_no_spawn_when_lock_not_acquired(monkeypatch) -> Nocalls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"@@ -1174,6 +1254,10 @@ def test_install_agent_ensure_stops_wedged_runtime_before_restart(monkeypatch) -calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"preset = "persistent-task"@@ -1236,6 +1320,10 @@ def test_install_agent_ensure_starts_when_stopped_and_lock_acquired(monkeypatch)calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"preset = "persistent-task"@@ -1279,6 +1367,10 @@ def test_install_agent_ensure_no_duplicate_spawn_after_lock_recheck(monkeypatch)calls: list[str] = []class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"@@ -1317,6 +1409,10 @@ def test_install_agent_ensure_propagates_start_deployment_failure(monkeypatch) -runner = CliRunner()class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs = {}profile = "default"health_url = "http://127.0.0.1:8787/readyz"preset = "persistent-task"@@ -1344,3 +1440,85 @@ def test_install_agent_ensure_propagates_start_deployment_failure(monkeypatch) -result = runner.invoke(main, ["install", "agent", "ensure"])assert result.exit_code != 0, f"expected non-zero exit, got {result.exit_code}: {result.output}"assert "simulated start failure" in result.output+++def test_install_start_reconciles_a_healthy_deployment(monkeypatch) -> None:+ """The regression this whole change exists for.++ ``install start`` activated mutations only when the deployment had NONE+ recorded. A normally-installed, working deployment always has some, so the+ reconcile never ran on the one command the affected users actually type --+ and the stale env var stayed stale forever.+ """+ runner = CliRunner()+ applied: list[str] = []++ class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ # Pre-#746: base URL written, tool search never enabled.+ tool_envs = {"claude": {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"}}+ profile = "default"+ preset = "persistent-service"+ runtime_kind = "python"+ supervisor_kind = "service"+ scope = "user"+ health_url = "http://127.0.0.1:8787/readyz"+ mutations = [object()] # healthy AND already mutated: the skipped case+ artifacts = []++ manifest = Manifest()+ monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: manifest)+ monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: True)+ monkeypatch.setattr(+ "headroom.cli.install.apply_mutations", lambda m: applied.append("apply") or []+ )+ monkeypatch.setattr("headroom.cli.install.save_manifest", lambda m: None)+ monkeypatch.setattr("headroom.cli.install.start_supervisor", lambda m: None)+ monkeypatch.setattr("headroom.cli.install.wait_ready", lambda m, timeout_seconds=None: True)++ result = runner.invoke(main, ["install", "start"])++ assert result.exit_code == 0, result.output+ assert "ENABLE_TOOL_SEARCH" in manifest.tool_envs["claude"]+ assert applied == ["apply"] # re-applied so the new key reaches the config+++def test_install_start_still_skips_when_nothing_is_pending(monkeypatch) -> None:+ """A deployment that is already current must not be perturbed."""+ runner = CliRunner()+ applied: list[str] = []++ class Manifest:+ targets = ["claude"]+ port = 8787+ backend = "anthropic"+ tool_envs: dict = {}+ profile = "default"+ preset = "persistent-service"+ runtime_kind = "python"+ supervisor_kind = "service"+ scope = "user"+ health_url = "http://127.0.0.1:8787/readyz"+ mutations = [object()]+ artifacts = []++ manifest = Manifest()+ from headroom.cli.install import _reconcile_tool_envs++ _reconcile_tool_envs(manifest) # bring it fully up to date first++ monkeypatch.setattr("headroom.cli.install.load_manifest", lambda profile: manifest)+ monkeypatch.setattr("headroom.cli.install.probe_ready", lambda url: True)+ monkeypatch.setattr(+ "headroom.cli.install.apply_mutations", lambda m: applied.append("apply") or []+ )+ monkeypatch.setattr("headroom.cli.install.save_manifest", lambda m: None)+ monkeypatch.setattr("headroom.cli.install.start_supervisor", lambda m: None)+ monkeypatch.setattr("headroom.cli.install.wait_ready", lambda m, timeout_seconds=None: True)++ result = runner.invoke(main, ["install", "start"])++ assert result.exit_code == 0, result.output+ assert applied == []diff --git a/tests/test_install_tool_env_reconcile.py b/tests/test_install_tool_env_reconcile.pynew file mode 100644index 000000000..6928114bd--- /dev/null+++ b/tests/test_install_tool_env_reconcile.py@@ -0,0 +1,163 @@+"""A deployment must pick up managed env vars added after it was installed.++``tool_envs`` is computed once, by ``build_manifest`` during ``headroom+install``, and stored on disk. Every lifecycle command after that re-applies the+STORED map, so anything added to a provider's install env later never reaches an+existing deployment -- not on ``start``, not on ``restart``, not on an upgrade.++The case that motivated this: ``ENABLE_TOOL_SEARCH`` joined Claude's install env+on 2026-06-19 (GH #746), because pointing Claude Code at a custom+``ANTHROPIC_BASE_URL`` makes it stop deferring MCP tool schemas and inline all of+them. A deployment installed before that date keeps getting the base URL written+without the mitigation -- the expensive half of the change, indefinitely.+"""++from __future__ import annotations++from headroom.cli.install import _reconcile_tool_envs, pending_tool_envs+from headroom.install.models import DeploymentManifest+from headroom.providers.claude import TOOL_SEARCH_DEFAULT, TOOL_SEARCH_ENV++CLAUDE = "claude"+++def _manifest(tool_envs: dict[str, dict[str, str]]) -> DeploymentManifest:+ return DeploymentManifest(+ profile="default",+ preset="local",+ runtime_kind="native",+ supervisor_kind="none",+ scope="provider",+ provider_mode="claude",+ targets=[CLAUDE],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ tool_envs=tool_envs,+ )+++def test_pre_746_manifest_gains_the_tool_search_var() -> None:+ """The regression this exists for: base URL set, deferral never enabled."""+ manifest = _manifest({CLAUDE: {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"}})++ added = _reconcile_tool_envs(manifest)++ assert TOOL_SEARCH_ENV in manifest.tool_envs[CLAUDE]+ assert manifest.tool_envs[CLAUDE][TOOL_SEARCH_ENV] == TOOL_SEARCH_DEFAULT+ assert added == {CLAUDE: [TOOL_SEARCH_ENV]}+++def test_existing_values_are_never_overwritten() -> None:+ """A stored value may be deliberate; healing an omission is the smaller claim."""+ manifest = _manifest(+ {+ CLAUDE: {+ "ANTHROPIC_BASE_URL": "http://127.0.0.1:9999",+ TOOL_SEARCH_ENV: "false",+ }+ }+ )++ added = _reconcile_tool_envs(manifest)++ assert manifest.tool_envs[CLAUDE]["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9999"+ assert manifest.tool_envs[CLAUDE][TOOL_SEARCH_ENV] == "false"+ assert added == {}+++def test_current_manifest_is_unchanged() -> None:+ """No churn, and nothing printed, for a deployment that is already correct."""+ manifest = _manifest({})+ _reconcile_tool_envs(manifest)+ current = {k: dict(v) for k, v in manifest.tool_envs.items()}++ manifest2 = _manifest(current)+ added = _reconcile_tool_envs(manifest2)++ assert added == {}+ assert manifest2.tool_envs == current+++def test_reconcile_is_idempotent() -> None:+ manifest = _manifest({CLAUDE: {"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787"}})++ first = _reconcile_tool_envs(manifest)+ second = _reconcile_tool_envs(manifest)++ assert first == {CLAUDE: [TOOL_SEARCH_ENV]}+ assert second == {}+++def test_a_target_absent_from_the_manifest_is_populated() -> None:+ """An older manifest may predate the target entirely, not just one key."""+ manifest = _manifest({})++ added = _reconcile_tool_envs(manifest)++ assert CLAUDE in manifest.tool_envs+ assert TOOL_SEARCH_ENV in manifest.tool_envs[CLAUDE]+ assert added.get(CLAUDE)+++def test_untargeted_tools_are_left_alone() -> None:+ """Reconciliation only covers targets this deployment actually manages."""+ manifest = _manifest({"someone-elses-tool": {"CUSTOM": "1"}})++ _reconcile_tool_envs(manifest)++ assert manifest.tool_envs["someone-elses-tool"] == {"CUSTOM": "1"}+++def test_the_rebuilt_base_url_uses_the_manifest_port() -> None:+ """Rebuilding must not silently re-point a deployment at a default port."""+ manifest = _manifest({})+ manifest.port = 9123++ _reconcile_tool_envs(manifest)++ assert "9123" in manifest.tool_envs[CLAUDE]["ANTHROPIC_BASE_URL"]+++def test_a_non_dict_entry_does_not_crash_a_lifecycle_command() -> None:+ """A hand-edited manifest must not turn ``install restart`` into a traceback.++ ``load_manifest`` does not type-check ``tool_envs``, so a string here+ reached ``stored.update(...)`` and raised AttributeError from a path with+ no handler.+ """+ manifest = _manifest({CLAUDE: "http://127.0.0.1:8787"}) # type: ignore[dict-item]++ added = _reconcile_tool_envs(manifest)++ assert isinstance(manifest.tool_envs[CLAUDE], dict)+ assert TOOL_SEARCH_ENV in manifest.tool_envs[CLAUDE]+ assert added.get(CLAUDE)+++def test_a_target_with_no_managed_env_is_not_written() -> None:+ """No silent manifest churn: a no-op reconcile must not rewrite the file."""+ manifest = _manifest({})+ manifest.targets = [CLAUDE, "opencode"]++ _reconcile_tool_envs(manifest)++ assert "opencode" not in manifest.tool_envs+++def test_pending_does_not_mutate() -> None:+ """The lifecycle commands ask before deciding; asking must be free."""+ manifest = _manifest({})+ before = {k: dict(v) for k, v in manifest.tool_envs.items()}++ pending = pending_tool_envs(manifest)++ assert pending # there IS something to do+ assert manifest.tool_envs == before # ...but nothing was done+++def test_pending_is_empty_once_reconciled() -> None:+ manifest = _manifest({})+ _reconcile_tool_envs(manifest)++ assert pending_tool_envs(manifest) == {}