opera-devtools-mcp 0.2.3 → 0.3.0

package/build/src/McpPage.js

@@ -3,10 +3,113 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { logger } from './logger.js';
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+export function replaceHtmlElementsWithUids(schema) {
+    if (typeof schema === 'boolean') {
+        return;
+    }
+    let isHtmlElement = false;
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === 'x-mcp-type' && value === 'HTMLElement') {
+            isHtmlElement = true;
+            break;
+        }
+    }
+    if (isHtmlElement) {
+        schema.properties = { uid: { type: 'string' } };
+        schema.required = ['uid'];
+    }
+    if (schema.properties) {
+        for (const key of Object.keys(schema.properties)) {
+            replaceHtmlElementsWithUids(schema.properties[key]);
+        }
+    }
+    if (schema.items) {
+        if (Array.isArray(schema.items)) {
+            for (const item of schema.items) {
+                replaceHtmlElementsWithUids(item);
+            }
+        }
+        else {
+            replaceHtmlElementsWithUids(schema.items);
+        }
+    }
+    if (schema.anyOf) {
+        for (const s of schema.anyOf) {
+            replaceHtmlElementsWithUids(s);
+        }
+    }
+    if (schema.allOf) {
+        for (const s of schema.allOf) {
+            replaceHtmlElementsWithUids(s);
+        }
+    }
+    if (schema.oneOf) {
+        for (const s of schema.oneOf) {
+            replaceHtmlElementsWithUids(s);
+        }
+    }
+}
+import { createTargetUniverse, } from './devtools/DevtoolsUtils.js';
+import { ConsoleCollector, NetworkCollector, } from './collectors/PageCollector.js';
 import { TextSnapshot } from './TextSnapshot.js';
+import { PredefinedNetworkConditions, } from './third_party/index.js';
 import { takeSnapshot } from './tools/snapshot.js';
