GeezerVison

- New CallOptions key cancel_on_abandon (default true): abandoning a request
  (timeout or caller cancellation) sends notifications/cancelled unless the
  caller opted out or the request carries resumption hints
- Bound the two shielded cancellation-path writes with a 5s deadline so a
  wedged transport write cannot hang shutdown or a cancelled caller
- Capitalize the connection-closed fan-out message ("Connection closed")
- Pin the server-seat timeout contract in the interaction suite: a timed-out
  server-initiated request is followed by notifications/cancelled

A raising notification handler ran as a bare task in the dispatcher's task
group, so its exception cancelled the read loop and every in-flight request.
Wrap spawned handlers in the same containment boundary progress callbacks
already have: log the failure and keep the connection serving.

Transports yield Exception items on the read stream for connection faults
and parse errors; the dispatcher debug-logged and dropped them. An optional
observer now receives them (awaited in the read loop, contained so a raising
observer costs the item, not the connection). Unset keeps the old behavior.

TransportT now defaults to TransportContext (PEP 696, same pattern as
shared/context.py), so omitting transport_builder no longer needs a
dedicated overload to pin the type parameter.

ClientSession keeps its public surface (constructor, typed methods, manual
initialize, context-manager lifecycle) but now owns a JSONRPCDispatcher
instead of inheriting the v1 BaseSession receive loop. Server-initiated
requests are answered through the existing callbacks via the closed-union
parse; notifications validate-or-drop and tee to message_handler; transport
exceptions reach message_handler through the dispatcher's stream-exception
observer. A from_dispatcher constructor accepts a pre-built dispatcher for
in-process embedding.

mcp.shared.session shrinks to the surviving names: the ProgressFnT re-export
and a typing-only RequestResponder stub for MessageHandlerFnT annotations.

Behavior changes (deliberate, to be covered in the migration guide):
- request ids count from 1; the progress token follows
- timeouts use the dispatcher error text and send notifications/cancelled,
  so a timed-out server handler is interrupted instead of running on
- responses with unknown ids are ignored per spec instead of surfacing a
  RuntimeError to message_handler
- a raising request callback is answered with code 0 and the exception text
- notification callbacks run concurrently (no completion-before-response)

Three interaction-suite divergence entries are resolved and deleted, and the
server-to-client cancellation requirement is now pinned by a passing test.

Adds tests for ServerMessageMetadata routing, related-request-id
notifications, and params-absent inbound requests over direct dispatch,
plus the migration-guide entry for the ClientSession dispatcher swap.

Transport teardown closes the standalone stream's send side first, so a
writer parked in receive() ends on a clean end-of-stream; but when teardown
lands while the writer is between dequeues, the next receive() raises
ClosedResourceError, which fell into the catch-all and logged a traceback
at ERROR level for a routine disconnect. Catch it and end quietly. A new
test pins the close ordering that keeps the parked path clean.

Replaces the from_dispatcher classmethod: read_stream/write_stream become
optional and dispatcher is a keyword-only alternative, with mutual
exclusion validated at construction. Drops the __new__-based alternate
constructor and its shared state-init helper.

Covers MCPError.from_jsonrpc_error and the context-stream sync close()
methods, whose only exercisers died with BaseSession and its tests, and
restructures three test handler arms that could never take their false
branch.

- Bound the timeout-path courtesy cancel like the other abandon writes and
  extract a single _final_write policy: 5s for courtesy cancels, 1s for
  shutdown responses so closing a session stays fast on a wedged transport
- Answer shutdown-interrupted requests with CONNECTION_CLOSED and retire the
  REQUEST_CANCELLED constant (-32002 collides with resource-not-found)
- Key the peer-cancel error response on cancelled_caught so a cancel landing
  after the handler finished cannot produce a second answer for the same id
- Decide outbound metadata and cancel-on-abandon suppression in one place:
  only resumption hints that actually reach the transport suppress the
  courtesy cancel
- Never send notifications/cancelled for a request whose write never completed
- Identity-guard the in-flight pop so a finished handler cannot evict a newer
  entry that reused its request id
- Map request-write stream failures to MCPError(CONNECTION_CLOSED); warn when
  a bounded final write gives up; mark the Dispatcher lifecycle provisional

