agents 0.11.2 → 0.11.4

package/dist/experimental/webmcp.d.ts

@@ -0,0 +1,212 @@
+//#region src/experimental/webmcp.d.ts
+/**
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ * !! WARNING: EXPERIMENTAL — DO NOT USE IN PRODUCTION                  !!
+ * !!                                                                   !!
+ * !! This API is under active development and WILL break between       !!
+ * !! releases. Google's WebMCP API (navigator.modelContext) is still   !!
+ * !! in early preview and subject to change.                           !!
+ * !!                                                                   !!
+ * !! If you use this, pin your agents version and expect to rewrite    !!
+ * !! your code when upgrading.                                         !!
+ * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+ *
+ * WebMCP adapter for Cloudflare Agents SDK.
+ *
+ * Bridges tools registered on an McpAgent server to Chrome's native
+ * navigator.modelContext API, so browser-native agents can discover
+ * and call them without extra infrastructure.
+ *
+ * @example Bridge a remote McpAgent endpoint into the page
+ * ```ts
+ * import { registerWebMcp } from "agents/experimental/webmcp";
+ *
+ * const handle = await registerWebMcp({ url: "/mcp" });
+ *
+ * // Later, to clean up:
+ * await handle.dispose();
+ * ```
+ *
+ * @example Mix in-page tools with bridged tools (recommended pattern)
+ * ```ts
+ * import { registerWebMcp } from "agents/experimental/webmcp";
+ *
+ * // 1. Register page-local tools — things only the page can do
+ * navigator.modelContext?.registerTool({
+ *   name: "scroll_to_section",
+ *   description: "Scroll the page to a named section",
+ *   inputSchema: {
+ *     type: "object",
+ *     properties: { id: { type: "string" } },
+ *     required: ["id"]
+ *   },
+ *   async execute({ id }) {
+ *     document.getElementById(String(id))?.scrollIntoView({ behavior: "smooth" });
+ *     return "ok";
+ *   }
+ * });
+ *
+ * // 2. Bridge server tools — things that need durable storage / auth / DB access
+ * const handle = await registerWebMcp({
+ *   url: "/mcp",
+ *   prefix: "remote.",            // optional namespace to avoid collisions
+ *   getHeaders: async () => ({ Authorization: `Bearer ${await getToken()}` })
+ * });
+ *
+ * // The browser AI sees both kinds of tools side by side.
+ * ```
+ *
+ * @experimental This API is not yet stable and may change.
+ */
+interface ModelContextToolAnnotations {
+  readOnlyHint?: boolean;
+}
+interface ModelContextClient {
+  requestUserInteraction(callback: () => Promise<unknown>): Promise<unknown>;
+}
+interface ModelContextTool {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  execute: (input: Record<string, unknown>, client: ModelContextClient) => Promise<unknown>;
+  annotations?: ModelContextToolAnnotations;
+}
+interface ModelContextRegisterToolOptions {
+  signal?: AbortSignal;
+}
+interface ModelContext {
+  registerTool(tool: ModelContextTool, options?: ModelContextRegisterToolOptions): void;
+}
+declare global {
+  interface Navigator {
+    modelContext?: ModelContext;
+  }
+}
+interface McpTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  annotations?: {
+    readOnlyHint?: boolean;
+  };
+}
+/**
+ * Logger interface for adapter diagnostics. Defaults to `console`.
+ * Pass a no-op implementation (or `quiet: true`) to silence output.
+ */
+interface WebMcpLogger {
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+interface WebMcpOptions {
+  /** URL of the MCP endpoint (absolute or relative, e.g. `"/mcp"`). */
+  url: string;
+  /**
+   * Additional headers to include in every request to the MCP server.
+   * Useful for static authentication (e.g. `{ Authorization: "Bearer <token>" }`).
+   */
+  headers?: Record<string, string>;
+  /**
+   * Async function that returns headers for each request.
+   * Called before every request, useful for tokens that refresh.
+   * If both `headers` and `getHeaders` are provided, they are merged
+   * with `getHeaders` values taking precedence.
+   */
+  getHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+  /**
+   * If true, listen for `tools/list_changed` notifications and re-sync
+   * tools with `navigator.modelContext`. The adapter opens an SSE GET to
+   * the MCP endpoint to receive notifications; servers that don't support
+   * server-initiated streams (e.g. respond `405` on GET) gracefully degrade.
+   * @default true
+   */
+  watch?: boolean;
+  /**
+   * Optional namespace prefix prepended to every tool name registered with
+   * `navigator.modelContext`. Useful when bridging multiple MCP servers, or
+   * when the page also registers in-page tools and you want to avoid
+   * collisions. The original (unprefixed) name is still used on the wire
+   * when calling the server.
+   *
+   * @example `prefix: "remote."` turns `search` into `remote.search`.
+   */
+  prefix?: string;
+  /**
+   * Per-request timeout (in milliseconds) applied to `tools/list` and
+   * `tools/call`. If the server doesn't respond in time, the request is
+   * aborted and the resulting error is surfaced through the normal error
+   * paths (`onError` for sync, rejection for tool execution).
+   */
+  timeoutMs?: number;
+  /**
+   * Custom logger. Defaults to `console` with a `[webmcp-adapter]` prefix.
+   * Pass `{ info: () => {}, warn: () => {}, error: () => {} }` to silence.
+   */
+  logger?: WebMcpLogger;
+  /** Convenience shortcut for `logger: SILENT_LOGGER`. @default false */
+  quiet?: boolean;
+  /**
+   * Called whenever the adapter performs a successful sync (initial load
+   * and on `tools/list_changed`). Receives the tools as the server returned
+   * them (with their original, unprefixed names).
+   */
+  onSync?: (tools: McpTool[]) => void;
+  /**
+   * Called when an error occurs during background work that the caller
+   * cannot otherwise observe — specifically: a watch-mode re-sync failure.
+   *
+   * **Not** called for:
+   * - Initialization failures (those reject the `registerWebMcp` promise).
+   * - Per-tool execution failures (those reject the `execute` promise the
+   *   browser host awaits; Chrome surfaces them to the AI).
+   */
+  onError?: (error: Error) => void;
+}
+interface WebMcpHandle {
+  /**
+   * Currently registered tool names (with `prefix` applied). Returns a fresh
+   * snapshot on each access — safe to mutate.
+   */
+  readonly tools: ReadonlyArray<string>;
+  /**
+   * Re-fetch the tool list from the server and re-register everything.
+   * If a sync is already in flight (from a `tools/list_changed` notification
+   * or a previous `refresh()` call), returns the in-flight promise rather
+   * than starting a second sync.
+   */
+  refresh(): Promise<void>;
+  /**
+   * Unregister all tools, signal any in-flight work to abort, and close the
+   * MCP connection. Safe to call multiple times.
+   */
+  dispose(): Promise<void>;
+  /** True after `dispose()` has been called at least once. */
+  readonly disposed: boolean;
+}
+/**
+ * Discovers tools from a Cloudflare McpAgent endpoint and registers them
+ * with Chrome's native `navigator.modelContext` API.
+ *
+ * On browsers without `navigator.modelContext` (everything except recent
+ * Chrome with the relevant flags), this function is a no-op and returns a
+ * handle with an empty tools array. No network request is made.
+ *
+ * @example
+ * ```ts
+ * import { registerWebMcp } from "agents/experimental/webmcp";
+ *
+ * const handle = await registerWebMcp({ url: "/mcp" });
+ * console.log("Registered tools:", handle.tools);
+ *
+ * // Clean up when done (e.g. in a React effect cleanup)
+ * await handle.dispose();
+ * ```
+ *
+ * See the JSDoc on the module itself for the recommended "in-page tools +
+ * remote tools" composition pattern.
+ */
+declare function registerWebMcp(options: WebMcpOptions): Promise<WebMcpHandle>;
+//#endregion
+export { WebMcpHandle, WebMcpLogger, WebMcpOptions, registerWebMcp };
+//# sourceMappingURL=webmcp.d.ts.map

package/dist/experimental/webmcp.js

@@ -0,0 +1,298 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+//#region src/experimental/webmcp.ts
+/**
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+* !! WARNING: EXPERIMENTAL — DO NOT USE IN PRODUCTION                  !!
+* !!                                                                   !!
+* !! This API is under active development and WILL break between       !!
+* !! releases. Google's WebMCP API (navigator.modelContext) is still   !!
+* !! in early preview and subject to change.                           !!
+* !!                                                                   !!
+* !! If you use this, pin your agents version and expect to rewrite    !!
+* !! your code when upgrading.                                         !!
+* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+*
+* WebMCP adapter for Cloudflare Agents SDK.
+*
+* Bridges tools registered on an McpAgent server to Chrome's native
+* navigator.modelContext API, so browser-native agents can discover
+* and call them without extra infrastructure.
+*
+* @example Bridge a remote McpAgent endpoint into the page
+* ```ts
+* import { registerWebMcp } from "agents/experimental/webmcp";
+*
+* const handle = await registerWebMcp({ url: "/mcp" });
+*
+* // Later, to clean up:
+* await handle.dispose();
+* ```
+*
+* @example Mix in-page tools with bridged tools (recommended pattern)
+* ```ts
+* import { registerWebMcp } from "agents/experimental/webmcp";
+*
+* // 1. Register page-local tools — things only the page can do
+* navigator.modelContext?.registerTool({
+*   name: "scroll_to_section",
+*   description: "Scroll the page to a named section",
+*   inputSchema: {
+*     type: "object",
+*     properties: { id: { type: "string" } },
+*     required: ["id"]
+*   },
+*   async execute({ id }) {
+*     document.getElementById(String(id))?.scrollIntoView({ behavior: "smooth" });
+*     return "ok";
+*   }
+* });
+*
+* // 2. Bridge server tools — things that need durable storage / auth / DB access
+* const handle = await registerWebMcp({
+*   url: "/mcp",
+*   prefix: "remote.",            // optional namespace to avoid collisions
+*   getHeaders: async () => ({ Authorization: `Bearer ${await getToken()}` })
+* });
+*
+* // The browser AI sees both kinds of tools side by side.
+* ```
+*
+* @experimental This API is not yet stable and may change.
+*/
+const DEFAULT_LOGGER = {
+	info: (...args) => console.info("[webmcp-adapter]", ...args),
+	warn: (...args) => console.warn("[webmcp-adapter]", ...args),
+	error: (...args) => console.error("[webmcp-adapter]", ...args)
+};
+const SILENT_LOGGER = {
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+var McpHttpClient = class {
+	constructor(url, headers, getHeaders, timeoutMs) {
+		const resolvedUrl = new URL(url, globalThis.location?.origin);
+		this._timeoutMs = timeoutMs;
+		const transportOptions = { requestInit: { headers: headers ?? {} } };
+		if (getHeaders) transportOptions.fetch = async (input, init) => {
+			const dynamic = await getHeaders();
+			const merged = new Headers(init?.headers);
+			for (const [k, v] of Object.entries(dynamic)) merged.set(k, v);
+			return globalThis.fetch(input, {
+				...init,
+				headers: merged
+			});
+		};
+		this._transport = new StreamableHTTPClientTransport(resolvedUrl, transportOptions);
+		this._client = new Client({
+			name: "webmcp-adapter",
+			version: "0.1.0"
+		}, { capabilities: {} });
+	}
+	async initialize(signal) {
+		await this._client.connect(this._transport);
+		this._client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+			if (signal?.aborted) return;
+			this._onToolsChanged?.();
+		});
+	}
+	async listTools(signal) {
+		const allTools = [];
+		let cursor;
+		do {
+			if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+			const result = await this._client.listTools(cursor ? { cursor } : void 0, {
+				signal,
+				timeout: this._timeoutMs
+			});
+			for (const t of result.tools) allTools.push({
+				name: t.name,
+				description: t.description,
+				inputSchema: t.inputSchema,
+				annotations: t.annotations ? { readOnlyHint: t.annotations.readOnlyHint } : void 0
+			});
+			cursor = result.nextCursor;
+		} while (cursor);
+		return allTools;
+	}
+	async callTool(name, args, signal) {
+		const result = await this._client.callTool({
+			name,
+			arguments: args
+		}, void 0, {
+			signal,
+			timeout: this._timeoutMs
+		});
+		if ("content" in result) return {
+			content: result.content.map((c) => ({
+				type: c.type,
+				text: "text" in c ? c.text : void 0,
+				data: "data" in c ? c.data : void 0,
+				mimeType: "mimeType" in c ? c.mimeType : void 0
+			})),
+			isError: "isError" in result ? result.isError : false
+		};
+		return {
+			content: [],
+			isError: false
+		};
+	}
+	listenForChanges(onToolsChanged) {
+		this._onToolsChanged = onToolsChanged;
+	}
+	async close() {
+		try {
+			await this._client.close();
+		} catch {}
+	}
+};
+/**
+* Discovers tools from a Cloudflare McpAgent endpoint and registers them
+* with Chrome's native `navigator.modelContext` API.
+*
+* On browsers without `navigator.modelContext` (everything except recent
+* Chrome with the relevant flags), this function is a no-op and returns a
+* handle with an empty tools array. No network request is made.
+*
+* @example
+* ```ts
+* import { registerWebMcp } from "agents/experimental/webmcp";
+*
+* const handle = await registerWebMcp({ url: "/mcp" });
+* console.log("Registered tools:", handle.tools);
+*
+* // Clean up when done (e.g. in a React effect cleanup)
+* await handle.dispose();
+* ```
+*
+* See the JSDoc on the module itself for the recommended "in-page tools +
+* remote tools" composition pattern.
+*/
+async function registerWebMcp(options) {
+	const { url, headers, getHeaders, watch = true, prefix = "", timeoutMs, logger: userLogger, quiet = false, onSync, onError } = options;
+	const logger = quiet ? SILENT_LOGGER : userLogger ?? DEFAULT_LOGGER;
+	const registeredTools = [];
+	const toolControllers = /* @__PURE__ */ new Map();
+	const lifecycleController = new AbortController();
+	let disposed = false;
+	let inflightSync = null;
+	if (!navigator.modelContext) {
+		logger.info("navigator.modelContext not available — skipping registration. This is expected on non-Chrome browsers.");
+		onSync?.([]);
+		return {
+			get tools() {
+				return [];
+			},
+			get disposed() {
+				return disposed;
+			},
+			refresh: async () => {},
+			dispose: async () => {
+				disposed = true;
+			}
+		};
+	}
+	const modelContext = navigator.modelContext;
+	const client = new McpHttpClient(url, headers, getHeaders, timeoutMs);
+	function unregisterAll() {
+		for (const controller of toolControllers.values()) controller.abort();
+		toolControllers.clear();
+		registeredTools.length = 0;
+	}
+	function registerTools(tools) {
+		for (const tool of tools) {
+			const registeredName = `${prefix}${tool.name}`;
+			const toolDef = {
+				name: registeredName,
+				description: tool.description ?? tool.name,
+				...tool.inputSchema ? { inputSchema: tool.inputSchema } : {},
+				...tool.annotations ? { annotations: { readOnlyHint: tool.annotations.readOnlyHint } } : {},
+				execute: async (input) => {
+					if (disposed) throw new Error("WebMCP adapter has been disposed");
+					const result = await client.callTool(tool.name, input, lifecycleController.signal);
+					if (result.isError) {
+						const errorText = result.content.map((c) => c.text ?? "").join("\n");
+						throw new Error(errorText || "Tool execution failed");
+					}
+					const parts = [];
+					let sawUnsupported = false;
+					for (const c of result.content) if (c.type === "text" && c.text) parts.push(c.text);
+					else if (c.type === "image" && c.data) parts.push(`data:${c.mimeType ?? "image/png"};base64,${c.data}`);
+					else if (c.data) {
+						parts.push(c.data);
+						sawUnsupported = true;
+					} else sawUnsupported = true;
+					if (sawUnsupported) logger.warn(`Tool "${tool.name}" returned content type(s) the adapter cannot fully represent as a string.`);
+					return parts.join("\n");
+				}
+			};
+			try {
+				const controller = new AbortController();
+				modelContext.registerTool(toolDef, { signal: controller.signal });
+				toolControllers.set(registeredName, controller);
+				registeredTools.push(registeredName);
+			} catch (err) {
+				logger.warn(`Failed to register tool "${registeredName}":`, err);
+			}
+		}
+	}
+	function syncTools() {
+		if (disposed) return Promise.resolve();
+		if (inflightSync) return inflightSync;
+		inflightSync = (async () => {
+			try {
+				const tools = await client.listTools(lifecycleController.signal);
+				if (disposed) return;
+				unregisterAll();
+				registerTools(tools);
+				onSync?.(tools);
+			} finally {
+				inflightSync = null;
+			}
+		})();
+		return inflightSync;
+	}
+	try {
+		await client.initialize(lifecycleController.signal);
+		await syncTools();
+		if (watch) client.listenForChanges(() => {
+			if (disposed) return;
+			syncTools().catch((err) => {
+				if (disposed) return;
+				const error = err instanceof Error ? err : new Error(String(err));
+				logger.warn("Watch-mode sync failed:", error);
+				onError?.(error);
+			});
+		});
+	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		logger.error("Initialization failed:", error);
+		await client.close();
+		throw error;
+	}
+	return {
+		get tools() {
+			return [...registeredTools];
+		},
+		get disposed() {
+			return disposed;
+		},
+		refresh: syncTools,
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			lifecycleController.abort();
+			unregisterAll();
+			try {
+				await inflightSync;
+			} catch {}
+			await client.close();
+		}
+	};
+}
+//#endregion
+export { registerWebMcp };
+
+//# sourceMappingURL=webmcp.js.map

