Skip to content

fix(apps): keep agent configs through a local-source app update - #34578

Merged
bolichen97 merged 1 commit into
mainfrom
fix/32258-local-update-keeps-agents
Nov 10, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/32258-local-update-keeps-agents

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Updating an app from a local folder keeps the user's edits in its agent configs, even when the gateway cannot write a config back.

POST /api/apps/{name}/update with a local source deleted the app's agent configs (<agents dir>/<app>--<agent>.json) before it copied the new version in, then wrote them back from a snapshot. When that write failed (a full disk) or registration declined it (a data home that does not own a shared agents directory), the config was gone, and the user's edits in it (model, description, ...) with it. The next boot recreated the template default.

Why it matters

Anyone who develops an app locally, or installed one from a folder, updates it this way. The loss is silent: nothing says the agent's model or description went back to the template. #32213 fixed the same order on the registry update; the local branch still had it.

Not a goal

What changed (motivation → approach → change)

A local update leaves the agent configs on disk while it swaps the app's files, the way a registry update already does. The configs hold the user's edits, so a config the gateway cannot rewrite keeps its last good copy instead of disappearing.

The old order was the root cause: the take-down ran a full deregister_app, which deletes the configs, and the edits survived only if the re-registration managed to write the snapshot back. The registry branch avoids this with deregister_app(name, keep_agents=True): registration rewrites each config in place and reads the edits from the file itself.

handle_update_app (routes_install.py) takes the local branch down with keep_agents=True too. After a successful copy it prunes the configs of agents the new version dropped, then registers as before. An app the update leaves unable to run (a new sessionApproval, or a disabled app) loses every config, as on the registry branch. A failed copy restores the old tree and record together, so the restore re-registers over the kept configs.

Local update Before After
Config rewrite fails or is declined config deleted, edits lost config kept as it was
New version drops an agent its config deleted its config pruned
New version asks for sessionApproval no config no config

In routes_lifecycle.py the prune moves out of _reinstall_from_registry into a shared _prune_dropped_resources, and the route-layer snapshot plumbing goes: _snapshot_agent_configs_off_loop, the prior_agent_configs parameter of _register_app_off_loop and _restore_app_after_failed_update, and the facade's snapshot_app_agent_configs import. The routes facade, two comments in bridges_register.py and the app-kit-platform spec (§3) say that every update keeps the agent configs.

Backwards compatibility

Compatible: the update route keeps its request body, status codes and response fields, and an update that rewrites every config writes the same files as before.

Reader: src/kiro_crew/apps/routes_install.py:handle_update_app -- app -- the only caller of _snapshot_agent_configs_off_loop and of the two removed prior_agent_configs parameters; test_an_update_keeps_an_agent_file_it_cannot_rewrite
Reader: src/kiro_crew/apps/routes.py:_snapshot_agent_configs_off_loop -- app -- facade names removed with their last route-layer user (snapshot_app_agent_configs stays importable from kiro_crew.apps.bridges, where its tests import it); test_routes_facade.py
Reader: src/kiro_crew/apps/routes_lifecycle.py:_reinstall_from_registry -- app -- calls _restore_app_after_failed_update(name) and the shared prune; test_an_agent_the_new_version_drops_does_not_come_back

Tests

  • test_an_update_keeps_an_agent_file_it_cannot_rewrite (was test_a_registry_update_...) covers the local branch: a declined or failed (disk full) rewrite leaves the user's config byte for byte, on both branches of the update route and both registry install routes.
  • test_an_update_that_needs_consent_leaves_no_agent_file (was test_a_registry_update_...) covers the local branch: an update that newly asks for sessionApproval leaves no agent config.
  • test_local_update_failure_leaves_a_disabled_app_unregistered pins the kept-configs take-down, with nothing registered or started.
  • The local-branch stubs of deregister_app in test_apps_routes_coverage_update_uninstall.py take the keep_agents keyword.
  • test_an_agent_the_new_version_drops_does_not_come_back[False] pins the local prune.

Proof: PROVEN test/test_apps_routes_coverage_update_uninstall.py::TestUpdateApp::test_local_update_failure_leaves_a_disabled_app_unregistered (head 2f63413)

Determinism: the three changed tests (every parameter) passed 20 runs at -n0 and 10 runs at -n 4 beside test_app_routes.py and test_apps_routes_coverage_registry_install.py, and both changed files (75 tests) passed in 3 shuffled orders (seeds 32258, 7, 11).

Manual verification

N/A — unit coverage sufficient: the route tests drive the real update route, update_app and registration over a temporary data home, and the disk-full and declined cases are the issue's two failure causes.

Screenshots / video

N/A — no frontend change.

Related Issues

Closes #32258

Sibling sweep