- Unwind the entered task group when __aenter__ is cancelled while the
  dispatcher is starting, instead of abandoning its cancel scope
- Deliver transport-level exceptions to message_handler concurrently and
  contained, like notifications, so a handler that awaits session I/O no
  longer deadlocks the read loop
- Route related_request_id=0 correctly in send_notification (ids are opaque)
- Document the dispatcher= constructor path in send_request's contract

- Add an interaction test proving a timed-out initialize sends no
  notifications/cancelled, and drop the stale deferred rationale for the
  initialize-not-cancellable requirement
- Record null-id error-response drops in the requirements manifest and
  describe the cancelled-request error response as applying to both seats
- Record wire messages only after the inner send succeeds, so a failed or
  cancelled write is not logged as sent
- Bound the remaining indefinite waits, refresh comments stale since the
  courtesy-cancel change, and assert the issue-88 timeout by error code
- Rewrite the suite README's concurrency section for the dispatcher model

Drive the between-dequeues teardown path directly through the transport's
ASGI entry point with a gated send, so the ClosedResourceError arm is
covered by a real test and no longer needs its coverage pragma. The e2e
teardown test's docstring now claims only what its assertion proves.

Cut the comment and docstring volume roughly in half: single-sentence
docstring summaries, Raises sections kept but shortened, inline narration
replaced by one-line statements of the non-inferable constraint, and
development-artifact comments removed. No code changes.

ServerMessageMetadata.related_request_id exists for the server's
streamable-HTTP transport to route outbound messages onto the originating
request's SSE stream. No client transport has ever serialized it, so
ClientSession's related_request_id parameter and ServerMessageMetadata
acceptance were dead inheritance from the shared v1 BaseSession.

- send_notification loses its related_request_id parameter
- send_request's metadata narrows to ClientMessageMetadata | None
  (resumption hints, the live part)
- the isinstance(dispatcher) downcasts those parameters forced are gone

Progress and response correlation (progressToken in params, JSON-RPC id)
are payload-level mechanisms and are unaffected.

RequestContext[ClientSession] was the only instantiation of the generic
left in the tree (the server seat has ServerRequestContext), so the
public ClientRequestContext alias becomes the real dataclass and the
private mcp.shared._context module is deleted. request_id is now always
populated: the client only builds a context for inbound requests, and
ping is answered before any context exists.

Server-initiated sampling/elicitation/roots requests over a ClientSession
built with dispatcher=DirectDispatcher failed before the callback ran:
the session requires a populated request id and direct dispatch carried
none. DirectDispatcher now assigns per-instance monotonic ids to inbound
requests (notifications keep None, which is how middleware distinguishes
them). Adds a non-ping direct-dispatch test and bounds the indefinite
awaits in the existing dispatcher= tests.

send_raw_request raised RuntimeError both before run() and after the
transport closed, contradicting the documented contract that connection
loss surfaces as MCPError(CONNECTION_CLOSED). A closed flag now separates
the two states: RuntimeError remains for use before run(), and a request
after EOF gets the same CONNECTION_CLOSED error the in-flight waiters
receive.

The previous canary (a raising message_handler) could never fire: correct
code drops unknown-id responses before any handler, and regressed code's
delivery paths contain handler exceptions. Collect surfaced messages
instead and assert only a control notification arrives; verified against
a simulation of the v1 surface-as-RuntimeError behavior.

Cut the ClientSession section by about a third: merged single-concern
bullets (stray responses; the timeout exemptions), dropped rationale
padding, reframed the shutdown bullet as new-versus-v1 (v1 never answered
at shutdown), and removed the REQUEST_CANCELLED bullet entirely - the
constant never existed in v1, so it has no place in a v1-to-v2 guide.

run() entered both streams inside its own task group, so at teardown the
write stream closed before in-flight handlers sent their final answers:
the shutdown CONNECTION_CLOSED response was deterministically dropped on
the EOF path and raced the close on the cancel path. The write stream's
scope now wraps the task group, so scope exits order the join strictly
before the close and teardown writes always land. The shutdown-delivery
test becomes a real memory-stream pin, and the wedged-shutdown test's
synthetic stream is replaced by a plain unread one.

