[v2] ClientSession runs on JSONRPCDispatcher; BaseSession removed

[maxisbey]

V2 client receive path: Transport -> JSONRPCDispatcher -> ClientSession callbacks, replacing the BaseSession receive loop. Companion to #2710, which did the same for the server seat; BaseSession is now deleted.

Motivation and Context

ClientSession was the last consumer of the v1 BaseSession engine. Moving it onto the dispatcher unifies both seats on one receive path and fixes the v1 client's structural problems: server-initiated requests were handled inline in the receive loop (a slow sampling callback blocked everything, a callback that sent a request deadlocked, and peer cancellation was unactionable), and a raising notification handler could take down the connection.

ClientSession's public surface is unchanged: same constructor, same typed methods, manual initialize(), same context-manager lifecycle. A new keyword-only dispatcher= constructor argument accepts a pre-built dispatcher instead of the stream pair (e.g. DirectDispatcher for in-process embedding).

What changed

• CallOptions.cancel_on_abandon + suppression: abandoning a request (timeout or caller cancellation) sends a courtesy notifications/cancelled, unless the caller opted out (initialize, which the spec forbids cancelling) or the request carries resumption hints (the peer's work must survive for the resume)
• The two shielded cancellation-path writes are bounded (5s), so a wedged transport write can no longer hang shutdown or a cancelled caller
• Spawned notification handlers and the new on_stream_exception observer are contained at the dispatcher: a raising handler costs itself, never the connection (matching the TypeScript/C#/Go engines)
• ClientSession internals rewritten over the dispatcher; mcp.shared.session shrinks to a compatibility module (ProgressFnT re-export, typing-only RequestResponder stub for MessageHandlerFnT annotations)
• The dispatcher constructor overloads collapsed via a defaulted TypeVar (PEP 696)
• Drive-by fix: the standalone SSE writer no longer logs an ERROR traceback when transport teardown closes its stream mid-listen

Parity bar

The transport-parametrized interaction suite passes. Three recorded divergences are now resolved and deleted from the requirements manifest (protocol:timeout:sends-cancellation, protocol:cancel:late-response-ignored, protocol:cancel:server-to-client), and the server-to-client cancellation requirement is pinned by a new test passing over all three transports.

Breaking Changes

Documented in docs/migration.md (one grouped entry):

• Request ids count from 1 (previously 0); progress tokens follow
• Timeout error text is now Request 'tools/call' timed out, and a timed-out or abandoned request sends notifications/cancelled, interrupting the server handler
• Server-initiated requests run concurrently; a server's cancellation now actually interrupts the client callback
• Notification callbacks are concurrent (no completion-before-response guarantee)
• Responses with unknown ids are ignored per spec instead of surfacing a RuntimeError to message_handler
• Unknown inbound methods are answered with METHOD_NOT_FOUND (carrying the method in data), completing Fix unknown-method error code and add a protocol version registry #2836's contract on the client seat
• A raising request callback is answered with code=0 and the exception text (previously flattened to INVALID_PARAMS)
• send_request before entering the context manager raises RuntimeError immediately

Fixes #2489, #2507, #2610, #2673. Supersedes #2490.

How Has This Been Tested?

Full suite (1741 tests) including the interaction suite over in-memory, SSE, and streamable HTTP; 100% branch coverage held on all changed files. New tests: courtesy-cancel wire pins and suppression, wedged-transport shutdown bound (trio virtual clock), notification-handler containment, stream-exception observer, the dispatcher= constructor over direct dispatch, server-seat timeout cancellation, abandoned-server-request cancellation, standalone-stream teardown ordering.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

_{AI Disclaimer}