Make forwarding tests' Legacy dependency explicit (#6051)

The seven real-backend forwarding tests exercise server-initiated elicitation
and sampling, which MCP 2026-07-28 removes outright: go-sdk's
assertServerInitiatedRequestAllowed refuses them on negotiated protocol version
alone, never consulting client capabilities. They passed only because
newRealTestServer leaves Modern dispatch disabled, so the downstream client
landed on Legacy incidentally.

Pin the downstream client to Legacy explicitly by answering its server/discover
probe with a successful Legacy-only DiscoverResult -- what a Legacy-only server
actually sends -- and assert the pin fired, so deleting it fails loudly instead
of silently relying on a server-side default.

Two of the seven passed vacuously without the pin: a sessionless connect error
satisfied their lenient assertions regardless of the capability advertisement
they exist to exercise. Verified by falsifying their premise -- with the
capability granted they pass unpinned and fail pinned.

Add Modern-path tests recording today's actual behaviour for progress and
logging, so all five dispositions are executable rather than prose, and
document why each is what it is: progress is pinned because dispatchModern
cannot stream, not because Modern lacks the channel.

Refs #5959, #6033, #5743, #6058, #6062.

Author: JAORMX

docs/arch/10-virtual-mcp-architecture.md

@@ -289,6 +289,98 @@ multi-round tool retrieval (MRTR), so the fix is shaped MRTR-first rather than b
 extending the SSE standalone-stream model — see the epic (#5743) and the
 mid-call forwarding section below for the Legacy behaviour this contrasts with.
 
+### Limitation: elicitation and sampling are unavailable to Modern clients
+
+The client edge mirrors the backend edge. The Modern dispatcher
+(`pkg/vmcp/server`'s `dispatchModern`) is single-shot: every result it builds is
+`resultType: "complete"`, and it never emits `"input_required"` — MRTR
+(SEP-2322) is unimplemented on this edge too. When a backend tool issues a
+mid-call server-initiated request during a **Modern** client's `tools/call`,
+there is no client session to forward it to, so the call fails with an explicit
+`-32603` whose message names the refused request (pinned by
+`TestIntegration_Modern_RealBackend_ElicitingToolFailsCleanly`). This is a
+deliberate honest-unsupported error, not a gap left by accident:
+
+**The `-32603` is a documented deviation, not the spec's answer — and the
+spec's answer is unshippable today.** For a client that did NOT declare the
+needed capability in its per-request `clientCapabilities`, SEP-2575 MUSTs a
+`-32021` `MissingRequiredClientCapabilityError` at **HTTP 400**, with
+explicitly execution-time language ("if processing a request requires a
+capability…") — go-sdk's own doc comment on the error type tells handlers to
+return it mid-execution, so the mid-call timing is not the problem. The
+problem is the transport: go-sdk's streamable client treats any non-transient
+4xx (its transient set is only 500/502/503/504/429) as a **connection**
+failure — `checkResponse` → `fail()` → a one-shot, permanent session death —
+so a conformant 400 would tear down the entire client session to punish one
+call. And for a client that DID declare the capability, the 2026-07-28
+vocabulary has no conformant code at all: no "operation not supported", MRTR
+is not a server-advertised capability, and SEP-2322 has no decline mechanism.
+The planned follow-up therefore serves `-32021` (with
+`data.requiredCapabilities`, and a message naming both the capability and the
+gateway limitation) at **HTTP 200** for the undeclared case — deviating from
+the mandated 400 for exactly the reason above — and keeps `-32603` for the
+declared case as a documented spec gap. Until that lands, both cases surface
+as `-32603`.
+
+**A clean error does not mean nothing happened.** The refusal reaches the
+backend mid-call, so a real backend tool may have executed — including side
+effects — up to the point it demanded input. A Modern client receiving this
+error must not assume the call was side-effect-free. (The integration
+fixture's tools elicit as their first action, so the tests cannot exhibit
+this; production tools can.)
+
+- The 2026-07-28 revision **removed** server-initiated requests; go-sdk's
+  `ServerSession.assertServerInitiatedRequestAllowed` refuses
+  elicitation/sampling/roots purely by negotiated protocol version, so no
+  capability negotiation can restore the Legacy forwarding model for Modern
+  clients.
+- A server that never returns `input_required` is fully SEP-2575-conformant:
+  the per-request `clientCapabilities` a client declares are an offer the
+  server may use, not an obligation.
+- SEP-2577 deprecates sampling (and logging and roots) outright as of
+  2026-07-28, with direct LLM-provider integration as the sanctioned
+  replacement — so elicitation is the only durable consumer a future MRTR
+  implementation would serve.
+
+Legacy clients keep the full mid-call forwarding behaviour unchanged; the
+forwarding integration tests pin their downstream clients to Legacy explicitly
+(`legacyPinningRoundTripper` in `pkg/vmcp/server`'s external test package)
+because that surface exists only on a Legacy session.
+
+**Bridging was considered, costed, and rejected.** Serving MRTR to Modern
+clients on top of a *Legacy*
+backend would require parking the live, mid-flight backend call server-side
+(the blocked goroutine and its open session cannot be serialized into the
+opaque `requestState` the SEP designed for handler re-invocation) and keying
+the resume on an unguessable token — per-round server state with TTL/eviction,
+identity binding on a token that becomes a capability to resume someone else's
+in-flight call, and replica affinity with no `Mcp-Session-Id` to route on. That
+would reintroduce, in different clothes, the per-request server state the
+2026-07-28 revision removed. The spec's own sanctioned path for genuinely stateful
+`input_required` work is the **Tasks** extension (SEP-2663: `tools/call`
+returns `resultType: "task"` with a `taskId`; the client polls `tasks/get` and
+answers outstanding `inputRequests` via `inputResponses` on `tasks/update`;
+note SEP-2663 supersedes SEP-1686 and removed the blocking `tasks/result`
+method for the same reasons argued here) — if Modern-client elicitation over
+Legacy backends is ever truly demanded, that is the machinery to reach for,
+not parked `tools/call`.
+
+The coherent future MRTR shape for a re-aggregating gateway is
+**Modern-client ↔ Modern-backend pass-through** — relay a Modern backend's
+`inputRequests`/`requestState` to the client and the client's
+`inputResponses` back, genuinely stateless at vMCP. It requires the egress
+half first (today a Modern backend's `input_required` surfaces as
+`errModernInputRequired`, the seam left in `pkg/vmcp/client`), and by the time
+Modern backends exist to relay from, SEP-2577's deprecations make elicitation
+its only durable consumer; see #5743.
+
+Progress and log notifications toward Modern clients are a separate concern
+from MRTR: they remain spec-legal as request-scoped notifications on the
+POST-initiated SSE response stream (SEP-2260 requires messages on that stream
+to relate to the originating request; `progressToken` is unchanged), which the
+single-shot dispatcher does not produce today — a vMCP streaming-dispatch gap,
+not a spec absence.
+
 ## Served MCP Capabilities
 
 Beyond tools, vMCP aggregates and serves the full complement of MCP capabilities. Every served capability flows through the domain **core** (`pkg/vmcp/core`), so the same admission decision that filters `tools/list` also gates reads, gets, and completions.
@@ -484,6 +576,13 @@ While a backend `tools/call` (or other request) is in flight, the backend may is
 
 **Implementation**: `pkg/vmcp/forwarding.go`, `pkg/vmcp/client/forwarding.go`, `pkg/vmcp/server/serve_handlers.go`
 
+**Known limitation (Modern clients)**: everything in this section describes a
+**Legacy (2025-11-25) client session**. For Modern (2026-07-28) clients there
+is no session and no server-initiated request channel, so none of this
+forwarding applies — see
+[Limitation: elicitation and sampling are unavailable to Modern clients](#limitation-elicitation-and-sampling-are-unavailable-to-modern-clients)
+for what a Modern caller gets instead.
+
 **Known limitation (logging level)**: forwarded backend logging is not yet filtered to the downstream client's requested `logging/setLevel`. vMCP requests debug-level logging from the backend so it emits `notifications/message`, and every such notification is forwarded — the downstream client's own level preference is not applied to the relayed stream.
 
 **Known limitation (resource-template authorization)**: a resource template is advertised on the template-string entity (e.g. `file:///logs/{date}.txt`), but a concrete read is admission-checked on the **expanded** URI (e.g. `file:///logs/2025-01-01.txt`). Operators should therefore author resource authorization policies against concrete URI patterns, not the template string.