bopbop 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# better-browser-mcp: server reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server, the page agent and the relay extension. Setup steps for a team: [`INSTALL.md`](INSTALL.md).
+
+## Run
+
+From npm (the package is `bopbop`; the project is being renamed from better-browser-mcp):
+
+```bash
+claude mcp add -s user bbm -- npx -y bopbop
+codex mcp add bbm -- npx -y bopbop
+```
+
+From a clone:
+
+```bash
+bun install                                   # or: npm install
+claude mcp add -s user bbm -- bun /abs/path/prototype/src/server.ts
+codex mcp add bbm -- bun /abs/path/prototype/src/server.ts
+```
+
+Node 24+ also runs the server: replace `bun` with `node`.
+
+## Modes (`BBM_MODE`)
+
+| Mode | What it does | Settings |
+|---|---|---|
+| `launch` | Starts a fresh Chromium with a temporary profile. Headless unless `BBM_HEADLESS=0`. | `BBM_CHROME`: the browser binary; `BBM_CHROME_ARGS`: extra flags (e.g. `--no-sandbox` in CI) |
+| `connect` | Attaches to a running browser over CDP. | `BBM_CDP_URL=http://127.0.0.1:9222` |
+| `extension` (default) | Drives **your real Chrome profile** through the relay extension (build and load `dist/extension` unpacked). | `BBM_RELAY_PORT` pins one port; default: the first free port of 9333–9362 (30 sessions) |
+
+## Settings
+
+| Setting | Effect |
+|---|---|
+| `BBM_GUARD=shop-social` | Blocks Buy now, Place order, checkout pages and Post buttons (step checks, in-page guard, browser-level blocking). Under the guard, JavaScript clicks through `eval` are blocked too. |
+| `BBM_ALLOW=http://127.0.0.1:*,*.example.com` | Origin allowlist. Fails closed. Enforced in the browser (documents, frames, redirects, popups). |
+| `BBM_UPLOAD_ROOTS=/path/a,/path/b` | Upload files only from these folders (default `~/Downloads`, `$TMPDIR/bbm-uploads`). Hidden files are refused. |
+| `BBM_OUTPUT_DIR=/path` | Where HAR files go (default `~/Downloads/bbm`). The agent gives only a file name. |
+| `BBM_SHOW_COOKIES=1` | Show cookie and credential header values in full (default: shortened). |
+| `BBM_WINDOW=agent` | Extension mode: agent tabs in their own unfocused window. |
+| `BBM_KEEP_TABS=1` | Extension mode: keep the agent's tabs open when the session ends. |
+| `BBM_FRONT=1` | Extension mode: bring agent tabs to the front (old behavior). |
+| `BBM_TRACE=1` | Timing traces on stderr. |
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `navigate` | Open a URL (or back, forward, reload). Returns the snapshot; `snapshot: interactive\|none` for less. |
+| `act` | Batched steps; returns step results, events (navigation, dialogs, new tabs, errors) and what changed. Refs or locators: `text=Save`, `css=.bar button`, `e12 >> text=Save`; alternatives `css=textarea, text=Ask` (first match wins); an ambiguous `text=` gives a warning. |
+| `snapshot` | Page structure with refs. `search`, `ref`, `viewport`, `mode=interactive`, `scope=page` (default: the open dialog). |
+| `read` | Page text. `format=markdown`: the main content as Markdown. |
+| `extract` | Tables as rows keyed by column, label/value tables and `<dl>` as fields, as JSON. |
+| `wait` | Until text appears or goes, a ref is visible, or the URL matches. |
+| `screenshot` | JPEG of the viewport, a ref/locator, a `clip` rect (+`padding`) or the full page; `marks` draws refs. 1280 px wide at most, `scale: full` for 1:1. Returns the captured area in CSS px. |
+| `eval` | JavaScript for values that the other tools do not show. Awaits a returned Promise (`timeout`). One line if the page changed; `snapshot: diff\|full` shows the change. |
+| `console` | Console messages and page errors; identical messages show once with `×N`. |
+| `network` | Requests with time and size; `id`: phases, headers, bodies; `cookies`; `har` export. |
+| `emulate` | Device presets, viewport, dark mode, reduced motion, network and CPU throttling, `reset`; `window=true` resizes the agent window. |
+| `perf` | Web Vitals with ratings, long tasks, slowest and largest resources, heap and DOM size. |
+| `tabs` | List, open, select (one line), close, duplicate (keeps sessionStorage). Extension mode: `label` names the tab group `Agent:<1-5 letters, digits or emoji>` (default: project initials + slot, e.g. `Agent:CT2`). |
+
+`act` steps: `click`, `type` (+`submit`), `press`, `hover`, `select` (native or custom combobox, verified), `check`/`uncheck`, `upload`, `drag` (+`position`), `click_xy`, `scroll` (+`until`), `wait`, `wait_for`, `dialog`, `navigate`. Any ref field also accepts `text=Label`.
+
+## Test
+
+```bash
+npm test                 # unit + e2e (fixture tasks, guard, modal scope, extract, network, perf, emulate) + MCP stdio
+npm run test:extension   # the fixture suite through the extension relay (chrome.debugger)
+npm run bench:runtime    # Node vs Bun timings
+```
+
+Extension-only suites (focus, parallel sessions, other extensions) run in `npm test` with a test Chromium that loads the extension.

