Skip to content

feat(mcp): session_end_wait wakes a created session from the wait tool - #15166

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-session-end-wait
Sep 30, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-session-end-wait

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A session can wake a worker it created from the wait tool early, without cancelling the worker's turn.

The dashboard's End wait button does this for a person, but the kirocrew-dashboard MCP server has no equivalent. A conductor that already knows its worker's wait is over (the build finished, the PR merged) can only let the worker sleep out the rest of its wait (up to 30 minutes), stop the turn with session_stop (discarding its work), or session_send it text (which ends the wait as a steer but also hands the worker a message to act on).

Why it matters

Dispatch loops spend worker time asleep on a condition the conductor has already observed. Each such wait holds a turn and a subagent slot for minutes that do nothing, and the only faster options today either throw away work or inject an instruction the conductor did not mean to send.

Not a goal

  • A cancel. The tool never stops a turn, drops queued messages, or escalates.
  • Any change to what the End wait button does for a person.
  • Reaching sessions the caller did not create.
  • A standing auto-approve grant. session_end_wait stays out of _CONDUCTOR_DASHBOARD_GRANTS and _MEMBER_DASHBOARD_GRANTS. An unattended dispatch loop reaches it through trust mode, the session-level auto-approve an operator arms, which is the same path session_send and session_stop use for a conductor. An attended loop approves it once. Adding it to the member grants (it is creator-fenced and discards nothing) is left to a maintainer as a follow-up.
  • A generic registry for dashboard actions.

What changed (motivation → approach → change)

The button works by parking the in-flight wait_id on the slot (_end_wait_request); the sleeping tool picks it up from its next keepalive reply and returns a normal result. The new tool reuses that mechanism instead of adding a second one. The browser route needs the caller to name a wait_id because a stale tab can show an old countdown; an MCP caller has no countdown, so the new verb reads the id from the slot at request time and can only name the sleep that is running now.

  • session_end_wait(target) in mcp_dashboard.py, posting to a new strict-internal route /api/session-control/end-wait (added to _STRICT_INTERNAL_API_PATHS in server.py).
  • end_wait_target in dashboard/session_control.py runs authorize_target and then refuses any target the caller did not create (not_creator), including for an owner session the other verbs do not fence. On success it parks the request and records the caller in a new slot field, _end_wait_by. A target that is not sleeping, or whose wait is contested (two sleeps on one session key), gets ended: false with an info string instead of an error. The SEL audit detail records requested, not_waiting or contested.
  • The keepalive reply (handlers/sessions.py) carries end_wait_by when a session parked the request. The wait tool (mcp_tools/control.py) reads it only from a reply whose end_wait names its own sleep, and then returns Wait ended early by session <key> (session_end_wait) after Ns of Ms. The button route clears _end_wait_by so a click is still reported as the user.
  • Containment follows the existing verbs: added to SESSION_CONTROL_TOOLS and to CHANNEL_AGENT_BLOCKED_TOOLS in channel.py, documented as withheld from the conductor grants in agent.py, with a schema in validation.py and a title in mcp_tool_titles.json.
  • Docs: a session_end_wait section in docs/session-control.md, tool counts in docs/index.md, the server row in docs/architecture/mcp.md, the Session control row and endpoint list in docs/feature-map/README.md, the keepalive reply contract in docs/system-specs/modules/learn-cron-dashboard.md, and a tool row plus an "Ending a wait early" section in docs/system-specs/modules/session-control.md.

Backwards compatibility

Compatible: the keepalive reply only gains an optional field, and a wait tool that ignores them behaves exactly as before. Existing routes and tools are unchanged.

Tests

  • test/test_session_end_wait.py: the verb parks the live wait_id and records the caller; a non-waiting target and a contested wait return ended: false without parking anything; a peer the caller did not create is refused not_creator; an ephemeral target is still refused by the shared gate; the keepalive reply carries the requester for a session request and none for a button request; the route refuses a caller without the internal secret, reaches the verb with it, and is in the strict-internal set; MCP dispatch posts the target, renders "Nothing to end" for a non-waiting target, and renders a refusal as an error; the audit detail names requested, not_waiting and contested apart.
  • test/test_wait_tool_early_end.py: a session end names that session in the wait result; an end_wait_by on a reply for another wait is ignored.
  • test/test_mcp_dashboard_registration.py, test/test_session_control_doc.py: the advertised set and the session-control group include the tool.

Manual verification

N/A: the change is a server verb plus a field on an existing reply; the handoff between the verb, the keepalive handler and the wait loop is covered end to end by the unit tests above.

