@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/runtime-mcp/scope-config.ts

@@ -0,0 +1,78 @@
+/**
+ * Scope-aware MCP configuration access.
+ *
+ * Canonical read/write contract for GJC's native MCP config in both scopes —
+ * project `<project>/.gjc/mcp.json` and global `~/.gjc/agent/mcp.json`.
+ * These wrappers resolve the scope to its file path, reuse the atomic config
+ * writer, and return provenance (scope + path) with every read so callers can
+ * show source and status without re-deriving path rules. Secret values are
+ * never printed by these APIs; the CLI applies its existing redaction layer on
+ * top of returned configs.
+ */
+import { getMCPConfigPath, getProjectDir } from "@gajae-code/utils";
+import {
+	getMCPServer,
+	readDisabledServers,
+	readMCPConfigFile,
+	removeMCPServer,
+	type UpsertMCPServerResult,
+	upsertMCPServer,
+} from "./config-writer";
+import type { MCPConfigFile, MCPServerConfig } from "./types";
+
+export type MCPConfigScope = "user" | "project";
+
+/** Resolved scope + path + parsed config (provenance for diagnostics). */
+export interface ScopeMCPConfigSnapshot {
+	scope: MCPConfigScope;
+	path: string;
+	config: MCPConfigFile;
+}
+
+/** Resolve the canonical file path for a native MCP config scope. */
+export function resolveScopeMCPConfigPath(scope: MCPConfigScope, cwd: string = getProjectDir()): string {
+	return getMCPConfigPath(scope, cwd);
+}
+
+/** Read a native MCP config for a scope. Returns an empty config when absent. */
+export async function readScopeMCPConfig(scope: MCPConfigScope, cwd?: string): Promise<ScopeMCPConfigSnapshot> {
+	const path = resolveScopeMCPConfigPath(scope, cwd);
+	return { scope, path, config: await readMCPConfigFile(path) };
+}
+/** Add a server, or overwrite an existing one only when `force` is set. */
+export async function upsertScopeMCPServer(
+	scope: MCPConfigScope,
+	name: string,
+	config: MCPServerConfig,
+	options: { force?: boolean } = {},
+	cwd?: string,
+): Promise<ScopeMCPConfigSnapshot & { result: UpsertMCPServerResult }> {
+	const path = resolveScopeMCPConfigPath(scope, cwd);
+	const result = await upsertMCPServer(path, name, config, options);
+	return { scope, path, config: await readMCPConfigFile(path), result };
+}
+
+/** Remove a server from a scope (throws when the name does not exist). */
+export async function removeScopeMCPServer(
+	scope: MCPConfigScope,
+	name: string,
+	cwd?: string,
+): Promise<ScopeMCPConfigSnapshot> {
+	const path = resolveScopeMCPConfigPath(scope, cwd);
+	await removeMCPServer(path, name);
+	return { scope, path, config: await readMCPConfigFile(path) };
+}
+
+/** Get a specific server config from a scope. */
+export async function getScopeMCPServer(
+	scope: MCPConfigScope,
+	name: string,
+	cwd?: string,
+): Promise<{ scope: MCPConfigScope; path: string; config: MCPServerConfig | undefined }> {
+	const path = resolveScopeMCPConfigPath(scope, cwd);
+	return { scope, path, config: await getMCPServer(path, name) };
+}
+/** Read the disabled-servers denylist for a scope. */
+export async function readScopeDisabledServers(scope: MCPConfigScope, cwd?: string): Promise<string[]> {
+	return readDisabledServers(resolveScopeMCPConfigPath(scope, cwd));
+}

package/src/runtime-mcp/tool-bridge.ts

@@ -19,16 +19,36 @@ import { ToolAbortError, throwIfAborted } from "../tools/tool-errors";
 import { callTool } from "./client";
 import type { MCPPoolLease } from "./pool";
 import { renderMCPCall, renderMCPResult } from "./render";
-import type { MCPContent, MCPServerConnection, MCPToolCallParams, MCPToolCallResult, MCPToolDefinition } from "./types";
+import type {
+	MCPContent,
+	MCPInputRequestHandler,
+	MCPRequestOptions,
+	MCPServerConnection,
+	MCPToolCallParams,
+	MCPToolCallResult,
+	MCPToolDefinition,
+} from "./types";
 
 /** Reconnect callback: tears down stale connection, returns new one or null. */
 export type MCPReconnect = () => Promise<MCPServerConnection | null>;
 
 type MCPToolTarget = MCPServerConnection | MCPPoolLease;
 
+/** Options shared by MCPTool and DeferredMCPTool. */
+export interface MCPToolOptions {
+	/** Shared lease policy: never retry the original request after transport/auth failure. */
+	noReplay?: boolean;
+	/**
+	 * Lazy resolver for the modern MRTR `input_required` handler, registered by the
+	 * owning manager/runtime. Resolved per call so late registration still applies.
+	 */
+	inputHandler?: () => MCPInputRequestHandler | undefined;
+}
+
 function connectionForTool(target: MCPToolTarget): MCPServerConnection {
 	return "connectionForLease" in target ? target.connectionForLease() : target;
 }
+
 /**
  * Network-level and stale-session errors that warrant a reconnect + single retry.
  * Conservative: only catches errors where the server is likely alive but the
@@ -226,12 +246,18 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 
 	private connection: MCPServerConnection;
 	#noReplay = false;
+	#inputHandlerResolver: (() => MCPInputRequestHandler | undefined) | undefined;
+
+	#callOptions(signal?: AbortSignal): MCPRequestOptions {
+		const inputHandler = this.#inputHandlerResolver?.();
+		return { signal, noReplay: this.#noReplay, ...(inputHandler ? { inputHandler } : {}) };
+	}
 	/** Create MCPTool instances for all tools from an MCP server lease/connection. */
 	static fromTools(
 		target: MCPToolTarget,
 		tools: MCPToolDefinition[],
 		reconnect?: MCPReconnect,
-		options?: { noReplay?: boolean },
+		options?: MCPToolOptions,
 	): MCPTool[] {
 		return tools.map(tool => new MCPTool(target, tool, reconnect, options));
 	}
@@ -240,11 +266,12 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		target: MCPToolTarget,
 		private readonly tool: MCPToolDefinition,
 		private readonly reconnect?: MCPReconnect,
