Add the client-side subscriptions/listen driver (#3047)

examples/stories/subscriptions/README.md

@@ -7,16 +7,16 @@ server publishes with `ctx.notify_resource_updated(uri)` /
 per-stream filtering, subscription-id tagging). Replaces the handshake-era
 `resources/subscribe` + standalone-GET notification path.
 
-The client edits a note it did not subscribe to (silence), edits the one it
-did (a tagged `notifications/resources/updated`), registers a tool at runtime
-(`notifications/tools/list_changed`, then re-lists and calls it), and finally
-stops listening - cancelling the parked request releases the local task, and
-closing the connection ends the stream server-side.
+The client opens the stream with `client.listen(...)`, edits a note it did
+not subscribe to (silence), edits the one it did (a typed `ResourceUpdated`),
+registers a tool at runtime (a typed `ToolsListChanged`, then re-lists and
+calls it), and finally leaves the `async with` block, which ends the
+subscription while the connection lives on.
 
 ## Run it
 
 ```bash
-# HTTP — the client self-hosts the server on a free port, runs, then tears it
+# HTTP: the client self-hosts the server on a free port, runs, then tears it
 # down (subscriptions/listen is 2026-era only)
 uv run python -m stories.subscriptions.client --http
 # same, against the lowlevel-API server variant
@@ -25,17 +25,18 @@ uv run python -m stories.subscriptions.client --http --server server_lowlevel
 
 ## What to look at
 
-- `client.py` — stream frames arrive as ordinary server notifications via the
-  constructor-only `message_handler=`. There is no client-side listen API yet,
-  so opening the stream drops to the `client.session` escape hatch; the request
-  parks for the stream's lifetime. Cancelling it releases the local task; over
-  HTTP the server-side stream ends when the connection closes. Every frame's
-  `_meta["io.modelcontextprotocol/subscriptionId"]` is the listen request's
-  JSON-RPC id.
-- `server.py` — publishing is one `await ctx.notify_*()` line per change; the
+- `client.py`: the whole subscription is one context manager,
+  `async with client.listen(...) as sub`. Entering waits for the server's
+  acknowledgment, so `sub.honored` is already in hand on the first line of the
+  block. Events arrive as typed values from `anext(sub)`; the edit to the
+  unsubscribed note never shows up, because the filter is enforced
+  server-side. Leaving the block ends the subscription (over HTTP the SDK
+  closes that request's response stream) and the session carries on, which the
+  final `search` call proves.
+- `server.py`: publishing is one `await ctx.notify_*()` line per change; the
   filter, the tagging, and the ack ordering are the SDK's job. Publishing with
   no subscribers is a no-op.
-- `server_lowlevel.py` — the same machinery held by hand: an
+- `server_lowlevel.py`: the same machinery held by hand: an
   `InMemorySubscriptionBus`, handlers that `await bus.publish(...)`, and
   `ListenHandler(bus)` passed as `on_subscriptions_listen=`. A multi-replica
   deployment swaps the bus for one backed by its own pub/sub
@@ -51,10 +52,11 @@ uv run python -m stories.subscriptions.client --http --server server_lowlevel
 
 ## Spec
 
-[Subscriptions — basic utilities](https://modelcontextprotocol.io/specification/draft/basic/utilities/subscriptions)
+[Subscriptions, basic utilities](https://modelcontextprotocol.io/specification/draft/basic/utilities/subscriptions)
 
 ## See also
 
 `streaming/` (request-scoped notifications), `events/` (the events extension
-on top of this channel, deferred), and `docs/handlers/subscriptions.md` (the
-narrative version).
+on top of this channel, deferred), and the narrative versions:
+`docs/handlers/subscriptions.md` (server) and `docs/client/subscriptions.md`
+(client).