Two rendezvous tests: three concurrent outbound tool calls proven
simultaneously in flight and resolved out of order to their own callers,
and two overlapping server-initiated sampling requests serviced
concurrently by the client's callbacks (the v1 receive loop serialized
these). Also note in the migration guide that delivery concurrency is
unbounded.

- Rename _SHIELDED_WRITE_TIMEOUT to _ABANDON_WRITE_TIMEOUT; the
  timed-out arm passes it unshielded, so the old name lied there
- Document that on_stream_exception is awaited inline in the read loop
- Note in run()'s docstring that the dispatcher is single-shot
- Import ProgressFnT from mcp.shared.dispatcher (its home) instead of
  the mcp.shared.session compat shim
- Migration guide: scope the optional-fields section to
  ServerRequestContext, and correct the null-id bullet (v1 surfaced
  the transport's ValidationError, not an MCPError)

Collapse 12 dense bullets to 6: keep BaseSession removal, the new
concurrency model, pre-enter/post-close error contracts, the raising-
callback code change, the removed metadata kwargs, and the
ClientRequestContext rename. Drop ids-from-1, the courtesy-cancel
exemption taxonomy, the (incorrect) resumption-hints-from-callbacks
bullet, the shutdown-CONNECTION_CLOSED detail, and the stray-response
handling - these are feature/internals trivia, not migration steps.

Also correct the protocol:error:null-id divergence note in the
requirements manifest: v1.x had a non-nullable JSONRPCError.id, so a
null-id error response failed transport validation and the
ValidationError reached message_handler as an exception. The note
previously described the v2-prerelease BaseSession's MCPError path
(PR #2056) as v1 behavior.

DirectDispatcher now mirrors JSONRPCDispatcher's lifecycle so the
public ClientSession(dispatcher=...) path honors the documented
contracts: send_raw_request raises RuntimeError before run() and
MCPError(CONNECTION_CLOSED) after close, inbound dispatch to a closed
side fails the peer's request instead of serving the exited session's
callbacks, and the ready-wait sits inside fail_after so a request
timeout bounds waiting on a peer whose run() never started.

ClientSession._on_notify self-contains a raising logging_callback /
message_handler (matching ServerRunner._on_notify) so a callback that
throws over DirectDispatcher costs only that delivery instead of
failing the in-process peer's notify() call.

JSONRPCDispatcher.notify is now fire-and-forget all the way: a post-
close send or a write onto a torn-down transport drops the
notification with a debug log instead of leaking raw anyio
ClosedResourceError/BrokenResourceError. DirectDispatcher.notify
matches.

JSONRPCDispatcher.send_raw_request: a builtin TimeoutError raised by a
custom transport's bounded send() now propagates raw instead of being
mislabelled REQUEST_TIMEOUT (the timeout-conversion arm only fires
once the response fail_after has armed). request_write_started is set
before the write so a delivered-but-cancelled request still triggers
the courtesy notifications/cancelled, and _handle_request skips the
shutdown CONNECTION_CLOSED answer once an answer write has started,
preferring possibly-zero responses over possibly-two for one id.

request_read_timeout_seconds=0.0 is now honored as fail-immediately on
both ClientSession.send_request and ServerSession.send_request (was
silently treated as unset via or-fallback). None remains the only
sentinel that defers to the session-level timeout.

The new post-close DirectDispatcher test asserts after running_pair's
cancelled task-group join, and several of the new jsonrpc_dispatcher
race tests have a 1-tick join fast path - both shapes hit
python/cpython#106749 on 3.11 (coro.throw() drops the outer-frame
'call' trace events and desyncs CTracer until the next normal resume,
roaming onto unrelated tests on the same xdist worker). Add the
established resync_tracer() heal at each new cancel site.

run() ends via its own internal cancelled task-group join; on 3.11 a
direct `await dispatcher.run(...)` (not via tg.start) loses tracing
on the lines that follow. Heal at the exit, matching the pattern in
ClientSession.__aexit__.

felixweinberger left a comment •

edited

Loading

Uh oh!

There was an error while loading. Please reload this page.