chrome-ai-bridge 1.0.0

package/build/src/tools/iframe-popup-tools.js

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// src/tools/iframe-popup-tools.ts
+// Tools for inspecting & editing in-page iframe popups via CDP.
+// These tools enable direct access to iframe-embedded extension popups.
+// Uses OOPIF (Out-Of-Process iFrame) detection via Target.setAutoAttach.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function findExtensionIdViaTargets(cdp) {
+    const { targetInfos } = await cdp.send('Target.getTargets');
+    const ext = targetInfos.find(t => t.type === 'service_worker' && t.url.startsWith('chrome-extension://'));
+    if (!ext)
+        throw new Error('Extension service worker not found');
+    return new URL(ext.url).host;
+}
+export async function enableOopifAutoAttach(cdp) {
+    await cdp.send('Target.setDiscoverTargets', { discover: true });
+    await cdp.send('Target.setAutoAttach', {
+        autoAttach: true,
+        waitForDebuggerOnStart: false,
+        flatten: true, // Essential for OOPIF detection
+    });
+}
+export async function waitForExtensionChildTarget(cdp, pattern, timeoutMs = 8000) {
+    const start = Date.now();
+    return await new Promise((resolve, reject) => {
+        let resolved = false;
+        const onAttach = (e) => {
+            const url = e?.targetInfo?.url || '';
+            if (pattern.test(url)) {
+                resolved = true;
+                cleanup();
+                resolve({
+                    sessionId: e.sessionId,
+                    targetId: e.targetInfo.targetId,
+                    url,
+                });
+            }
+        };
+        const onTimeout = () => {
+            if (!resolved) {
+                cleanup();
+                reject(new Error(`Timeout: extension popup child target not found (pattern: ${pattern})`));
+            }
+        };
+        const cleanup = () => {
+            cdp.off('Target.attachedToTarget', onAttach);
+        };
+        cdp.on('Target.attachedToTarget', onAttach);
+        setTimeout(onTimeout, Math.max(0, timeoutMs - (Date.now() - start)));
+    });
+}
+export async function inspectIframe(cdp, urlPattern, waitMs = 8000) {
+    // Strategy: Use DOMSnapshot.captureSnapshot to get iframe-inclusive DOM structure
+    // Note: chrome-extension:// iframes may not be included due to SOP/extension isolation
+    await cdp.send('DOMSnapshot.enable');
+    try {
+        // Capture full DOM snapshot including iframes
+        const snapshot = await cdp.send('DOMSnapshot.captureSnapshot', {
+            computedStyles: [],
+            includeDOMRects: false,
+            includePaintOrder: false,
+        });
+        // Search for matching iframe in the snapshot
+        const result = findIframeInSnapshot(snapshot, urlPattern);
+        if (result) {
+            return {
+                frameId: null,
+                frameUrl: result.url,
+                html: result.html,
+            };
+        }
+        // Extension iframe not found in snapshot - this is expected behavior
+        // due to Same-Origin Policy and Chrome extension isolation
+        throw new Error('EXTENSION_FRAME_UNREADABLE: Chrome extension iframes are isolated by ' +
+            'Same-Origin Policy and extension security model. The iframe exists but ' +
+            'cannot be read from the page context. This is expected Chrome behavior.');
+    }
+    catch (error) {
+        // If DOMSnapshot fails or iframe not found, provide clear explanation
+        if (error.message?.includes('EXTENSION_FRAME_UNREADABLE')) {
+            throw error;
+        }
+        throw new Error(`Failed to capture DOM snapshot: ${error.message}. ` +
+            'Note: Chrome extension iframes are typically unreadable due to security policies.');
+    }
+    finally {
+        await cdp.send('DOMSnapshot.disable');
+    }
+}
+function findIframeInSnapshot(snapshot, urlPattern) {
+    // DOMSnapshot structure:
+    // - documents: array of document snapshots
+    // - strings: string table for deduplication
+    const documents = snapshot.documents || [];
+    for (const doc of documents) {
+        const baseURL = doc.baseURL;
+        // Check if this document matches the pattern
+        if (baseURL && urlPattern.test(baseURL)) {
+            // Reconstruct HTML from snapshot
+            const html = reconstructHTMLFromSnapshot(doc, snapshot.strings || []);
+            return { url: baseURL, html };
+        }
+    }
+    return null;
+}
+function reconstructHTMLFromSnapshot(doc, strings) {
+    // Simple reconstruction - get text content from nodes
+    // Note: DOMSnapshot doesn't provide perfect HTML reconstruction
+    // but gives us the essential content
+    const nodes = doc.nodes || {};
+    const nodeNames = nodes.nodeName || [];
+    const nodeValues = nodes.nodeValue || [];
+    const textValues = nodes.textValue || {};
+    // Build a simple HTML representation
+    let html = '<html>';
+    // Try to find body content
+    for (let i = 0; i < nodeNames.length; i++) {
+        const nameIdx = nodeNames[i];
+        const name = strings[nameIdx] || '';
+        const valueIdx = nodeValues[i];
+        const value = valueIdx >= 0 ? strings[valueIdx] : '';
+        if (name === '#document' || name === 'HTML')
+            continue;
+        if (name === '#text' && value) {
+            html += value;
+        }
+        else if (name) {
+            html += `<${name}>`;
+        }
+    }
+    html += '</html>';
+    return html;
+}
+async function sendToChildSession(cdp, sessionId, method, params) {
+    const id = Math.floor(Math.random() * 1000000);
+    const message = JSON.stringify({ id, method, params });
+    // Send message to child target
+    await cdp.send('Target.sendMessageToTarget', { sessionId, message });
+    // Wait for response from child target
+    return await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error(`Timeout waiting for response from child session: ${method}`));
+        }, 5000);
+        const onMessage = (e) => {
+            if (e.sessionId === sessionId) {
+                try {
+                    const response = JSON.parse(e.message);
+                    if (response.id === id) {
+                        cleanup();
+                        if (response.error) {
+                            reject(new Error(`CDP error: ${JSON.stringify(response.error)}`));
+                        }
+                        else {
+                            resolve(response.result);
+                        }
+                    }
+                }
+                catch (err) {
+                    // Ignore parse errors for other messages
+                }
+            }
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            cdp.off('Target.receivedMessageFromTarget', onMessage);
+        };
+        cdp.on('Target.receivedMessageFromTarget', onMessage);
+    });
+}
+export async function patchAndReload(cdp, extensionPath, patches) {
+    for (const p of patches) {
+        const abs = path.join(extensionPath, p.file);
+        const src = await fs.readFile(abs, 'utf8');
+        const rx = new RegExp(p.find, 'g');
+        const out = src.replace(rx, p.replace);
+        if (out != src)
+            await fs.writeFile(abs, out, 'utf8');
+    }
+    await reloadExtension(cdp);
+}
+export async function reloadExtension(cdp) {
+    const { targetInfos } = await cdp.send('Target.getTargets');
+    const sw = targetInfos.find(t => t.type === 'service_worker' && t.url.startsWith('chrome-extension://'));
+    if (!sw)
+        throw new Error('Extension service worker not found for reload');
+    // Attach to the service worker and execute chrome.runtime.reload()
+    const { sessionId } = await cdp.send('Target.attachToTarget', {
+        targetId: sw.targetId,
+        flatten: true,
+    });
+    await cdp.send('Target.sendMessageToTarget', {
+        sessionId,
+        message: JSON.stringify({
+            id: 1,
+            method: 'Runtime.evaluate',
+            params: { expression: 'chrome.runtime.reload()' },
+        }),
+    });
+}

