@mehmoodqureshi/chrome-mcp 0.1.0

package/dist/src/executor/cdp-executor.js

@@ -0,0 +1,422 @@
+"use strict";
+/**
+ * src/executor/cdp-executor.ts — the Playwright-driven fallback Executor.
+ *
+ * Used when no extension is paired. Two acquisition modes:
+ *   - 'connect': attach over CDP to a Chrome we did NOT launch (never closed by
+ *     us — its lifecycle is the user's).
+ *   - 'launch':  spawn a dedicated persistent Chromium under a profile that is
+ *     NOT the user's real one (would conflict with the extension-driven Chrome).
+ *
+ * Ported from linkedin-mcp/src/driver/browser.ts: the stale-profile-lock
+ * recovery (a SIGKILLed MCP child orphans `SingletonLock`), connect-once reuse,
+ * stealth init on the launch path only, and tab resolution. `tabId`s are stamped
+ * `cdp:<sessionId>:<n>` so a handle never mis-routes across a backend switch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CdpExecutor = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const playwright_1 = require("playwright");
+const download_1 = require("../../shared/download");
+const types_1 = require("./types");
+const SINGLETON_FILES = ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
+const STEALTH = `Object.defineProperty(navigator,'webdriver',{get:()=>undefined});`;
+const NON_CONTENT = /^(file|data|devtools|chrome|about):/i;
+// --- lock recovery helpers (ported) ---------------------------------------
+function inspectProfileLock(profileDir) {
+    try {
+        const lockPath = (0, node_path_1.join)(profileDir, 'SingletonLock');
+        if (!(0, node_fs_1.existsSync)(lockPath))
+            return { alive: false, pid: null };
+        const target = (0, node_fs_1.readlinkSync)(lockPath);
+        const pid = Number.parseInt(target.slice(target.lastIndexOf('-') + 1), 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return { alive: false, pid: null };
+        try {
+            process.kill(pid, 0);
+            return { alive: true, pid };
+        }
+        catch (e) {
+            return { alive: e.code === 'EPERM', pid };
+        }
+    }
+    catch {
+        return { alive: false, pid: null };
+    }
+}
+function clearProfileLocks(profileDir) {
+    for (const name of SINGLETON_FILES) {
+        try {
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(profileDir, name), { force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+function isChromiumProcess(pid) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)('ps', ['-p', String(pid), '-o', 'command='], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return /chrom(e|ium)|Chrome for Testing/i.test(out);
+    }
+    catch {
+        return false;
+    }
+}
+class CdpExecutor {
+    opts;
+    backend = 'cdp';
+    sessionId = (0, node_crypto_1.randomUUID)();
+    profileDir;
+    cdpBrowser = null;
+    context = null;
+    launching = null;
+    /** Whether WE own (launched) the browser — only then may we close it. */
+    launched = false;
+    tabs = new Map();
+    seq = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.profileDir = (0, node_path_1.join)(opts.userDataDir, 'cdp-profile');
+    }
+    status() {
+        return {
+            ready: this.context !== null,
+            backend: this.backend,
+            activeTabId: null,
+            extensionConnected: false,
+            cdpAttached: this.context !== null,
+        };
+    }
+    async ensureReady() {
+        await this.getContext();
+    }
+    async ping() {
+        return this.context !== null;
+    }
+    async dispose() {
+        const ctx = this.context;
+        this.context = null;
+        this.tabs.clear();
+        if (this.opts.mode === 'connect' || !this.launched)
+            return; // never close the user's Chrome
+        try {
+            await ctx?.close();
+        }
+        catch {
+            /* ignore */
+        }
+        this.launched = false;
+    }
+    // -- acquisition --------------------------------------------------------
+    async getContext() {
+        if (this.context)
+            return this.context;
+        if (this.launching)
+            return this.launching;
+        this.launching = this.opts.mode === 'connect' ? this.doConnect() : this.doLaunch();
+        try {
+            return await this.launching;
+        }
+        finally {
+            this.launching = null;
+        }
+    }
+    async doConnect() {
+        if (!this.opts.cdpEndpoint)
+            throw new types_1.ExecutorError('LAUNCH_FAILED', 'connect mode requires a cdpEndpoint');
+        if (!this.cdpBrowser || !this.cdpBrowser.isConnected()) {
+            this.cdpBrowser = await playwright_1.chromium.connectOverCDP(this.opts.cdpEndpoint);
+            this.cdpBrowser.on('disconnected', () => {
+                this.cdpBrowser = null;
+                this.context = null;
+                this.tabs.clear();
+            });
+        }
+        const ctx = this.cdpBrowser.contexts()[0];
+        if (!ctx)
+            throw new types_1.ExecutorError('LAUNCH_FAILED', 'connected browser exposed no context');
+        this.context = ctx;
+        this.launched = false;
+        return ctx;
+    }
+    async doLaunch() {
+        (0, node_fs_1.mkdirSync)(this.profileDir, { recursive: true });
+        const args = ['--disable-blink-features=AutomationControlled'];
+        let ctx;
+        try {
+            ctx = await this.launchWithLockRecovery(args);
+        }
+        catch (err) {
+            throw new types_1.ExecutorError('LAUNCH_FAILED', `failed to launch Chromium: ${err.message}`);
+        }
+        try {
+            await ctx.addInitScript(STEALTH);
+        }
+        catch {
+            /* non-fatal */
+        }
+        this.context = ctx;
+        this.launched = true;
+        ctx.on('close', () => {
+            if (this.context === ctx) {
+                this.context = null;
+                this.tabs.clear();
+            }
+        });
+        return ctx;
+    }
+    async launchWithLockRecovery(args) {
+        const launchOpts = {
+            headless: this.opts.headless ?? true,
+            args,
+            acceptDownloads: true,
+        };
+        try {
+            return await playwright_1.chromium.launchPersistentContext(this.profileDir, launchOpts);
+        }
+        catch (err) {
+            const msg = err.message ?? '';
+            if (!/already in use|existing browser session|ProcessSingleton|SingletonLock|profile.*in use/i.test(msg)) {
+                throw err;
+            }
+            const owner = inspectProfileLock(this.profileDir);
+            if (owner.alive && owner.pid !== null) {
+                if (isChromiumProcess(owner.pid)) {
+                    try {
+                        process.kill(owner.pid, 'SIGKILL');
+                    }
+                    catch {
+                        /* gone */
+                    }
+                    await new Promise((r) => setTimeout(r, 500));
+                }
+                else {
+                    throw new types_1.ExecutorError('LAUNCH_FAILED', `profile lock held by pid ${owner.pid}, which is not our Chromium`);
+                }
+            }
+            clearProfileLocks(this.profileDir);
+            return await playwright_1.chromium.launchPersistentContext(this.profileDir, launchOpts);
+        }
+    }
+    // -- tab resolution -----------------------------------------------------
+    idFor(page) {
+        for (const [id, p] of this.tabs)
+            if (p === page)
+                return id;
+        const id = `cdp:${this.sessionId}:${++this.seq}`;
+        this.tabs.set(id, page);
+        return id;
+    }
+    contentPages(ctx) {
+        return ctx.pages().filter((p) => {
+            const u = p.url();
+            return !!u && !NON_CONTENT.test(u) && u !== 'about:blank';
+        });
+    }
+    async resolveTab(tabId) {
+        const ctx = await this.getContext();
+        if (tabId) {
+            const p = this.tabs.get(tabId);
+            if (!p || p.isClosed()) {
+                if (tabId.startsWith('cdp:') && !tabId.startsWith(`cdp:${this.sessionId}:`)) {
+                    throw new types_1.ExecutorError('STALE_TAB', 'tab handle is from a previous session; call tabs_list again');
+                }
+                throw new types_1.ExecutorError('TAB_NOT_FOUND', `no such tab: ${tabId}`);
+            }
+            return p;
+        }
+        const content = this.contentPages(ctx);
+        const page = content[0] ?? ctx.pages()[0] ?? (await ctx.newPage());
+        return page;
+    }
+    locator(page, t) {
+        if ('selector' in t && t.selector !== undefined)
+            return page.locator(t.selector).first();
+        throw new types_1.ExecutorError('SELECTOR_NOT_FOUND', 'the CDP fallback supports selectors, not refs (use the extension backend)');
+    }
+    // -- tabs ---------------------------------------------------------------
+    async tabsList() {
+        const ctx = await this.getContext();
+        const pages = this.contentPages(ctx);
+        const out = [];
+        for (let i = 0; i < pages.length; i++) {
+            const p = pages[i];
+            out.push({ tabId: this.idFor(p), url: p.url(), title: await p.title().catch(() => ''), active: i === 0, index: i });
+        }
+        return out;
+    }
+    async tabSelect(tabId) {
+        const p = await this.resolveTab(tabId);
+        await p.bringToFront().catch(() => undefined);
+        return { tabId, url: p.url(), title: await p.title().catch(() => ''), active: true, index: 0 };
+    }
+    async tabNew(url) {
+        const ctx = await this.getContext();
+        const p = await ctx.newPage();
+        if (url)
+            await p.goto(url, { waitUntil: 'load' }).catch(() => undefined);
+        return { tabId: this.idFor(p), url: p.url(), title: await p.title().catch(() => ''), active: true, index: 0 };
+    }
+    async tabClose(tabId) {
+        const p = await this.resolveTab(tabId);
+        await p.close();
+        this.tabs.delete(tabId);
+        return { closed: true, tabId };
+    }
+    // -- navigation ---------------------------------------------------------
+    toState(w) {
+        return w ?? 'load';
+    }
+    async navigate(args) {
+        const p = await this.resolveTab(args.tabId);
+        const resp = await p.goto(args.url, { waitUntil: this.toState(args.waitUntil) });
+        return { url: p.url(), title: await p.title().catch(() => ''), httpStatus: resp?.status() };
+    }
+    async back(tabId) {
+        const p = await this.resolveTab(tabId);
+        await p.goBack().catch(() => undefined);
+        return { url: p.url(), title: await p.title().catch(() => '') };
+    }
+    async forward(tabId) {
+        const p = await this.resolveTab(tabId);
+        await p.goForward().catch(() => undefined);
+        return { url: p.url(), title: await p.title().catch(() => '') };
+    }
+    async reload(args) {
+        const p = await this.resolveTab(args?.tabId);
+        await p.reload({ waitUntil: this.toState(args?.waitUntil) });
+        return { url: p.url(), title: await p.title().catch(() => '') };
+    }
+    // -- interaction --------------------------------------------------------
+    ok = { ok: true };
+    async click(t, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        await this.locator(p, t).click({ button: opts?.button, clickCount: opts?.clickCount });
+        return this.ok;
+    }
+    async type(t, text, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        const loc = this.locator(p, t);
+        if (opts?.clear)
+            await loc.fill('');
+        if (opts?.keyEvents)
+            await loc.pressSequentially(text);
+        else
+            await loc.fill((opts?.clear ? '' : '') + text);
+        if (opts?.pressEnter)
+            await loc.press('Enter');
+        return this.ok;
+    }
+    async fill(t, value, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        await this.locator(p, t).fill(value);
+        return this.ok;
+    }
+    async press(key, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        const combo = [...(opts?.modifiers ?? []), key].join('+');
+        await p.keyboard.press(combo);
+        return this.ok;
+    }
+    async hover(t, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        await this.locator(p, t).hover();
+        return this.ok;
+    }
+    async scroll(opts) {
+        const p = await this.resolveTab(opts.tabId);
+        if (opts.target)
+            await this.locator(p, opts.target).scrollIntoViewIfNeeded();
+        else if (opts.x !== undefined || opts.y !== undefined)
+            await p.evaluate(([x, y]) => window.scrollTo(x ?? 0, y ?? 0), [opts.x, opts.y]);
+        else
+            await p.mouse.wheel(opts.deltaX ?? 0, opts.deltaY ?? 0);
+        return this.ok;
+    }
+    // -- read ---------------------------------------------------------------
+    async getText(t, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        const text = t ? await this.locator(p, t).innerText() : await p.locator('body').innerText();
+        return { text };
+    }
+    async getHtml(t, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        if (!t)
+            return { html: await p.content() };
+        const loc = this.locator(p, t);
+        const html = opts?.outer ? await loc.evaluate((el) => el.outerHTML) : await loc.innerHTML();
+        return { html };
+    }
+    async screenshot(opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        const buf = opts?.target
+            ? await this.locator(p, opts.target).screenshot()
+            : await p.screenshot({ fullPage: opts?.fullPage });
+        const size = p.viewportSize() ?? { width: 0, height: 0 };
+        return { dataBase64: buf.toString('base64'), mimeType: 'image/png', width: size.width, height: size.height, truncated: false };
+    }
+    async eval(expression, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        try {
+            const value = await p.evaluate((expr) => {
+                // eslint-disable-next-line no-eval
+                return (0, eval)(expr);
+            }, expression);
+            return { ok: true, value, type: typeof value };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    }
+    async waitFor(opts) {
+        const p = await this.resolveTab(opts.tabId);
+        const timeout = opts.timeoutMs ?? 30_000;
+        const start = Date.now();
+        try {
+            if (opts.selector) {
+                await p.locator(opts.selector).first().waitFor({ state: opts.gone ? 'detached' : 'visible', timeout });
+            }
+            else if (opts.textContains) {
+                await p.waitForFunction((needle) => document.body?.innerText.includes(needle) ?? false, opts.textContains, { timeout });
+            }
+            return { matched: true, waitedMs: Date.now() - start };
+        }
+        catch {
+            return { matched: false, waitedMs: Date.now() - start };
+        }
+    }
+    // -- privileged ---------------------------------------------------------
+    async download(args) {
+        const ctx = await this.getContext();
+        const dir = this.opts.downloadDir ?? (0, node_path_1.join)(this.opts.userDataDir, 'downloads');
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const safeName = (0, download_1.sanitizeDownloadName)(args.suggestedName);
+        const dest = (0, node_path_1.join)(dir, safeName);
+        if (args.url) {
+            const resp = await ctx.request.get(args.url);
+            const body = await resp.body();
+            if (!(0, download_1.isWithinSizeCap)(body.length)) {
+                throw new types_1.ExecutorError('DOWNLOAD_FAILED', `download exceeds the ${download_1.MAX_DOWNLOAD_BYTES}-byte cap`);
+            }
+            (0, node_fs_1.writeFileSync)(dest, body);
+            return { path: dest, backend: this.backend, bytes: body.length, mimeType: resp.headers()['content-type'] };
+        }
+        // Element-triggered download.
+        const p = await this.resolveTab(args.tabId);
+        const target = args.target;
+        if (!target)
+            throw new types_1.ExecutorError('DOWNLOAD_FAILED', 'provide a url or a target');
+        const [dl] = await Promise.all([p.waitForEvent('download'), this.locator(p, target).click()]);
+        await dl.saveAs(dest);
+        return { path: dest, backend: this.backend, bytes: 0, suggestedName: dl.suggestedFilename() };
+    }
+}
+exports.CdpExecutor = CdpExecutor;
+//# sourceMappingURL=cdp-executor.js.map

