feat: multi round-trip requests — neutral contract and client auto-fulfilment engine

.changeset/mrtr-client-engine.md

@@ -0,0 +1,12 @@
+---
+'@modelcontextprotocol/core': minor
+'@modelcontextprotocol/client': minor
+---
+
+Add the client side of multi round-trip requests (protocol revision 2026-07-28, SEP-2322). The neutral `InputRequest`/`InputResponse`/`InputRequests`/`InputResponses`/`InputRequiredResult` types and the `isInputRequiredResult()` guard ship as the neutral surface (the
+`inputRequired()` builder family and the `acceptedContent()` reader are exported by the server package as part of the server-side change); the 2026-07-28 wire codec models the in-band vocabulary (embedded requests and bare responses) and the retry-channel request fields. On the
+client, an `input_required` answer to `tools/call`, `prompts/get`, or `resources/read` on a 2026-07-28 connection is now fulfilled automatically by default: the embedded requests are dispatched to the client's already-registered elicitation/sampling/roots handlers, and the
+original call is retried with the collected `inputResponses`, a byte-exact echo of the opaque `requestState`, and a fresh request id, up to `inputRequired.maxRounds` rounds (default 10; exhaustion raises a typed `InputRequiredRoundsExceeded` error carrying the last result).
+`client.callTool()` and its siblings keep returning their plain result types. `ClientOptions.inputRequired` (`autoFulfill`, `maxRounds`) configures the driver; manual mode is `autoFulfill: false` plus the per-call `allowInputRequired: true` request option and the
+`withInputRequired()` schema wrapper. Retried requests surface their `inputResponses` to server handlers as bare response objects — entries in a wrapped `{method, result}` shape are dropped and reported via `ctx.mcpReq.droppedInputResponseKeys`. 2025-era behavior is unchanged:
+the legacy wire has no `input_required` vocabulary and the legacy server-to-client request flow is untouched.

packages/client/src/client/client.ts

@@ -14,6 +14,7 @@
     GetPromptRequest,
     GetPromptResult,
     Implementation,
+    InputRequiredOptions,
     JSONRPCNotification,
     JSONRPCRequest,
     JsonSchemaType,
@@ -59,6 +60,7 @@
     Protocol,
     ProtocolError,
     ProtocolErrorCode,
+    resolveInputRequiredDriverConfig,
     SdkError,
     SdkErrorCode
 } from '@modelcontextprotocol/core';
@@ -178,6 +180,31 @@
      */
     versionNegotiation?: VersionNegotiationOptions;
 