package/build/src/tools/input.js

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const click = defineTool({
+    name: 'click',
+    description: 'Click on element by uid.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z.string().describe('Element uid'),
+        dblClick: z.boolean().optional().describe('Double click'),
+    },
+    handler: async (request, response, context) => {
+        const uid = request.params.uid;
+        const handle = await context.getElementByUid(uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().click({
+                    count: request.params.dblClick ? 2 : 1,
+                });
+            });
+            response.appendResponseLine('Clicked');
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const hover = defineTool({
+    name: 'hover',
+    description: 'Hover over element by uid.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z.string().describe('Element uid'),
+    },
+    handler: async (request, response, context) => {
+        const uid = request.params.uid;
+        const handle = await context.getElementByUid(uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().hover();
+            });
+            response.appendResponseLine('Hovered');
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const fill = defineTool({
+    name: 'fill',
+    description: 'Fill input, textarea, or select element.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z.string().describe('Element uid'),
+        value: z.string().describe('Value to fill'),
+    },
+    handler: async (request, response, context) => {
+        const handle = await context.getElementByUid(request.params.uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().fill(request.params.value);
+            });
+            response.appendResponseLine('Filled');
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const drag = defineTool({
+    name: 'drag',
+    description: 'Drag element to another element.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        from_uid: z.string().describe('Source element uid'),
+        to_uid: z.string().describe('Target element uid'),
+    },
+    handler: async (request, response, context) => {
+        const fromHandle = await context.getElementByUid(request.params.from_uid);
+        const toHandle = await context.getElementByUid(request.params.to_uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await fromHandle.drag(toHandle);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                await toHandle.drop(fromHandle);
+            });
+            response.appendResponseLine('Dragged');
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void fromHandle.dispose();
+            void toHandle.dispose();
+        }
+    },
+});
+export const fillForm = defineTool({
+    name: 'fill_form',
+    description: 'Fill multiple form elements.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        elements: z
+            .array(z.object({
+            uid: z.string().describe('Element uid'),
+            value: z.string().describe('Value'),
+        }))
+            .describe('Elements to fill'),
+    },
+    handler: async (request, response, context) => {
+        for (const element of request.params.elements) {
+            const handle = await context.getElementByUid(element.uid);
+            try {
+                await context.waitForEventsAfterAction(async () => {
+                    await handle.asLocator().fill(element.value);
+                });
+            }
+            finally {
+                void handle.dispose();
+            }
+        }
+        response.appendResponseLine('Form filled');
+        response.setIncludeSnapshot(true);
+    },
+});
+export const uploadFile = defineTool({
+    name: 'upload_file',
+    description: 'Upload file through element.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z.string().describe('File input element uid'),
+        filePath: z.string().describe('Local file path'),
+    },
+    handler: async (request, response, context) => {
+        const { uid, filePath } = request.params;
+        const handle = (await context.getElementByUid(uid));
+        try {
+            try {
+                await handle.uploadFile(filePath);
+            }
+            catch {
+                try {
+                    const page = await context.getSelectedPage();
+                    const [fileChooser] = await Promise.all([
+                        page.waitForFileChooser({ timeout: 3000 }),
+                        handle.asLocator().click(),
+                    ]);
+                    await fileChooser.accept([filePath]);
+                }
+                catch {
+                    throw new Error('Failed to upload file');
+                }
+            }
+            response.setIncludeSnapshot(true);
+            response.appendResponseLine(`Uploaded: ${filePath}`);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});

package/build/src/tools/network.js

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+const FILTERABLE_RESOURCE_TYPES = [
+    'document',
+    'stylesheet',
+    'image',
+    'media',
+    'font',
+    'script',
+    'texttrack',
+    'xhr',
+    'fetch',
+    'prefetch',
+    'eventsource',
+    'websocket',
+    'manifest',
+    'signedexchange',
+    'ping',
+    'cspviolationreport',
+    'preflight',
+    'fedcm',
+    'other',
+];
+/**
+ * Consolidated network tool.
+ * Combines: list_network_requests, get_network_request
+ */
+export const network = defineTool({
+    name: 'network',
+    description: 'Network requests: list all or get by URL.',
+    annotations: {
+        category: ToolCategories.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {
+        op: z.enum(['list', 'get']).describe('Operation'),
+        url: z.string().optional().describe('Request URL (for get)'),
+        pageSize: z.number().int().positive().optional().describe('Max results'),
+        pageIdx: z.number().int().min(0).optional().describe('Page number'),
+        resourceTypes: z
+            .array(z.enum(FILTERABLE_RESOURCE_TYPES))
+            .optional()
+            .describe('Filter types'),
+    },
+    handler: async (request, response) => {
+        const { op, url, pageSize, pageIdx, resourceTypes } = request.params;
+        if (op === 'list') {
+            response.setIncludeNetworkRequests(true, {
+                pageSize,
+                pageIdx,
+                resourceTypes,
+            });
+        }
+        else {
+            if (!url) {
+                throw new Error('url required for get');
+            }
+            response.attachNetworkRequest(url);
+            response.setIncludeNetworkRequests(true);
+        }
+    },
+});

package/build/src/tools/optional-tools.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as chatgptWebTools from './chatgpt-web.js';
+import * as geminiWebTools from './gemini-web.js';
+/**
+ * All optional (web-llm) tools as an array.
+ */
+export const optionalTools = [
+    ...Object.values(chatgptWebTools),
+    ...Object.values(geminiWebTools),
+];
+/**
+ * Check if web-llm tools should be loaded.
+ * Returns false if MCP_DISABLE_WEB_LLM is set to 'true'.
+ */
+export function shouldLoadWebLlmTools() {
+    const disable = process.env.MCP_DISABLE_WEB_LLM;
+    return disable !== 'true' && disable !== '1';
+}
+/**
+ * Register optional tools with a ToolRegistry.
+ * Respects MCP_DISABLE_WEB_LLM environment variable.
+ */
+export function registerOptionalTools(registry) {
+    if (!shouldLoadWebLlmTools()) {
+        console.error('[tools] Web-LLM tools disabled via MCP_DISABLE_WEB_LLM');
+        return 0;
+    }
+    let count = 0;
+    for (const tool of optionalTools) {
+        // Skip non-tool exports (like constants)
+        if (tool &&
+            typeof tool === 'object' &&
+            'name' in tool &&
+            'handler' in tool) {
+            try {
+                registry.register(tool);
+                count++;
+            }
+            catch (error) {
+                // Log but don't fail - optional tools should not block startup
+                console.error(`[tools] Failed to register optional tool: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    if (count > 0) {
+        console.error(`[tools] Loaded ${count} optional web-llm tools (experimental, may break)`);
+    }
+    return count;
+}
+/**
+ * Get count of optional tools.
+ */
+export function getOptionalToolCount() {
+    return optionalTools.filter(tool => tool && typeof tool === 'object' && 'name' in tool && 'handler' in tool).length;
+}
+/**
+ * Metadata about optional tools for documentation.
+ */
+export const WEB_LLM_TOOLS_INFO = {
+    disclaimer: 'Web-LLM tools (ask_chatgpt_web, ask_gemini_web) are experimental and best-effort. ' +
+        'They depend on specific website UIs and may break when those UIs change. ' +
+        'For production use, consider using official APIs instead.',
+    disableEnvVar: 'MCP_DISABLE_WEB_LLM',
+    tools: ['ask_chatgpt_web', 'ask_gemini_web'],
+};

package/build/src/tools/pages.js

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { CLOSE_PAGE_ERROR, defineTool } from './ToolDefinition.js';
+/**
+ * Consolidated page management tool.
+ * Combines: list_pages, select_page, close_page
+ */
+export const pages = defineTool({
+    name: 'pages',
+    description: 'Manage browser pages: list, select, or close.',
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        op: z.enum(['list', 'select', 'close']).describe('Operation'),
+        pageIdx: z.number().optional().describe('Page index (for select/close)'),
+    },
+    handler: async (request, response, context) => {
+        const { op, pageIdx } = request.params;
+        switch (op) {
+            case 'list':
+                response.setIncludePages(true);
+                break;
+            case 'select':
+                if (pageIdx === undefined) {
+                    throw new Error('pageIdx required for select');
+                }
+                const selectPage = context.getPageByIdx(pageIdx);
+                await selectPage.bringToFront();
+                context.setSelectedPageIdx(pageIdx);
+                response.setIncludePages(true);
+                break;
+            case 'close':
+                if (pageIdx === undefined) {
+                    throw new Error('pageIdx required for close');
+                }
+                try {
+                    await context.closePage(pageIdx);
+                }
+                catch (err) {
+                    if (err.message === CLOSE_PAGE_ERROR) {
+                        response.appendResponseLine(err.message);
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                response.setIncludePages(true);
+                break;
+        }
+    },
+});
+/**
+ * Consolidated navigation tool.
+ * Combines: navigate_page, navigate_page_history, new_page
+ */
+export const navigate = defineTool({
+    name: 'navigate',
+    description: 'Navigate: goto URL, back, forward, or open new page.',
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        op: z.enum(['goto', 'back', 'forward', 'new']).describe('Operation'),
+        url: z.string().optional().describe('URL (for goto/new)'),
+    },
+    handler: async (request, response, context) => {
+        const { op, url } = request.params;
+        switch (op) {
+            case 'goto':
+                if (!url) {
+                    throw new Error('url required for goto');
+                }
+                const gotoPage = context.getSelectedPage();
+                await context.waitForEventsAfterAction(async () => {
+                    await gotoPage.goto(url);
+                });
+                response.setIncludePages(true);
+                break;
+            case 'new':
+                if (!url) {
+                    throw new Error('url required for new');
+                }
+                const newPage = await context.newPage();
+                await context.waitForEventsAfterAction(async () => {
+                    await newPage.goto(url);
+                });
+                response.setIncludePages(true);
+                break;
+            case 'back':
+            case 'forward':
+                const navPage = context.getSelectedPage();
+                try {
+                    if (op === 'back') {
+                        await navPage.goBack();
+                    }
+                    else {
+                        await navPage.goForward();
+                    }
+                }
+                catch {
+                    response.appendResponseLine(`Unable to navigate ${op}`);
+                }
+                response.setIncludePages(true);
+                break;
+        }
+    },
+});
+/**
+ * Resize page dimensions.
+ */
+export const resizePage = defineTool({
+    name: 'resize_page',
+    description: 'Resize page dimensions.',
+    annotations: {
+        category: ToolCategories.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        width: z.number().describe('Width'),
+        height: z.number().describe('Height'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        // @ts-expect-error internal API for now.
+        await page.resize({
+            contentWidth: request.params.width,
+            contentHeight: request.params.height,
+        });
+        response.setIncludePages(true);
+    },
+});
+/**
+ * Handle browser dialog (alert, confirm, prompt).
+ */
+export const handleDialog = defineTool({
+    name: 'handle_dialog',
+    description: 'Handle browser dialog: accept or dismiss.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        action: z.enum(['accept', 'dismiss']).describe('Action'),
+        promptText: z.string().optional().describe('Prompt text'),
+    },
+    handler: async (request, response, context) => {
+        const dialog = context.getDialog();
+        if (!dialog) {
+            throw new Error('No open dialog found');
+        }
+        switch (request.params.action) {
+            case 'accept':
+                await dialog.accept(request.params.promptText);
+                response.appendResponseLine('Dialog accepted');
+                break;
+            case 'dismiss':
+                await dialog.dismiss();
+                response.appendResponseLine('Dialog dismissed');
+                break;
+        }
+        context.clearDialog();
+        response.setIncludePages(true);
+    },
+});