playwriter 0.0.89 → 0.0.103

package/src/cli.ts

@@ -4,14 +4,23 @@ import fs from 'node:fs'
 import path from 'node:path'
 import util from 'node:util'
 import { fileURLToPath } from 'node:url'
-import { cac } from '@xmorse/cac'
+import { goke } from 'goke'
+import { z } from 'zod'
 import pc from 'picocolors'
+import {
+  getBrowserLaunchArgs,
+  getDefaultBrowserUserDataDir,
+  startBrowserProcess,
+} from './browser-launch.js'
+import { resolveBrowserExecutablePath, shouldUseHeadlessByDefault } from './browser-config.js'
+import { getBundledExtensionPath } from './package-paths.js'
 
 // Prevent Buffers from dumping hex bytes in util.inspect output.
 Buffer.prototype[util.inspect.custom] = function () {
   return `<Buffer ${this.length} bytes>`
 }
 import { killPortProcess } from './kill-port.js'
+import { canEmitKittyGraphics, emitKittyImage } from './kitty-graphics.js'
 import { VERSION, LOG_FILE_PATH, LOG_CDP_FILE_PATH, parseRelayHost } from './utils.js'
 import {
   ensureRelayServer,
@@ -21,12 +30,73 @@ import {
   getExtensionStatus,
   type ExtensionStatus,
 } from './relay-client.js'
+import { discoverChromeInstances, resolveDirectInput, type DiscoveredInstance } from './chrome-discovery.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 const cliRelayEnv = { PLAYWRITER_AUTO_ENABLE: '1' }
 
-const cli = cac('playwriter')
+const cli = goke('playwriter')
+
+cli
+  .command('browser start [binaryPath]', 'Start Chromium or Chrome for Testing with the bundled Playwriter extension')
+  .hidden()
+  .option('--user-data-dir <dir>', 'Persistent browser profile directory used for the managed browser')
+  .option('--headless', 'Run the browser in headless mode')
+  .option('--headed', 'Force headed mode even on Linux without DISPLAY/WAYLAND_DISPLAY')
+  .option('--disable-sandbox', 'Disable the browser sandbox, useful on some VPS setups')
+  .action(async (binaryPath, options) => {
+      if (options.headless && options.headed) {
+        console.error('Error: --headless and --headed cannot be used together.')
+        process.exit(1)
+      }
+
+      try {
+        await ensureRelayServer({ logger: console, env: cliRelayEnv })
+
+        const browserPath = resolveBrowserExecutablePath({ browserPath: binaryPath })
+        const extensionPath = getBundledExtensionPath()
+        const userDataDir = path.resolve(options.userDataDir || getDefaultBrowserUserDataDir())
+        const headless = options.headed ? false : options.headless ? true : shouldUseHeadlessByDefault()
+        const args = getBrowserLaunchArgs({
+          extensionPath,
+          userDataDir,
+          headless,
+          noSandbox: options.disableSandbox,
+        })
+
+        const { pid } = startBrowserProcess({
+          browserPath,
+          args,
+          userDataDir,
+        })
+
+        const connectedExtensions = await waitForConnectedExtensions({
+          timeoutMs: 15000,
+          pollIntervalMs: 250,
+          logger: console,
+        })
+
+        console.log(`Browser started (pid ${pid}).`)
+        console.log(`  Binary: ${browserPath}`)
+        console.log(`  Extension: ${extensionPath}`)
+        console.log(`  Profile: ${userDataDir}`)
+        console.log(`  Mode: ${headless ? 'headless' : 'headed'}`)
+        console.log('  Permissions: recording/tabCapture flags enabled')
+
+        if (connectedExtensions.length > 0) {
+          console.log('Playwriter extension connected to the relay server.')
+          return
+        }
+
+        console.log('Browser started, but the extension has not connected yet.')
+        console.log(`Check logs at: ${LOG_FILE_PATH}`)
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`)
+        process.exit(1)
+      }
+    },
+  )
 
 cli
   .command('', 'Start the MCP server or controls the browser with -e')
@@ -34,8 +104,8 @@ cli
   .option('--token <token>', 'Authentication token (or use PLAYWRITER_TOKEN env var)')
   .option('-s, --session <name>', 'Session ID (required for -e, get one with `playwriter session new`)')
   .option('-e, --eval <code>', 'Execute JavaScript code and exit, read https://playwriter.dev/SKILL.md for usage')
-  .option('--timeout <ms>', 'Execution timeout in milliseconds', { default: 10000 })
-  .action(async (options: { host?: string; token?: string; eval?: string; timeout?: number; session?: string }) => {
+  .option('--timeout [ms]', z.number().default(10000).describe('Execution timeout in milliseconds'))
+  .action(async (options) => {
     // If -e flag is provided, execute code via relay server
     if (options.eval) {
       await executeCode({
@@ -49,6 +119,7 @@ cli
     }
 
     // Otherwise start the MCP server
+    // For direct CDP in MCP mode, use PLAYWRITER_DIRECT env var
     const { startMcp } = await import('./mcp.js')
     await startMcp({
       host: options.host,
@@ -171,6 +242,7 @@ async function executeCode(options: {
     const result = (await response.json()) as {
       text: string
       images: Array<{ data: string; mimeType: string }>
+      screenshots: Array<{ path: string; base64: string; snapshot: string; labelCount: number }>
       isError: boolean
     }
 
@@ -183,9 +255,36 @@ async function executeCode(options: {
       }
     }
 
-    // Note: images are base64 encoded, we could save them to files if needed
-    if (result.images && result.images.length > 0) {
-      console.log(`\n${result.images.length} screenshot(s) captured`)
+    // Emit images via Kitty Graphics Protocol when AGENT_GRAPHICS=kitty.
+    // Agents with kitty-graphics-agent intercept these escape sequences and pass
+    // the PNG images to the LLM as media parts — no extra tool call needed.
+    const kittyEnabled = canEmitKittyGraphics()
+
+    // Track emitted base64 to avoid duplicates (screenshots appear in both
+    // result.screenshots and result.images from the same screenshotCollector)
+    const emittedImages = new Set<string>()
+
+    if (result.screenshots && result.screenshots.length > 0) {
+      for (const s of result.screenshots) {
+        if (kittyEnabled && s.base64) {
+          emitKittyImage({ base64: s.base64 })
+          emittedImages.add(s.base64)
+        }
+        console.log(`\nScreenshot saved to: ${s.path}`)
+        console.log(`Labels shown: ${s.labelCount}\n`)
+        console.log(`Accessibility snapshot:\n${s.snapshot}`)
+      }
+    }
+
+    // Emit resized images from resizeImageForAgent() calls that aren't
+    // already emitted as part of labeled screenshots
+    if (kittyEnabled && result.images && result.images.length > 0) {
+      for (const img of result.images) {
+        if (img.data && !emittedImages.has(img.data)) {
+          emitKittyImage({ base64: img.data })
+          emittedImages.add(img.data)
+        }
+      }
     }
 
     if (result.isError) {
@@ -204,13 +303,106 @@ async function executeCode(options: {
 }
 
 // Session management commands
+// Unified browser option type used in the multi-browser selection table
+interface BrowserOption {
+  key: string
+  type: 'extension' | 'direct'
+  browser: string
+  profile: string
+  /** For extension entries */
+  extensionId?: string | null
+  /** For direct CDP entries */
+  wsUrl?: string
+  /** Raw profile data from discovery (for passing to relay) */
+  profiles?: Array<{ name: string; email: string }>
+}
+
 cli
   .command('session new', 'Create a new session and print the session ID')
   .option('--host <host>', 'Remote relay server host')
-  .option('--browser <stableKey>', 'Stable browser key when multiple browsers are connected')
-  .action(async (options: { host?: string; browser?: string }) => {
+  .option('--browser <key>', 'Browser key when multiple browsers are available')
+  .option('--direct [endpoint]', 'Use direct CDP connection without the extension. Enable debugging first at chrome://inspect/#remote-debugging or launch Chrome with --remote-debugging-port=9222. Auto-discovers instances or accepts an explicit ws:// endpoint')
+  .action(async (options) => {
     const isLocal = !options.host && !process.env.PLAYWRITER_HOST
+    const directEndpoint = typeof options.direct === 'string' ? options.direct : null
+
+    // If --direct with explicit endpoint, resolve it (handles host:port → ws://) then skip discovery
+    if (directEndpoint) {
+      let cdpEndpoint: string
+      try {
+        cdpEndpoint = await resolveDirectInput(directEndpoint)
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`)
+        process.exit(1)
+      }
+      await ensureRelayForSessionCreation(isLocal)
+      const serverUrl = await getServerUrl(options.host)
+      const result = await createDirectSession({ serverUrl, cdpEndpoint })
+      console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
+      console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
+      return
+    }
 
+    // If --direct with no endpoint, discover Chrome instances
+    if (options.direct === true) {
+      if (!isLocal) {
+        console.error('Error: --direct auto-discovery only works locally.')
+        console.error('For remote relay, pass an explicit endpoint reachable from the relay host:')
+        console.error('  playwriter session new --host <host> --direct ws://relay-host:9222/devtools/browser/...')
+        process.exit(1)
+      }
+      await ensureRelayForSessionCreation(isLocal)
+      console.log(pc.dim('Discovering Chrome instances with debugging enabled...'))
+      const instances = await discoverChromeInstances()
+
+      if (instances.length === 0) {
+        console.error('No Chrome instances with debugging enabled found.')
+        console.error('')
+        console.error('Enable debugging in one of these ways:')
+        console.error('  1. Open chrome://inspect/#remote-debugging in Chrome')
+        console.error('  2. Launch Chrome with: chrome --remote-debugging-port=9222')
+        process.exit(1)
+      }
+
+      if (instances.length === 1 && !options.browser) {
+        const instance = instances[0]
+        const serverUrl = await getServerUrl(options.host)
+        const result = await createDirectSession({ serverUrl, cdpEndpoint: instance.wsUrl, browser: instance.browser, profiles: instance.profiles })
+        const profileLabel = formatInstanceProfiles(instance)
+        console.log(
+          `Session ${result.id} created (direct CDP, ${instance.browser}${profileLabel}). Use with: playwriter -s ${result.id} -e "..."`,
+        )
+        console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
+        return
+      }
+
+      // Multiple instances or --browser specified
+      const directOptions = instances.map((instance) => {
+        return instanceToBrowserOption(instance)
+      })
+
+      if (options.browser) {
+        const selected = directOptions.find((opt) => {
+          return opt.key === options.browser
+        })
+        if (!selected) {
+          console.error(`Browser not found: ${options.browser}`)
+          console.error('Available: ' + directOptions.map((opt) => opt.key).join(', '))
+          process.exit(1)
+        }
+        const serverUrl = await getServerUrl(options.host)
+        const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles })
+        console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
+        console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
+        return
+      }
+
+      printBrowserTable(directOptions)
+      console.log('\nRun again with --browser <key>.')
+      process.exit(1)
+    }
+
+    // Default mode: extension-based (existing behavior)
     let extensions: ExtensionStatus[] = []
 
     if (isLocal) {
@@ -235,6 +427,7 @@ cli
 
     if (extensions.length === 0) {
       console.error('No connected browsers detected. Click the Playwriter extension icon.')
+      console.error(pc.dim('Tip: Use --direct to connect via Chrome DevTools Protocol instead.'))
       process.exit(1)
     }
 
@@ -247,64 +440,184 @@ cli
       }
     }
 
-    let selectedExtension: ExtensionStatus | null = null
-
-    if (extensions.length === 1) {
-      selectedExtension = extensions[0]
-    } else if (!options.browser) {
-      console.log('Multiple browsers detected:\n')
-      console.log('KEY                      BROWSER  PROFILE')
-      console.log('-----------------------  -------  -------')
-      for (const extension of extensions) {
-        const label = extension.profile?.email || '(not signed in)'
-        const stableKey = extension.stableKey || '-'
-        console.log(`${stableKey.padEnd(23)}  ${(extension.browser || 'Chrome').padEnd(7)}  ${label}`)
-      }
-      console.log('\nRun again with --browser <stableKey>.')
-      process.exit(1)
-    } else {
-      const browserArg = options.browser
-      selectedExtension = extensions.find((extension) => extension.stableKey === browserArg) || null
-      if (!selectedExtension) {
-        console.error(`Browser not found: ${browserArg}`)
+    // Single extension: auto-select (unchanged behavior)
+    if (extensions.length === 1 && !options.browser) {
+      const selectedExtension = extensions[0]
+      try {
+        const serverUrl = await getServerUrl(options.host)
+        const extensionId =
+          selectedExtension.extensionId === 'default'
+            ? null
+            : selectedExtension.stableKey || selectedExtension.extensionId
+        const cwd = process.cwd()
+        const response = await fetch(`${serverUrl}/cli/session/new`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ extensionId, cwd }),
+        })
+        if (!response.ok) {
+          const text = await response.text()
+          console.error(`Error: ${response.status} ${text}`)
+          process.exit(1)
+        }
+        const result = (await response.json()) as { id: string; extensionId: string | null }
+        console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`)
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`)
         process.exit(1)
       }