+    /**
+     * Multi-round-trip auto-fulfilment (protocol revision 2026-07-28).
+     *
+     * On the 2026-07-28 era, servers obtain client input (elicitation,
+     * sampling, roots) by answering `tools/call`, `prompts/get`, or
+     * `resources/read` with an `input_required` result instead of sending a
+     * server→client request. By default the client fulfils those embedded
+     * requests automatically through the SAME handlers registered via
+     * {@linkcode Client.setRequestHandler | setRequestHandler} (e.g.
+     * `elicitation/create`), then retries the original call with the
+     * collected `inputResponses` and a byte-exact echo of the opaque
+     * `requestState`, on a fresh request id, up to `maxRounds` rounds.
+     * `client.callTool()` (and its siblings) keep returning their plain
+     * result type — the interactive rounds happen inside the call.
+     *
+     * Set `autoFulfill: false` for manual mode: an `input_required` response
+     * then surfaces as a typed error unless the individual call passes
+     * `allowInputRequired: true` (pair it with `withInputRequired()` on the
+     * explicit-schema path to type both outcomes).
+     *
+     * Has no effect on 2025-era connections, which have no `input_required`
+     * vocabulary.
+     */
+    inputRequired?: InputRequiredOptions;
+
     /**
      * Configure handlers for list changed notifications (tools, prompts, resources).
      *
@@ -267,6 +294,9 @@
         this._enforceStrictCapabilities = options?.enforceStrictCapabilities ?? false;
         this._versionNegotiation = options?.versionNegotiation;
         this._supportedProtocolVersionsOption = options?.supportedProtocolVersions;
+        // Multi-round-trip auto-fulfilment driver (2026-07-28): on by default,
+        // configurable via ClientOptions.inputRequired.
+        this._inputRequiredDriverConfig = resolveInputRequiredDriverConfig(options?.inputRequired);
 
         // Store list changed config for setup after connection (when we know server capabilities)
         if (options?.listChanged) {
@@ -352,14 +382,16 @@
         if (method === 'elicitation/create') {
             return async (request, ctx) => {
                 // Era-exact validation: the schemas are resolved from the
-                // instance era at dispatch time (the era gate guarantees the
-                // method exists on the serving era before we get here).
+                // instance era at dispatch time. On the 2025 era the method
+                // is a wire request (registry schemas); on the 2026 era it is
+                // in-band vocabulary reached only via the multi-round-trip
+                // driver, so the in-band schemas apply.
                 const codec = codecForVersion(this._negotiatedProtocolVersion);
-                const elicitRequestSchema = codec.requestSchema('elicitation/create');
+                const elicitRequestSchema = codec.requestSchema('elicitation/create') ?? codec.inputRequestSchema('elicitation/create');
                 // The era registry entry IS the plain ElicitResult schema
                 // (the result map is aligned to the typed map — no widened
                 // unions), so no narrower surface is needed.
-                const elicitResultSchema = codec.resultSchema('elicitation/create');
+                const elicitResultSchema = codec.resultSchema('elicitation/create') ?? codec.inputResponseSchema('elicitation/create');
                 if (!elicitRequestSchema || !elicitResultSchema) {
                     throw new ProtocolError(ProtocolErrorCode.InternalError, 'No wire schema for elicitation/create in the resolved era');
                 }
@@ -416,9 +448,13 @@
 
         if (method === 'sampling/createMessage') {
             return async (request, ctx) => {
-                // Era-exact validation via the instance era (see above).
+                // Era-exact validation via the instance era (see above): wire
+                // request schema on the 2025 era, in-band schema on the 2026
+                // era (where sampling reaches the handler only as an embedded
+                // input request).
                 const codec = codecForVersion(this._negotiatedProtocolVersion);
-                const samplingRequestSchema = codec.requestSchema('sampling/createMessage');
+                const wireSamplingRequestSchema = codec.requestSchema('sampling/createMessage');
+                const samplingRequestSchema = wireSamplingRequestSchema ?? codec.inputRequestSchema('sampling/createMessage');
                 if (!samplingRequestSchema) {
                     throw new ProtocolError(
                         ProtocolErrorCode.InternalError,
@@ -436,13 +472,28 @@
 
                 const result = await handler(request, ctx);
 
-                // The result schema depends on the REQUEST params (tools vs
-                // no tools) — something a method-keyed registry entry cannot
-                // express, so the pair is picked here. The era gate keeps
-                // this era-correct: sampling/createMessage is only ever
-                // dispatched on an era whose registry defines it.
+                // The result-side schema mirrors the request-side selection so
+                // both stay on the same era's vocabulary. On the 2025 era the
+                // schema depends on the REQUEST params (tools vs no tools) —
+                // something a method-keyed registry entry cannot express, so
+                // the pair is picked here. When the request schema came from
+                // the in-band fallback (2026 era, where sampling reaches the
+                // handler only as an embedded input request), the embedded
+                // response schema applies — it covers plain and tool-bearing
+                // responses alike.
                 const hasTools = params.tools || params.toolChoice;
-                const resultSchema = hasTools ? CreateMessageResultWithToolsSchema : CreateMessageResultSchema;
+                const resultSchema =
+                    wireSamplingRequestSchema === undefined
+                        ? codec.inputResponseSchema('sampling/createMessage')
+                        : hasTools
+                          ? CreateMessageResultWithToolsSchema
+                          : CreateMessageResultSchema;
+                if (!resultSchema) {
+                    throw new ProtocolError(
+                        ProtocolErrorCode.InternalError,
+                        'No result schema for sampling/createMessage in the resolved era'
+                    );
+                }
                 const validationResult = parseSchema(resultSchema, result);
                 if (!validationResult.success) {
                     const errorMessage =

packages/client/src/index.ts

@@ -75,5 +75,11 @@ export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
 // runtime-aware wrapper (shadows core/public's fromJsonSchema with optional validator)
 export { fromJsonSchema } from './fromJsonSchema.js';
 
+// Multi-round-trip requests (protocol revision 2026-07-28): the client-side
+// auto-fulfilment knobs (ClientOptions.inputRequired) and the manual-mode
+// schema wrapper for callers that opt out of auto-fulfilment per call.
+export type { InputRequiredOptions } from '@modelcontextprotocol/core';
+export { withInputRequired } from '@modelcontextprotocol/core';
+
 // re-export curated public API from core
 export * from '@modelcontextprotocol/core/public';