package/dist/src/executor/extension-executor.d.ts

@@ -0,0 +1,102 @@
+/**
+ * src/executor/extension-executor.ts — the Executor backed by the MV3 extension.
+ *
+ * Every method is a thin translation into a single `bridge.sendCommand(method,
+ * params, {tabId, timeoutMs})` round-trip; the extension does the real work over
+ * `chrome.debugger`. The "operate-on" tab travels in the frame's `tabId`;
+ * method-specific arguments travel in `params`. Results are trusted shapes
+ * produced by the extension router (validated there).
+ */
+import { type ActionOk, type BackendKind, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type MouseButton, type NavResult, type ScreenshotResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
+import type { BridgeServer } from '../bridge/server';
+export declare class ExtensionExecutor implements Executor {
+    private readonly bridge;
+    readonly backend: BackendKind;
+    constructor(bridge: BridgeServer);
+    private send;
+    status(): ExecutorStatus;
+    ensureReady(): Promise<void>;
+    ping(deadlineMs?: number): Promise<boolean>;
+    dispose(): Promise<void>;
+    tabsList(): Promise<TabInfo[]>;
+    tabSelect(tabId: TabId): Promise<TabInfo>;
+    tabNew(url?: string): Promise<TabInfo>;
+    tabClose(tabId: TabId): Promise<{
+        closed: true;
+        tabId: TabId;
+    }>;
+    navigate(args: {
+        url: string;
+        tabId?: TabId;
+        waitUntil?: WaitUntil;
+    }): Promise<NavResult>;
+    back(tabId?: TabId): Promise<NavResult>;
+    forward(tabId?: TabId): Promise<NavResult>;
+    reload(args?: {
+        tabId?: TabId;
+        waitUntil?: WaitUntil;
+    }): Promise<NavResult>;
+    click(t: Target, opts?: {
+        tabId?: TabId;
+        button?: MouseButton;
+        clickCount?: number;
+    }): Promise<ActionOk>;
+    type(t: Target, text: string, opts?: {
+        tabId?: TabId;
+        clear?: boolean;
+        pressEnter?: boolean;
+        keyEvents?: boolean;
+    }): Promise<ActionOk>;
+    fill(t: Target, value: string, opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
+    press(key: string, opts?: {
+        tabId?: TabId;
+        modifiers?: KeyModifier[];
+    }): Promise<ActionOk>;
+    hover(t: Target, opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
+    scroll(opts: {
+        tabId?: TabId;
+        x?: number;
+        y?: number;
+        deltaX?: number;
+        deltaY?: number;
+        target?: Target;
+    }): Promise<ActionOk>;
+    getText(t?: Target, opts?: {
+        tabId?: TabId;
+    }): Promise<{
+        text: string;
+        ref?: string;
+    }>;
+    getHtml(t?: Target, opts?: {
+        tabId?: TabId;
+        outer?: boolean;
+    }): Promise<{
+        html: string;
+    }>;
+    screenshot(opts?: {
+        tabId?: TabId;
+        fullPage?: boolean;
+        target?: Target;
+    }): Promise<ScreenshotResult>;
+    eval(expression: string, opts?: {
+        tabId?: TabId;
+        awaitPromise?: boolean;
+    }): Promise<EvalResult>;
+    waitFor(opts: {
+        tabId?: TabId;
+        selector?: string;
+        textContains?: string;
+        gone?: boolean;
+        timeoutMs?: number;
+    }): Promise<WaitResult>;
+    download(args: {
+        url?: string;
+        target?: Target;
+        tabId?: TabId;
+        suggestedName?: string;
+    }): Promise<DownloadResult>;
+}

package/dist/src/executor/extension-executor.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * src/executor/extension-executor.ts — the Executor backed by the MV3 extension.
+ *
+ * Every method is a thin translation into a single `bridge.sendCommand(method,
+ * params, {tabId, timeoutMs})` round-trip; the extension does the real work over
+ * `chrome.debugger`. The "operate-on" tab travels in the frame's `tabId`;
+ * method-specific arguments travel in `params`. Results are trusted shapes
+ * produced by the extension router (validated there).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtensionExecutor = void 0;
+/** Flatten a Target into the params a wire command carries. */
+function targetParams(t) {
+    if (!t)
+        return {};
+    return 'selector' in t && t.selector !== undefined ? { selector: t.selector } : { ref: t.ref };
+}
+class ExtensionExecutor {
+    bridge;
+    backend = 'extension';
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    send(method, params, opts) {
+        return this.bridge.sendCommand(method, params, opts);
+    }
+    status() {
+        const connected = this.bridge.hasActiveExtension();
+        return {
+            ready: connected,
+            backend: this.backend,
+            activeTabId: null, // not known synchronously
+            extensionConnected: connected,
+            cdpAttached: false,
+        };
+    }
+    async ensureReady() {
+        // The bridge owns connectivity; nothing to launch here. The selector has
+        // already confirmed an extension is paired + responsive before picking us.
+    }
+    async ping(deadlineMs = 800) {
+        if (!this.bridge.hasActiveExtension())
+            return false;
+        try {
+            await this.send('ping_probe', {}, { timeoutMs: deadlineMs });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dispose() {
+        // Never close the user's Chrome.
+    }
+    // -- tabs ---------------------------------------------------------------
+    async tabsList() {
+        return (await this.send('tabs_list', {}));
+    }
+    async tabSelect(tabId) {
+        return (await this.send('tab_select', {}, { tabId }));
+    }
+    async tabNew(url) {
+        return (await this.send('tab_new', { url }));
+    }
+    async tabClose(tabId) {
+        return (await this.send('tab_close', {}, { tabId }));
+    }
+    // -- navigation ---------------------------------------------------------
+    async navigate(args) {
+        return (await this.send('navigate', { url: args.url, waitUntil: args.waitUntil }, { tabId: args.tabId }));
+    }
+    async back(tabId) {
+        return (await this.send('back', {}, { tabId }));
+    }
+    async forward(tabId) {
+        return (await this.send('forward', {}, { tabId }));
+    }
+    async reload(args) {
+        return (await this.send('reload', { waitUntil: args?.waitUntil }, { tabId: args?.tabId }));
+    }
+    // -- interaction --------------------------------------------------------
+    async click(t, opts) {
+        return (await this.send('click', { ...targetParams(t), button: opts?.button, clickCount: opts?.clickCount }, { tabId: opts?.tabId }));
+    }
+    async type(t, text, opts) {
+        return (await this.send('type', { ...targetParams(t), text, clear: opts?.clear, pressEnter: opts?.pressEnter, keyEvents: opts?.keyEvents }, { tabId: opts?.tabId }));
+    }
+    async fill(t, value, opts) {
+        // No dedicated wire method: a cleared insertText is the fill primitive.
+        return (await this.send('type', { ...targetParams(t), text: value, clear: true, keyEvents: false }, { tabId: opts?.tabId }));
+    }
+    async press(key, opts) {
+        return (await this.send('press', { key, modifiers: opts?.modifiers }, { tabId: opts?.tabId }));
+    }
+    async hover(t, opts) {
+        return (await this.send('hover', { ...targetParams(t) }, { tabId: opts?.tabId }));
+    }
+    async scroll(opts) {
+        return (await this.send('scroll', { x: opts.x, y: opts.y, deltaX: opts.deltaX, deltaY: opts.deltaY, ...targetParams(opts.target) }, { tabId: opts.tabId }));
+    }
+    // -- read ---------------------------------------------------------------
+    async getText(t, opts) {
+        return (await this.send('get_text', { ...targetParams(t) }, { tabId: opts?.tabId }));
+    }
+    async getHtml(t, opts) {
+        return (await this.send('get_html', { ...targetParams(t), outer: opts?.outer }, { tabId: opts?.tabId }));
+    }
+    async screenshot(opts) {
+        return (await this.send('screenshot', { fullPage: opts?.fullPage, ...targetParams(opts?.target) }, { tabId: opts?.tabId }));
+    }
+    async eval(expression, opts) {
+        return (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise }, { tabId: opts?.tabId }));
+    }
+    async waitFor(opts) {
+        return (await this.send('wait_for', { selector: opts.selector, textContains: opts.textContains, gone: opts.gone, timeoutMs: opts.timeoutMs }, { tabId: opts.tabId, timeoutMs: opts.timeoutMs ? opts.timeoutMs + 5_000 : undefined }));
+    }
+    // -- privileged ---------------------------------------------------------
+    async download(args) {
+        return (await this.send('download_file', { url: args.url, ...targetParams(args.target), suggestedName: args.suggestedName }, { tabId: args.tabId }));
+    }
+}
+exports.ExtensionExecutor = ExtensionExecutor;
+//# sourceMappingURL=extension-executor.js.map

package/dist/src/executor/manager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * src/executor/manager.ts — owns the process-global active Executor and the
+ * `withReadyExecutor()` accessor every tool routes through (the `withReadyDriver`
+ * analog from the LinkedIn repo).
+ *
+ * Phase 1 holds a single Executor produced by an injected factory (the Stub).
+ * Later phases replace the factory with real selection logic (extension-if-
+ * responsive else CDP), but the surface the tools see — `ensureReady()` +
+ * `policy` — does not change.
+ */
+import { type Executor } from './types';
+import type { Policy } from '../security/policy';
+export interface ManagerOptions {
+    policy: Policy;
+    /** Lazily construct a single backend on first use (Phase 1: the Stub). */
+    makeExecutor?: () => Executor;
+    /** Phase 3+ selection strategy, re-evaluated each `ensureReady()`. Wins over
+     *  `makeExecutor` when both are present. Returns the chosen (not-yet-ready)
+     *  Executor; the manager calls `ensureReady()` on it. */
+    select?: () => Promise<Executor>;
+}
+export declare class ExecutorManager {
+    private readonly opts;
+    private current;
+    private readying;
+    constructor(opts: ManagerOptions);
+    get policy(): Policy;
+    /** Inject a ready-made executor (tests, or a later phase's selector). */
+    setExecutor(ex: Executor): void;
+    /**
+     * Return a ready Executor, constructing it lazily and single-flight-guarding
+     * concurrent callers. Throws `NO_BACKEND` when nothing is configured.
+     */
+    ensureReady(): Promise<Executor>;
+    private doEnsure;
+    dispose(): Promise<void>;
+}
+/** Install (or replace) the global manager. Returns it. */
+export declare function configureManager(opts: ManagerOptions): ExecutorManager;
+export declare function getManager(): ExecutorManager;
+/** Tear down the singleton (tests). */
+export declare function resetManagerForTesting(): void;
+export declare function withReadyExecutor(): Promise<Executor>;