mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(install): apply managed env vars added after a deployment was installed (#3740)
## The bug
`tool_envs` is computed **once**, by `build_manifest` during `headroom
install`, and then stored in the deployment manifest. Every lifecycle
command afterwards re-applies the **stored** map:
```
install start → _require_manifest(profile) → _activate_deployment_mutations(manifest)
→ apply_mutations(manifest) → manifest.tool_envs
```
`build_tool_envs()` is never called again. So any variable added to a
provider's install env later reaches **new installs only** — never an
existing deployment, 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.
## Why it matters
`ENABLE_TOOL_SEARCH` joined Claude's install env on **2026-06-19**
(#995, GH #746) because pointing Claude Code at a custom
`ANTHROPIC_BASE_URL` makes it **stop deferring MCP tool schemas and
inline every one of them**.
A deployment installed before that date has kept getting the base URL
written *without* the mitigation ever since — the client is pointed at
the proxy **and** has its own tool-schema deferral switched off. That's
the expensive half of the change with none of the benefit, indefinitely.
Measured live against the API on a 15-builtin + 40-MCP-tool surface:
| | input_tokens |
|---|---|
| tool schemas inlined (deferral off) | **16,246** |
| deferral active | **718** |
Paid on every turn, silently, because the manifest is authoritative and
was written before the fix existed.
## The fix
`_reconcile_tool_envs()` rebuilds the expected env from the manifest's
own `port`, `backend` and `targets`, and adds any keys the stored map is
missing. It runs inside `_activate_deployment_mutations()` — the single
choke point every path already goes through (`start`, `restart`,
`_restore_deployment`) — so managed env becomes **self-healing across
upgrades** instead of frozen at install time. Each addition is reported
to the user.
**Missing keys are added; existing values are never overwritten.** A
stored value may legitimately differ from a fresh build — a hand-edited
port, a deployment pinned deliberately — and healing an omission is a
much smaller claim than re-deciding a setting the manifest already
records.
Rebuilding from `manifest.port` also means a deployment on a non-default
port cannot be re-pointed at 8787 by reconciliation. There's a test for
that specifically.
## Testing
7 new tests in `tests/test_install_tool_env_reconcile.py`, including the
pre-#746 manifest case, idempotency, and the non-default-port guard. 199
pass across the install suites.
## Note
This is the class of bug where the code was correct for three months and
every existing deployment kept the old behaviour anyway. Worth assuming
any future addition to a provider's install env had the same fate until
now.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
### Update after self-review
The reconcile **never ran on the command this PR is about**. `install
start` had:
```python
if probe_ready(manifest.health_url) and not manifest.mutations:
```
Every normally-installed working deployment *has* mutations recorded, so
activation was skipped for exactly the population whose stored env is
stale — the commit message's "not on `start`" was still true after the
patch claiming to fix it.
Added `pending_tool_envs()`, which answers "is anything missing?"
without mutating, so start re-applies when — and only when — there is
something to apply. The new test **fails against the old condition and
passes against the new one** (checked, not assumed). A deployment
already current is still left completely alone.
Also fixed: a `tool_envs` entry that is present but not a dict
(hand-edited manifest; `load_manifest` does not type-check it) raised
`AttributeError` out of a lifecycle command; and a target with no
managed env no longer gets an empty dict written, which rewrote the
manifest and bumped `updated_at` for nothing.
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
26a2c4939c
commit
a4cb2bc021
+75
-2
@@ -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_envs
|
||||
from headroom.install.providers import apply_mutations, revert_mutations
|
||||
from 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}'.")
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@ from click.testing import CliRunner
|
||||
|
||||
from headroom.cli import install as inst
|
||||
from headroom.cli.main import main
|
||||
from headroom.install.planner import build_tool_envs
|
||||
|
||||
|
||||
def 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(monkeypat
|
||||
runner = 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(monkeypa
|
||||
calls: list[str] = []
|
||||
|
||||
class Manifest:
|
||||
targets = ["claude"]
|
||||
port = 8787
|
||||
backend = "anthropic"
|
||||
tool_envs = {}
|
||||
|
||||
def __init__(self, profile: str, targets: list[str]) -> None:
|
||||
self.profile = profile
|
||||
self.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) -> N
|
||||
calls: 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) -> No
|
||||
calls: 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 == []
|
||||
|
||||
@@ -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) == {}
|
||||
Reference in New Issue
Block a user