Related Issues

Fixes #15165

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

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Intent: Let a session wake a worker it created from the wait tool early, through the same parked request the End wait button uses, and tell the woken worker which session ended its sleep.
Not a goal: Cancelling a turn, changing the End wait button, reaching sessions the caller did not create, or a generic dashboard-action registry.

@dwu96

dwu96 commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 29, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-end-wait branch from c43f6c9 to 0375a65 Compare September 29, 2026 23:13
@Pearcekieser
Pearcekieser marked this pull request as ready for review September 29, 2026 23:13
@Pearcekieser
Pearcekieser requested a review from a team as a code owner September 29, 2026 23:13
@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 Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 741a67d827566258a62380b68d2d602c0f81ff8b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 741a67d

Description read

[DESCRIPTION-READ] bb5194c01ea8c46ee175337d122e0897a3b9adcbe88c7ac5ed97231e42abdf0f

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 Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 741a67d827566258a62380b68d2d602c0f81ff8b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 741a67d

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 741a67d827566258a62380b68d2d602c0f81ff8b via the fork AI-review pipeline — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify #15165 asks for this shape — the creator fence (owner sessions refused too) and the counted 30-minute cost both rest on that linked issue.

The verb genuinely reuses the End-wait button's parked _end_wait_request (12 existing references counted in src/kiro_crew/dashboard/) rather than adding a second wake mechanism, and the nearest existing spellings are meaningfully different, as the description says: session_stop discards the turn, session_send steer delivers text the worker acts on. The end_wait_by attribution chain earns its place because without it the pre-existing result text ("Wait ended early by the user") would misattribute a peer's wake to the human. No defaults change, the tool stays out of both auto-approve grant sets, no pin is deleted, and every diff hunk is declared in the description.

What this change ships

Inventory (10 items) — 10 justified

Intent: let a session wake a worker it created from the wait tool early without cancelling the worker's turn — an ADDITION.

  1. New session_end_wait MCP tool wakes a created session from wait, keeping its turn — justified
  2. New strict-internal route POST /api/session-control/end-wait — justified
  3. Creator fence: any target the caller did not create is refused, owner sessions included — justified
  4. The woken session's wait result names the peer that ended it, not the user — justified
  5. A not-sleeping or contested target gets an informational reply instead of an error — justified
  6. Channel agents blocked; withheld from conductor and member auto-approve grants — justified
  7. SEL audit distinguishes requested / not_waiting / contested — justified
  8. Keepalive reply gains optional end_wait_by, read only for the reply's own wait — justified
  9. Button-ended waits still report the user (the button route clears the requester) — justified
  10. Docs and tool counts updated (23 → 24) — justified

[FIRST-PRINCIPLES-REVIEWED] 741a67d

Description read

[DESCRIPTION-READ] 6b185413d92fc8b7d6fceb9aeefe67640087f1d8786ef3178b275d627deabf5f

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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 741a67d827566258a62380b68d2d602c0f81ff8b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 741a67d

@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-end-wait branch from 0375a65 to 28fc04e Compare September 30, 2026 00:15
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: dropped end_wait_reason from the keepalive reply

fixed in 28fc04e: end_wait_reason is gone from the keepalive reply and the session end reason is folded back into user.
The reply now carries only end_wait_by, set when a session parked the request; the wait tool reads it only from a reply whose end_wait names its own sleep.
No field is left without a consumer; test_session_end_wait.py and test_wait_tool_early_end.py pin the requester and the other-wait case.

Also in this push: session_end_wait added to the advertised-set pin in test/test_mcp_dashboard_folders.py (the Backend Tests failure on both OSes), and a rebase onto current main with no behaviour change in the resolution.

@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 Sep 30, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-end-wait branch from 28fc04e to 6ece06b Compare September 30, 2026 01:16
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note: rebased onto current main (6ece06b) with no code change, to re-run the two checks that failed on the CI app installation rate limit on 28fc04e: Resolve desktop matrix (00:36:57 UTC) and Fork PR Description ("could not list check-runs", 00:38:12 UTC). The GPT 5.6, Opus 5, Design and First Principles lanes all passed on 28fc04e.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

