feat(doctor): report the KAS bundle engine instead of probing kiro-cli
Problem / Motivation
Goal: On the KAS bundle route, kirocrew doctor, the diagnostics bundle and the gateway self-update describe the engine Kiro Crew actually runs, and never ask kiro-cli for it.
With agent.acp_backend = "kas" and agent.kas_bundle = true, Kiro Crew runs its own installed engine and kiro-cli may not be on the machine at all. Three surfaces still talked about kiro-cli anyway. kirocrew doctor said kiro-cli: not found and told the user to install it, printed kas auth: kiro-cli's own sign-in; could not check, and skipped the version row. The diagnostics bundle's versions.txt said kiro_cli_version: unavailable with nothing about the engine. kirocrew update and the gateway's unattended auto-apply still ran kiro-cli update, and the gateway warned at boot when a kiro-cli it never spawns was old.
Why it matters
A user on the bundle route reads doctor to learn if their install is healthy. Today it sends them to install a program nothing on their machine will run, and hides the one fact that matters: which engine is installed and whether it is the release's pin. The same gap makes a support bundle useless for a bundle-route host. Fixing this is one of the rows that lets agent.kas_bundle become the default and the desktop app drop the bundled kiro-cli (#21843).
Not a goal
- The dashboard identity endpoint (
whoamiindashboard/handlers/sessions.py) and the model picker: separate items of #21843. - Flipping
agent.kas_bundleto default-on, or changing what the relay route (bundle off) reports: every kiro-cli row there is unchanged. - The spec
permissionsblock's kiro-cli version gate (#20730): doctor keeps naming it. - The dashboard's own
update-cliaction in the prerequisite service.
What changed (motivation → approach → change)
One question decides all three surfaces: is the next spawn Crew's own engine? kas_bundle_route() in src/kiro_crew/agent_sdk/kas_bundle.py answers it, positive on both halves (KAS selected AND agent.kas_bundle on), read from config at call time. Every kiro-cli-facing diagnostic asks it, so they cannot disagree. The same module gains installed_engine_label(), the one spelling of the engine's version, and KAS_BUNDLE_SIGN_IN_REMEDY, the remedy that names only Crew's sign-in.
| Surface | Bundle route now says | Relay route |
|---|---|---|
| doctor Dependencies | kiro-cli: ⏭ not installed; not needed (KAS runs Kiro Crew's own engine bundle), no install hint | unchanged |
| doctor KAS backend | engine version, pin: against this release's KAS_PIN_VERSION (⚠️ only when KIROCREW_KAS_VERSION picked another; other installed versions listed), the install.json path and its two entry points, the spawn argv, the vault as the only owner with Crew's sign-in remedy | unchanged |
doctor kas auth: row | the vault decides: ✅ Kiro Crew vault or ⏹ Kiro Crew vault; not signed in plus the remedy; never falls through to kiro-cli whoami | unchanged |
| doctor Connectivity | engine: ✅ KAS <ver>, Node <ver> instead of kiro-cli --version | unchanged |
versions.txt | kiro_cli_version: unavailable (not used: …) and a new kas_engine: line with the pin | kas_engine: not selected |
kirocrew update, auto-apply | kiro-cli update skipped; the printed line / log says kiro-cli is not used and names kirocrew kas install for a changed engine pin (the update itself installs no engine) | unchanged |
| gateway boot | the outdated-kiro-cli warning is skipped | unchanged |
acp/kas_bundle.py makes the install.json name public so doctor can print its path. cli_doctor.py threads one route decision to both of its kiro-cli rows; the new KAS rows live in cli_doctor_parts/kas_relay.py. doctor_checks/agents.py owns the auth row. diagnostics.py, cli_server_update.py, slack/gateway_runtime/update_apply.py and install_repair.py each read the one predicate. docs/system-specs/modules/cli.md and acp-client.md record the rows.
Backwards compatibility
Compatible: the predicate is false on every install that exists today (the bundle is off by default), so every row, line and update step keeps its current text and behaviour there. _INSTALL_RECORD_NAME was a private module constant with no reader outside its file.
Removes nothing: no row, line or step is taken away; the bundle route gets different text where it got wrong text.
Tests
test/test_cli_doctor_agent_auth.py: the KAS section'spin:row for the pinned engine and for an overridden one (namesKIROCREW_KAS_VERSION, lists the other installed version), theinstall.jsonand entry-point rows, the vault row green only for a-> usableidentity and a warning with the remedy for a stored identity the issuer rejected; thekas auth:row on the bundle route for an empty vault (Crew's remedy, nokiro-cli login, nocould not check), a signed-in vault (no second store), a stored-but-unusable identity, and the relay-route fallback to the kiro-cli store unchanged.test/test_kiro_cli_pin.py:versions.txt's kiro-cli line says "not used" on the bundle route and staysunavailablewhen only the flag is on; thekas_engine:line for an installed engine, for no install, and for the relay route.test/test_slack_gateway_more_coverage.py: the boot-time outdated warning neither pins nor spawns kiro-cli on the bundle route.test/test_slack_gateway_update_reset.py: the auto-apply skipskiro-cli updateon the bundle route, logs the reason namingkirocrew kas install, and still builds the frontend.
Manual verification
Isolated run per docs/guides/worktree-verification-recipes.md: own KIROCREW_HOME, KIRO_HOME=<data home>/kiro, a fake HOME so no known kiro-cli install dir resolves, kiro-cli off PATH, agent.kas_bundle: true, engine installed with kirocrew kas install. kirocrew doctor exits 0 and ends ✅ Kiro Crew is ready!; excerpt:
kiro-cli: ⏭ not installed; not needed (KAS runs Kiro Crew's own engine bundle)
kas auth: ⏹ Kiro Crew vault; not signed in
Sign in from Settings → Agent Harness → Kiro sign-in, then start a new chat.
kiro-cli is not used on this route.
KAS backend
bundle: ✅ KAS 0.66.33, Node 22.23.3
pin: ✅ KAS 0.66.33 is this release's pin
install.json: /tmp/kc-bundle-doctor-home/engines/kas/0.66.33/install.json
engine: …/engines/kas/0.66.33/bundle/node_modules/@kiro/agent/dist/server/acp-server.js
node: …/engines/kas/0.66.33/node/node-v22.23.3-linux-arm64/bin/node
crew vault: ⚠️ not signed in; the first prompt will ask for a sign-in
Connectivity
engine: ✅ KAS 0.66.33, Node 22.23.3 (Kiro Crew's own bundle; kiro-cli not used)
✅ Kiro Crew is ready!
kirocrew doctor --bundle on the same home: kiro_cli_version: unavailable (not used: KAS runs Kiro Crew's own engine bundle) and kas_engine: KAS 0.66.33, Node 22.23.3 (release pins KAS 0.66.33).
Parity: the same doctor run on a relay-route home (kas_bundle: false, kiro-cli 2.34.0 installed) from origin/main and from this branch: every kiro-cli, kas auth, relay:, engine:, token: and tool names row byte-identical; versions.txt reads kiro_cli_version: kiro-cli 2.34.0 and kas_engine: not selected.
Related Issues
Part of #21843
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
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.