Skip to content

docs(rfc): propose gateway session interoperability - #18294

Closed
twpedersen wants to merge 2 commits into
kirodotdev:mainfrom
twpedersen:docs/rfc-gateway-session-api
Closed

twpedersen wants to merge 2 commits into
kirodotdev:mainfrom
twpedersen:docs/rfc-gateway-session-api

Conversation

@twpedersen

@twpedersen twpedersen commented Oct 9, 2026 •

Copy link
Copy Markdown

Problem / Motivation

Goal: Record a reviewable design for owner-authorized, protocol-neutral Gateway session interoperability before implementation begins.

Trusted local clients currently cannot configure session-scoped MCP requests, answer stateless question cards, correlate turns, or consume minimal session events through one neutral contract. The existing implementation proposal reached code review before the required architectural decision was recorded.

Why it matters

A base-branch decision lets maintainers settle the trust boundary, wire vocabulary, lifecycle ownership, and phased rollout before server, client, or adapter code depends on them. It also lets later implementations reuse the existing Gateway and Python client rather than creating protocol-specific security and lifecycle paths.

Not a goal

  • Add or modify production code.
  • Accept the prototype wire spelling or implementation by documenting it after the fact.
  • Add an ACP adapter, editor integration, or second Gateway client.
  • Merge, close, or modify the existing implementation and source-snapshot pull requests.

What changed (motivation → approach → change)

This PR adds a draft RFC for the T4 architectural change tracked by #16891. It audits the current owner-authentication, question-card, MCP-projection, WebSocket, and Python-client seams; defines a protocol-neutral owner-only contract; and specifies fail-closed authorization, name-only MCP requests, non-blocking provider mutation, atomic question answers, turn correlation, bounded events, and audit-or-deny behavior.

The rollout remains default-off and separates the Gateway contract, Python-client extension, and any later protocol adapter. Phase 1 is Linux-only and requires a separately accepted and implemented managed-execution containment RFC, tracked in #29483. The document gives every selectable harness an explicit projection outcome, treats PR #14999 and PR #7415 as falsification evidence rather than dependencies, and leaves six named design questions for maintainer sign-off.

Backwards compatibility

Compatible: documentation only; no runtime contract or accepted decision changes.

Removes nothing: the PR adds one draft RFC and one index row.

Tests

  • The final bounded post-rebase floor passed on b63cd0c525d39e0e40a0ef0829a5adf7fca483b7 over da44457c102bcb6fc444aa7240bf3d02c9381e8b, including documentation and policy gates, 84 related backend tests, and 13,041 cross-surface frontend tests. The preceding exact-candidate full profile also passed types, lint, Electron, duplication, and memory-store checks.
  • The profile's build-then-analyze bundle-size command reports SettingsPage 1.7 KB over budget. The identical sequence reproduces on clean current main; a standalone clean candidate build passes the bundle and chunk-cycle checks.
  • CI-derived GPT and Opus reviews found no issues on exact final candidate b63cd0c525d39e0e40a0ef0829a5adf7fca483b7. Opus ran as claude-opus-5.5; the GPT lane's served model was not reported.

Manual verification

Confirmed the RFC body remained byte-identical through the rebase, the current-main index was preserved wholesale, and exactly one audit-history sentence and one RFC index row were restored. The branch is one clean documentation commit directly over current main.

Screenshots / video

N/A — documentation-only change with no rendered product surface.

Related Issues

Part of #16891
Prerequisite tracked in #29483

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

Contribution License Agreement

@twpedersen
twpedersen requested review from a team and KiroCrewCaptain as code owners October 9, 2026 01:09
@twpedersen
twpedersen requested a review from bolichen97 October 9, 2026 01:09
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 6924c6946f471e42007dfd0852175ea2e398acbf 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 commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 6924c6946f471e42007dfd0852175ea2e398acbf 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 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 6924c6946f471e42007dfd0852175ea2e398acbf via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

This is a docs-only draft RFC with one index row. It removes nothing and changes no runtime contract, so it does not block.

Notes

[DESIGN-REVIEWED] 6924c69

Description read

[DESCRIPTION-READ] 75a38827bf83a2005ca1d8bfb075b4cff27dfd7599d17a65032685b77fa41b13

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 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 6924c69

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • The RFC's harness table and its "all nine rows" exit criterion leave out Strands, but ACP_BACKEND_STRANDS is in BASELINE_SELECTABLE_BACKENDS on the base tree.

[OPUS-REVIEWED] 6924c69

@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 9, 2026
@twpedersen
twpedersen force-pushed the docs/rfc-gateway-session-api branch from 93b2d8c to 7442359 Compare October 9, 2026 20:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running 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 Oct 9, 2026
@twpedersen
twpedersen force-pushed the docs/rfc-gateway-session-api branch from 7442359 to 003d43f Compare October 9, 2026 21:53
@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 Oct 9, 2026
@twpedersen
twpedersen force-pushed the docs/rfc-gateway-session-api branch from 003d43f to 02a83ff Compare October 9, 2026 23:01
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 9, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 23, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Hi @twpedersen, this RFC now conflicts with main again, only in the index table in docs/request-for-change/README.md. Could you rebase onto current main and keep your row? The document itself had no open findings at 28a883b; the remaining step is the design sign-off.

@twpedersen
twpedersen force-pushed the docs/rfc-gateway-session-api branch from 28a883b to d125ece Compare October 30, 2026 09:26
@twpedersen

Copy link
Copy Markdown
Author

