Repository navigation
feat(session-control): start a session on a chosen harness with session_create(backend=...) - #33145
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. One note: the turn-start reset works around a hard-Stop respawn that drops the session's allocation identity, and that cause can be reached directly. Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: a conductor starts each worker session on the harness it chooses. ADDITION (Closes #33126).
[FIRST-PRINCIPLES-REVIEWED] 92b6d73 Description read[DESCRIPTION-READ] 8d9fc259642f76b8bb1c6157df4b6c7874492856c505022ec0da2aedde9af70e That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change reuses the existing Notes
[DESIGN-REVIEWED] 92b6d73 Description read[DESCRIPTION-READ] 8e78f70ff9ce15d7cd7b35eb06e5b80eb69b448712214e512270d3a3b8d89bfd 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 |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
e1c96f1 to
f8fe227
Compare
…on_create(backend=...)
f8fe227 to
92b6d73
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Approving. session_create(backend=...) now starts a dashboard session on a chosen harness, the way spawn_run(backend=...) already does for a sub-agent. Gate: 97 ok, 0 red, 0 pending, with the AI review lanes passing.
What I read in the product code:
- The route in
handlers/session_control.pyruns the spawn endpoint's own up-front check (_requested_backend) before it creates anything, so a pick that cannot start is refused with the spawn codes and never becomes a session that silently runs elsewhere. It also refuses a non-string value, and refusesbackendtogether with crew or a work item (backend_with_crew), because a remote crew's harnesses cannot be checked here. That refusal is on a new parameter, so no existing behaviour gets stricter. - The pick is stored once on the slot (
slot.backend, stored spelling) and in the birth metadata, restored by the metadata codec, and published to an in-memory table thatsession_backend_pickreads. Every allocation passes it to the one selection gate asbackend_override, so it ranks above a crewmate's pin exactly as a spawn pick does. The ten or so readers that resolve a backend from a session key (slash commands, model switch, effort, autocompact, wake, transfer, request_server) all take the pick, and passcrew_backendonly when there is no pick, so they agree with the allocation. - A slot created on a harness whose live session runs another one (after a hard Stop respawn) is reset onto its pick, compared against what the gate resolves the pick to, so a pick that governance has since degraded does not reset every turn.
- A spawn from such a session with no
backendof its own inherits the pick at admission, so a queued run andspawn_continuekeep it. modelis judged against the pick, and a worker pin is not reused for a different harness.- The metadata line is unchanged when no pick was made.
- No regex in the added code.
Not checked: I did not run the tests, and I did not read the 243-line test file or the MCP tool schema and docs changes line by line. One small note, not a blocker: the pick table _SESSION_BACKEND_PICKS is keyed by slot and I did not see where an entry is dropped when a slot closes. It holds a short string per slot, so I count it as minor.
I set auto-merge on this head.
Problem / Motivation
Goal: A conductor can start each worker session on the harness it chooses, by passing
backendtosession_createorwork_dispatch.Today every session
session_createorwork_dispatchopens runs on the gateway default (agent.acp_backend); only a Bot's own worker follows that Bot's harness setting. A sub-agent can already pick its harness withspawn_run(backend=...), and a Bot has a per-Bot harness, but a dashboard worker session has neither. A conductor that wants one worker on Claude and another on Codex has to change the gateway default, which moves every chat.Why it matters
Different harnesses suit different tasks and have separate quotas. A conductor fanning work out to several workers should be able to put each on the harness that fits it, and the person should see each worker in the sidebar on the harness it really runs on. Without this the only per-task harness choice is a sub-agent, which the person cannot open, read or take over.
Not a goal
crew(a remote crew starts sessions on its own harnesses).What changed (motivation → approach → change)
spawn_run(backend=...)already starts a session on a chosen harness and keeps it through reset and compaction (backend_override). A dashboard session only lacked a place to store a pick, a way to set it, and the readers that must see it before the session exists. So this reuses that path and adds no second selection gate.backendonsession_create/work_dispatch, spelled asspawn_runspells it (kiro,claude,codex, ...).mcp_dashboard_session_tools.py,mcp_dashboard_session_runs.py,validation_parts/messaging_session_schemas.py_requested_backend):unknown_backend,backend_not_installed,backend_restart_required, nothing created.modelis judged against the pick (model_rejected). Withcrew:backend_with_crew.dashboard/handlers/session_control.py,dashboard/session_control_parts/session_create.pyslot.backend, the birth metadata line and restore, plus an in-memory pick table by slot key (session_backend_pick).dashboard/state_parts/,dashboard/slot_persistence/metadata_codec.py,history_schema.py,members_parts/member_sessions.py,members.pyselect_provider_backendasbackend_override. Every reader that works out a session's harness before it starts passes the same pick, in thecrewmate_backend_pin(...) if pick is None else Noneshape the harness-parity test enforces.dashboard/chat_turn/,dashboard/chat_api/,model_switch.py,template_server_request.py,session_transfer_layers.py,warm_task_brief_wake.pyspawn_runwith nobackend(and nocrew) from such a session takes the pick as its ownbackendat admission, so a queued run replayed after a restart and aspawn_continuekeep it.dashboard/messaging_api/spawn.py,mcp_tools/spawn_parts/schemas.pydashboard/chat_turn/model_fallback.pydashboard/chat_api/slot_effort.pyPrecedence is the gate's:
spawn_run(backend=...)> this pick > the Bot's harness pin > member-DM route >agent.acp_backend. Tool descriptions,docs/system-specs/modules/session-control.md,harness-parity.mdH17 and the bundledsrc/kiro_crew/docs/session-control.mdsay so.This is the creation-time half of the closed #19599, written fresh from main; it shares no code with it.
Backwards compatibility
Compatible:
backendis optional and empty by default; a slot with no pick allocates with exactly the arguments it has on main, and a metadata line without the key reads as no pick.Removes nothing: the diff adds an optional field and a stored key; no route, validator, record or key is removed or tightened.
Tests
test/test_session_create_backend.py(new): a pick is stored on the slot, the birth line and the pick table;kiroselects Kiro's id; no pick changes nothing; an unknown, denied or uninstalled pick is refused with the spawn codes and creates nothing; a non-string pick and a pick withcreware refused; the model is judged against the pick; the allocation hands the pick to the gate; restore reads it back; a cold slot reads as its pick; a live session on another harness is reset and one on its pick is kept; both MCP tools forward it andsession_createrefuses it withcrew.test/test_spawn_backend.py: a child with no backend starts on the parent's pick, the child's own backend wins, a parent with no pick hands down nothing, a child naming another Bot inherits nothing.test/test_slot_metadata_codec.py,test/test_state_parts_facade.py: the new slot field and metadata key.scripts/check_harness_parity.py, and the related guard files (test_crewmate_harness.py,test_chat_runner_composition_contract.py,test_handlers_messaging_composition_contract.py,test_session_control_doc.py,test_mcp_dashboard_registration.py,test_flake_pattern_ratchet.py).Manual verification
What tests we did (end to end, real gateway)
A gateway built from this PR's head
92b6d73248ran on its own port with a fresh, isolatedKIROCREW_HOME; the live gateway and its config were not touched. Installed and startable harnesses on the test host:kas(Kiro CLI, the default) andclaude(Claude Agent SDK). A conductor chat on that gateway called the realkirocrew-dashboardtoolsession_create.session_createWorker A, nobackend"backend": "kas"session_createWorker B,backend: "claude"chat-4-...(Worker B (claude)) on harnessclaude". Reply (translated): "I run in the Kiro Crew dashboard on the Claude Agent SDK (Claude Code); the model is Claude Opus 5.5 (claude-opus-5-5)." Capabilities:"backend": "claude", "models_backend": "claude". The gateway log shows B's session started byclaude-agent-acp"backend": "claude"; A's has nobackendkey"backend": "claude". Reply: "I'm running in the Kiro Crew dashboard, on the Claude Agent SDK (Claude Code) backend, with model Claude Opus 5.5 (claude-opus-5-5)."session_createwithbackend: "nonesuch","codex","pi"backend 'nonesuch' is not available; choose one of ['claude', 'kas', 'kiro'](unknown_backend);backend 'codex' is not installed on this machine (missing: codex-acp)and'pi' ... (missing: pi-acp, pi)(backend_not_installed)spawn_runwith nobackend"backend": "claude"; its session started byclaude-agent-acp. Child's answer (translated): "I run as a Kiro Crew sub-agent; the harness is the Claude Code CLI on Anthropic's Claude Agent SDK; the model is claude-opus-5-5."opus,sonnet); A's lists the Kiro models with credit multipliersA conductor creates a worker on
claude, and the worker answers from Claude (38 s, real time):create-session-on-claude.mp4
Notes on the test setup: the test shell cannot create user namespaces, so the throwaway instance ran with
agent.sandbox_allow_unsandboxed_execand--approval yolo. The workers used thekirocrewtemplate, because that host's sharedkirocrew-workerspec belongs to the live instance. The refusal codes in step 5 come from the create route; the tool reply printed only the message, so a follow-up adds the code to the tool reply.Other notes
spawn_run) does not inherit it; both follow whatspawn_run(backend=...)does today.Related Issues
Closes #33126
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)