package/dist/npm/cdp/browser.js

@@ -0,0 +1,196 @@
+// Browser-level CDP wrapper: tab list, create/close/activate, attach.
+// Works the same over a direct CDP WebSocket and over the extension relay,
+// because the relay emulates the Target.* domain with chrome.tabs + chrome.debugger.
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { join } from 'node:path';
+import { CDPConnection, webSocketTransport } from './connection.js';
+export class CDPBrowser {
+    conn;
+    targets;
+    listeners;
+    _onClose;
+    process;
+    extensionId;
+    port;
+    mode;
+    relay; // extension mode: the RelayServer this link came from
+    constructor(conn, { onClose } = {}) {
+        this.conn = conn;
+        this.targets = new Map(); // targetId -> {targetId, url, title, openerId, type}
+        this.listeners = { created: new Set(), destroyed: new Set(), changed: new Set() };
+        this._onClose = onClose;
+    }
+    async init() {
+        this.conn.on('Target.targetCreated', ({ targetInfo: t }) => {
+            if (t.type !== 'page')
+                return;
+            this.targets.set(t.targetId, t);
+            for (const fn of this.listeners.created)
+                fn(t);
+        });
+        this.conn.on('Target.targetInfoChanged', ({ targetInfo: t }) => {
+            if (!this.targets.has(t.targetId))
+                return;
+            this.targets.set(t.targetId, t);
+            for (const fn of this.listeners.changed)
+                fn(t);
+        });
+        this.conn.on('Target.targetDestroyed', ({ targetId }) => {
+            if (!this.targets.delete(targetId))
+                return;
+            for (const fn of this.listeners.destroyed)
+                fn(targetId);
+        });
+        await this.conn.send('Target.setDiscoverTargets', { discover: true });
+        const { targetInfos } = await this.conn.send('Target.getTargets');
+        for (const t of targetInfos)
+            if (t.type === 'page')
+                this.targets.set(t.targetId, t);
+    }
+    onTabCreated(fn) {
+        this.listeners.created.add(fn);
+    }
+    onTabDestroyed(fn) {
+        this.listeners.destroyed.add(fn);
+    }
+    onTabChanged(fn) {
+        this.listeners.changed.add(fn);
+    }
+    listTabs() {
+        return [...this.targets.values()].filter((t) => !t.url.startsWith('devtools://') && !t.url.startsWith('chrome-extension://'));
+    }
+    async createTab(url = 'about:blank', { background = false, newWindow = false } = {}) {
+        const { targetId } = await this.conn.send('Target.createTarget', { url, background, ...(newWindow ? { newWindow } : {}) });
+        return targetId;
+    }
+    closeTab(targetId) {
+        return this.conn.send('Target.closeTarget', { targetId });
+    }
+    activateTab(targetId) {
+        return this.conn.send('Target.activateTarget', { targetId });
+    }
+    async attach(targetId) {
+        const { sessionId } = await this.conn.send('Target.attachToTarget', { targetId, flatten: true });
+        return this.conn.session(sessionId);
+    }
+    async close() {
+        try {
+            this.conn.close();
+        }
+        catch { }
+        await this._onClose?.();
+    }
+}
+function findChromium() {
+    if (process.env.BBM_CHROME)
+        return process.env.BBM_CHROME;
+    // Playwright's Chromium: macOS and Linux caches, old and new folder names.
+    for (const pw of [join(homedir(), 'Library/Caches/ms-playwright'), join(homedir(), '.cache/ms-playwright')]) {
+        if (!existsSync(pw))
+            continue;
+        const dirs = readdirSync(pw)
+            .filter((d) => /^chromium-\d+$/.test(d))
+            .sort()
+            .reverse();
+        for (const d of dirs) {
+            for (const rel of [
+                'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
+                'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',
+                'chrome-linux64/chrome',
+                'chrome-linux/chrome',
+            ]) {
+                if (existsSync(join(pw, d, rel)))
+                    return join(pw, d, rel);
+            }
+        }
+    }
+    const mac = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+    if (existsSync(mac))
+        return mac;
+    throw new Error('No Chromium found; set BBM_CHROME');
+}
+/** Launch a fresh Chromium with a temp profile. */
+const QUIET_PREFS = {
+    autofill: { profile_enabled: false, credit_card_enabled: false },
+    credentials_enable_service: false,
+    profile: { password_manager_enabled: false },
+};
+export async function launchChromium({ headless = true, executable = findChromium(), args = [], userDataDir, } = {}) {
+    const dir = userDataDir || (await mkdtemp(join(tmpdir(), 'bbm-profile-')));
+    // A fresh profile: no "Save address / card / password?" bubbles when an agent fills forms (they pop over the
+    // user's screen and wait for a click). A given userDataDir is the user's: we leave its settings alone.
+    if (!userDataDir) {
+        await mkdir(join(dir, 'Default'), { recursive: true });
+        await writeFile(join(dir, 'Default', 'Preferences'), JSON.stringify(QUIET_PREFS));
+    }
+    const proc = spawn(executable, [
+        '--remote-debugging-port=0',
+        `--user-data-dir=${dir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-search-engine-choice-screen',
+        '--disable-features=Translate,MediaRouter,CalculateNativeWinOcclusion',
+        '--password-store=basic',
+        '--use-mock-keychain',
+        // keep background/occluded tabs rendering, else input acks wait seconds for a frame
+        '--disable-backgrounding-occluded-windows',
+        '--disable-renderer-backgrounding',
+        '--disable-background-timer-throttling',
+        ...(headless ? ['--headless=new'] : []),
+        // extra flags, e.g. BBM_CHROME_ARGS=--no-sandbox in CI containers where the sandbox cannot start
+        ...(process.env.BBM_CHROME_ARGS?.split(/\s+/).filter(Boolean) ?? []),
+        ...args,
+        'about:blank',
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    proc.stderr.on('data', (d) => {
+        stderr += d;
+        if (stderr.length > 20000)
+            stderr = stderr.slice(-10000);
+    });
+    const portFile = join(dir, 'DevToolsActivePort');
+    const t0 = Date.now();
+    let wsUrl;
+    while (!wsUrl) {
+        if (proc.exitCode !== null)
+            throw new Error(`Chromium exited: ${stderr.slice(-2000)}`);
+        if (Date.now() - t0 > 20000) {
+            proc.kill();
+            throw new Error(`Chromium launch timeout: ${stderr.slice(-1500)}`);
+        }
+        try {
+            const [port, path] = (await readFile(portFile, 'utf8')).trim().split('\n');
+            if (port && path)
+                wsUrl = `ws://127.0.0.1:${port}${path}`;
+        }
+        catch { }
+        if (!wsUrl)
+            await new Promise((r) => setTimeout(r, 50));
+    }
+    const conn = new CDPConnection(await webSocketTransport(wsUrl));
+    const browser = new CDPBrowser(conn, {
+        onClose: async () => {
+            proc.kill();
+            await new Promise((r) => (proc.exitCode !== null ? r() : proc.once('exit', () => r())));
+            if (!userDataDir)
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
+        },
+    });
+    await browser.init();
+    browser.process = proc;
+    return browser;
+}
+/** Connect to a running browser: http://host:port or ws://... */
+export async function connectCDP(endpoint) {
+    let wsUrl = endpoint;
+    if (endpoint.startsWith('http')) {
+        const res = await fetch(new URL('/json/version', endpoint));
+        wsUrl = (await res.json()).webSocketDebuggerUrl;
+    }
+    const browser = new CDPBrowser(new CDPConnection(await webSocketTransport(wsUrl)));
+    await browser.init();
+    return browser;
+}

