Skip to content

feat(session-control): start a session on a chosen harness with session_create(backend=...) - #33145

Merged
bolichen97 merged 1 commit into
mainfrom
feat/worker-backend-select
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/worker-backend-select

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A conductor can start each worker session on the harness it chooses, by passing backend to session_create or work_dispatch.

Today every session session_create or work_dispatch opens 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 with spawn_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

  • No verb to switch a live session to another harness. The pick is made at creation only.
  • No change to side chats, thread replies or their read-only tool posture.
  • No backend dropdown in the composer.
  • No pick with 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.

Part What it does Where
The field Optional backend on session_create / work_dispatch, spelled as spawn_run spells it (kiro, claude, codex, ...). mcp_dashboard_session_tools.py, mcp_dashboard_session_runs.py, validation_parts/messaging_session_schemas.py
Create-time refusal The create route runs the spawn endpoint's own check (_requested_backend): unknown_backend, backend_not_installed, backend_restart_required, nothing created. model is judged against the pick (model_rejected). With crew: backend_with_crew. dashboard/handlers/session_control.py, dashboard/session_control_parts/session_create.py
Storage slot.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.py
The one gate Both allocation sites pass the pick to select_provider_backend as backend_override. Every reader that works out a session's harness before it starts passes the same pick, in the crewmate_backend_pin(...) if pick is None else None shape 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.py
Children A spawn_run with no backend (and no crew) from such a session takes the pick as its own backend at admission, so a queued run replayed after a restart and a spawn_continue keep it. dashboard/messaging_api/spawn.py, mcp_tools/spawn_parts/schemas.py
Live mismatch A live session on another harness at turn start (a hard Stop's respawn starts with no identity) is reset onto the pick. dashboard/chat_turn/model_fallback.py
UI A cold slot's selection capabilities answer with the pick, so the Context panel and the model picker name the right harness before the first turn. dashboard/chat_api/slot_effort.py

Precedence 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.md H17 and the bundled src/kiro_crew/docs/session-control.md say so.

This is the creation-time half of the closed #19599, written fresh from main; it shares no code with it.

Backwards compatibility

Compatible: backend is 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; kiro selects 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 with crew are 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 and session_create refuses it with crew.
  • 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.
  • Determinism: the new tests passed 3 repeats and a reversed class order.
  • Gates run locally: flake8, isort, black, mypy on the changed files, 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 92b6d73248 ran on its own port with a fresh, isolated KIROCREW_HOME; the live gateway and its config were not touched. Installed and startable harnesses on the test host: kas (Kiro CLI, the default) and claude (Claude Agent SDK). A conductor chat on that gateway called the real kirocrew-dashboard tool session_create.

Step What we did Result
1 session_create Worker A, no backend Reply (translated from Chinese): "I run on Kiro CLI, connected to the Kiro Crew gateway over ACP; the model is Claude Opus 5.5." Selection capabilities: "backend": "kas"
2 session_create Worker B, backend: "claude" Tool reply: "Opened chat-4-... (Worker B (claude)) on harness claude". 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 by claude-agent-acp
3 Persisted pick B's metadata line: "backend": "claude"; A's has no backend key
4 Restarted the gateway, read B cold, then sent B a message Cold capabilities still "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)."
5 session_create with backend: "nonesuch", "codex", "pi" Refused, no session made: 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)
6 From B, spawn_run with no backend The child's run state records "backend": "claude"; its session started by claude-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."
7 Dashboard B's model picker lists Claude's own models (opus, sonnet); A's lists the Kiro models with credit multipliers

Worker B, created on claude: its reply and its child's answer

Worker B's model picker: Claude's own model list

Worker A, no backend: runs on Kiro CLI

Worker A's model picker: the Kiro model list, for contrast

A 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_exec and --approval yolo. The workers used the kirocrew template, because that host's shared kirocrew-worker spec 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

  • A fork of a picked session starts with no pick, and a grandchild of a picked session (a sub-agent's own spawn_run) does not inherit it; both follow what spawn_run(backend=...) does today.
  • A pick that governance denies after creation degrades to Kiro through the existing gate, with the reason in the log.

Related Issues

Closes #33126

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

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners November 8, 2026 11:54
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 92b6d73248fa7c4121161d3390ea737a14b84507 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 92b6d73248fa7c4121161d3390ea737a14b84507 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 6 — symptom-level: the diff says "A hard Stop's respawn starts the key with no identity", then detects the mismatch in _turn_admit and resets the session, so the respawn starts a process on the wrong harness and the next turn starts it again. The cause is session_lifecycle_parts/turn_stop.py:426 calling owner._eager_respawn(key) with no identity. The reset path (teardown.py:389) calls _respawn_as(key, allocation_identity(owner, key, session)), and session is in scope at the hard-Stop site. 1 of 2 respawn sites drops identity. That also loses spawn_run(backend=...)'s backend_override, extra_env and reasoning_effort_override on a hard Stop.
    Subtraction: delete _live_session_off_slot_backend and its call in turn_admission.py, and have the hard Stop respawn through _respawn_as with allocation_identity(...). If that path is out of scope, defer it to an issue.

What this change ships

Inventory (8 items) — 7 justified

Intent: a conductor starts each worker session on the harness it chooses. ADDITION (Closes #33126).

  1. session_create / work_dispatch take an optional backend — justified
  2. A pick that cannot start is refused before anything is created, with the spawn endpoint's codes; backend with crew is refused (backend_with_crew) — justified
  3. The pick is persisted on the slot and its metadata line, and comes back after a restart — justified
  4. model is judged against the picked harness — justified
  5. Pre-start readers (Context panel, model picker, slash commands, transfer, wake) report the picked harness — justified
  6. A live session on another harness is reset onto the pick at turn start — symptom-level: hard-Stop respawn drops identity
  7. A spawn_run with no backend from a picked session inherits the pick — justified
  8. The create reply names the harness and any failover_from — justified

[FIRST-PRINCIPLES-REVIEWED] 92b6d73

Description read

[DESCRIPTION-READ] 8d9fc259642f76b8bb1c6157df4b6c7874492856c505022ec0da2aedde9af70e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 92b6d73248fa7c4121161d3390ea737a14b84507 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 92b6d73

Verdict parsed from the review's SHA-scoped output markers for commit 92b6d73248fa7c4121161d3390ea737a14b84507.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 92b6d73248fa7c4121161d3390ea737a14b84507 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 92b6d73248fa7c4121161d3390ea737a14b84507 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change reuses the existing backend_override gate, adds an optional field that changes nothing when left empty, takes nothing away, and touches no website/ surface.

Notes

  • The pick is stored twice: once on the slot (slot.backend) and once in _SESSION_BACKEND_PICKS. The diff writes the table in two places, at birth and on restore, and never clears it when a slot is deleted or archived. The two copies can drift apart, and the table keeps entries for slots that no longer exist. Clearing the entry on slot teardown would keep the table matching the slot.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 92b6d73248fa7c4121161d3390ea737a14b84507 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 92b6d73

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 92b6d73248fa7c4121161d3390ea737a14b84507 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 8, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/worker-backend-select branch from e1c96f1 to f8fe227 Compare November 8, 2026 12:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 8, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/worker-backend-select branch from f8fe227 to 92b6d73 Compare November 8, 2026 13:10
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 8, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.py runs 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 refuses backend together 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 that session_backend_pick reads. Every allocation passes it to the one selection gate as backend_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 pass crew_backend only 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 backend of its own inherits the pick at admission, so a queued run and spawn_continue keep it.
  • model is 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let session_create and work_dispatch start a worker on a chosen harness

2 participants