agents 0.17.3 → 0.17.4

package/dist/{client-BZ-B3NhC.js → client-C7F0MaVz.js}

@@ -2,9 +2,9 @@ import { tryN } from "./retries.js";
 import { DurableObjectOAuthClientProvider } from "./mcp/do-oauth-client-provider.js";
 import { nanoid } from "nanoid";
 import { getServerByName } from "partyserver";
-import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker-provider.js";
 import { z } from "zod";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker-provider.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { ElicitRequestSchema, JSONRPCMessageSchema, PromptListChangedNotificationSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, isJSONRPCErrorResponse, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
@@ -282,6 +282,7 @@ var RPCServerTransport = class {
 };
 //#endregion
 //#region src/mcp/client-connection.ts
+const defaultClientOptions = { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() };
 /**
 * Connection state machine for MCP client connections.
 *
@@ -304,12 +305,21 @@ const MCPConnectionState = {
 	/** Connection failed at some point */
 	FAILED: "failed"
 };
+/** Derive the elicitation capability to advertise from the handler keys. */
+function elicitationCapabilitiesFromHandlers(handlers) {
+	if (!handlers) return void 0;
+	const elicitation = {};
+	if (handlers.form) elicitation.form = {};
+	if (handlers.url) elicitation.url = {};
+	return elicitation.form || elicitation.url ? elicitation : void 0;
+}
 var MCPClientConnection = class {
-	constructor(url, info, options = {
+	constructor(url, _info, options = {
 		client: {},
 		transport: {}
 	}) {
 		this.url = url;
+		this._info = _info;
 		this.options = options;
 		this.connectionState = MCPConnectionState.CONNECTING;
 		this.connectionError = null;
@@ -320,14 +330,44 @@ var MCPClientConnection = class {
 		this._probingCapabilities = false;
 		this._onObservabilityEvent = new Emitter();
 		this.onObservabilityEvent = this._onObservabilityEvent.event;
+		this._elicitationEnabled = false;
+		this.options = {
+			...options,
+			client: {
+				...defaultClientOptions,
+				...options.client
+			}
+		};
+		this.client = this.createClient();
+	}
+	createClient() {
+		const seed = this.options.capabilitySeed;
+		const elicitation = this.options.client?.capabilities?.elicitation ?? elicitationCapabilitiesFromHandlers(this.options.elicitationHandlers) ?? seed?.elicitation;
+		this._elicitationEnabled = elicitation !== void 0;
 		const clientOptions = {
-			...options.client,
+			...this.options.client,
 			capabilities: {
-				...options.client?.capabilities,
-				elicitation: {}
+				...seed,
+				...this.options.client?.capabilities,
+				...elicitation ? { elicitation } : {}
 			}
 		};
-		this.client = new Client(info, clientOptions);
+		return new Client(this._info, clientOptions);
+	}
+	/**
+	* Configure the handler used for server-initiated elicitation requests.
+	*
+	* If the connection has not been initialized yet, rebuild the SDK client so
+	* handler-driven elicitation capabilities are reflected in the initial
+	* handshake. A rebuild (rather than `Client.registerCapabilities`) is
+	* required because SDK capability registration is merge-only — it cannot
+	* un-advertise a mode when handlers are cleared before connecting. Active
+	* connections keep their negotiated capabilities until they reconnect.
+	*/
+	configureElicitationHandlers(handlers) {
+		this.options.elicitationHandlers = handlers;
+		this.options.capabilitySeed = void 0;
+		if (!this.client.transport) this.client = this.createClient();
 	}
 	/**
 	* Initialize a client connection, if authentication is required, the connection will be in the AUTHENTICATING state
@@ -343,11 +383,12 @@ var MCPClientConnection = class {
 			try {
 				await this.client.close();
 			} catch {}
+			this.client = this.createClient();
 		}
 		const res = await this.tryConnect(transportType);
 		this.connectionState = res.state;
 		if (res.state === MCPConnectionState.CONNECTED && res.transport) {
-			this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
+			if (this._elicitationEnabled) this.client.setRequestHandler(ElicitRequestSchema, async (request) => {
 				return await this.handleElicitationRequest(request);
 			});
 			this.lastConnectedTransport = res.transport;
@@ -634,11 +675,19 @@ var MCPClientConnection = class {
 		return templatesAgg;
 	}
 	/**
-	* Handle elicitation request from server
-	* Automatically uses the Agent's built-in elicitation handling if available
+	* Handle elicitation request from server.
+	*
+	* Delegates to the `elicitationHandlers` connection option when provided.
+	*
+	* @deprecated Overriding or instance-patching this method directly is
+	* deprecated — pass the `elicitationHandlers` connection option instead.
 	*/
-	async handleElicitationRequest(_request) {
-		throw new Error("Elicitation handler must be implemented for your platform. Override handleElicitationRequest method.");
+	async handleElicitationRequest(request) {
+		const mode = request.params.mode === "url" ? "url" : "form";
+		const handler = this.options.elicitationHandlers?.[mode];
+		if (handler) return handler(request);
+		if (this.options.elicitationHandlers) throw new Error(`No MCP ${mode}-mode elicitation handler configured for this connection.`);
+		throw new Error("Elicitation handler must be implemented for your platform. Provide the MCPClientConnection elicitationHandlers option, or register handlers through the MCP client manager before connecting.");
 	}
 	isResumedStreamableHttpSession() {
 		return this._transport instanceof StreamableHTTPClientTransport && typeof this._transport.sessionId === "string";
@@ -764,7 +813,6 @@ var MCPClientConnection = class {
 };
 //#endregion
 //#region src/mcp/client.ts
-const defaultClientOptions = { jsonSchemaValidator: new CfWorkerJsonSchemaValidator() };
 /** Maximum length of a normalized MCP server id. */
 const MCP_SERVER_ID_MAX_LENGTH = 64;
 /**
@@ -912,6 +960,21 @@ var MCPClientManager = class {
 		this._storage = options.storage;
 		this._createAuthProviderFn = options.createAuthProvider;
 	}
+	/**
+	* Scope the manager-level elicitation handler to a single connection.
+	* Returns undefined when no handler is configured so the connection keeps
+	* its default throwing behavior.
+	*/
+	scopedElicitationHandlers(serverId) {
+		const handlers = this._elicitationHandlers;
+		if (!handlers) return void 0;
+		const form = handlers.form;
+		const url = handlers.url;
+		return {
+			form: form ? (request) => form(request, serverId) : void 0,
+			url: url ? (request) => url(request, serverId) : void 0
+		};
+	}
 	sql(query, ...bindings) {
 		return [...this._storage.sql.exec(query, ...bindings)];
 	}
@@ -979,6 +1042,8 @@ var MCPClientManager = class {
 			delete this.mcpConnections[oldId];
 			const authProvider = conn.options.transport.authProvider;
 			if (authProvider) authProvider.serverId = newId;
+			const scoped = this.scopedElicitationHandlers(newId);
+			if (scoped) conn.configureElicitationHandlers(scoped);
 		}
 		const disposables = this._connectionDisposables.get(oldId);
 		if (disposables) {
@@ -1007,12 +1072,37 @@ var MCPClientManager = class {
 		}));
 	}
 	/**
-	* Get the retry options for a server from stored server_options
+	* Get the parsed server_options for a stored server, if any.
 	*/
-	getServerRetryOptions(serverId) {
+	getStoredServerOptions(serverId) {
 		const rows = this.sql("SELECT server_options FROM cf_agents_mcp_servers WHERE id = ?", serverId);
 		if (!rows.length || !rows[0].server_options) return void 0;
-		return JSON.parse(rows[0].server_options).retry;
+		return JSON.parse(rows[0].server_options);
+	}
+	/**
+	* Clear the capabilities persisted on a stored server row. Called once a
+	* seeded connection's handshake completes (see `createConnection`): the
+	* stamp is valid for one successful restore — sessions that configure
+	* handlers re-stamp every row, so a deploy that stops configuring them
+	* stops advertising stale modes after its first connected wake instead of
+	* forever, while wakes that never handshake don't burn the stamp.
+	*/
+	clearStoredCapabilities(serverId) {
+		const row = this.sql("SELECT id, name, server_url, client_id, auth_url, callback_url, server_options FROM cf_agents_mcp_servers WHERE id = ?", serverId)[0];
+		if (!row?.server_options) return;
+		const options = JSON.parse(row.server_options);
+		if (!options.capabilities) return;
+		options.capabilities = void 0;
+		this.saveServerToStorage({
+			...row,
+			server_options: JSON.stringify(options)
+		});
+	}
+	/**
+	* Get the retry options for a server from stored server_options
+	*/
+	getServerRetryOptions(serverId) {
+		return this.getStoredServerOptions(serverId)?.retry;
 	}
 	clearServerAuthUrl(serverId) {
 		this.sql("UPDATE cf_agents_mcp_servers SET auth_url = NULL WHERE id = ?", serverId);
@@ -1129,7 +1219,8 @@ var MCPClientManager = class {
 			callback_url: "",
 			server_options: JSON.stringify({
 				bindingName,
-				props
+				props,
+				capabilities: this.advertisedHandlerCapabilities()
 			})
 		});
 	}
@@ -1166,6 +1257,7 @@ var MCPClientManager = class {
 				}
 			}
 			const parsedOptions = server.server_options ? JSON.parse(server.server_options) : null;
+			if (parsedOptions?.client) delete parsedOptions.client.jsonSchemaValidator;
 			let authProvider;
 			if (server.callback_url) {
 				authProvider = this._createAuthProviderFn ? this._createAuthProviderFn(server.callback_url) : this.createAuthProvider(server.id, server.callback_url, clientName, server.client_id ?? void 0);
@@ -1257,24 +1349,11 @@ var MCPClientManager = class {
 		}
 		if (isBlockedUrl(url)) throw new Error(`Blocked URL: ${url} — MCP client connections to private/internal addresses are not allowed`);
 		if (!options.reconnect?.oauthCode || !this.mcpConnections[id]) {
-			const normalizedTransport = {
-				...options.transport,
-				type: options.transport?.type ?? "auto"
-			};
-			this.mcpConnections[id] = new MCPClientConnection(new URL(url), {
-				name: this._name,
-				version: this._version
-			}, {
-				client: options.client ?? {},
-				transport: normalizedTransport
+			delete this.mcpConnections[id];
+			this.createConnection(id, url, {
+				client: options.client,
+				transport: options.transport ?? {}
 			});
-			const store = new DisposableStore();
-			const existing = this._connectionDisposables.get(id);
-			if (existing) existing.dispose();
-			this._connectionDisposables.set(id, store);
-			store.add(this.mcpConnections[id].onObservabilityEvent((event) => {
-				this._onObservabilityEvent.fire(event);
-			}));
 		}
 		await this.mcpConnections[id].init();
 		if (options.reconnect?.oauthCode) try {
@@ -1326,15 +1405,15 @@ var MCPClientManager = class {
 			...options.transport,
 			type: options.transport?.type ?? "auto"
 		};
+		const capabilitySeed = this.getStoredServerOptions(id)?.capabilities;
 		this.mcpConnections[id] = new MCPClientConnection(new URL(url), {
 			name: this._name,
 			version: this._version
 		}, {
-			client: {
-				...defaultClientOptions,
-				...options.client
-			},
-			transport: normalizedTransport
+			client: options.client ?? {},
+			transport: normalizedTransport,
+			elicitationHandlers: this.scopedElicitationHandlers(id),
+			capabilitySeed
 		});
 		const store = new DisposableStore();
 		const existing = this._connectionDisposables.get(id);
@@ -1343,6 +1422,17 @@ var MCPClientManager = class {
 		store.add(this.mcpConnections[id].onObservabilityEvent((event) => {
 			this._onObservabilityEvent.fire(event);
 		}));
+		if (capabilitySeed) {
+			const conn = this.mcpConnections[id];
+			const seedClear = conn.onObservabilityEvent((event) => {
+				if (event.type !== "mcp:client:connect" || event.payload.state !== MCPConnectionState.CONNECTED) return;
+				seedClear.dispose();
+				if (this._elicitationHandlers || !conn.options.capabilitySeed) return;
+				const currentId = Object.keys(this.mcpConnections).find((key) => this.mcpConnections[key] === conn);
+				if (currentId) this.clearStoredCapabilities(currentId);
+			});
+			store.add(seedClear);
+		}
 		return this.mcpConnections[id];
 	}
 	/**
@@ -1363,6 +1453,7 @@ var MCPClientManager = class {
 			}
 		});
 		const { authProvider: _, ...transportWithoutAuth } = options.transport ?? {};
+		const { jsonSchemaValidator: _validator, ...serializableClient } = options.client ?? {};
 		this.saveServerToStorage({
 			id,
 			name: options.name,
@@ -1371,9 +1462,10 @@ var MCPClientManager = class {
 			client_id: options.clientId ?? null,
 			auth_url: options.authUrl ?? null,
 			server_options: JSON.stringify({
-				client: options.client,
+				client: serializableClient,
 				transport: transportWithoutAuth,
-				retry: options.retry
+				retry: options.retry,
+				capabilities: this.advertisedHandlerCapabilities()
 			})
 		});
 		this._onServerStateChanged.fire();
@@ -1649,6 +1741,51 @@ var MCPClientManager = class {
 		this._oauthCallbackConfig = config;
 	}
 	/**
+	* Configure handling for server-initiated `elicitation/create` requests.
+	*
+	* The handler is held in memory only and applied to every MCP connection
+	* created or restored by this manager. Call this before registering
+	* connections when you want the initial MCP handshake to advertise
+	* handler-driven form- and url-mode elicitation. Existing active connections
+	* keep their negotiated capabilities until they reconnect.
+	*
+	* The advertised modes are persisted with each stored server, so
+	* connections restored after hibernation re-advertise them at the handshake
+	* even when this is called later in the wake-up (e.g. from onStart) — the
+	* handlers attach to the live connections as soon as this runs.
+	*
+	* Pass undefined to clear the handler.
+	*
+	* @param handlers Elicitation handlers keyed by mode, each scoped with the server id that sent the request
+	*/
+	configureElicitationHandlers(handlers) {
+		this._elicitationHandlers = handlers && (handlers.form || handlers.url) ? handlers : void 0;
+		this.persistAdvertisedCapabilities();
+		for (const [id, connection] of Object.entries(this.mcpConnections)) connection.configureElicitationHandlers(this.scopedElicitationHandlers(id));
+	}
+	/** Client capabilities advertised from the currently configured handlers. */
+	advertisedHandlerCapabilities() {
+		const elicitation = elicitationCapabilitiesFromHandlers(this._elicitationHandlers);
+		return elicitation ? { elicitation } : void 0;
+	}
+	/**
+	* Record the handler-derived capabilities on every stored server row so a
+	* restore after hibernation re-advertises them before the handlers
+	* themselves are reconfigured.
+	*/
+	persistAdvertisedCapabilities() {
+		const capabilities = this.advertisedHandlerCapabilities();
+		for (const server of this.getServersFromStorage()) {
+			const options = server.server_options ? JSON.parse(server.server_options) : {};
+			if (JSON.stringify(options.capabilities) === JSON.stringify(capabilities)) continue;
+			options.capabilities = capabilities;
+			this.saveServerToStorage({
+				...server,
+				server_options: JSON.stringify(options)
+			});
+		}
+	}
+	/**
 	* Get the current OAuth callback configuration
 	* @returns The current OAuth callback configuration
 	*/
@@ -1845,4 +1982,4 @@ function getNamespacedData(mcpClients, type) {
 //#endregion
 export { MCPConnectionState as a, RPC_DO_PREFIX as c, normalizeServerId as i, DisposableStore as l, MCP_SERVER_ID_MAX_LENGTH as n, RPCClientTransport as o, getNamespacedData as r, RPCServerTransport as s, MCPClientManager as t };
 
-//# sourceMappingURL=client-BZ-B3NhC.js.map
+//# sourceMappingURL=client-C7F0MaVz.js.map