package/dist/npm/cdp/connection.js

@@ -0,0 +1,123 @@
+// Minimal CDP connection over a message transport, with flat sessions.
+// Transport: { send(string), onMessage(cb), onClose(cb), close() }
+class CDPError extends Error {
+    code;
+}
+export class CDPConnection {
+    #nextId = 1;
+    #pending = new Map();
+    #listeners = new Map(); // `${sessionId}|${method}` -> Set<fn>
+    #closed = false;
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+        transport.onMessage((raw) => this.#onMessage(raw));
+        transport.onClose(() => {
+            this.#closed = true;
+            for (const { reject } of this.#pending.values())
+                reject(new Error('CDP connection closed'));
+            this.#pending.clear();
+            this.#emit('', 'close', {});
+        });
+    }
+    get closed() {
+        return this.#closed;
+    }
+    send(method, params = {}, sessionId) {
+        if (this.#closed)
+            return Promise.reject(new Error('CDP connection closed'));
+        const id = this.#nextId++;
+        const msg = { id, method, params };
+        if (sessionId)
+            msg.sessionId = sessionId;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject, method });
+            this.transport.send(JSON.stringify(msg));
+        });
+    }
+    on(method, fn, sessionId = '') {
+        const key = `${sessionId}|${method}`;
+        if (!this.#listeners.has(key))
+            this.#listeners.set(key, new Set());
+        this.#listeners.get(key).add(fn);
+        return () => this.#listeners.get(key)?.delete(fn);
+    }
+    session(sessionId) {
+        return new CDPSession(this, sessionId);
+    }
+    close() {
+        this.transport.close();
+    }
+    #emit(sessionId, method, params) {
+        for (const key of [`${sessionId}|${method}`, `*|${method}`]) {
+            const set = this.#listeners.get(key);
+            if (!set)
+                continue;
+            // Copy: a listener may remove itself (or add others) while we iterate.
+            // oxlint-disable-next-line unicorn/no-useless-spread
+            for (const fn of [...set]) {
+                // An async listener's rejection is logged like a thrown error, never left unhandled (that would end the process).
+                try {
+                    Promise.resolve(fn(params, sessionId)).catch((e) => console.error('[cdp listener]', method, e));
+                }
+                catch (e) {
+                    console.error('[cdp listener]', method, e);
+                }
+            }
+        }
+    }
+    #onMessage(raw) {
+        const msg = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (msg.id !== undefined) {
+            const p = this.#pending.get(msg.id);
+            if (!p)
+                return;
+            this.#pending.delete(msg.id);
+            if (msg.error) {
+                const err = new CDPError(`${p.method}: ${msg.error.message}`);
+                err.code = msg.error.code;
+                p.reject(err);
+            }
+            else
+                p.resolve(msg.result ?? {});
+        }
+        else if (msg.method) {
+            this.#emit(msg.sessionId || '', msg.method, msg.params ?? {});
+        }
+    }
+}
+export class CDPSession {
+    conn;
+    id;
+    constructor(conn, id) {
+        this.conn = conn;
+        this.id = id;
+    }
+    send(method, params) {
+        return this.conn.send(method, params, this.id);
+    }
+    on(method, fn) {
+        return this.conn.on(method, fn, this.id);
+    }
+}
+export function webSocketTransport(url) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        const msgCbs = [], closeCbs = [];
+        ws.addEventListener('open', () => resolve({
+            send: (s) => ws.send(s),
+            onMessage: (cb) => msgCbs.push(cb),
+            onClose: (cb) => closeCbs.push(cb),
+            close: () => ws.close(),
+        }));
+        ws.addEventListener('error', (e) => reject(new Error(`WebSocket error: ${e.message || url}`)));
+        ws.addEventListener('message', (e) => {
+            for (const cb of msgCbs)
+                cb(e.data);
+        });
+        ws.addEventListener('close', () => {
+            for (const cb of closeCbs)
+                cb();
+        });
+    });
+}