rebutted: the withhold is intended, and it follows the invariant _CONDUCTOR_DASHBOARD_GRANTS states in agent.py: a granted verb may CREATE or READ, never MUTATE workspace state that already exists and is not the agent's own.
Ending a wait mutates the target's turn: its wait returns now instead of at the time the target chose. The conductor ingests untrusted content on unattended cycles, so an auto-approved call would let that content move any reachable worker's turn forward with nobody deciding.
The motivating loop still works without a standing grant: an operator who arms a conductor in trust mode (the session-level grant session_send/session_stop already rely on) gets session_end_wait without a prompt, and attended sessions get it after one approval.
The server-side fence is also narrower than those two verbs: end_wait_target refuses any target the caller did not create (not_creator), so a later grant would widen nothing beyond the caller's own workers.
Adding it to the conductor or member grants is a trust decision for a maintainer; this PR deliberately does not make it.

iamwhatever
iamwhatever previously approved these changes Sep 30, 2026

@iamwhatever iamwhatever 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.

Reviewed. session_end_wait runs the shared authorize_target gate and then _created_by_other for every caller including owners (stricter than session_stop), failing closed on a blank _created_by; a worker cannot wake its creator and a subagent reaches only its parent's own workers. Route is in _STRICT_INTERNAL_API_PATHS and the tool is channel-blocked. No await between gate and write. control.py reads end_wait_by only from a reply naming this sleep, capped at 128 chars.

Non-blocking test gap: test_a_button_request_reports_the_user never seeds a stale _end_wait_by and never goes through api_chat_slot_end_wait, so deleting the clear at chat_handlers.py:5565 still passes; either add a route-level test with that seeding or clear _end_wait_by at every site that clears _end_wait_request (state.py:3927 says it needs no clearing, but none of the consume sites clear it).

@iamwhatever
iamwhatever enabled auto-merge (squash) September 30, 2026 05:29
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
auto-merge was automatically disabled September 30, 2026 06:00

Head branch was pushed to by a user without write access

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

rebutted: the withheld default is intended, and this item's first clearing condition asks a human to confirm it. That call is left to a maintainer.
_CONDUCTOR_DASHBOARD_GRANTS grants only verbs that create or read. Ending a wait moves another session's turn forward, and a conductor ingests untrusted content on unattended cycles, so an auto-approved call would let that content advance a worker's turn with no one deciding.
The dispatch loop still works on default config. An attended caller approves the call once, and an operator who arms a conductor in trust mode gets it without a prompt, the same session-level grant session_send and session_stop rely on.
The member-grant route this item names as the other clearing condition is answered for span 8ed0ef1cf537: it is a sound follow-up, kept out of this PR because it is a trust change.

@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-end-wait branch from 070b63b to eda6bf0 Compare September 30, 2026 09:01
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

fixed: docs/system-specs/modules/session-control.md now has a session_end_wait row in the tool table and an "Ending a wait early" section after the wait → read poll loop. The section covers the creator fence that binds every caller class, reuse of the button's _end_wait_request, the end_wait_by handoff, the informational not-waiting and contested replies, and the audit values. The "Ordinary (non-member) callers are untouched" line now names this verb's fence as the exception.

@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 Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

fixed: the PR description now states the approval path, which is this item's first clearing condition. A new "Not a goal" entry says session_end_wait stays out of _CONDUCTOR_DASHBOARD_GRANTS and _MEMBER_DASHBOARD_GRANTS. An unattended dispatch loop reaches it through trust mode, the session-level auto-approve an operator arms and the same path session_send and session_stop use for a conductor. An attended loop approves it once.
Adding it to the member grants on the creator-fence argument is recorded there as a maintainer follow-up, because it is a trust change and also moves the _MEMBER_DASHBOARD_GRANTS contract pins.

@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 Sep 30, 2026
…l early

Adds session_end_wait to kirocrew-dashboard. It parks the same end-wait request the dashboard's End wait button parks, aimed at the wait in flight on a session the caller created, via a new strict-internal /api/session-control/end-wait route. The keepalive reply now names a session requester so the woken wait's result says which session ended it.
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-end-wait branch from eda6bf0 to 741a67d Compare September 30, 2026 10:15
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Same-tree retrigger: 741a67d827 has the same tree as eda6bf03e7 and only a new commit timestamp. Round 7 was green except Backend Tests (Windows) shard 8, which failed on test_decisions_memory_recall_reachable.py::test_a_timed_out_request_records_nothing, a timing test in code this PR does not touch. No code change.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Sep 30, 2026

@iamwhatever iamwhatever 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.

Re-approving: head 741a67d has the same tree (ad222e4aa5c8) as the head I approved earlier; timestamp-only re-push to clear a Windows shard flake in a test this PR does not touch.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 30, 2026 17:32
@iamwhatever
iamwhatever merged commit 707051e into kirodotdev:main Sep 30, 2026
102 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(mcp): session_end_wait to wake a created session from the wait tool

3 participants