@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/runtime-mcp/protocol.ts

@@ -0,0 +1,624 @@
+/**
+ * MCP protocol generation model ("MCP v2", specification 2026-07-28).
+ *
+ * Canonical authority (verified against the primary sources, not secondary
+ * summaries):
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
+ * - https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr
+ * - https://modelcontextprotocol.io/specification/2026-07-28/server/discover
+ * - https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching
+ * - schema source of truth: modelcontextprotocol/specification schema/2026-07-28/schema.ts
+ *
+ * 2026-07-28 ("modern" era) removes the initialize/initialized handshake,
+ * protocol sessions (`Mcp-Session-Id`), the standalone GET SSE stream, and
+ * `Last-Event-ID` replay from the core request path. Every request carries its
+ * protocol version, client identity, and client capabilities in `_meta`, and
+ * Streamable HTTP mirrors selected fields into `MCP-Protocol-Version`,
+ * `Mcp-Method`, and `Mcp-Name` headers.
+ */
+
+// =============================================================================
+// Protocol versions and eras
+// =============================================================================
+
+/** The modern (stateless) protocol revision implemented by this client. */
+export const MCP_PROTOCOL_VERSION_2026_07_28 = "2026-07-28";
+
+/** Legacy (initialize handshake) revision this client speaks for compatibility. */
+export const MCP_PROTOCOL_VERSION_LEGACY = "2025-03-26";
+
+/** Modern-era revisions this client can speak, most preferred first. */
+export const MCP_MODERN_PROTOCOL_VERSIONS: readonly string[] = [MCP_PROTOCOL_VERSION_2026_07_28];
+
+/** Protocol generation: modern = per-request metadata (2026-07-28+), legacy = initialize handshake. */
+export type MCPProtocolEra = "modern" | "legacy";
+
+/**
+ * Per-server protocol preference from configuration.
+ * - `auto`: attempt modern first; bounded, observable legacy fallback per the
+ *   specification's era-detection rules. Default when unset.
+ * - `2026-07-28`: strict modern-only; never initializes a legacy session.
+ * - `legacy`: bounded compatibility mode; always uses the legacy handshake.
+ */
+export type MCPProtocolPreference = "auto" | "2026-07-28" | "legacy";
+
+export const MCP_PROTOCOL_PREFERENCES: readonly MCPProtocolPreference[] = ["auto", "2026-07-28", "legacy"];
+
+export function isMCPProtocolPreference(value: unknown): value is MCPProtocolPreference {
+	return typeof value === "string" && (MCP_PROTOCOL_PREFERENCES as readonly string[]).includes(value);
+}
+
+/** Resolve the effective preference; `auto` when unset. */
+export function resolveMCPProtocolPreference(value: MCPProtocolPreference | undefined): MCPProtocolPreference {
+	return value ?? "auto";
+}
+
+/** True when a version string names a modern-era revision (date-based, >= 2026-07-28). */
+export function isModernProtocolVersion(version: string): boolean {
+	return version >= MCP_PROTOCOL_VERSION_2026_07_28;
+}
+
+// =============================================================================
+// Protocol-defined JSON-RPC error codes (2026-07-28 reserved range)
+// =============================================================================
+
+/** Headers do not match the request body, or required headers are missing/malformed. */
+export const MCP_ERROR_HEADER_MISMATCH = -32020;
+/** The request requires a client capability the client did not declare. */
+export const MCP_ERROR_MISSING_REQUIRED_CLIENT_CAPABILITY = -32021;
+/** The server does not implement the requested protocol version. */
+export const MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** Standard JSON-RPC method-not-found (modern servers pair it with HTTP 404). */
+export const JSONRPC_ERROR_METHOD_NOT_FOUND = -32601;
+/** Standard JSON-RPC invalid-params (modern servers reject missing `_meta` with it). */
+export const JSONRPC_ERROR_INVALID_PARAMS = -32602;
+
+// =============================================================================
+// Per-request `_meta` (modern era)
+// =============================================================================
+
+export const MCP_META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export const MCP_META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+export const MCP_META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+export const MCP_META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+
+/** Client identity advertised in modern per-request `_meta`. */
+export interface MCPModernClientContext {
+	protocolVersion: string;
+	clientInfo: { name: string; version: string };
+	/** Capabilities relevant to requests, e.g. `{ roots: {...}, elicitation: {...} }`. */
+	capabilities: Record<string, unknown>;
+}
+
+/**
+ * Build the `_meta` object every modern request MUST carry. Callers merge this
+ * into `params._meta`, preserving any pre-existing keys (e.g. `progressToken`).
+ */
+export function buildModernRequestMeta(context: MCPModernClientContext): Record<string, unknown> {
+	return {
+		[MCP_META_PROTOCOL_VERSION]: context.protocolVersion,
+		[MCP_META_CLIENT_INFO]: { name: context.clientInfo.name, version: context.clientInfo.version },
+		[MCP_META_CLIENT_CAPABILITIES]: context.capabilities,
+	};
+}
+
+/** Merge modern `_meta` into request params without clobbering existing keys. */
+export function withModernMeta(
+	params: Record<string, unknown>,
+	context: MCPModernClientContext,
+): Record<string, unknown> {
+	const existing = params._meta;
+	const base = typeof existing === "object" && existing !== null && !Array.isArray(existing) ? existing : {};
+	return { ...params, _meta: { ...base, ...buildModernRequestMeta(context) } };
+}
+
+// =============================================================================
+// Streamable HTTP mirrored headers (modern era)
+// =============================================================================
+
+const BASE64_SENTINEL_PREFIX = "=?base64?";
+const BASE64_SENTINEL_SUFFIX = "?=";
+
+/** RFC 9110 field-value safe set: visible ASCII, space, and horizontal tab. */
+export function isPlainAsciiHeaderValue(value: string): boolean {
+	if (value.length === 0) return true;
+	// Leading/trailing whitespace forces encoding (intermediaries may trim).
+	if (value !== value.trim()) return false;
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code === 0x09) continue;
+		if (code < 0x21 || code > 0x7e) return false;
+	}
+	return true;
+}
+
+/**
+ * Encode a value for `Mcp-Name` / `Mcp-Param-{Name}` headers: plain ASCII when
+ * safe, otherwise the `=?base64?<base64-utf8>?=` sentinel. Values already
+ * matching the sentinel pattern MUST also be encoded to avoid ambiguity.
+ */
+export function encodeMcpHeaderValue(value: string): string {
+	if (
+		isPlainAsciiHeaderValue(value) &&
+		!(value.startsWith(BASE64_SENTINEL_PREFIX) && value.endsWith(BASE64_SENTINEL_SUFFIX))
+	) {
+		return value;
+	}
+	return `${BASE64_SENTINEL_PREFIX}${Buffer.from(value, "utf8").toString("base64")}${BASE64_SENTINEL_SUFFIX}`;
+}
+
+/** HTTP field-name token syntax (RFC 9110 §5.1: 1*tchar). */
+const HTTP_FIELD_NAME_PATTERN = /^[!#$%&'*+\-.0-9A-Za-z^_`|~]+$/;
+
+/** Methods whose `params.name` / `params.uri` MUST be mirrored into `Mcp-Name`. */
+const MCP_NAME_HEADER_METHODS = new Set(["tools/call", "resources/read", "prompts/get"]);
+
+/**
+ * Build the mirrored headers a modern Streamable HTTP request MUST carry:
+ * `MCP-Protocol-Version` (must equal the `_meta` version), `Mcp-Method`, and —
+ * for `tools/call`, `resources/read`, `prompts/get` — `Mcp-Name`.
+ */
+export function buildModernMcpHeaders(input: {
+	protocolVersion: string;
+	method: string;
+	params?: Record<string, unknown>;
+}): Record<string, string> {
+	const headers: Record<string, string> = {
+		"MCP-Protocol-Version": input.protocolVersion,
+		"Mcp-Method": encodeMcpHeaderValue(input.method),
+	};
+	if (MCP_NAME_HEADER_METHODS.has(input.method)) {
+		const nameValue = input.params?.name ?? input.params?.uri;
+		if (typeof nameValue === "string" && nameValue.length > 0) {
+			headers["Mcp-Name"] = encodeMcpHeaderValue(nameValue);
+		}
+	}
+	return headers;
+}
+
+// =============================================================================
+// `x-mcp-header` tool parameter mirroring (modern era, Streamable HTTP)
+// =============================================================================
+
+/** A validated binding from a tool inputSchema property to an `Mcp-Param-*` header. */
+export interface McpHeaderParamBinding {
+	/** Exact property path (chain of `properties` keys) in the call arguments. */
+	propertyPath: string[];
+	/** The `name` portion of the `Mcp-Param-{name}` header. */
+	headerName: string;
+	/** Primitive type of the annotated property. */
+	propertyType: "string" | "integer" | "boolean";
+}
+
+export interface XMcpHeaderBindingsResult {
+	bindings: McpHeaderParamBinding[];
+	/** Human-readable reasons the tool definition is invalid for HTTP mirroring. */
+	violations: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Collect `x-mcp-header` bindings from a tool `inputSchema`, enforcing the
+ * specification constraints: field-name token syntax, primitive (non-number)
+ * types, case-insensitive uniqueness, and static reachability via `properties`
+ * chains only. Any violation invalidates the tool definition for HTTP clients.
+ */
+export function collectXMcpHeaderBindings(inputSchema: unknown): XMcpHeaderBindingsResult {
+	const bindings: McpHeaderParamBinding[] = [];
+	const violations: string[] = [];
+	const seenHeaderNames = new Set<string>();
+
+	const walk = (schema: unknown, path: string[]): void => {
+		if (!isRecord(schema)) return;
+		const annotation = schema["x-mcp-header"];
+		if (annotation !== undefined) {
+			const label = path.length > 0 ? path.join(".") : "(root)";
+			if (typeof annotation !== "string" || annotation.length === 0) {
+				violations.push(`x-mcp-header on "${label}" must be a non-empty string`);
+			} else if (!HTTP_FIELD_NAME_PATTERN.test(annotation)) {
+				violations.push(`x-mcp-header "${annotation}" on "${label}" is not a valid HTTP field-name token`);
+			} else if (seenHeaderNames.has(annotation.toLowerCase())) {
+				violations.push(`x-mcp-header "${annotation}" is not case-insensitively unique`);
+			} else {
+				const type = schema.type;
+				if (type !== "string" && type !== "integer" && type !== "boolean") {
+					violations.push(
+						`x-mcp-header "${annotation}" on "${label}" requires a primitive type (string, integer, boolean)`,
+					);
+				} else if (path.length === 0) {
+					violations.push(`x-mcp-header "${annotation}" must annotate a property, not the schema root`);
+				} else {
+					seenHeaderNames.add(annotation.toLowerCase());
+					bindings.push({ propertyPath: path, headerName: annotation, propertyType: type });
+				}
+			}
+		}
+		// Only `properties` chains are statically reachable; anything annotated
+		// under items/composition/conditional keywords is unreachable and invalid
+		// by construction (we simply never descend there, so such annotations are
+		// ignored rather than mirrored).
+		if (isRecord(schema.properties)) {
+			for (const [key, subschema] of Object.entries(schema.properties)) {
+				walk(subschema, [...path, key]);
+			}
+		}
+	};
+
+	walk(inputSchema, []);
+	return { bindings, violations };
+}
+
+/**
+ * Extract `Mcp-Param-{name}` headers from tool call arguments per validated
+ * bindings. Missing or null values omit the header, per the specification.
+ */
+export function buildXMcpParamHeaders(
+	bindings: readonly McpHeaderParamBinding[],
+	args: Record<string, unknown>,
+): Record<string, string> {
+	const headers: Record<string, string> = {};
+	for (const binding of bindings) {
+		let value: unknown = args;
+		for (const key of binding.propertyPath) {
+			if (!isRecord(value)) {
+				value = undefined;
+				break;
+			}
+			value = value[key];
+		}
+		if (value === undefined || value === null) continue;
+		let text: string;
+		switch (binding.propertyType) {
+			case "string":
+				if (typeof value !== "string") continue;
+				text = value;
+				break;
+			case "integer":
+				if (typeof value !== "number" || !Number.isSafeInteger(value)) continue;
+				text = String(value);
+				break;
+			case "boolean":
+				if (typeof value !== "boolean") continue;
+				text = value ? "true" : "false";
+				break;
+		}
+		headers[`Mcp-Param-${binding.headerName}`] = encodeMcpHeaderValue(text);
+	}
+	return headers;
+}
+
+// =============================================================================
+// Era detection (Streamable HTTP backward compatibility)
+// =============================================================================
+
+/** Failure classes for a modern probe request. */
+export type MCPProbeFailureClass =
+	/** Recognized modern JSON-RPC error: the server speaks a modern revision. */
+	| "modern-error"
+	/** 4xx without a recognized modern error body: legacy-era server signal. */
+	| "legacy-signal"
+	/** 401/403 (and WWW-Authenticate challenges): never a downgrade signal. */
+	| "auth-failure"
+	/** Anything else (5xx, network, malformed payload): not a downgrade signal. */
+	| "other-failure";
+
+export interface MCPProbeClassification {
+	class: MCPProbeFailureClass;
+	/** Protocol-defined modern error code when recognized. */
+	modernErrorCode?: number;
+	/** `data.supported` from an UnsupportedProtocolVersionError, when present. */
+	supportedVersions?: string[];
+	/** `data.requested` from an UnsupportedProtocolVersionError, when present. */
+	requestedVersion?: string;
+}
+
+function isModernErrorCode(code: number): boolean {
+	return (
+		code === MCP_ERROR_HEADER_MISMATCH ||
+		code === MCP_ERROR_MISSING_REQUIRED_CLIENT_CAPABILITY ||
+		code === MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION
+	);
+}
+
+/**
+ * Classify a failed modern probe per the specification's era-detection rules:
+ * recognized modern JSON-RPC errors identify a modern server; a 400/404/405
+ * without one identifies a legacy server; auth and security failures are never
+ * era signals and must never authorize a downgrade.
+ */
+export function classifyMcpProbeFailure(status: number, parsedBody: unknown): MCPProbeClassification {
+	if (status === 401 || status === 403) {
+		return { class: "auth-failure" };
+	}
+
+	let errorCode: number | undefined;
+	let errorData: unknown;
+	if (isRecord(parsedBody) && isRecord(parsedBody.error)) {
+		if (typeof parsedBody.error.code === "number") errorCode = parsedBody.error.code;
+		errorData = parsedBody.error.data;
+	}
+
+	if (errorCode !== undefined && isModernErrorCode(errorCode)) {
+		const classification: MCPProbeClassification = { class: "modern-error", modernErrorCode: errorCode };
+		if (errorCode === MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION && isRecord(errorData)) {
+			if (Array.isArray(errorData.supported) && errorData.supported.every(v => typeof v === "string")) {
+				classification.supportedVersions = errorData.supported as string[];
+			}
+			if (typeof errorData.requested === "string") classification.requestedVersion = errorData.requested;
+		}
+		return classification;
+	}
+
+	// A modern server reports unknown methods as 404 + -32601; that pairing is
+	// itself a modern-era signal (legacy HTTP+SSE 404s carry no JSON-RPC body).
+	if (status === 404 && errorCode === JSONRPC_ERROR_METHOD_NOT_FOUND) {
+		return { class: "modern-error", modernErrorCode: errorCode };
+	}
+
+	if (status === 400 || status === 404 || status === 405) {
+		return { class: "legacy-signal" };
+	}
+
+	return { class: "other-failure" };
+}
+
+// =============================================================================
+// Authoritative protocol observation model
+// =============================================================================
+
+/** Lifecycle state of a protocol feature, mirroring the specification's feature lifecycle. */
+export type MCPFeatureLifecycle = "active" | "deprecated" | "removed";
+
+export interface MCPProtocolFeatureState {
+	feature: string;
+	lifecycle: MCPFeatureLifecycle;
+	/** Secret-free explanation shown in diagnostics. */
+	note?: string;
+}
+
+/** How the effective era/version was reached. */
+export type MCPNegotiationState =
+	/** No negotiation attempt has completed yet. */
+	| "pending"
+	/** Modern era confirmed (probe or direct modern request succeeded). */
+	| "modern"
+	/** Modern era after selecting a mutually supported version from UnsupportedProtocolVersionError. */
+	| "modern-version-retry"
+	/** Legacy era via era detection (legacy server signal) under `auto`. */
+	| "legacy-fallback"
+	/** Legacy era because configuration forced it (`legacy`) or the transport is stdio. */
+	| "legacy-forced"
+	/** Negotiation failed; the connection could not be established. */
+	| "failed";
+
+/** Machine-readable reasons a legacy fallback was engaged (never auth/security driven). */
+export type MCPDowngradeReason =
+	/** `protocol: "legacy"` configured explicitly. */
+	| "preference-legacy"
+	/** stdio transport has no per-request HTTP signals; legacy handshake retained. */
+	| "stdio-transport"
+	/** Probe returned 400/404/405 without a recognized modern error body. */
+	| "legacy-server-signal"
+	/** A modern server advertised only legacy-era versions in `supported`. */
+	| "server-advertised-legacy-only";
+
+/**
+ * One authoritative, secret-free observation of a server's negotiated protocol
+ * state. Consumed by `/extensions` (#4291) and customization doctor (#4288);
+ * contains no credentials, tokens, metadata documents, or header values.
+ */
+export interface MCPProtocolObservation {
+	/** Configured preference (defaults to `auto`). */
+	preference: MCPProtocolPreference;
+	/** Effective protocol version in use, once negotiated. */
+	effectiveVersion: string | null;
+	/** Effective era, once negotiated. */
+	era: MCPProtocolEra | null;
+	/** How the effective state was reached. */
+	negotiation: MCPNegotiationState;
+	/** Why a legacy fallback engaged; null unless `negotiation` is a legacy state. */
+	downgradeReason: MCPDowngradeReason | null;
+	/** Versions the server advertised (via server/discover or version errors). */
+	supportedVersions: string[];
+	/** Self-reported server identity (display only; never security-relevant). */
+	serverInfo: { name: string; version: string } | null;
+	/** Lifecycle visibility for protocol features (legacy session behavior, etc). */
+	features: MCPProtocolFeatureState[];
+	/** v2 capability state observed for this connection. */
+	capabilities: {
+		/** server/discover answered (optional per spec; absence does not block calls). */
+		discover: "yes" | "no" | "unknown";
+		/** Server advertised tools capability. */
+		tools: boolean;
+		/** Server advertised resources capability. */
+		resources: boolean;
+		/** Server advertised prompts capability. */
+		prompts: boolean;
+	};
+}
+
+/** Initial observation before negotiation completes. */
+export function createMCPProtocolObservation(preference: MCPProtocolPreference): MCPProtocolObservation {
+	return {
+		preference,
+		effectiveVersion: null,
+		era: null,
+		negotiation: "pending",
+		downgradeReason: null,
+		supportedVersions: [],
+		serverInfo: null,
+		features: [],
+		capabilities: { discover: "unknown", tools: false, resources: false, prompts: false },
+	};
+}
+
+/** Legacy session/transport features reported as deprecated under the feature lifecycle. */
+export function legacyEraFeatureStates(): MCPProtocolFeatureState[] {
+	return [
+		{
+			feature: "initialize-handshake",
+			lifecycle: "deprecated",
+			note: "Connection-scoped initialize/initialized handshake; removed from the core request path in 2026-07-28",
+		},
+		{
+			feature: "mcp-session-id",
+			lifecycle: "deprecated",
+			note: "Protocol-level Mcp-Session-Id sessions; not part of 2026-07-28",
+		},
+		{
+			feature: "standalone-sse-stream",
+			lifecycle: "deprecated",
+			note: "GET-opened standalone SSE stream; removed in 2026-07-28 (subscriptions/listen replaces it)",
+		},
+		{
+			feature: "sse-resumability",
+			lifecycle: "deprecated",
+			note: "Last-Event-ID stream replay; unsupported in 2026-07-28",
+		},
+	];
+}
+
+/** Finalize an observation for a negotiated modern connection. */
+export function modernEraObservation(input: {
+	preference: MCPProtocolPreference;
+	effectiveVersion: string;
+	negotiation: "modern" | "modern-version-retry";
+	supportedVersions?: string[];
+	serverInfo?: { name: string; version: string } | null;
+	capabilities?: { tools?: boolean; resources?: boolean; prompts?: boolean };
+	discover: "yes" | "no" | "unknown";
+}): MCPProtocolObservation {
+	return {
+		preference: input.preference,
+		effectiveVersion: input.effectiveVersion,
+		era: "modern",
+		negotiation: input.negotiation,
+		downgradeReason: null,
+		supportedVersions: input.supportedVersions ?? [],
+		serverInfo: input.serverInfo ?? null,
+		features: [],
+		capabilities: {
+			discover: input.discover,
+			tools: input.capabilities?.tools ?? false,
+			resources: input.capabilities?.resources ?? false,
+			prompts: input.capabilities?.prompts ?? false,
+		},
+	};
+}
+
+/** Finalize an observation for a negotiated legacy connection. */
+export function legacyEraObservation(input: {
+	preference: MCPProtocolPreference;
+	effectiveVersion: string;
+	negotiation: "legacy-fallback" | "legacy-forced";
+	downgradeReason: MCPDowngradeReason;
+	serverInfo?: { name: string; version: string } | null;
+	capabilities?: { tools?: boolean; resources?: boolean; prompts?: boolean };
+}): MCPProtocolObservation {
+	return {
+		preference: input.preference,
+		effectiveVersion: input.effectiveVersion,
+		era: "legacy",
+		negotiation: input.negotiation,
+		downgradeReason: input.downgradeReason,
+		supportedVersions: [],
+		serverInfo: input.serverInfo ?? null,
+		features: legacyEraFeatureStates(),
+		capabilities: {
+			discover: "no",
+			tools: input.capabilities?.tools ?? false,
+			resources: input.capabilities?.resources ?? false,
+			prompts: input.capabilities?.prompts ?? false,
+		},
+	};
+}
+
+// =============================================================================
+// Caching hints (server/discover and catalog results)
+// =============================================================================
+
+/** Cache scope hint: public results may cross authorization contexts; private must not. */
+export type MCPCacheScope = "public" | "private";
+
+/** Server-supplied caching hints carried on cacheable `complete` results. */
+export interface MCPCacheHints {
+	/** Milliseconds the result may be considered fresh; absent/negative means 0. */
+	ttlMs?: number;
+	cacheScope?: MCPCacheScope;
+}
+
+/** Normalize raw hints: negative ttlMs is treated as 0 per the specification. */
+export function normalizeMcpCacheHints(raw: unknown): MCPCacheHints | undefined {
+	if (!isRecord(raw)) return undefined;
+	const hints: MCPCacheHints = {};
+	if (typeof raw.ttlMs === "number" && Number.isFinite(raw.ttlMs)) {
+		hints.ttlMs = Math.max(0, raw.ttlMs);
+	}
+	if (raw.cacheScope === "public" || raw.cacheScope === "private") {
+		hints.cacheScope = raw.cacheScope;
+	}
+	return hints.ttlMs === undefined && hints.cacheScope === undefined ? undefined : hints;
+}
+
+// =============================================================================
+// MRTR (multi round-trip requests)
+// =============================================================================
+
+/** Result type marker for interim input requests. */
+export const MCP_RESULT_TYPE_INPUT_REQUIRED = "input_required";
+export const MCP_RESULT_TYPE_COMPLETE = "complete";
+
+/** Input request methods a server may embed in an InputRequiredResult. */
+export const MCP_INPUT_REQUEST_METHODS = new Set(["elicitation/create", "sampling/createMessage", "roots/list"]);
+
+export interface MCPInputRequiredData {
+	inputRequests: Record<string, { method: string; params?: Record<string, unknown> }>;
+	requestState?: string;
+}
+
+/**
+ * Extract MRTR input data from a JSON-RPC result. Returns null when the result
+ * is a normal `complete` result (including legacy results with no resultType,
+ * which the specification requires clients to treat as `"complete"`).
+ * Throws on a malformed `input_required` payload.
+ */
+export function extractMcpInputRequired(result: unknown): MCPInputRequiredData | null {
+	if (!isRecord(result)) return null;
+	const resultType = result.resultType;
+	if (resultType === undefined || resultType === MCP_RESULT_TYPE_COMPLETE) return null;
+	if (resultType !== MCP_RESULT_TYPE_INPUT_REQUIRED) {
+		// Unrecognized resultType values are invalid per the specification.
+		throw new Error(`MCP result has unrecognized resultType "${String(resultType)}"`);
+	}
+	const inputRequests: MCPInputRequiredData["inputRequests"] = {};
+	if (result.inputRequests !== undefined) {
+		if (!isRecord(result.inputRequests)) {
+			throw new Error("MCP input_required result has malformed inputRequests");
+		}
+		for (const [key, value] of Object.entries(result.inputRequests)) {
+			if (!isRecord(value) || typeof value.method !== "string" || !MCP_INPUT_REQUEST_METHODS.has(value.method)) {
+				throw new Error(`MCP input_required request "${key}" is not a supported input request`);
+			}
+			inputRequests[key] = {
+				method: value.method,
+				...(isRecord(value.params) ? { params: value.params } : {}),
+			};
+		}
+	}
+	let requestState: string | undefined;
+	if (result.requestState !== undefined) {
+		if (typeof result.requestState !== "string") {
+			throw new Error("MCP input_required result has non-string requestState");
+		}
+		requestState = result.requestState;
+	}
+	if (Object.keys(inputRequests).length === 0 && requestState === undefined) {
+		throw new Error("MCP input_required result carries neither inputRequests nor requestState");
+	}
+	return { inputRequests, ...(requestState === undefined ? {} : { requestState }) };
+}