package/dist/npm/cdp/keys.js

@@ -0,0 +1,90 @@
+const K = {
+    Enter: [13, 'Enter', '\r'],
+    Tab: [9, 'Tab'],
+    Escape: [27, 'Escape'],
+    Backspace: [8, 'Backspace'],
+    Delete: [46, 'Delete'],
+    ArrowUp: [38, 'ArrowUp'],
+    ArrowDown: [40, 'ArrowDown'],
+    ArrowLeft: [37, 'ArrowLeft'],
+    ArrowRight: [39, 'ArrowRight'],
+    Home: [36, 'Home'],
+    End: [35, 'End'],
+    PageUp: [33, 'PageUp'],
+    PageDown: [34, 'PageDown'],
+    Space: [32, 'Space', ' '],
+    Insert: [45, 'Insert'],
+    F1: [112, 'F1'],
+    F2: [113, 'F2'],
+    F3: [114, 'F3'],
+    F4: [115, 'F4'],
+    F5: [116, 'F5'],
+    F12: [123, 'F12'],
+};
+const ALIAS = {
+    Esc: 'Escape',
+    Return: 'Enter',
+    Up: 'ArrowUp',
+    Down: 'ArrowDown',
+    Left: 'ArrowLeft',
+    Right: 'ArrowRight',
+    Del: 'Delete',
+    ' ': 'Space',
+};
+const MODS = { Alt: 1, Control: 2, Ctrl: 2, Meta: 4, Cmd: 4, Command: 4, Shift: 8 };
+const MOD_KEYS = { 1: ['Alt', 18], 2: ['Control', 17], 4: ['Meta', 91], 8: ['Shift', 16] };
+/** Parse "Control+Shift+a" -> {modifiers, key, code, keyCode, text} */
+export function parseKey(combo) {
+    const parts = combo === '+' ? ['+'] : combo.split('+').filter(Boolean);
+    let modifiers = 0;
+    const keyName = parts.pop() ?? '';
+    for (const p of parts) {
+        const m = MODS[p] ?? MODS[p[0].toUpperCase() + p.slice(1).toLowerCase()];
+        if (!m)
+            throw new Error(`unknown modifier ${p}`);
+        modifiers |= m;
+    }
+    const name = ALIAS[keyName] || keyName;
+    if (K[name]) {
+        const [keyCode, code, text] = K[name];
+        return { modifiers, key: name === 'Space' ? ' ' : name, code, keyCode, text: modifiers & ~8 ? undefined : text };
+    }
+    if (name.length === 1) {
+        const upper = name.toUpperCase();
+        const isLetter = /[A-Z]/.test(upper);
+        const isDigit = /[0-9]/.test(name);
+        return {
+            modifiers,
+            key: name,
+            keyCode: upper.charCodeAt(0),
+            code: isLetter ? `Key${upper}` : isDigit ? `Digit${name}` : undefined,
+            text: modifiers & ~8 ? undefined : name,
+        };
+    }
+    throw new Error(`unknown key ${keyName}`);
+}
+export async function pressKey(session, combo) {
+    const k = parseKey(combo);
+    const mods = [1, 2, 4, 8].filter((m) => k.modifiers & m);
+    let active = 0;
+    for (const m of mods) {
+        active |= m;
+        const [key, kc] = MOD_KEYS[m];
+        await session.send('Input.dispatchKeyEvent', { type: 'rawKeyDown', modifiers: active, key, code: key + 'Left', windowsVirtualKeyCode: kc });
+    }
+    const base = { modifiers: k.modifiers, key: k.key, code: k.code, windowsVirtualKeyCode: k.keyCode };
+    // macOS: editing shortcuts need explicit commands
+    const commands = [];
+    if (process.platform === 'darwin' && k.modifiers & 4 && !(k.modifiers & 3)) {
+        const map = { a: 'selectAll', c: 'copy', v: 'paste', x: 'cut', z: 'undo' };
+        if (map[k.key.toLowerCase()])
+            commands.push(map[k.key.toLowerCase()]);
+    }
+    await session.send('Input.dispatchKeyEvent', { type: k.text ? 'keyDown' : 'rawKeyDown', ...base, text: k.text, unmodifiedText: k.text, commands });
+    await session.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+    for (const m of mods.reverse()) {
+        active &= ~m;
+        const [key, kc] = MOD_KEYS[m];
+        await session.send('Input.dispatchKeyEvent', { type: 'keyUp', modifiers: active, key, code: key + 'Left', windowsVirtualKeyCode: kc });
+    }
+}