Swept: git grep -nE "deregister_app(|_deregister_app_off_loop(" -- src/
Sibling: src/kiro_crew/apps/routes_lifecycle.py -- not affected -- the registry take-down already keeps the configs (#32213); its prune is the shared helper
Sibling: src/kiro_crew/apps/bridges_register.py -- not affected -- a policy-denied registration scrubs the app's resources on purpose and writes nothing back
Sibling: src/kiro_crew/apps/routes_enable.py -- not affected -- the enable rollback disables the app, so no re-registration follows
Sibling: src/kiro_crew/apps/routes_uninstall.py -- not affected -- uninstall removes the app, so no re-registration follows
Sibling: src/kiro_crew/cli_commands_app.py -- not affected -- the CLI update goes through this route; its disable and uninstall remove the app's resources on purpose
Sibling: src/kiro_crew/apps/backend_runtime/registration.py -- not affected -- it drops a disabled app's resources and never re-registers

Pattern harvest

Not generalizable: the delete-then-rewrite order lived in one route's two branches; #32213 fixed the registry one and this fixes the other.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

A local-source update deleted the app's agent configs before it copied
the new version in, then wrote them back from a snapshot. When that
write failed (a full disk) or was declined (a data home that does not
own a shared agents directory), the user's edits in them were gone.

The local-source branch now takes the app down the way the registry
branch does: it keeps the agent configs, registration rewrites each in
place, and the configs of agents the new version dropped are pruned. An
app the update leaves unable to run still loses them all. The snapshot
plumbing the route layer no longer passes is removed.
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 10, 2026 14:59
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 2f63413df080e5c593e99b224c5c7451b6f085da touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2f63413df080e5c593e99b224c5c7451b6f085da — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

The fix is at cause level: the delete-then-rewrite order is gone and the registry branch's existing keep_agents=True mechanism is reused. The only gap is surface this PR leaves with zero callers, and the description defers it openly.

Notes

  • Item 4 — oversized (deferred): once this lands, snapshot_app_agent_configs (bridges_agents.py:655) and register_app's prior_agent_configs (bridges_register.py:178) have 0 callers under src/ (grepped snapshot_app_agent_configs|prior_agent_configs; only the definitions and the bridges.py:85 re-export remain). The PR adds no new code to that surface, but it keeps a concept the spec now has to explain ("No route passes register_app's prior_agent_configs"). Subtraction: delete both, plus the spec sentence describing them, when fix(apps): bring untouched agent spec values up to the new app version #32910 lands.

What this change ships

Inventory (6 items) — 5 justified

Intent: updating an app from a local folder no longer silently throws away the user's agent edits (model, description). This is a FIX for #32258.

  1. A local-source update leaves agent configs on disk during the file swap, so a failed or declined rewrite keeps the user's copy — justified
  2. A local update removes the configs of agents the new version dropped — justified
  3. A local update that leaves the app unable to run (new sessionApproval, disabled) removes every kept config — justified
  4. Route-layer snapshot plumbing removed (_snapshot_agent_configs_off_loop, prior_agent_configs params) — oversized (bridges-layer leftovers deferred to fix(apps): bring untouched agent spec values up to the new app version #32910)
  5. Prune step pulled out into the shared _prune_dropped_resources (2 callers: routes_install.py, routes_lifecycle.py) — justified
  6. Spec §3, module table and docstrings now say every update keeps agent configs — justified

[FIRST-PRINCIPLES-REVIEWED] 2f63413

Description read

[DESCRIPTION-READ] 6bd6f0a630bba082f967312bc29d25b172ddcf47bd11695bb2ab857f9783387b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2f63413df080e5c593e99b224c5c7451b6f085da — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the local branch now follows the same keep-then-prune order as the registry branch (#32213), and nothing in the tree still reads the removed snapshot plumbing.

Notes

[DESIGN-REVIEWED] 2f63413

Description read

[DESCRIPTION-READ] 85034579a39b577dc2f6fc163b1ece617e8896c14339acea60ccab327c2860ab

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2f63413df080e5c593e99b224c5c7451b6f085da and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2f63413

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2f63413df080e5c593e99b224c5c7451b6f085da false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2f63413df080e5c593e99b224c5c7451b6f085da — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2f63413

Verdict parsed from the review's SHA-scoped output markers for commit 2f63413df080e5c593e99b224c5c7451b6f085da.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2f63413df080e5c593e99b224c5c7451b6f085da false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 enabled auto-merge (squash) November 10, 2026 15:18

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve on 2f63413. The local-source update now keeps agent configs on disk through the take-down (keep_agents=True), prunes only agents the new version dropped and fully deregisters only an app that may no longer run, matching the registry branch (#32213). A failed or declined config rewrite keeps the user's edited config. No data loss found, and no specific app is hard-coded in core. Decisive lines: src/kiro_crew/apps/routes_install.py:289, src/kiro_crew/apps/routes_install.py:320-324, src/kiro_crew/apps/routes_lifecycle.py:288-306, src/kiro_crew/apps/bridges_agents.py:1044

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 10, 2026
@bolichen97
bolichen97 merged commit 6cc4e97 into main Nov 10, 2026
98 checks passed
@bolichen97
bolichen97 deleted the fix/32258-local-update-keeps-agents branch November 10, 2026 16:29
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

App update: a local-source update deletes agent configs before it can rewrite them

2 participants