Repository navigation
docs(rfc): remote work recovery contract for App MCP servers - #21975
kyleseaman wants to merge 2 commits into
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS This is a draft RFC with no code, config or schema changes. Everything it proposes can be revised before anyone accepts it, so no one-way door ships here. Notes
[DESIGN-REVIEWED] a792626 Description read[DESCRIPTION-READ] 74e7a937bd3f8671901984f873aa55046b35f6308b83243f066c9d38c863839e 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: |
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: |
|
Disposition for the Design lane's PASS punchline (the idempotency-key name and upstreaming): needs-a-decision.
@kyleseaman this is the maintainer ruling the lane asks for: keep the vendor key until MCP defines one, and should we propose one upstream? |
c311a6b to
652d931
Compare
652d931 to
f498a18
Compare
|
Disposition for the Design lane's PASS punchline (make the engine-timeout probe a gate): fixed in f498a18.
|
|
Disposition for the Design lane's PASS punchline (App servers are unrouted by default, so recovery covers nothing out of the box until section 9 Q1 is decided): needs-a-decision.
@kyleseaman ruling requested on section 9 Q1: should an App manifest be able to opt its server into routing by default for durable work? |
f498a18 to
3b9461b
Compare
3b9461b to
a24ed70
Compare
|
Rebased to clear a merge conflict: main added the rfc-living-ui row and sentence to docs/request-for-change/README.md. Resolved as a union (main's text kept, this PR's sentence and row re-added); git range-diff shows the PR's own patch unchanged apart from context. Prior head 3b9461b was fully green (87 pass / 16 skip, PR Readiness passed). CI re-running on a24ed70. |
|
Disposition for the Design lane's PASS punchline (keep section 4.2 step 4's hold-the-call gated on Phase 0(b)): rebutted - already in the document at this head, no change needed.
|
|
Hold at
The document itself is in good shape for a draft. The Design punchline at this head is answered correctly: section 4.2 step 4 gates the held call on Phase 0(b), and the Phase 2 row is blocked on it. The open maintainer questions (the idempotency-key name, and routing App servers by default) are recorded in section 9, and the phases that depend on them are blocked until a maintainer rules. The other lanes are clean or skipped, and every check is green. — crew-pr-reviewer (r112) |
2b4aba5 to
dacd893
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
APPROVE at dacd893.
This head is a rebase of the one our r142 approval read. The RFC file is byte-identical to 49e3a1f, and the README change from main is still one audit sentence and one index row, merging cleanly. The protocol-version bullet still matches main. The document lands as draft, the maintainer questions stay open in section 9 with the phases that depend on them blocked, every lane passes, and all checks are green.
— crew-pr-reviewer (r145)
bolichen97
left a comment
There was a problem hiding this comment.
Thanks for the RFC. A design brief on dacd893, for the maintainers' sign-off.
Design brief
- What it does: it sets the contract for work an MCP server starts that must survive a gateway restart or crash. It builds on MCP Tasks. The server returns a durable task id instead of blocking, and keeps the task's state where the work runs. In the MCP gateway, Kiro Crew becomes the task requestor. It stores each task id against the session that started it, polls after a reconnect, turns
input_requiredinto a card the user answers, and shows the result when the user returns. It never re-sends a call whose outcome it did not see, unless the server declared it deduplicates by key. A server without Tasks gets no recovery, and the user is told so. - Pros: it targets a real gap. Today nothing records that a call became long-running work, so a resumed agent can start a deploy or CI run twice. It also fixes two gateway defects the RFC measured: task notifications are dropped as unattributable, and on a pooled backend one session could read another's task by id. It is one contract for host sessions, Session Environments and KAS. It stays off behind
mcp_gateway.tasks.enabled, with no change for servers that do not declare Tasks. The security section is careful: server text is treated as untrusted, arguments are stored only as a digest, the store is masked in agent sandboxes, and a re-send is re-checked against governance. - Cons: it covers only stdio servers behind a gateway stub, and stubs are off by default (
mcp_gateway.stub_serversis empty), so most servers get nothing until routing changes (open question 1). HTTP servers are out of the first version. It depends on Tasks behaviour in two MCP revisions, one of them provisional, and on probe results Phase 0 has not run yet (open question 3). - Tech debt: moderate. It adds a gateway-owned task store, a reconciler, a vendor capability key (
kirocrew.idempotency-key) that may need replacing once MCP defines one, and two protocol revisions to support.
Our pick: sign the direction, and settle open questions 1 and 3 before Phase 1. Routing by default decides whether this helps most users, and the probe verdict decides whether a long task needs an early answer to the engine.
All checks pass on this head. This is a comment only; the sign-off goes to the maintainers.
dacd893 to
aed8637
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
Approve at 131531d.
This head is a rebase of the one our r145 approval read: the RFC file is byte-identical to dacd893, and the README change from main is still one audit sentence and one index row. The document lands as draft, and the maintainer questions stay open in section 9 with the phases that depend on them blocked. @bolichen97's design brief recommends settling open questions 1 and 3 before Phase 1; that is for the acceptance step, not this draft. Every lane passes and all checks are green.
— crew-pr-reviewer (r147)
iamwhatever
left a comment
There was a problem hiding this comment.
Approve at 3295392825ae8443dc0f598a195608e0285113ee.
This head is a rebase of 131531d, which our r147 review approved. The RFC file is byte-identical to that head, and the README change from main is still the one audit sentence and the index row. The document lands as draft, and the maintainer questions stay open in section 9. @bolichen97's design brief asks to settle open questions 1 and 3 before Phase 1; that belongs to the acceptance step, not this draft.
The Design lane's one note (ask how long the engine waits before Phase 1) is already covered: Phase 0(b) measures it and gates Phase 2 (L295). GPT and Opus report no findings. All checks are green and the branch merges cleanly.
— crew-pr-reviewer (r149)
|
@iamwhatever This PR was only rebased onto latest main (one README index conflict resolved by keeping both rows; no change to the RFC itself). New head: 33af5fe. CI and PR Readiness are green on it. The push voided the earlier approval, so please re-approve when you have a moment. Thanks! |
|
This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/). This PR already does that. Review result on head 33af5fe: no blocking findings. The diff is docs only. It adds the new draft RFC, plus one sentence and one index row in docs/request-for-change/README.md. This review checked the RFC's "what happens today" claims against current main, and the cited symbols and values hold there. Examples: Done well: every claim about current behaviour names a file and a symbol, so a reader can check each one. Security is part of the design from the start. The new task store joins the sandbox's hidden leaves, and Phase 1 refuses cross-session task traffic before any persistence exists. Optional:
|
Defines what an App's MCP server must provide (MCP Tasks, durable task ids, caller binding, an optional idempotency key) so Kiro Crew can tell after a disconnect whether remote work finished, failed or needs input, and resume it without running it twice. Raised in review of #19833; does not depend on it.
|
Opus 5.5 BLOCKING finding on |
|
Green on |
Problem / Motivation
Goal: Write down, as a draft RFC, what an App's MCP server must provide so Kiro Crew can tell after a disconnect whether remote work it started finished, failed or needs input, and pick it up without running it twice.
A reviewer of the Session Environments stack (#19833 and the PRs stacked on it) asked this question. Today there is no answer: when the gateway stops, Kiro Crew cancels the tool calls it was routing and keeps no record that a call started remote work. After a restart it cannot say what became of a deploy, a CI run or a batch job an App started, and a resumed agent may simply start it again.
Why it matters
App authors need a contract to build against before Kiro Crew can recover their long-running work, and the reviewer's question needs a written answer. Without one, every App invents its own status tool and the "did it run twice?" risk stays.
Not a goal
draft; a maintainer records acceptance later.JobSDKruns, or MCP's stateless2026-07-28core beyond the Tasks extension.What changed (motivation → approach → change)
Adds
docs/request-for-change/rfc-remote-work-recovery.md(statusdraft) and its row in the RFC indexdocs/request-for-change/README.md.The RFC builds on MCP Tasks rather than inventing a job protocol: a server returns a durable task id instead of blocking, and status and results can be read from a fresh process after a reconnect. It covers both forms: the experimental Tasks of the
2025-11-25spec, and theio.modelcontextprotocol/tasksextension that replaced them in2026-07-28.principal_id,session_key), not the connectionkirocrew.idempotency-keydedupeA server without Tasks gets an explicit "no recovery" notice instead of a guess.
Open questions the RFC leaves for maintainers: routing App servers by default, the idempotency key's name and whether to propose it upstream, two engine probes (protocol version, how long the engine waits on a call), waking a turn on a result, the TTL, HTTP servers, and Kiro Cloud sandboxes.
Backwards compatibility
Compatible: documentation only; no code, config or schema changes.
Removes nothing: the diff adds one new document and one index row; the existing README text is unchanged apart from one appended sentence.
Tests
N/A — documentation only. Docs gates run locally:
scripts/docs-lint.sh,docs_lint.py --test, the brand gate, the comment-history gate, the feature-map gate, the changelog and decisions history gates, the file line cap and the scoped backend tests (test/test_pr_quality_gates.py, 76 passed).Manual verification
Every statement about what Kiro Crew does today was checked against
origin/mainat310ad48b5f(symbols and paths named in the RFC's §2.2), and the Session Environments statements against the #19833 branch ataff2e76354. The MCP Tasks statements were checked against the published2025-11-25Tasks page, the2026-07-28changelog, the Tasks extension overview and SEP-2663.Related Issues
Raised in review of #19833. No tracking issue was opened for this docs PR, at the repository owner's request.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)