Skip to content

Instantly share code, notes, and snippets.

@felixweinberger
Created May 1, 2026 13:52
Show Gist options
  • Select an option

  • Save felixweinberger/9e3357c04224d411ab3b20b227fd820c to your computer and use it in GitHub Desktop.

Select an option

Save felixweinberger/9e3357c04224d411ab3b20b227fd820c to your computer and use it in GitHub Desktop.
TS SDK R0-R4 review guide — Protocol decomposition + handleHttp

R0-R4 review guide — Protocol decomposition + per-request HTTP entry

TLDR for reviewers. Full RFC: 2026-04-30-rfc-minimal-additive-approach.md.

What this chain does

Decomposes Protocol internally into a private Dispatcher (stateless: handler registry + dispatch) and a private StreamDriver (per-connection: id correlation, timeouts, abort), then adds a per-request HTTP entry point (handleHttp) that calls Dispatcher directly without ever touching StreamDriver. McpServer/Client/Server class hierarchy unchanged; they keep extending Protocol and inherit the new dispatch() method.

Two doors after this lands:

  • mcp.connect(transport) — pipe transports (stdio, ws, in-memory). Unchanged behavior.
  • handleHttp(mcp, {session?, backchannel?}) — per-request HTTP. New.

Why R0 deletes tasks first

The 2025-11 experimental tasks API is woven into Protocol._onrequest/request via processInbound*/processOutbound* interception. Preserving that through the decomposition required ~100 LOC of _tasksMiddleware glue, an onrequestsend tap on StreamDriver, and microtask-timing hacks — all to keep an experimental API that SEP-2663 is replacing with a simpler server-directed model anyway.

R0 deletes the interception (no BC owed; it was always experimental). Integration tests that exercise task behavior are describe.skipped with // TODO(F3) markers. Storage interfaces (InMemoryTaskStore etc.) stay. F3 brings tasksPlugin() back via the use() middleware seam — ~150 LOC, no Protocol coupling.

This makes R2 a clean ~800-line shrink instead of "shrink plus tasks-BC mess."

Per-PR

main → R0 → R1 → R2 → R3 → R4
PR What Review focus Gate
R0 Delete experimental tasks interception; skip integration tests What got deleted vs skipped; any orphaned references tests pass (−121 deleted, +101 skipped)
R1 Dispatcher + StreamDriver new files + own unit tests Do these two classes do what they claim, in isolation own tests pass; existing tests unchanged
R2 Protocol composes them; dispatch() public; types move to context.ts The heavy review. Each public method delegates correctly. protocol.ts 1011→393 protocol.test.ts passes unchanged; conformance 40/40
R3 handleHttp (+ internal shttpHandler) + SessionCompat + toNodeHttpHandler + dual-conformance harness + Last-Event-ID session-binding fix New files; the IDOR fix; both conformance targets dual-conformance both 40/40
R4 BackchannelCompat (legacy server→client over SSE for handleHttp); Server.buildContext uses ctx.mcpReq.send Writer lifecycle; the buildContext change drops a capability check (restored in F1) dual-conformance both 40/40; client conformance 289/289

What's NOT in this chain

  • No SEP feature implementations (those are S/F-group, follow-ups)
  • McpServer/Client don't extends Dispatcher (that's optional, deferred)
  • streamableHttp.ts (the existing transport class) is untouched — both entry points coexist
  • Dispatcher/StreamDriver are NOT exported publicly (internal to core)

Dual-conformance

R3 adds a second conformance target so CI runs the suite against both mcp.connect(transport) (existing path) and handleHttp(mcp, {session}) (new path). Both must hit 40/40 server scenarios. This is the behavior-equivalence proof for R2's delegation.

Consumer impact (tasks deletion)

After filtering false positives (mastra's InMemoryTaskStore is Google A2A; cf-agents' hit is CF-generated types), real usage is:

  • mcp-framework (third-party): rolled their own task manager, never imported the SDK interception. R0 doesn't break compile. ~10 LOC adapt (drop params.task branch, emit {resultType:'task'}).
  • inspector / mcp-servers (first-party): the long-running-tool half maps cleanly to F3's tasksPlugin(). The "server polls client's tasks/* for async sampling" half has no SEP-2663 equivalent — that pattern becomes MRTR (S3/F2/F4), not tasks. Those files are rewrites either way.

No old-way compat shim — the parts that would need it are MRTR rewrites, not tasks migrations.

Known follow-ups

  • main's streamableHttp.ts:534 has the same Last-Event-ID cross-session replay issue R3 fixes in shttpHandler — separate security PR.
  • 101 skipped tests are the F3 checklist.
  • R4's Server.buildContext change drops the _clientCapabilities.elicitation check from elicitInput(); F1 (per-request _meta caps) restores it correctly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment