playwriter 0.3.0 → 0.4.0

package/src/cdp-relay.ts

@@ -24,8 +24,11 @@ Buffer.prototype[util.inspect.custom] = function () {
   return `<Buffer ${this.length} bytes>`
 }
 
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
 import { EventEmitter } from 'node:events'
-import { VERSION, EXTENSION_IDS } from './utils.js'
+import { VERSION, EXTENSION_IDS, shouldAutoEnablePlaywriter } from './utils.js'
 import { createCdpLogger, type CdpLogEntry, type CdpLogger } from './cdp-log.js'
 import { RecordingRelay } from './recording-relay.js'
 import { appendSessionToWsUrl } from './chrome-discovery.js'
@@ -156,22 +159,6 @@ export async function startPlayWriterCDPRelayServer({
     return null
   }
 
-  const buildStableExtensionKey = (info: relayState.ExtensionInfo, connectionId: string): string => {
-    if (info.id) {
-      return `profile:${info.id}`
-    }
-    if (info.email) {
-      return `email:${info.email}`
-    }
-    if (info.installId) {
-      return `install:${info.browser || 'unknown'}:${info.installId}`
-    }
-    if (info.browser) {
-      return `browser:${info.browser}`
-    }
-    return `connection:${connectionId}`
-  }
-
   const normalizeSessionId = (value: string | number | null | undefined): string | null => {
     if (value === undefined || value === null) {
       return null
@@ -521,11 +508,10 @@ export async function startPlayWriterCDPRelayServer({
     return recordingRelays.get(connId) || null
   }
 
-  // Auto-create initial tab when PLAYWRITER_AUTO_ENABLE is set and no targets exist.
-  // This allows Playwright to connect and immediately have a page to work with.
-  async function maybeAutoCreateInitialTab(options: { extensionId: string; autoEnable: boolean }): Promise<void> {
-    const { extensionId, autoEnable } = options
-    if (!autoEnable && !process.env.PLAYWRITER_AUTO_ENABLE) {
+  // Auto-create an initial blank tab when no targets exist. Set
+  // PLAYWRITER_AUTO_ENABLE=false to require manually enabled tabs instead.
+  async function maybeAutoCreateInitialTab(extensionId: string): Promise<void> {
+    if (!shouldAutoEnablePlaywriter()) {
       return
     }
     const conn = getExtensionConnection(extensionId)
@@ -655,14 +641,12 @@ export async function startPlayWriterCDPRelayServer({
     params,
     sessionId,
     source,
-    autoEnable,
   }: {
     extensionId: string | null
     method: CDPCommand['method'] | (string & {})
     params: CDPCommand['params']
     sessionId?: CDPCommand['sessionId']
     source?: CDPCommand['source']
-    autoEnable: boolean
   }) {
     const conn = getExtensionConnection(extensionId)
     const connectedTargets = conn?.connectedTargets || new Map<string, relayState.ConnectedTarget>()
@@ -702,7 +686,7 @@ export async function startPlayWriterCDPRelayServer({
           break
         }
         if (conn) {
-          await maybeAutoCreateInitialTab({ extensionId: conn.id, autoEnable })
+          await maybeAutoCreateInitialTab(conn.id)
         }
         // Forward auto-attach so Chrome emits iframe Target.attachedToTarget events.
         // Playwright relies on these (with parentFrameId) when reconnecting over CDP.
@@ -840,6 +824,13 @@ export async function startPlayWriterCDPRelayServer({
   }
 
   const app = new Hono()
+
+  // Global error handler — ensures server errors are logged, not silently swallowed
+  app.onError((err, c) => {
+    logger?.error('Unhandled route error:', err)
+    return c.json({ error: err.message }, 500)
+  })
+
   // CORS middleware for HTTP endpoints - only allows our specific extension IDs.
   // This prevents other extensions from reading responses via fetch/XHR.
   // WebSocket connections have their own separate origin validation.
@@ -1112,7 +1103,6 @@ export async function startPlayWriterCDPRelayServer({
       const clientId = c.req.param('clientId') || 'default'
       const url = new URL(c.req.url, 'http://localhost')
       const requestedExtensionId = url.searchParams.get('extensionId')
-      const autoEnable = url.searchParams.get('autoEnable') === '1'
       // When extensionId is explicit, resolve directly. Otherwise use fallback which
       // handles single-extension and uniquely-active-extension cases (#52).
       const resolvedExtension = requestedExtensionId
@@ -1204,7 +1194,6 @@ export async function startPlayWriterCDPRelayServer({
               params,
               sessionId,
               source,
-              autoEnable,
             })
 
             if (method === 'Target.setAutoAttach' && !sessionId) {
@@ -1403,7 +1392,7 @@ export async function startPlayWriterCDPRelayServer({
       const connectionId = `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
       return {
         onOpen(_event, ws) {
-          const stableKey = buildStableExtensionKey(incomingExtensionInfo, connectionId)
+          const stableKey = relayState.buildStableExtensionKey(incomingExtensionInfo, connectionId)
 
           // Check for existing connection with same stableKey and close it
           const existingExt = relayState.findExtensionByStableKey(store.getState(), stableKey)
@@ -1935,9 +1924,27 @@ export async function startPlayWriterCDPRelayServer({
           404,
         )
       }
-      const result = await existingExecutor.execute(code, timeout)
+      // Touch cloud session activity tracking if this session is cloud-backed
+      const cloudTracking = cloudSessionTracking.get(sessionId)
+      if (cloudTracking) {
+        cloudTracking.lastActivityAt = Date.now()
+        cloudTracking.activeExecutions++
+      }
+
+      let result: Awaited<ReturnType<typeof existingExecutor.execute>>
+      try {
+        result = await existingExecutor.execute(code, timeout)
+      } finally {
+        if (cloudTracking) {
+          cloudTracking.activeExecutions--
+          cloudTracking.lastActivityAt = Date.now()
+        }
+      }
 
-      return c.json(result)
+      // Use the cloudTracking snapshot captured before execute (not a fresh
+      // map lookup) so long-running executes that outlive idle cleanup still
+      // report isCloud correctly.
+      return c.json({ ...result, isCloud: Boolean(cloudTracking) })
     } catch (error: any) {
       logger?.error('Execute endpoint error:', error)
       return c.json({ text: `Server error: ${error.message}`, images: [], screenshots: [], isError: true }, 500)
@@ -1983,18 +1990,60 @@ export async function startPlayWriterCDPRelayServer({
   app.post('/cli/session/new', async (c) => {
     const body = (await c.req.json().catch(() => ({}))) as {
       extensionId?: string | null
-      autoEnable?: boolean
       cwd?: string
       /** Direct CDP WebSocket URL — bypasses extension, connects straight to Chrome */
       cdpEndpoint?: string
+      /** Launch a headless Chrome via chromium.launch() — no extension or relay CDP routing */
+      headless?: boolean
       /** Browser name from discovery (e.g. "Chrome", "Brave") */
       browser?: string
       /** Profile info from discovery */
       profiles?: Array<{ name: string; email: string }>
+      /** Cloud session tracking metadata (set by CLI when connecting to a cloud browser) */
+      cloud?: {
+        cloudSessionId: string
+        cloudBaseUrl: string
+        cloudToken: string
+        /** BU VM hard timeout (ISO string or epoch ms) */
+        timeoutAt?: string | number
+        /** Block images/video/fonts to save proxy bandwidth */
+        blockProxyResources?: boolean
+      }
     }
     const sessionId = String(nextSessionNumber++)
     const cwd = body.cwd
 
+    // Headless mode: launch Chrome via chromium.launch(), no extension needed.
+    // Force connection immediately so missing Chrome errors surface at creation time,
+    // not on first execute call.
+    if (body.headless) {
+      const manager = await getExecutorManager()
+      const executor = manager.getExecutor({
+        sessionId,
+        cwd,
+        cdpConfig: { headless: true },
+        sessionMetadata: {
+          extensionId: null,
+          browser: 'Chrome (Headless)',
+          profile: null,
+        },
+      })
+      try {
+        await executor.reset()
+      } catch (error) {
+        manager.deleteExecutor(sessionId)
+        return c.json({ error: error instanceof Error ? error.message : String(error) }, 500)
+      }
+      const metadata = executor.getSessionMetadata()
+      return c.json({
+        id: sessionId,
+        mode: 'headless' as const,
+        extensionId: metadata.extensionId,
+        browser: metadata.browser,
+        profile: metadata.profile,
+      })
+    }
+
     // Direct CDP mode: skip extension lookup, pass direct WebSocket URL to executor
     if (body.cdpEndpoint) {
       if (!body.cdpEndpoint.startsWith('ws://') && !body.cdpEndpoint.startsWith('wss://')) {
@@ -2002,6 +2051,9 @@ export async function startPlayWriterCDPRelayServer({
       }
       // Use first profile from discovery for session metadata (if available)
       const firstProfile = body.profiles?.[0]
+      const cloudTimeoutAt = body.cloud?.timeoutAt
+        ? (typeof body.cloud.timeoutAt === 'string' ? new Date(body.cloud.timeoutAt).getTime() : body.cloud.timeoutAt)
+        : undefined
       const manager = await getExecutorManager()
       const executor = manager.getExecutor({
         sessionId,
@@ -2012,8 +2064,23 @@ export async function startPlayWriterCDPRelayServer({
           browser: body.browser || null,
           profile: firstProfile ? { email: firstProfile.email, id: firstProfile.name } : null,
         },
+        cloudSession: body.cloud ? { timeoutAt: cloudTimeoutAt, blockProxyResources: body.cloud.blockProxyResources } : undefined,
       })
       const metadata = executor.getSessionMetadata()
+
+      // Register cloud session tracking if cloud metadata was provided
+      if (body.cloud) {
+        cloudSessionTracking.set(sessionId, {
+          cloudSessionId: body.cloud.cloudSessionId,
+          cloudBaseUrl: body.cloud.cloudBaseUrl,
+          cloudToken: body.cloud.cloudToken,
+          lastActivityAt: Date.now(),
+          activeExecutions: 0,
+          timeoutAt: cloudTimeoutAt,
+        })
+        persistCloudSessions()
+      }
+
       return c.json({
         id: sessionId,
         mode: 'direct' as const,
@@ -2037,7 +2104,6 @@ export async function startPlayWriterCDPRelayServer({
     const executor = manager.getExecutor({
       sessionId,
       cwd,
-      cdpConfig: { host: '127.0.0.1', port, token, extensionId: conn.stableKey, autoEnable: body.autoEnable === true },
       sessionMetadata: {
         extensionId: conn.stableKey,
         browser: conn.info.browser || null,
@@ -2074,11 +2140,32 @@ export async function startPlayWriterCDPRelayServer({
       }
 
       const manager = await getExecutorManager()
+      const executor = manager.getSession(sessionId)
+
+      // Close headless context before deleting to prevent context/page leaks
+      // on the shared headless browser. Only affects headless sessions.
+      if (executor) {
+        await executor.closeHeadlessContext()
+      }
+
       const deleted = manager.deleteExecutor(sessionId)
 
       if (!deleted) {
         return c.json({ error: `Session ${sessionId} not found` }, 404)
       }
+
+      // If this was a cloud-backed session, stop the VM only if no other
+      // relay session is still using the same cloud VM (reference counting).
+      const cloudTracking = cloudSessionTracking.get(sessionId)
+      if (cloudTracking) {
+        const shouldStopVm = !hasOtherCloudReferences(sessionId, cloudTracking.cloudSessionId)
+        cloudSessionTracking.delete(sessionId)
+        persistCloudSessions()
+        if (shouldStopVm) {
+          disconnectCloudVm(cloudTracking)
+        }
+      }
+
       return c.json({ success: true })
     } catch (error: any) {
       logger?.error('Delete session endpoint error:', error)
@@ -2153,6 +2240,180 @@ export async function startPlayWriterCDPRelayServer({
     return c.json(result)
   })
 
+  // ============================================================================
+  // Cloud session idle tracking
+  //
+  // Tracks lastActivityAt for cloud-backed sessions (those created via
+  // cdpEndpoint pointing to Browser Use VMs). A background interval checks
+  // every 60s and disconnects sessions idle > 10 minutes by calling the
+  // website's /api/cloud/disconnect endpoint.
+  // ============================================================================
+
+  interface CloudSessionTracking {
+    cloudSessionId: string
+    /** Website base URL for disconnect calls */
+    cloudBaseUrl: string
+    /** Bearer token for website API */
+    cloudToken: string
+    lastActivityAt: number
+    /** Number of currently running execute calls — skip idle timeout while > 0 */
+    activeExecutions: number
+    /** BU VM hard timeout (epoch ms) — used to warn users before expiration */
+    timeoutAt?: number
+  }
+
+  const cloudSessionTracking = new Map<string, CloudSessionTracking>()
+  const CLOUD_IDLE_TIMEOUT_MS = 10 * 60 * 1000 // 10 minutes
+
+  /** Check if any OTHER relay session references the same cloud VM.
+   *  Used to prevent stopping a VM that's still used by another relay session
+   *  (e.g. user attached twice via `session new --browser cloud-1`). */
+  function hasOtherCloudReferences(relaySessionId: string, cloudSessionId: string): boolean {
+    for (const [otherId, tracking] of cloudSessionTracking) {
+      if (otherId !== relaySessionId && tracking.cloudSessionId === cloudSessionId) {
+        return true
+      }
+    }
+    return false
+  }
+
+  /** Disconnect a cloud VM via the website API (best-effort, non-blocking). */
+  function disconnectCloudVm(tracking: CloudSessionTracking): void {
+    fetch(new URL('/api/cloud/disconnect', tracking.cloudBaseUrl).toString(), {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${tracking.cloudToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ cloudSessionId: tracking.cloudSessionId }),
+    }).catch((err) => {
+      logger?.error('[Cloud] Failed to disconnect cloud session:', err)
+    })
+  }
+
+  // ── Cloud session crash recovery ──────────────────────────────────
+  // Persist cloud session IDs to disk so orphaned VMs can be cleaned up
+  // if the relay process crashes. On startup, read the file and disconnect
+  // any leftover VMs (best-effort).
+
+  const CLOUD_SESSIONS_FILE = path.join(os.homedir(), '.playwriter', 'cloud-sessions.json')
+
+  interface PersistedCloudSession {
+    cloudSessionId: string
+    cloudBaseUrl: string
+    cloudToken: string
+  }
+
+  function persistCloudSessions(): void {
+    // Dedupe by cloudSessionId — multiple relay sessions can reference the same VM
+    const seen = new Set<string>()
+    const entries: PersistedCloudSession[] = []
+    for (const t of cloudSessionTracking.values()) {
+      if (seen.has(t.cloudSessionId)) continue
+      seen.add(t.cloudSessionId)
+      entries.push({
+        cloudSessionId: t.cloudSessionId,
+        cloudBaseUrl: t.cloudBaseUrl,
+        cloudToken: t.cloudToken,
+      })
+    }
+    try {
+      const dir = path.dirname(CLOUD_SESSIONS_FILE)
+      fs.mkdirSync(dir, { recursive: true })
+      if (entries.length > 0) {
+        // Atomic write: write to temp file then rename, so a crash mid-write
+        // doesn't leave corrupt JSON that blocks future cleanup.
+        const tmpFile = CLOUD_SESSIONS_FILE + '.tmp'
+        fs.writeFileSync(tmpFile, JSON.stringify(entries), { encoding: 'utf-8', mode: 0o600 })
+        fs.renameSync(tmpFile, CLOUD_SESSIONS_FILE)
+      } else {
+        // No active sessions — remove file to avoid stale data
+        try { fs.unlinkSync(CLOUD_SESSIONS_FILE) } catch { /* already gone */ }
+      }
+    } catch {
+      // Best-effort: don't crash relay if disk write fails
+    }
+  }
+
+  function cleanupOrphanedCloudSessions(): void {
+    let raw: string
+    try {
+      raw = fs.readFileSync(CLOUD_SESSIONS_FILE, 'utf-8')
+    } catch {
+      return // No file — nothing to clean up
+    }
+
+    let entries: PersistedCloudSession[]
+    try {
+      const parsed = JSON.parse(raw)
+      if (!Array.isArray(parsed)) return
+      // Validate shape: each entry must have cloudSessionId and cloudBaseUrl
+      entries = parsed.filter((e): e is PersistedCloudSession => {
+        return e && typeof e.cloudSessionId === 'string' && typeof e.cloudBaseUrl === 'string' && typeof e.cloudToken === 'string'
+      })
+    } catch {
+      // Corrupt JSON (e.g. crash during non-atomic write) — just remove it
+      try { fs.unlinkSync(CLOUD_SESSIONS_FILE) } catch { /* ignore */ }
+      return
+    }
+    if (!entries.length) {
+      try { fs.unlinkSync(CLOUD_SESSIONS_FILE) } catch { /* ignore */ }
+      return
+    }
+
+    logger?.log(pc.yellow(`[Cloud] Found ${entries.length} orphaned cloud session(s) from previous relay. Cleaning up...`))
+    // Remove file after we've read it — disconnect calls are best-effort async.
+    // If they fail, the BU VM will eventually hit its own timeout anyway.
+    try { fs.unlinkSync(CLOUD_SESSIONS_FILE) } catch { /* ignore */ }
+
+    for (const entry of entries) {
+      disconnectCloudVm({
+        cloudSessionId: entry.cloudSessionId,
+        cloudBaseUrl: entry.cloudBaseUrl,
+        cloudToken: entry.cloudToken,
+        lastActivityAt: 0,
+        activeExecutions: 0,
+      })
+    }
+  }
+
+  const cloudIdleInterval = setInterval(async () => {
+    const now = Date.now()
+    // Collect idle sessions first, then process — avoid mutating map during iteration
+    const idleSessions: Array<[string, CloudSessionTracking]> = []
+    for (const [sessionId, tracking] of cloudSessionTracking) {
+      // VM already past BU hard timeout — schedule for cleanup regardless of activity
+      if (tracking.timeoutAt && tracking.timeoutAt <= now) {
+        idleSessions.push([sessionId, tracking])
+        continue
+      }
+      // Timeout warnings are handled by the executor on each execute() call
+      // (deduped by minute bucket) — no need to enqueue from the relay interval.
+
+      if (tracking.activeExecutions > 0) continue
+      if (now - tracking.lastActivityAt > CLOUD_IDLE_TIMEOUT_MS) {
+        idleSessions.push([sessionId, tracking])
+      }
+    }
+
+    if (idleSessions.length > 0) {
+      for (const [sessionId, tracking] of idleSessions) {
+        logger?.log(
+          pc.yellow(`[Cloud] Stopping idle relay session ${sessionId} (idle > 10 min)`),
+        )
+        // Check if other relay sessions reference the same cloud VM.
+        // Only stop the VM when this is the last relay session for it.
+        const shouldStopVm = !hasOtherCloudReferences(sessionId, tracking.cloudSessionId)
+        cloudSessionTracking.delete(sessionId)
+        executorManager?.deleteExecutor(sessionId)
+        if (shouldStopVm) {
+          disconnectCloudVm(tracking)
+        }
+      }
+      persistCloudSessions()
+    }
+  }, 60_000)
+
   // Use createAdaptorServer instead of serve() so we control the listen()
   // timing. This lets us inject WebSocket upgrade handlers before binding and
   // await the bind to surface EADDRINUSE as a catchable error (issue #75).
@@ -2173,6 +2434,11 @@ export async function startPlayWriterCDPRelayServer({
     server.listen(port, host)
   })
 
+  // Clean up orphaned cloud sessions from a previous relay crash.
+  // Must run AFTER successful listen — if another relay is already running,
+  // we'd fail with EADDRINUSE but only after killing its live VMs.
+  cleanupOrphanedCloudSessions()
+
   const wsHost = `ws://${host}:${port}`
   const cdpEndpoint = `${wsHost}/cdp`
   const extensionEndpoint = `${wsHost}/extension`
@@ -2198,11 +2464,19 @@ export async function startPlayWriterCDPRelayServer({
         ext.ws?.close(1000, 'Server stopped')
       }
 
+      // Close shared headless browser if any headless sessions were created (fire-and-forget)
+      void import('./executor.js').then(({ PlaywrightExecutor }) => {
+        return PlaywrightExecutor.closeSharedHeadlessBrowser()
+      })
+
       // Reset store state
       store.setState({
         extensions: new Map(),
         playwrightClients: new Map(),
       })
+      clearInterval(cloudIdleInterval)
+      cloudSessionTracking.clear()
+      persistCloudSessions() // Remove the file on graceful shutdown
       server.close()
       emitter.removeAllListeners()
     },

package/src/chrome-discovery.ts

@@ -170,6 +170,15 @@ export async function resolveDirectInput(input: string): Promise<string> {
     return input
   }
 
+  // Cloud browser providers (Browser Use, Browserbase) return https:// CDP URLs.
+  // Convert to wss:// since the WebSocket connection uses the same hostname.
+  if (input.startsWith('https://')) {
+    return 'wss://' + input.slice('https://'.length)
+  }
+  if (input.startsWith('http://')) {
+    return 'ws://' + input.slice('http://'.length)
+  }
+
   const match = input.match(/^([^:]+):(\d+)$/)
   if (!match) {
     throw new Error(