+      return
     }
 
-    if (!selectedExtension) {
-      console.error('Unable to determine browser identity.')
-      process.exit(1)
-    }
-
-    try {
-      const serverUrl = await getServerUrl(options.host)
-      const extensionId =
-        selectedExtension.extensionId === 'default'
-          ? null
-          : selectedExtension.stableKey || selectedExtension.extensionId
-      const cwd = process.cwd()
-      const response = await fetch(`${serverUrl}/cli/session/new`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ extensionId, cwd }),
+    // Multiple extensions: also discover direct CDP instances and show unified table.
+    // Only discover locally — remote relay can't reach local Chrome debug ports.
+    const directInstances = isLocal ? await (async () => {
+      console.log(pc.dim('Discovering additional Chrome instances...'))
+      return await discoverChromeInstances()
+    })() : []
+
+    const allOptions: BrowserOption[] = [
+      ...extensions.map((ext) => {
+        return {
+          key: ext.stableKey || ext.extensionId,
+          type: 'extension' as const,
+          browser: ext.browser || 'Chrome',
+          profile: ext.profile?.email || '(not signed in)',
+          extensionId: ext.extensionId === 'default' ? null : ext.stableKey || ext.extensionId,
+        }
+      }),
+      ...directInstances.map((instance) => {
+        return instanceToBrowserOption(instance)
+      }),
+    ]
+
+    if (options.browser) {
+      const selected = allOptions.find((opt) => {
+        return opt.key === options.browser
       })
-      if (!response.ok) {
-        const text = await response.text()
-        console.error(`Error: ${response.status} ${text}`)
+      if (!selected) {
+        console.error(`Browser not found: ${options.browser}`)
+        console.error('Available: ' + allOptions.map((opt) => opt.key).join(', '))
         process.exit(1)
       }
-      const result = (await response.json()) as { id: string; extensionId: string | null }
-      console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`)
-    } catch (error: any) {
-      console.error(`Error: ${error.message}`)
-      process.exit(1)
+
+      try {
+        const serverUrl = await getServerUrl(options.host)
+        if (selected.type === 'direct') {
+          const result = await createDirectSession({ serverUrl, cdpEndpoint: selected.wsUrl!, browser: selected.browser, profiles: selected.profiles })
+          console.log(`Session ${result.id} created (direct CDP). Use with: playwriter -s ${result.id} -e "..."`)
+          console.log(pc.dim('NOTE: Recording unavailable in direct CDP mode.'))
+        } else {
+          const cwd = process.cwd()
+          const response = await fetch(`${serverUrl}/cli/session/new`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ extensionId: selected.extensionId, cwd }),
+          })
+          if (!response.ok) {
+            const text = await response.text()
+            console.error(`Error: ${response.status} ${text}`)
+            process.exit(1)
+          }
+          const result = (await response.json()) as { id: string }
+          console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`)
+        }
+      } catch (error: any) {
+        console.error(`Error: ${error.message}`)
+        process.exit(1)
+      }
+      return
     }
+
+    // Show unified table
+    console.log('\nMultiple browsers detected:\n')
+    printBrowserTable(allOptions)
+    console.log('\nRun again with --browser <key>.')
+    process.exit(1)
+  })
+
+async function ensureRelayForSessionCreation(isLocal: boolean): Promise<void> {
+  if (isLocal) {
+    await ensureRelayServer({ logger: console, env: cliRelayEnv })
+  }
+}
+
+async function createDirectSession({
+  serverUrl,
+  cdpEndpoint,
+  browser,
+  profiles,
+}: {
+  serverUrl: string
+  cdpEndpoint: string
+  browser?: string
+  profiles?: Array<{ name: string; email: string }>
+}): Promise<{ id: string }> {
+  const cwd = process.cwd()
+  const response = await fetch(`${serverUrl}/cli/session/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ cdpEndpoint, cwd, browser, profiles }),
+  })
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`${response.status} ${text}`)
+  }
+  return (await response.json()) as { id: string }
+}
+
+function instanceToBrowserOption(instance: DiscoveredInstance): BrowserOption {
+  return {
+    key: `direct:${instance.port}`,
+    type: 'direct',
+    browser: instance.browser,
+    profile: formatInstanceProfiles(instance),
+    wsUrl: instance.wsUrl,
+    profiles: instance.profiles,
+  }
+}
+
+function formatInstanceProfiles(instance: DiscoveredInstance): string {
+  if (instance.profiles.length === 0) {
+    return '(unknown)'
+  }
+  return instance.profiles
+    .map((p) => {
+      return p.email ? `${p.name} (${p.email})` : p.name
+    })
+    .join(', ')
+}
+
+function printBrowserTable(options: BrowserOption[]): void {
+  const typeLabels = options.map((opt) => {
+    return opt.type === 'direct' ? '--direct' : opt.type
   })
+  const keyWidth = Math.max(3, ...options.map((opt) => opt.key.length))
+  const typeWidth = Math.max(4, ...typeLabels.map((t) => t.length))
+  const browserWidth = Math.max(7, ...options.map((opt) => opt.browser.length))
+
+  console.log(
+    'KEY'.padEnd(keyWidth) + '  ' + 'TYPE'.padEnd(typeWidth) + '  ' + 'BROWSER'.padEnd(browserWidth) + '  ' + 'PROFILE',
+  )
+  console.log('-'.repeat(keyWidth + typeWidth + browserWidth + 20))
+  for (let i = 0; i < options.length; i++) {
+    const opt = options[i]
+    console.log(
+      opt.key.padEnd(keyWidth) +
+        '  ' +
+        typeLabels[i].padEnd(typeWidth) +
+        '  ' +
+        opt.browser.padEnd(browserWidth) +
+        '  ' +
+        opt.profile,
+    )
+  }
+}
 
 cli
   .command('session list', 'List all active sessions')
   .option('--host <host>', 'Remote relay server host')
-  .action(async (options: { host?: string }) => {
+  .action(async (options) => {
     if (!options.host && !process.env.PLAYWRITER_HOST) {
       await ensureRelayServer({ logger: console, env: cliRelayEnv })
     }
@@ -316,6 +629,7 @@ cli
       browser: string | null
       profile: { email: string; id: string } | null
       extensionId: string | null
+      cwd: string | null
     }> = []
 
     try {
@@ -333,6 +647,7 @@ cli
           browser: string | null
           profile: { email: string; id: string } | null
           extensionId: string | null
+          cwd: string | null
         }>
       }
       sessions = result.sessions
@@ -350,6 +665,7 @@ cli
     const browserWidth = Math.max(7, ...sessions.map((session) => (session.browser || 'Chrome').length))
     const profileWidth = Math.max(7, ...sessions.map((session) => (session.profile?.email || '').length || 1))
     const extensionWidth = Math.max(2, ...sessions.map((session) => (session.extensionId || '').length || 1))
+    const cwdWidth = Math.max(3, ...sessions.map((session) => (session.cwd || '').length || 1))
     const stateWidth = Math.max(10, ...sessions.map((session) => session.stateKeys.join(', ').length || 1))
 
     console.log(
@@ -361,13 +677,16 @@ cli
         '  ' +
         'EXT'.padEnd(extensionWidth) +
         '  ' +
+        'CWD'.padEnd(cwdWidth) +
+        '  ' +
         'STATE KEYS',
     )
-    console.log('-'.repeat(idWidth + browserWidth + profileWidth + extensionWidth + stateWidth + 8))
+    console.log('-'.repeat(idWidth + browserWidth + profileWidth + extensionWidth + cwdWidth + stateWidth + 10))
 
     for (const session of sessions) {
       const stateStr = session.stateKeys.length > 0 ? session.stateKeys.join(', ') : '-'
       const profileLabel = session.profile?.email || '-'
+      const cwdLabel = session.cwd || '-'
       console.log(
         String(session.id).padEnd(idWidth) +
           '  ' +
@@ -377,6 +696,8 @@ cli
           '  ' +
           (session.extensionId || '-').padEnd(extensionWidth) +
           '  ' +
+          cwdLabel.padEnd(cwdWidth) +
+          '  ' +
           stateStr,
       )
     }
@@ -385,7 +706,7 @@ cli
 cli
   .command('session delete <sessionId>', 'Delete a session and clear its state')
   .option('--host <host>', 'Remote relay server host')
-  .action(async (sessionId: string, options: { host?: string }) => {
+  .action(async (sessionId, options) => {
     const serverUrl = await getServerUrl(options.host)
 
     if (!options.host && !process.env.PLAYWRITER_HOST) {
@@ -415,7 +736,7 @@ cli
 cli
   .command('session reset <sessionId>', 'Reset the browser connection for a session')
   .option('--host <host>', 'Remote relay server host')
-  .action(async (sessionId: string, options: { host?: string }) => {
+  .action(async (sessionId, options) => {
     const cwd = process.cwd()
     const serverUrl = await getServerUrl(options.host)
 
@@ -451,10 +772,10 @@ cli
     'serve',
     `Start the relay server on this machine (must be the same host where Chrome is running). Remote clients (Docker, other machines) connect via PLAYWRITER_HOST. Use --host localhost for Docker (no token needed) — containers reach it via host.docker.internal. Use --host 0.0.0.0 for LAN/internet access (requires --token).`,
   )
-  .option('--host <host>', 'Host to bind to (use "localhost" for Docker, "0.0.0.0" for remote access)', { default: '0.0.0.0' })
+  .option('--host [host]', z.string().default('0.0.0.0').describe('Host to bind to (use "localhost" for Docker, "0.0.0.0" for remote access)'))
   .option('--token <token>', 'Authentication token, required when --host is 0.0.0.0 (or use PLAYWRITER_TOKEN env var)')
   .option('--replace', 'Kill existing server if running')
-  .action(async (options: { host: string; token?: string; replace?: boolean }) => {
+  .action(async (options) => {
     const token = options.token || process.env.PLAYWRITER_TOKEN
     const isPublicHost = options.host === '0.0.0.0' || options.host === '::'
     if (isPublicHost && !token) {
@@ -543,6 +864,58 @@ cli
     })
   })
 
+cli
+  .command('browser list', 'List all available browsers: extension-connected and direct CDP on port 9222')
+  .option('--host <host>', z.string().describe('Remote relay server host'))
+  .action(async (options) => {
+    const isLocal = !options.host && !process.env.PLAYWRITER_HOST
+
+    // Start relay if local so the extension can connect, then fetch in parallel
+    if (isLocal) {
+      await ensureRelayServer({ logger: console, env: cliRelayEnv })
+    }
+
+    const [extensions, directInstances] = await Promise.all([
+      isLocal
+        ? waitForConnectedExtensions({ timeoutMs: 2000, pollIntervalMs: 200, logger: console })
+        : fetchExtensionsStatus(options.host),
+      isLocal ? discoverChromeInstances() : Promise.resolve([] as DiscoveredInstance[]),
+    ])
+
+    const allOptions: BrowserOption[] = [
+      ...extensions.map((ext) => {
+        return {
+          key: ext.stableKey || ext.extensionId,
+          type: 'extension' as const,
+          browser: ext.browser || 'Chrome',
+          profile: ext.profile?.email || '(not signed in)',
+          extensionId: ext.extensionId === 'default' ? null : ext.stableKey || ext.extensionId,
+        }
+      }),
+      ...directInstances.map(instanceToBrowserOption),
+    ]
+
+    if (allOptions.length === 0) {
+      console.log('No browsers detected.\n')
+      console.log('  Extension: click the Playwriter icon on a tab to connect')
+      console.log('  Direct:    open chrome://inspect/#remote-debugging in Chrome')
+      return
+    }
+
+    printBrowserTable(allOptions)
+    console.log('')
+
+    const hasDirectInstances = allOptions.some((opt) => {
+      return opt.type === 'direct'
+    })
+    if (hasDirectInstances) {
+      console.log(pc.dim('Connect with: playwriter session new --direct'))
+      console.log(pc.dim('Chrome may ask to approve the debugging connection.'))
+    } else {
+      console.log(pc.dim('Use with: playwriter session new [--browser <key>]'))
+    }
+  })
+
 cli.command('logfile', 'Print the path to the relay server log file').action(() => {
   console.log(`relay: ${LOG_FILE_PATH}`)
   console.log(`cdp: ${LOG_CDP_FILE_PATH}`)