package/dist/experimental/webmcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.js","names":[],"sources":["../../src/experimental/webmcp.ts"],"sourcesContent":["/**\n * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n * !! WARNING: EXPERIMENTAL — DO NOT USE IN PRODUCTION                  !!\n * !!                                                                   !!\n * !! This API is under active development and WILL break between       !!\n * !! releases. Google's WebMCP API (navigator.modelContext) is still   !!\n * !! in early preview and subject to change.                           !!\n * !!                                                                   !!\n * !! If you use this, pin your agents version and expect to rewrite    !!\n * !! your code when upgrading.                                         !!\n * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n *\n * WebMCP adapter for Cloudflare Agents SDK.\n *\n * Bridges tools registered on an McpAgent server to Chrome's native\n * navigator.modelContext API, so browser-native agents can discover\n * and call them without extra infrastructure.\n *\n * @example Bridge a remote McpAgent endpoint into the page\n * ```ts\n * import { registerWebMcp } from \"agents/experimental/webmcp\";\n *\n * const handle = await registerWebMcp({ url: \"/mcp\" });\n *\n * // Later, to clean up:\n * await handle.dispose();\n * ```\n *\n * @example Mix in-page tools with bridged tools (recommended pattern)\n * ```ts\n * import { registerWebMcp } from \"agents/experimental/webmcp\";\n *\n * // 1. Register page-local tools — things only the page can do\n * navigator.modelContext?.registerTool({\n *   name: \"scroll_to_section\",\n *   description: \"Scroll the page to a named section\",\n *   inputSchema: {\n *     type: \"object\",\n *     properties: { id: { type: \"string\" } },\n *     required: [\"id\"]\n *   },\n *   async execute({ id }) {\n *     document.getElementById(String(id))?.scrollIntoView({ behavior: \"smooth\" });\n *     return \"ok\";\n *   }\n * });\n *\n * // 2. Bridge server tools — things that need durable storage / auth / DB access\n * const handle = await registerWebMcp({\n *   url: \"/mcp\",\n *   prefix: \"remote.\",            // optional namespace to avoid collisions\n *   getHeaders: async () => ({ Authorization: `Bearer ${await getToken()}` })\n * });\n *\n * // The browser AI sees both kinds of tools side by side.\n * ```\n *\n * @experimental This API is not yet stable and may change.\n */\n\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\nimport { ToolListChangedNotificationSchema } from \"@modelcontextprotocol/sdk/types.js\";\n\n// ── WebMCP browser API surface (Chrome's navigator.modelContext) ─────\n\ninterface ModelContextToolAnnotations {\n  readOnlyHint?: boolean;\n}\n\ninterface ModelContextClient {\n  requestUserInteraction(callback: () => Promise<unknown>): Promise<unknown>;\n}\n\ninterface ModelContextTool {\n  name: string;\n  description: string;\n  inputSchema?: Record<string, unknown>;\n  execute: (\n    input: Record<string, unknown>,\n    client: ModelContextClient\n  ) => Promise<unknown>;\n  annotations?: ModelContextToolAnnotations;\n}\n\ninterface ModelContextRegisterToolOptions {\n  signal?: AbortSignal;\n}\n\ninterface ModelContext {\n  registerTool(\n    tool: ModelContextTool,\n    options?: ModelContextRegisterToolOptions\n  ): void;\n}\n\ndeclare global {\n  interface Navigator {\n    modelContext?: ModelContext;\n  }\n}\n\n// ── Internal types ───────────────────────────────────────────────────\n\ninterface McpTool {\n  name: string;\n  description?: string;\n  inputSchema?: Record<string, unknown>;\n  annotations?: { readOnlyHint?: boolean };\n}\n\ninterface McpToolCallResult {\n  content: Array<{\n    type: string;\n    text?: string;\n    data?: string;\n    mimeType?: string;\n  }>;\n  isError?: boolean;\n}\n\n/**\n * Logger interface for adapter diagnostics. Defaults to `console`.\n * Pass a no-op implementation (or `quiet: true`) to silence output.\n */\nexport interface WebMcpLogger {\n  info(...args: unknown[]): void;\n  warn(...args: unknown[]): void;\n  error(...args: unknown[]): void;\n}\n\nconst DEFAULT_LOGGER: WebMcpLogger = {\n  info: (...args) => console.info(\"[webmcp-adapter]\", ...args),\n  warn: (...args) => console.warn(\"[webmcp-adapter]\", ...args),\n  error: (...args) => console.error(\"[webmcp-adapter]\", ...args)\n};\n\nconst SILENT_LOGGER: WebMcpLogger = {\n  info: () => {},\n  warn: () => {},\n  error: () => {}\n};\n\n// ── MCP transport wrapper ────────────────────────────────────────────\n\nclass McpHttpClient {\n  private _client: Client;\n  private _transport: StreamableHTTPClientTransport;\n  private _onToolsChanged?: () => void;\n  private _timeoutMs?: number;\n\n  constructor(\n    url: string,\n    headers?: Record<string, string>,\n    getHeaders?: () => Promise<Record<string, string>> | Record<string, string>,\n    timeoutMs?: number\n  ) {\n    const resolvedUrl = new URL(url, globalThis.location?.origin);\n    this._timeoutMs = timeoutMs;\n\n    const transportOptions: ConstructorParameters<\n      typeof StreamableHTTPClientTransport\n    >[1] = {\n      requestInit: { headers: headers ?? {} }\n    };\n\n    if (getHeaders) {\n      transportOptions.fetch = async (input, init) => {\n        const dynamic = await getHeaders();\n        const merged = new Headers(init?.headers);\n        for (const [k, v] of Object.entries(dynamic)) {\n          merged.set(k, v);\n        }\n        return globalThis.fetch(input, {\n          ...init,\n          headers: merged\n        });\n      };\n    }\n\n    this._transport = new StreamableHTTPClientTransport(\n      resolvedUrl,\n      transportOptions\n    );\n\n    this._client = new Client(\n      { name: \"webmcp-adapter\", version: \"0.1.0\" },\n      { capabilities: {} }\n    );\n  }\n\n  async initialize(signal?: AbortSignal): Promise<void> {\n    await this._client.connect(this._transport);\n\n    this._client.setNotificationHandler(\n      ToolListChangedNotificationSchema,\n      async () => {\n        if (signal?.aborted) return;\n        this._onToolsChanged?.();\n      }\n    );\n  }\n\n  async listTools(signal?: AbortSignal): Promise<McpTool[]> {\n    const allTools: McpTool[] = [];\n    let cursor: string | undefined;\n    do {\n      if (signal?.aborted) throw new DOMException(\"Aborted\", \"AbortError\");\n      const result = await this._client.listTools(\n        cursor ? { cursor } : undefined,\n        { signal, timeout: this._timeoutMs }\n      );\n      for (const t of result.tools) {\n        allTools.push({\n          name: t.name,\n          description: t.description,\n          inputSchema: t.inputSchema as Record<string, unknown> | undefined,\n          annotations: t.annotations\n            ? { readOnlyHint: t.annotations.readOnlyHint }\n            : undefined\n        });\n      }\n      cursor = result.nextCursor;\n    } while (cursor);\n    return allTools;\n  }\n\n  async callTool(\n    name: string,\n    args: Record<string, unknown>,\n    signal?: AbortSignal\n  ): Promise<McpToolCallResult> {\n    const result = await this._client.callTool(\n      { name, arguments: args },\n      undefined,\n      { signal, timeout: this._timeoutMs }\n    );\n    if (\"content\" in result) {\n      return {\n        content: (\n          result.content as Array<{\n            type: string;\n            text?: string;\n            data?: string;\n          }>\n        ).map((c) => ({\n          type: c.type,\n          text: \"text\" in c ? (c.text as string) : undefined,\n          data: \"data\" in c ? (c.data as string) : undefined,\n          mimeType: \"mimeType\" in c ? (c.mimeType as string) : undefined\n        })),\n        isError: \"isError\" in result ? (result.isError as boolean) : false\n      };\n    }\n    return { content: [], isError: false };\n  }\n\n  listenForChanges(onToolsChanged: () => void): void {\n    this._onToolsChanged = onToolsChanged;\n  }\n\n  async close(): Promise<void> {\n    try {\n      await this._client.close();\n    } catch {\n      // Closing a never-connected or already-closed client is fine.\n    }\n  }\n}\n\n// ── Public API ───────────────────────────────────────────────────────\n\nexport interface WebMcpOptions {\n  /** URL of the MCP endpoint (absolute or relative, e.g. `\"/mcp\"`). */\n  url: string;\n  /**\n   * Additional headers to include in every request to the MCP server.\n   * Useful for static authentication (e.g. `{ Authorization: \"Bearer <token>\" }`).\n   */\n  headers?: Record<string, string>;\n  /**\n   * Async function that returns headers for each request.\n   * Called before every request, useful for tokens that refresh.\n   * If both `headers` and `getHeaders` are provided, they are merged\n   * with `getHeaders` values taking precedence.\n   */\n  getHeaders?: () => Promise<Record<string, string>> | Record<string, string>;\n  /**\n   * If true, listen for `tools/list_changed` notifications and re-sync\n   * tools with `navigator.modelContext`. The adapter opens an SSE GET to\n   * the MCP endpoint to receive notifications; servers that don't support\n   * server-initiated streams (e.g. respond `405` on GET) gracefully degrade.\n   * @default true\n   */\n  watch?: boolean;\n  /**\n   * Optional namespace prefix prepended to every tool name registered with\n   * `navigator.modelContext`. Useful when bridging multiple MCP servers, or\n   * when the page also registers in-page tools and you want to avoid\n   * collisions. The original (unprefixed) name is still used on the wire\n   * when calling the server.\n   *\n   * @example `prefix: \"remote.\"` turns `search` into `remote.search`.\n   */\n  prefix?: string;\n  /**\n   * Per-request timeout (in milliseconds) applied to `tools/list` and\n   * `tools/call`. If the server doesn't respond in time, the request is\n   * aborted and the resulting error is surfaced through the normal error\n   * paths (`onError` for sync, rejection for tool execution).\n   */\n  timeoutMs?: number;\n  /**\n   * Custom logger. Defaults to `console` with a `[webmcp-adapter]` prefix.\n   * Pass `{ info: () => {}, warn: () => {}, error: () => {} }` to silence.\n   */\n  logger?: WebMcpLogger;\n  /** Convenience shortcut for `logger: SILENT_LOGGER`. @default false */\n  quiet?: boolean;\n  /**\n   * Called whenever the adapter performs a successful sync (initial load\n   * and on `tools/list_changed`). Receives the tools as the server returned\n   * them (with their original, unprefixed names).\n   */\n  onSync?: (tools: McpTool[]) => void;\n  /**\n   * Called when an error occurs during background work that the caller\n   * cannot otherwise observe — specifically: a watch-mode re-sync failure.\n   *\n   * **Not** called for:\n   * - Initialization failures (those reject the `registerWebMcp` promise).\n   * - Per-tool execution failures (those reject the `execute` promise the\n   *   browser host awaits; Chrome surfaces them to the AI).\n   */\n  onError?: (error: Error) => void;\n}\n\nexport interface WebMcpHandle {\n  /**\n   * Currently registered tool names (with `prefix` applied). Returns a fresh\n   * snapshot on each access — safe to mutate.\n   */\n  readonly tools: ReadonlyArray<string>;\n  /**\n   * Re-fetch the tool list from the server and re-register everything.\n   * If a sync is already in flight (from a `tools/list_changed` notification\n   * or a previous `refresh()` call), returns the in-flight promise rather\n   * than starting a second sync.\n   */\n  refresh(): Promise<void>;\n  /**\n   * Unregister all tools, signal any in-flight work to abort, and close the\n   * MCP connection. Safe to call multiple times.\n   */\n  dispose(): Promise<void>;\n  /** True after `dispose()` has been called at least once. */\n  readonly disposed: boolean;\n}\n\n/**\n * Discovers tools from a Cloudflare McpAgent endpoint and registers them\n * with Chrome's native `navigator.modelContext` API.\n *\n * On browsers without `navigator.modelContext` (everything except recent\n * Chrome with the relevant flags), this function is a no-op and returns a\n * handle with an empty tools array. No network request is made.\n *\n * @example\n * ```ts\n * import { registerWebMcp } from \"agents/experimental/webmcp\";\n *\n * const handle = await registerWebMcp({ url: \"/mcp\" });\n * console.log(\"Registered tools:\", handle.tools);\n *\n * // Clean up when done (e.g. in a React effect cleanup)\n * await handle.dispose();\n * ```\n *\n * See the JSDoc on the module itself for the recommended \"in-page tools +\n * remote tools\" composition pattern.\n */\nexport async function registerWebMcp(\n  options: WebMcpOptions\n): Promise<WebMcpHandle> {\n  const {\n    url,\n    headers,\n    getHeaders,\n    watch = true,\n    prefix = \"\",\n    timeoutMs,\n    logger: userLogger,\n    quiet = false,\n    onSync,\n    onError\n  } = options;\n\n  const logger = quiet ? SILENT_LOGGER : (userLogger ?? DEFAULT_LOGGER);\n\n  const registeredTools: string[] = [];\n  const toolControllers = new Map<string, AbortController>();\n  const lifecycleController = new AbortController();\n  let disposed = false;\n  let inflightSync: Promise<void> | null = null;\n\n  if (!navigator.modelContext) {\n    logger.info(\n      \"navigator.modelContext not available — skipping registration. \" +\n        \"This is expected on non-Chrome browsers.\"\n    );\n    onSync?.([]);\n    return {\n      get tools() {\n        return [];\n      },\n      get disposed() {\n        return disposed;\n      },\n      refresh: async () => {},\n      dispose: async () => {\n        disposed = true;\n      }\n    };\n  }\n\n  const modelContext: ModelContext = navigator.modelContext;\n  const client = new McpHttpClient(url, headers, getHeaders, timeoutMs);\n\n  function unregisterAll(): void {\n    for (const controller of toolControllers.values()) {\n      controller.abort();\n    }\n    toolControllers.clear();\n    registeredTools.length = 0;\n  }\n\n  function registerTools(tools: McpTool[]): void {\n    for (const tool of tools) {\n      const registeredName = `${prefix}${tool.name}`;\n      const toolDef: ModelContextTool = {\n        name: registeredName,\n        description: tool.description ?? tool.name,\n        ...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),\n        ...(tool.annotations\n          ? { annotations: { readOnlyHint: tool.annotations.readOnlyHint } }\n          : {}),\n        execute: async (input: Record<string, unknown>) => {\n          if (disposed) {\n            throw new Error(\"WebMCP adapter has been disposed\");\n          }\n          const result = await client.callTool(\n            tool.name,\n            input,\n            lifecycleController.signal\n          );\n\n          if (result.isError) {\n            const errorText = result.content\n              .map((c) => c.text ?? \"\")\n              .join(\"\\n\");\n            throw new Error(errorText || \"Tool execution failed\");\n          }\n\n          const parts: string[] = [];\n          let sawUnsupported = false;\n          for (const c of result.content) {\n            if (c.type === \"text\" && c.text) {\n              parts.push(c.text);\n            } else if (c.type === \"image\" && c.data) {\n              parts.push(`data:${c.mimeType ?? \"image/png\"};base64,${c.data}`);\n            } else if (c.data) {\n              parts.push(c.data);\n              sawUnsupported = true;\n            } else {\n              sawUnsupported = true;\n            }\n          }\n          if (sawUnsupported) {\n            logger.warn(\n              `Tool \"${tool.name}\" returned content type(s) the adapter` +\n                \" cannot fully represent as a string.\"\n            );\n          }\n          return parts.join(\"\\n\");\n        }\n      };\n\n      try {\n        const controller = new AbortController();\n        modelContext.registerTool(toolDef, { signal: controller.signal });\n        toolControllers.set(registeredName, controller);\n        registeredTools.push(registeredName);\n      } catch (err) {\n        logger.warn(`Failed to register tool \"${registeredName}\":`, err);\n      }\n    }\n  }\n\n  // Serialize syncs: if one is already running, share its promise. This\n  // prevents the unregister/listTools/registerTools sequence from\n  // interleaving when both `refresh()` and a `tools/list_changed`\n  // notification fire concurrently.\n  function syncTools(): Promise<void> {\n    if (disposed) return Promise.resolve();\n    if (inflightSync) return inflightSync;\n    inflightSync = (async () => {\n      try {\n        const tools = await client.listTools(lifecycleController.signal);\n        if (disposed) return;\n        unregisterAll();\n        registerTools(tools);\n        onSync?.(tools);\n      } finally {\n        inflightSync = null;\n      }\n    })();\n    return inflightSync;\n  }\n\n  try {\n    await client.initialize(lifecycleController.signal);\n    await syncTools();\n\n    if (watch) {\n      client.listenForChanges(() => {\n        if (disposed) return;\n        syncTools().catch((err: unknown) => {\n          if (disposed) return;\n          const error = err instanceof Error ? err : new Error(String(err));\n          logger.warn(\"Watch-mode sync failed:\", error);\n          onError?.(error);\n        });\n      });\n    }\n  } catch (err) {\n    const error = err instanceof Error ? err : new Error(String(err));\n    logger.error(\"Initialization failed:\", error);\n    // Best-effort cleanup so a failed init doesn't leak the transport.\n    await client.close();\n    throw error;\n  }\n\n  return {\n    get tools() {\n      return [...registeredTools];\n    },\n    get disposed() {\n      return disposed;\n    },\n    refresh: syncTools,\n    async dispose() {\n      if (disposed) return;\n      disposed = true;\n      lifecycleController.abort();\n      unregisterAll();\n      // Wait for any in-flight sync to settle so callers can rely on\n      // a quiet adapter after `await handle.dispose()`.\n      try {\n        await inflightSync;\n      } catch {\n        // Already surfaced via onError or thrown to the original caller.\n      }\n      await client.close();\n    }\n  };\n}\n"],"mappings":"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"}

package/dist/{index-BBh8iKgk.d.ts → index-D9qo_Inc.d.ts}

@@ -729,7 +729,7 @@ declare class MCPClientConnection {
    */
   getTransport(
     transportType: BaseTransportType
-  ): StreamableHTTPClientTransport | SSEClientTransport | RPCClientTransport;
+  ): RPCClientTransport | SSEClientTransport | StreamableHTTPClientTransport;
   private tryConnect;
   private _capabilityErrorHandler;
 }
@@ -1640,6 +1640,11 @@ type FiberRecoveryContext = {
   /** Fiber ID. */ id: string /** Name passed to `runFiber`. */;
   name: string /** Last checkpoint data from `stash()`, or null if never stashed. */;
   snapshot: unknown | null;
+  /**
+   * Epoch milliseconds when the fiber row was inserted (when `runFiber`
+   * started). Use `Date.now() - createdAt` to gate stale recoveries.
+   */
+  createdAt: number;
   [key: string]: unknown;
 };
 /**
@@ -1898,6 +1903,18 @@ declare class Agent<
    * @param excludeIds Additional connection IDs to exclude (e.g. the source)
    */
   private _broadcastProtocol;
+  /**
+   * When running as a facet, the parent DO owns the WebSocket registry
+   * (`ctx.getWebSockets()`). Iterating from the child isolate throws
+   * "Cannot perform I/O on behalf of a different Durable Object".
+   * Downstream callers (e.g. chat-streaming paths) invoke
+   * `this.broadcast()` directly, bypassing `_broadcastProtocol`'s
+   * guard, so override at the base to catch every path.
+   */
+  broadcast(
+    msg: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
   private _setStateInternal;
   /**
    * Update the Agent's state
@@ -2369,12 +2386,23 @@ declare class Agent<
    */
   alarm(): Promise<void>;
   /**
-   * Marks this agent as running inside a facet (sub-agent). Once set,
-   * scheduling methods throw a clear error instead of crashing on
-   * `setAlarm()` (which is not supported in facets).
-   * @internal
+   * Initialize this agent as a facet in a single RPC.
+   *
+   * Runs entirely inside the child's isolate, so every storage write
+   * and `onStart()` I/O is owned by the child DO. This replaces the
+   * previous "construct a Request in the parent DO and `stub.fetch()`
+   * it on the child" handshake, whose native I/O was tied to the
+   * parent and triggered "Cannot perform I/O on behalf of a different
+   * Durable Object" on the child.
+   *
+   * Order matters: set `_isFacet` BEFORE triggering initialization, so
+   * the first `onStart()` run (which calls `broadcastMcpServers`) sees
+   * the flag and skips broadcasts that would touch the parent DO's
+   * WebSocket registry.
+   *
+   * @internal Called by {@link subAgent}.
    */
-  _cf_markAsFacet(): Promise<void>;
+  _cf_initAsFacet(name: string): Promise<void>;
   /**
    * Get or create a named sub-agent — a child Durable Object (facet)
    * with its own isolated SQLite storage running on the same machine.
@@ -2383,7 +2411,7 @@ declare class Agent<
    * entry point. The first call for a given name triggers the child's
    * `onStart()`. Subsequent calls return the existing instance.
    *
-   * @experimental Requires the `"experimental"` compatibility flag.
+   * @experimental The API surface may change before stabilizing.
    *
    * @param cls The Agent subclass (must be exported from the worker)
    * @param name Unique name for this child instance
@@ -2405,7 +2433,7 @@ declare class Agent<
    * Pending RPC calls receive the reason as an error.
    * Transitively aborts the child's own children.
    *
-   * @experimental Requires the `"experimental"` compatibility flag.
+   * @experimental The API surface may change before stabilizing.
    *
    * @param cls The Agent subclass used when creating the child
    * @param name Name of the child to abort
@@ -2416,7 +2444,7 @@ declare class Agent<
    * Delete a sub-agent: abort it if running, then permanently wipe its
    * storage. Transitively deletes the child's own children.
    *
-   * @experimental Requires the `"experimental"` compatibility flag.
+   * @experimental The API surface may change before stabilizing.
    *
    * @param cls The Agent subclass used when creating the child
    * @param name Name of the child to delete
@@ -3080,4 +3108,4 @@ export {
   QueueItem as y,
   MCPClientOAuthResult as z
 };
-//# sourceMappingURL=index-BBh8iKgk.d.ts.map
+//# sourceMappingURL=index-D9qo_Inc.d.ts.map

package/dist/index.d.ts

@@ -37,7 +37,7 @@ import {
   w as SqlError,
   x as RPCResponse,
   y as QueueItem
-} from "./index-BBh8iKgk.js";
+} from "./index-D9qo_Inc.js";
 import {
   n as AgentsOAuthProvider,
   r as DurableObjectOAuthClientProvider,