Repository navigation
feat(pi): report handed-off MCP servers pi did not register - #31121
Conversation
On pi, Crew's MCP servers reach the session only through the gate extension's per-session handoff file. Nothing came back from the pi process to say whether it registered them, so a handoff that did not open, or a name shadowed by pi's own mcp.json, left the server with no cause on the MCP card and nothing in the subagent's spawn-time reading. The extension now writes a nonce-bound receipt to the session's scratch window during session_start, and the host reads it before the first prompt: a server pi confirms it did not register becomes a failed row naming the cause; no valid receipt is only a warning, never a failed row. The Real Adapter lane measures that the receipt exists when pi-acp answers session/new. Closes #19774 Co-authored-by: Leon <leon.lai.yc@gmail.com>
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the receipt is additive and read once, an unconfirmed result is only logged, and no session is refused. Notes
[DESIGN-REVIEWED] 7316816 Description read[DESCRIPTION-READ] 80b99012f15be55e4d752e468e8b2711f957a208a80a05b62e2cc70fc10f5d53 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Each item answers the problem in #19774: servers pi never registered show up with no named cause. Each one reuses the existing failed-row path ( What this change shipsInventory (8 items) — 8 justifiedIntent: on pi, a user should see which Crew MCP servers pi did not register, and why, before the first prompt. ADDITION (closes #19774).
[FIRST-PRINCIPLES-REVIEWED] 7316816 Description read[DESCRIPTION-READ] 73991f4435e7fd50bbebaa78af4dff7b24141818723315536eba9a779e18cb9b 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: |
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: |
buluoray
left a comment
There was a problem hiding this comment.
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:
APPROVE at 7316816.
What it does for users: on pi, a handed-off Crew MCP server that pi did not register now appears on the MCP card as failed before the first prompt, with the cause pi named (a same-named entry in pi's own mcp.json, an unreadable mcp.json, a refused or replaced registration, or a handoff that did not load). Until now that server only showed as "not reported", with no cause.
Harness parity. Every behaviour change sits in a branch that was already pi-only. In client_start.py around line 1115 the existing if self._is_pi: block now calls verify_registration before it discards the handoff. _republish_pi_mcp_handoff (client_mcp_array.py:1093) is pi-only. The receipt path is set in harness/pi.py:1093-1099. Identity is stated positively throughout: _is_pi appears everywhere and no not is_kiro check was added. The work reuses seams that already existed: the session tree's shared work directory, the gate nonce, and McpSessionReport.record_pruned for the failed rows. The one protocol addition on ProcessSession (harness/base.py:153), the work-directory property, declares a property that AcpClient already exposes (client_class.py:1271), so the seam is described more precisely without being widened. The Kiro path is unchanged.
Security. The receipt reader (pi_mcp_registration.py:89-138) opens the file with O_NOFOLLOW and O_NONBLOCK, accepts only a regular file, caps the read, requires the marker, version and nonce, and accepts only known statuses and causes. It removes the file whatever it contains. A missing or invalid receipt produces a warning log line and no failed row (lines 154-161), so an unknown is never reported as "unavailable". The spawn env drops an inherited receipt path before setting its own (pi.py:1097). No session is refused on any outcome. Nothing is loosened.
Evidence:
- Targeted tests: test_pi_mcp_registration.py, test_pi_gate_extension_mcp.py, test_pi_real_adapter.py, test_acp_pi_backend.py and test_acp_refactor_facade.py gave 550 passed and 9 skipped. The skips are the real pi-acp cases, which need the pinned npm install, and one Windows-only codec case.
- Mutation: removing the nonce check from read_registration turned test_another_sessions_receipt_reports_unconfirmed red, and the other 30 tests in the file stayed green. The tree was restored and git status was clean afterwards.
- CI on this head: 77 success and 16 skipped, with Real Adapter Contract Tests green and PR Readiness green. All five review lanes pass on this head. merge-tree against main is clean (exit 0).
Source-only: I did not run the measured ordering locally (that pi finishes session_start before pi-acp answers session/new). I relied on the green Real Adapter Contract Tests job for it.
Follow-ups (non-blocking):
- The Backwards compatibility section says the receipt's one writer is the sealed gate extension. Other agents of the same session tree can also write that shared work directory, as the description notes elsewhere. The design lane points out that a planted file can only add failed rows, but the spawn notice reads those rows as "do not retry". Please state in harness-parity.md that the nonce in the file name and body is the only thing binding the receipt to this session, and reword that sentence to match.
Problem / Motivation
Goal: A pi session whose own pi process did not register a handed-off Crew MCP server shows that server as failed, with the cause pi named, before its first prompt.
On pi, Crew's MCP servers reach the session only through the gate extension's per-session handoff file, because pi-acp drops the
session/newarray. Nothing comes back from the pi process to say whether it registered them. When the handoff file is missing, unreadable or sealed for another session, or a name is shadowed by pi's ownmcp.json, the server simply never reports: the MCP card shows it as not reported with no cause, and the routing read-back cannot help because it runs a separate pi child without the handoff.Why it matters
Every Crew capability on pi (send_message, memory, cron, crew tools) is an MCP tool. A server pi never registered leaves the agent without those tools and the user with no named cause. The session-open mount check covers only pooled broker stubs (not the member mounts pi execs directly), cannot say why a stub never arrived, and reports up to 30 s after the session opens, after a subagent's one spawn-time reading of the report.
Not a goal
What changed (motivation → approach → change)
Only the session's own pi process knows what it registered, so it now says so. During
session_startthe gate extension writes a small receipt into the session's scratch window, bound to the session nonce, exclusive-create, mode 0600. The host reads and removes it right aftersession/neworsession/loadand before the first prompt, with a non-blocking open of a regular file only, since other agents of the session tree can write that window.none/unreadable/malformed/unsealedmcp.json)mcp_json/mcp_json_unreadable/refused/replacedThe unknown case stays off the failed bucket on purpose: the subagent spawn notice reads that bucket as "do not retry", and the task and webhook notices print it as "unusable". Rows past the bucket's cap are dropped, as the mount check's are. A load-to-new retry clears the previous child's receipt before it republishes the handoff.
Code: in
agent_sdk/gate_extensions/pi/kiro_crew_tool_gate.ts,readMcpHandoffreturns a status beside the servers andsession_startwrites the receipt (PI_GATE_EXTENSION_SHA256re-pinned);acp/pi_mcp_registration.pyvalidates and applies it;harness/pi.pypointsKIROCREW_PI_MCP_RECEIPTat a nonce-named file in the allocated scratch window, dropping an inherited value;client_start._initialize_sessioncalls it before discarding the handoff;client_mcp_arrayclears it on retry;harness/base.pydeclareswork_scratch_diron theProcessSessionprotocol.docs/system-specs/modules/harness-parity.mddocuments the receipt and the three outcomes.Backwards compatibility
Compatible: no pi session is refused and the MCP report payload gains no key; a session whose receipt is missing opens exactly as before. The receipt's one writer is the sealed gate extension in this diff, verified by digest at every spawn. Sessions with no handed-off servers, and every non-pi harness, are unaffected.
Removes nothing: the change adds a receipt and failed rows for servers pi confirmed it did not register; no field, path or behaviour is taken away.
Tests
test/test_pi_mcp_registration.py(new): a full receipt records nothing and sends no request; each per-server cause and each handoff status gives failed rows with its own reason (no handoff reason mentionsmcp.json); invalid shapes (wrong version, wrong types, unknown status or cause, unhashable values, a name both registered and unregistered), unparseable or too-deeply-nested JSON, another nonce, no receipt and no scratch window each give no failed row and a warning naming the cause, and the receipt is removed; a FIFO at the receipt path is not read and does not block; a confirmed refusal reaches the subagent spawn notice; a load-to-new retry deletes the old receipt; the spawn env names the allocated scratch window, not an inherited value;_initialize_sessionopens with or without a receipt and drops the handoff either way.test/test_pi_gate_extension_mcp.py: the real.tsunder Node writesloadedwith the server registered for a clean handoff,mcp_json/mcp_json_unreadablefor a shadowed or brokenmcp.json,refusedwhen pi holds nothing under the name,unsealedfor another key or nonce,malformedfor a non-handoff file.test/test_pi_real_adapter.py:test_real_pi_confirms_its_mcp_registration_before_session_new_returnsdrives the pinned pi-acp and pi through Crew's own launch and asserts the receipt is already there,loadedwith the probe server registered, whensession/newreturns.verify_registrationcall taken out of_initialize_session,test_session_start_without_a_receipt_opens_and_reports_before_the_first_promptgoes red; with the non-blocking open and the type guards taken out, the FIFO test times out and the unhashable-value case raisesTypeError.Local: black, isort, flake8, mypy (changed modules), subprocess-encoding, comment-history, brand, harness-parity, feature-map, file-line cap, docs-lint, flake-pattern ratchet (66 passed), semgrep 1.78.0 on the diff (0 findings). 1635 passed, 2 skipped across the pi, ACP harness, MCP report, subagent report and client-binding suites.
Manual verification
Ran the Real Adapter lane's pi tests locally against the pinned pair installed from
test/real_adapters/package-lock.json(pi-acp 0.0.34, pi 1.4.0), withPI_ACP_BINandPI_ACP_PI_COMMANDset asci.ymldoes: 8 passed, including the new receipt check, the MCP handoff mount and the gated tool calls (21 with the Node-driven extension tests).Screenshots / video
N/A — no frontend change: the MCP card already renders a failed row with its reason.
Related Issues
Closes #19774
Builds on #22400 by @leonlaiyc.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.