Repository navigation
Conversation
|
@buluoray, could you review this? It narrows The default ( needs-a-decision
|
Add agent.kiro_cli_engine with "auto" (default) and "v2". "auto" keeps the 2026-10-28 rule unchanged: a stored Kiro CLI choice runs on the KAS path once kiro-cli is confirmed to offer v3. "v2" keeps that choice on the Kiro CLI harness and starts kiro-cli with --agent-engine v2, which kiro-cli 3.0 needs because a bare "acp" starts v3. The pin is added only while the pinned kiro-cli's acp --help lists v2; otherwise the argv is unchanged, and once kiro-cli retires v2 the choice follows "auto" again. Covers both Kiro CLI argv builders, the crewmate pin, the gateway floor and the per-process verdict. Settings > Agent Harness shows the picker in the Kiro CLI row, labelled temporary. The save-KAS offer stays quiet for a v2 user because the pick no longer resolves to KAS. Part of kirodotdev#20450
6f14e36 to
acb17f5
Compare
|
Edited the "Problem / Motivation" section at the PR author's request: "Measured on this host" now reads "Measured on an aarch64 Linux host with kiro-cli 3.0.0", so readers know what was measured. The goal and findings are unchanged. |
|
V2 is deprecated |
Problem / Motivation
Goal: A person whose Agent Harness is Kiro CLI can choose to keep kiro-cli's V2 engine until kiro-cli removes it, while the default stays exactly as the 2026-10-28 decision describes.
On kiro-cli 3.0.0, a bare
kiro-cli acpstarts the V3 engine, although its--helpstill says "v2 when neither is set". Measured on an aarch64 Linux host with kiro-cli 3.0.0: an ACPinitializeagainstkiro-cli acpreturns the V3 capability block (_kiro/...extension methods); the same call againstkiro-cli acp --agent-engine v2returns a plainagentInfo {name: "Kiro CLI Agent", version: "3.0.0"}. Combined with docs/decisions/2026-10-28-a-kiro-cli-choice-runs-on-kas.md, every Kiro CLI choice now runs on V3, and there is no way back to V2.This needs @buluoray's sign-off. It narrows a recorded decision, which AGENTS.md (§ Specs and docs) and
docs/decisions/README.mdrule 3 say only a maintainer may do. A draft superseding entry is at the end of this description for the owner to approve, edit or reject.Why it matters
V3 has an open defect that hits Kiro CLI users today: sub-agents receive the parent session's context and skill catalog (internal ticket P554087731). People who depend on isolated sub-agents have no workaround while every Kiro CLI choice runs V3. #20450 asked for the explicit
--agent-engine v2pin before the default flip; this delivers it as an opt-in instead of a default.Not a goal
"auto"is today's behaviour, byte for byte.--agent-engine v3and never reads the setting.docs/decisions/README.mdlets an agent add an entry only for a decision a maintainer already made, so the entry is drafted below rather than committed.What changed (motivation → approach → change)
New setting
agent.kiro_cli_engine:auto(default) orv2.auto: nothing moves. A Kiro CLI choice runs on KAS once kiro-cli is confirmed to offer V3, and on the V2 launch otherwise.v2: the Kiro CLI choice stays on the Kiro CLI harness, and kiro-cli starts with--agent-engine v2. The flag is added only while the pinned kiro-cli'sacp --helplists V2, read by a cached probe that never runs a binary found onPATH. If kiro-cli has no engine selector, the probe can't run, or V2 is retired, the command is unchanged and the reason is logged once. Once kiro-cli is known to have retired V2, the choice followsautoagain.The rule applies everywhere a Kiro CLI choice is resolved or launched: both command builders, a crewmate's own
kiropin, the gateway's startup check and the per-process check outside the gateway. The "Kiro CLI now runs on Kiro Agent" note and its one-click "save KAS" button stay quiet for av2user, because the choice no longer resolves to KAS.kirocrew doctorprints an engine row.The setting is read once per process, so a save reaches the choice and the launch together at the next restart. Settings → Agent Harness → Kiro CLI shows "Engine: Automatic / V2 (until kiro-cli removes it)". The setting needs a restart, and the card says so after a save. All 12 catalogs carry the new strings.
Where:
src/kiro_crew/kiro_cli_engine.py(new: the setting's values and the command flag),kiro_cli.py(acp_agent_engines_at),agent_sdk/backends.py(kiro_cli_pick_backend(engine),record_kiro_cli_v2_evidence),config/sections_agent.py,config/loader_builders.py,config/loader_document.py(field, loader, document reader),platform/bootstrap.py(gateway check),crewmate_harness.py,acp/harness/kiro.pyandacp/client_start.py(the two command builders),cli_doctor.py+cli_doctor_parts/kas_relay.py(engine row),dashboard/handlers/core_config_schema.py(PATCH schema),config-baseline.json(regenerated),website/src/pages/developer/KiroCliEngineCard.tsx+AgentBackendTab.tsx(UI),website/src/i18n/locales/*(strings).Owning specs updated in this commit: harness-parity H1, H9 and H17, the harness-choice record in config.md, and the Kiro CLI launch line in acp-client.md.
Backwards compatibility
Compatible: the setting is new and defaults to
auto, which follows the same code path as main. No stored value changes meaning, and the schema accepts onlyautoandv2.Removes nothing: no field, path, validator or behaviour that main accepts is narrowed. The KAS move is skipped only for a user who saves
v2.Tests
test/test_kiro_cli_engine.py(52 tests):autoandv2on bothKiroHarness.resolve_spawnand theAcpClientKiro pathautoacp --helpresult is reused, so the engine read spawns nothing extrakirocrew doctorkeeps its KAS rows when a policy moved av2Kiro CLI choice onto KASacp --helpparser and cacheautowith confirmed V3 still runs on KAS, so it is unchanged from mainv2keeps the choice on Kiro CLI, including the provider factory, the crewmate pin (H17) and the per-process checkv2on a kiro-cli that retired V2 followsautov2auto/v2and refusesv3,v1,V2,"",2andnullwith a 400, writing nothingwebsite/src/test/KiroCliEngineCard.test.tsx: the stored value shown, the temporary V2 label, the PATCH on pick, no write when the stored value is picked again, restart-pending after a save, inline error on a failed save.website/src/test/AgentBackendTab.detailCard.test.tsx: the picker renders in the Kiro CLI detail only.test_acp_harness_contract,test_acp_backend_kas,test_acp_client_binary_resolution,test_crewmate_harness,test_kas_cli_floor,test_kiro_on_kas_notice,test_harness_parity,test_cli_chat,test_config_baseline,test_config_schema,test_cli_doctor_parts, the usage-scrape suites and theAgentBackendTabvitest files.-n 4and in a seeded shuffled order (52 passed); the vitest card file green in 5--sequence.shuffleruns.Proof: not provable -- other: feat PR, no reverted-hunk proof applies; the auto-unchanged and v2 tests above pin both sides.
Manual verification
Live check on an aarch64 Linux host with kiro-cli 3.0.0, using this branch's command builder against the real pinned binary:
I couldn't run a full gateway on that Linux host: its sandbox's SQLite has no FTS5 and there is no systemd user bus. So the end-to-end "new session's child runs
acp --agent-engine v2" check covers the two command builders, which every session path goes through: sessions, sub-agents (spawn_run), crons, crew and worker sessions, background sessions, session reload/respawn and model switch (providers/acp_runtime_start.py,session_background.py→KiroHarness.resolve_spawn), plusknowledge/llm_pooland the placeholder client (AcpClient's own Kiro path).agent_sdk/pod_child_probe.py's bareacpstartup probe carries no session and is unchanged.Screenshots / video
The images are committed under
temp-screenshots/kiro-cli-engine/(the fork-PR path in.gitignoreand docs/ci/ci-and-reviews.md, read by the review lanes) and linked here at the head commit so they render. The Kiro CLI row's new picker, rendered from Storybook with the real schema entry (dark theme). Automatic (default), V2 saved, and the open list:Related Issues
Part of #20450
Draft superseding decision entry (for @buluoray)
Proposed file
docs/decisions/2026-11-04-a-kiro-cli-choice-may-keep-kiro-clis-v2-engine.md, to be added by or quoting the owner in its own PR, per rule 3:Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)