Skip to content

docs(rfc): remote work recovery contract for App MCP servers - #21975

Open
kyleseaman wants to merge 2 commits into
mainfrom
docs/rfc-remote-work-recovery
Open

kyleseaman wants to merge 2 commits into
mainfrom
docs/rfc-remote-work-recovery

Conversation

@kyleseaman

Copy link
Copy Markdown
Contributor

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

  • Any implementation. This PR adds a document and an index row; no code changes.
  • Accepting the RFC. It lands as draft; a maintainer records acceptance later.
  • Depending on feat: add Coder remote session environments #19833. The RFC holds on main as it stands; the sentences that read the stack say so.
  • Keeping the agent's own turn alive across a restart, recovering JobSDK runs, or MCP's stateless 2026-07-28 core beyond the Tasks extension.

What changed (motivation → approach → change)

Adds docs/request-for-change/rfc-remote-work-recovery.md (status draft) and its row in the RFC index docs/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-25 spec, and the io.modelcontextprotocol/tasks extension that replaced them in 2026-07-28.

What an App's MCP server must provide What Kiro Crew does
Declare Tasks (either form) on tools that start long work Acts as the task requestor in its MCP gateway, so no engine needs Tasks support
Durable task ids, kept where the work lives Persists one record per task, against the session that started it, before the call leaves the gateway
Bind tasks to the caller (principal_id, session_key), not the connection Polls after a reconnect as that same session
The five task states and a readable status message Shows still running / finished / failed / cancelled / gone on return
Input requests as elicitations Shows an input card that only the starting session and user can answer
Optional kirocrew.idempotency-key dedupe Never re-sends a call it did not see finish unless the server declared the key; holds a repeat for the user

