@browser_use/pi 0.1.0

package/dist/browser.js

@@ -0,0 +1,264 @@
+import { spawn, execFile } from 'node:child_process';
+import { access, mkdir, mkdtemp, open, readFile, realpath, rm, stat } from 'node:fs/promises';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+/** Declarative browser choices. BrowserUse owns the resulting connection lifecycle. */
+export const Browser = {
+    cloud: (options) => ({ ...options, kind: 'cloud' }),
+    chromium: (options = {}) => ({
+        ...options,
+        kind: 'chromium',
+    }),
+    chrome: (options = {}) => ({ ...options, kind: 'chrome' }),
+};
+/** Same profile discovery convention as Browser Harness on macOS, Linux and Windows. */
+export function chromeProfileDirs(platform = process.platform, home = homedir(), local = process.env.LOCALAPPDATA) {
+    if (platform === 'darwin')
+        return [join(home, 'Library/Application Support/Google/Chrome')];
+    if (platform === 'win32')
+        return [join(local || join(home, 'AppData/Local'), 'Google/Chrome/User Data')];
+    return [join(home, '.config/google-chrome'), join(home, '.config/chromium')];
+}
+async function discoverChrome(options) {
+    for (const profile of options.profileDir ? [options.profileDir] : chromeProfileDirs()) {
+        try {
+            const [port, path] = (await readFile(join(profile, 'DevToolsActivePort'), 'utf8'))
+                .trim()
+                .split('\n');
+            if (!port ||
+                !/^\d+$/.test(port) ||
+                +port < 1 ||
+                +port > 65535 ||
+                !path?.startsWith('/devtools/browser/'))
+                continue;
+            const response = await fetch(`http://127.0.0.1:${port}/json/version`, {
+                signal: AbortSignal.timeout(1500),
+            });
+            // Chrome 147 can disable HTTP discovery for its default profile.
+            if (response.status === 404)
+                return `ws://127.0.0.1:${port}${path}`;
+            if (!response.ok)
+                continue;
+            const info = (await response.json());
+            if (info.webSocketDebuggerUrl)
+                return info.webSocketDebuggerUrl;
+        }
+        catch { }
+    }
+    throw new Error('No running Chrome debugging endpoint found. Enable chrome://inspect/#remote-debugging and accept Chrome’s connection prompt, or pass Browser.chrome({ cdpUrl }). No browser was launched or profile copied.');
+}
+async function openCloud(options) {
+    if (typeof options.apiKey !== 'string' || !options.apiKey.trim())
+        throw new Error('Browser.cloud requires apiKey.');
+    const timeout = options.timeoutMinutes ?? 30;
+    if (!Number.isInteger(timeout) || timeout <= 0 || timeout > 240)
+        throw new Error('timeoutMinutes must be an integer from 1 to 240.');
+    const request = async (path, method, body) => {
+        const response = await fetch(`https://api.browser-use.com/api/v3${path}`, {
+            method,
+            headers: { 'X-Browser-Use-API-Key': options.apiKey, 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw new Error(`Browser Use Cloud ${method} failed (${response.status}).`);
+        return response;
+    };
+    // Never retry provisioning: an ambiguous POST can already have created a billable browser.
+    const data = (await (await request('/browsers', 'POST', {
+        timeout,
+        enableRecording: false,
+        ...(options.profileId ? { profileId: options.profileId } : {}),
+        ...(options.proxyCountryCode ? { proxyCountryCode: options.proxyCountryCode } : {}),
+    })).json());
+    if (typeof data.id !== 'string' || !data.id)
+        throw new Error('Cloud response missing browser id; check the Cloud dashboard for an orphaned browser.');
+    let closing;
+    const close = () => (closing ??= request(`/browsers/${encodeURIComponent(data.id)}`, 'PATCH', { action: 'stop' })
+        .then(() => { })
+        .catch((error) => {
+        closing = undefined;
+        throw error;
+    }));
+    try {
+        if (typeof data.cdpUrl !== 'string' ||
+            !['ws:', 'wss:', 'http:', 'https:'].includes(new URL(data.cdpUrl).protocol))
+            throw new Error('Cloud response missing valid cdpUrl.');
+        return { endpoint: data.cdpUrl, close };
+    }
+    catch (error) {
+        try {
+            await close();
+        }
+        catch {
+            throw new Error(`Invalid Cloud response and cleanup failed for browser ${data.id}; stop it in the Cloud dashboard.`);
+        }
+        throw error;
+    }
+}
+async function executable(options) {
+    if (options.executablePath) {
+        await access(options.executablePath);
+        return options.executablePath;
+    }
+    const candidates = process.platform === 'darwin'
+        ? [
+            options.channel === 'msedge'
+                ? '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'
+                : '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        ]
+        : process.platform === 'win32'
+            ? [
+                join(process.env.PROGRAMFILES ?? 'C:\\Program Files', options.channel === 'msedge'
+                    ? 'Microsoft/Edge/Application/msedge.exe'
+                    : 'Google/Chrome/Application/chrome.exe'),
+            ]
+            : options.channel === 'msedge'
+                ? ['/usr/bin/microsoft-edge']
+                : ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+    for (const path of candidates) {
+        try {
+            await access(path);
+            return path;
+        }
+        catch { }
+    }
+    throw new Error('Chrome not found. Install Chrome or set browser.executablePath / browser.cdpUrl.');
+}
+/** Local Chrome has an isolated temporary profile; external Chrome always belongs to the caller. */
+export async function openBrowser(options = {}) {
+    if (options.kind !== undefined && !['cloud', 'chrome', 'chromium'].includes(options.kind))
+        throw new Error('Unknown browser kind. Use Browser.cloud, Browser.chromium or Browser.chrome.');
+    if (options.kind === 'cloud')
+        return openCloud(options);
+    if (options.kind === 'chrome') {
+        if (options.approveConnection !== undefined && typeof options.approveConnection !== 'boolean')
+            throw new Error('approveConnection must be boolean.');
+        if (options.approveConnection && process.platform !== 'darwin')
+            throw new Error('approveConnection is supported only on macOS.');
+        const endpoint = options.cdpUrl ?? (await discoverChrome(options));
+        if (!['http:', 'https:', 'ws:', 'wss:'].includes(new URL(endpoint).protocol))
+            throw new Error('Invalid Chrome CDP endpoint.');
+        return { endpoint, close: async () => { } };
+    }
+    if ('cdpUrl' in options && options.cdpUrl) {
+        if (['headless', 'channel', 'executablePath', 'profileDir'].some((key) => key in options))
+            throw new Error('cdpUrl cannot be combined with local browser options.');
+        if (!['http:', 'https:', 'ws:', 'wss:'].includes(new URL(options.cdpUrl).protocol))
+            throw new Error('cdpUrl must be an HTTP(S) or WebSocket endpoint.');
+        return { endpoint: options.cdpUrl, close: async () => { } };
+    }
+    const path = await executable(options);
+    const persistent = !!options.profileDir;
+    if (options.profileDir)
+        await mkdir(options.profileDir, { recursive: true, mode: 0o700 });
+    const profile = options.profileDir
+        ? await realpath(options.profileDir)
+        : await mkdtemp(join(tmpdir(), 'browser-use-'));
+    const lockPath = join(profile, '.bu-pi.lock');
+    const lock = await open(lockPath, 'wx', 0o600).catch(() => {
+        throw new Error(`Browser profile is locked: ${profile}. Close its owner. After a crash, verify Chrome and the SDK have exited before removing .bu-pi.lock.`);
+    });
+    await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+    const launchedAt = Date.now();
+    const child = spawn(path, [
+        `--user-data-dir=${profile}`,
+        '--remote-debugging-port=0',
+        '--remote-debugging-address=127.0.0.1',
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--window-size=1440,900',
+        ...(options.headless === false ? [] : ['--headless=new']),
+        'about:blank',
+    ], { stdio: 'ignore' });
+    let launchError;
+    child.on('error', (error) => {
+        launchError = error;
+    });
+    let closing;
+    const close = () => (closing ??= (async () => {
+        if (child.exitCode === null && child.signalCode === null && child.pid) {
+            const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+            child.kill('SIGTERM');
+            const timer = setTimeout(() => child.kill('SIGKILL'), 2000);
+            await exited;
+            clearTimeout(timer);
+        }
+        await lock.close();
+        await rm(lockPath, { force: true });
+        if (!persistent)
+            await rm(profile, { recursive: true, force: true });
+    })());
+    try {
+        const deadline = Date.now() + 15_000;
+        while (Date.now() < deadline) {
+            if (launchError)
+                throw launchError;
+            if (child.exitCode !== null || child.signalCode !== null)
+                throw new Error('Chrome exited before exposing CDP.');
+            try {
+                if ((await stat(join(profile, 'DevToolsActivePort'))).mtimeMs < launchedAt - 1)
+                    throw new Error('Waiting for a fresh DevTools endpoint.');
+                const [port, path] = (await readFile(join(profile, 'DevToolsActivePort'), 'utf8'))
+                    .trim()
+                    .split('\n');
+                if (port && path)
+                    return { endpoint: `ws://127.0.0.1:${port}${path}`, close };
+            }
+            catch { }
+            await delay(50);
+        }
+        throw new Error('Chrome did not expose CDP within 15000 ms.');
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
+/** Narrow AX action from Browser Harness. Never enables debugging or grants Accessibility. */
+export function approveChromeConnection(signal) {
+    const script = `using terms from application "System Events"
+    on clickAllow(nodeRef)
+      try
+        if (role of nodeRef as text) is "AXButton" and (description of nodeRef as text) is "Allow" then
+          perform action "AXPress" of nodeRef
+          return true
+        end if
+      end try
+      try
+        repeat with childRef in UI elements of nodeRef
+          if my clickAllow(childRef) then return true
+        end repeat
+      end try
+      return false
+    end clickAllow
+  end using terms from
+  tell application "System Events"
+    if exists process "Google Chrome" then
+      tell process "Google Chrome"
+        repeat with w in windows
+          try
+            repeat with s in sheets of w
+              if (name of s as text) is "Allow remote debugging?" then
+                if my clickAllow(s) then return "ready"
+              end if
+            end repeat
+          end try
+        end repeat
+      end tell
+    end if
+  end tell
+  return "not-found"`;
+    return new Promise((resolve, reject) => {
+        execFile('/usr/bin/osascript', ['-e', script], { timeout: 5000, signal }, (error, stdout) => {
+            if (error)
+                reject(new Error('Chrome approval needs macOS Accessibility permission for the app running Browser Use Pi. Accept Chrome’s prompt manually, or grant that permission.'));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn, execFile } from 'node:child_process';\nimport { access, mkdir, mkdtemp, open, readFile, realpath, rm, stat } from 'node:fs/promises';\nimport { tmpdir, homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { setTimeout as delay } from 'node:timers/promises';\n\nexport interface LocalBrowserOptions {\n  headless?: boolean;\n  channel?: 'chrome' | 'msedge';\n  executablePath?: string;\n  profileDir?: string;\n}\nexport interface CloudBrowserOptions {\n  apiKey: string;\n  profileId?: string;\n  timeoutMinutes?: number;\n  proxyCountryCode?: string;\n}\nexport interface ChromeBrowserOptions {\n  cdpUrl?: string;\n  /** User-data root containing DevToolsActivePort, not its Default subdirectory. */\n  profileDir?: string;\n  targetId?: string;\n  /** macOS only: accept Chrome’s exact remote-debugging sheet while connecting. */\n  approveConnection?: boolean;\n}\nexport type BrowserOptions =\n  | ({ kind: 'cloud' } & CloudBrowserOptions)\n  | ({ kind: 'chromium' } & LocalBrowserOptions)\n  | ({ kind: 'chrome' } & ChromeBrowserOptions)\n  | ({ kind?: never; cdpUrl: string; targetId?: string } & {\n      [K in keyof LocalBrowserOptions]?: never;\n    })\n  | ({ kind?: never; cdpUrl?: never; targetId?: never } & LocalBrowserOptions);\n\n/** Declarative browser choices. BrowserUse owns the resulting connection lifecycle. */\nexport const Browser = {\n  cloud: (options: CloudBrowserOptions): BrowserOptions => ({ ...options, kind: 'cloud' }),\n  chromium: (options: LocalBrowserOptions = {}): BrowserOptions => ({\n    ...options,\n    kind: 'chromium',\n  }),\n  chrome: (options: ChromeBrowserOptions = {}): BrowserOptions => ({ ...options, kind: 'chrome' }),\n};\n\n/** Same profile discovery convention as Browser Harness on macOS, Linux and Windows. */\nexport function chromeProfileDirs(\n  platform = process.platform,\n  home = homedir(),\n  local = process.env.LOCALAPPDATA,\n) {\n  if (platform === 'darwin') return [join(home, 'Library/Application Support/Google/Chrome')];\n  if (platform === 'win32')\n    return [join(local || join(home, 'AppData/Local'), 'Google/Chrome/User Data')];\n  return [join(home, '.config/google-chrome'), join(home, '.config/chromium')];\n}\nasync function discoverChrome(options: ChromeBrowserOptions) {\n  for (const profile of options.profileDir ? [options.profileDir] : chromeProfileDirs()) {\n    try {\n      const [port, path] = (await readFile(join(profile, 'DevToolsActivePort'), 'utf8'))\n        .trim()\n        .split('\\n');\n      if (\n        !port ||\n        !/^\\d+$/.test(port) ||\n        +port < 1 ||\n        +port > 65535 ||\n        !path?.startsWith('/devtools/browser/')\n      )\n        continue;\n      const response = await fetch(`http://127.0.0.1:${port}/json/version`, {\n        signal: AbortSignal.timeout(1500),\n      });\n      // Chrome 147 can disable HTTP discovery for its default profile.\n      if (response.status === 404) return `ws://127.0.0.1:${port}${path}`;\n      if (!response.ok) continue;\n      const info = (await response.json()) as { webSocketDebuggerUrl?: string };\n      if (info.webSocketDebuggerUrl) return info.webSocketDebuggerUrl;\n    } catch {}\n  }\n  throw new Error(\n    'No running Chrome debugging endpoint found. Enable chrome://inspect/#remote-debugging and accept Chrome’s connection prompt, or pass Browser.chrome({ cdpUrl }). No browser was launched or profile copied.',\n  );\n}\n\nasync function openCloud(options: CloudBrowserOptions) {\n  if (typeof options.apiKey !== 'string' || !options.apiKey.trim())\n    throw new Error('Browser.cloud requires apiKey.');\n  const timeout = options.timeoutMinutes ?? 30;\n  if (!Number.isInteger(timeout) || timeout <= 0 || timeout > 240)\n    throw new Error('timeoutMinutes must be an integer from 1 to 240.');\n  const request = async (path: string, method: string, body: object) => {\n    const response = await fetch(`https://api.browser-use.com/api/v3${path}`, {\n      method,\n      headers: { 'X-Browser-Use-API-Key': options.apiKey, 'Content-Type': 'application/json' },\n      body: JSON.stringify(body),\n      signal: AbortSignal.timeout(30_000),\n      redirect: 'error',\n    });\n    if (!response.ok) throw new Error(`Browser Use Cloud ${method} failed (${response.status}).`);\n    return response;\n  };\n  // Never retry provisioning: an ambiguous POST can already have created a billable browser.\n  const data = (await (\n    await request('/browsers', 'POST', {\n      timeout,\n      enableRecording: false,\n      ...(options.profileId ? { profileId: options.profileId } : {}),\n      ...(options.proxyCountryCode ? { proxyCountryCode: options.proxyCountryCode } : {}),\n    })\n  ).json()) as { id?: string; cdpUrl?: string; liveUrl?: string };\n  if (typeof data.id !== 'string' || !data.id)\n    throw new Error(\n      'Cloud response missing browser id; check the Cloud dashboard for an orphaned browser.',\n    );\n  let closing: Promise<void> | undefined;\n  const close = () =>\n    (closing ??= request(`/browsers/${encodeURIComponent(data.id!)}`, 'PATCH', { action: 'stop' })\n      .then(() => {})\n      .catch((error) => {\n        closing = undefined;\n        throw error;\n      }));\n  try {\n    if (\n      typeof data.cdpUrl !== 'string' ||\n      !['ws:', 'wss:', 'http:', 'https:'].includes(new URL(data.cdpUrl).protocol)\n    )\n      throw new Error('Cloud response missing valid cdpUrl.');\n    return { endpoint: data.cdpUrl, close };\n  } catch (error) {\n    try {\n      await close();\n    } catch {\n      throw new Error(\n        `Invalid Cloud response and cleanup failed for browser ${data.id}; stop it in the Cloud dashboard.`,\n      );\n    }\n    throw error;\n  }\n}\n\nasync function executable(options: LocalBrowserOptions) {\n  if (options.executablePath) {\n    await access(options.executablePath);\n    return options.executablePath;\n  }\n  const candidates =\n    process.platform === 'darwin'\n      ? [\n          options.channel === 'msedge'\n            ? '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'\n            : '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',\n          '/Applications/Chromium.app/Contents/MacOS/Chromium',\n        ]\n      : process.platform === 'win32'\n        ? [\n            join(\n              process.env.PROGRAMFILES ?? 'C:\\\\Program Files',\n              options.channel === 'msedge'\n                ? 'Microsoft/Edge/Application/msedge.exe'\n                : 'Google/Chrome/Application/chrome.exe',\n            ),\n          ]\n        : options.channel === 'msedge'\n          ? ['/usr/bin/microsoft-edge']\n          : ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser'];\n  for (const path of candidates) {\n    try {\n      await access(path);\n      return path;\n    } catch {}\n  }\n  throw new Error(\n    'Chrome not found. Install Chrome or set browser.executablePath / browser.cdpUrl.',\n  );\n}\n\n/** Local Chrome has an isolated temporary profile; external Chrome always belongs to the caller. */\nexport async function openBrowser(options: BrowserOptions = {}) {\n  if (options.kind !== undefined && !['cloud', 'chrome', 'chromium'].includes(options.kind))\n    throw new Error('Unknown browser kind. Use Browser.cloud, Browser.chromium or Browser.chrome.');\n  if (options.kind === 'cloud') return openCloud(options);\n  if (options.kind === 'chrome') {\n    if (options.approveConnection !== undefined && typeof options.approveConnection !== 'boolean')\n      throw new Error('approveConnection must be boolean.');\n    if (options.approveConnection && process.platform !== 'darwin')\n      throw new Error('approveConnection is supported only on macOS.');\n    const endpoint = options.cdpUrl ?? (await discoverChrome(options));\n    if (!['http:', 'https:', 'ws:', 'wss:'].includes(new URL(endpoint).protocol))\n      throw new Error('Invalid Chrome CDP endpoint.');\n    return { endpoint, close: async () => {} };\n  }\n  if ('cdpUrl' in options && options.cdpUrl) {\n    if (['headless', 'channel', 'executablePath', 'profileDir'].some((key) => key in options))\n      throw new Error('cdpUrl cannot be combined with local browser options.');\n    if (!['http:', 'https:', 'ws:', 'wss:'].includes(new URL(options.cdpUrl).protocol))\n      throw new Error('cdpUrl must be an HTTP(S) or WebSocket endpoint.');\n    return { endpoint: options.cdpUrl, close: async () => {} };\n  }\n  const path = await executable(options as LocalBrowserOptions);\n  const persistent = !!options.profileDir;\n  if (options.profileDir) await mkdir(options.profileDir, { recursive: true, mode: 0o700 });\n  const profile = options.profileDir\n    ? await realpath(options.profileDir)\n    : await mkdtemp(join(tmpdir(), 'browser-use-'));\n  const lockPath = join(profile, '.bu-pi.lock');\n  const lock = await open(lockPath, 'wx', 0o600).catch(() => {\n    throw new Error(\n      `Browser profile is locked: ${profile}. Close its owner. After a crash, verify Chrome and the SDK have exited before removing .bu-pi.lock.`,\n    );\n  });\n  await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));\n  const launchedAt = Date.now();\n  const child = spawn(\n    path,\n    [\n      `--user-data-dir=${profile}`,\n      '--remote-debugging-port=0',\n      '--remote-debugging-address=127.0.0.1',\n      '--no-first-run',\n      '--no-default-browser-check',\n      '--window-size=1440,900',\n      ...(options.headless === false ? [] : ['--headless=new']),\n      'about:blank',\n    ],\n    { stdio: 'ignore' },\n  );\n  let launchError: Error | undefined;\n  child.on('error', (error) => {\n    launchError = error;\n  });\n  let closing: Promise<void> | undefined;\n  const close = () =>\n    (closing ??= (async () => {\n      if (child.exitCode === null && child.signalCode === null && child.pid) {\n        const exited = new Promise<void>((resolve) => child.once('exit', () => resolve()));\n        child.kill('SIGTERM');\n        const timer = setTimeout(() => child.kill('SIGKILL'), 2000);\n        await exited;\n        clearTimeout(timer);\n      }\n      await lock.close();\n      await rm(lockPath, { force: true });\n      if (!persistent) await rm(profile, { recursive: true, force: true });\n    })());\n  try {\n    const deadline = Date.now() + 15_000;\n    while (Date.now() < deadline) {\n      if (launchError) throw launchError;\n      if (child.exitCode !== null || child.signalCode !== null)\n        throw new Error('Chrome exited before exposing CDP.');\n      try {\n        if ((await stat(join(profile, 'DevToolsActivePort'))).mtimeMs < launchedAt - 1)\n          throw new Error('Waiting for a fresh DevTools endpoint.');\n        const [port, path] = (await readFile(join(profile, 'DevToolsActivePort'), 'utf8'))\n          .trim()\n          .split('\\n');\n        if (port && path) return { endpoint: `ws://127.0.0.1:${port}${path}`, close };\n      } catch {}\n      await delay(50);\n    }\n    throw new Error('Chrome did not expose CDP within 15000 ms.');\n  } catch (error) {\n    await close();\n    throw error;\n  }\n}\n\n/** Narrow AX action from Browser Harness. Never enables debugging or grants Accessibility. */\nexport function approveChromeConnection(signal: AbortSignal): Promise<string> {\n  const script = `using terms from application \"System Events\"\n    on clickAllow(nodeRef)\n      try\n        if (role of nodeRef as text) is \"AXButton\" and (description of nodeRef as text) is \"Allow\" then\n          perform action \"AXPress\" of nodeRef\n          return true\n        end if\n      end try\n      try\n        repeat with childRef in UI elements of nodeRef\n          if my clickAllow(childRef) then return true\n        end repeat\n      end try\n      return false\n    end clickAllow\n  end using terms from\n  tell application \"System Events\"\n    if exists process \"Google Chrome\" then\n      tell process \"Google Chrome\"\n        repeat with w in windows\n          try\n            repeat with s in sheets of w\n              if (name of s as text) is \"Allow remote debugging?\" then\n                if my clickAllow(s) then return \"ready\"\n              end if\n            end repeat\n          end try\n        end repeat\n      end tell\n    end if\n  end tell\n  return \"not-found\"`;\n  return new Promise((resolve, reject) => {\n    execFile('/usr/bin/osascript', ['-e', script], { timeout: 5000, signal }, (error, stdout) => {\n      if (error)\n        reject(\n          new Error(\n            'Chrome approval needs macOS Accessibility permission for the app running Browser Use Pi. Accept Chrome’s prompt manually, or grant that permission.',\n          ),\n        );\n      else resolve(stdout.trim());\n    });\n  });\n}\n"]}

package/dist/cdp.d.ts

@@ -0,0 +1,39 @@
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
+type Commands = ProtocolMapping.Commands;
+type Events = ProtocolMapping.Events;
+/** Explicit commands and one-shot events over one flattened CDP WebSocket. No proxies. */
+export declare class CDP {
+    private socket;
+    readonly timeoutMs: number;
+    private nextId;
+    private activity;
+    get observationTargetId(): string | undefined;
+    targetForSession(sessionId: string): string | undefined;
+    /** Optional metadata observer; errors cannot change command delivery. Never receives responses. */
+    observeCommand: ((method: string, params: unknown, sessionId?: string) => void) | undefined;
+    /** Passive result tap. Exceptions cannot change command delivery. May contain page data. */
+    observeResponse: ((method: string, params: unknown, result: unknown, sessionId?: string) => void) | undefined;
+    observeEvent: ((method: string, params: unknown, sessionId?: string) => void) | undefined;
+    private pending;
+    private listeners;
+    private constructor();
+    private endpoint;
+    private approveConnection;
+    private delegate;
+    private closed;
+    /** Defer network access until the first browser operation. Never replay a command. */
+    static lazy(endpoint: string, timeoutMs?: number, approveConnection?: boolean): CDP;
+    private connected;
+    static connect(endpoint: string, timeoutMs?: number, approveConnection?: boolean): Promise<CDP>;
+    send<M extends keyof Commands>(method: M, params?: Commands[M]['paramsType'][0], sessionId?: string): Promise<Commands[M]['returnType']>;
+    private sendMessage;
+    waitFor<M extends keyof Events>(method: M, options?: {
+        sessionId?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        predicate?: (event: Events[M][0]) => boolean;
+    }): Promise<Events[M][0]>;
+    private fail;
+    close(): void;
+}
+export {};

package/dist/cdp.js

@@ -0,0 +1,291 @@
+import { approveChromeConnection } from './browser.js';
+import { positiveInteger } from './protocol.js';
+/** Explicit commands and one-shot events over one flattened CDP WebSocket. No proxies. */
+export class CDP {
+    socket;
+    timeoutMs;
+    nextId = 0;
+    // Shared with the lazy connection. Observation follows protocol sessions, not JS variable names.
+    activity = {
+        targets: new Map(),
+        parents: new Map(),
+        targetId: undefined,
+    };
+    get observationTargetId() {
+        let targetId = this.activity.targetId;
+        const visited = new Set();
+        while (targetId && this.activity.parents.has(targetId) && !visited.has(targetId)) {
+            visited.add(targetId);
+            targetId = this.activity.parents.get(targetId);
+        }
+        return targetId;
+    }
+    targetForSession(sessionId) {
+        return this.activity.targets.get(sessionId);
+    }
+    /** Optional metadata observer; errors cannot change command delivery. Never receives responses. */
+    observeCommand;
+    /** Passive result tap. Exceptions cannot change command delivery. May contain page data. */
+    observeResponse;
+    observeEvent;
+    pending = new Map();
+    listeners = new Set();
+    constructor(socket, timeoutMs) {
+        this.socket = socket;
+        this.timeoutMs = timeoutMs;
+        if (!socket)
+            return;
+        socket.addEventListener('message', ({ data }) => {
+            try {
+                const message = JSON.parse(String(data));
+                if (message.id !== undefined) {
+                    const request = this.pending.get(message.id);
+                    if (message.error)
+                        request?.reject(new Error(`CDP ${message.error.code}: ${message.error.message}`));
+                    else
+                        request?.resolve(message.result);
+                }
+                else {
+                    this.observeEvent?.(message.method, message.params, message.sessionId);
+                    if (message.method === 'Target.detachedFromTarget')
+                        this.activity.targets.delete(message.params.sessionId);
+                    for (const listener of [...this.listeners]) {
+                        if (listener.method === message.method && listener.sessionId === message.sessionId)
+                            listener.accept(message.params);
+                    }
+                }
+            }
+            catch {
+                this.fail(new Error('Malformed CDP message.'));
+                socket.close();
+            }
+        });
+        socket.addEventListener('close', () => this.fail(new Error('CDP connection closed. Inspect state before retrying.')));
+        socket.addEventListener('error', () => this.fail(new Error('CDP connection failed.')));
+    }
+    endpoint;
+    approveConnection = false;
+    delegate;
+    closed = false;
+    /** Defer network access until the first browser operation. Never replay a command. */
+    static lazy(endpoint, timeoutMs = 15_000, approveConnection = false) {
+        const connection = new CDP(undefined, timeoutMs);
+        connection.endpoint = endpoint;
+        connection.approveConnection = approveConnection;
+        return connection;
+    }
+    connected() {
+        if (this.closed)
+            return Promise.reject(new Error('CDP connection is closed.'));
+        this.delegate ??= CDP.connect(this.endpoint, this.timeoutMs, this.approveConnection)
+            .then((connection) => {
+            if (this.closed) {
+                connection.close();
+                throw new Error('CDP connection is closed.');
+            }
+            connection.activity = this.activity;
+            connection.observeEvent = (method, params, session) => this.observeEvent?.(method, params, session);
+            connection.observeCommand = (method, params, sessionId) => this.observeCommand?.(method, params, sessionId);
+            return connection;
+        })
+            .catch((error) => {
+            this.delegate = undefined;
+            throw error;
+        });
+        return this.delegate;
+    }
+    static async connect(endpoint, timeoutMs = 15_000, approveConnection = false) {
+        if (approveConnection && process.platform !== 'darwin')
+            throw new Error('Chrome approval is macOS only.');
+        positiveInteger('timeoutMs', timeoutMs);
+        const url = new URL(endpoint);
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            url.pathname = `${url.pathname.replace(/\/$/, '')}/json/version`;
+            const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+            if (!response.ok)
+                throw new Error(`CDP discovery failed (${response.status}).`);
+            endpoint = (await response.json()).webSocketDebuggerUrl;
+        }
+        else if (!['ws:', 'wss:'].includes(url.protocol))
+            throw new Error('Unsupported CDP endpoint protocol.');
+        const socket = new WebSocket(endpoint);
+        const connection = new CDP(socket, timeoutMs);
+        await new Promise((resolve, reject) => {
+            const approval = new AbortController();
+            const finish = (error) => {
+                approval.abort();
+                clearTimeout(timer);
+                socket.removeEventListener('open', open);
+                socket.removeEventListener('error', failed);
+                socket.removeEventListener('close', failed);
+                if (error) {
+                    socket.close();
+                    reject(error);
+                }
+                else
+                    resolve();
+            };
+            const open = () => finish();
+            const failed = () => finish(new Error('Could not connect to CDP endpoint.'));
+            const timer = setTimeout(() => finish(new Error('CDP connection timed out.')), timeoutMs);
+            socket.addEventListener('open', open, { once: true });
+            socket.addEventListener('error', failed, { once: true });
+            socket.addEventListener('close', failed, { once: true });
+            if (approveConnection) {
+                void (async () => {
+                    while (!approval.signal.aborted) {
+                        await new Promise((resolve) => setTimeout(resolve, 300));
+                        if (approval.signal.aborted)
+                            return;
+                        if ((await approveChromeConnection(approval.signal)) === 'ready')
+                            return;
+                    }
+                })().catch((error) => {
+                    if (!approval.signal.aborted)
+                        finish(error);
+                });
+            }
+        });
+        return connection;
+    }
+    async send(method, params = {}, sessionId) {
+        // Capture the observer at dispatch, so late responses cannot enter a later cell.
+        const observe = this.observeResponse;
+        const result = this.endpoint
+            ? await (await this.connected()).send(method, params, sessionId)
+            : await this.sendMessage(method, params, sessionId);
+        if (method === 'Target.attachToTarget') {
+            const attached = result;
+            const target = params.targetId;
+            this.activity.targets.set(attached.sessionId, target);
+            this.activity.targetId = target;
+        }
+        else if (method === 'Target.detachFromTarget') {
+            const detached = params;
+            if (detached?.sessionId)
+                this.activity.targets.delete(detached.sessionId);
+        }
+        else if (method === 'Target.closeTarget' && result.success) {
+            const target = params.targetId;
+            if (this.observationTargetId === target || this.activity.targetId === target)
+                this.activity.targetId = undefined;
+            for (const [id, value] of this.activity.targets)
+                if (value === target)
+                    this.activity.targets.delete(id);
+            this.activity.parents.delete(target);
+        }
+        if (method === 'Target.getTargets' || method === 'Target.getTargetInfo') {
+            const infos = method === 'Target.getTargets'
+                ? result.targetInfos
+                : [result.targetInfo];
+            for (const info of infos)
+                if (info.type === 'iframe' && info.parentFrameId)
+                    this.activity.parents.set(info.targetId, info.parentFrameId);
+        }
+        if (method === 'Page.getFrameTree' && sessionId) {
+            const targetId = this.targetForSession(sessionId);
+            const visit = (tree) => {
+                if (targetId && tree.frame.id !== targetId)
+                    this.activity.parents.set(tree.frame.id, targetId);
+                tree.childFrames?.forEach(visit);
+            };
+            visit(result.frameTree);
+        }
+        try {
+            observe?.(method, params, result, sessionId);
+        }
+        catch { }
+        return result;
+    }
+    sendMessage(method, params, sessionId) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return Promise.reject(new Error('CDP connection is closed.'));
+        if (this.pending.size >= 256)
+            return Promise.reject(new Error('Too many pending CDP commands (256).'));
+        if (sessionId)
+            this.activity.targetId = this.targetForSession(sessionId);
+        try {
+            this.observeCommand?.(method, params, sessionId);
+        }
+        catch { }
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const finish = (error, value) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const timer = setTimeout(() => finish(new Error(`CDP ${method} exceeded ${this.timeoutMs} ms; the action may have happened.`)), this.timeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => finish(undefined, value),
+                reject: (error) => finish(error),
+            });
+            try {
+                this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    waitFor(method, options = {}) {
+        const timeoutMs = positiveInteger('timeoutMs', options.timeoutMs ?? this.timeoutMs);
+        if (this.endpoint)
+            return this.connected().then((connection) => connection.waitFor(method, options));
+        const promise = new Promise((resolve, reject) => {
+            const finish = (error, value) => {
+                clearTimeout(timer);
+                this.listeners.delete(listener);
+                options.signal?.removeEventListener('abort', abort);
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const listener = {
+                method,
+                sessionId: options.sessionId,
+                accept: (value) => {
+                    try {
+                        if (!options.predicate || options.predicate(value))
+                            finish(undefined, value);
+                    }
+                    catch (e) {
+                        finish(e instanceof Error ? e : new Error(String(e)));
+                    }
+                },
+                reject: (error) => finish(error),
+            };
+            const abort = () => finish(new Error(`CDP ${method} wait cancelled.`));
+            const timer = setTimeout(() => finish(new Error(`CDP event ${method} exceeded ${timeoutMs} ms.`)), timeoutMs);
+            this.listeners.add(listener);
+            options.signal?.addEventListener('abort', abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            else if (this.socket?.readyState !== WebSocket.OPEN)
+                finish(new Error('CDP connection is closed.'));
+        });
+        // A caller commonly registers a waiter before an action, then awaits it afterward.
+        void promise.catch(() => { });
+        return promise;
+    }
+    fail(error) {
+        for (const request of [...this.pending.values()])
+            request.reject(error);
+        for (const listener of [...this.listeners])
+            listener.reject(error);
+    }
+    close() {
+        this.closed = true;
+        this.activity.targets.clear();
+        this.activity.parents.clear();
+        this.activity.targetId = undefined;
+        void this.delegate?.then((connection) => connection.close()).catch(() => { });
+        this.fail(new Error('CDP connection closed.'));
+        this.socket?.close();
+    }
+}
+//# sourceMappingURL=cdp.js.map