playwriter 0.3.1 → 0.4.0

package/src/cloud-client.ts

@@ -0,0 +1,172 @@
+// HTTP client for CLI to call the website's /api/cloud/* routes.
+// Auth: three methods, checked in priority order:
+//   1. PLAYWRITER_API_KEY env var → sent as x-api-key header (for CI/VPS/headless)
+//   2. PLAYWRITER_CLOUD_TOKEN env var → sent as Authorization: Bearer (for CI with session tokens)
+//   3. ~/.playwriter/auth.json file → saved by `cloud login` device flow
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const DEFAULT_BASE_URL = 'https://playwriter.dev'
+const AUTH_FILE = path.join(os.homedir(), '.playwriter', 'auth.json')
+
+/** Build a playwriter.dev/live URL from the exact CDP WebSocket URL.
+ *  Passes the full wss endpoint as ?wss= param so the client connects
+ *  to the exact host (Browser Use can shard across cdp1, cdp2, etc.). */
+export function buildLiveUrl(cdpUrl: string, baseUrl: string = DEFAULT_BASE_URL): string {
+  // Browser Use returns https:// CDP URLs; the live viewer needs wss://
+  const wssUrl = cdpUrl.replace(/^https:\/\//, 'wss://').replace(/^http:\/\//, 'ws://')
+  const url = new URL('/live', baseUrl)
+  url.searchParams.set('wss', wssUrl)
+  return url.toString()
+}
+
+// ── Auth persistence ────────────────────────────────────────────────
+
+export interface CloudAuth {
+  token: string
+  baseUrl: string
+  /** When true, token is an API key sent via x-api-key header instead of Bearer */
+  isApiKey?: boolean
+}
+
+export function loadCloudAuth(): CloudAuth | null {
+  // API key takes highest priority (simplest for CI/VPS/headless)
+  const apiKey = process.env.PLAYWRITER_API_KEY
+  if (apiKey) {
+    return { token: apiKey, baseUrl: process.env.PLAYWRITER_CLOUD_URL || DEFAULT_BASE_URL, isApiKey: true }
+  }
+  // Session token env var (for CI with device flow tokens)
+  const envToken = process.env.PLAYWRITER_CLOUD_TOKEN
+  if (envToken) {
+    return { token: envToken, baseUrl: process.env.PLAYWRITER_CLOUD_URL || DEFAULT_BASE_URL }
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(AUTH_FILE, 'utf-8'))
+    if (data.token) {
+      return { token: data.token, baseUrl: data.baseUrl || DEFAULT_BASE_URL }
+    }
+  } catch {
+    // No auth file
+  }
+  return null
+}
+
+export function saveCloudAuth(auth: CloudAuth): void {
+  const dir = path.dirname(AUTH_FILE)
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2), { encoding: 'utf-8', mode: 0o600 })
+}
+
+// ── Cloud session status types ───────────────────────────────────────
+
+export interface CloudSessionStatus {
+  cloudSessionId: string
+  browserUseSessionId: string
+  index: number
+  createdAt: number
+  status: 'active' | 'stopped'
+  cdpUrl: string | null
+  liveUrl: string | null
+  timeoutAt: string
+}
+
+export interface ConnectResult {
+  cloudSessionId: string
+  cdpUrl: string | null
+  liveUrl: string | null
+  /** BU VM hard timeout (ISO string from server) */
+  timeoutAt?: string
+}
+
+// ── Client ──────────────────────────────────────────────────────────
+
+export class CloudClient {
+  private baseUrl: string
+  private token: string
+  private isApiKey: boolean
+
+  constructor(auth: CloudAuth) {
+    this.baseUrl = auth.baseUrl
+    this.token = auth.token
+    this.isApiKey = auth.isApiKey ?? false
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: Record<string, unknown>,
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl).toString()
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+    // API keys use x-api-key header; session tokens use Authorization: Bearer
+    if (this.isApiKey) {
+      headers['x-api-key'] = this.token
+    } else {
+      headers['Authorization'] = `Bearer ${this.token}`
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    if (response.status === 401) {
+      throw new Error('Cloud auth expired or invalid. Run `playwriter cloud login` or set PLAYWRITER_API_KEY.')
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '')
+      let detail = text
+      try {
+        const json = JSON.parse(text)
+        detail = json.error || json.message || text
+      } catch {
+        // use raw text
+      }
+      throw new Error(`Cloud API error: ${response.status} — ${detail}`)
+    }
+
+    return response.json() as Promise<T>
+  }
+
+  async getStatus(): Promise<{ sessions: CloudSessionStatus[] }> {
+    return this.request('GET', '/api/cloud/status')
+  }
+
+  async connect(options: {
+    proxyRegion?: string
+    customProxy?: { host: string; port: number; username?: string; password?: string }
+    /** Cloud browser timeout in minutes (1-240, default 60) */
+    timeout?: number
+  }): Promise<ConnectResult> {
+    return this.request('POST', '/api/cloud/connect', {
+      proxyRegion: options.proxyRegion,
+      customProxy: options.customProxy,
+      ...(options.timeout ? { timeout: options.timeout } : {}),
+    })
+  }
+
+  async disconnect(cloudSessionId: string): Promise<void> {
+    await this.request('POST', '/api/cloud/disconnect', { cloudSessionId })
+  }
+
+  /** Get a single session's status by cloudSessionId (from the status list). */
+  async getSessionStatus(cloudSessionId: string): Promise<CloudSessionStatus | null> {
+    const { sessions } = await this.getStatus()
+    return sessions.find((s) => {
+      return s.cloudSessionId === cloudSessionId
+    }) ?? null
+  }
+}
+
+/** Create a CloudClient from saved auth, or null if not logged in. */
+export function getCloudClient(): CloudClient | null {
+  const auth = loadCloudAuth()
+  if (!auth) return null
+  return new CloudClient(auth)
+}

