Repository navigation
feat(onboarding): default to Kiro CLI, offer other coding agents - #13888
Conversation
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- src/kiro_crew/kiro_prerequisite.py:2979 -- False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the six Suggestions
[DESIGN-REVIEWED] ae2a514 Description read[DESCRIPTION-READ] a3c50682bf8bdbf875a51a7d8845e053d5bfd6d0723e16be7db4ac02de1afeb4 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 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Confirm maintainers intend the harness switch to shed its Developer-Mode-preview gating — kas-auth.md's deleted "KAS is a Developer Mode preview" pin recorded that hiding as deliberate. The reversal is declared and carries in-diff cause (first-run now creates users with no Developer Mode path to the switch), so it is not a hidden pin deletion; it is still the one prior decision this PR overturns. Every new surface counted real consumers: What this change shipsInventory (10 items) — 10 justifiedIntent: Let a first-run operator finish setup with a non-Kiro coding harness, and switch harness later without Developer Mode — an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] ae2a514 Description read[DESCRIPTION-READ] cee13aa95bcc1d1a5673bd2ebef195ed6224f2704af3c2e2e61c0e775197a98b That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS "Sandbox turned off" strands the user with no action or link, and "Agent Harness" is a label the setup errors point at but nobody can decode. Watch
Suggestions
[UX-REVIEWED] ae2a514 Description read[DESCRIPTION-READ] ba38ede94b1096f6aff4e4855d284363ba14ad1132d6144cbed919b08765c785 That sha256 names everything this verdict read: the PR description, plus the 28 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 |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsTwo advisory findings; nothing blocks. FINDING — website/src/pages/developer/AgentBackendTab.tsx:1440 — the badge is hardcoded FINDING — test/gui_user/scenarios/auth-sign-in-card-signed-out.yaml:26 — the scenario's route and first step were moved to Settings › Agent Harness but step 2 still says [OPUS-REVIEWED] ae2a514 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
a8f3158 to
012a256
Compare
5b320f0 to
613a892
Compare
78db12e to
4526169
Compare
4526169 to
6b03e2d
Compare
|
|
|
1c5ced7 to
b4d76c5
Compare
|
@iamwhatever Could you review this onboarding flow when you have a chance? It defaults to Kiro CLI while allowing other ACP coding agents, with probe/recheck and sandbox handling. I have addressed the latest automated review findings and CI is running on the current head. Thanks! |
|
|
|
The first-run setup gate checked Kiro CLI alone, so an operator configured for another ACP harness (Claude Code, Codex, ...) with no Kiro CLI was held on "Set up Kiro" indefinitely. - Kiro CLI stays the default and its card is the only Kiro step: it states where things stand, shows the one-line installer for the gateway's platform (copy-only; Kiro Crew still runs nothing), swaps in the two sign-in commands once installed but signed out, and carries its own Check again. The separate Sign in to Kiro card and the page footer are gone. - A collapsed "Use other coding agents" section, modelled on Developer > Agent Backend, lists the selectable third-party harnesses with their install state. The picked agent's panel opens under its own row: install command, sign-in note, Use, and Check again (none for a ready agent). Use writes agent.acp_backend. - The gate reads the configured backend once Kiro is not ready: a usable non-Kiro backend opens the dashboard; one that is not ready keeps setup up with the section open and a way back to Kiro CLI. - The intro no longer calls Kiro CLI the engine and is one translatable sentence rendered with <Trans>.
Problem / Motivation
Goal: Let a first-run operator start Kiro Crew with a usable coding harness without first installing or signing in to Kiro CLI, and let them change harness later without Developer Mode.
The first-run gate only knew Kiro CLI. Someone using Claude Code, Codex, or another selectable ACP harness was held at "Set up Kiro" even when that harness was ready. A new Kiro CLI user saw only a docs link instead of an install command. The only place to switch harness afterwards was Developer > Agent Backend, which is hidden unless Developer Mode is on.
Why it matters
Operators using another harness could not finish onboarding; Kiro CLI newcomers had to leave the page to find the right gateway-host command; and an operator who set up with Claude Code had no visible way to switch back to Kiro CLI or sign in to Kiro later.
Not a goal
main's readiness check; rerun support for non-Kiro harnesses is tracked in Restore safe history reruns for non-Kiro ACP harnesses #14512.agent.acp_backendcontract.What changed (motivation → approach → change)
First-run gate. The gate shows the gateway OS, a Kiro CLI card with a copyable install or sign-in command and its own Check again, and a collapsed "Use other coding agents" picker for the selectable harnesses. The picker reads the same
/api/acp-backendsprobes and writes the sameagent.acp_backendsetting as the Settings tab. A configured independent harness whose install is confirmed opens the dashboard without Kiro CLI; one whose install check failed keeps setup open, matching the gateway's setup-marker rule. The bypass requires what a session on that host requires: an OS sandbox, or unsandboxed execution permitted (the native-Windows default, or an operator opt-in); a harness that needs Kiro Crew's credential mask (for example Codex) stays blocked without the sandbox. A gateway that omits the newunsandboxed_exec_permittedfield is read as not permitted. When the host has a sandbox butagent.sandboxturns it off, the agent's detail names that setting instead of blaming the host, and offers no Check again. The two badges differ: "Host can't sandbox" and "Sandbox turned off". The Update Kiro CLI button says it runskiro-cli updateon the gateway host (hidden for the desktop app's bundled CLI, which it cannot update). KAS stays subject to the Kiro CLI ACP compatibility check, which now runs whether or not Kiro CLI is signed in (KAS needs no Kiro CLI sign-in), and it also needs Kiro Crew's agent specs present and accepted: a missing or rejected spec keeps the repair card. The out-of-date card no longer claims the CLI is signed in. An unknown gateway OS gets platform-free copy (the old "local" filler is dropped). Probe failure keeps the Kiro setup fallback. If the screen's automatic setup record fails after the configured agent turns ready, the dashboard still opens and an error notice floats over it with Try again and a close button; it does not retry on its own. No install or sign-in command is executed by the dashboard.Gateway, first-run only.
/api/acp-backendsrows carry anindependent_setupflag from a fixed list of harnesses that can finish setup without Kiro CLI, and the prerequisite status reports whether the host sandbox can run them. Picking a ready independent harness, pressing Check again on it, or the screen's own poll seeing the configured harness turn ready (once), records setup as finished, and the status reports it immediately, so later browsers and non-owners get in without a restart. If recording fails after the setting is saved, the API returns a coded partial-success error with a retry.unsandboxed_exec_permittedis false when the governance floor (sandbox.min_level) mandates a sandbox, using the same floor checkwrap_argvapplies, so setup cannot finish onto sessions that are then refused. While Kiro CLI is signed out (KAS's normal state, andkiro-cli agent validaterefuses to run signed out), Kiro Crew's agent specs are checked against KAS's own loading steps (load_agent_spec, then prompt resolution) instead; a spec KAS cannot load is reported as rejected, raises the repair card, and blocks the KAS setup record, which re-checks at record time. Because the probe does not know the configured backend, a signed-out user on Kiro CLI with such a spec also sees the repair card. None of this runs once setup is finished.Settings > Agent Harness. The harness switch moves out of Developer > Agent Backend into an ordinary Settings tab (
/settings/agent, under Preferences), laid out like the onboarding picker: one list of radio rows with the onboarding status badges and an "In use" marker, the checked row's detail opening under it, and Kiro sign-in only inside the KAS row. A checked row that is not the one in use says what its Use button does ("New sessions switch from Claude Code to codex."), and the restart-needed line uses the same sentence as first-run setup. Kiro CLI and KAS are listed for everyone. The rows, badges, detail block and copy box are shared components (website/src/components/agentHarness/) used by both screens. The radio is drawn by hand so an unchecked row reads as unchecked under a darkcolor-scheme. "Settings > Agent Harness" replaces "Developer > Agent Backend" in the setup text, the Overview signpost and the gateway's sign-in and sandbox messages, in all 12 locales.Changed areas:
src/kiro_crew/agent_sdk,src/kiro_crew/kiro_prerequisite.py,src/kiro_crew/dashboard,test,website/src/api,website/src/components,website/src/pages,website/src/hooks,website/src/i18n,website/src/test,website/scripts,website/capture,docs, and.github/screenshots/pr-13888.Backwards compatibility
/developer?tab=agent-backendlinks, including the chat's "Sign in to Kiro" link, forward to Settings > Agent Harness and still land on the Kiro sign-in.independent_setupfield and sandbox status fields are additive.Tests
ad73f4b22e, after rebasing ontomain8ae5dff6ee: the KAS version re-check at setup record, the fresh probe in the Check again error response, the Agent Harness save-succeeded-but-record-failed state and the restored Change default crewmate highlight each have a test that fails with the fix removed. 553 backend tests (prerequisite status, config PATCH, error surface, backend cards) and 1,045 frontend tests (gate, Agent Harness, Settings, Developer, all ofsrc/i18nwithI18N_BASE_REF=origin/main) pass, with typecheck, eslint, black, flake8, the SDK-boundary gate and the comment-history gate.55ce021bc9: a KAS setup record that arrives before the boot probe has resolved a kiro-cli now runs the probe and requires the resolved binary to pass theacp --helpcheck, and is refused when no kiro-cli resolves. The new tests fail with the fix removed; 278 prerequisite tests and 1,162 backend tests pass, with black, flake8, the SDK-boundary gate and the comment-history gate.6648366755: the governance-floor rule (20 cases, 12 fail without the fix), KAS spec loading while signed out (6 cases, 4 fail without the fix) and the setup-record failure notice (4 tests, all fail without it) are new. 396 backend tests (prerequisite status, error surface, editable config) with black and flake8, and 1,033 frontend tests (gate, Agent Harness, all ofsrc/i18nwithI18N_BASE_REF=origin/main, which is what caught the five locales using the formal register) with typecheck,i18n:checkand eslint pass. The 22 backend modules importingkiro_prerequisitepass (1,824).main, 38,485 tests acrosssrc/test,src/pages,src/components,src/hooksandsrc/i18npass again.i18n:check,gen:settings(no drift), the web build, eslint on the touched files, and black pass.2e992f5ba0, after rebasing ontomainf10a74d412: 3,673 frontend tests (gate, Agent Harness, Settings, Developer, Overview, i18n) and 2,130 backend tests (prerequisite status, config PATCH, backend install, tool gate, host auth, KAS, onboarding) pass, with typecheck,lint:i18n,i18n:check,gen:settings(no drift), black and flake8. The poll-driven setup record, the immediate status refresh, the native-Windows rule and the distinct sandbox badges each have a test that fails with the fix removed.bde3aca46d: 1,017 focused frontend tests (gate, Agent Harness, Settings, i18n) and 472 backend tests (prerequisite status, backend cards, config PATCH) pass. The signed-out ACP probe, the KAS spec rule (client and marker), sandbox-off copy, the switch-outcome line, the shared restart line and the signed-out out-of-date copy each have a test that fails with the fix removed.Manual verification
Screenshots / video
Settings > Agent Harness, Claude Code in use (light and dark):
More Agent Harness states
The Overview page with KAS selected (cropped to the stat row and the signpost):
First-run setup, Kiro CLI missing and signed out:
First-run setup, other coding agents:
More first-run states
Related Issues
no linked issue: first-run onboarding change requested directly by the maintainer.
History reruns for non-Kiro harnesses are out of scope here and tracked in Restore safe history reruns for non-Kiro ACP harnesses #14512.
Pattern harvest
Not generalizable: this first-run gate was written when Kiro CLI was the only selectable agent and assumed its readiness represented every harness.
Checklist