@browserbasehq/orca 3.5.0-preview.1 → 3.5.1-preview.0

package/dist/esm/lib/v3/understudy/page.js

@@ -47,7 +47,7 @@ import { NavigationResponseTracker } from "./navigationResponseTracker.js";
 import { Response, isSerializableResponse } from "./response.js";
 import { ConsoleMessage } from "./consoleMessage.js";
 import { StagehandSetExtraHTTPHeadersError, StagehandSnapshotError, } from "../types/public/index.js";
-import { StagehandInvalidArgumentError, StagehandEvalError, } from "../types/public/sdkErrors.js";
+import { StagehandInvalidArgumentError, StagehandEvalError, StagehandUnsupportedBrowserFeatureError, } from "../types/public/sdkErrors.js";
 import { normalizeInitScriptSource } from "./initScripts.js";
 import { buildLocatorInvocation } from "./locatorInvocation.js";
 import { applyMaskOverlays, applyStyleToFrames, collectFramesForScreenshot, computeScreenshotScale, disableAnimations, hideCaret, normalizeScreenshotClip, runScreenshotCleanups, setTransparentBackground, } from "./screenshotUtils.js";
@@ -70,8 +70,49 @@ const LIFECYCLE_NAME = {
     domcontentloaded: "DOMContentLoaded",
     networkidle: "networkIdle",
 };
+const WEB_MCP_SUPPORT_MESSAGE = "Make sure you are using Chrome/Chromium newer than version 149 and that it is launched with --enable-features=WebMCPTesting,DevToolsWebMCPSupport.";
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+function stripWebMCPToolDebugFields(tool) {
+    const { name, description, inputSchema, annotations, frameId } = tool;
+    const publicAnnotations = annotations === undefined ? undefined : { ...annotations };
+    return {
+        name,
+        ...(description !== undefined && { description }),
+        ...(inputSchema !== undefined && { inputSchema }),
+        ...(publicAnnotations !== undefined && { annotations: publicAnnotations }),
+        frameId,
+    };
+}
+function webMCPResultFromEvent(invocationId, event) {
+    return {
+        invocationId,
+        status: event.status ?? "Error",
+        ...(event.output !== undefined && { output: event.output }),
+        ...(event.errorText !== undefined && { errorText: event.errorText }),
+        ...(event.exception !== undefined && { exception: event.exception }),
+    };
+}
+function isWebMCPUnsupportedBrowserError(error) {
+    if (error instanceof StagehandUnsupportedBrowserFeatureError)
+        return true;
+    const code = error?.code;
+    if (code === -32601)
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /method not found/i.test(message);
+}
 let Page = (() => {
     let _instanceExtraInitializers = [];
+    let _listWebMCPTools_decorators;
+    let _invokeWebMCPTool_decorators;
     let _close_decorators;
     let _goto_decorators;
     let _reload_decorators;
@@ -91,6 +132,8 @@ let Page = (() => {
     return class Page {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _listWebMCPTools_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageListWebMCPTools" })];
+            _invokeWebMCPTool_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageInvokeWebMCPTool" })];
             _close_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageClose" })];
             _goto_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageGoto" })];
             _reload_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageReload" })];
@@ -117,6 +160,8 @@ let Page = (() => {
             _type_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageType" })];
             _keyPress_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageKeyPress" })];
             _snapshot_decorators = [FlowLogger.wrapWithLogging({ eventType: "PageSnapshot" })];
+            __esDecorate(this, null, _listWebMCPTools_decorators, { kind: "method", name: "listWebMCPTools", static: false, private: false, access: { has: obj => "listWebMCPTools" in obj, get: obj => obj.listWebMCPTools }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _invokeWebMCPTool_decorators, { kind: "method", name: "invokeWebMCPTool", static: false, private: false, access: { has: obj => "invokeWebMCPTool" in obj, get: obj => obj.invokeWebMCPTool }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _close_decorators, { kind: "method", name: "close", static: false, private: false, access: { has: obj => "close" in obj, get: obj => obj.close }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _goto_decorators, { kind: "method", name: "goto", static: false, private: false, access: { has: obj => "goto" in obj, get: obj => obj.goto }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _reload_decorators, { kind: "method", name: "reload", static: false, private: false, access: { has: obj => "reload" in obj, get: obj => obj.reload }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -161,6 +206,10 @@ let Page = (() => {
         apiClient = null;
         consoleListeners = new Set();
         consoleHandlers = new Map();
+        webMCPEnablePromise = null;
+        pendingWebMCPInvocations = new Map();
+        bufferedWebMCPResults = new Map();
+        pendingWebMCPInvokeToolResponses = 0;
         /** Document-start scripts installed across every session this page owns. */
         initScripts = [];
         extraHTTPHeaders;
@@ -514,6 +563,154 @@ let Page = (() => {
             }
             return this;
         }
+        onWebMCPToolResponded = (event) => {
+            if (!event.invocationId)
+                return;
+            const result = webMCPResultFromEvent(event.invocationId, event);
+            const pending = this.pendingWebMCPInvocations.get(event.invocationId);
+            if (!pending) {
+                /*
+                 * WebMCP.invokeTool returns the invocationId, while WebMCP.toolResponded
+                 * is a separate event. Very fast tools can emit the event before the
+                 * invokeTool command response reaches us, so there is not yet a pending
+                 * invocation entry to resolve. Buffer only during that command-response
+                 * window; otherwise unmatched events are stale or unexpected.
+                 */
+                if (this.pendingWebMCPInvokeToolResponses > 0) {
+                    this.bufferedWebMCPResults.set(event.invocationId, result);
+                }
+                return;
+            }
+            clearTimeout(pending.timer);
+            this.pendingWebMCPInvocations.delete(event.invocationId);
+            pending.deferred.resolve(result);
+        };
+        async ensureWebMCPEnabled() {
+            if (this.webMCPEnablePromise) {
+                return this.webMCPEnablePromise;
+            }
+            this.mainSession.on("WebMCP.toolResponded", this.onWebMCPToolResponded);
+            this.webMCPEnablePromise = this.mainSession
+                .send("WebMCP.enable")
+                .then(() => undefined)
+                .catch((error) => {
+                this.teardownWebMCP();
+                const message = error instanceof Error ? error.message : String(error);
+                if (isWebMCPUnsupportedBrowserError(error)) {
+                    throw new StagehandUnsupportedBrowserFeatureError("WebMCP", `Unable to enable WebMCP. ${WEB_MCP_SUPPORT_MESSAGE} CDP error: ${message}`, error);
+                }
+                throw error;
+            });
+            return this.webMCPEnablePromise;
+        }
+        /**
+         * `WebMCP.enable` is the browser's source-of-truth snapshot trigger: CDP emits
+         * `WebMCP.toolsAdded` for all tools currently registered on the page. Keep
+         * this scoped to the list call so tools from old documents are not cached here.
+         */
+        async collectWebMCPToolsSnapshot(timeoutMs) {
+            const quietWindowMs = Math.min(100, Math.max(0, timeoutMs));
+            const tools = new Map();
+            let toolsVersion = 0;
+            let toolsLastUpdatedAt = null;
+            const toolKey = (tool) => `${tool.frameId}:${tool.name}`;
+            const onToolsAdded = (event) => {
+                if (!Array.isArray(event.tools))
+                    return;
+                let changed = false;
+                for (const tool of event.tools) {
+                    const normalized = stripWebMCPToolDebugFields(tool);
+                    tools.set(toolKey(normalized), normalized);
+                    changed = true;
+                }
+                if (!changed)
+                    return;
+                toolsVersion += 1;
+                toolsLastUpdatedAt = Date.now();
+                schedule?.();
+            };
+            const onToolsRemoved = (event) => {
+                if (!Array.isArray(event.tools))
+                    return;
+                let changed = false;
+                for (const tool of event.tools) {
+                    changed = tools.delete(toolKey(tool)) || changed;
+                }
+                if (!changed)
+                    return;
+                toolsVersion += 1;
+                toolsLastUpdatedAt = Date.now();
+                schedule?.();
+            };
+            const deadline = Date.now() + timeoutMs;
+            let schedule = null;
+            this.mainSession.on("WebMCP.toolsAdded", onToolsAdded);
+            this.mainSession.on("WebMCP.toolsRemoved", onToolsRemoved);
+            try {
+                await this.mainSession.send("WebMCP.enable");
+                if (quietWindowMs === 0)
+                    return [...tools.values()];
+                await new Promise((resolve) => {
+                    const startVersion = toolsVersion;
+                    let quietTimer = null;
+                    let timeoutTimer = null;
+                    let done = false;
+                    const cleanup = () => {
+                        if (done)
+                            return;
+                        done = true;
+                        if (quietTimer)
+                            clearTimeout(quietTimer);
+                        if (timeoutTimer)
+                            clearTimeout(timeoutTimer);
+                        resolve();
+                    };
+                    schedule = () => {
+                        if (done)
+                            return;
+                        if (quietTimer) {
+                            clearTimeout(quietTimer);
+                            quietTimer = null;
+                        }
+                        const now = Date.now();
+                        if (now >= deadline) {
+                            cleanup();
+                            return;
+                        }
+                        const sawToolsSinceStart = toolsVersion > startVersion;
+                        const lastUpdate = toolsLastUpdatedAt;
+                        const quietRemaining = sawToolsSinceStart && lastUpdate !== null
+                            ? Math.max(0, quietWindowMs - (now - lastUpdate))
+                            : quietWindowMs;
+                        quietTimer = setTimeout(cleanup, Math.min(quietRemaining, deadline - now));
+                    };
+                    timeoutTimer = setTimeout(cleanup, timeoutMs);
+                    schedule();
+                });
+            }
+            finally {
+                this.mainSession.off("WebMCP.toolsAdded", onToolsAdded);
+                this.mainSession.off("WebMCP.toolsRemoved", onToolsRemoved);
+            }
+            return [...tools.values()];
+        }
+        cleanupWebMCPInvocation(invocationId) {
+            const pending = this.pendingWebMCPInvocations.get(invocationId);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this.pendingWebMCPInvocations.delete(invocationId);
+        }
+        teardownWebMCP() {
+            this.mainSession.off("WebMCP.toolResponded", this.onWebMCPToolResponded);
+            for (const [invocationId, pending] of this.pendingWebMCPInvocations) {
+                clearTimeout(pending.timer);
+                pending.deferred.reject(new StagehandInvalidArgumentError(`WebMCP invocation "${invocationId}" was disposed before it completed.`));
+            }
+            this.pendingWebMCPInvocations.clear();
+            this.bufferedWebMCPResults.clear();
+            this.webMCPEnablePromise = null;
+        }
         // ---------------- MAIN APIs ----------------
         targetId() {
             return this._targetId;
@@ -540,6 +737,90 @@ let Page = (() => {
         sendCDP(method, params) {
             return this.mainSession.send(method, params);
         }
+        /**
+         * List WebMCP tools registered by the current page.
+         * CDP emits WebMCP.toolsAdded for all currently registered tools each time
+         * WebMCP.enable is called, so this method treats the browser as the source of
+         * truth and collects that per-call snapshot instead of keeping a tool cache.
+         */
+        async listWebMCPTools(options) {
+            const timeoutMs = options?.timeoutMs ?? 1_000;
+            try {
+                return await this.collectWebMCPToolsSnapshot(timeoutMs);
+            }
+            catch (error) {
+                if (error instanceof StagehandUnsupportedBrowserFeatureError)
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                if (isWebMCPUnsupportedBrowserError(error)) {
+                    throw new StagehandUnsupportedBrowserFeatureError("WebMCP", `Unable to list WebMCP tools. ${WEB_MCP_SUPPORT_MESSAGE} CDP error: ${message}`, error);
+                }
+                throw error;
+            }
+        }
+        async invokeWebMCPTool(toolName, input, options) {
+            const timeoutMs = options?.timeoutMs ?? 30_000;
+            let frameId = options?.frameId;
+            if (!frameId) {
+                const matchingTools = (await this.listWebMCPTools()).filter((tool) => tool.name === toolName);
+                if (matchingTools.length === 0) {
+                    throw new StagehandInvalidArgumentError(`Unable to invoke WebMCP tool "${toolName}" because it was not found on the current page.`);
+                }
+                if (matchingTools.length > 1) {
+                    throw new StagehandInvalidArgumentError(`Unable to invoke WebMCP tool "${toolName}" because multiple frames registered a tool with that name. Pass options.frameId to disambiguate.`);
+                }
+                frameId = matchingTools[0].frameId;
+            }
+            const deferred = createDeferred();
+            let invocationId;
+            await this.ensureWebMCPEnabled();
+            try {
+                this.pendingWebMCPInvokeToolResponses += 1;
+                const response = await this.mainSession
+                    .send("WebMCP.invokeTool", {
+                    frameId,
+                    toolName,
+                    input,
+                })
+                    .finally(() => {
+                    this.pendingWebMCPInvokeToolResponses -= 1;
+                });
+                invocationId = response.invocationId;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (isWebMCPUnsupportedBrowserError(error)) {
+                    throw new StagehandUnsupportedBrowserFeatureError("WebMCP", `Unable to invoke WebMCP tool "${toolName}". ${WEB_MCP_SUPPORT_MESSAGE} CDP error: ${message}`, error);
+                }
+                throw error;
+            }
+            const bufferedResult = this.bufferedWebMCPResults.get(invocationId);
+            if (bufferedResult) {
+                this.bufferedWebMCPResults.delete(invocationId);
+                deferred.resolve(bufferedResult);
+            }
+            else {
+                const timer = setTimeout(() => {
+                    this.cleanupWebMCPInvocation(invocationId);
+                    deferred.reject(new StagehandInvalidArgumentError(`Timed out waiting for WebMCP tool "${toolName}" invocation result after ${timeoutMs}ms.`));
+                }, timeoutMs);
+                this.pendingWebMCPInvocations.set(invocationId, {
+                    deferred,
+                    timer,
+                });
+            }
+            return {
+                invocationId,
+                toolName,
+                frameId,
+                result: deferred.promise,
+                cancel: async () => {
+                    await this.mainSession.send("WebMCP.cancelInvocation", {
+                        invocationId,
+                    });
+                },
+            };
+        }
         /** Seed the cached URL before navigation events converge. */
         seedCurrentUrl(url) {
             if (!url)
@@ -576,6 +857,7 @@ let Page = (() => {
                     const targets = await this.conn.getTargets();
                     if (!targets.some((t) => t.targetId === this._targetId)) {
                         this.networkManager.dispose();
+                        this.teardownWebMCP();
                         return;
                     }
                 }
@@ -585,6 +867,7 @@ let Page = (() => {
                 await new Promise((r) => setTimeout(r, 25));
             }
             this.networkManager.dispose();
+            this.teardownWebMCP();
             this.removeAllConsoleTaps();
             this.consoleListeners.clear();
         }