Repository navigation
fix: refresh app agents before the boot builds the mcp overlay - #32133
bolichen97 wants to merge 1 commit into
Conversation
An app agent that lists a host-managed server in its tools gets that server's launch spec, which names the running launcher, copied in when it is materialized. The boot built the MCP overlay before the dashboard re-materialized app agents, so the first start after an upgrade routed them through the previous launcher until a second restart. When a server is routed, the boot now re-materializes every enabled app's agents first, on dashboard and --no-dashboard boots alike.
UX Review (Opus 5.5) — ⏭️ skippedRevision |
|
Superseded: main already resets the kirocrew-* launchers when it builds the overlay (#13155); verified with a targeted repro on main |
Pull request was closed
Problem / Motivation
Goal: On the first gateway start after an upgrade, agents declared by an app reach their control-plane MCP tools through stubs that name the running launcher, not the previous one.
An app agent that lists a host-managed server (
@kirocrew-core,@kirocrew-cron) in itstoolsgets that server's launch spec copied into its materialized spec, and the spec names the running launcher. When a server is routed, the boot builds the MCP overlay from~/.kiro/agentsbefore the dashboard re-materializes app agents. So after an upgrade the overlay stubs for those agents keep the previous version's launcher, and their sessions getidentity_unattestedon the firstwork_*/session_*call until the operator toggles Share MCP Backends or restarts a second time. Under--no-dashboardthe boot never re-materializes app agents at all.Why it matters
Every operator who routes a server and runs an app that declares agents hits this on each upgrade: the app's agents lose their control-plane tools on the first start, and nothing on screen points at the cause.
Not a goal
What changed (motivation → approach → change)
Symptom and cause. The overlay pass reads the agent specs on disk, and app agent specs get the current launcher only later, from the dashboard's app reconcile. A second overlay pass after that reconcile cannot help: an overlay refresh refuses a routed target the running daemon does not hold, and a moved launcher is exactly that.
Change. When
mcp_gateway.stub_serversis non-empty, the boot now re-materializes every enabled app's agent specs, and nothing else, right before the overlay pass ingateway_runtime/service_boot.py, on dashboard and--no-dashboardboots alike. The newrefresh_enabled_app_agentsinapps/bridges_register.pyruns the agent half ofregister_appfor each enabled app: the same source (a shipped builtin's manifest is read from the package, which matters because the data-home copy is still the previous version's at this point after an upgrade), the same admission gate, and the same field-wise refresh. One app's failure is logged and the others still refresh; a failure of the whole step keeps the old specs and the boot goes on. The app-kit platform spec (§7) records the order.Boot cost. The step runs off the event loop (
asyncio.to_thread) and only when a server is routed, which is off by default, so a default boot does no new work. It cannot be deferred: the overlay and the daemon's routing are fixed when the broker starts, and a spec written after that waits for a restart. Its worst case is one small JSON read, render and write per declared agent of each enabled app, which scales with installed apps, not with sessions or history, and repeats writes the dashboard's reconcile already makes later in the same boot.Backwards compatibility
Compatible: the step writes the same app agent specs the dashboard's reconcile already writes later in the same boot, only earlier; no spec, config key or API changes shape.
Removes nothing: no file, key or capability is deleted or narrowed; app agent specs are rewritten from their templates as before.
Tests
test/test_app_agents_refresh_before_mcp_overlay.pyruns the boot with an enabled app whose materialized agent spec names an old launcher. With a routed server, the overlay pass sees the current launcher; with nothing routed, the spec is left alone, so the default boot gains no work.test/test_slack_gateway_overload_wiring.pygives its bare orchestrator the routed-server listrunnow reads.Proof: PROVEN test/test_app_agents_refresh_before_mcp_overlay.py::test_boot_refreshes_app_agents_before_the_overlay_pass[stub_servers0-expected0] (head 2b77131)
Determinism: the new test passed 20 runs at
-n0, 10 runs at-n 4 --dist loadgroup --max-worker-restart=2besidetest/test_slack_gateway_overload_wiring.pyandtest/test_app_bridges_agent_configs.py, and a shuffled order of those three files (seed 18489, 88 node ids).Manual verification
N/A — unit coverage sufficient: the test drives the real boot sequence up to the overlay pass with a real installed app, and the overlay builder itself is unchanged.
Screenshots / video
N/A — no frontend change.
Related Issues
Closes #14059
Sibling sweep
Swept: git grep -nE "refresh_forks=|_materialize_managed_refs|reconcile_enabled_app_resources" -- src/kiro_crew/
Sibling: src/kiro_crew/agent_parts/spec_rebuild.py -- not affected -- the host agent spec is rebuilt in _init_services, before the overlay pass
Sibling: src/kiro_crew/dashboard/server_runtime/app_platform.py -- not affected -- the full reconcile still runs here and rewrites the same specs after the overlay
Pattern harvest
Not generalizable: the one boot-ordered writer of app agent specs ran after the one reader that freezes them; the order is now pinned by a boot test rather than a rule.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.