agents 0.19.0 → 0.20.1

package/dist/mcp/index.js

@@ -1,30 +1,24 @@
 import "../types.js";
-import { c as RPC_DO_PREFIX, i as normalizeServerId, n as MCP_SERVER_ID_MAX_LENGTH, o as RPCClientTransport, s as RPCServerTransport } from "../client-CcjiFpTf.js";
+import { c as RPC_DO_PREFIX, i as normalizeServerId, n as MCP_SERVER_ID_MAX_LENGTH, o as RPCClientTransport, s as RPCServerTransport } from "../client-zqKcsyFa.js";
 import { Agent, getAgentByName, getCurrentAgent } from "../index.js";
-import { AsyncLocalStorage } from "node:async_hooks";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { ElicitRequestSchema, InitializeRequestSchema, JSONRPCMessageSchema, isInitializeRequest, isJSONRPCErrorResponse, isJSONRPCNotification, isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { n as getMcpAuthContext, r as runWithAuthContext, t as createStatelessMcpHandler } from "../handler-stateless-CIkKPETH.js";
+import { SSEClientTransport, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { ElicitRequestSchema, InitializeRequestSchema, JSONRPCMessageSchema, SUPPORTED_PROTOCOL_VERSIONS, isInitializeRequest, isJSONRPCErrorResponse, isJSONRPCNotification, isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
+import { McpServer, Server } from "@modelcontextprotocol/server";
+import { McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport as WebStandardStreamableHTTPServerTransport$1 } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/mcp/sse-keepalive.ts
 /**
-* Shared SSE keepalive utility for MCP transports.
+* SSE keepalive for the retained McpAgent WebSocket-to-SSE bridge.
 *
-* Cloudflare's edge closes idle SSE responses after ~5 minutes. Writers
-* that may sit silent for that long (long-running tool calls, idle
-* standalone GET streams) arm a keepalive to keep the response under the
-* watchdog.
+* SDK-backed HTTP transports own their keepalive timers. This helper remains
+* only for the custom bridge, where long-running POST tool calls can otherwise
+* sit silent until Cloudflare's edge closes the idle stream.
 *
 * See cloudflare/agents#1583.
 */
-/** Interval between SSE keepalive comment frames, in ms.
-*
-* The WHATWG SSE spec recommends a comment line every "15 seconds or so"
-* (html.spec.whatwg.org §9.2.7). 25s gives comfortable headroom below
-* both the ~30s post-handler background-work cancellation window on
-* Workers and the ~5min Cloudflare edge idle-stream watchdog.
-*/
+/** Interval between bridge SSE keepalive comment frames, in ms. */
 const KEEPALIVE_INTERVAL_MS = 25e3;
 /** SSE comment frame the parser drops before any event dispatch. */
 const KEEPALIVE_FRAME = ": keepalive\n\n";
@@ -54,6 +48,18 @@ const MCP_HTTP_METHOD_HEADER = "cf-mcp-method";
 */
 const MCP_MESSAGE_HEADER = "cf-mcp-message";
 const MAXIMUM_MESSAGE_SIZE_BYTES = 4 * 1024 * 1024;
+function unsupportedProtocolVersionResponse(request) {
+	const protocolVersion = request.headers.get("mcp-protocol-version");
+	if (protocolVersion === null || SUPPORTED_PROTOCOL_VERSIONS.includes(protocolVersion)) return;
+	return Response.json({
+		error: {
+			code: -32e3,
+			message: `Bad Request: Unsupported protocol version: ${protocolVersion} (supported versions: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")})`
+		},
+		id: null,
+		jsonrpc: "2.0"
+	}, { status: 400 });
+}
 const createStreamingHttpHandler = (basePath, namespace, options = {}) => {
 	let pathname = basePath;
 	if (basePath === "/") pathname = "/*";
@@ -151,6 +157,10 @@ const createStreamingHttpHandler = (basePath, namespace, options = {}) => {
 					});
 					return new Response(body, { status: 400 });
 				}
+				if (!maybeInitializeRequest) {
+					const unsupportedVersion = unsupportedProtocolVersionResponse(request);
+					if (unsupportedVersion) return unsupportedVersion;
+				}
 				if (!maybeInitializeRequest && !sessionId) {
 					const body = JSON.stringify({
 						error: {
@@ -279,6 +289,8 @@ const createStreamingHttpHandler = (basePath, namespace, options = {}) => {
 					id: null,
 					jsonrpc: "2.0"
 				}), { status: 400 });
+				const unsupportedVersion = unsupportedProtocolVersionResponse(request);
+				if (unsupportedVersion) return unsupportedVersion;
 				const { readable, writable } = new TransformStream();
 				const writer = writable.getWriter();
 				const encoder = new TextEncoder();
@@ -338,6 +350,8 @@ const createStreamingHttpHandler = (basePath, namespace, options = {}) => {
 					status: 200
 				});
 			} else if (request.method === "DELETE") {
+				const unsupportedVersion = unsupportedProtocolVersionResponse(request);
+				if (unsupportedVersion) return unsupportedVersion;
 				const sessionId = request.headers.get("mcp-session-id");
 				if (!sessionId) return new Response(JSON.stringify({
 					jsonrpc: "2.0",
@@ -980,36 +994,36 @@ DurableObjectEventStore.REPLAY_LIMIT = 1e3;
 */
 let didWarnAboutSSEEdgeClientTransport = false;
 /**
-* @deprecated Use SSEClientTransport from @modelcontextprotocol/sdk/client/sse.js instead. This alias will be removed in the next major version.
+* @deprecated Use SSEClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
 */
 var SSEEdgeClientTransport = class extends SSEClientTransport {
 	constructor(url, options) {
 		super(url, options);
 		if (!didWarnAboutSSEEdgeClientTransport) {
 			didWarnAboutSSEEdgeClientTransport = true;
-			console.warn("SSEEdgeClientTransport is deprecated. Use SSEClientTransport from @modelcontextprotocol/sdk/client/sse.js instead. SSEEdgeClientTransport will be removed in the next major version.");
+			console.warn("SSEEdgeClientTransport is deprecated. Use SSEClientTransport from @modelcontextprotocol/client instead. SSEEdgeClientTransport will be removed in the next major version.");
 		}
 	}
 };
 let didWarnAboutStreamableHTTPEdgeClientTransport = false;
 /**
-* @deprecated Use StreamableHTTPClientTransport from @modelcontextprotocol/sdk/client/streamableHttp.js instead. This alias will be removed in the next major version.
+* @deprecated Use StreamableHTTPClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
 */
 var StreamableHTTPEdgeClientTransport = class extends StreamableHTTPClientTransport {
 	constructor(url, options) {
 		super(url, options);
 		if (!didWarnAboutStreamableHTTPEdgeClientTransport) {
 			didWarnAboutStreamableHTTPEdgeClientTransport = true;
-			console.warn("StreamableHTTPEdgeClientTransport is deprecated. Use StreamableHTTPClientTransport from @modelcontextprotocol/sdk/client/streamableHttp.js instead. StreamableHTTPEdgeClientTransport will be removed in the next major version.");
+			console.warn("StreamableHTTPEdgeClientTransport is deprecated. Use StreamableHTTPClientTransport from @modelcontextprotocol/client instead. StreamableHTTPEdgeClientTransport will be removed in the next major version.");
 		}
 	}
 };
 //#endregion
 //#region src/mcp/worker-transport.ts
 /**
-* WorkerTransport
+* WorkerTransport — retained sessionful Legacy transport
 *
-* Thin Cloudflare-Workers wrapper around the official MCP SDK
+* Thin Cloudflare-Workers wrapper around the official MCP SDK v1
 * `WebStandardStreamableHTTPServerTransport`. The wrapper layers a couple of
 * Workers-specific concerns on top of the SDK transport without forking it:
 *
@@ -1021,15 +1035,12 @@ var StreamableHTTPEdgeClientTransport = class extends StreamableHTTPClientTransp
 *     survive DO hibernation / eviction. On the first request after a cold
 *     start, the saved initialize params are replayed through the `Server`
 *     so client capabilities are re-established.
-*  3. **SSE keepalive** — SSE responses are wrapped in a TransformStream that
-*     injects a `: keepalive\n\n` comment frame every 25s so the Cloudflare
-*     edge ~5min idle-stream watchdog doesn't kill long-running tool calls.
-*     Disabled on the standalone GET stream when an `eventStore` is
-*     configured — clients recover idle drops via `Last-Event-ID` instead.
-*     POST response streams always keepalive (no resumption path during a
-*     mid-flight tool call). See cloudflare/agents#1583.
+*  3. **SSE keepalive** — delegated to the SDK transport, which writes SSE
+*     comment frames and owns timer cleanup. Configure the cadence with the
+*     inherited `keepAliveMs` option.
 *
-* Everything else (session validation, SSE streaming, protocol-version
+* Stateless handlers do not import this module. Everything else (session
+* validation, SSE streaming, protocol-version
 * negotiation, event-store resumability, etc.) is delegated to the SDK
 * transport.
 */
@@ -1042,7 +1053,7 @@ const DEFAULT_CORS_OPTIONS = {
 	exposeHeaders: "mcp-session-id",
 	maxAge: 86400
 };
-var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
+var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport$1 {
 	constructor(options = {}) {
 		const { corsOptions, storage, onsessioninitialized, ...sdkOptions } = options;
 		super({
@@ -1051,7 +1062,6 @@ var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
 		});
 		this._stateRestored = false;
 		this._bridgeInstalled = false;
-		this._keepaliveCleanups = /* @__PURE__ */ new Map();
 		this._closedRequestIds = /* @__PURE__ */ new Set();
 		this._corsOptions = corsOptions;
 		this._storage = storage;
@@ -1067,17 +1077,15 @@ var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
 	/**
 	* Top-level request entry point. Handles CORS preflight, restores any
 	* persisted state on first invocation, then delegates to the SDK transport
-	* and finally appends CORS headers + keepalive to whatever response comes
-	* back.
+	* and finally appends CORS headers to whatever response comes back.
 	*/
 	async handleRequest(request, options) {
 		if (request.method === "OPTIONS") return new Response(null, { headers: this.getCorsHeaders({ forPreflight: true }) });
 		await this.restoreState();
 		this.installOnSessionInitializedBridge();
 		await this.captureInitializeParams(request, options);
-		const requestIdForKeepalive = request.method === "GET" ? "_standalone" : this._pendingRequestId;
 		const response = await super.handleRequest(request, options);
-		return this.withCorsHeaders(this.withKeepalive(this.normalizeAllowHeader(response), requestIdForKeepalive));
+		return this.withCorsHeaders(this.normalizeAllowHeader(response));
 	}
 	/**
 	* The SDK's 405 responses advertise `Allow: GET, POST, DELETE` because
@@ -1097,19 +1105,10 @@ var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
 		});
 	}
 	closeSSEStream(requestId) {
-		this._keepaliveCleanups.get(requestId)?.();
-		this._keepaliveCleanups.delete(requestId);
 		this._closedRequestIds.add(requestId);
 		super.closeSSEStream(requestId);
 	}
-	closeStandaloneSSEStream() {
-		this._keepaliveCleanups.get("_standalone")?.();
-		this._keepaliveCleanups.delete("_standalone");
-		super.closeStandaloneSSEStream();
-	}
 	async close() {
-		for (const cleanup of Array.from(this._keepaliveCleanups.values())) cleanup();
-		this._keepaliveCleanups.clear();
 		this._closedRequestIds.clear();
 		await super.close();
 	}
@@ -1139,77 +1138,6 @@ var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
 		if (requestId !== void 0 && this._closedRequestIds.has(requestId)) return;
 		await super.send(message, options);
 	}
-	/**
-	* If the response is an SSE stream, tee the body through a TransformStream
-	* that injects a `: keepalive\n\n` comment frame every 25s. The interval
-	* is cleared when the wrapped stream closes — which happens both when the
-	* SDK ends the underlying stream naturally and when `closeSSEStream` is
-	* called.
-	*
-	* Keepalive policy:
-	*   - POST response streams (`key` is a request id): always keepalive.
-	*     In-progress tool calls have no recovery path — if the stream drops
-	*     mid-execution the result is lost — so we keep it under the
-	*     Cloudflare edge ~5min idle watchdog.
-	*   - Standalone GET stream (`key === "_standalone"`): keepalive only
-	*     when no `eventStore` is configured. When resumability is enabled,
-	*     clients reconnect with `Last-Event-ID` after an idle drop, so we
-	*     skip the keepalive and let the DO hibernate.
-	*
-	* Uses the shared `sse-keepalive` constants so both this wrapper and
-	* `McpAgent.serve()` write identical frames at the same cadence.
-	* See cloudflare/agents#1583.
-	*/
-	withKeepalive(response, key) {
-		if (!(response.headers.get("Content-Type") ?? "").includes("text/event-stream") || !response.body) return response;
-		if (key === "_standalone" && this.eventStoreConfigured()) return response;
-		const encoder = new TextEncoder();
-		let intervalId;
-		let controllerRef;
-		const clear = () => {
-			if (intervalId !== void 0) {
-				clearInterval(intervalId);
-				intervalId = void 0;
-			}
-			if (key !== void 0) this._keepaliveCleanups.delete(key);
-		};
-		const transform = new TransformStream({
-			start: (controller) => {
-				controllerRef = controller;
-				intervalId = setInterval(() => {
-					try {
-						controllerRef?.enqueue(encoder.encode(KEEPALIVE_FRAME));
-					} catch {
-						clear();
-					}
-				}, KEEPALIVE_INTERVAL_MS);
-				if (key !== void 0) this._keepaliveCleanups.set(key, clear);
-			},
-			transform(chunk, controller) {
-				controller.enqueue(chunk);
-			},
-			flush() {
-				clear();
-			},
-			cancel() {
-				clear();
-			}
-		});
-		const piped = response.body.pipeThrough(transform);
-		return new Response(piped, {
-			status: response.status,
-			statusText: response.statusText,
-			headers: response.headers
-		});
-	}
-	/**
-	* Does the SDK transport have an `eventStore`? Reaches into the SDK's
-	* private field because the option isn't surfaced on the public API —
-	* we only need a yes/no for keepalive policy.
-	*/
-	eventStoreConfigured() {
-		return this._eventStore !== void 0;
-	}
 	getCorsHeaders({ forPreflight } = {}) {
 		const merged = {
 			...DEFAULT_CORS_OPTIONS,
@@ -1245,19 +1173,15 @@ var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
 		this._bridgeInstalled = true;
 	}
 	async captureInitializeParams(request, handleOptions) {
-		this._pendingRequestId = void 0;
 		if (request.method !== "POST") return;
 		try {
 			const parsed = handleOptions?.parsedBody ?? await request.clone().json();
-			const messages = Array.isArray(parsed) ? parsed : [parsed];
-			const init = messages.find((m) => typeof m === "object" && m !== null && isInitializeRequest(m));
+			const init = (Array.isArray(parsed) ? parsed : [parsed]).find((m) => typeof m === "object" && m !== null && isInitializeRequest(m));
 			if (init && isInitializeRequest(init)) this._capturedInitializeParams = {
 				capabilities: init.params.capabilities,
 				clientInfo: init.params.clientInfo,
 				protocolVersion: init.params.protocolVersion
 			};
-			const firstRequest = messages.find((m) => typeof m === "object" && m !== null && "id" in m && "method" in m);
-			if (firstRequest) this._pendingRequestId = firstRequest.id;
 		} catch {}
 	}
 	async restoreState() {
@@ -1294,67 +1218,81 @@ var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
 	}
 };
 //#endregion
-//#region src/mcp/auth-context.ts
-const authContextStorage = new AsyncLocalStorage();
-function getMcpAuthContext() {
-	return authContextStorage.getStore();
-}
-function runWithAuthContext(context, fn) {
-	return authContextStorage.run(context, fn);
-}
-//#endregion
-//#region src/mcp/handler.ts
-function createMcpHandler(server, options = {}) {
+//#region src/mcp/handler-legacy.ts
+/**
+* Create a sessionful Legacy MCP handler backed by SDK v1.
+*
+* New Stateless servers should use `createMcpHandler` from
+* `agents/mcp/server` instead.
+*/
+function createLegacyMcpHandler(server, options = {}) {
 	const route = options.route ?? "/mcp";
 	const { route: _route, authContext, transport: providedTransport, ...transportOptions } = options;
 	return async (request, _env, ctx) => {
 		const url = new URL(request.url);
 		if (route && url.pathname !== route) return new Response("Not Found", { status: 404 });
 		const transport = providedTransport ?? new WorkerTransport(transportOptions);
-		const buildAuthContext = () => {
-			if (authContext) return authContext;
-			if (ctx.props && Object.keys(ctx.props).length > 0) return { props: ctx.props };
-		};
-		const handleRequest = async () => {
-			return await transport.handleRequest(request);
-		};
-		const resolvedAuthContext = buildAuthContext();
+		const resolvedAuthContext = authContext ?? (ctx.props && Object.keys(ctx.props).length > 0 ? { props: ctx.props } : void 0);
 		if (!transport.started) {
-			if (server instanceof McpServer ? server.isConnected() : server.transport !== void 0) throw new Error("Server is already connected to a transport. Create a new McpServer instance per request for stateless handlers.");
+			if (server instanceof McpServer$1 ? server.isConnected() : server.transport !== void 0) throw new Error("Server is already connected to a transport. Create a new McpServer instance per request for stateless handlers.");
 			await server.connect(transport);
 		}
+		const handleRequest = () => transport.handleRequest(request);
 		try {
-			if (resolvedAuthContext) return await runWithAuthContext(resolvedAuthContext, handleRequest);
-			else return await handleRequest();
+			return resolvedAuthContext ? await runWithAuthContext(resolvedAuthContext, handleRequest) : await handleRequest();
 		} catch (error) {
 			console.error("MCP handler error:", error);
-			return new Response(JSON.stringify({
+			return Response.json({
 				jsonrpc: "2.0",
 				error: {
 					code: -32603,
 					message: error instanceof Error ? error.message : "Internal server error"
 				},
 				id: null
-			}), {
-				status: 500,
-				headers: { "Content-Type": "application/json" }
-			});
+			}, { status: 500 });
 		}
 	};
 }
+//#endregion
+//#region src/mcp/handler-warning.ts
+let didWarnAboutLegacyCreateMcpHandlerOverload = false;
+function warnLegacyCreateMcpHandlerOverload() {
+	if (didWarnAboutLegacyCreateMcpHandlerOverload) return;
+	didWarnAboutLegacyCreateMcpHandlerOverload = true;
+	console.warn("[agents/mcp] Passing an MCP SDK v1 server to createMcpHandler is deprecated and will be removed in the next major version. Pass an @modelcontextprotocol/server factory to createMcpHandler. To temporarily retain sessionful SDK v1 behavior while migrating, use createLegacyMcpHandler.");
+}
+//#endregion
+//#region src/mcp/handler-compat.ts
+function createMcpHandler(serverOrFactory, options = {}) {
+	if (typeof serverOrFactory === "function") return createStatelessMcpHandler(serverOrFactory, options);
+	if (serverOrFactory instanceof McpServer$1 || serverOrFactory instanceof Server$1) {
+		warnLegacyCreateMcpHandlerOverload();
+		return createLegacyMcpHandler(serverOrFactory, options);
+	}
+	throw new TypeError("createMcpHandler received an unsupported server. Pass a factory returning McpServer or Server from \"@modelcontextprotocol/server\", or use createLegacyMcpHandler with an MCP SDK v1 server.");
+}
 let didWarnAboutExperimentalCreateMcpHandler = false;
 /**
-* @deprecated This has been renamed to createMcpHandler, and experimental_createMcpHandler will be removed in the next major version
+* @deprecated Pass an SDK v2 factory to createMcpHandler.
+* experimental_createMcpHandler will be removed in the next major version.
+* Use createLegacyMcpHandler only to temporarily retain sessionful SDK v1
+* behavior while migrating.
 */
 function experimental_createMcpHandler(server, options = {}) {
 	if (!didWarnAboutExperimentalCreateMcpHandler) {
 		didWarnAboutExperimentalCreateMcpHandler = true;
-		console.warn("experimental_createMcpHandler is deprecated, use createMcpHandler instead. experimental_createMcpHandler will be removed in the next major version.");
+		console.warn("experimental_createMcpHandler is deprecated and will be removed in the next major version. Pass an @modelcontextprotocol/server factory to createMcpHandler. To temporarily retain sessionful SDK v1 behavior while migrating, use createLegacyMcpHandler.");
 	}
-	return createMcpHandler(server, options);
+	return createLegacyMcpHandler(server, options);
 }
 //#endregion
-//#region src/mcp/index.ts
+//#region src/mcp/legacy-agent.ts
+/**
+* @deprecated McpAgent is feature-frozen. Migrate to an SDK v2 factory with
+* createMcpHandler from agents/mcp/server. When sessionful features prevent an
+* immediate migration, run the stateless route beside the existing McpAgent
+* route until clients transition and sessions drain.
+*/
 var McpAgent = class McpAgent extends Agent {
 	constructor(..._args) {
 		super(..._args);
@@ -1502,6 +1440,7 @@ var McpAgent = class McpAgent extends Agent {
 		else this.props = await this.ctx.storage.get("props");
 		await this.init();
 		const server = await this.server;
+		if (server instanceof McpServer || server instanceof Server) throw new TypeError("McpAgent uses MCP SDK v1 and cannot serve McpServer from \"@modelcontextprotocol/server\". For MCP SDK v2, use createMcpHandler. Existing McpAgent applications should continue importing McpServer from \"@modelcontextprotocol/sdk/server/mcp.js\".");
 		this._transport = this.initTransport();
 		if (!this._transport) throw new Error("Failed to initialize transport");
 		await server.connect(this._transport);
@@ -1698,6 +1637,6 @@ var McpAgent = class McpAgent extends Agent {
 };
 McpAgent.STREAM_REQS_KEY_PREFIX = "__mcp_stream_reqs__:";
 //#endregion
-export { DurableObjectEventStore, ElicitRequestSchema, MCP_SERVER_ID_MAX_LENGTH, McpAgent, RPCClientTransport, RPCServerTransport, RPC_DO_PREFIX, SSEEdgeClientTransport, StreamableHTTPEdgeClientTransport, WorkerTransport, createMcpHandler, experimental_createMcpHandler, getMcpAuthContext, normalizeServerId };
+export { DurableObjectEventStore, ElicitRequestSchema, MCP_SERVER_ID_MAX_LENGTH, McpAgent, RPCClientTransport, RPCServerTransport, RPC_DO_PREFIX, SSEEdgeClientTransport, StreamableHTTPEdgeClientTransport, WorkerTransport, createLegacyMcpHandler, createMcpHandler, experimental_createMcpHandler, getMcpAuthContext, normalizeServerId };
 
 //# sourceMappingURL=index.js.map