Skip to content

fix(session-control): name the backend refusal code in the session_create reply - #33220

Merged
bolichen97 merged 1 commit into
mainfrom
fix/session-create-backend-refusal-code
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/session-create-backend-refusal-code

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When session_create or work_dispatch refuses a backend, the tool reply names the refusal code, as the tool description promises.

The create route refuses a backend that cannot start here with unknown_backend, backend_not_installed or backend_restart_required (from #33145). The MCP tool reply printed only the message, so the code a conductor is told to branch on never reached it.

Why it matters

A conductor that picks a harness for a worker needs to tell "no such harness" from "not installed here" to choose its next step: pick another listed backend, or drop backend. Today it has to parse prose. The gap was found in the end-to-end run recorded on #33126.

Not a goal

  • No code added to the other session_create refusals.
  • No change to the HTTP route's response; it already carries code.

What changed (motivation → approach → change)

The create route already returns the code; only the MCP reply dropped it. The tool's existing per-code remedy hook (_create_refusal_remedy in mcp_dashboard_session_runs.py) now appends the code and the remedy for the three backend refusal codes. One branch, no new state.

Before (tool reply, end-to-end run on a real gateway):

Error: could not create a session: backend 'codex' is not installed on this machine (missing: codex-acp); choose one of ['claude', 'kas', 'kiro']

After (same call, same gateway, this change):

Error: could not create a session: backend 'codex' is not installed on this machine (missing: codex-acp); choose one of ['claude', 'kas', 'kiro'] (code `backend_not_installed`). Pick a backend from that list, or omit `backend` to run on the default harness.

Backwards compatibility

Compatible: the reply only gains a suffix on these three refusals; every other reply is unchanged.

Removes nothing: no route, field or reply is removed or tightened.

Tests

  • test/test_session_create_backend.py::TestTheTools::test_a_backend_refusal_names_its_code: a create route answering unknown_backend makes the session_create tool reply contain (code `unknown_backend`).
  • Run serially with test/test_mcp_dashboard_facade.py; flake8, isort, black and mypy clean on the changed files.

Proof: PROVEN test/test_session_create_backend.py::TestTheTools::test_a_backend_refusal_names_its_code (head 877e5cb)

Manual verification

On the isolated end-to-end gateway used for #33145, a conductor called session_create with backend nonesuch, codex and pi. Replies after this change: (code `unknown_backend`), (code `backend_not_installed`), (code `backend_not_installed`). No session was created for any of them.

Sibling sweep

Swept: git grep -n "_create_refusal_remedy\|refused.code" -- src/kiro_crew/mcp_dashboard_session_runs.py
Sibling: src/kiro_crew/mcp_dashboard_session_runs.py -- changed here

Both session_create and work_dispatch render create refusals through _create_session, which calls this hook, so the one change covers both.

Pattern harvest

Not generalizable: the one place a tool description named refusal codes its reply did not print; the reply hook already existed for exactly this.

Other notes

None.

Related Issues

Closes #33218

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 14:32
@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 877e5cba4d5518cab3eed71c1fe0f5ba4c3b6b21 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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the change appends the backend refusal code inside the reply hook that already exists for create refusals.

[DESIGN-REVIEWED] 877e5cb

Description read

[DESCRIPTION-READ] 149bea79d983d30a370e10b63e8bd7fddb56d3eb1e98aebec49087e275956ded

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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 877e5cba4d5518cab3eed71c1fe0f5ba4c3b6b21 — 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. The code suffix fixes the gap where it occurs, in the one remedy hook that both session_create and work_dispatch replies go through. It uses the per-code branching idiom found across mcp_dashboard_*_runs.py.

What this change ships

Inventory (3 items) — 2 justified

Intent: let a conductor that is refused a backend tell "no such harness" apart from "not installed here" by reading the code in the tool reply, which the tool description (mcp_dashboard_session_tools.py:147) already promises. This is a FIX.

  1. Replies to session_create and work_dispatch that refuse a backend now name the code: unknown_backend, backend_not_installed or backend_restart_required. — justified
  2. The same replies gain a remedy sentence: "Pick a backend from that list, or omit backend". All three route messages in spawn.py:233-277 carry that list. — rides along (it goes past the Goal's "names the refusal code", but the description declares it)
  3. A test pins the unknown_backend code in the session_create reply. — justified

[FIRST-PRINCIPLES-REVIEWED] 877e5cb

Description read

[DESCRIPTION-READ] a92eaed29d8ba9435754504ee2ec8939b4d44316da8429203708e4b2a312da54

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 877e5cba4d5518cab3eed71c1fe0f5ba4c3b6b21 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 877e5cb

Verdict parsed from the review's SHA-scoped output markers for commit 877e5cba4d5518cab3eed71c1fe0f5ba4c3b6b21.

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

@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 877e5cba4d5518cab3eed71c1fe0f5ba4c3b6b21 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 877e5cb

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

@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 on 877e5cb. Base is main, and all 96 checks are green.

_create_refusal_remedy now names the code for the create route's three backend refusals (unknown_backend, backend_not_installed, backend_restart_required), plus a short next step, so a conductor can branch on it. Other refusal codes fall through as before. A test covers the unknown_backend reply.

No regex, no new restrictions.

@bolichen97
bolichen97 merged commit 9601cda into main Nov 8, 2026
96 checks passed
@bolichen97
bolichen97 deleted the fix/session-create-backend-refusal-code branch November 8, 2026 15:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

session_create: name the backend refusal code in the tool reply

2 participants