🤖 Rebased onto current main at abb929483d23282c99ec065da6a4f7ba05bf768f, keeping the RFC index row. The published head is d125ece87831fbbba37fa12627bc4d5c1f2c02d5.

The current-base audit also found that Copilot joined BASELINE_SELECTABLE_BACKENDS after the prior audit, so the RFC now adds its explicit fail-closed harness row and updates the harness criteria from eight rows to nine. The settled design is otherwise unchanged.

The full 62-command profile passed before the final unrelated upstream rebase, and bounded exact-head checks passed afterward: docs/static gates, 84 backend tests, and 12,451 frontend tests. Opus 5.5 and the available GPT-family fallback (gpt-5.6-sol; the gpt-6.1-sol profile pin was unavailable) both found no issue on the published candidate. The remaining step is maintainer design sign-off.

@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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 30, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Hi @twpedersen, main moved again and this head (d125ece) now conflicts with it, only in the RFC index table in docs/request-for-change/README.md. Could you rebase onto current main and keep your row? The document itself is unchanged from my last review.

@twpedersen
twpedersen force-pushed the docs/rfc-gateway-session-api branch from d125ece to b63cd0c Compare November 2, 2026 20:27
@twpedersen

Copy link
Copy Markdown
Author

🤖 Rebased onto da44457c102bcb6fc444aa7240bf3d02c9381e8b; the new head is b63cd0c525d39e0e40a0ef0829a5adf7fca483b7. The RFC body is unchanged, and its index row remains preserved exactly once. The final bounded floor passed (84 backend tests and 13,041 frontend tests), and fresh GPT and Opus reviews on the exact head found no blocking issues. I did not merge or enable auto-merge.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 2, 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.

Maintainer decision on this head (b63cd0c): accept the direction of this RFC as a draft. This is a comment, not an approval.

I checked the delta from 28a883b, my last review. The only change to the RFC is the new Copilot row in the harness table, plus the matching "eight" → "nine" updates in the Phase 1 tests and exit criteria. The Copilot row is fail-closed. It has a mirror carrier and whole-server narrowing, but replace/restore return the side-effect-free harness_unsupported until its user-level ~/.copilot MCP sources are disabled or refused before readiness. It becomes a supported row only once a seeded user-level server is shown not to be callable. That is the right posture.

My earlier points (owner predicate vs. authorization, bootstrap row, app-token wording, the env equality oracle, no-wait provider_busy, per-harness narrowing, and the containment-prerequisite scope) are all fixed, as noted in my previous reviews.

Before the status can move from draft to accepted:

  1. The separate managed-execution containment RFC must be accepted and implemented. This RFC already names it as a hard Phase 1 prerequisite.
  2. The six open questions must be settled: the correlation carrier, registration_id spelling, restart posture, title events, conditional restore, and the first consumer.

@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 readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 3, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-gateway-session-api branch from b63cd0c to d074511 Compare November 3, 2026 23:29

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

Request changes at d074511: one deferred item needs a tracking issue.

The RFC itself is sound as a draft: the maintainer accepted its direction at b63cd0c, this head is a byte-identical rebase, every earlier review item is answered, and CI is green.

Blocker

  • The RFC makes a separately accepted and implemented managed-execution containment RFC a hard Phase 1 prerequisite (
    containment RFC must be accepted and implemented first. That decision owns the
    ), and the maintainer's review lists it as the first condition for accepted. No issue or RFC tracks that work, and #16891 does not mention it. Please open one issue for the containment RFC and link it in the PR description (and, if you like, from the RFC's tracking-issues).

Non-blocking, easy to fix in the same push

  • The README index row still says "the eight harnesses" (
    | [rfc-gateway-session-interoperability.md](rfc-gateway-session-interoperability.md) | `draft` | Nothing built. Re-audited 2026-10-23 against `33cdb8f1ee68`: the existing owner predicate and local bootstrap do not distinguish every managed process, the eight harnesses retain distinct MCP projection seams, and the dashboard queue remains separate from provider ownership. Proposes a protocol-neutral local session contract with name-only MCP requests, non-blocking provider mutation, question-card answers, turn correlation, bounded events, default-off rollout, and audit-or-deny. Phase 1 is Linux-only, unavailable on default installs, and blocked until a separate managed-execution containment RFC is accepted and implemented; macOS and Windows fail closed. |
    ); the RFC's table now has nine rows.

— crew-pr-reviewer (r145)

@iamwhatever

Copy link
Copy Markdown
Contributor

Re: review 5764897971 (crew-pr-reviewer r145):

Pushed as 3fd8195, on top of d074511 (no rebase).

Thomas Pedersen and others added 2 commits November 6, 2026 04:31
Define the owner-authenticated, protocol-neutral session contract before implementation. Separate Gateway behavior, the existing Python client, and protocol adapters into independently reviewable phases.
@iamwhatever

Copy link
Copy Markdown
Contributor

Thanks @twpedersen for this RFC! Fork CI hit a wall here: the fork Security Scope lane failed with [scope-floor:unsettled], and its rerun ended in startup_failure. So I opened #31179 with your commits, rebased onto main, from an in-repo branch where CI runs on the larger runners. Your authorship is kept. This PR stays open until the copy merges, and the open review here stays for a maintainer.

@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you @twpedersen for this thorough RFC. Gateway session interoperability is a large direction change that no maintainer has taken up, so we are closing this proposal (and its in-repo copy #31179) for now. If the need comes back, this document is a good place to restart from.

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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants