minimal-agent 0.10.0 → 0.12.0

package/src/web/browserBridge.js

@@ -2,16 +2,12 @@ import { randomUUID } from 'node:crypto';
 import { rm } from 'node:fs/promises';
 import { configService } from '../config/configService.js';
 import { resolveAgentBrowserPath } from '../tools/webbrowser/agentBrowserPath.js';
-import { browserProfilePath, sessionArgs, spawnRunner } from '../tools/webbrowser/browser.js';
+import { browserProfilePath, normalizeUrl, sessionArgs, spawnRunner } from '../tools/webbrowser/browser.js';
 import { ensureDaemon, stopDaemon } from '../tools/webbrowser/browserDaemon.js';
 import { browserService } from '../tools/webbrowser/browserService.js';
+import { browserRunRegistry } from '../tools/webbrowser/browserRunRegistry.js';
+import { createConversationTab, ensureConversationTab, listBrowserTabs, } from '../tools/webbrowser/browserTabs.js';
 import { getBrowserStream, } from '../tools/webbrowser/browserStream.js';
-function normalizeUrl(value) {
-    const input = value.trim();
-    if (/^[a-z][a-z0-9+.-]*:/i.test(input))
-        return input;
-    return `https://${input}`;
-}
 function requireAllowedDeveloperOrigin(url, allowedOrigins) {
     let origin;
     try {
@@ -89,6 +85,24 @@ function mapStreamEvent(event) {
                     return { id: String(item.tabId ?? item.id ?? ''), url: String(item.url ?? ''), title: typeof item.title === 'string' ? item.title : undefined, active: Boolean(item.active), favicon: typeof item.favicon === 'string' ? item.favicon : undefined };
                 }) };
         }
+        case 'agent_candidates': {
+            const list = Array.isArray(event.candidates) ? event.candidates : [];
+            return {
+                t: 'browser/agent/candidates',
+                candidates: list.map((item) => {
+                    const c = item;
+                    return { ref: String(c.ref ?? ''), line: String(c.line ?? '') };
+                }),
+                ...(typeof event.selector === 'string' ? { selector: event.selector } : {}),
+            };
+        }
+        case 'agent_outcome': return {
+            t: 'browser/agent/outcome',
+            action: String(event.action ?? ''),
+            effect: event.effect === 'unknown' ? 'unknown' : 'unchanged',
+            ...(typeof event.selector === 'string' ? { selector: event.selector } : {}),
+            ...(typeof event.maskedLines === 'number' ? { maskedLines: event.maskedLines } : {}),
+        };
         case 'url': return { t: 'browser/url', url: String(event.url ?? ''), tabId: typeof event.tabId === 'string' ? event.tabId : undefined };
         case 'title': return { t: 'browser/title', title: String(event.title ?? ''), tabId: typeof event.tabId === 'string' ? event.tabId : undefined };
         case 'navigation': return { t: 'browser/navigation', url: String(event.url ?? ''), state: (event.state === 'start' || event.state === 'commit' || event.state === 'domcontentloaded') ? event.state : 'load' };
@@ -99,37 +113,151 @@ function mapStreamEvent(event) {
         case 'mode': return { t: 'browser/mode', mode: event.mode };
         case 'marked_elements': return { t: 'browser/marked/elements', elements: (event.elements ?? []) };
         case 'agent_acting': return { t: 'browser/agent/acting', acting: Boolean(event.acting), action: typeof event.action === 'string' ? event.action : undefined, target: typeof event.target === 'string' ? event.target : undefined };
+        case 'agent_pointer': return { t: 'browser/agent/pointer', x: Number(event.x ?? 0), y: Number(event.y ?? 0), visible: Boolean(event.visible), action: (typeof event.action === 'string' ? event.action : undefined), elementRef: typeof event.elementRef === 'string' ? event.elementRef : undefined };
         case 'control_state': return { t: 'browser/control/changed', state: event.state };
         default: return null;
     }
 }
+function mapHumanInterventionEvent(event) {
+    if (event.type === 'started') {
+        return {
+            t: 'human-intervention/started',
+            intervention: event.intervention,
+        };
+    }
+    return {
+        t: 'human-intervention/resolved',
+        resolution: event.resolution,
+    };
+}
+export function createPointerRouteState() {
+    return { dragging: false, dragButton: 'left', pendingPress: null, lastDragMoveAt: 0 };
+}
+/**
+ * 纯函数：按持久路由状态决定一个用户鼠标帧怎么走。就地更新 state，返回待下发的快通路帧
+ * 与待入队的命令通路 argv。抽成纯函数便于单测拖拽判定/单击缓冲/节流，不碰真实 spawn。
+ */
+export function routeUserMouse(state, frame, now, dragMoveThrottleMs = 40) {
+    const plan = { stream: [], commands: [] };
+    const eventType = String(frame.eventType ?? '');
+    const x = Math.round(Number(frame.x ?? 0));
+    const y = Math.round(Number(frame.y ?? 0));
+    const fast = (f = frame) => plan.stream.push({ type: 'input_mouse', ...f, t: undefined });
+    if (eventType === 'mousePressed') {
+        // 缓冲按下：还不知道是单击还是拖拽——先不派发，等下一帧揭晓。
+        state.pendingPress = frame;
+        state.dragging = false;
+        return plan;
+    }
+    if (eventType === 'mouseMoved') {
+        if (state.pendingPress && !state.dragging) {
+            // 按下后首次移动 = 拖拽：在命令通路上建立「按住」状态（mouse down 令 daemon 记住 buttons）。
+            const px = Math.round(Number(state.pendingPress.x ?? x));
+            const py = Math.round(Number(state.pendingPress.y ?? y));
+            state.dragButton = String(state.pendingPress.button ?? 'left') || 'left';
+            state.dragging = true;
+            state.pendingPress = null;
+            state.lastDragMoveAt = now;
+            plan.commands.push(['move', String(px), String(py)], ['down', state.dragButton], ['move', String(x), String(y)]);
+            return plan;
+        }
+        if (state.dragging) {
+            // 拖拽中间帧：节流下发命令通路（spawn 昂贵），不再走 input_mouse 避免双通路重复派发。
+            if (now - state.lastDragMoveAt >= dragMoveThrottleMs) {
+                state.lastDragMoveAt = now;
+                plan.commands.push(['move', String(x), String(y)]);
+            }
+            return plan;
+        }
+        fast(); // 普通悬停 → 快通路
+        return plan;
+    }
+    if (eventType === 'mouseReleased') {
+        if (state.dragging) {
+            // 收尾：先补末帧到真实抬起坐标（节流可能丢了它），再抬起清 buttons。
+            plan.commands.push(['move', String(x), String(y)], ['up', state.dragButton]);
+            state.dragging = false;
+            return plan;
+        }
+        if (state.pendingPress) {
+            // 纯单击（按下后无移动）：快通路补发缓冲的按下 + 本次抬起，语义仍是一次点击。
+            fast(state.pendingPress);
+            fast();
+            state.pendingPress = null;
+            return plan;
+        }
+        fast();
+        return plan;
+    }
+    // mouseWheel / 其它鼠标事件 → 快通路（不涉及按住拖拽）。
+    fast();
+    return plan;
+}
 export function createBrowserBridge(send, sessionName = 'minimal-agent') {
     let disposed = false;
     let activeTabId = '';
     let pageRevision = randomUUID();
+    let runContext = null;
     const stream = getBrowserStream(sessionName);
     const unsubscribe = stream.subscribe((event) => {
         if (disposed)
             return;
+        if (event.type === 'control_state') {
+            const control = event.state;
+            if (control && control.status !== 'idle' && control.conversationKey) {
+                runContext = browserRunRegistry.find(control.conversationKey, control.runId)
+                    ?? browserRunRegistry.ensure({
+                        conversationKey: control.conversationKey,
+                        runId: control.runId,
+                        profileId: 'default',
+                        grants: ['observe', 'interact'],
+                    });
+            }
+        }
+        if (event.type === 'human_intervention_started' || event.type === 'human_intervention_resolved') {
+            const interventionEvent = event.event;
+            if (interventionEvent)
+                send(mapHumanInterventionEvent(interventionEvent));
+        }
         if (event.type === 'url' || event.type === 'navigation')
             pageRevision = randomUUID();
         if (event.type === 'tabs' && Array.isArray(event.tabs)) {
             const active = event.tabs.find((tab) => Boolean(tab.active));
             activeTabId = String(active?.tabId ?? active?.id ?? activeTabId);
         }
-        const mapped = mapStreamEvent(event);
+        let mapped = mapStreamEvent(event);
+        const activeOwner = activeTabId ? browserRunRegistry.ownerOf(activeTabId) : undefined;
+        if (runContext && activeTabId && activeOwner !== runContext.conversationKey
+            && mapped && ['browser/frame', 'browser/url', 'browser/title', 'browser/navigation'].includes(mapped.t)) {
+            return;
+        }
+        if (runContext && mapped?.t === 'browser/tabs') {
+            const claimed = new Set(browserRunRegistry.claimedTabs(runContext.conversationKey).map(String));
+            mapped = { ...mapped, tabs: mapped.tabs.filter((tab) => claimed.has(tab.id)) };
+        }
         if (mapped?.t === 'browser/frame')
-            send({ ...mapped, tabId: activeTabId || mapped.tabId, pageRevision });
+            send({
+                ...mapped,
+                tabId: activeTabId || mapped.tabId,
+                pageRevision,
+                ...(runContext ? { conversationKey: runContext.conversationKey, runId: runContext.runId } : {}),
+            });
         else if (mapped)
             send(mapped);
         if (event.type === 'control_state') {
             const state = event.state;
+            // 控制权移交给用户（手动接管或验证挑战）时淡出 AI 指针，避免“谁在操作”的混淆。
+            if (state?.owner === 'user')
+                stream.setAgentPointer({ x: 0, y: 0, visible: false });
             if (state?.status === 'waiting_human' && state.reason !== 'manual') {
                 const summary = state.reason === 'captcha' ? '页面需要人工完成安全验证'
                     : state.reason === 'otp' ? '页面需要人工输入一次性验证码'
-                        : state.reason === 'login' ? '页面需要人工登录'
-                            : state.reason === 'permission' ? '页面需要人工确认权限'
-                                : '网站已暂停或拦截当前访问';
+                        : state.reason === 'password' ? '页面需要人工输入密码'
+                            : state.reason === 'qr_login' ? '页面需要人工扫码登录'
+                                : state.reason === 'login' ? '页面需要人工登录'
+                                    : state.reason === 'permission' ? '页面需要人工确认权限'
+                                        : state.reason === 'security_warning' ? '页面需要人工处理安全警告'
+                                            : '网站已暂停或拦截当前访问';
                 send({
                     t: 'browser/challenge/detected',
                     reason: state.reason,
@@ -151,6 +279,63 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
             throw new Error((result.stderr || result.stdout || `exit ${result.code}`).trim());
         return result.stdout.trim();
     };
+    const requireContext = () => {
+        if (!runContext)
+            throw new Error('浏览器尚未绑定当前会话，请重新打开工作台');
+        return runContext;
+    };
+    const claimContextTab = async () => {
+        const context = requireContext();
+        const bin = await resolveAgentBrowserPath();
+        if (!bin)
+            throw new Error('未找到内置 agent-browser');
+        await ensureDaemon(sessionName);
+        const tabId = await ensureConversationTab({
+            context,
+            sessionName,
+            bin,
+            globals: sessionArgs(sessionName),
+            runner: spawnRunner,
+        });
+        activeTabId = tabId;
+        return tabId;
+    };
+    const createContextTab = async (url = 'about:blank') => {
+        const context = requireContext();
+        const bin = await resolveAgentBrowserPath();
+        if (!bin)
+            throw new Error('未找到内置 agent-browser');
+        await ensureDaemon(sessionName);
+        const tabId = await createConversationTab({
+            context,
+            sessionName,
+            bin,
+            globals: sessionArgs(sessionName),
+            runner: spawnRunner,
+        }, url);
+        activeTabId = tabId;
+        return tabId;
+    };
+    const runOnContextTab = async (args) => {
+        const tabId = await claimContextTab();
+        const bin = await resolveAgentBrowserPath();
+        if (!bin)
+            throw new Error('未找到内置 agent-browser');
+        const output = await browserService.exclusive({
+            sessionName,
+            bin,
+            runner: spawnRunner,
+        }, async (execute) => {
+            const switched = await execute([...sessionArgs(sessionName), 'tab', tabId]);
+            if (switched.code !== 0)
+                return switched;
+            return execute([...sessionArgs(sessionName), ...args]);
+        });
+        if (output.code !== 0) {
+            throw new Error((output.stderr || output.stdout || `exit ${output.code}`).trim());
+        }
+        return output.stdout.trim();
+    };
     const ensureStarted = async () => {
         const config = await configService.browser();
         if (!config.enabled)
@@ -159,29 +344,41 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
         await stream.connect();
         return info;
     };
+    // 改视口后重连查看者，让下一帧按新尺寸编码（screencast 尺寸绑定在查看者连接时刻）。
+    // 注意：标签切换/新建/关闭/导航不需要在这里重连——agent-browser daemon 在这些命令后会自己
+    // set_cdp_session_id + notify、让 screencast 重定向到新活动标签（见 actions.rs / stream/cdp_loop.rs）。
+    // 真正的坑是「链接点击开的新标签」不在 daemon 的同步清单里，那条路由前端「活动标签变化 → 补发 tab/switch」兜住（useBrowser.ts）。
+    const reconnectViewer = async () => {
+        if (stream.isConnected()) {
+            stream.disconnect();
+            await stream.connect();
+        }
+    };
     const applyViewport = async (widthValue, heightValue) => {
         const width = Math.max(320, Math.round(Number(widthValue)));
         const height = Math.max(240, Math.round(Number(heightValue)));
         if (!Number.isFinite(width) || !Number.isFinite(height))
             throw new Error('无效的浏览器视口尺寸');
-        await run(['set', 'viewport', String(width), String(height)]);
-        // agent-browser starts its CDP screencast with the dimensions that were
-        // active when the viewer connected. Reconnect only the viewer so the next
-        // frame is encoded at the new viewport without touching tabs or profile.
-        if (stream.isConnected()) {
-            stream.disconnect();
-            await stream.connect();
-        }
+        await runOnContextTab(['set', 'viewport', String(width), String(height)]);
+        await reconnectViewer();
     };
     const pick = async (x, y) => {
-        const value = parseJsonOutput(await run(['eval', pickScript(x, y)]));
+        const value = parseJsonOutput(await runOnContextTab(['eval', pickScript(x, y)]));
         if (!value || typeof value !== 'object')
             return null;
         return value;
     };
     stream.setPicker(pick);
+    // 用户指针输入的双通路路由状态 + 命令通路串行队列（见 routeUserMouse 头注）。
+    const pointerRoute = createPointerRouteState();
+    let mouseCmdChain = Promise.resolve();
+    const enqueueMouseCmd = (args) => {
+        // 串行保序：逐条 await 上一条再跑下一条；失败吞掉（拖拽单帧丢失不该中断整段手势）。
+        mouseCmdChain = mouseCmdChain.then(() => runOnContextTab(['mouse', ...args])).catch(() => { });
+    };
     const result = (frame, ok, data, error) => send({
         t: 'browser/result', requestId: frame.requestId, action: frame.t, ok,
+        ...(runContext ? { conversationKey: runContext.conversationKey, runId: runContext.runId, tabId: activeTabId || undefined } : {}),
         ...(typeof data === 'string' ? { content: data } : data === undefined ? {} : { data }),
         ...(error ? { error } : {}),
     });
@@ -191,12 +388,42 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
                 return;
             try {
                 switch (frame.t) {
+                    case 'browser/context/set': {
+                        const conversationKey = String(frame.conversationKey ?? '').trim();
+                        if (!conversationKey)
+                            throw new Error('缺少浏览器会话标识');
+                        runContext = browserRunRegistry.ensure({
+                            conversationKey,
+                            runId: typeof frame.runId === 'string' ? frame.runId : 'workbench',
+                            profileId: 'default',
+                            grants: ['observe', 'interact'],
+                        });
+                        const tabId = await claimContextTab();
+                        send({
+                            t: 'browser/context/changed',
+                            requestId: frame.requestId,
+                            conversationKey: runContext.conversationKey,
+                            runId: runContext.runId,
+                            tabId,
+                        });
+                        return;
+                    }
                     case 'browser/start': {
+                        requireContext();
                         const info = await ensureStarted();
+                        await claimContextTab();
                         const viewport = frame.viewport;
                         if (viewport?.width && viewport?.height)
                             await applyViewport(viewport.width, viewport.height);
-                        send({ t: 'browser/started', requestId: frame.requestId, streamPort: info.streamPort, pid: info.pid, sessionId: sessionName });
+                        send({
+                            t: 'browser/started',
+                            requestId: frame.requestId,
+                            streamPort: info.streamPort,
+                            pid: info.pid,
+                            sessionId: sessionName,
+                            conversationKey: runContext?.conversationKey,
+                            runId: runContext?.runId,
+                        });
                         result(frame, true, info);
                         return;
                     }
@@ -217,10 +444,15 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
                         result(frame, true);
                         return;
                     case 'browser/control/get':
+                        requireContext();
                         send({ t: 'browser/control/changed', state: stream.getControlState() });
                         return;
                     case 'browser/control/takeover':
-                        stream.requestHuman('manual');
+                        stream.requestHuman('manual', {
+                            runId: runContext?.runId,
+                            conversationKey: runContext?.conversationKey,
+                            ownerId: 'local-owner',
+                        });
                         result(frame, true, stream.getControlState());
                         return;
                     case 'browser/control/resume': {
@@ -228,53 +460,119 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
                         result(frame, ok, stream.getControlState(), ok ? undefined : '浏览器接管请求已失效');
                         return;
                     }
-                    case 'browser/control/stop':
-                        stream.stopControl(typeof frame.resumeToken === 'string' ? frame.resumeToken : undefined);
-                        result(frame, true, stream.getControlState());
+                    case 'browser/control/stop': {
+                        const ok = stream.stopControl(typeof frame.resumeToken === 'string' ? frame.resumeToken : undefined);
+                        result(frame, ok, stream.getControlState(), ok ? undefined : '浏览器接管请求已失效');
+                        return;
+                    }
+                    case 'human-intervention/resume': {
+                        const ok = stream.resumeIntervention({
+                            id: String(frame.interventionId ?? ''),
+                            resumeToken: String(frame.resumeToken ?? ''),
+                            ownerId: String(frame.ownerId ?? ''),
+                            conversationKey: String(frame.conversationKey ?? ''),
+                            runId: String(frame.runId ?? ''),
+                        });
+                        result(frame, ok, stream.getControlState(), ok ? undefined : '浏览器人工介入请求已失效');
                         return;
+                    }
+                    case 'human-intervention/cancel': {
+                        const ok = stream.cancelIntervention({
+                            id: String(frame.interventionId ?? ''),
+                            resumeToken: String(frame.resumeToken ?? ''),
+                            ownerId: String(frame.ownerId ?? ''),
+                            conversationKey: String(frame.conversationKey ?? ''),
+                            runId: String(frame.runId ?? ''),
+                        });
+                        result(frame, ok, stream.getControlState(), ok ? undefined : '浏览器人工介入请求已失效');
+                        return;
+                    }
                     case 'browser/user/input': {
+                        requireContext();
+                        await claimContextTab();
                         const type = String(frame.eventType ?? '');
-                        if (type.startsWith('mouse'))
-                            stream.send({ type: 'input_mouse', ...frame, t: undefined });
-                        else
+                        if (!type.startsWith('mouse')) {
                             stream.send({ type: 'input_keyboard', ...frame, t: undefined });
+                            return;
+                        }
+                        // 鼠标：hover/单击/滚轮走快通路 input_mouse；拖拽手势改走 daemon 带 buttons 的命令通路。
+                        const plan = routeUserMouse(pointerRoute, frame, Date.now());
+                        for (const f of plan.stream)
+                            stream.send(f);
+                        for (const args of plan.commands)
+                            enqueueMouseCmd(args);
                         return;
                     }
                     case 'browser/navigate': {
+                        requireContext();
                         await ensureStarted();
                         const url = normalizeUrl(String(frame.url ?? ''));
-                        await run(frame.newTab ? ['tab', 'new', url] : ['open', url]);
+                        if (frame.newTab)
+                            await createContextTab(url);
+                        else {
+                            await claimContextTab();
+                            await run(['open', url]);
+                        }
                         stream.setCurrentUrl(url);
                         result(frame, true);
                         return;
                     }
                     case 'browser/back':
-                        await run(['back']);
+                        await runOnContextTab(['back']);
                         result(frame, true);
                         return;
                     case 'browser/forward':
-                        await run(['forward']);
+                        await runOnContextTab(['forward']);
                         result(frame, true);
                         return;
                     case 'browser/reload':
-                        await run(['reload']);
+                        await runOnContextTab(['reload']);
                         result(frame, true);
                         return;
-                    case 'browser/tab/new':
-                        await run(frame.url ? ['tab', 'new', normalizeUrl(String(frame.url))] : ['tab', 'new']);
-                        result(frame, true);
+                    case 'browser/tab/new': {
+                        const tabId = await createContextTab(frame.url ? normalizeUrl(String(frame.url)) : 'about:blank');
+                        result(frame, true, { tabId });
                         return;
-                    case 'browser/tab/close':
-                        await run(frame.tabId ? ['tab', 'close', String(frame.tabId)] : ['tab', 'close']);
+                    }
+                    case 'browser/tab/close': {
+                        const context = requireContext();
+                        const tabId = String(frame.tabId ?? context.activeTabId ?? '');
+                        if (!tabId)
+                            throw new Error('无效的标签标识');
+                        browserRunRegistry.assertTab(context, tabId);
+                        await run(['tab', 'close', tabId]);
+                        browserRunRegistry.releaseTab(context.conversationKey, tabId);
+                        activeTabId = context.activeTabId ?? '';
                         result(frame, true);
                         return;
-                    case 'browser/tab/switch':
-                        await run(['tab', 'switch', String(frame.tabId)]);
+                    }
+                    case 'browser/tab/switch': {
+                        const context = requireContext();
+                        const tabId = String(frame.tabId ?? '');
+                        if (!tabId)
+                            throw new Error('无效的标签标识');
+                        browserRunRegistry.assertTab(context, tabId);
+                        await run(['tab', tabId]);
+                        context.activeTabId = tabId;
+                        activeTabId = tabId;
                         result(frame, true);
                         return;
-                    case 'browser/tabs':
-                        result(frame, true, parseJsonOutput(await run(['tab', 'list'])));
+                    }
+                    case 'browser/tabs': {
+                        const context = requireContext();
+                        const bin = await resolveAgentBrowserPath();
+                        if (!bin)
+                            throw new Error('未找到内置 agent-browser');
+                        const tabs = await listBrowserTabs({
+                            sessionName,
+                            bin,
+                            globals: sessionArgs(sessionName),
+                            runner: spawnRunner,
+                        });
+                        const claimed = new Set(browserRunRegistry.claimedTabs(context.conversationKey));
+                        result(frame, true, tabs.filter((tab) => claimed.has(tab.id)));
                         return;
+                    }
                     case 'browser/pick': {
                         const element = await pick(Number(frame.x), Number(frame.y));
                         if (!element) {
@@ -291,7 +589,7 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
                         return;
                     }
                     case 'browser/mark/element': {
-                        const raw = parseJsonOutput(await run(['eval', `(() => { const el=document.querySelector(${JSON.stringify(String(frame.selector))}); if(!el)return null; const r=el.getBoundingClientRect(); return {ref:${JSON.stringify(String(frame.selector))},tag:el.tagName.toLowerCase(),text:String(el.innerText||el.textContent||'').trim().slice(0,1000),boundingBox:{x:r.x,y:r.y,width:r.width,height:r.height}} })()`]));
+                        const raw = parseJsonOutput(await runOnContextTab(['eval', `(() => { const el=document.querySelector(${JSON.stringify(String(frame.selector))}); if(!el)return null; const r=el.getBoundingClientRect(); return {ref:${JSON.stringify(String(frame.selector))},tag:el.tagName.toLowerCase(),text:String(el.innerText||el.textContent||'').trim().slice(0,1000),boundingBox:{x:r.x,y:r.y,width:r.width,height:r.height}} })()`]));
                         if (!raw || typeof raw !== 'object')
                             throw new Error('未找到该元素');
                         stream.markElement({ ...raw, label: typeof frame.label === 'string' ? frame.label : undefined, color: typeof frame.color === 'string' ? frame.color : undefined });
@@ -308,100 +606,100 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
                         result(frame, true);
                         return;
                     case 'browser/dialog/accept':
-                        await run(frame.text ? ['dialog', 'accept', '--text', String(frame.text)] : ['dialog', 'accept']);
+                        await runOnContextTab(frame.text ? ['dialog', 'accept', '--text', String(frame.text)] : ['dialog', 'accept']);
                         result(frame, true);
                         return;
                     case 'browser/dialog/dismiss':
-                        await run(['dialog', 'dismiss']);
+                        await runOnContextTab(['dialog', 'dismiss']);
                         result(frame, true);
                         return;
                     case 'browser/snapshot': {
-                        const tree = await run(['snapshot']);
+                        const tree = await runOnContextTab(['snapshot']);
                         send({ t: 'browser/snapshot', requestId: frame.requestId, tree });
                         return;
                     }
                     case 'browser/getContent': {
-                        const text = await run(['get', 'text', String(frame.selector ?? 'body')]);
+                        const text = await runOnContextTab(['get', 'text', String(frame.selector ?? 'body')]);
                         send({ t: 'browser/content', requestId: frame.requestId, text });
                         return;
                     }
                     case 'browser/click':
-                        await run(['click', String(frame.selector)]);
+                        await runOnContextTab(['click', String(frame.selector)]);
                         result(frame, true);
                         return;
                     case 'browser/fill':
-                        await run(['fill', String(frame.selector), String(frame.value ?? '')]);
+                        await runOnContextTab(['fill', String(frame.selector), String(frame.value ?? '')]);
                         result(frame, true);
                         return;
                     case 'browser/type':
-                        await run(['type', String(frame.selector), String(frame.value ?? '')]);
+                        await runOnContextTab(['type', String(frame.selector), String(frame.value ?? '')]);
                         result(frame, true);
                         return;
                     case 'browser/hover':
-                        await run(['hover', String(frame.selector)]);
+                        await runOnContextTab(['hover', String(frame.selector)]);
                         result(frame, true);
                         return;
                     case 'browser/scroll': {
                         const args = frame.selector ? ['scrollintoview', String(frame.selector)] : ['scroll', String(frame.direction ?? 'down'), String(Math.abs(Number(frame.y ?? 600)))];
-                        await run(args);
+                        await runOnContextTab(args);
                         result(frame, true);
                         return;
                     }
                     case 'browser/select':
-                        await run(['select', String(frame.selector), ...(Array.isArray(frame.value) ? frame.value.map(String) : [String(frame.value ?? '')])]);
+                        await runOnContextTab(['select', String(frame.selector), ...(Array.isArray(frame.value) ? frame.value.map(String) : [String(frame.value ?? '')])]);
                         result(frame, true);
                         return;
                     case 'browser/press':
-                        await run(['press', String(frame.key)]);
+                        await runOnContextTab(['press', String(frame.key)]);
                         result(frame, true);
                         return;
                     case 'browser/wait':
-                        await run(frame.selector ? ['wait', String(frame.selector)] : frame.text ? ['wait', '--text', String(frame.text)] : ['wait', String(frame.ms ?? 500)]);
+                        await runOnContextTab(frame.selector ? ['wait', String(frame.selector)] : frame.text ? ['wait', '--text', String(frame.text)] : ['wait', String(frame.ms ?? 500)]);
                         result(frame, true);
                         return;
                     case 'browser/eval':
-                        result(frame, true, parseJsonOutput(await run(['eval', String(frame.js ?? '')])));
+                        result(frame, true, parseJsonOutput(await runOnContextTab(['eval', String(frame.js ?? '')])));
                         return;
                     case 'browser/upload':
-                        await run(['upload', String(frame.selector), ...(Array.isArray(frame.files) ? frame.files.map(String) : [])]);
+                        await runOnContextTab(['upload', String(frame.selector), ...(Array.isArray(frame.files) ? frame.files.map(String) : [])]);
                         result(frame, true);
                         return;
                     case 'browser/drag':
-                        await run(['drag', String(frame.fromSelector), String(frame.toSelector)]);
+                        await runOnContextTab(['drag', String(frame.fromSelector), String(frame.toSelector)]);
                         result(frame, true);
                         return;
                     case 'browser/screenshot': {
                         const args = ['screenshot', ...(frame.path ? [String(frame.path)] : []), ...(frame.annotate ? ['--annotate'] : []), ...(frame.fullPage ? ['--full'] : [])];
-                        const output = await run(args);
+                        const output = await runOnContextTab(args);
                         send({ t: 'browser/screenshot', requestId: frame.requestId, path: typeof frame.path === 'string' ? frame.path : undefined, data: output });
                         return;
                     }
                     case 'browser/pdf': {
-                        const output = await run(['pdf', String(frame.path ?? '')]);
+                        const output = await runOnContextTab(['pdf', String(frame.path ?? '')]);
                         result(frame, true, output);
                         return;
                     }
                     case 'browser/cookies/get':
-                        send({ t: 'browser/cookies', requestId: frame.requestId, cookies: parseJsonOutput(await run(['cookies', 'get'])) ?? [] });
+                        send({ t: 'browser/cookies', requestId: frame.requestId, cookies: parseJsonOutput(await runOnContextTab(['cookies', 'get'])) ?? [] });
                         return;
                     case 'browser/cookies/clear':
-                        await run(['cookies', 'clear']);
+                        await runOnContextTab(['cookies', 'clear']);
                         result(frame, true);
                         return;
                     case 'browser/device':
-                        await run(frame.preset ? ['set', 'device', String(frame.preset)] : ['set', 'viewport', String(frame.width), String(frame.height)]);
+                        await runOnContextTab(frame.preset ? ['set', 'device', String(frame.preset)] : ['set', 'viewport', String(frame.width), String(frame.height)]);
                         result(frame, true);
                         return;
                     case 'browser/media':
-                        await run(['set', 'media', String(frame.scheme ?? 'no-preference')]);
+                        await runOnContextTab(['set', 'media', String(frame.scheme ?? 'no-preference')]);
                         result(frame, true);
                         return;
                     case 'browser/record/start':
-                        await run(['record', 'start', String(frame.path ?? '')]);
+                        await runOnContextTab(['record', 'start', String(frame.path ?? '')]);
                         result(frame, true);
                         return;
                     case 'browser/record/stop':
-                        result(frame, true, await run(['record', 'stop']));
+                        result(frame, true, await runOnContextTab(['record', 'stop']));
                         return;
                     case 'browser/debug/console':
                     case 'browser/debug/errors':
@@ -410,6 +708,7 @@ export function createBrowserBridge(send, sessionName = 'minimal-agent') {
                     case 'browser/debug/vitals':
                     case 'browser/debug/trace/start':
                     case 'browser/debug/trace/stop': {
+                        await claimContextTab();
                         const browserConfig = await configService.browser();
                         if (!browserConfig.developerMode)
                             throw new Error('请先在“设置 → 浏览器”开启完整 CDP Developer Mode');