chore: import upstream snapshot with attribution

examples/stories/mrtr/README.md

@@ -0,0 +1,79 @@
+# mrtr
+
+Multi-round tool result: on the 2026-07-28 protocol a tool that needs user
+input mid-call **returns** `resultType: "input_required"` with embedded
+`inputRequests` and an opaque `requestState`, instead of pushing a
+server-to-client request. The client fulfils the embedded requests and retries the
+original `tools/call` carrying `inputResponses` and the echoed `requestState`.
+The story shows both the `Client` auto-loop (one `await call_tool`, callbacks
+fired transparently) and a manual `client.session` loop (the persistable
+form). Because `requestState` round-trips through the client, it also shows
+the security surface that protects it: `MCPServer` seals state by default
+under a process-local key, handlers keep writing plaintext, and the wire only
+ever carries an opaque token. The manual loop tampers with the sealed token to
+show what a forged echo gets back.
+
+## Run it
+
+```bash
+# HTTP: the client self-hosts the server on a free port, runs, then tears it
+# down (the InputRequiredResult round-trip is 2026-era only)
+uv run python -m stories.mrtr.client --http
+# same, against the lowlevel-API server variant
+uv run python -m stories.mrtr.client --http --server server_lowlevel
+```
+
+## What to look at
+
+- `server.py` `build_server`: no security configuration at all. The default
+  seals under a key generated at process start, which is right for a
+  single-process server like this one; a fleet (multi-worker or load-balanced)
+  shares keys with `request_state_security=RequestStateSecurity(keys=[...])`
+  so any instance can verify state another minted.
+- `server.py` `deploy`: handlers stay plaintext. The first round returns
+  `InputRequiredResult(input_requests={...},
+  request_state="awaiting-confirm")` and the retry asserts
+  `ctx.request_state == "awaiting-confirm"`. The tool never touches the
+  crypto; the boundary seals on the way out and unseals the echo on the way
+  back in.
+- `client.py` `main`: the auto-loop is invisible at the call site:
+  `Client(target, mode=mode, elicitation_callback=on_elicit)` then
+  `await client.call_tool("deploy", ...)`. The same `on_elicit` callback the
+  legacy push path uses is dispatched for each embedded `inputRequests` entry.
+- `client.py` manual block: `client.session.call_tool(...,
+  allow_input_required=True)` returns the raw `InputRequiredResult` so
+  `request_state` can be persisted between rounds. The wire value is an opaque
+  sealed token, **not** the string the server code wrote. The client asserts
+  exactly that, then retries with one character of the token flipped and gets
+  the single frozen error every verification failure maps to: `-32602`,
+  `"Invalid or expired requestState"`, `{"reason": "invalid_request_state"}`.
+  The specific reason (tampered tag, expiry, wrong request, wrong principal)
+  appears only in the server's log, never on the wire. The untampered token
+  then completes the round normally.
+- `server_lowlevel.py`: the lowlevel tier doesn't seal by default; the same
+  enforcement is one appended middleware:
+  `server.middleware.append(RequestStateBoundary(RequestStateSecurity.ephemeral(),
+  default_audience=server.name))`.
+
+## Caveats
+
+- **Loop bound.** The auto-loop gives up after `input_required_max_rounds`
+  (default 10) with `InputRequiredRoundsExceededError`; raise it on the
+  `Client` ctor or drop to the manual loop.
+- **The default key dies with the process.** It is generated at startup and
+  held only in memory, so a server restart (or a retry landing on a different
+  instance) invalidates in-flight rounds: the client gets the same frozen
+  rejection and must start the flow over. Use
+  `RequestStateSecurity(keys=[...])` when state must survive either.
+
+## Spec
+
+[Input required tool results (server features)](https://modelcontextprotocol.io/specification/draft/server/tools#input-required-tool-results),
+[Multi-round-trip requests (security patterns)](https://modelcontextprotocol.io/specification/draft/basic/patterns/mrtr)
+
+## See also
+
+`legacy_elicitation/` and `sampling/`: the handshake-era push equivalents this
+mechanism replaces on the 2026 protocol. `refund_desk/`: resolver DI at the
+MCPServer tier: the questions a tool can declare instead of pushing by hand
+(its elicited answers ride in the same sealed `requestState`).