chrome-ai-bridge 1.0.0

package/build/src/McpContext.js

@@ -0,0 +1,400 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { BrowserConnectionManager, } from './browser-connection-manager.js';
+import { NetworkCollector, PageCollector } from './PageCollector.js';
+import { pages } from './tools/pages.js';
+import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
+import { WaitForHelper } from './WaitForHelper.js';
+const DEFAULT_TIMEOUT = 5_000;
+const NAVIGATION_TIMEOUT = 10_000;
+function getNetworkMultiplierFromString(condition) {
+    const puppeteerCondition = condition;
+    switch (puppeteerCondition) {
+        case 'Fast 4G':
+            return 1;
+        case 'Slow 4G':
+            return 2.5;
+        case 'Fast 3G':
+            return 5;
+        case 'Slow 3G':
+            return 10;
+    }
+    return 1;
+}
+export class McpContext {
+    browser;
+    logger;
+    connectionManager;
+    // The most recent page state.
+    #pages = [];
+    #selectedPageIdx = 0;
+    // The most recent snapshot.
+    #textSnapshot = null;
+    #networkCollector;
+    #consoleCollector;
+    #isRunningTrace = false;
+    #networkConditionsMap = new WeakMap();
+    #cpuThrottlingRateMap = new WeakMap();
+    #dialog;
+    #nextSnapshotId = 1;
+    #traceResults = [];
+    // CDP Session management (v0.8.4+)
+    #browserSession;
+    #pageSessions = new Map();
+    constructor(browser, logger, browserFactory, connectionOptions) {
+        this.browser = browser;
+        this.logger = logger;
+        this.connectionManager = new BrowserConnectionManager(connectionOptions);
+        // Set up browser instance and factory for reconnection
+        if (browserFactory) {
+            this.connectionManager.setBrowser(browser, browserFactory);
+        }
+        this.#networkCollector = new NetworkCollector(this.browser, (page, collect) => {
+            page.on('request', request => {
+                collect(request);
+            });
+        });
+        this.#consoleCollector = new PageCollector(this.browser, (page, collect) => {
+            page.on('console', event => {
+                collect(event);
+            });
+            page.on('pageerror', event => {
+                if (event instanceof Error) {
+                    collect(event);
+                }
+                else {
+                    const error = new Error(`${event}`);
+                    error.stack = undefined;
+                    collect(error);
+                }
+            });
+        });
+    }
+    async #init() {
+        await this.createPagesSnapshot();
+        this.setSelectedPageIdx(0);
+        await this.#networkCollector.init();
+        await this.#consoleCollector.init();
+    }
+    static async from(browser, logger, browserFactory, connectionOptions) {
+        const context = new McpContext(browser, logger, browserFactory, connectionOptions);
+        await context.#init();
+        return context;
+    }
+    /**
+     * Dispose all CDP sessions to prevent memory leaks
+     */
+    async #disposeSessions() {
+        await Promise.allSettled([
+            this.#browserSession?.detach(),
+            ...[...this.#pageSessions.values()].map(s => s.detach()),
+        ]);
+        this.#browserSession = undefined;
+        this.#pageSessions.clear();
+    }
+    /**
+     * Reinitialize CDP protocol domains after reconnection
+     * This ensures proper CDP event handling after browser restart
+     */
+    async reinitializeCDP() {
+        try {
+            // 1. Dispose old sessions to prevent leaks
+            await this.#disposeSessions();
+            // 2. Create browser-level CDP session (public API, not _client())
+            this.#browserSession = await this.browser.target().createCDPSession();
+            this.logger('CDP: Browser-level session created');
+            // 3. Enable Target discovery and auto-attach
+            try {
+                await this.#browserSession.send('Target.setDiscoverTargets', {
+                    discover: true,
+                });
+                this.logger('CDP: Target discovery enabled');
+            }
+            catch (err) {
+                this.logger('Warning: Failed to enable target discovery:', err);
+            }
+            try {
+                await this.#browserSession.send('Target.setAutoAttach', {
+                    autoAttach: true,
+                    waitForDebuggerOnStart: false,
+                    flatten: true,
+                });
+                this.logger('CDP: Auto-attach configured');
+            }
+            catch (err) {
+                this.logger('Warning: Failed to configure auto-attach:', err);
+            }
+            // 4. Enable essential CDP domains for all targets
+            for (const target of this.browser.targets()) {
+                const type = target.type();
+                if (type === 'page') {
+                    const page = await target.page();
+                    if (!page)
+                        continue;
+                    try {
+                        const session = await page.createCDPSession();
+                        await Promise.allSettled([
+                            session.send('Network.enable'),
+                            session.send('Runtime.enable'),
+                            session.send('Log.enable'),
+                        ]);
+                        this.#pageSessions.set(page, session);
+                        this.logger(`CDP domains enabled for ${type}: ${page.url()}`);
+                    }
+                    catch (err) {
+                        this.logger(`Warning: Failed to enable CDP domains for ${type} ${page.url()}:`, err);
+                    }
+                }
+                // Service Worker / Worker support can be added here if needed
+                // if (type === 'service_worker' || type === 'worker') { ... }
+            }
+            this.logger('CDP protocol reinitialization completed');
+        }
+        catch (err) {
+            this.logger('Error during CDP reinitialization:', err);
+            // Don't throw - this is a best-effort operation
+            // The browser should still be usable even if CDP setup partially fails
+        }
+    }
+    /**
+     * Update browser instance after reconnection
+     */
+    async updateBrowser(newBrowser) {
+        // Dispose old sessions first
+        await this.#disposeSessions();
+        this.browser = newBrowser;
+        this.connectionManager.setBrowser(newBrowser, async () => newBrowser);
+        // Reinitialize CDP protocol domains BEFORE collectors
+        // This ensures CDP events are properly set up
+        await this.reinitializeCDP();
+        // Reinitialize collectors for new browser
+        await this.#networkCollector.init();
+        await this.#consoleCollector.init();
+        // Recreate pages snapshot
+        await this.createPagesSnapshot();
+        this.setSelectedPageIdx(0);
+        this.logger('Browser instance updated after reconnection');
+    }
+    getNetworkRequests() {
+        const page = this.getSelectedPage();
+        return this.#networkCollector.getData(page);
+    }
+    getConsoleData() {
+        const page = this.getSelectedPage();
+        return this.#consoleCollector.getData(page);
+    }
+    async newPage() {
+        const page = await this.browser.newPage();
+        const pages = await this.createPagesSnapshot();
+        this.setSelectedPageIdx(pages.indexOf(page));
+        this.#networkCollector.addPage(page);
+        this.#consoleCollector.addPage(page);
+        return page;
+    }
+    async closePage(pageIdx) {
+        if (this.#pages.length === 1) {
+            throw new Error(CLOSE_PAGE_ERROR);
+        }
+        const page = this.getPageByIdx(pageIdx);
+        this.setSelectedPageIdx(0);
+        await page.close({ runBeforeUnload: false });
+    }
+    getNetworkRequestByUrl(url) {
+        const requests = this.getNetworkRequests();
+        if (!requests.length) {
+            throw new Error('No requests found for selected page');
+        }
+        for (const request of requests) {
+            if (request.url() === url) {
+                return request;
+            }
+        }
+        throw new Error('Request not found for selected page');
+    }
+    setNetworkConditions(conditions) {
+        const page = this.getSelectedPage();
+        if (conditions === null) {
+            this.#networkConditionsMap.delete(page);
+        }
+        else {
+            this.#networkConditionsMap.set(page, conditions);
+        }
+        this.#updateSelectedPageTimeouts();
+    }
+    getNetworkConditions() {
+        const page = this.getSelectedPage();
+        return this.#networkConditionsMap.get(page) ?? null;
+    }
+    setCpuThrottlingRate(rate) {
+        const page = this.getSelectedPage();
+        this.#cpuThrottlingRateMap.set(page, rate);
+        this.#updateSelectedPageTimeouts();
+    }
+    getCpuThrottlingRate() {
+        const page = this.getSelectedPage();
+        return this.#cpuThrottlingRateMap.get(page) ?? 1;
+    }
+    setIsRunningPerformanceTrace(x) {
+        this.#isRunningTrace = x;
+    }
+    isRunningPerformanceTrace() {
+        return this.#isRunningTrace;
+    }
+    getDialog() {
+        return this.#dialog;
+    }
+    clearDialog() {
+        this.#dialog = undefined;
+    }
+    getSelectedPage() {
+        const page = this.#pages[this.#selectedPageIdx];
+        if (!page) {
+            throw new Error('No page selected');
+        }
+        if (page.isClosed()) {
+            throw new Error(`The selected page has been closed. Call ${pages.name} to see open pages.`);
+        }
+        return page;
+    }
+    getPageByIdx(idx) {
+        const pages = this.#pages;
+        const page = pages[idx];
+        if (!page) {
+            throw new Error('No page found');
+        }
+        return page;
+    }
+    getSelectedPageIdx() {
+        return this.#selectedPageIdx;
+    }
+    #dialogHandler = (dialog) => {
+        this.#dialog = dialog;
+    };
+    setSelectedPageIdx(idx) {
+        // Remove dialog handler from old page if exists
+        const oldPage = this.#pages[this.#selectedPageIdx];
+        if (oldPage && !oldPage.isClosed()) {
+            oldPage.off('dialog', this.#dialogHandler);
+        }
+        this.#selectedPageIdx = idx;
+        // Add dialog handler to new page if exists
+        const newPage = this.#pages[idx];
+        if (newPage && !newPage.isClosed()) {
+            newPage.on('dialog', this.#dialogHandler);
+            this.#updateSelectedPageTimeouts();
+        }
+    }
+    #updateSelectedPageTimeouts() {
+        const page = this.getSelectedPage();
+        // For waiters 5sec timeout should be sufficient.
+        // Increased in case we throttle the CPU
+        const cpuMultiplier = this.getCpuThrottlingRate();
+        page.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
+        const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
+        page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier);
+    }
+    getNavigationTimeout() {
+        const page = this.getSelectedPage();
+        return page.getDefaultNavigationTimeout();
+    }
+    async getElementByUid(uid) {
+        if (!this.#textSnapshot?.idToNode.size) {
+            throw new Error('No snapshot found. Use browser_snapshot to capture one');
+        }
+        const [snapshotId] = uid.split('_');
+        if (this.#textSnapshot.snapshotId !== snapshotId) {
+            throw new Error('This uid is coming from a stale snapshot. Call take_snapshot to get a fresh snapshot.');
+        }
+        const node = this.#textSnapshot?.idToNode.get(uid);
+        if (!node) {
+            throw new Error('No such element found in the snapshot');
+        }
+        const handle = await node.elementHandle();
+        if (!handle) {
+            throw new Error('No such element found in the snapshot');
+        }
+        return handle;
+    }
+    /**
+     * Creates a snapshot of the pages.
+     */
+    async createPagesSnapshot() {
+        this.#pages = await this.browser.pages();
+        return this.#pages;
+    }
+    getPages() {
+        return this.#pages;
+    }
+    /**
+     * Creates a text snapshot of a page.
+     */
+    async createTextSnapshot() {
+        const page = this.getSelectedPage();
+        const rootNode = await page.accessibility.snapshot();
+        if (!rootNode) {
+            return;
+        }
+        const snapshotId = this.#nextSnapshotId++;
+        // Iterate through the whole accessibility node tree and assign node ids that
+        // will be used for the tree serialization and mapping ids back to nodes.
+        let idCounter = 0;
+        const idToNode = new Map();
+        const assignIds = (node) => {
+            const nodeWithId = {
+                ...node,
+                id: `${snapshotId}_${idCounter++}`,
+                children: node.children
+                    ? node.children.map(child => assignIds(child))
+                    : [],
+            };
+            idToNode.set(nodeWithId.id, nodeWithId);
+            return nodeWithId;
+        };
+        const rootNodeWithId = assignIds(rootNode);
+        this.#textSnapshot = {
+            root: rootNodeWithId,
+            snapshotId: String(snapshotId),
+            idToNode,
+        };
+    }
+    getTextSnapshot() {
+        return this.#textSnapshot;
+    }
+    async saveTemporaryFile(data, mimeType) {
+        try {
+            const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-ai-bridge-'));
+            const filename = path.join(dir, mimeType == 'image/png' ? `screenshot.png` : 'screenshot.jpg');
+            await fs.writeFile(path.join(dir, `screenshot.png`), data);
+            return { filename };
+        }
+        catch (err) {
+            this.logger(err);
+            throw new Error('Could not save a screenshot to a file');
+        }
+    }
+    storeTraceRecording(result) {
+        this.#traceResults.push(result);
+    }
+    recordedTraces() {
+        return this.#traceResults;
+    }
+    getWaitForHelper(page, cpuMultiplier, networkMultiplier) {
+        return new WaitForHelper(page, cpuMultiplier, networkMultiplier);
+    }
+    waitForEventsAfterAction(action) {
+        const page = this.getSelectedPage();
+        const cpuMultiplier = this.getCpuThrottlingRate();
+        const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
+        const waitForHelper = this.getWaitForHelper(page, cpuMultiplier, networkMultiplier);
+        return waitForHelper.waitForEventsAfterAction(action);
+    }
+}

