playwriter 0.0.89 → 0.0.103

package/dist/chrome-discovery.test.js

@@ -0,0 +1,41 @@
+import { describe, test, expect } from 'vitest';
+import { parseDevToolsActivePort } from './chrome-discovery.js';
+describe('parseDevToolsActivePort', () => {
+    test('parses valid contents', () => {
+        const result = parseDevToolsActivePort('9222\n/devtools/browser/abc-123-def\n');
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "port": 9222,
+        "wsPath": "/devtools/browser/abc-123-def",
+      }
+    `);
+    });
+    test('parses with extra whitespace', () => {
+        const result = parseDevToolsActivePort('  9222  \n  /devtools/browser/abc  \n');
+        expect(result).toMatchInlineSnapshot(`
+      {
+        "port": 9222,
+        "wsPath": "/devtools/browser/abc",
+      }
+    `);
+    });
+    test('returns null for single line', () => {
+        expect(parseDevToolsActivePort('9222')).toBeNull();
+    });
+    test('returns null for empty string', () => {
+        expect(parseDevToolsActivePort('')).toBeNull();
+    });
+    test('returns null for invalid port', () => {
+        expect(parseDevToolsActivePort('abc\n/devtools/browser/123')).toBeNull();
+    });
+    test('returns null for port 0', () => {
+        expect(parseDevToolsActivePort('0\n/devtools/browser/123')).toBeNull();
+    });
+    test('returns null for port > 65535', () => {
+        expect(parseDevToolsActivePort('99999\n/devtools/browser/123')).toBeNull();
+    });
+    test('returns null for invalid ws path', () => {
+        expect(parseDevToolsActivePort('9222\n/some/other/path')).toBeNull();
+    });
+});
+//# sourceMappingURL=chrome-discovery.test.js.map

package/dist/chrome-discovery.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome-discovery.test.js","sourceRoot":"","sources":["../src/chrome-discovery.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AAE/D,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,IAAI,CAAC,uBAAuB,EAAE,GAAG,EAAE;QACjC,MAAM,MAAM,GAAG,uBAAuB,CAAC,uCAAuC,CAAC,CAAA;QAC/E,MAAM,CAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC;;;;;KAKpC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACxC,MAAM,MAAM,GAAG,uBAAuB,CAAC,uCAAuC,CAAC,CAAA;QAC/E,MAAM,CAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC;;;;;KAKpC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACpD,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,uBAAuB,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IAChD,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,uBAAuB,CAAC,4BAA4B,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IAC1E,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,uBAAuB,CAAC,0BAA0B,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,uBAAuB,CAAC,8BAA8B,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IAC5E,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,uBAAuB,CAAC,wBAAwB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACtE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/cli.js

@@ -3,25 +3,83 @@ 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, RELAY_PORT, waitForConnectedExtensions, getExtensionOutdatedWarning, getExtensionStatus, } from './relay-client.js';
+import { discoverChromeInstances, resolveDirectInput } 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) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+});
 cli
     .command('', 'Start the MCP server or controls the browser with -e')
     .option('--host <host>', 'Remote relay server host to connect to (or use PLAYWRITER_HOST env var)')
     .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 })
+    .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) {
@@ -35,6 +93,7 @@ cli
         return;
     }
     // 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,
@@ -140,9 +199,33 @@ async function executeCode(options) {
                 console.log(result.text);
             }
         }
-        // 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();
+        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) {
             process.exit(1);
@@ -160,13 +243,83 @@ async function executeCode(options) {
         process.exit(1);
     }
 }
-// Session management commands
 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')
+    .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;
+        try {
+            cdpEndpoint = await resolveDirectInput(directEndpoint);
+        }
+        catch (error) {
+            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 = [];
     if (isLocal) {
         await ensureRelayServer({ logger: console, env: cliRelayEnv });
@@ -189,6 +342,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);
     }
     // Warn if any connected extension was built with an older playwriter version
@@ -199,58 +353,156 @@ cli
             break;
         }
     }
-    let selectedExtension = 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}`);
+    // 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());
+            console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`);
         }
-        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}`);
+        catch (error) {
+            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 = [
+        ...extensions.map((ext) => {
+            return {
+                key: ext.stableKey || ext.extensionId,
+                type: 'extension',
+                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());
-        console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`);
-    }
-    catch (error) {
-        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());
+                console.log(`Session ${result.id} created. Use with: playwriter -s ${result.id} -e "..."`);
+            }
+        }
+        catch (error) {
+            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) {
+    if (isLocal) {
+        await ensureRelayServer({ logger: console, env: cliRelayEnv });
+    }
+}
+async function createDirectSession({ serverUrl, cdpEndpoint, browser, profiles, }) {
+    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());
+}
+function instanceToBrowserOption(instance) {
+    return {
+        key: `direct:${instance.port}`,
+        type: 'direct',
+        browser: instance.browser,
+        profile: formatInstanceProfiles(instance),
+        wsUrl: instance.wsUrl,
+        profiles: instance.profiles,
+    };
+}
+function formatInstanceProfiles(instance) {
+    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) {
+    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')
@@ -283,6 +535,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('ID'.padEnd(idWidth) +
         '  ' +
@@ -292,11 +545,14 @@ 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) +
             '  ' +
             (session.browser || 'Chrome').padEnd(browserWidth) +
@@ -305,6 +561,8 @@ cli
             '  ' +
             (session.extensionId || '-').padEnd(extensionWidth) +
             '  ' +
+            cwdLabel.padEnd(cwdWidth) +
+            '  ' +
             stateStr);
     }
 });
@@ -364,7 +622,7 @@ cli
 });
 cli
     .command('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) => {
@@ -443,6 +701,52 @@ cli
         process.exit(0);
     });
 });
+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([]),
+    ]);
+    const allOptions = [
+        ...extensions.map((ext) => {
+            return {
+                key: ext.stableKey || ext.extensionId,
+                type: 'extension',
+                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}`);