tabwright 1.0.0

package/dist/executor.js

@@ -0,0 +1,1465 @@
+/**
+ * PlaywrightExecutor - Manages browser connection and code execution per session.
+ * Used by both MCP and CLI to execute Playwright code with persistent state.
+ */
+import { getChromium } from './playwright-import.js';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import util from 'node:util';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import vm from 'node:vm';
+import * as acorn from 'acorn';
+import { createSmartDiff } from './diff-utils.js';
+import { getCdpUrl, parseRelayHost, shouldAutoEnableTabwright } from './utils.js';
+import { getExtensionOutdatedWarning } from './relay-client.js';
+import { waitForPageLoad } from './wait-for-page-load.js';
+import { getCDPSessionForPage } from './cdp-session.js';
+import { Debugger } from './debugger.js';
+import { Editor } from './editor.js';
+import { getStylesForLocator, formatStylesAsText } from './styles.js';
+import { getReactSource, getReactComponentInfo } from './react-source.js';
+import { ScopedFS } from './scoped-fs.js';
+import { screenshotWithAccessibilityLabels, getAriaSnapshot, resizeImageForAgent, } from './aria-snapshot.js';
+import { createGhostBrowserChrome } from './ghost-browser.js';
+import { getCleanHTML } from './clean-html.js';
+import { getPageMarkdown } from './page-markdown.js';
+import { createReplayApi } from './rrweb-recording.js';
+import { saveWorkflowCapability, saveWorkflowFromRecording, } from './workflow-capability.js';
+import { GhostCursorController } from './ghost-cursor-controller.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+export class CodeExecutionTimeoutError extends Error {
+    constructor(timeout) {
+        super(`Code execution timed out after ${timeout}ms`);
+        this.name = 'CodeExecutionTimeoutError';
+    }
+}
+const usefulGlobals = {
+    setTimeout,
+    setInterval,
+    clearTimeout,
+    clearInterval,
+    URL,
+    URLSearchParams,
+    fetch,
+    Buffer,
+    TextEncoder,
+    TextDecoder,
+    crypto,
+    AbortController,
+    AbortSignal,
+    structuredClone,
+    process,
+};
+/**
+ * Parse code and check if it's a single expression that should be auto-returned.
+ * Returns the exact expression source (without trailing semicolon) using AST
+ * node offsets, or null if the code should not be auto-wrapped. See #58.
+ */
+export function getAutoReturnExpression(code) {
+    try {
+        const ast = acorn.parse(code, {
+            ecmaVersion: 'latest',
+            allowAwaitOutsideFunction: true,
+            allowReturnOutsideFunction: true,
+            sourceType: 'script',
+        });
+        // Must be exactly one statement
+        if (ast.body.length !== 1) {
+            return null;
+        }
+        const stmt = ast.body[0];
+        // If it's already a return statement, don't auto-wrap
+        if (stmt.type === 'ReturnStatement') {
+            return null;
+        }
+        // Must be an ExpressionStatement
+        if (stmt.type !== 'ExpressionStatement') {
+            return null;
+        }
+        // Don't auto-return side-effect expressions
+        const expr = stmt.expression;
+        if (expr.type === 'AssignmentExpression' ||
+            expr.type === 'UpdateExpression' ||
+            (expr.type === 'UnaryExpression' && expr.operator === 'delete')) {
+            return null;
+        }
+        // Don't auto-return sequence expressions that contain assignments
+        if (expr.type === 'SequenceExpression') {
+            const hasAssignment = expr.expressions.some((e) => e.type === 'AssignmentExpression');
+            if (hasAssignment) {
+                return null;
+            }
+        }
+        // Use the expression node's start/end offsets to extract just the expression
+        // source, excluding any trailing semicolon. This is more robust than regex.
+        return code.slice(expr.start, expr.end);
+    }
+    catch {
+        // Parse failed, don't auto-return
+        return null;
+    }
+}
+/** Backward-compatible helper: returns true if code should be auto-wrapped. */
+export function shouldAutoReturn(code) {
+    return getAutoReturnExpression(code) !== null;
+}
+/**
+ * Wraps user code in an async IIFE for vm execution.
+ * Uses AST node offsets to extract the expression without trailing semicolons,
+ * avoiding SyntaxError when embedding inside `return await (...)`. See #58.
+ */
+export function wrapCode(code) {
+    const expr = getAutoReturnExpression(code);
+    if (expr !== null) {
+        return `(async () => { return await (${expr}) })()`;
+    }
+    return `(async () => { ${code} })()`;
+}
+const EXTENSION_NOT_CONNECTED_ERROR = `The Tabwright Chrome extension is not connected. Make sure you have:
+1. Installed the extension: https://chromewebstore.google.com/detail/tabwright/jfeammnjpkecdekppnclgkkffahnhfhe
+2. Clicked the extension icon on a tab to enable it (or refreshed the page if just installed)
+3. Or use a cloud browser instead: run \`tabwright cloud login\` in your terminal to rent a browser in the cloud, with auto CAPTCHA solving, residential proxies and anti-detection built in`;
+const NO_PAGES_AVAILABLE_ERROR = 'No Playwright pages are available. Enable Tabwright on a tab or unset TABWRIGHT_AUTO_ENABLE=false to auto-create one.';
+const CLOUD_SESSION_EXPIRED_ERROR = 'Cloud browser session expired or was destroyed. Create a new session with: tabwright session new --browser cloud';
+/** Patterns that indicate the browser/page/context was closed or the WebSocket died.
+ *  Used to detect cloud VM expiration vs other Playwright errors. */
+const DISCONNECTION_PATTERNS = [
+    'browser has been closed',
+    'browser.close',
+    'Target page, context or browser has been closed',
+    'Target closed',
+    'connection refused',
+    'WebSocket is not open',
+    'WebSocket error',
+    'connect ECONNREFUSED',
+    'Session closed',
+    'Connection closed',
+    'NS_ERROR_NET_RESET',
+];
+function isDisconnectionError(error) {
+    const msg = error.message || '';
+    const stack = error.stack || '';
+    const matchesHere = DISCONNECTION_PATTERNS.some((pattern) => {
+        return msg.includes(pattern) || stack.includes(pattern);
+    });
+    if (matchesHere)
+        return true;
+    // Walk the cause chain — ensureConnection wraps the real WebSocket error
+    // in a new Error with { cause }, so we need to check nested causes too.
+    if (error.cause instanceof Error) {
+        return isDisconnectionError(error.cause);
+    }
+    return false;
+}
+const MAX_LOGS_PER_PAGE = 5000;
+const ALLOWED_MODULES = new Set([
+    'path',
+    'node:path',
+    'url',
+    'node:url',
+    'querystring',
+    'node:querystring',
+    'punycode',
+    'node:punycode',
+    'crypto',
+    'node:crypto',
+    'buffer',
+    'node:buffer',
+    'string_decoder',
+    'node:string_decoder',
+    'util',
+    'node:util',
+    'assert',
+    'node:assert',
+    'events',
+    'node:events',
+    'timers',
+    'node:timers',
+    'stream',
+    'node:stream',
+    'zlib',
+    'node:zlib',
+    'http',
+    'node:http',
+    'https',
+    'node:https',
+    'http2',
+    'node:http2',
+    'os',
+    'node:os',
+    'fs',
+    'node:fs',
+]);
+function isRegExp(value) {
+    return (typeof value === 'object' && value !== null && typeof value.test === 'function' && typeof value.exec === 'function');
+}
+function isPromise(value) {
+    return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}
+/**
+ * Duck-type check for a Playwright ChannelOwner (Response, Page, Browser,
+ * Request, Frame, BrowserContext, etc.). Used to skip auto-printing these
+ * objects from the REPL — they're meant for programmatic use, and dumping
+ * them risks leaking internal fields. Users can still `console.log(obj)` to
+ * inspect them via the safe handler in playwright-core. See issue #82.
+ */
+export function isPlaywrightChannelOwner(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value._type === 'string' &&
+        typeof value._guid === 'string' &&
+        value._connection !== undefined);
+}
+export class PlaywrightExecutor {
+    isConnected = false;
+    page = null;
+    browser = null;
+    context = null;
+    userState = {};
+    browserLogs = new Map();
+    // Tracks the index up to which getLatestLogs({ sinceLastCall: true }) has
+    // returned logs. 0 means "return everything" (first call gets full buffer).
+    // When addBrowserLog shifts old entries (cap at MAX_LOGS_PER_PAGE), cursors
+    // are decremented so they stay in sync with the array.
+    pageLogCursor = new Map();
+    lastSnapshots = new WeakMap();
+    lastRefToLocator = new WeakMap();
+    warningEvents = [];
+    nextWarningEventId = 0;
+    lastDeliveredWarningEventId = 0;
+    activeWarningScopes = new Set();
+    pagesWithListeners = new WeakSet();
+    suppressPageCloseWarnings = false;
+    scopedFs;
+    sandboxedRequire;
+    cdpConfig;
+    logger;
+    sessionMetadata;
+    sessionCwd;
+    hasWarnedExtensionOutdated = false;
+    ghostCursorController;
+    /** Non-null when this executor is backed by a cloud Browser Use VM */
+    cloudSession;
+    /** Last minute bucket for which a cloud timeout warning was enqueued (dedup) */
+    lastCloudTimeoutWarningMinute = null;
+    constructor(options) {
+        this.cdpConfig = options.cdpConfig;
+        this.logger = options.logger || { log: console.log, error: console.error };
+        this.sessionMetadata = options.sessionMetadata || { extensionId: null, browser: null, profile: null };
+        this.sessionCwd = options.cwd ? path.resolve(options.cwd) : null;
+        this.cloudSession = options.cloudSession || null;
+        // ScopedFS expects an array of allowed directories. If cwd is provided, use it; otherwise use defaults.
+        this.scopedFs = new ScopedFS(this.sessionCwd ? [this.sessionCwd, '/tmp', os.tmpdir()] : undefined, this.sessionCwd || undefined);
+        this.sandboxedRequire = this.createSandboxedRequire(require);
+        this.ghostCursorController = new GhostCursorController({
+            logger: {
+                error: (...args) => {
+                    this.logger.error(...args);
+                },
+            },
+        });
+    }
+    createSandboxedRequire(originalRequire) {
+        const scopedFs = this.scopedFs;
+        const sandboxedRequire = ((id) => {
+            if (!ALLOWED_MODULES.has(id)) {
+                const error = new Error(`Module "${id}" is not allowed in the sandbox. ` +
+                    `Only safe Node.js built-ins are permitted: ${[...ALLOWED_MODULES].filter((m) => !m.startsWith('node:')).join(', ')}`);
+                error.name = 'ModuleNotAllowedError';
+                throw error;
+            }
+            if (id === 'fs' || id === 'node:fs') {
+                return scopedFs;
+            }
+            return originalRequire(id);
+        });
+        sandboxedRequire.resolve = originalRequire.resolve;
+        sandboxedRequire.cache = originalRequire.cache;
+        sandboxedRequire.extensions = originalRequire.extensions;
+        sandboxedRequire.main = originalRequire.main;
+        return sandboxedRequire;
+    }
+    async setDeviceScaleFactorForMacOS(context) {
+        if (os.platform() !== 'darwin') {
+            return;
+        }
+        const options = context._options;
+        if (!options || options.deviceScaleFactor === 2) {
+            return;
+        }
+        options.deviceScaleFactor = 2;
+    }
+    /** Block images, video, and font resources via Network.setBlockedURLs to save
+     *  residential proxy bandwidth. Single CDP command, zero per-request overhead.
+     *  Applied per-context on every page (existing and future). */
+    async applyProxyResourceBlocking(context) {
+        // URL patterns using the URLPattern spec syntax (absolute patterns).
+        // Covers the vast majority of image/video/font resources by file extension.
+        const blockedPatterns = [
+            // Images (SVGs excluded — lightweight and often used for icons/UI)
+            '*.png', '*.jpg', '*.jpeg', '*.gif', '*.webp', '*.ico', '*.bmp', '*.avif',
+        ];
+        const applyToPage = async (page) => {
+            try {
+                const cdpSession = await page.context().newCDPSession(page);
+                await cdpSession.send('Network.enable');
+                await cdpSession.send('Network.setBlockedURLs', {
+                    urls: blockedPatterns,
+                });
+                await cdpSession.detach();
+            }
+            catch (err) {
+                // Best-effort: don't break the session if blocking fails
+                this.logger.error('Failed to apply proxy resource blocking:', err);
+            }
+        };
+        // Apply to existing pages
+        const pages = context.pages().filter((p) => !p.isClosed());
+        await Promise.all(pages.map(applyToPage));
+        // Apply to future pages
+        context.on('page', (page) => {
+            applyToPage(page);
+        });
+        this.logger.log('Proxy bandwidth acceleration enabled: blocking raster images');
+    }
+    clearUserState() {
+        Object.keys(this.userState).forEach((key) => delete this.userState[key]);
+    }
+    clearConnectionState() {
+        this.isConnected = false;
+        this.browser = null;
+        this.page = null;
+        this.context = null;
+    }
+    enqueueWarning(message) {
+        this.nextWarningEventId += 1;
+        this.warningEvents.push({ id: this.nextWarningEventId, message });
+    }
+    /** Update the cloud session timeout from external tracking (relay timer). */
+    updateCloudTimeout(timeoutAt) {
+        if (this.cloudSession) {
+            this.cloudSession.timeoutAt = timeoutAt;
+        }
+    }
+    beginWarningScope() {
+        // Use lastDeliveredWarningEventId as cursor (not nextWarningEventId) so
+        // warnings enqueued by the relay interval between execute() calls are
+        // picked up by the next scope. Using nextWarningEventId would skip them.
+        const scope = {
+            cursor: this.lastDeliveredWarningEventId,
+        };
+        this.activeWarningScopes.add(scope);
+        return scope;
+    }
+    flushWarningsForScope(scope) {
+        const relevantWarnings = this.warningEvents.filter((warning) => {
+            return warning.id > scope.cursor;
+        });
+        const latestWarningId = relevantWarnings.at(-1)?.id;
+        if (latestWarningId && latestWarningId > this.lastDeliveredWarningEventId) {
+            this.lastDeliveredWarningEventId = latestWarningId;
+        }
+        this.activeWarningScopes.delete(scope);
+        this.pruneDeliveredWarnings();
+        if (relevantWarnings.length === 0) {
+            return '';
+        }
+        return `${relevantWarnings.map((warning) => `[WARNING] ${warning.message}`).join('\n')}\n`;
+    }
+    pruneDeliveredWarnings() {
+        const activeCursors = [...this.activeWarningScopes].map((scope) => {
+            return scope.cursor;
+        });
+        const minActiveCursor = activeCursors.length > 0 ? Math.min(...activeCursors) : this.lastDeliveredWarningEventId;
+        const pruneBeforeOrAt = Math.min(this.lastDeliveredWarningEventId, minActiveCursor);
+        this.warningEvents = this.warningEvents.filter((warning) => {
+            return warning.id > pruneBeforeOrAt;
+        });
+    }
+    warnIfExtensionOutdated(playwriterVersion) {
+        if (this.hasWarnedExtensionOutdated) {
+            return;
+        }
+        const warning = getExtensionOutdatedWarning(playwriterVersion);
+        if (warning) {
+            this.logger.log(warning);
+            // Enqueue so MCP agents see version-skew messages in their next execute
+            // response — logger.log alone only reaches stdout, not the LLM.
+            this.enqueueWarning(warning);
+            this.hasWarnedExtensionOutdated = true;
+        }
+    }
+    setupPageListeners(page) {
+        if (this.pagesWithListeners.has(page)) {
+            return;
+        }
+        this.pagesWithListeners.add(page);
+        this.setupPageCloseDetection(page);
+        this.setupPageConsoleListener(page);
+        this.setupNewPageLogging(page);
+        this.ghostCursorController.attachToPage({ page });
+        page.on('close', () => {
+            this.ghostCursorController.detachFromPage({ page });
+        });
+    }
+    setupPageCloseDetection(page) {
+        page.on('close', () => {
+            const stateKeysForClosedPage = Object.entries(this.userState)
+                .filter(([, value]) => {
+                return value === page;
+            })
+                .map(([key]) => key);
+            const wasCurrentPage = this.page === page;
+            let replacementPageInfo = null;
+            if (wasCurrentPage) {
+                this.page = null;
+                const context = this.context || page.context();
+                const openPages = context.pages().filter((candidate) => {
+                    return !candidate.isClosed();
+                });
+                if (openPages.length > 0) {
+                    const replacementPage = openPages[0];
+                    this.page = replacementPage;
+                    const replacementIndex = context.pages().indexOf(replacementPage);
+                    replacementPageInfo = {
+                        index: replacementIndex >= 0 ? String(replacementIndex) : 'unknown',
+                        url: replacementPage.url() || 'unknown',
+                    };
+                }
+            }
+            if (!this.isConnected || this.suppressPageCloseWarnings || stateKeysForClosedPage.length === 0) {
+                return;
+            }
+            const stateKeyLabel = stateKeysForClosedPage.map((key) => `state.${key}`).join(', ');
+            const closedUrl = page.url() || 'unknown';
+            if (!wasCurrentPage) {
+                this.enqueueWarning(`Page closed (url: ${closedUrl}) for ${stateKeyLabel}. ` +
+                    `Assign a new open page to ${stateKeyLabel} before reusing it.`);
+                return;
+            }
+            if (replacementPageInfo) {
+                this.enqueueWarning(`The current page in ${stateKeyLabel} was closed (url: ${closedUrl}). ` +
+                    `Switched active page to index ${replacementPageInfo.index} (url: ${replacementPageInfo.url}). ` +
+                    `Reassign ${stateKeyLabel} before using it again.`);
+                return;
+            }
+            this.enqueueWarning(`The current page in ${stateKeyLabel} was closed (url: ${closedUrl}). ` +
+                `No open pages remain. Open a tab with Tabwright enabled, then reassign ${stateKeyLabel}.`);
+        });
+    }
+    setupNewPageLogging(page) {
+        // page.on('popup') fires for window.open, target=_blank, and cmd+click
+        // (but not context.newPage() or CDP reconnection). The extension
+        // auto-relocates popups to tabs, so these pages are controllable via
+        // context.pages(). Enqueue synchronously so the warning lands in the
+        // enclosing execute() call's scope. initialUrl may be 'about:blank'
+        // for blank-then-scripted popups.
+        page.on('popup', (popup) => {
+            const pages = popup.context().pages();
+            const rawIndex = pages.indexOf(popup);
+            const pageIndex = rawIndex >= 0 ? String(rawIndex) : 'unknown';
+            const initialUrl = popup.url() || 'about:blank';
+            this.enqueueWarning(`New page opened from current page (index ${pageIndex}, initial url: ${initialUrl}). ` +
+                `Access it via context.pages()[${pageIndex}] to interact with it.`);
+        });
+    }
+    setupPageConsoleListener(page) {
+        if (!this.browserLogs.has(page)) {
+            this.browserLogs.set(page, []);
+        }
+        // Logs are NOT cleared on navigation so that getLatestLogs({ sinceLastCall: true })
+        // can return errors from the previous page load. The MAX_LOGS_PER_PAGE cap (5000)
+        // prevents unbounded growth; old entries are shifted out in addBrowserLog.
+        page.on('close', () => {
+            this.browserLogs.delete(page);
+            this.pageLogCursor.delete(page);
+        });
+        page.on('console', (msg) => {
+            try {
+                const logEntry = `[${msg.type()}] ${msg.text()}`;
+                this.addBrowserLog({ page, logEntry });
+            }
+            catch (e) {
+                this.logger.error('[Executor] Failed to get console message text:', e);
+            }
+        });
+        page.on('pageerror', (error) => {
+            this.addBrowserLog({ page, logEntry: `[pageerror] ${error.message}` });
+        });
+    }
+    addBrowserLog(options) {
+        if (!this.browserLogs.has(options.page)) {
+            this.browserLogs.set(options.page, []);
+        }
+        const pageLogs = this.browserLogs.get(options.page);
+        pageLogs.push(options.logEntry);
+        if (pageLogs.length > MAX_LOGS_PER_PAGE) {
+            pageLogs.shift();
+            // Decrement cursor so it stays in sync with the shifted array.
+            // Clamp to 0 so the cursor never goes negative.
+            const cursor = this.pageLogCursor.get(options.page);
+            if (cursor !== undefined && cursor > 0) {
+                this.pageLogCursor.set(options.page, cursor - 1);
+            }
+        }
+    }
+    pagesRelatedToPage(page) {
+        const frameUrls = new Set(page
+            .frames()
+            .map((frame) => {
+            return frame.url();
+        })
+            .filter((url) => {
+            return url && url !== 'about:blank';
+        }));
+        return page
+            .context()
+            .pages()
+            .filter((candidate) => {
+            return candidate === page || frameUrls.has(candidate.url());
+        });
+    }
+    async checkExtensionStatus() {
+        const { host = '127.0.0.1', port = 19988, extensionId, token } = this.cdpConfig;
+        const { httpBaseUrl } = parseRelayHost(host, port);
+        const notConnected = { connected: false, activeTargets: 0, playwriterVersion: null };
+        const headers = {};
+        const effectiveToken = token || process.env.TABWRIGHT_TOKEN || process.env.PLAYWRITER_TOKEN;
+        if (effectiveToken) {
+            headers['Authorization'] = `Bearer ${effectiveToken}`;
+        }
+        try {
+            if (extensionId) {
+                const response = await fetch(`${httpBaseUrl}/extensions/status`, {
+                    signal: AbortSignal.timeout(2000),
+                    headers,
+                });
+                if (!response.ok) {
+                    const fallback = await fetch(`${httpBaseUrl}/extension/status`, {
+                        signal: AbortSignal.timeout(2000),
+                        headers,
+                    });
+                    if (!fallback.ok) {
+                        return notConnected;
+                    }
+                    return (await fallback.json());
+                }
+                const data = (await response.json());
+                const extension = data.extensions.find((item) => {
+                    return item.extensionId === extensionId || item.stableKey === extensionId;
+                });
+                if (!extension) {
+                    return notConnected;
+                }
+                return {
+                    connected: true,
+                    activeTargets: extension.activeTargets,
+                    playwriterVersion: extension?.playwriterVersion || null,
+                };
+            }
+            const response = await fetch(`${httpBaseUrl}/extension/status`, {
+                signal: AbortSignal.timeout(2000),
+                headers,
+            });
+            if (!response.ok) {
+                return notConnected;
+            }
+            return (await response.json());
+        }
+        catch {
+            return notConnected;
+        }
+    }
+    isDirectCdpMode() {
+        return !!this.cdpConfig.directCdpUrl;
+    }
+    isHeadlessMode() {
+        return !!this.cdpConfig.headless;
+    }
+    /**
+     * Connect to Chrome and set up context/page. Shared by ensureConnection and reset.
+     * In headless mode, launches Chrome via chromium.launch().
+     * In direct CDP mode, connects straight to Chrome's WebSocket.
+     * In extension mode, checks extension status then connects via relay.
+     */
+    async connectToBrowser() {
+        // Headless mode: launch Chrome directly via Playwright (no extension, no relay CDP routing)
+        if (this.isHeadlessMode()) {
+            return this.connectHeadlessBrowser();
+        }
+        if (this.isDirectCdpMode()) {
+            // Direct CDP: connect straight to Chrome, no relay or extension needed
+            const chromium = await getChromium();
+            const browser = await chromium.connectOverCDP(this.cdpConfig.directCdpUrl);
+            browser.on('disconnected', () => {
+                this.logger.log('Browser disconnected, clearing connection state');
+                this.clearConnectionState();
+            });
+            const contexts = browser.contexts();
+            const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+            context.setDefaultTimeout(60000);
+            context.setDefaultNavigationTimeout(10000);
+            context.on('page', (page) => {
+                this.setupPageListeners(page);
+            });
+            context.pages().forEach((p) => this.setupPageListeners(p));
+            // In direct CDP mode, pages are always available (all tabs visible).
+            // Use the first non-closed page, or create one.
+            const pages = context.pages().filter((p) => !p.isClosed());
+            const page = pages.length > 0 ? pages[0] : await context.newPage();
+            this.setupPageListeners(page);
+            await this.setDeviceScaleFactorForMacOS(context);
+            // Block images, video, and fonts for cloud sessions with proxy enabled
+            // to reduce residential proxy bandwidth costs. Uses Network.setBlockedURLs
+            // which is a single fire-and-forget CDP command with zero per-request overhead.
+            if (this.cloudSession?.blockProxyResources) {
+                await this.applyProxyResourceBlocking(context);
+            }
+            return { browser, page, context };
+        }
+        // Extension mode: check status first for better error messages
+        const extensionStatus = await this.checkExtensionStatus();
+        if (!extensionStatus.connected) {
+            throw new Error(EXTENSION_NOT_CONNECTED_ERROR);
+        }
+        this.warnIfExtensionOutdated(extensionStatus.playwriterVersion);
+        const cdpUrl = getCdpUrl(this.cdpConfig);
+        const chromium = await getChromium();
+        const browser = await chromium.connectOverCDP(cdpUrl);
+        browser.on('disconnected', () => {
+            this.logger.log('Browser disconnected, clearing connection state');
+            this.clearConnectionState();
+        });
+        const contexts = browser.contexts();
+        const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+        // Action timeout (click, fill, hover, etc.) is longer to tolerate slower
+        // SPA/Turbo navigations and post-click settling on real sites.
+        // Navigation timeout (goto, reload) remains separate.
+        context.setDefaultTimeout(60000);
+        context.setDefaultNavigationTimeout(10000);
+        context.on('page', (page) => {
+            this.setupPageListeners(page);
+        });
+        context.pages().forEach((p) => this.setupPageListeners(p));
+        const page = await this.ensurePageForContext({ context, timeout: 10000 });
+        await this.setDeviceScaleFactorForMacOS(context);
+        return { browser, page, context };
+    }
+    /**
+     * Launch a headless Chrome via chromium.launch(). No extension, no relay CDP routing.
+     * Reuses an existing shared browser if one was already launched for headless mode.
+     * Does NOT add per-session disconnect listeners to avoid accumulation on the shared
+     * browser; instead, ensureConnection checks browser.isConnected() on each call.
+     */
+    async connectHeadlessBrowser() {
+        const browser = await PlaywrightExecutor.getOrLaunchHeadlessBrowser();
+        const context = await browser.newContext();
+        context.setDefaultTimeout(60000);
+        context.setDefaultNavigationTimeout(10000);
+        context.on('page', (page) => {
+            this.setupPageListeners(page);
+        });
+        const page = await context.newPage();
+        this.setupPageListeners(page);
+        await this.setDeviceScaleFactorForMacOS(context);
+        return { browser, page, context };
+    }
+    /** Shared headless browser instance across all headless sessions.
+     *  Uses a launch promise to prevent concurrent first-session races from
+     *  spawning multiple browsers. The disconnect handler is registered once
+     *  at launch time and clears both statics so the next session relaunches. */
+    static _sharedHeadlessBrowser = null;
+    static _sharedHeadlessBrowserPromise = null;
+    static async getOrLaunchHeadlessBrowser() {
+        // Check the cached browser is actually alive (not just non-null after a crash)
+        if (PlaywrightExecutor._sharedHeadlessBrowser?.isConnected()) {
+            return PlaywrightExecutor._sharedHeadlessBrowser;
+        }
+        // Deduplicate concurrent launches: second caller awaits the first's promise
+        if (PlaywrightExecutor._sharedHeadlessBrowserPromise) {
+            return PlaywrightExecutor._sharedHeadlessBrowserPromise;
+        }
+        const launchPromise = (async () => {
+            const chromium = await getChromium();
+            const { resolveBrowserExecutablePath } = await import('./browser-config.js');
+            const executablePath = resolveBrowserExecutablePath();
+            const browser = await chromium.launch({
+                headless: true,
+                executablePath,
+            });
+            // Single handler registered once per browser lifetime.
+            // Clears both statics so the next headless session relaunches.
+            browser.on('disconnected', () => {
+                PlaywrightExecutor._sharedHeadlessBrowser = null;
+                PlaywrightExecutor._sharedHeadlessBrowserPromise = null;
+            });
+            PlaywrightExecutor._sharedHeadlessBrowser = browser;
+            // Clear the promise now that the browser is cached; future callers
+            // use _sharedHeadlessBrowser directly. Concurrent waiters already
+            // hold a reference to launchPromise so they still resolve correctly.
+            PlaywrightExecutor._sharedHeadlessBrowserPromise = null;
+            return browser;
+        })();
+        PlaywrightExecutor._sharedHeadlessBrowserPromise = launchPromise;
+        try {
+            return await launchPromise;
+        }
+        catch (error) {
+            PlaywrightExecutor._sharedHeadlessBrowserPromise = null;
+            throw error;
+        }
+    }
+    /** Close the headless context for this session (called on session delete). */
+    async closeHeadlessContext() {
+        if (!this.isHeadlessMode() || !this.context) {
+            return;
+        }
+        await this.context.close().catch((e) => {
+            this.logger.error('Error closing headless context:', e);
+        });
+        this.clearConnectionState();
+    }
+    /** Close the shared headless browser (called on relay shutdown). */
+    static async closeSharedHeadlessBrowser() {
+        if (PlaywrightExecutor._sharedHeadlessBrowser) {
+            await PlaywrightExecutor._sharedHeadlessBrowser.close().catch(() => { });
+            PlaywrightExecutor._sharedHeadlessBrowser = null;
+            PlaywrightExecutor._sharedHeadlessBrowserPromise = null;
+        }
+    }
+    async ensureConnection() {
+        // In headless mode, also check the shared browser is still alive.
+        // After a crash, isConnected() returns false and we need to reconnect.
+        const browserAlive = this.isHeadlessMode() ? this.browser?.isConnected() : true;
+        if (this.isConnected && this.browser && this.page && browserAlive) {
+            return { browser: this.browser, page: this.page };
+        }
+        try {
+            const { browser, page, context } = await this.connectToBrowser();
+            this.browser = browser;
+            this.page = page;
+            this.context = context;
+            this.isConnected = true;
+            return { browser, page };
+        }
+        catch (error) {
+            // Cloud sessions that fail to connect are likely expired VMs.
+            // Give a clear error instead of a cryptic WebSocket/connection error.
+            if (this.cloudSession && error instanceof Error && isDisconnectionError(error)) {
+                throw new Error(CLOUD_SESSION_EXPIRED_ERROR, { cause: error });
+            }
+            throw error;
+        }
+    }
+    async getCurrentPage(timeout = 10000) {
+        if (this.page && !this.page.isClosed()) {
+            return this.page;
+        }
+        if (this.browser) {
+            const contexts = this.browser.contexts();
+            if (contexts.length > 0) {
+                const context = contexts[0];
+                this.context = context;
+                const pages = context.pages().filter((p) => !p.isClosed());
+                if (pages.length > 0) {
+                    const page = pages[0];
+                    await page.waitForLoadState('domcontentloaded', { timeout }).catch(() => { });
+                    this.page = page;
+                    return page;
+                }
+                const page = await this.ensurePageForContext({ context, timeout });
+                this.page = page;
+                return page;
+            }
+        }
+        throw new Error(NO_PAGES_AVAILABLE_ERROR);
+    }
+    async reset() {
+        this.suppressPageCloseWarnings = true;
+        try {
+            if (this.isHeadlessMode()) {
+                // In headless mode, only close this session's context, not the shared browser.
+                // Other headless sessions share the same browser instance.
+                if (this.context) {
+                    await this.context.close().catch((e) => {
+                        this.logger.error('Error closing context:', e);
+                    });
+                }
+            }
+            else if (this.browser) {
+                await this.browser.close();
+            }
+        }
+        catch (e) {
+            this.logger.error('Error closing browser:', e);
+        }
+        finally {
+            this.suppressPageCloseWarnings = false;
+        }
+        this.clearConnectionState();
+        this.clearUserState();
+        const { browser, page, context } = await this.connectToBrowser();
+        this.browser = browser;
+        this.page = page;
+        this.context = context;
+        this.isConnected = true;
+        return { page, context };
+    }
+    async execute(code, timeout = 10000, options = {}) {
+        const consoleLogs = [];
+        const warningScope = this.beginWarningScope();
+        const formatConsoleLogs = (logs, prefix = 'Console output') => {
+            if (logs.length === 0) {
+                return '';
+            }
+            let text = `${prefix}:\n`;
+            logs.forEach(({ method, args }) => {
+                const formattedArgs = args
+                    .map((arg) => {
+                    if (typeof arg === 'string')
+                        return arg;
+                    return util.inspect(arg, {
+                        depth: 4,
+                        colors: false,
+                        maxArrayLength: 100,
+                        maxStringLength: 1000,
+                        breakLength: 80,
+                    });
+                })
+                    .join(' ');
+                text += `[${method}] ${formattedArgs}\n`;
+            });
+            return text + '\n';
+        };
+        try {
+            // Warn if cloud VM is approaching its hard timeout (deduped by minute bucket)
+            if (this.cloudSession?.timeoutAt) {
+                const remainingMs = this.cloudSession.timeoutAt - Date.now();
+                if (remainingMs <= 0) {
+                    throw new Error(CLOUD_SESSION_EXPIRED_ERROR);
+                }
+                if (remainingMs < 5 * 60_000) {
+                    const mins = Math.ceil(remainingMs / 60_000);
+                    if (this.lastCloudTimeoutWarningMinute !== mins) {
+                        this.lastCloudTimeoutWarningMinute = mins;
+                        this.enqueueWarning(`Cloud browser expires in ~${mins} minute${mins === 1 ? '' : 's'}. ` +
+                            `Create a new session soon with: tabwright session new --browser cloud`);
+                    }
+                }
+            }
+            await this.ensureConnection();
+            const page = await this.getCurrentPage(timeout);
+            const context = this.context || page.context();
+            this.logger.log('Executing code:', code);
+            const customConsole = {
+                log: (...args) => {
+                    consoleLogs.push({ method: 'log', args });
+                },
+                info: (...args) => {
+                    consoleLogs.push({ method: 'info', args });
+                },
+                warn: (...args) => {
+                    consoleLogs.push({ method: 'warn', args });
+                },
+                error: (...args) => {
+                    consoleLogs.push({ method: 'error', args });
+                },
+                debug: (...args) => {
+                    consoleLogs.push({ method: 'debug', args });
+                },
+            };
+            const snapshot = async (options) => {
+                const { page: targetPage, frame, locator, search, showDiffSinceLastCall = !search, interactiveOnly = false, } = options;
+                const resolvedPage = targetPage || page;
+                if (!resolvedPage) {
+                    throw new Error('snapshot requires a page');
+                }
+                // Use new in-page implementation via getAriaSnapshot
+                const { snapshot: rawSnapshot, refs, getSelectorForRef, } = await getAriaSnapshot({
+                    page: resolvedPage,
+                    frame,
+                    locator,
+                    interactiveOnly,
+                });
+                const snapshotStr = rawSnapshot.toWellFormed?.() ?? rawSnapshot;
+                const refToLocator = new Map();
+                for (const entry of refs) {
+                    const locatorStr = getSelectorForRef(entry.ref);
+                    if (locatorStr) {
+                        refToLocator.set(entry.shortRef, locatorStr);
+                    }
+                }
+                this.lastRefToLocator.set(resolvedPage, refToLocator);
+                const shouldCacheSnapshot = !frame;
+                // Cache keyed by locator selector so full-page and locator-scoped snapshots
+                // don't pollute each other's diff baselines
+                const snapshotKey = locator ? `locator:${locator.selector()}` : 'page';
+                let pageSnapshots = this.lastSnapshots.get(resolvedPage);
+                if (!pageSnapshots) {
+                    pageSnapshots = new Map();
+                    this.lastSnapshots.set(resolvedPage, pageSnapshots);
+                }
+                const previousSnapshot = shouldCacheSnapshot ? pageSnapshots.get(snapshotKey) : undefined;
+                if (shouldCacheSnapshot) {
+                    pageSnapshots.set(snapshotKey, snapshotStr);
+                }
+                // Diff defaults off when search is provided, but agent can explicitly enable both
+                if (showDiffSinceLastCall && previousSnapshot && shouldCacheSnapshot) {
+                    const diffResult = createSmartDiff({
+                        oldContent: previousSnapshot,
+                        newContent: snapshotStr,
+                        label: 'snapshot',
+                    });
+                    if (diffResult.type === 'no-change') {
+                        return 'No changes since last snapshot. Use showDiffSinceLastCall: false to see full content.';
+                    }
+                    return diffResult.content;
+                }
+                if (!search) {
+                    return `${snapshotStr}\n\nuse refToLocator({ ref: 'e3' }) to get locators for ref strings.`;
+                }
+                const lines = snapshotStr.split('\n');
+                const matchIndices = [];
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    const isMatch = isRegExp(search) ? search.test(line) : line.includes(search);
+                    if (isMatch) {
+                        matchIndices.push(i);
+                        if (matchIndices.length >= 10)
+                            break;
+                    }
+                }
+                if (matchIndices.length === 0) {
+                    return 'No matches found';
+                }
+                const CONTEXT_LINES = 5;
+                const includedLines = new Set();
+                for (const idx of matchIndices) {
+                    const start = Math.max(0, idx - CONTEXT_LINES);
+                    const end = Math.min(lines.length - 1, idx + CONTEXT_LINES);
+                    for (let i = start; i <= end; i++) {
+                        includedLines.add(i);
+                    }
+                }
+                const sortedIndices = [...includedLines].sort((a, b) => a - b);
+                const result = [];
+                for (let i = 0; i < sortedIndices.length; i++) {
+                    const lineIdx = sortedIndices[i];
+                    if (i > 0 && sortedIndices[i - 1] !== lineIdx - 1) {
+                        result.push('---');
+                    }
+                    result.push(lines[lineIdx]);
+                }
+                return result.join('\n');
+            };
+            const refToLocator = (options) => {
+                const targetPage = options.page || page;
+                const map = this.lastRefToLocator.get(targetPage);
+                if (!map) {
+                    return null;
+                }
+                return map.get(options.ref) ?? null;
+            };
+            const getLocatorStringForElement = async (element) => {
+                if (!element || typeof element.evaluate !== 'function') {
+                    throw new Error('getLocatorStringForElement: argument must be a Playwright Locator or ElementHandle');
+                }
+                const elementPage = element.page ? element.page() : page;
+                const hasGenerator = await elementPage.evaluate(() => !!globalThis.__selectorGenerator);
+                if (!hasGenerator) {
+                    const scriptPath = path.join(__dirname, '..', 'dist', 'selector-generator.js');
+                    const scriptContent = fs.readFileSync(scriptPath, 'utf-8');
+                    const cdp = await getCDPSession({ page: elementPage });
+                    await cdp.send('Runtime.evaluate', { expression: scriptContent });
+                }
+                return await element.evaluate((el) => {
+                    const { createSelectorGenerator, toLocator } = globalThis.__selectorGenerator;
+                    const generator = createSelectorGenerator(globalThis);
+                    const result = generator(el);
+                    return toLocator(result.selector, 'javascript');
+                });
+            };
+            const getLatestLogs = async (options) => {
+                const { page: filterPage, count, search, sinceLastCall = false } = options || {};
+                let allLogs = [];
+                // Collect logs, optionally slicing from cursor when sinceLastCall is set
+                const collectLogs = (targetPage) => {
+                    const logs = this.browserLogs.get(targetPage) || [];
+                    if (!sinceLastCall) {
+                        return logs;
+                    }
+                    const cursor = this.pageLogCursor.get(targetPage) || 0;
+                    return logs.slice(cursor);
+                };
+                if (filterPage) {
+                    const relatedPages = this.pagesRelatedToPage(filterPage);
+                    allLogs = relatedPages.flatMap((relatedPage) => {
+                        return collectLogs(relatedPage);
+                    });
+                }
+                else {
+                    for (const [p] of this.browserLogs) {
+                        allLogs.push(...collectLogs(p));
+                    }
+                }
+                // Advance cursors after collecting so next sinceLastCall call starts fresh
+                if (sinceLastCall) {
+                    const pagesToAdvance = filterPage
+                        ? this.pagesRelatedToPage(filterPage)
+                        : [...this.browserLogs.keys()];
+                    for (const p of pagesToAdvance) {
+                        const logs = this.browserLogs.get(p);
+                        if (logs) {
+                            this.pageLogCursor.set(p, logs.length);
+                        }
+                    }
+                }
+                if (search) {
+                    const matchIndices = [];
+                    for (let i = 0; i < allLogs.length; i++) {
+                        const log = allLogs[i];
+                        const isMatch = typeof search === 'string' ? log.includes(search) : isRegExp(search) && search.test(log);
+                        if (isMatch)
+                            matchIndices.push(i);
+                    }
+                    const CONTEXT_LINES = 5;
+                    const includedIndices = new Set();
+                    for (const idx of matchIndices) {
+                        const start = Math.max(0, idx - CONTEXT_LINES);
+                        const end = Math.min(allLogs.length - 1, idx + CONTEXT_LINES);
+                        for (let i = start; i <= end; i++) {
+                            includedIndices.add(i);
+                        }
+                    }
+                    const sortedIndices = [...includedIndices].sort((a, b) => a - b);
+                    const result = [];
+                    for (let i = 0; i < sortedIndices.length; i++) {
+                        const logIdx = sortedIndices[i];
+                        if (i > 0 && sortedIndices[i - 1] !== logIdx - 1) {
+                            result.push('---');
+                        }
+                        result.push(allLogs[logIdx]);
+                    }
+                    allLogs = result;
+                }
+                return count !== undefined ? allLogs.slice(-count) : allLogs;
+            };
+            const clearAllLogs = () => {
+                this.browserLogs.clear();
+                this.pageLogCursor.clear();
+            };
+            const getCDPSession = async (options) => {
+                if (options.page.isClosed()) {
+                    throw new Error('Cannot create CDP session for closed page');
+                }
+                return await getCDPSessionForPage({ page: options.page });
+            };
+            const createDebugger = (options) => new Debugger(options);
+            const createEditor = (options) => new Editor(options);
+            const getStylesForLocatorFn = async (options) => {
+                const cdp = await getCDPSession({ page: options.locator.page() });
+                return getStylesForLocator({ locator: options.locator, cdp });
+            };
+            const getReactSourceFn = async (options) => {
+                const cdp = await getCDPSession({ page: options.locator.page() });
+                return getReactSource({ locator: options.locator, cdp });
+            };
+            const getReactComponentInfoFn = async (options) => {
+                const targetPage = await (async () => {
+                    if ('page' in options.locator) {
+                        return options.locator.page();
+                    }
+                    return (await options.locator.ownerFrame())?.page() ?? null;
+                })();
+                if (!targetPage) {
+                    throw new Error('Could not get page from locator');
+                }
+                const cdp = await getCDPSession({ page: targetPage });
+                return getReactComponentInfo({ locator: options.locator, cdp });
+            };
+            const inspectPinnedElement = async (pageUrl, elementExpression) => {
+                const targetPage = context.pages().find((candidate) => candidate.url() === pageUrl) || context.pages()[0];
+                if (!targetPage) {
+                    throw new Error('No Playwright pages are available');
+                }
+                this.userState.page = targetPage;
+                const handle = (await targetPage.evaluateHandle((expression) => {
+                    return Function(`return (${expression})`)();
+                }, elementExpression)).asElement();
+                const result = await (async () => {
+                    if (!handle) {
+                        return { url: targetPage.url(), outerHTML: null, react: null };
+                    }
+                    return {
+                        url: targetPage.url(),
+                        outerHTML: await handle.evaluate((el) => el.outerHTML),
+                        react: await getReactComponentInfoFn({ locator: handle }),
+                    };
+                })();
+                console.log(result);
+                return result;
+            };
+            const screenshotCollector = [];
+            // Separate collector for images produced by resizeImageForAgent() calls.
+            // These get merged into result.images so the CLI can emit them via Kitty Graphics.
+            const resizedImageCollector = [];
+            const resizeImageForAgentFn = async (options) => {
+                const result = await resizeImageForAgent(options);
+                resizedImageCollector.push({ data: result.buffer.toString('base64'), mimeType: result.mimeType });
+                return result;
+            };
+            const screenshotWithAccessibilityLabelsFn = async (options) => {
+                return screenshotWithAccessibilityLabels({
+                    ...options,
+                    collector: screenshotCollector,
+                    logger: {
+                        info: (...args) => {
+                            this.logger.error('[tabwright]', ...args);
+                        },
+                        error: (...args) => {
+                            this.logger.error('[tabwright]', ...args);
+                        },
+                    },
+                });
+            };
+            const relayPort = this.cdpConfig.port || 19988;
+            const self = this;
+            const ghostCursorController = this.ghostCursorController;
+            const showGhostCursor = async (options) => {
+                const targetPage = options?.page || page;
+                const cursorOptions = (() => {
+                    if (!options) {
+                        return undefined;
+                    }
+                    const { page: _ignoredPage, ...rest } = options;
+                    return rest;
+                })();
+                await ghostCursorController.show({ page: targetPage, cursorOptions });
+            };
+            const hideGhostCursor = async (options) => {
+                const targetPage = options?.page || page;
+                await ghostCursorController.hide({ page: targetPage });
+            };
+            const replayApi = createReplayApi({
+                context,
+                defaultPage: page,
+                relayPort,
+            });
+            const workflow = {
+                saveCapability: (input) => {
+                    return saveWorkflowCapability({
+                        ...input,
+                        cwd: self.sessionCwd || process.cwd(),
+                    });
+                },
+                saveFromRecording: (input) => {
+                    return saveWorkflowFromRecording({
+                        ...input,
+                        cwd: self.sessionCwd || process.cwd(),
+                    });
+                },
+            };
+            // Ghost Browser API - creates chrome object that mirrors Ghost Browser's APIs
+            // See extension/src/ghost-browser-api.d.ts for full API documentation
+            const chromeGhostBrowser = createGhostBrowserChrome(async (namespace, method, args) => {
+                const cdp = await getCDPSession({ page });
+                const result = await cdp.send('ghost-browser', { namespace, method, args });
+                const typed = result;
+                if (!typed.success) {
+                    throw new Error(typed.error || `Ghost Browser API call failed: ${namespace}.${method}`);
+                }
+                return typed.result;
+            });
+            let vmContextObj = {
+                page,
+                context,
+                browser: this.browser,
+                state: this.userState,
+                console: customConsole,
+                snapshot,
+                accessibilitySnapshot: snapshot, // backward compat alias
+                refToLocator,
+                getCleanHTML,
+                getPageMarkdown,
+                getLocatorStringForElement,
+                getLatestLogs,
+                clearAllLogs,
+                waitForPageLoad,
+                getCDPSession,
+                createDebugger,
+                createEditor,
+                getStylesForLocator: getStylesForLocatorFn,
+                formatStylesAsText,
+                getReactSource: getReactSourceFn,
+                getReactComponentInfo: getReactComponentInfoFn,
+                inspectPinnedElement,
+                screenshotWithAccessibilityLabels: screenshotWithAccessibilityLabelsFn,
+                resizeImageForAgent: resizeImageForAgentFn,
+                // Backward-compatible alias for resizeImageForAgent
+                resizeImage: resizeImageForAgentFn,
+                ghostCursor: {
+                    show: showGhostCursor,
+                    hide: hideGhostCursor,
+                },
+                replay: {
+                    start: replayApi.start,
+                    stop: replayApi.stop,
+                    isRecording: replayApi.isRecording,
+                    cancel: replayApi.cancel,
+                    list: replayApi.list,
+                    events: replayApi.events,
+                },
+                workflow,
+                // Backward-compatible aliases
+                startReplay: replayApi.start,
+                stopReplay: replayApi.stop,
+                isReplayRecording: replayApi.isRecording,
+                cancelReplay: replayApi.cancel,
+                listReplays: replayApi.list,
+                saveWorkflowCapability: workflow.saveCapability,
+                saveWorkflowFromRecording: workflow.saveFromRecording,
+                resetPlaywright: async () => {
+                    const { page: newPage, context: newContext } = await self.reset();
+                    vmContextObj.page = newPage;
+                    vmContextObj.context = newContext;
+                    vmContextObj.browser = self.browser;
+                    return { page: newPage, context: newContext };
+                },
+                require: this.sandboxedRequire,
+                import: (specifier) => import(specifier),
+                // Ghost Browser API - only works in Ghost Browser, mirrors chrome.ghostPublicAPI etc
+                chrome: chromeGhostBrowser,
+                ...usefulGlobals,
+                // Expose process with safety overrides:
+                // - cwd() returns the session's cwd instead of the relay server's cwd
+                // - exit() is blocked to prevent killing the relay server
+                // - chdir() is blocked to prevent affecting other sessions
+                process: new Proxy(process, {
+                    get(target, prop, receiver) {
+                        if (prop === 'cwd')
+                            return () => self.sessionCwd || target.cwd();
+                        if (prop === 'exit')
+                            return () => { throw new Error('process.exit() is not allowed in the sandbox'); };
+                        if (prop === 'chdir')
+                            return () => { throw new Error('process.chdir() is not allowed in the sandbox, use a new session with a different cwd instead'); };
+                        return Reflect.get(target, prop, receiver);
+                    },
+                }),
+            };
+            const vmContext = vm.createContext(vmContextObj);
+            const autoReturnExpr = getAutoReturnExpression(code);
+            const wrappedCode = autoReturnExpr !== null
+                ? `(async () => { return await (${autoReturnExpr}) })()`
+                : `(async () => { ${code} })()`;
+            const hasExplicitReturn = autoReturnExpr !== null || /\breturn\b/.test(code);
+            const result = await Promise.race([
+                vm.runInContext(wrappedCode, vmContext, { timeout, displayErrors: true }),
+                new Promise((_, reject) => setTimeout(() => reject(new CodeExecutionTimeoutError(timeout)), timeout)),
+            ]);
+            let responseText = formatConsoleLogs(consoleLogs);
+            // Only show return value if user explicitly used return
+            let structuredResult;
+            if (hasExplicitReturn) {
+                const resolvedResult = isPromise(result) ? await result : result;
+                // Auto-returned Playwright handles (Response, Page, Browser, Request,
+                // Frame, etc.) are silently skipped — they're programmatic references,
+                // not useful display data. Users can `console.log(response)` or
+                // return specific fields (`return response.url()`) to see values.
+                // See issue #82.
+                if (resolvedResult !== undefined && !isPlaywrightChannelOwner(resolvedResult)) {
+                    if (options.includeStructuredResult) {
+                        structuredResult = resolvedResult;
+                    }
+                    const formatted = typeof resolvedResult === 'string'
+                        ? resolvedResult
+                        : util.inspect(resolvedResult, {
+                            depth: 4,
+                            colors: false,
+                            maxArrayLength: 100,
+                            maxStringLength: 1000,
+                            breakLength: 80,
+                        });
+                    if (formatted.trim()) {
+                        responseText += `[return value] ${formatted}\n`;
+                    }
+                }
+            }
+            responseText += this.flushWarningsForScope(warningScope);
+            if (!responseText.trim()) {
+                responseText = 'Code executed successfully (no output)';
+            }
+            const MAX_LENGTH = 10000;
+            let finalText = responseText.trim();
+            if (finalText.length > MAX_LENGTH) {
+                finalText =
+                    finalText.slice(0, MAX_LENGTH) +
+                        `\n\n[Truncated to ${MAX_LENGTH} characters. Use search to find specific content]`;
+            }
+            const images = [
+                ...screenshotCollector.map((s) => ({ data: s.base64, mimeType: s.mimeType })),
+                ...resizedImageCollector,
+            ];
+            const screenshots = screenshotCollector.map((s) => ({
+                path: s.path,
+                base64: s.base64,
+                mimeType: s.mimeType,
+                snapshot: s.snapshot,
+                labelCount: s.labelCount,
+            }));
+            return options.includeStructuredResult
+                ? { text: finalText, images, screenshots, isError: false, structuredResult }
+                : { text: finalText, images, screenshots, isError: false };
+        }
+        catch (error) {
+            const errorStack = error.stack || error.message;
+            const isTimeoutError = error instanceof CodeExecutionTimeoutError || error?.name === 'TimeoutError' || error?.name === 'AbortError';
+            this.logger.error('Error in execute:', errorStack);
+            const logsText = formatConsoleLogs(consoleLogs, 'Console output (before error)');
+            const warningText = this.flushWarningsForScope(warningScope);
+            // Cloud sessions: disconnection errors mean the VM expired or was destroyed.
+            // Give a clear actionable message instead of a generic "call reset" hint.
+            const isDisconnect = error instanceof Error && isDisconnectionError(error);
+            const resetHint = (() => {
+                if (isTimeoutError)
+                    return '';
+                if (this.cloudSession && isDisconnect) {
+                    return `\n\n[Cloud browser expired or disconnected. Create a new session with: tabwright session new --browser cloud]`;
+                }
+                return '\n\n[HINT: If this is an internal Playwright error, page/browser closed, or connection issue, call reset to reconnect.]';
+            })();
+            // timeout stacks are internal noise (Promise.race / setTimeout); only show the message
+            const errorText = isTimeoutError ? error.message : errorStack;
+            return {
+                text: `${logsText}${warningText}\nError executing code: ${errorText}${resetHint}`,
+                images: [],
+                screenshots: [],
+                isError: true,
+            };
+        }
+    }
+    // When extension is connected but has no pages, auto-create unless PLAYWRITER_AUTO_ENABLE=false disables it.
+    // In direct CDP mode, always create a page (no extension check needed).
+    async ensurePageForContext(options) {
+        const { context, timeout } = options;
+        const pages = context.pages().filter((p) => !p.isClosed());
+        if (pages.length > 0) {
+            return pages[0];
+        }
+        // Direct CDP mode: always create a new page, no extension involved
+        if (this.isDirectCdpMode()) {
+            const page = await context.newPage();
+            this.setupPageListeners(page);
+            await page.waitForLoadState('domcontentloaded', { timeout }).catch(() => { });
+            return page;
+        }
+        const extensionStatus = await this.checkExtensionStatus();
+        if (!extensionStatus.connected) {
+            throw new Error(EXTENSION_NOT_CONNECTED_ERROR);
+        }
+        if (!shouldAutoEnableTabwright()) {
+            const waitTimeoutMs = Math.min(timeout, 1000);
+            const startTime = Date.now();
+            while (Date.now() - startTime < waitTimeoutMs) {
+                const availablePages = context.pages().filter((p) => !p.isClosed());
+                if (availablePages.length > 0) {
+                    return availablePages[0];
+                }
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            throw new Error(NO_PAGES_AVAILABLE_ERROR);
+        }
+        const page = await context.newPage();
+        this.setupPageListeners(page);
+        const pageUrl = page.url();
+        if (pageUrl === 'about:blank') {
+            return page;
+        }
+        // Avoid burning the full timeout on about:blank-like pages.
+        await page.waitForLoadState('domcontentloaded', { timeout }).catch(() => { });
+        return page;
+    }
+    /** Get info about current connection state */
+    getStatus() {
+        return {
+            connected: this.isConnected,
+            pageUrl: this.page?.url() || null,
+            pagesCount: this.context?.pages().length || 0,
+        };
+    }
+    /** Get keys of user-defined state */
+    getStateKeys() {
+        return Object.keys(this.userState);
+    }
+    getSessionMetadata() {
+        return this.sessionMetadata;
+    }
+    getSessionInfo({ id }) {
+        const status = this.getStatus();
+        return {
+            id,
+            stateKeys: this.getStateKeys(),
+            extensionId: this.sessionMetadata.extensionId,
+            browser: this.sessionMetadata.browser,
+            profile: this.sessionMetadata.profile,
+            cwd: this.sessionCwd,
+            connected: status.connected,
+            pageUrl: status.pageUrl,
+            pagesCount: status.pagesCount,
+        };
+    }
+}
+/**
+ * Session manager for multiple executors, keyed by session ID.
+ */
+export class ExecutorManager {
+    executors = new Map();
+    cdpConfig;
+    logger;
+    constructor(options) {
+        this.cdpConfig = options.cdpConfig;
+        this.logger = options.logger || { log: console.log, error: console.error };
+    }
+    getExecutor(options) {
+        const { sessionId, cwd, sessionMetadata } = options;
+        let executor = this.executors.get(sessionId);
+        if (!executor) {
+            const cdpConfig = (() => {
+                // Per-session override takes priority (used for direct CDP sessions)
+                if (options.cdpConfig) {
+                    return options.cdpConfig;
+                }
+                const baseConfig = typeof this.cdpConfig === 'function' ? this.cdpConfig(sessionId) : this.cdpConfig;
+                if (sessionMetadata?.extensionId) {
+                    return { ...baseConfig, extensionId: sessionMetadata.extensionId };
+                }
+                return baseConfig;
+            })();
+            executor = new PlaywrightExecutor({
+                cdpConfig,
+                sessionMetadata,
+                logger: this.logger,
+                cwd,
+                cloudSession: options.cloudSession,
+            });
+            this.executors.set(sessionId, executor);
+        }
+        return executor;
+    }
+    deleteExecutor(sessionId) {
+        return this.executors.delete(sessionId);
+    }
+    getSession(sessionId) {
+        return this.executors.get(sessionId) || null;
+    }
+    listSessions() {
+        return [...this.executors.entries()].map(([id, executor]) => {
+            return executor.getSessionInfo({ id });
+        });
+    }
+}
+//# sourceMappingURL=executor.js.map