A 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/main at 310ad48b5f (symbols and paths named in the RFC's §2.2), and the Session Environments statements against the #19833 branch at aff2e76354. The MCP Tasks statements were checked against the published 2025-11-25 Tasks page, the 2026-07-28 changelog, 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

  • 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

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 18, 2026 22:45
@kyleseaman
kyleseaman requested a review from CrysisDeu October 18, 2026 22:45
@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a792626b84b4968d5af3f5211b4e6a34d7b61c73 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 Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision a792626b84b4968d5af3f5211b4e6a34d7b61c73 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 18, 2026
@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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

  • §4.1 item 7 introduces kirocrew.idempotency-key as a vendor _meta key. That becomes a one-way door once a third-party App adopts it. Decide whether to propose it upstream before the RFC moves to accepted, not after.
  • §4.5 has the reconciler re-send an unacknowledged call whenever the server declares the key. That is only safe if the server keeps the key at least as long as the record's TTL. Make that retention window an explicit part of the contract.

[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 .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 Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a792626

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

@github-actions

github-actions Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a792626

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

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

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Disposition for the Design lane's PASS punchline (the idempotency-key name and upstreaming): needs-a-decision.

Agreed that App authors will build against the key, so its name must be settled before this draft moves to accepted.
The RFC already records it as open question 2 (section 9): kirocrew.idempotency-key under capabilities.experimental, following the kirocrew.caller-identity precedent, and whether to propose a standard key upstream to MCP.
Section 5 makes Phase 4 (the key and the repeat guard) blocked on that question, so nothing builds against the name before a maintainer rules.
No change to the document: it stays draft until a maintainer records the ruling here or in the RFC.

@kyleseaman this is the maintainer ruling the lane asks for: keep the vendor key until MCP defines one, and should we propose one upstream?

@kyleseaman
kyleseaman force-pushed the docs/rfc-remote-work-recovery branch from c311a6b to 652d931 Compare October 18, 2026 23:30
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/ (rfc-agent-started-turns.md, rfc-webhook-subscriptions.md) since this head went green (310ad48 -> 518b36d); CI re-running. The same push fills the RFC's doc-pr front-matter field with 21975.

@kyleseaman
kyleseaman force-pushed the docs/rfc-remote-work-recovery branch from 652d931 to f498a18 Compare October 18, 2026 23:52
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Disposition for the Design lane's PASS punchline (make the engine-timeout probe a gate): fixed in f498a18.

Legitimate: section 4.2 step 4 holds the engine's tools/call open until the task ends, which only works while kiro-cli and KAS wait longer than the task runs, yet Phase 2 was blocked on Phase 0(a) alone.
Phase 2's Blocked-on column now names Phase 0(b), so the gateway-as-requestor work cannot start before the engine's wait is measured and recorded.
Section 4.2 step 4 now says that if the engine gives up first, Phase 2 ships the early answer from section 9 Q3, keeps the task on its record, and the result is delivered through the return view instead of holding the call.
Phase 2's exit criteria now test that a call outlasting the measured wait gets the early answer and its task stays recorded.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

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.

Agreed on the fact: mcp_gateway.stub_servers defaults to empty on main (config/integration_sections.py), and recovery needs a stub, so with today's default no App server is covered.
The RFC states this in section 4.9 (servers that cannot be recovered) and leaves the choice open as section 9 Q1: let an App manifest declare durable work so its server is routed by default, or keep routing the user's per-server choice with the section 4.9 nudge.
That is a product default a maintainer owns, so the document stays draft and does not pick one; nothing ships with the flag on before Phase 2, which is itself off by default.

@kyleseaman ruling requested on section 9 Q1: should an App manifest be able to opt its server into routing by default for durable work?

@kyleseaman
kyleseaman force-pushed the docs/rfc-remote-work-recovery branch from f498a18 to 3b9461b Compare October 19, 2026 00:56
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/ (rfc-resumable-subagent-sessions.md) since this head went green (518b36d -> b4efd2d); CI re-running. The prior head f498a18 had 86 pass / 16 skip / 0 fail with only PR Readiness still re-checking.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 19, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-remote-work-recovery branch from 3b9461b to a24ed70 Compare October 19, 2026 01:52
@kyleseaman

Copy link
Copy Markdown
Contributor Author

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 19, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

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.

Section 4.2 step 4 says the hold only works while the engine waits longer than the task runs, that Phase 0(b) measures how long kiro-cli and KAS wait, and that Phase 2 does not start until that verdict is recorded.
The section 5 phase table's Phase 2 row is blocked on Phase 0(a), Phase 0(b), Phase 1, and its exit criteria test that a call outlasting the measured wait gets the early answer and its task stays recorded for Phase 3.
If the engine gives up first, Phase 2 ships the section 9 Q3 early answer instead of holding the call, so acceptance cannot carry an ungated hold.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 19, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Hold at a24ed70678ad9b428bf4067855f92c2d27625355: it conflicts with main again.

docs/request-for-change/README.md changed on main after the 01:52 union rebase, and git merge-tree against afed43d2 reports a content conflict in that file. Rebase onto main and keep both index rows, as last time. A rebase is a new head, so it needs another review.

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)

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 3, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-remote-work-recovery branch from 2b4aba5 to dacd893 Compare November 3, 2026 22:54
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 3, 2026
iamwhatever
iamwhatever previously approved these changes Nov 4, 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.

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

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_required into 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_servers is 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.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-remote-work-recovery branch from dacd893 to aed8637 Compare November 6, 2026 01:53
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision labels Nov 6, 2026
iamwhatever
iamwhatever previously approved these changes Nov 6, 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.

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
iamwhatever previously approved these changes Nov 7, 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.

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

Copy link
Copy Markdown
Contributor

@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!

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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: cancel_in_flight_for_stub, _owner_liveness_sweeper, HAZARD_UNATTRIBUTABLE_NOTIFICATION, _CREW_HIDDEN_LEAVES, the 2024-11-05 version in mcp_shared_dispatch.py, MCP_CLIENT_PROTOCOL_VERSION = "2025-06-18" and the 20 s app_call timeout. No open PR duplicates this RFC. Open questions §9 Q1 and Q2 are left for the maintainer decision.

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:

kyleseaman and others added 2 commits November 10, 2026 06:15
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.
…23635

Main's db60123 (#23635) made the broker's eager send_initialize offer MCP_CLIENT_PROTOCOL_VERSION (2025-06-18, defined in mcp_discovery_probe_state.py) with one downgrade retry, so the RFC's and the README row's hard-codes-2024-11-05 claim is no longer true.
@iamwhatever

Copy link
Copy Markdown
Contributor

Opus 5.5 BLOCKING finding on e5976b615 (send_initialize fact not true at the 310ad48b5f audit point): fixed in a792626b8. The finding offered two fixes, and this takes the second one. The RFC sentence (line 96) and the matching README index clause now say the MCP_CLIENT_PROTOCOL_VERSION offer and the downgrade_protocol_version retry were read at db60123ef7, where #23635 added them. That is the same way the RFC already marks its Session Environments facts as read at aff2e76354. The rest of the audit stamp is unchanged.

@iamwhatever

Copy link
Copy Markdown
Contributor

Green on a792626b8: CI and PR Readiness pass, and Opus, GPT and Design report no blocking findings. Since the last approval (3295392) this is a rebase onto main plus one fix for the Opus finding: the send_initialize sentence and its README clause now say they were read at db60123ef7, where #23635 added that behaviour. The RFC stays draft. Ready for a maintainer review.

This branch has not been deployed

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

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants