deckide 3.5.36 → 3.5.37

package/dist/utils/agent-browser.js

@@ -1,7 +1,6 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
-import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { WebSocket } from 'ws';
@@ -23,6 +22,22 @@ function sleep(ms) {
 function isOpen(socket) {
     return socket.readyState === WebSocket.OPEN;
 }
+function waitForSocketOpen(socket, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error('Timed out connecting to Chrome DevTools WebSocket'));
+        }, timeoutMs);
+        timer.unref?.();
+        socket.once('open', () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        socket.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
 function coercePositiveInt(value, fallback, min, max) {
     if (typeof value !== 'number' || !Number.isFinite(value)) {
         return fallback;
@@ -105,35 +120,57 @@ async function findChromeExecutable() {
         }
         throw new Error(`AGENT_BROWSER_CHROME does not exist: ${process.env.AGENT_BROWSER_CHROME}`);
     }
-    const playwrightChrome = await findPlaywrightChromium();
-    if (playwrightChrome) {
-        return playwrightChrome;
-    }
-    return findInPath([
+    // 本物の Google Chrome を最優先（指紋が自然でボット判定を通りやすい）。
+    // Playwright の Chromium はフォールバックに回す。
+    const systemChrome = await findInPath([
         'google-chrome',
         'google-chrome-stable',
         'chromium',
         'chromium-browser',
         'chrome',
     ]);
+    if (systemChrome) {
+        return systemChrome;
+    }
+    return findPlaywrightChromium();
 }
-function getFreePort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.unref();
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            const address = server.address();
-            server.close(() => {
-                if (address && typeof address === 'object') {
-                    resolve(address.port);
-                }
-                else {
-                    reject(new Error('Unable to allocate a local port'));
-                }
-            });
-        });
-    });
+// MCP（chrome-devtools-mcp 等）が --browserUrl で確実に相乗りできるよう、
+// CDP ポートは固定にする。AGENT_BROWSER_CDP_PORT で上書き可、既定 9222。
+const DEFAULT_CDP_PORT = 9222;
+function resolveCdpPort() {
+    const raw = process.env.AGENT_BROWSER_CDP_PORT;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    if (Number.isInteger(parsed) && parsed >= 1 && parsed <= 65535) {
+        return parsed;
+    }
+    return DEFAULT_CDP_PORT;
+}
+/**
+ * Chrome の起動コマンドを解決する。
+ * ボット判定対策として「実 Chrome を headful」で動かしたい。Linux サーバ等で
+ * ディスプレイが無い場合は xvfb-run で仮想ディスプレイ上の headful を使う。
+ * xvfb-run も無ければやむを得ず headless にフォールバックする。
+ */
+function resolveLaunchCommand(executable, chromeArgs) {
+    const hasDisplay = Boolean(process.env.DISPLAY);
+    if (process.platform === 'linux' && !hasDisplay) {
+        const xvfbRun = ['/usr/bin/xvfb-run', '/usr/local/bin/xvfb-run'].find((p) => fsSync.existsSync(p));
+        if (xvfbRun) {
+            return {
+                command: xvfbRun,
+                args: [
+                    '-a',
+                    '--server-args=-screen 0 1280x720x24 -nolisten tcp',
+                    executable,
+                    ...chromeArgs,
+                ],
+            };
+        }
+        // ディスプレイも xvfb-run も無い → headless で動かす（Cloudflare は通りにくい）。
+        return { command: executable, args: ['--headless=new', ...chromeArgs] };
+    }
+    // ディスプレイがある（mac/win/Linux+X）→ そのまま headful 起動。
+    return { command: executable, args: chromeArgs };
 }
 async function fetchJson(url, options = {}, timeoutMs = 5000) {
     const controller = new AbortController();
@@ -243,10 +280,27 @@ export class AgentBrowserService {
     launching = null;
     port = null;
     executablePath = null;
-    cdp = null;
-    cdpSocket = null;
-    cdpConnecting = null;
+    // Browser-level CDP connection used only to discover tabs (page targets) and
+    // drive their lifecycle (create/close/activate). One per running Chrome.
+    browserCdp = null;
+    browserCdpSocket = null;
+    browserCdpConnecting = null;
+    // CDP connection to the *active* tab's page target — the only tab that streams
+    // frames and receives input. Switching tabs tears this down and reconnects to
+    // the new target.
+    activeCdp = null;
+    activeCdpSocket = null;
+    activeConnecting = null;
+    // Bumped on every tab switch. A slower in-flight connect compares against it
+    // and bails if it lost the race, so it can't clobber the newer active tab.
+    activeGeneration = 0;
     screencastStarted = false;
+    // Known page targets (tabs) keyed by targetId, in discovery/creation order.
+    tabs = new Map();
+    activeTargetId = null;
+    // True once the first active tab is established. Gates popup auto-follow so
+    // targets discovered during launch don't hijack focus before we've picked one.
+    ready = false;
     // Raw JPEG bytes of the most recent screencast frame, kept so reconnecting or
     // late-joining clients can be shown the current page immediately. Frames are
     // pushed to clients as binary WebSocket messages (no base64) to cut ~33% size
@@ -257,13 +311,12 @@ export class AgentBrowserService {
     frameFlushTimer = null;
     clients = new Set();
     viewport = { ...DEFAULT_VIEWPORT };
-    pageUrl = null;
-    pageTitle = null;
     lastError;
     audioRelay = new BrowserAudioRelay();
     profileDir = process.env.AGENT_BROWSER_PROFILE_DIR || DEFAULT_PROFILE_DIR;
     outputDir = process.env.AGENT_BROWSER_OUTPUT_DIR || DEFAULT_OUTPUT_DIR;
     async getStatus() {
+        const active = this.activeTargetId ? this.tabs.get(this.activeTargetId) : null;
         return {
             running: this.isRunning(),
             launching: Boolean(this.launching),
@@ -271,15 +324,17 @@ export class AgentBrowserService {
             outputDir: this.outputDir,
             executablePath: this.executablePath ?? await findChromeExecutable().catch(() => null),
             cdpUrl: this.port ? `http://127.0.0.1:${this.port}` : null,
-            pageUrl: this.pageUrl,
-            pageTitle: this.pageTitle,
+            pageUrl: active?.url ?? null,
+            pageTitle: active?.title ?? null,
+            tabs: [...this.tabs.values()].map((tab) => ({ ...tab })),
+            activeTabId: this.activeTargetId,
             audio: await this.audioRelay.getStatus(),
             error: this.lastError,
         };
     }
     async start() {
         if (this.isRunning()) {
-            await this.ensureCdp();
+            await this.ensureSession();
             if (this.clients.size > 0) {
                 await this.startScreencast();
             }
@@ -309,12 +364,14 @@ export class AgentBrowserService {
         }
     }
     async stop() {
-        this.closeCdp();
+        this.disconnectActiveCdp();
+        this.closeBrowserCdp();
         const proc = this.chromeProcess;
         this.chromeProcess = null;
         this.port = null;
-        this.pageUrl = null;
-        this.pageTitle = null;
+        this.tabs.clear();
+        this.activeTargetId = null;
+        this.ready = false;
         this.screencastStarted = false;
         this.lastFrameBuffer = null;
         this.pendingFrames.clear();
@@ -372,12 +429,46 @@ export class AgentBrowserService {
     async navigate(input) {
         const url = normalizeBrowserUrl(input);
         await this.start();
-        await this.ensureCdp();
-        await this.cdp?.send('Page.navigate', { url });
-        this.pageUrl = url;
-        await this.refreshPageInfo();
+        await this.ensureActiveCdp();
+        await this.activeCdp?.send('Page.navigate', { url });
+        const tab = this.activeTargetId ? this.tabs.get(this.activeTargetId) : null;
+        if (tab) {
+            tab.url = url;
+        }
+        await this.refreshActivePageInfo();
         await this.broadcastStatus();
     }
+    async newTab(input) {
+        await this.start();
+        await this.connectBrowserCdp();
+        const url = input ? normalizeBrowserUrl(input) : 'about:blank';
+        const result = await this.browserCdp?.send('Target.createTarget', { url });
+        const targetId = result?.targetId;
+        if (!targetId) {
+            throw new Error('Failed to open a new tab');
+        }
+        if (!this.tabs.has(targetId)) {
+            this.tabs.set(targetId, { id: targetId, url: url === 'about:blank' ? '' : url, title: '' });
+        }
+        await this.setActiveTab(targetId);
+    }
+    async closeTab(targetId) {
+        await this.connectBrowserCdp();
+        await this.browserCdp?.send('Target.closeTarget', { targetId }).catch(() => undefined);
+        this.removeTab(targetId);
+        // Never leave the pane with zero tabs — reopen a blank one like a real
+        // browser keeping a minimum of one tab.
+        if (this.tabs.size === 0 && this.isRunning()) {
+            await this.newTab().catch(() => undefined);
+        }
+    }
+    async activateTab(targetId) {
+        if (!this.tabs.has(targetId)) {
+            return;
+        }
+        await this.setActiveTab(targetId);
+        await this.browserCdp?.send('Target.activateTarget', { targetId }).catch(() => undefined);
+    }
     async launch() {
         this.lastError = undefined;
         await fs.mkdir(this.profileDir, { recursive: true });
@@ -387,10 +478,11 @@ export class AgentBrowserService {
             throw new Error('Chromium or Chrome was not found. Set AGENT_BROWSER_CHROME to a browser executable.');
         }
         this.executablePath = executable;
-        this.port = await getFreePort();
+        this.port = resolveCdpPort();
         this.openLogStream();
-        const args = [
-            '--headless=new',
+        // headless フラグは付けない（headful を既定にする）。ディスプレイ無し環境では
+        // resolveLaunchCommand が xvfb-run で仮想ディスプレイを用意する。
+        const chromeArgs = [
             `--remote-debugging-address=127.0.0.1`,
             `--remote-debugging-port=${this.port}`,
             `--user-data-dir=${this.profileDir}`,
@@ -398,13 +490,23 @@ export class AgentBrowserService {
             '--no-default-browser-check',
             '--disable-dev-shm-usage',
             '--autoplay-policy=no-user-gesture-required',
+            // GPU の無いサーバ + Xvfb 上で headful 起動すると、別プロセスの GPU が
+            // 起動失敗して "GPU process isn't usable. Goodbye." で即クラッシュする。
+            // GPU を browser プロセス内で動かし、GPU サンドボックスを外して回避する。
+            '--in-process-gpu',
+            '--disable-gpu-sandbox',
+            // ボット判定（Cloudflare の Managed Challenge 等）で誤検知されにくくする。
+            // navigator.webdriver を立てる自動化フラグを無効化する。残りの偽装は CDP 側。
+            '--disable-blink-features=AutomationControlled',
+            '--lang=ja-JP',
             '--window-size=1280,720',
-            'about:blank',
         ];
         if (process.getuid?.() === 0) {
-            args.splice(args.length - 1, 0, '--no-sandbox');
+            chromeArgs.push('--no-sandbox');
         }
-        const child = spawn(executable, args, {
+        chromeArgs.push('about:blank');
+        const { command, args } = resolveLaunchCommand(executable, chromeArgs);
+        const child = spawn(command, args, {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: process.env,
         });
@@ -415,7 +517,11 @@ export class AgentBrowserService {
             if (this.chromeProcess === child) {
                 this.chromeProcess = null;
                 this.port = null;
-                this.closeCdp();
+                this.disconnectActiveCdp();
+                this.closeBrowserCdp();
+                this.tabs.clear();
+                this.activeTargetId = null;
+                this.ready = false;
                 this.closeLogStream();
                 this.lastError = code === 0 ? undefined : `Browser exited (${signal ?? code ?? 'unknown'})`;
                 void this.broadcastStatus();
@@ -426,8 +532,8 @@ export class AgentBrowserService {
             void this.broadcastStatus();
         });
         await this.waitForChrome();
-        await this.ensureCdp();
-        await this.refreshPageInfo();
+        await this.connectBrowserCdp();
+        await this.ensureActiveTab();
         await this.broadcastStatus();
     }
     async waitForChrome() {
@@ -455,7 +561,7 @@ export class AgentBrowserService {
     async openForClient(socket) {
         try {
             await this.start();
-            await this.ensureCdp();
+            await this.ensureActiveCdp();
             await this.sendStatus(socket);
             // Replay the most recent frame so a reconnecting or late-joining client
             // sees the current page immediately. Screencast only emits frames on
@@ -479,80 +585,258 @@ export class AgentBrowserService {
         const proc = this.chromeProcess;
         return Boolean(proc && proc.exitCode == null && proc.signalCode == null);
     }
-    async ensureCdp() {
-        if (this.cdp && this.cdpSocket && isOpen(this.cdpSocket)) {
+    // Make sure the browser-level connection and an active tab (+ its CDP) exist.
+    async ensureSession() {
+        await this.connectBrowserCdp();
+        await this.ensureActiveTab();
+    }
+    async connectBrowserCdp() {
+        if (this.browserCdp && this.browserCdpSocket && isOpen(this.browserCdpSocket)) {
             return;
         }
-        if (this.cdpConnecting) {
-            return this.cdpConnecting;
+        if (this.browserCdpConnecting) {
+            return this.browserCdpConnecting;
         }
-        this.cdpConnecting = this.connectCdp();
+        this.browserCdpConnecting = this.doConnectBrowserCdp();
         try {
-            await this.cdpConnecting;
+            await this.browserCdpConnecting;
         }
         finally {
-            this.cdpConnecting = null;
+            this.browserCdpConnecting = null;
         }
     }
-    async connectCdp() {
+    async doConnectBrowserCdp() {
         if (!this.port) {
             throw new Error('Browser is not running');
         }
-        const target = await this.getOrCreatePageTarget();
-        if (!target.webSocketDebuggerUrl) {
-            throw new Error('Chrome page target has no DevTools WebSocket URL');
+        const version = await fetchJson(`http://127.0.0.1:${this.port}/json/version`);
+        if (!version.webSocketDebuggerUrl) {
+            throw new Error('Chrome has no browser-level DevTools endpoint');
         }
-        this.closeCdp();
-        const socket = new WebSocket(target.webSocketDebuggerUrl);
-        await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                reject(new Error('Timed out connecting to Chrome DevTools WebSocket'));
-            }, 10_000);
-            socket.once('open', () => {
-                clearTimeout(timer);
-                resolve();
-            });
-            socket.once('error', (error) => {
-                clearTimeout(timer);
-                reject(error);
-            });
+        this.closeBrowserCdp();
+        const socket = new WebSocket(version.webSocketDebuggerUrl);
+        await waitForSocketOpen(socket);
+        const cdp = new CdpConnection(socket);
+        cdp.onEvent = (message) => this.handleBrowserEvent(message);
+        this.browserCdp = cdp;
+        this.browserCdpSocket = socket;
+        socket.on('close', () => {
+            if (this.browserCdpSocket === socket) {
+                this.browserCdp = null;
+                this.browserCdpSocket = null;
+            }
         });
+        // Emits Target.targetCreated for every existing target, then keeps us posted
+        // on creation/url/title changes and destruction.
+        await cdp.send('Target.setDiscoverTargets', { discover: true });
+    }
+    async ensureActiveTab() {
+        await this.connectBrowserCdp();
+        // Discovery events normally populate `tabs`; if they haven't landed yet (or
+        // none exist), fall back to the HTTP target list, then create one.
+        if (this.tabs.size === 0) {
+            const targets = await fetchJson(`http://127.0.0.1:${this.port}/json/list`)
+                .catch(() => []);
+            for (const target of targets) {
+                if (target.type === 'page' && !target.url.startsWith('devtools://')) {
+                    this.tabs.set(target.id, { id: target.id, url: target.url, title: target.title ?? '' });
+                }
+            }
+        }
+        if (this.tabs.size === 0) {
+            const created = await this.browserCdp?.send('Target.createTarget', {
+                url: 'about:blank',
+            });
+            const targetId = created?.targetId;
+            if (!targetId) {
+                throw new Error('Failed to open a browser tab');
+            }
+            this.tabs.set(targetId, { id: targetId, url: '', title: '' });
+            await this.setActiveTab(targetId);
+            this.ready = true;
+            return;
+        }
+        if (!this.activeTargetId || !this.tabs.has(this.activeTargetId)) {
+            const first = this.tabs.keys().next().value;
+            await this.setActiveTab(first);
+        }
+        else if (!this.activeCdp || !this.activeCdpSocket || !isOpen(this.activeCdpSocket)) {
+            await this.connectActiveCdp(this.activeTargetId);
+        }
+        this.ready = true;
+    }
+    async ensureActiveCdp() {
+        if (this.activeCdp && this.activeCdpSocket && isOpen(this.activeCdpSocket)) {
+            return;
+        }
+        if (this.activeConnecting) {
+            return this.activeConnecting;
+        }
+        this.activeConnecting = (async () => {
+            if (!this.activeTargetId || !this.tabs.has(this.activeTargetId)) {
+                await this.ensureActiveTab();
+            }
+            else {
+                await this.connectActiveCdp(this.activeTargetId);
+            }
+        })();
+        try {
+            await this.activeConnecting;
+        }
+        finally {
+            this.activeConnecting = null;
+        }
+    }
+    async setActiveTab(targetId) {
+        this.activeGeneration += 1;
+        const generation = this.activeGeneration;
+        this.activeTargetId = targetId;
+        this.clearActiveFrame();
+        // Drop the stale page from every client while the new tab's first frame is
+        // still in flight.
+        this.broadcast({ type: 'clear' });
+        try {
+            await this.connectActiveCdp(targetId, generation);
+        }
+        catch (error) {
+            if (generation === this.activeGeneration) {
+                this.lastError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        await this.broadcastStatus();
+    }
+    async connectActiveCdp(targetId, generation = this.activeGeneration) {
+        if (!this.port) {
+            throw new Error('Browser is not running');
+        }
+        this.disconnectActiveCdp();
+        const socket = new WebSocket(`ws://127.0.0.1:${this.port}/devtools/page/${targetId}`);
+        try {
+            await waitForSocketOpen(socket);
+        }
+        catch (error) {
+            try {
+                socket.close();
+            }
+            catch {
+                // ignore
+            }
+            throw error;
+        }
+        // A newer switch started while we were connecting — discard this one.
+        if (generation !== this.activeGeneration) {
+            try {
+                socket.close();
+            }
+            catch {
+                // ignore
+            }
+            return;
+        }
         const cdp = new CdpConnection(socket);
-        cdp.onEvent = (message) => this.handleCdpEvent(message);
-        this.cdp = cdp;
-        this.cdpSocket = socket;
+        cdp.onEvent = (message) => this.handleActiveEvent(message);
+        this.activeCdp = cdp;
+        this.activeCdpSocket = socket;
         this.screencastStarted = false;
-        this.pageUrl = target.url || this.pageUrl;
-        this.pageTitle = target.title || this.pageTitle;
         socket.on('close', () => {
-            if (this.cdp === cdp) {
-                this.cdp = null;
-                this.cdpSocket = null;
+            if (this.activeCdpSocket === socket) {
+                this.activeCdp = null;
+                this.activeCdpSocket = null;
                 this.screencastStarted = false;
             }
         });
         await cdp.send('Page.enable');
         await cdp.send('Runtime.enable');
+        await this.applyAntiDetection(cdp);
+        if (generation !== this.activeGeneration) {
+            this.disconnectActiveCdp();
+            return;
+        }
         await this.applyViewport();
+        if (this.clients.size > 0) {
+            await this.startScreencast();
+        }
     }
-    async getOrCreatePageTarget() {
-        if (!this.port) {
-            throw new Error('Browser is not running');
+    /**
+     * ヘッドレス Chrome がボット判定（Cloudflare の Managed Challenge / Turnstile 等）で
+     * 誤検知されるのを減らす。完全な突破は保証できないが、代表的な自動化シグナルを消す:
+     *  - UA から "HeadlessChrome" を除去（実バージョンに一致させる）
+     *  - navigator.webdriver / languages / chrome / plugins / WebGL ベンダを通常ブラウザ相当に
+     * 偽装スクリプトは addScriptToEvaluateOnNewDocument で「以後の」ページ生成時に毎回適用される。
+     */
+    async applyAntiDetection(cdp) {
+        try {
+            // 実際のブラウザ版に一致した UA を使う（バージョン不一致自体が検知シグナルになるため）。
+            // ページセッションでは Browser.* が使えないことがあるので /json/version を優先。
+            let userAgent = '';
+            try {
+                const info = await fetchJson(`http://127.0.0.1:${this.port}/json/version`);
+                userAgent = (info['User-Agent'] || '').replace(/HeadlessChrome/gi, 'Chrome');
+            }
+            catch {
+                // フォールバック: ページの navigator.userAgent を取得して整形。
+                const r = await cdp.send('Runtime.evaluate', {
+                    expression: 'navigator.userAgent',
+                    returnByValue: true,
+                });
+                userAgent = String(r.result?.value ?? '').replace(/HeadlessChrome/gi, 'Chrome');
+            }
+            const major = (userAgent.match(/Chrome\/(\d+)/) || [])[1] || '120';
+            if (userAgent) {
+                await cdp.send('Emulation.setUserAgentOverride', {
+                    userAgent,
+                    acceptLanguage: 'ja-JP,ja;q=0.9,en-US;q=0.8,en;q=0.7',
+                    platform: 'Linux x86_64',
+                    userAgentMetadata: {
+                        brands: [
+                            { brand: 'Not_A Brand', version: '24' },
+                            { brand: 'Chromium', version: major },
+                            { brand: 'Google Chrome', version: major },
+                        ],
+                        fullVersion: (userAgent.match(/Chrome\/([\d.]+)/) || [])[1] || `${major}.0.0.0`,
+                        platform: 'Linux',
+                        platformVersion: '',
+                        architecture: 'x86',
+                        model: '',
+                        mobile: false,
+                    },
+                });
+            }
+            const stealthSource = `
+        Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+        if (!window.chrome) { window.chrome = { runtime: {} }; }
+        Object.defineProperty(navigator, 'languages', { get: () => ['ja-JP', 'ja', 'en-US', 'en'] });
+        Object.defineProperty(navigator, 'plugins', { get: () => [1, 2, 3, 4, 5] });
+        try {
+          const _q = window.navigator.permissions && window.navigator.permissions.query;
+          if (_q) {
+            window.navigator.permissions.query = (p) =>
+              p && p.name === 'notifications'
+                ? Promise.resolve({ state: Notification.permission })
+                : _q(p);
+          }
+        } catch (e) { /* ignore */ }
+        try {
+          const getParam = WebGLRenderingContext.prototype.getParameter;
+          WebGLRenderingContext.prototype.getParameter = function (p) {
+            if (p === 37445) return 'Intel Inc.';
+            if (p === 37446) return 'Intel Iris OpenGL Engine';
+            return getParam.call(this, p);
+          };
+        } catch (e) { /* ignore */ }
+      `;
+            await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: stealthSource });
         }
-        const baseUrl = `http://127.0.0.1:${this.port}`;
-        const targets = await fetchJson(`${baseUrl}/json/list`);
-        const page = targets.find((target) => target.type === 'page' && target.webSocketDebuggerUrl);
-        if (page) {
-            return page;
+        catch {
+            // 反検知設定は best-effort。失敗してもブラウジング自体は続行する。
         }
-        return fetchJson(`${baseUrl}/json/new?about:blank`, { method: 'PUT' });
     }
     async startScreencast() {
-        if (this.screencastStarted || !this.cdp) {
+        if (this.screencastStarted || !this.activeCdp) {
             return;
         }
         await this.applyViewport();
-        await this.cdp.send('Page.startScreencast', {
+        await this.activeCdp.send('Page.startScreencast', {
             format: 'jpeg',
             quality: 72,
             maxWidth: this.viewport.width,
@@ -562,11 +846,11 @@ export class AgentBrowserService {
         this.screencastStarted = true;
     }
     async stopScreencast() {
-        if (!this.screencastStarted || !this.cdp) {
+        if (!this.screencastStarted || !this.activeCdp) {
             return;
         }
         try {
-            await this.cdp.send('Page.stopScreencast');
+            await this.activeCdp.send('Page.stopScreencast');
         }
         catch {
             // ignore
@@ -576,10 +860,10 @@ export class AgentBrowserService {
         }
     }
     async applyViewport() {
-        if (!this.cdp) {
+        if (!this.activeCdp) {
             return;
         }
-        await this.cdp.send('Emulation.setDeviceMetricsOverride', {
+        await this.activeCdp.send('Emulation.setDeviceMetricsOverride', {
             width: this.viewport.width,
             height: this.viewport.height,
             deviceScaleFactor: 1,
@@ -597,12 +881,12 @@ export class AgentBrowserService {
             return;
         }
         this.viewport = next;
-        if (!this.cdp) {
+        if (!this.activeCdp) {
             return;
         }
         await this.applyViewport();
         if (this.screencastStarted) {
-            await this.cdp.send('Page.stopScreencast').catch(() => undefined);
+            await this.activeCdp.send('Page.stopScreencast').catch(() => undefined);
             this.screencastStarted = false;
             await this.startScreencast();
         }
@@ -628,7 +912,19 @@ export class AgentBrowserService {
                 return;
             }
             await this.start();
-            await this.ensureCdp();
+            if (message.type === 'new-tab') {
+                await this.newTab(message.url);
+                return;
+            }
+            if (message.type === 'close-tab') {
+                await this.closeTab(message.targetId);
+                return;
+            }
+            if (message.type === 'activate-tab') {
+                await this.activateTab(message.targetId);
+                return;
+            }
+            await this.ensureActiveCdp();
             if (message.type === 'navigate') {
                 await this.navigate(message.url);
                 return;
@@ -649,9 +945,9 @@ export class AgentBrowserService {
         }
     }
     async dispatchMouse(message) {
-        if (!this.cdp)
+        if (!this.activeCdp)
             return;
-        await this.cdp.send('Input.dispatchMouseEvent', {
+        await this.activeCdp.send('Input.dispatchMouseEvent', {
             type: message.eventType,
             x: coercePositiveInt(message.x, 0, 0, MAX_VIEWPORT.width),
             y: coercePositiveInt(message.y, 0, 0, MAX_VIEWPORT.height),
@@ -663,10 +959,10 @@ export class AgentBrowserService {
         });
     }
     async dispatchKey(message) {
-        if (!this.cdp)
+        if (!this.activeCdp)
             return;
         const windowsVirtualKeyCode = getWindowsVirtualKeyCode(message.key);
-        await this.cdp.send('Input.dispatchKeyEvent', {
+        await this.activeCdp.send('Input.dispatchKeyEvent', {
             type: message.eventType,
             key: message.key,
             code: message.code,
@@ -677,13 +973,14 @@ export class AgentBrowserService {
             modifiers: message.modifiers ?? 0,
         });
     }
-    handleCdpEvent(message) {
+    // Events from the active tab's page CDP connection.
+    handleActiveEvent(message) {
         if (message.method === 'Page.screencastFrame') {
             const params = message.params;
             const data = typeof params.data === 'string' ? params.data : null;
             const sessionId = typeof params.sessionId === 'number' ? params.sessionId : null;
             if (sessionId != null) {
-                void this.cdp?.send('Page.screencastFrameAck', { sessionId }).catch(() => undefined);
+                void this.activeCdp?.send('Page.screencastFrameAck', { sessionId }).catch(() => undefined);
             }
             if (data) {
                 const buffer = Buffer.from(data, 'base64');
@@ -695,32 +992,104 @@ export class AgentBrowserService {
         if (message.method === 'Page.frameNavigated') {
             const frame = (message.params?.frame ?? null);
             if (frame && !frame.parentId && frame.url) {
-                this.pageUrl = frame.url;
-                void this.refreshPageInfo().finally(() => {
+                const tab = this.activeTargetId ? this.tabs.get(this.activeTargetId) : null;
+                if (tab) {
+                    tab.url = frame.url;
+                }
+                void this.refreshActivePageInfo().finally(() => {
                     void this.broadcastStatus();
                 });
             }
             return;
         }
         if (message.method === 'Page.loadEventFired') {
-            void this.refreshPageInfo().finally(() => {
+            void this.refreshActivePageInfo().finally(() => {
                 void this.broadcastStatus();
             });
         }
     }
-    async refreshPageInfo() {
-        if (!this.cdp) {
+    // Events from the browser-level CDP connection: tab lifecycle.
+    handleBrowserEvent(message) {
+        const method = message.method;
+        if (method === 'Target.targetCreated' || method === 'Target.targetInfoChanged') {
+            const info = message.params?.targetInfo;
+            if (info) {
+                this.upsertTab(info);
+            }
+            return;
+        }
+        if (method === 'Target.targetDestroyed') {
+            const targetId = typeof message.params?.targetId === 'string' ? message.params.targetId : null;
+            if (targetId) {
+                this.removeTab(targetId);
+            }
+        }
+    }
+    upsertTab(info) {
+        if (info.type !== 'page') {
+            return;
+        }
+        const url = info.url ?? '';
+        if (url.startsWith('devtools://')) {
+            return;
+        }
+        const prev = this.tabs.get(info.targetId);
+        const isNew = !prev;
+        const title = info.title ?? '';
+        const changed = !prev || prev.url !== url || prev.title !== title;
+        this.tabs.set(info.targetId, { id: info.targetId, url, title });
+        if (isNew && this.ready && this.activeTargetId !== info.targetId) {
+            // A page spawned a new tab/popup (target=_blank, window.open) — follow it
+            // the way a normal browser does.
+            void this.setActiveTab(info.targetId);
+            return;
+        }
+        if (changed) {
+            void this.broadcastStatus();
+        }
+    }
+    removeTab(targetId) {
+        if (!this.tabs.has(targetId)) {
+            return;
+        }
+        const ids = [...this.tabs.keys()];
+        const idx = ids.indexOf(targetId);
+        this.tabs.delete(targetId);
+        if (this.activeTargetId === targetId) {
+            this.activeTargetId = null;
+            this.disconnectActiveCdp();
+            this.clearActiveFrame();
+            this.broadcast({ type: 'clear' });
+            const nextId = ids[idx + 1] ?? ids[idx - 1] ?? null;
+            if (nextId && this.tabs.has(nextId)) {
+                void this.setActiveTab(nextId);
+                return; // setActiveTab broadcasts status
+            }
+        }
+        void this.broadcastStatus();
+    }
+    clearActiveFrame() {
+        this.lastFrameBuffer = null;
+        this.pendingFrames.clear();
+    }
+    async refreshActivePageInfo() {
+        if (!this.activeCdp || !this.activeTargetId) {
             return;
         }
         try {
-            const result = await this.cdp.send('Runtime.evaluate', {
+            const result = await this.activeCdp.send('Runtime.evaluate', {
                 expression: '({ title: document.title, url: location.href })',
                 returnByValue: true,
             });
             const value = result.result?.value;
-            if (value) {
-                this.pageTitle = typeof value.title === 'string' ? value.title : this.pageTitle;
-                this.pageUrl = typeof value.url === 'string' ? value.url : this.pageUrl;
+            const tab = this.tabs.get(this.activeTargetId);
+            if (value && tab) {
+                if (typeof value.title === 'string') {
+                    tab.title = value.title;
+                }
+                if (typeof value.url === 'string') {
+                    tab.url = value.url;
+                }
             }
         }
         catch {
@@ -841,11 +1210,11 @@ export class AgentBrowserService {
             }
         }
     }
-    closeCdp() {
-        const cdp = this.cdp;
-        const socket = this.cdpSocket;
-        this.cdp = null;
-        this.cdpSocket = null;
+    disconnectActiveCdp() {
+        const cdp = this.activeCdp;
+        const socket = this.activeCdpSocket;
+        this.activeCdp = null;
+        this.activeCdpSocket = null;
         this.screencastStarted = false;
         if (cdp) {
             cdp.close();
@@ -859,6 +1228,23 @@ export class AgentBrowserService {
             }
         }
     }
+    closeBrowserCdp() {
+        const cdp = this.browserCdp;
+        const socket = this.browserCdpSocket;
+        this.browserCdp = null;
+        this.browserCdpSocket = null;
+        if (cdp) {
+            cdp.close();
+        }
+        else if (socket) {
+            try {
+                socket.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
     openLogStream() {
         this.closeLogStream();
         const logPath = path.join(this.outputDir, 'deckide-browser.log');