-		options?: { noReplay?: boolean },
+		options?: MCPToolOptions,
 	) {
 		const resolvedConnection = connectionForTool(target);
 		this.connection = resolvedConnection;
 		this.#noReplay = options?.noReplay === true;
+		this.#inputHandlerResolver = options?.inputHandler;
 		this.name = createMCPToolName(resolvedConnection.name, tool.name);
 		this.label = `${resolvedConnection.name}/${tool.name}`;
 		this.description = tool.description ?? `MCP tool from ${resolvedConnection.name}`;
@@ -274,7 +301,7 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		const providerName = this.connection._source?.providerName;
 
 		try {
-			const result = await callTool(this.connection, this.tool.name, args, { signal, noReplay: this.#noReplay });
+			const result = await callTool(this.connection, this.tool.name, args, this.#callOptions(signal));
 			return buildResult(result, this.connection.name, this.tool.name, provider, providerName);
 		} catch (error) {
 			rethrowIfAborted(error, signal);
@@ -288,7 +315,7 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 					const retryProvider = newConn._source?.provider ?? provider;
 					const retryProviderName = newConn._source?.providerName ?? providerName;
 					try {
-						const result = await callTool(newConn, this.tool.name, args, { signal, noReplay: this.#noReplay });
+						const result = await callTool(newConn, this.tool.name, args, this.#callOptions(signal));
 						return buildResult(result, newConn.name, this.tool.name, retryProvider, retryProviderName);
 					} catch (retryError) {
 						rethrowIfAborted(retryError, signal);
@@ -322,6 +349,12 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 	readonly #fallbackProvider: string | undefined;
 	readonly #fallbackProviderName: string | undefined;
 	#noReplay = false;
+	#inputHandlerResolver: (() => MCPInputRequestHandler | undefined) | undefined;
+
+	#callOptions(signal?: AbortSignal): MCPRequestOptions {
+		const inputHandler = this.#inputHandlerResolver?.();
+		return { signal, noReplay: this.#noReplay, ...(inputHandler ? { inputHandler } : {}) };
+	}
 
 	/** Create DeferredMCPTool instances for all tools from an MCP server */
 	static fromTools(
@@ -330,7 +363,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		getConnection: () => Promise<MCPServerConnection>,
 		source?: SourceMeta,
 		reconnect?: MCPReconnect,
-		options?: { noReplay?: boolean },
+		options?: MCPToolOptions,
 	): DeferredMCPTool[] {
 		return tools.map(tool => new DeferredMCPTool(serverName, tool, getConnection, source, reconnect, options));
 	}
@@ -341,7 +374,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		private readonly getConnection: () => Promise<MCPServerConnection>,
 		source?: SourceMeta,
 		private readonly reconnect?: MCPReconnect,
-		options?: { noReplay?: boolean },
+		options?: MCPToolOptions,
 	) {
 		this.name = createMCPToolName(serverName, tool.name);
 		this.label = `${serverName}/${tool.name}`;
@@ -352,6 +385,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 		this.#fallbackProvider = source?.provider;
 		this.#fallbackProviderName = source?.providerName;
 		this.#noReplay = options?.noReplay === true;
+		this.#inputHandlerResolver = options?.inputHandler;
 	}
 
 	renderCall(args: unknown, _options: RenderResultOptions, theme: Theme) {
@@ -378,7 +412,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 			const connection = await untilAborted(signal, () => this.getConnection());
 			throwIfAborted(signal);
 			try {
-				const result = await callTool(connection, this.tool.name, args, { signal, noReplay: this.#noReplay });
+				const result = await callTool(connection, this.tool.name, args, this.#callOptions(signal));
 				return buildResult(
 					result,
 					this.serverName,
@@ -396,7 +430,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 						const retryProvider = newConn._source?.provider ?? provider;
 						const retryProviderName = newConn._source?.providerName ?? providerName;
 						try {
-							const result = await callTool(newConn, this.tool.name, args, { signal, noReplay: this.#noReplay });
+							const result = await callTool(newConn, this.tool.name, args, this.#callOptions(signal));
 							return buildResult(result, this.serverName, this.tool.name, retryProvider, retryProviderName);
 						} catch (retryError) {
 							rethrowIfAborted(retryError, signal);
@@ -421,7 +455,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 				const newConn = await reconnectWithAbort(this.reconnect, signal);
 				if (newConn && !this.#noReplay) {
 					try {
-						const result = await callTool(newConn, this.tool.name, args, { signal, noReplay: this.#noReplay });
+						const result = await callTool(newConn, this.tool.name, args, this.#callOptions(signal));
 						return buildResult(
 							result,
 							this.serverName,

package/src/runtime-mcp/transports/http.ts

@@ -2,7 +2,10 @@
  * MCP HTTP transport (Streamable HTTP).
  *
  * Implements JSON-RPC 2.0 over HTTP POST with optional SSE streaming.
- * Based on MCP spec 2025-03-26.
+ * Legacy era: session-oriented Streamable HTTP per MCP spec 2025-03-26
+ * (`Mcp-Session-Id`, standalone GET SSE listener, DELETE termination).
+ * Modern era (2026-07-28): stateless per-request `_meta` + mirrored headers,
+ * no sessions, no standalone stream, no replay. See ../protocol.ts.
  */
 import { logger, readSseJson, Snowflake } from "@gajae-code/utils";
 import type {
@@ -15,7 +18,7 @@ import type {
 	MCPSseServerConfig,
 	MCPTransport,
 } from "../../runtime-mcp/types";
-import { MCPExpectedFailure, toJsonRpcError } from "../../runtime-mcp/types";
+import { MCPExpectedFailure, MCPHttpRequestError, MCPJsonRpcError, toJsonRpcError } from "../../runtime-mcp/types";
 import {
 	cancelMCPStream,
 	MCP_MAX_CONTENT_BYTES,
@@ -25,6 +28,16 @@ import {
 	readMCPResponseText,
 } from "../content-limits";
 import { fetchPluginMcpRequest, isPluginMcpPublicNetworkBound } from "../plugin-network-boundary";
+import { buildModernMcpHeaders, type MCPModernClientContext, type MCPProtocolEra, withModernMeta } from "../protocol";
+
+/** Best-effort JSON parse of an error body for structured era classification. */
+function tryParseJsonBody(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+}
 
 /**
  * HTTP transport for MCP servers.
@@ -36,6 +49,12 @@ export class HttpTransport implements MCPTransport {
 	#sseConnection: AbortController | null = null;
 	#streamControllers = new Set<AbortController>();
 	#streamReaders = new Set<Promise<void>>();
+	/**
+	 * Negotiated protocol era. Legacy keeps the sessionful 2025-03-26 behavior;
+	 * modern (2026-07-28) is stateless: no session id, no GET stream, no DELETE.
+	 */
+	#era: MCPProtocolEra = "legacy";
+	#modernContext: MCPModernClientContext | null = null;
 
 	onClose?: () => void;
 	onError?: (error: Error) => void;
@@ -57,6 +76,25 @@ export class HttpTransport implements MCPTransport {
 		return this.config.url;
 	}
 
+	/** Negotiated protocol era (defaults to legacy until the client negotiates). */
+	get era(): MCPProtocolEra {
+		return this.#era;
+	}
+
+	/**
+	 * Select the protocol era. Modern mode requires the per-request client
+	 * context (protocol version, identity, capabilities) mirrored into `_meta`
+	 * and HTTP headers on every request.
+	 */
+	setProtocolMode(era: MCPProtocolEra, modernContext?: MCPModernClientContext): void {
+		if (era === "modern" && !modernContext) {
+			throw new Error("modern MCP protocol mode requires a client context");
+		}
+		this.#era = era;
+		this.#modernContext = era === "modern" ? (modernContext ?? null) : null;
+		if (era === "modern") this.#sessionId = null;
+	}
+
 	/**
 	 * Mark transport as connected.
 	 * HTTP doesn't need persistent connection, but we track state.
@@ -88,6 +126,9 @@ export class HttpTransport implements MCPTransport {
 	 */
 	async startSSEListener(): Promise<void> {
 		if (!this.#connected) return;
+		// The modern era removed the standalone GET stream; request-scoped SSE
+		// responses and subscriptions/listen are the only streams.
+		if (this.#era === "modern") return;
 		if (this.#sseConnection) return;
 
 		const sseConnection = new AbortController();
@@ -167,6 +208,13 @@ export class HttpTransport implements MCPTransport {
 		}
 		// Server-to-client request: has both method and id
 		if ("method" in message && "id" in message && message.id != null) {
+			if (this.#era === "modern") {
+				// 2026-07-28 forbids server-initiated JSON-RPC requests on SSE streams;
+				// server-to-client interactions use MRTR input requests instead. Do not
+				// fall back to the legacy elicitation-over-stream pattern.
+				logger.debug("Dropping server-initiated request on modern-era stream");
+				return;
+			}
 			void this.#handleServerRequest(message as JsonRpcRequest);
 			return;
 		}
@@ -219,7 +267,10 @@ export class HttpTransport implements MCPTransport {
 			jsonrpc: "2.0" as const,
 			id,
 			method,
-			params: params ?? {},
+			params:
+				this.#era === "modern" && this.#modernContext
+					? withModernMeta(params ?? {}, this.#modernContext)
+					: (params ?? {}),
 		};
 
 		const headers: Record<string, string> = {
@@ -228,7 +279,18 @@ export class HttpTransport implements MCPTransport {
 			...this.config.headers,
 		};
 
-		if (this.#sessionId) {
+		if (this.#era === "modern" && this.#modernContext) {
+			// 2026-07-28: mirrored request metadata headers are REQUIRED.
+			Object.assign(
+				headers,
+				buildModernMcpHeaders({
+					protocolVersion: this.#modernContext.protocolVersion,
+					method,
+					params: body.params,
+				}),
+			);
+			if (options?.mcpParamHeaders) Object.assign(headers, options.mcpParamHeaders);
+		} else if (this.#sessionId) {
 			headers["Mcp-Session-Id"] = this.#sessionId;
 		}
 
@@ -248,10 +310,12 @@ export class HttpTransport implements MCPTransport {
 				signal: operationSignal,
 			});
 
-			// Check for session ID in response
-			const newSessionId = response.headers.get("Mcp-Session-Id");
-			if (newSessionId) {
-				this.#sessionId = newSessionId;
+			// Check for session ID in response (legacy era only; modern servers do not mint sessions)
+			if (this.#era !== "modern") {
+				const newSessionId = response.headers.get("Mcp-Session-Id");
+				if (newSessionId) {
+					this.#sessionId = newSessionId;
+				}
 			}
 
 			if (!response.ok) {
@@ -265,7 +329,11 @@ export class HttpTransport implements MCPTransport {
 					.filter(Boolean)
 					.join("; ");
 				const suffix = authHints ? ` [${authHints}]` : "";
-				throw new Error(`HTTP ${response.status}: ${text}${suffix}`);
+				throw new MCPHttpRequestError(
+					response.status,
+					`HTTP ${response.status}: ${text}${suffix}`,
+					tryParseJsonBody(text),
+				);
 			}
 
 			const contentType = response.headers.get("Content-Type") ?? "";
@@ -298,7 +366,9 @@ export class HttpTransport implements MCPTransport {
 				if (!result.error) {
 					throw new MCPExpectedFailure();
 				}
-				throw new MCPExpectedFailure(new Error(`MCP error ${result.error.code}: ${result.error.message}`));
+				throw new MCPExpectedFailure(
+					new MCPJsonRpcError(result.error.code, result.error.message, result.error.data),
+				);
 			}
 
 			return result.result as T;
@@ -371,7 +441,7 @@ export class HttpTransport implements MCPTransport {
 								} else {
 									reject(
 										new MCPExpectedFailure(
-											new Error(`MCP error ${response.error.code}: ${response.error.message}`),
+											new MCPJsonRpcError(response.error.code, response.error.message, response.error.data),
 										),
 									);
 								}
@@ -547,8 +617,9 @@ export class HttpTransport implements MCPTransport {
 
 		if (!wasConnected && !this.#sessionId) return;
 
-		// Send session termination if we have a session
-		if (this.#sessionId) {
+		// Send session termination if we have a session (legacy era only;
+		// the modern era has no protocol session to terminate)
+		if (this.#era !== "modern" && this.#sessionId) {
 			try {
 				const timeout = this.config.timeout ?? 30000;
 				const headers: Record<string, string> = {

package/src/runtime-mcp/types.ts

@@ -1,16 +1,18 @@
 /**
  * MCP (Model Context Protocol) type definitions.
  *
- * Based on MCP specification 2025-03-26:
- * https://modelcontextprotocol.io/specification/2025-03-26/
+ * Legacy sessionful surface based on MCP specification 2025-03-26; the modern
+ * stateless generation (2026-07-28, "MCP v2") is modeled in ./protocol.ts.
+ * https://modelcontextprotocol.io/specification/2026-07-28/
  */
 
+import type { SourceMeta } from "../capability/types";
+import type { MCPCacheHints, MCPProtocolObservation, MCPProtocolPreference } from "./protocol";
+
 // =============================================================================
 // JSON-RPC 2.0 Types
 // =============================================================================
 
-import type { SourceMeta } from "../capability/types";
-
 export interface JsonRpcRequest {
 	jsonrpc: "2.0";
 	id: string | number;
@@ -63,15 +65,23 @@ export interface MCPServerConfigBase {
 	enabled?: boolean;
 	/**
 	 * Whether an explicit runtime MCP consumer should connect this server
-	 * automatically when that consumer starts (default: true). Normal standalone
-	 * `gjc`, `gjc --tmux`, and print-mode sessions do not consume `gjc mcp`
-	 * registrations today.
+	 * automatically when that consumer starts (default: true). Ordinary
+	 * standalone `gjc`, `gjc --tmux`, and print-mode sessions honor autoload for
+	 * conventional registrations; `autoload: false` keeps a server configured
+	 * for on-demand `/mcp` connection. `--no-mcp` opts a session out entirely.
 	 */
 	autoload?: boolean;
 	/** Connection timeout in milliseconds (default: 30000) */
 	timeout?: number;
 	/** Pool identity mode. W2 defaults to one physical connection per session. */
 	sharing?: "per-session" | "shared";
+	/**
+	 * Protocol preference for remote (http/sse) servers: `auto` (default) negotiates
+	 * the modern 2026-07-28 stateless protocol first with a bounded, observable
+	 * legacy fallback; `2026-07-28` is strict modern-only; `legacy` forces the
+	 * bounded compatibility handshake. Ignored by stdio servers (always legacy-era).
+	 */
+	protocol?: MCPProtocolPreference;
 	/** Authentication configuration (optional) */
 	auth?: MCPAuthConfig;
 	/** OAuth configuration for servers requiring explicit client credentials */
@@ -140,6 +150,8 @@ export interface MCPImplementation {
 export interface MCPClientCapabilities {
 	roots?: { listChanged?: boolean };
 	sampling?: Record<string, never>;
+	/** Form-mode elicitation support (modern MRTR `elicitation/create` input requests). */
+	elicitation?: { form?: Record<string, never> };
 	experimental?: Record<string, unknown>;
 }
 
@@ -180,7 +192,7 @@ export interface MCPToolDefinition {
 }
 
 /** tools/list response */
-export interface MCPToolsListResult {
+export interface MCPToolsListResult extends MCPCacheHints {
 	tools: MCPToolDefinition[];
 	nextCursor?: string;
 }
@@ -237,13 +249,82 @@ export class MCPExpectedFailure extends Error {
 		this.name = "MCPExpectedFailure";
 	}
 }
+
+/** HTTP-level request failure carrying structured detail for era classification. */
+export class MCPHttpRequestError extends Error {
+	/** HTTP status code. */
+	readonly status: number;
+	/** Parsed JSON body when the error payload was JSON; undefined otherwise. */
+	readonly body: unknown;
+	constructor(status: number, message: string, body?: unknown) {
+		super(message);
+		this.name = "MCPHttpRequestError";
+		this.status = status;
+		this.body = body;
+	}
+}
+
+/** JSON-RPC error response failure carrying the protocol error code. */
+export class MCPJsonRpcError extends Error {
+	readonly code: number;
+	readonly data?: unknown;
+	constructor(code: number, message: string, data?: unknown) {
+		super(`MCP error ${code}: ${message}`);
+		this.name = "MCPJsonRpcError";
+		this.code = code;
+		this.data = data;
+	}
+}
 export interface MCPRequestOptions {
 	/** Abort signal (e.g. Escape-to-interrupt) */
 	signal?: AbortSignal;
 	/** Shared lease policy: never retry the original request after transport/auth failure. */
 	noReplay?: boolean;
+	/**
+	 * Handler for modern MRTR `input_required` results (elicitation, roots, sampling).
+	 * When absent, an `input_required` result fails explicitly instead of hanging.
+	 */
+	inputHandler?: MCPInputRequestHandler;
+	/** Extra mirrored headers for modern requests (`Mcp-Param-*` from x-mcp-header bindings). */
+	mcpParamHeaders?: Record<string, string>;
+}
+
+// =============================================================================
+// MRTR (multi round-trip) input handling
+// =============================================================================
+
+/** Context for one server input request gathered during a modern MRTR exchange. */
+export interface MCPInputRequestContext {
+	/** Server being called. */
+	serverName: string;
+	/** Original client request method (`tools/call`, `prompts/get`, `resources/read`). */
+	originMethod: string;
+	/**
+	 * Stable correlation id shared by the initial request and its exactly-once
+	 * retry, fencing the accepted input to this exchange.
+	 */
+	correlationId: string;
+	/** Request-scoped abort signal (cancellation/timeout of the original call). */
+	signal?: AbortSignal;
 }
 
+/**
+ * Outcome of gathering one server input request. `result` values are placed in
+ * the retry's `inputResponses` under the request key. `failed` outcomes abort
+ * the MRTR exchange with an explicit error — except elicitation decline/cancel,
+ * which the handler expresses as an ElicitResult-shaped `result`.
+ */
+export type MCPInputRequestHandlerResult =
+	| { kind: "result"; result: unknown }
+	| { kind: "failed"; reason: "declined" | "cancelled" | "timeout" | "unavailable" | "error"; message?: string };
+
+/** Handler for one server input request inside an `input_required` result. */
+export type MCPInputRequestHandler = (
+	key: string,
+	request: { method: string; params?: Record<string, unknown> },
+	context: MCPInputRequestContext,
+) => Promise<MCPInputRequestHandlerResult>;
+
 /** Transport interface - abstracts stdio/http */
 export interface MCPTransport {
 	/** Send a request and wait for response */
@@ -300,6 +381,15 @@ export interface MCPServerConnection {
 	instructions?: string;
 	/** Cached prompts (populated on demand) */
 	prompts?: MCPPrompt[];
+	/**
+	 * Authoritative protocol observation for this connection (preference,
+	 * negotiated era/version, downgrade decision, deprecation state). Secret-free.
+	 */
+	protocol: MCPProtocolObservation;
+	/** Freshness deadline (ms epoch) for the cached tool catalog, from server ttlMs hints. */
+	toolsFreshUntil?: number;
+	/** Cache scope of the cached tool catalog; private entries never cross credential identities. */
+	toolsCacheScope?: "public" | "private";
 }
 
 /** MCP tool with server context */
@@ -341,13 +431,13 @@ export interface MCPResourceTemplate {
 }
 
 /** Result of resources/list */
-export interface MCPResourcesListResult {
+export interface MCPResourcesListResult extends MCPCacheHints {
 	resources: MCPResource[];
 	nextCursor?: string;
 }
 
 /** Result of resources/templates/list */
-export interface MCPResourceTemplatesListResult {
+export interface MCPResourceTemplatesListResult extends MCPCacheHints {
 	resourceTemplates: MCPResourceTemplate[];
 	nextCursor?: string;
 }
@@ -361,7 +451,7 @@ export interface MCPResourceContentItem {
 }
 
 /** Result of resources/read */
-export interface MCPResourceReadResult {
+export interface MCPResourceReadResult extends MCPCacheHints {
 	contents: MCPResourceContentItem[];
 }
 
@@ -395,7 +485,7 @@ export interface MCPPrompt {
 }
 
 /** Result of prompts/list */
-export interface MCPPromptsListResult {
+export interface MCPPromptsListResult extends MCPCacheHints {
 	prompts: MCPPrompt[];
 	nextCursor?: string;
 }
@@ -428,6 +518,27 @@ export interface MCPGetPromptResult {
 	messages: MCPPromptMessage[];
 }
 
+// =============================================================================
+// server/discover (modern era)
+// =============================================================================
+
+/** Result of the optional modern `server/discover` request. */
+export interface MCPDiscoverResult extends MCPCacheHints {
+	/** Protocol versions the server supports. */
+	supportedVersions: string[];
+	/** Capabilities the server supports. */
+	capabilities: MCPServerCapabilities;
+	/** Optional natural-language usage guidance. */
+	instructions?: string;
+	/** Result metadata; `io.modelcontextprotocol/serverInfo` carries the identity. */
+	_meta?: Record<string, unknown>;
+}
+
+/** Decoded `server/discover` payload with the extracted server identity. */
+export interface MCPDiscoverResultLite extends MCPDiscoverResult {
+	serverInfo?: MCPImplementation;
+}
+
 // =============================================================================
 // MCP Notification Method Names
 // =============================================================================