-import { getNetworkMultiplierFromString, WaitForHelper, } from './WaitForHelper.js';
+const DEFAULT_TIMEOUT = 5_000;
+const NAVIGATION_TIMEOUT = 10_000;
+import { logger } from './utils/logger.js';
+import { getNetworkMultiplierFromString, WaitForHelper, } from './utils/WaitForHelper.js';
 /**
  * Per-page state wrapper. Consolidates dialog, snapshot, emulation,
  * and metadata that were previously scattered across Maps in McpContext.
@@ -26,39 +129,224 @@ export class McpPage {
     emulationSettings = {};
     // Metadata
     isolatedContextName;
-    devToolsPage;
+    #devtoolsUniverse;
     // Dialog
     #dialog;
     #dialogHandler;
-    thirdPartyDeveloperTools;
-    constructor(page, id) {
+    thirdPartyDeveloperTools = [];
+    networkCollector;
+    consoleCollector;
+    #hasNetworkBlockOrAllowlist;
+    #locatorClass;
+    #navigationTimeout;
+    constructor(page, id, options) {
+        this.#hasNetworkBlockOrAllowlist = options.hasNetworkBlockOrAllowlist;
+        this.#locatorClass = options.locatorClass;
+        this.#navigationTimeout = options.navigationTimeout ?? NAVIGATION_TIMEOUT;
         this.pptrPage = page;
         this.id = id;
+        this.isolatedContextName = options.isolatedContextName;
         this.#dialogHandler = (dialog) => {
             this.#dialog = dialog;
         };
         page.on('dialog', this.#dialogHandler);
+        this.networkCollector = new NetworkCollector(page);
+        this.consoleCollector = new ConsoleCollector(page, collect => {
+            return {
+                console: event => {
+                    collect(event);
+                },
+                uncaughtError: event => {
+                    collect(event);
+                },
+                devtoolsAggregatedIssue: event => {
+                    collect(event);
+                },
+            };
+        });
     }
-    get dialog() {
-        return this.#dialog;
+    async init() {
+        await Promise.allSettled([
+            this.#initDevToolsUniverseNoThrow(),
+            this.#initFocusEmulationNoThrow(),
+        ]);
+    }
+    async #initFocusEmulationNoThrow() {
+        // We emulate a focused page for all pages to support multi-agent workflows.
+        void this.pptrPage.emulateFocusedPage(true).catch(error => {
+            logger?.('Error turning on focused page emulation', error);
+        });
+    }
+    async #initDevToolsUniverseNoThrow() {
+        if (this.#devtoolsUniverse) {
+            return undefined;
+        }
+        try {
+            const session = await this.pptrPage.createCDPSession();
+            this.#devtoolsUniverse = await createTargetUniverse(session);
+        }
+        catch (e) {
+            logger?.('Failed to initialize DevTools universe', e);
+        }
+    }
+    get devtoolsUniverse() {
+        return this.#devtoolsUniverse;
     }
     getDialog() {
-        return this.dialog;
+        return this.#dialog;
     }
     clearDialog() {
         this.#dialog = undefined;
     }
     throwIfDialogOpen() {
-        if (this.#dialog) {
+        if (this.#dialog && !this.#dialog.handled) {
             throw new Error(`A dialog is open (${this.#dialog.type()}: ${this.#dialog.message()}).`);
         }
     }
     getThirdPartyDeveloperTools() {
         return this.thirdPartyDeveloperTools;
     }
+    async getToolGroups() {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // Check if there is a `devtoolstooldiscovery` event listener
+            const windowHandle = __addDisposableResource(env_1, await this.pptrPage.evaluateHandle(() => window), false);
+            // @ts-expect-error internal API
+            const client = this.pptrPage._client();
+            const { listeners } = await client.send('DOMDebugger.getEventListeners', {
+                objectId: windowHandle.remoteObject().objectId,
+            });
+            if (listeners.find(l => l.type === 'devtoolstooldiscovery') === undefined) {
+                return [];
+            }
+            const toolGroups = await this.pptrPage.evaluate(() => {
+                if (window.__dtmcp) {
+                    window.__dtmcp.toolGroups = [];
+                }
+                return new Promise(resolve => {
+                    const event = new CustomEvent('devtoolstooldiscovery');
+                    const groups = [];
+                    // @ts-expect-error Adding custom property
+                    event.respondWith = toolGroup => {
+                        if (!window.__dtmcp) {
+                            window.__dtmcp = {};
+                        }
+                        if (!window.__dtmcp.toolGroups) {
+                            window.__dtmcp.toolGroups = [];
+                        }
+                        if (typeof toolGroup.name !== 'string' ||
+                            (toolGroup.description &&
+                                typeof toolGroup.description !== 'string') ||
+                            !Array.isArray(toolGroup.tools)) {
+                            console.error('Invalid toolGroup:', toolGroup);
+                            return;
+                        }
+                        for (const tool of toolGroup.tools) {
+                            if (typeof tool.name !== 'string' ||
+                                typeof tool.description !== 'string' ||
+                                typeof tool.inputSchema !== 'object' ||
+                                typeof tool.execute !== 'function') {
+                                console.error('Invalid tool:', tool);
+                                return;
+                            }
+                        }
+                        window.__dtmcp.toolGroups.push(toolGroup);
+                        // When receiving a toolGroup for the first time, expose a simple execution helper
+                        if (!window.__dtmcp.executeTool) {
+                            window.__dtmcp.executeTool = async (toolName, args) => {
+                                if (!window.__dtmcp?.toolGroups ||
+                                    window.__dtmcp.toolGroups.length === 0) {
+                                    throw new Error('No tools found on the page');
+                                }
+                                for (const group of window.__dtmcp.toolGroups) {
+                                    const tool = group.tools?.find(t => t.name === toolName);
+                                    if (tool) {
+                                        return await tool.execute(args);
+                                    }
+                                }
+                                throw new Error(`Tool ${toolName} not found`);
+                            };
+                        }
+                        groups.push(toolGroup);
+                    };
+                    window.dispatchEvent(event);
+                    // If at least one toolGroup was added synchronously, resolve with the array.
+                    // Otherwise, use setTimeout to allow for any microtask/asynchronous respondWith calls, or resolve with an empty array.
+                    if (groups.length > 0) {
+                        resolve(groups);
+                    }
+                    else {
+                        setTimeout(() => {
+                            if (groups.length > 0) {
+                                resolve(groups);
+                            }
+                            else {
+                                resolve([]);
+                            }
+                        }, 0);
+                    }
+                });
+            });
+            for (const group of toolGroups) {
+                for (const tool of group.tools ?? []) {
+                    replaceHtmlElementsWithUids(tool.inputSchema);
+                }
+            }
+            this.thirdPartyDeveloperTools = toolGroups;
+            return toolGroups;
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
     getWebMcpTools() {
         return this.pptrPage.webmcp.tools();
     }
+    resolveCdpRequestId(cdpRequestId) {
+        if (!cdpRequestId) {
+            logger?.('no network request');
+            return;
+        }
+        const request = this.networkCollector.find(request => {
+            // @ts-expect-error id is internal.
+            return request.id === cdpRequestId;
+        });
+        if (!request) {
+            logger?.('no network request for ' + cdpRequestId);
+            return;
+        }
+        return this.networkCollector.getIdForResource(request);
+    }
+    getNetworkRequests(includePreservedRequests) {
+        return this.networkCollector.getData(includePreservedRequests);
+    }
+    async getDevToolsPage() {
+        try {
+            if (await this.pptrPage.hasDevTools()) {
+                return await this.pptrPage.openDevTools();
+            }
+            return undefined;
+        }
+        catch {
+            // Prior to Chrome 144.0.7559.59, the command fails,
+            // Some Electron apps still use older version
+            // Fall back to not exposing DevTools at all.
+            return undefined;
+        }
+    }
+    getConsoleData(includePreservedMessages) {
+        return this.consoleCollector.getData(includePreservedMessages);
+    }
+    getConsoleMessageById(id) {
+        return this.consoleCollector.getById(id);
+    }
+    getNetworkRequestById(reqid) {
+        return this.networkCollector.getById(reqid);
+    }
     get networkConditions() {
         return this.emulationSettings.networkConditions ?? null;
     }
@@ -87,6 +375,14 @@ export class McpPage {
     }
     dispose() {
         this.pptrPage.off('dialog', this.#dialogHandler);
+        this.networkCollector.dispose();
+        this.consoleCollector.dispose();
+        const devtoolsUniverse = this.#devtoolsUniverse;
+        this.#devtoolsUniverse = undefined;
+        devtoolsUniverse?.universe.dispose();
+        void devtoolsUniverse?.session.detach().catch(e => {
+            logger?.('Failed to detach DevTools session', e);
+        });
     }
     async executeThirdPartyDeveloperTool(toolName, params, response) {
         // Creates array of ElementHandles from the UIDs in the params.
@@ -185,27 +481,40 @@ export class McpPage {
             }, i);
             elementHandles.push(elementHandle);
         }
+        await this.pptrPage.evaluate(() => {
+            if (window.__dtmcp) {
+                window.__dtmcp.stashedElements = undefined;
+            }
+        });
         if (elementHandles.length) {
-            const oldHandles = [...this.extraHandles];
-            this.textSnapshot = await TextSnapshot.create(this, {
-                extraHandles: elementHandles,
-            });
-            response.includeSnapshot();
-            for (const handle of oldHandles) {
-                await handle
-                    .dispose()
-                    .catch(e => logger('Failed to dispose old handle', e));
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const stack = __addDisposableResource(env_2, new DisposableStack(), false);
+                for (const handle of this.extraHandles) {
+                    stack.use(handle);
+                }
+                this.textSnapshot = await TextSnapshot.create(this, {
+                    extraHandles: elementHandles,
+                });
+                response.includeSnapshot();
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
             }
         }
         const cdpElementIds = await Promise.all(elementHandles.map(async (elementHandle, index) => {
             const backendNodeId = await elementHandle.backendNodeId();
             if (!backendNodeId) {
-                logger(`No backendNodeId for stashed DOM element with index ${index}`);
+                logger?.(`No backendNodeId for stashed DOM element with index ${index}`);
                 return `stashed-${index}`;
             }
-            const cdpElementId = this.resolveCdpElementId(backendNodeId);
+            const cdpElementId = this.textSnapshot?.resolveCdpElementId(backendNodeId);
             if (!cdpElementId) {
-                logger(`Could not get cdpElementId for backend node ${backendNodeId}`);
+                logger?.(`Could not get cdpElementId for backend node ${backendNodeId}`);
                 return `stashed-${index}`;
             }
             return cdpElementId;
@@ -261,35 +570,12 @@ export class McpPage {
     getAXNodeByUid(uid) {
         return this.textSnapshot?.idToNode.get(uid);
     }
-    resolveCdpElementId(cdpBackendNodeId) {
-        if (!cdpBackendNodeId) {
-            logger('no cdpBackendNodeId');
-            return;
-        }
-        const snapshot = this.textSnapshot;
-        if (!snapshot) {
-            logger('no text snapshot');
-            return;
-        }
-        // TODO: index by backendNodeId instead.
-        const queue = [snapshot.root];
-        while (queue.length) {
-            const current = queue.pop();
-            if (current.backendNodeId === cdpBackendNodeId) {
-                return current.id;
-            }
-            for (const child of current.children) {
-                queue.push(child);
-            }
-        }
-        return;
-    }
     async getDevToolsData() {
         try {
-            logger('Getting DevTools UI data');
-            const devtoolsPage = this.devToolsPage;
+            logger?.('Getting DevTools UI data');
+            const devtoolsPage = await this.getDevToolsPage();
             if (!devtoolsPage) {
-                logger('No DevTools page detected');
+                logger?.('No DevTools page detected');
                 return {};
             }
             const { cdpRequestId, cdpBackendNodeId } = await devtoolsPage.evaluate(async () => {
@@ -307,9 +593,150 @@ export class McpPage {
             return { cdpBackendNodeId, cdpRequestId };
         }
         catch (err) {
-            logger('error getting devtools data', err);
+            logger?.('error getting devtools data', err);
         }
         return {};
     }
+    async restoreEmulation() {
+        const currentSetting = this.emulationSettings;
+        await this.emulate(currentSetting);
+    }
+    async emulate(options) {
+        const page = this.pptrPage;
+        const newSettings = { ...this.emulationSettings };
+        // Skip network emulation if blocklist/allowlist is configured, as it conflicts with blocking rules in Puppeteer.
+        if (this.#hasNetworkBlockOrAllowlist) {
+            if (options.networkConditions !== undefined) {
+                throw new Error('Network throttling is not supported when network blocking (allowlist/blocklist) is configured.');
+            }
+        }
+        else if (!options.networkConditions) {
+            await page.emulateNetworkConditions(null);
+            delete newSettings.networkConditions;
+        }
+        else if (options.networkConditions === 'Offline') {
+            await page.emulateNetworkConditions({
+                offline: true,
+                download: 0,
+                upload: 0,
+                latency: 0,
+            });
+            newSettings.networkConditions = 'Offline';
+        }
+        else if (options.networkConditions in PredefinedNetworkConditions) {
+            const networkCondition = PredefinedNetworkConditions[options.networkConditions];
+            await page.emulateNetworkConditions(networkCondition);
+            newSettings.networkConditions = options.networkConditions;
+        }
+        const secondarySession = this.devtoolsUniverse?.session;
+        if (!options.cpuThrottlingRate) {
+            await page.emulateCPUThrottling(1);
+            if (secondarySession) {
+                await secondarySession.send('Emulation.setCPUThrottlingRate', {
+                    rate: 1,
+                });
+            }
+            delete newSettings.cpuThrottlingRate;
+        }
+        else {
+            await page.emulateCPUThrottling(options.cpuThrottlingRate);
+            if (secondarySession) {
+                await secondarySession.send('Emulation.setCPUThrottlingRate', {
+                    rate: options.cpuThrottlingRate,
+                });
+            }
+            newSettings.cpuThrottlingRate = options.cpuThrottlingRate;
+        }
+        if (!options.geolocation) {
+            await page.setGeolocation({ latitude: 0, longitude: 0 });
+            delete newSettings.geolocation;
+        }
+        else {
+            await page.setGeolocation(options.geolocation);
+            newSettings.geolocation = options.geolocation;
+        }
+        if (!options.userAgent) {
+            await page.setUserAgent({ userAgent: undefined });
+            delete newSettings.userAgent;
+        }
+        else {
+            await page.setUserAgent({ userAgent: options.userAgent });
+            newSettings.userAgent = options.userAgent;
+        }
+        if (!options.colorScheme || options.colorScheme === 'auto') {
+            await page.emulateMediaFeatures([
+                { name: 'prefers-color-scheme', value: '' },
+            ]);
+            delete newSettings.colorScheme;
+        }
+        else {
+            await page.emulateMediaFeatures([
+                { name: 'prefers-color-scheme', value: options.colorScheme },
+            ]);
+            newSettings.colorScheme = options.colorScheme;
+        }
+        if (!options.viewport) {
+            delete newSettings.viewport;
+        }
+        else {
+            const defaults = {
+                deviceScaleFactor: 1,
+                isMobile: false,
+                hasTouch: false,
+                isLandscape: false,
+            };
+            newSettings.viewport = { ...defaults, ...options.viewport };
+        }
+        if (options.extraHttpHeaders !== undefined) {
+            await page.setExtraHTTPHeaders(options.extraHttpHeaders);
+            newSettings.extraHttpHeaders = options.extraHttpHeaders;
+            if (Object.keys(options.extraHttpHeaders).length === 0) {
+                delete newSettings.extraHttpHeaders;
+            }
+        }
+        this.emulationSettings = Object.keys(newSettings).length ? newSettings : {};
+        this.updateTimeouts();
+        // This should happen after updating the page timeouts.
+        // Setting the viewport can trigger a reload which we don't want to timeout.
+        await page.setViewport(newSettings.viewport ?? null);
+    }
+    updateTimeouts() {
+        // For waiters 5sec timeout should be sufficient.
+        // Increased in case we throttle the CPU
+        const cpuMultiplier = this.cpuThrottlingRate;
+        this.pptrPage.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
+        // 10sec should be enough for the load event to be emitted during
+        // navigations.
+        // Increased in case we throttle the network requests or the CPU
+        const networkMultiplier = getNetworkMultiplierFromString(this.networkConditions);
+        this.pptrPage.setDefaultNavigationTimeout(this.#navigationTimeout * networkMultiplier * cpuMultiplier);
+    }
+    waitForTextOnPage(text, timeout) {
+        const frames = this.pptrPage.frames();
+        let locator = this.#locatorClass.race(frames.flatMap(frame => text.flatMap(value => [
+            frame.locator(`aria/${value}`),
+            frame.locator(`text/${value}`),
+        ])));
+        if (timeout) {
+            locator = locator.setTimeout(timeout);
+        }
+        return locator.wait();
+    }
+    /**
+     * We need to ignore favicon request as they make our test flaky
+     */
+    async setUpNetworkCollectorForTesting() {
+        this.networkCollector.dispose();
+        this.networkCollector = new NetworkCollector(this.pptrPage, undefined, collect => {
+            return {
+                request: req => {
+                    if (req.url().includes('favicon.ico')) {
+                        return;
+                    }
+                    collect(req);
+                },
+            };
+        });
+    }
 }
 //# sourceMappingURL=McpPage.js.map