Skip to content

fix(agents): let an installed agent become the default agent (release/0.8.0) - #16385

Merged
bolichen97 merged 2 commits into
release/0.8.0from
backport/0.8.0-p0-runtime-agents
Oct 3, 2026
Merged

bolichen97 merged 2 commits into
release/0.8.0from
backport/0.8.0-p0-runtime-agents

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: on release/0.8.0, a crewmate bound to an installed agent's file name runs, and an installed agent can become the default, without the healer that comes with that change overwriting a default the owner chose.

Both defects are present at the release/0.8.0 tip:

  • File-name binding. A package installs <Package>-<agent>.json declaring "name": "<agent>", and kiro-cli lists agents by declared name only. A crewmate whose kiro_agent recorded the file name fails closed on every turn with "Agent mode ... is not available".
  • Set as default. The picker's "Set as default" on an installed-template row always fails with 400 default_agent_not_alias.

Why it matters

The first defect fails every turn for the crewmates it hits. The second makes a visible picker action fail every time.

Not a goal

What changed (motivation → approach → change)

Backport of #12686, #16323, #16410, #16455 and #16512 to release/0.8.0, in main's merge order, as two commits (the PR Hygiene cap). Each commit is grouped by author and carries every source's -x line.

  1. fix(catalog): restore companion runtime_policy on member rows (fix(catalog): restore companion runtime_policy on member rows #12686), a clean pick whose patch-id matches the source. It is fix(agents): let an installed agent become the default agent #16323's prerequisite: an optional ProviderRegistry.agent_runtime_policy seam, emitted on owner-visible member rows. The public edition returns None, so its rows are unchanged.
  2. fix(agents): let an installed agent become the default agent #16323, fix(agents): reset a default agent only when its template was removed #16410, fix(agents): harden the default-agent healer and the file-name map #16455 and fix(agents): heal a default agent only after a scan that read every spec #16512, squashed:
    • fix(agents): let an installed agent become the default agent #16323.
      • The materialized-agent refresh records filename stem -> declared name, and member resolution dispatches the declared name. The crewmate's row is not edited.
      • PUT /api/config/default-agent enrolls a user-level installed template as an alias in the same locked write that sets the default. Lineage is read strictly, a template an alias already runs makes that alias the default, and the enrollment is SEL-logged.
      • It also adds a healer that points a default whose template file is gone back at default.
    • fix(agents): reset a default agent only when its template was removed #16410. Review of this PR's first revision found two defects in that healer, and both were fixed on main first.
      • The healer decided "gone" from absence in ~/.kiro/agents alone. A project checkout's own spec and an edition-contributed agent both dispatch without a file there, so their defaults were reset at every boot and refresh. It now acts only on a name a landed snapshot in this process declared and the current one does not, and never on a name the edition supplies.
      • The catalog fetch ran the healer's config.json write for any caller. It now heals only on the owner's own fetch.
    • fix(agents): harden the default-agent healer and the file-name map #16455 (merged on main as 4a11ed2, a clean pick whose patch-id matches), from review of this PR:
      • Healing is opt-in: refresh_materialized_agents defaults to heal_default=False, and only the owner's catalog fetch passes True.
      • dispatch_kiro_agent never stem-maps a name the edition contributes.
      • _MATERIALIZED_SEEN and _MATERIALIZED_STEMS are bounded where they are kept (4096 entries, 256 characters per name). The oldest stale removals are evicted first, and one aggregate warning is written only when the drop count changes.
      • The agent_runtime_policy docstring and its spec row name the key as the dispatched agent.
    • fix(agents): heal a default agent only after a scan that read every spec #16512 (merged on main as 4576a29; its added and removed lines match the source exactly), from review of this PR:
      • The scan records whether it read every spec, and that flag is published with the installed snapshot under the snapshot lock.
      • The healer acts only on a complete installed snapshot, and re-reads it inside the locked config write.
      • So a torn or briefly unreadable spec, or a partial scan that another refresh installed in between, is never taken as evidence of a removal.
    • Adaptation: test/integration/conftest.py conflicted on context only, both times, because main has an unrelated updates-loop entry beside these lines. Only these changes' _MATERIALIZED_* lines were applied. For every other file, the added and removed lines are identical to the sources'.

Backwards compatibility

  • Compatible. A crewmate that already names a declared agent resolves as before.
  • The alias table changes only when the owner chooses "Set as default" on an installed template.
  • The healer only ever repoints default_agent on the owner's own catalog fetch, after a template a running gateway saw is removed. App disable and template delete record the removal, and the owner's next picker open heals it.

Tests

Regression proof on this branch: each pick's source files are reverted to their state before it, and the tests are kept.

#16323 has little bake time on main, so the suite run here is wide. It covers every test file referencing the changed modules: agent handlers and catalog, config loader, session agent selection, execution context, admission gate, default-agent, the materialized snapshot and the healer (252 files). It also covers all of test/integration. Result: 17776 passed, 36 skipped. The failures (2 to 5 per run) are in test_acp_runtime.py and test_subagent_shared_scratch.py. They fail the same way under xdist on the untouched release/0.8.0 tip, pass in isolation, and neither file is touched here.

Gates:

  • The baselined black and subprocess-encoding gates, isort and flake8 pass. mypy on src/kiro_crew reports no issues (1863 files).
  • The comment-history gate (base origin/release/0.8.0) and docs-lint pass.
  • The agent-SDK boundary gate reports only the session_agent_selection.py offender that is already present at the release/0.8.0 tip, and no new edge on added lines.

Manual verification

N/A. The tests drive the real default-agent route, the real catalog route, and the real loader over real agent files and config.json.

Related Issues

Backport of #12686, #16323, #16410, #16455 and #16512 (#16409).

Pattern harvest

Not generalizable: these are backports, and each source PR carries its own harvest.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@bolichen97
bolichen97 requested a review from a team as a code owner October 3, 2026 06:11
@bolichen97
bolichen97 requested review from CrysisDeu and removed request for a team October 3, 2026 06:11
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 3, 2026
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 5452868816aee33d013ac40ebc5868162ea0e892 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the fidelity claim: the picks' patch-ids match main's sources (#12686, 4a11ed2, 4576a29) — every shape judgment here inherits from main's review.

Not justified as shipped

  • Item 5 — rides along: not either reported defect; declared ("It also adds a healer…"), scoped by the frozen Goal line, and it removes the dangling default that item 2's enrollment can newly create (uninstall leaves default_agent naming a template no chat can open).
  • Item 7 — rides along: a prerequisite pick ("It is fix(agents): let an installed agent become the default agent #16323's prerequisite") restoring the documented companion seam; the public edition's agent_runtime_policy returns None, so public rows are byte-identical.

What this change ships

Inventory (10 items) — 8 justified

Intent: On release/0.8.0, let a crewmate bound to an installed agent's file name run, and let the picker's "Set as default" work on an installed template — a FIX (backport of five main-merged PRs).

  1. A crewmate whose row recorded the agent's file name now runs the declared agent on every path (chat, default, subagent resume/inherit, role effort) — justified
  2. "Set as default" on an installed user-level template now enrolls it as an alias and sets the default in one locked write, instead of failing 400 — justified
  3. A template an alias already runs makes that alias the default; several candidates get a 409 naming them — justified
  4. An app-installed template is refused as default: disabling the app would strand it — justified
  5. The owner's picker fetch now resets a default whose template file is gone back to default (config write, warning, SEL event) — rides along
  6. Races on the PUT (spec deleted, alias rebound, same-name alias created in the window) answer 409 instead of writing a wrong default — justified
  7. Owner-visible member rows carry companion runtime_policy metadata again; public-edition rows unchanged — rides along
  8. Enrollment is audited as agent.create; the reset as a default_agent_reset SEL event — justified
  9. The user-writable agents directory's retained names are bounded (4096 entries, 256 chars) with one aggregate warning per change — justified
  10. A scan that could not read every spec never heals: a torn or unreadable file is not evidence of a removal — justified

[FIRST-PRINCIPLES-REVIEWED] 5452868

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 5452868816aee33d013ac40ebc5868162ea0e892 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5452868

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5452868816aee33d013ac40ebc5868162ea0e892: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 5452868816aee33d013ac40ebc5868162ea0e892 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the squashed commit's loader/handler hunks against main's post-#16512 state — patch-id covers only the two clean picks, the rest is author-asserted.

Suggestions

  • agent_catalog.py and execution_context.py at HEAD are byte-identical to main's tip, corroborating fidelity for those files; a one-line git diff origin/main -- <file> note per backported file in the description would make future backport reviews mechanical.

[DESIGN-REVIEWED] 5452868

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 5452868816aee33d013ac40ebc5868162ea0e892 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5452868

Verdict parsed from the review's SHA-scoped output markers for commit 5452868816aee33d013ac40ebc5868162ea0e892.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5452868816aee33d013ac40ebc5868162ea0e892: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 3, 2026
@bolichen97 bolichen97 changed the title fix(agents): initialize cold-start budget and installed agents as default/dispatch (release/0.8.0) fix(agents): let an installed agent become the default agent (release/0.8.0) Oct 3, 2026
@bolichen97
bolichen97 force-pushed the backport/0.8.0-p0-runtime-agents branch from 3a91c2a to d194276 Compare October 3, 2026 08:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 3, 2026
@bolichen97
bolichen97 force-pushed the backport/0.8.0-p0-runtime-agents branch from d194276 to 70752bc Compare October 3, 2026 09:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 3, 2026
@bolichen97
bolichen97 force-pushed the backport/0.8.0-p0-runtime-agents branch from 70752bc to b91911b Compare October 3, 2026 11:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 3, 2026
Premshay and others added 2 commits October 3, 2026 14:37
Co-authored-by: Premshay <28099628+Premshay@users.noreply.github.com>
(cherry picked from commit fa1b47d)
…/0.8.0)

Backport of #16323, #16410, #16455, #16512 to release/0.8.0, cherry-picked in main's merge order.

* fix(agents): let an installed agent become the default agent (#16323)
  (cherry picked from commit 5c6268a)
  Backport adaptation: test/integration/conftest.py conflicted only on context; the
  source's added reset lines (config_loader import, docstring bullet, the three
  _MATERIALIZED_* resets and checks) were applied, nothing else. Every other file
  applied cleanly.

* fix(agents): reset a default agent only when its template was removed (#16410)
  (cherry picked from commit f16fa23)
  Backport adaptation: test/integration/conftest.py conflicted on context only (a
  main-only updates-loop entry next to it); only this change's _MATERIALIZED_SEEN
  lines were applied. Every other file applied cleanly.

* fix(agents): harden the default-agent healer and the file-name map (#16455)
  (cherry picked from commit 4a11ed2)
* fix(agents): heal a default agent only after a scan that read every spec (#16512)
  (cherry picked from commit 4576a29)
@bolichen97
bolichen97 force-pushed the backport/0.8.0-p0-runtime-agents branch from b91911b to 5452868 Compare October 3, 2026 14:45
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 3, 2026
@bolichen97
bolichen97 merged commit 610ad66 into release/0.8.0 Oct 3, 2026
24 of 31 checks passed
@bolichen97
bolichen97 deleted the backport/0.8.0-p0-runtime-agents branch October 3, 2026 15:29
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 3, 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.

2 participants