feat(doctor): report the KAS bundle engine instead of probing kiro-cli

Merged
CR
1mo ago
+572-21

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 (whoami in dashboard/handlers/sessions.py) and the model picker: separate items of #21843.
  • Flipping agent.kas_bundle to default-on, or changing what the relay route (bundle off) reports: every kiro-cli row there is unchanged.
  • The spec permissions block's kiro-cli version gate (#20730): doctor keeps naming it.
  • The dashboard's own update-cli action 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.

SurfaceBundle route now saysRelay route
doctor Dependencieskiro-cli: ⏭ not installed; not needed (KAS runs Kiro Crew's own engine bundle), no install hintunchanged
doctor KAS backendengine 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 remedyunchanged
doctor kas auth: rowthe vault decides: ✅ Kiro Crew vault or ⏹ Kiro Crew vault; not signed in plus the remedy; never falls through to kiro-cli whoamiunchanged
doctor Connectivityengine: ✅ KAS <ver>, Node <ver> instead of kiro-cli --versionunchanged
versions.txtkiro_cli_version: unavailable (not used: …) and a new kas_engine: line with the pinkas_engine: not selected
kirocrew update, auto-applykiro-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 bootthe outdated-kiro-cli warning is skippedunchanged

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's pin: row for the pinned engine and for an overridden one (names KIROCREW_KAS_VERSION, lists the other installed version), the install.json and entry-point rows, the vault row green only for a -> usable identity and a warning with the remedy for a stored identity the issuer rejected; the kas auth: row on the bundle route for an empty vault (Crew's remedy, no kiro-cli login, no could 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 stays unavailable when only the flag is on; the kas_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 skips kiro-cli update on the bundle route, logs the reason naming kirocrew 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.