package/src/executor.ts

@@ -3,7 +3,8 @@
  * Used by both MCP and CLI to execute Playwright code with persistent state.
  */
 
-import { Page, Frame, Browser, BrowserContext, chromium, Locator, FrameLocator, ElementHandle } from '@xmorse/playwright-core'
+import type { Page, Frame, Browser, BrowserContext, Locator, FrameLocator, ElementHandle } from '@xmorse/playwright-core'
+import { getChromium, isPatchrightEnabled } from './playwright-import.js'
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -39,6 +40,7 @@ import { createDemoVideo } from './ffmpeg.js'
 import { type GhostCursorClientOptions } from './ghost-cursor.js'
 import { GhostCursorController } from './ghost-cursor-controller.js'
 
+
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
@@ -147,11 +149,46 @@ export function wrapCode(code: string): string {
 
 const EXTENSION_NOT_CONNECTED_ERROR = `The Playwriter Chrome extension is not connected. Make sure you have:
 1. Installed the extension: https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe
-2. Clicked the extension icon on a tab to enable it (or refreshed the page if just installed)`
+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 \`playwriter 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 Playwriter on a tab or unset PLAYWRITER_AUTO_ENABLE=false to auto-create one.'
 
+const CLOUD_SESSION_EXPIRED_ERROR =
+  'Cloud browser session expired or was destroyed. Create a new session with: playwriter 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: Error): boolean {
+  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([
@@ -229,6 +266,9 @@ export interface CdpConfig {
   extensionId?: string | null
   /** Direct CDP WebSocket URL — bypasses relay + extension, connects straight to Chrome */
   directCdpUrl?: string
+  /** Launch a headless Chrome via chromium.launch() instead of connecting to an existing one.
+   *  Uses direct Playwright browser management, no extension or relay CDP routing needed. */
+  headless?: boolean
 }
 
 export interface SessionMetadata {
@@ -246,12 +286,22 @@ export interface SessionInfo {
   cwd: string | null
 }
 
+export interface CloudSessionInfo {
+  /** Timestamp (epoch ms) when the BU VM will hard-timeout */
+  timeoutAt?: number
+  /** Whether proxy is enabled — when true, images/video/fonts are blocked to save bandwidth.
+   *  Set to false via --disable-proxy-bandwidth-acceleration to allow all resources. */
+  blockProxyResources?: boolean
+}
+
 export interface ExecutorOptions {
   cdpConfig: CdpConfig
   sessionMetadata?: SessionMetadata
   logger?: ExecutorLogger
   /** Working directory for scoped fs access */
   cwd?: string
+  /** Set when this executor is connected to a cloud Browser Use VM */
+  cloudSession?: CloudSessionInfo
 }
 
 function isRegExp(value: any): value is RegExp {
@@ -319,12 +369,17 @@ export class PlaywrightExecutor {
   private hasWarnedExtensionOutdated = false
 
   private ghostCursorController: GhostCursorController
+  /** Non-null when this executor is backed by a cloud Browser Use VM */
+  private cloudSession: CloudSessionInfo | null
+  /** Last minute bucket for which a cloud timeout warning was enqueued (dedup) */
+  private lastCloudTimeoutWarningMinute: number | null = null
 
   constructor(options: ExecutorOptions) {
     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,
@@ -376,6 +431,43 @@ export class PlaywrightExecutor {
     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). */
+  private async applyProxyResourceBlocking(context: BrowserContext): Promise<void> {
+    // 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: 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')
+  }
+
   private clearUserState() {
     Object.keys(this.userState).forEach((key) => delete this.userState[key])
   }
@@ -387,14 +479,24 @@ export class PlaywrightExecutor {
     this.context = null
   }
 
-  private enqueueWarning(message: string) {
+  enqueueWarning(message: string) {
     this.nextWarningEventId += 1
     this.warningEvents.push({ id: this.nextWarningEventId, message })
   }
 
+  /** Update the cloud session timeout from external tracking (relay timer). */
+  updateCloudTimeout(timeoutAt: number) {
+    if (this.cloudSession) {
+      this.cloudSession.timeoutAt = timeoutAt
+    }
+  }
+
   private beginWarningScope(): WarningScope {
+    // 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: WarningScope = {
-      cursor: this.nextWarningEventId,
+      cursor: this.lastDeliveredWarningEventId,
     }
     this.activeWarningScopes.add(scope)
     return scope
@@ -672,14 +774,25 @@ export class PlaywrightExecutor {
     return !!this.cdpConfig.directCdpUrl
   }
 
+  private isHeadlessMode(): boolean {
+    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.
    */
   private async connectToBrowser(): Promise<{ browser: Browser; page: Page; context: BrowserContext }> {
+    // 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', () => {
@@ -707,6 +820,13 @@ export class PlaywrightExecutor {
 
       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 }
     }
 
@@ -718,6 +838,7 @@ export class PlaywrightExecutor {
     this.warnIfExtensionOutdated(extensionStatus.playwriterVersion)
 
     const cdpUrl = getCdpUrl(this.cdpConfig)
+    const chromium = await getChromium()
     const browser = await chromium.connectOverCDP(cdpUrl)
 
     browser.on('disconnected', () => {
@@ -746,19 +867,128 @@ export class PlaywrightExecutor {
     return { browser, page, context }
   }
 
-  private async ensureConnection(): Promise<{ browser: Browser; page: Page }> {
-    if (this.isConnected && this.browser && this.page) {
-      return { browser: this.browser, page: this.page }
+  /**
+   * 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.
+   */
+  private async connectHeadlessBrowser(): Promise<{ browser: Browser; page: Page; context: BrowserContext }> {
+    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. */
+  private static _sharedHeadlessBrowser: Browser | null = null
+  private static _sharedHeadlessBrowserPromise: Promise<Browser> | null = null
+
+  private static async getOrLaunchHeadlessBrowser(): Promise<Browser> {
+    // Check the cached browser is actually alive (not just non-null after a crash)
+    if (PlaywrightExecutor._sharedHeadlessBrowser?.isConnected()) {
+      return PlaywrightExecutor._sharedHeadlessBrowser
     }
 
-    const { browser, page, context } = await this.connectToBrowser()
+    // Deduplicate concurrent launches: second caller awaits the first's promise
+    if (PlaywrightExecutor._sharedHeadlessBrowserPromise) {
+      return PlaywrightExecutor._sharedHeadlessBrowserPromise
+    }
 
-    this.browser = browser
-    this.page = page
-    this.context = context
-    this.isConnected = true
+    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
+    })()
 
-    return { browser, page }
+    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(): Promise<void> {
+    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(): Promise<void> {
+    if (PlaywrightExecutor._sharedHeadlessBrowser) {
+      await PlaywrightExecutor._sharedHeadlessBrowser.close().catch(() => {})
+      PlaywrightExecutor._sharedHeadlessBrowser = null
+      PlaywrightExecutor._sharedHeadlessBrowserPromise = null
+    }
+  }
+
+  private async ensureConnection(): Promise<{ browser: Browser; page: Page }> {
+    // 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
+    }
   }
 
   private async getCurrentPage(timeout = 10000): Promise<Page> {
@@ -788,15 +1018,23 @@ export class PlaywrightExecutor {
   }
 
   async reset(): Promise<{ page: Page; context: BrowserContext }> {
-    if (this.browser) {
-      this.suppressPageCloseWarnings = true
-      try {
+    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
       }
+    } catch (e) {
+      this.logger.error('Error closing browser:', e)
+    } finally {
+      this.suppressPageCloseWarnings = false
     }
 
     this.clearConnectionState()
@@ -840,6 +1078,24 @@ export class PlaywrightExecutor {
     }
 
     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: playwriter session new --browser cloud`,
+            )
+          }
+        }
+      }
+
       await this.ensureConnection()
       const page = await this.getCurrentPage(timeout)
       const context = this.context || page.context()
@@ -1237,6 +1493,7 @@ export class PlaywrightExecutor {
         return typed.result
       })
 
+
       let vmContextObj: any = {
         page,
         context,
@@ -1402,9 +1659,17 @@ export class PlaywrightExecutor {
 
       const logsText = formatConsoleLogs(consoleLogs, 'Console output (before error)')
       const warningText = this.flushWarningsForScope(warningScope)
-      const resetHint = isTimeoutError
-        ? ''
-        : '\n\n[HINT: If this is an internal Playwright error, page/browser closed, or connection issue, call reset to reconnect.]'
+
+      // 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: playwriter 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
@@ -1513,6 +1778,8 @@ export class ExecutorManager {
     sessionMetadata?: SessionMetadata
     /** Override cdpConfig for this session (e.g. direct CDP connection) */
     cdpConfig?: CdpConfig
+    /** Cloud session info (set when connecting to a Browser Use VM) */
+    cloudSession?: CloudSessionInfo
   }): PlaywrightExecutor {
     const { sessionId, cwd, sessionMetadata } = options
     let executor = this.executors.get(sessionId)
@@ -1533,6 +1800,7 @@ export class ExecutorManager {
         sessionMetadata,
         logger: this.logger,
         cwd,
+        cloudSession: options.cloudSession,
       })
       this.executors.set(sessionId, executor)
     }