package/build/src/McpResponse.js

@@ -0,0 +1,237 @@
+import { getDevelopmentExtensionPaths } from './browser.js';
+import { formatConsoleEvent } from './formatters/consoleFormatter.js';
+import { formatExtensionsPage } from './formatters/extensionsPageFormatter.js';
+import { getFormattedHeaderValue, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
+import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
+import { paginate } from './utils/pagination.js';
+export class McpResponse {
+    #includePages = false;
+    #includeSnapshot = false;
+    #attachedNetworkRequestUrl;
+    #includeConsoleData = false;
+    #textResponseLines = [];
+    #formattedConsoleData;
+    #images = [];
+    #networkRequestsOptions;
+    setIncludePages(value) {
+        this.#includePages = value;
+    }
+    setIncludeSnapshot(value) {
+        this.#includeSnapshot = value;
+    }
+    setIncludeNetworkRequests(value, options) {
+        if (!value) {
+            this.#networkRequestsOptions = undefined;
+            return;
+        }
+        this.#networkRequestsOptions = {
+            include: value,
+            pagination: options?.pageSize || options?.pageIdx
+                ? {
+                    pageSize: options.pageSize,
+                    pageIdx: options.pageIdx,
+                }
+                : undefined,
+            resourceTypes: options?.resourceTypes,
+        };
+    }
+    setIncludeConsoleData(value) {
+        this.#includeConsoleData = value;
+    }
+    attachNetworkRequest(url) {
+        this.#attachedNetworkRequestUrl = url;
+    }
+    get includePages() {
+        return this.#includePages;
+    }
+    get includeNetworkRequests() {
+        return this.#networkRequestsOptions?.include ?? false;
+    }
+    get includeConsoleData() {
+        return this.#includeConsoleData;
+    }
+    get attachedNetworkRequestUrl() {
+        return this.#attachedNetworkRequestUrl;
+    }
+    get networkRequestsPageIdx() {
+        return this.#networkRequestsOptions?.pagination?.pageIdx;
+    }
+    appendResponseLine(value) {
+        this.#textResponseLines.push(value);
+    }
+    attachImage(value) {
+        this.#images.push(value);
+    }
+    get responseLines() {
+        return this.#textResponseLines;
+    }
+    get images() {
+        return this.#images;
+    }
+    get includeSnapshot() {
+        return this.#includeSnapshot;
+    }
+    async handle(toolName, context) {
+        if (this.#includePages) {
+            await context.createPagesSnapshot();
+        }
+        if (this.#includeSnapshot) {
+            await context.createTextSnapshot();
+        }
+        let formattedConsoleMessages;
+        if (this.#includeConsoleData) {
+            const consoleMessages = context.getConsoleData();
+            if (consoleMessages) {
+                formattedConsoleMessages = await Promise.all(consoleMessages.map(message => formatConsoleEvent(message)));
+                this.#formattedConsoleData = formattedConsoleMessages;
+            }
+        }
+        return this.format(toolName, context);
+    }
+    format(toolName, context) {
+        const response = [`# ${toolName} response`];
+        for (const line of this.#textResponseLines) {
+            response.push(line);
+        }
+        const networkConditions = context.getNetworkConditions();
+        if (networkConditions) {
+            response.push(`## Network emulation`);
+            response.push(`Emulating: ${networkConditions}`);
+            response.push(`Navigation timeout set to ${context.getNavigationTimeout()} ms`);
+        }
+        const cpuThrottlingRate = context.getCpuThrottlingRate();
+        if (cpuThrottlingRate > 1) {
+            response.push(`## CPU emulation`);
+            response.push(`Emulating: ${cpuThrottlingRate}x slowdown`);
+        }
+        const dialog = context.getDialog();
+        if (dialog) {
+            response.push(`# Open dialog
+${dialog.type()}: ${dialog.message()} (default value: ${dialog.message()}).
+Call browser_handle_dialog to handle it before continuing.`);
+        }
+        if (this.#includePages) {
+            const parts = [`## Pages`];
+            let idx = 0;
+            for (const page of context.getPages()) {
+                parts.push(`${idx}: ${page.url()}${idx === context.getSelectedPageIdx() ? ' [selected]' : ''}`);
+                idx++;
+            }
+            response.push(...parts);
+        }
+        if (this.#includeSnapshot) {
+            const snapshot = context.getTextSnapshot();
+            if (snapshot) {
+                const pageUrl = context.getSelectedPage().url();
+                const isExtensionsPage = pageUrl.startsWith('chrome://extensions');
+                let formattedSnapshot;
+                if (isExtensionsPage) {
+                    // Use structured extensions page formatter
+                    const developmentPaths = getDevelopmentExtensionPaths();
+                    formattedSnapshot = formatExtensionsPage(snapshot.root, developmentPaths);
+                    response.push(formattedSnapshot);
+                }
+                else {
+                    // Use standard accessibility tree formatter
+                    formattedSnapshot = formatA11ySnapshot(snapshot.root);
+                    response.push('## Page content');
+                    response.push(formattedSnapshot);
+                }
+            }
+        }
+        response.push(...this.#getIncludeNetworkRequestsData(context));
+        if (this.#networkRequestsOptions?.include) {
+            let requests = context.getNetworkRequests();
+            // Apply resource type filtering if specified
+            if (this.#networkRequestsOptions.resourceTypes?.length) {
+                const normalizedTypes = new Set(this.#networkRequestsOptions.resourceTypes);
+                requests = requests.filter(request => {
+                    const type = request.resourceType();
+                    return normalizedTypes.has(type);
+                });
+            }
+            response.push('## Network requests');
+            if (requests.length) {
+                const paginationResult = paginate(requests, this.#networkRequestsOptions.pagination);
+                if (paginationResult.invalidPage) {
+                    response.push('Invalid page number provided. Showing first page.');
+                }
+                const { startIndex, endIndex, currentPage, totalPages } = paginationResult;
+                response.push(`Showing ${startIndex + 1}-${endIndex} of ${requests.length} (Page ${currentPage + 1} of ${totalPages}).`);
+                if (this.#networkRequestsOptions.pagination) {
+                    if (paginationResult.hasNextPage) {
+                        response.push(`Next page: ${currentPage + 1}`);
+                    }
+                    if (paginationResult.hasPreviousPage) {
+                        response.push(`Previous page: ${currentPage - 1}`);
+                    }
+                }
+                for (const request of paginationResult.items) {
+                    response.push(getShortDescriptionForRequest(request));
+                }
+            }
+            else {
+                response.push('No requests found.');
+            }
+        }
+        if (this.#includeConsoleData && this.#formattedConsoleData) {
+            response.push('## Console messages');
+            if (this.#formattedConsoleData.length) {
+                response.push(...this.#formattedConsoleData);
+            }
+            else {
+                response.push('<no console messages found>');
+            }
+        }
+        const text = {
+            type: 'text',
+            text: response.join('\n'),
+        };
+        const images = this.#images.map(imageData => {
+            return {
+                type: 'image',
+                ...imageData,
+            };
+        });
+        return [text, ...images];
+    }
+    #getIncludeNetworkRequestsData(context) {
+        const response = [];
+        const url = this.#attachedNetworkRequestUrl;
+        if (!url) {
+            return response;
+        }
+        const httpRequest = context.getNetworkRequestByUrl(url);
+        response.push(`## Request ${httpRequest.url()}`);
+        response.push(`Status:  ${getStatusFromRequest(httpRequest)}`);
+        response.push(`### Request Headers`);
+        for (const line of getFormattedHeaderValue(httpRequest.headers())) {
+            response.push(line);
+        }
+        const httpResponse = httpRequest.response();
+        if (httpResponse) {
+            response.push(`### Response Headers`);
+            for (const line of getFormattedHeaderValue(httpResponse.headers())) {
+                response.push(line);
+            }
+        }
+        const httpFailure = httpRequest.failure();
+        if (httpFailure) {
+            response.push(`### Request failed with`);
+            response.push(httpFailure.errorText);
+        }
+        const redirectChain = httpRequest.redirectChain();
+        if (redirectChain.length) {
+            response.push(`### Redirect chain`);
+            let indent = 0;
+            for (const request of redirectChain.reverse()) {
+                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request)}`);
+                indent++;
+            }
+        }
+        return response;
+    }
+    resetResponseLineForTesting() {
+        this.#textResponseLines = [];
+    }
+}

package/build/src/Mutex.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class Mutex {
+    static Guard = class Guard {
+        #mutex;
+        #onRelease;
+        constructor(mutex, onRelease) {
+            this.#mutex = mutex;
+            this.#onRelease = onRelease;
+        }
+        dispose() {
+            this.#onRelease?.();
+            return this.#mutex.release();
+        }
+    };
+    #locked = false;
+    #acquirers = [];
+    // This is FIFO.
+    async acquire(onRelease) {
+        if (!this.#locked) {
+            this.#locked = true;
+            return new Mutex.Guard(this);
+        }
+        const { resolve, promise } = Promise.withResolvers();
+        this.#acquirers.push(resolve);
+        await promise;
+        return new Mutex.Guard(this, onRelease);
+    }
+    release() {
+        const resolve = this.#acquirers.shift();
+        if (!resolve) {
+            this.#locked = false;
+            return;
+        }
+        resolve();
+    }
+}