ai-browser 0.2.3 → 0.2.5

package/dist/mcp/browser-mcp-server.js

@@ -8,6 +8,7 @@ import * as toolActions from '../task/tool-actions.js';
 import { RunManager } from '../task/run-manager.js';
 import { ArtifactStore } from '../task/artifact-store.js';
 import { registerTaskTools } from './task-tools.js';
+import { enrichWithAiMarkdown } from './ai-markdown.js';
 export { ErrorCode } from '../task/error-codes.js';
 import { ErrorCode } from '../task/error-codes.js';
 export function createBrowserMcpServer(sessionManager, cookieStore, options) {
@@ -106,8 +107,9 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return tab;
     }
     // Helper: wrap result as MCP text content
-    function textResult(data) {
-        return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+    function textResult(data, toolName) {
+        const payload = toolName ? enrichWithAiMarkdown(toolName, data) : data;
+        return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
     }
     // Helper: wrap error as MCP error content
     function errorResult(message, errorCode) {
@@ -139,6 +141,33 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         err.errorCode = ErrorCode.INVALID_PARAMETER;
         return err;
     }
+    function summarizeNetworkIssues(logs) {
+        const timeoutLogs = logs.filter((l) => String(l?.error || '').toLowerCase().includes('timeout'));
+        const failedLogs = logs.filter((l) => Boolean(l?.error));
+        const httpErrorLogs = logs.filter((l) => typeof l?.status === 'number' && l.status >= 400);
+        const slowLogs = logs.filter((l) => (l?.timing?.duration ?? 0) > 1000);
+        const issues = [];
+        if (timeoutLogs.length > 0)
+            issues.push({ kind: 'timeout', count: timeoutLogs.length, sample: timeoutLogs[0]?.url });
+        if (failedLogs.length > 0)
+            issues.push({ kind: 'request_failed', count: failedLogs.length, sample: failedLogs[0]?.url });
+        if (httpErrorLogs.length > 0)
+            issues.push({ kind: 'http_error', count: httpErrorLogs.length, sample: httpErrorLogs[0]?.url });
+        if (slowLogs.length > 0)
+            issues.push({ kind: 'slow_request', count: slowLogs.length, sample: slowLogs[0]?.url });
+        return issues.slice(0, 5);
+    }
+    function summarizeConsoleIssues(logs) {
+        const levels = ['error', 'warn', 'info', 'log', 'debug'];
+        const issues = [];
+        for (const level of levels) {
+            const levelLogs = logs.filter((l) => l?.level === level);
+            if (levelLogs.length > 0) {
+                issues.push({ kind: level, count: levelLogs.length, sample: levelLogs[0]?.text });
+            }
+        }
+        return issues.slice(0, 5);
+    }
     // Helper: wrap async handler with try/catch to prevent unhandled exceptions
     function safe(fn) {
         return (async (...args) => {
@@ -175,7 +204,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             defaultSessionId = session.id;
         }
         options?.onSessionCreated?.(session.id);
-        return textResult({ sessionId: session.id });
+        return textResult({ sessionId: session.id }, 'create_session');
     }));
     server.tool('close_session', '关闭浏览器会话（headful 会话会保留，不会被自动关闭）', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
@@ -183,21 +212,21 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, force }) => {
         // No-op if no sessionId provided and no default session exists
         if (!rawSessionId && !defaultSessionId && !defaultSessionPromise) {
-            return textResult({ success: true, reason: 'No active session to close' });
+            return textResult({ success: true, reason: 'No active session to close' }, 'close_session');
         }
         const sessionId = await resolveSession(rawSessionId);
         await sessionManager.saveAllCookies(sessionId);
         // 默认保留 headful 会话，force=true 时允许主动关闭。
         const session = sessionManager.get(sessionId);
         if (session && !session.headless && !force) {
-            return textResult({ success: true, kept: true, reason: 'headful session preserved (set force=true to close)' });
+            return textResult({ success: true, kept: true, reason: 'headful session preserved (set force=true to close)' }, 'close_session');
         }
         const closed = await sessionManager.close(sessionId);
         // Clear default session if it was closed
         if (sessionId === defaultSessionId) {
             defaultSessionId = null;
         }
-        return textResult({ success: closed });
+        return textResult({ success: closed }, 'close_session');
     }));
     // ===== navigate =====
     server.tool('navigate', '导航到指定URL', {
@@ -206,7 +235,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, url }) => {
         const sessionId = await resolveSession(rawSessionId);
         const result = await toolActions.navigate(toolCtx, sessionId, url);
-        return textResult(result);
+        return textResult(result, 'navigate');
     }));
     // ===== get_page_info =====
     server.tool('get_page_info', '获取当前页面的语义信息，包括可交互元素列表', {
@@ -216,8 +245,56 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, maxElements, visibleOnly }) => {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
-        const result = await toolActions.getPageInfo(toolCtx, sessionId, tab.id, { maxElements, visibleOnly });
-        return textResult(result);
+        // Fetch with a generous limit first to measure page complexity
+        const fetchLimit = maxElements ?? 200;
+        const result = await toolActions.getPageInfo(toolCtx, sessionId, tab.id, { maxElements: fetchLimit, visibleOnly });
+        const totalElements = Array.isArray(result.elements) ? result.elements.length : 0;
+        // Adaptive limit: if caller specified maxElements, respect it; otherwise auto-adjust
+        let effectiveLimit;
+        if (maxElements !== undefined) {
+            effectiveLimit = maxElements;
+        }
+        else if (totalElements <= 30) {
+            // Small page — return all
+            effectiveLimit = totalElements;
+        }
+        else if (totalElements <= 100) {
+            // Medium page — default 50, prioritize inputs > buttons > links
+            effectiveLimit = 50;
+        }
+        else {
+            // Complex page — default 30, but always include intent-recommended elements
+            effectiveLimit = 30;
+        }
+        // Prioritize elements: inputs first, then buttons, then links, then rest
+        let elements = Array.isArray(result.elements) ? result.elements : [];
+        if (elements.length > effectiveLimit) {
+            const intentIds = new Set();
+            if (Array.isArray(result.recommendedByIntent)) {
+                for (const rec of result.recommendedByIntent) {
+                    if (Array.isArray(rec?.suggestedElementIds)) {
+                        for (const id of rec.suggestedElementIds)
+                            intentIds.add(id);
+                    }
+                }
+            }
+            const intentElements = elements.filter((e) => intentIds.has(e.id));
+            const rest = elements.filter((e) => !intentIds.has(e.id));
+            const inputs = rest.filter((e) => e.type === 'input' || e.type === 'textarea' || e.type === 'select');
+            const buttons = rest.filter((e) => e.type === 'button' || e.type === 'submit');
+            const links = rest.filter((e) => e.type === 'link');
+            const others = rest.filter((e) => !['input', 'textarea', 'select', 'button', 'submit', 'link'].includes(e.type));
+            const prioritized = [...intentElements, ...inputs, ...buttons, ...links, ...others];
+            elements = prioritized.slice(0, effectiveLimit);
+        }
+        const hasMore = totalElements > effectiveLimit;
+        const nextCursor = hasMore
+            ? {
+                strategy: 'increase_max_elements',
+                suggestedMaxElements: Math.min(Math.max(effectiveLimit * 2, 100), 1000),
+            }
+            : null;
+        return textResult({ ...result, elements, totalElements, hasMore, nextCursor }, 'get_page_info');
     }));
     // ===== get_page_content =====
     server.tool('get_page_content', '提取当前页面的文本内容', {
@@ -227,7 +304,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         const result = await toolActions.getPageContent(toolCtx, sessionId, tab.id, { maxLength });
-        return textResult(result);
+        return textResult(result, 'get_page_content');
     }));
     // ===== click =====
     server.tool('click', '点击页面上的元素', {
@@ -264,7 +341,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             if (pending)
                 result.dialog = pending;
         }
-        return textResult(result);
+        return textResult(result, 'click');
     }));
     // ===== type_text =====
     server.tool('type_text', '在输入框中输入文本。设置 submit=true 可在输入后自动按回车提交（适用于搜索框）', {
@@ -287,7 +364,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return textResult({
             success: true,
             page: { url: tab.page.url(), title: await tab.page.title() },
-        });
+        }, 'type_text');
     }));
     // ===== scroll =====
     server.tool('scroll', '滚动页面', {
@@ -301,7 +378,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const tab = getActiveTab(sessionId);
         await executeAction(tab.page, 'scroll', undefined, direction);
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true });
+        return textResult({ success: true }, 'scroll');
     }));
     // ===== press_key =====
     const ALLOWED_KEYS = new Set([
@@ -373,7 +450,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             return textResult({
                 success: true,
                 page: { url: tab.page.url(), title: await tab.page.title() },
-            });
+            }, 'press_key');
         }
         // Single key mode (original logic)
         if (!ALLOWED_KEYS.has(key)) {
@@ -387,7 +464,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return textResult({
             success: true,
             page: { url: tab.page.url(), title: await tab.page.title() },
-        });
+        }, 'press_key');
     }));
     // ===== go_back =====
     server.tool('go_back', '返回上一页', {
@@ -401,7 +478,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return textResult({
             success: true,
             page: { url: tab.page.url(), title: await tab.page.title() },
-        });
+        }, 'go_back');
     }));
     // ===== find_element =====
     server.tool('find_element', '通过自然语言描述模糊匹配页面元素', {
@@ -422,7 +499,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
                 score: c.score,
                 matchReason: c.matchReason,
             })),
-        });
+        }, 'find_element');
     }));
     // ===== wait =====
     server.tool('wait', '按条件等待：time / selector / networkidle / element_hidden', {
@@ -455,7 +532,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             await new Promise(r => setTimeout(r, Math.min(milliseconds || 1000, 30000)));
         }
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true });
+        return textResult({ success: true }, 'wait');
     }));
     // ===== execute_javascript =====
     server.tool('execute_javascript', '在当前页面执行 JavaScript（仅 local 模式可用）。脚本需通过表达式或 return 返回数据，console.log 不会作为返回值', {
@@ -491,14 +568,14 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         }
         sessionManager.updateActivity(sessionId);
         if (result === undefined || result === null) {
-            return textResult({ result: null, hint: '脚本无返回值。如需获取数据，请在脚本末尾使用表达式（如 document.title）或 return 语句。console.log 的输出不会返回。' });
+            return textResult({ result: null, hint: '脚本无返回值。如需获取数据，请在脚本末尾使用表达式（如 document.title）或 return 语句。console.log 的输出不会返回。' }, 'execute_javascript');
         }
         let serialized = JSON.stringify(result);
         const truncated = serialized && serialized.length > 4000;
         if (truncated) {
             serialized = serialized.slice(0, 4000) + '...(truncated)';
         }
-        return textResult({ result: truncated ? serialized : result, truncated });
+        return textResult({ result: truncated ? serialized : result, truncated }, 'execute_javascript');
     }));
     // ===== select_option =====
     server.tool('select_option', '选择下拉框中的选项', {
@@ -510,7 +587,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const tab = getActiveTab(sessionId);
         await executeAction(tab.page, 'select', element_id, value);
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true });
+        return textResult({ success: true }, 'select_option');
     }));
     // ===== hover =====
     server.tool('hover', '将鼠标悬停在页面元素上（触发 tooltip/dropdown 等）', {
@@ -521,7 +598,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const tab = getActiveTab(sessionId);
         await executeAction(tab.page, 'hover', element_id);
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true });
+        return textResult({ success: true }, 'hover');
     }));
     // ===== close_tab =====
     server.tool('close_tab', '关闭指定标签页', {
@@ -530,7 +607,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, tabId }) => {
         const sessionId = await resolveSession(rawSessionId);
         const result = await toolActions.closeTab(toolCtx, sessionId, tabId);
-        return textResult(result);
+        return textResult(result, 'close_tab');
     }));
     // ===== switch_tab =====
     server.tool('switch_tab', '切换到指定标签页', {
@@ -546,7 +623,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return textResult({
             success: true,
             page: { url: tab.page.url(), title: await tab.page.title() },
-        });
+        }, 'switch_tab');
     }));
     // ===== create_tab =====
     server.tool('create_tab', '在当前会话中创建新标签页', {
@@ -555,7 +632,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, url }) => {
         const sessionId = await resolveSession(rawSessionId);
         const result = await toolActions.createTab(toolCtx, sessionId, url);
-        return textResult(result);
+        return textResult(result, 'create_tab');
     }));
     // ===== list_tabs =====
     server.tool('list_tabs', '列出当前会话的所有标签页', {
@@ -567,17 +644,20 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             throw new Error(`Session not found: ${sessionId}`);
         const tabs = sessionManager.listTabs(sessionId);
         sessionManager.updateActivity(sessionId);
+        const tabItems = await Promise.all(tabs.map(async (t) => {
+            let title = '';
+            try {
+                title = await t.page.title();
+            }
+            catch { }
+            return { id: t.id, url: t.page.url(), title };
+        }));
         return textResult({
             activeTabId: session.activeTabId,
-            tabs: await Promise.all(tabs.map(async (t) => {
-                let title = '';
-                try {
-                    title = await t.page.title();
-                }
-                catch { }
-                return { id: t.id, url: t.page.url(), title };
-            })),
-        });
+            tabs: tabItems,
+            hasMore: false,
+            nextCursor: null,
+        }, 'list_tabs');
     }));
     // ===== screenshot =====
     server.tool('screenshot', '截取当前页面的屏幕截图，支持全页截图、元素截图、格式和质量选项', {
@@ -624,11 +704,18 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         sessionManager.updateActivity(sessionId);
         const pageUrl = tab.page.url();
         const pageTitle = await tab.page.title().catch(() => '');
+        const screenshotMeta = enrichWithAiMarkdown('screenshot', {
+            captured: true,
+            url: pageUrl,
+            title: pageTitle,
+            fullPage: !!fullPage,
+            element: element_id || null,
+        });
         return {
             content: [
                 // Some MCP clients only render the first content block; keep image first for compatibility.
                 { type: 'image', data: base64, mimeType },
-                { type: 'text', text: JSON.stringify({ captured: true, url: pageUrl, title: pageTitle, fullPage: !!fullPage, element: element_id || null }) },
+                { type: 'text', text: JSON.stringify(screenshotMeta) },
             ],
         };
     }));
@@ -678,7 +765,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             await setValueByAccessibility(tab.page, element_id, value, html);
         }
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true });
+        return textResult({ success: true }, 'set_value');
     }));
     // ===== handle_dialog =====
     server.tool('handle_dialog', '处理页面弹窗（alert/confirm/prompt），接受或拒绝', {
@@ -692,15 +779,15 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
-            return textResult({ success: false, reason: 'Event tracking not available' });
+            return textResult({ success: false, reason: 'Event tracking not available' }, 'handle_dialog');
         }
         const pending = tab.events.getPendingDialog();
         if (!pending) {
-            return textResult({ success: false, reason: 'No pending dialog' });
+            return textResult({ success: false, reason: 'No pending dialog' }, 'handle_dialog');
         }
         await tab.events.handleDialog(action, text);
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true, dialog: pending });
+        return textResult({ success: true, dialog: pending }, 'handle_dialog');
     }));
     // ===== get_dialog_info =====
     server.tool('get_dialog_info', '获取页面弹窗信息和历史记录', {
@@ -709,13 +796,15 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
-            return textResult({ pendingDialog: null, dialogHistory: [] });
+            return textResult({ pendingDialog: null, dialogHistory: [], hasMore: false, nextCursor: null }, 'get_dialog_info');
         }
         sessionManager.updateActivity(sessionId);
         return textResult({
             pendingDialog: tab.events.getPendingDialog(),
             dialogHistory: tab.events.getDialogs(),
-        });
+            hasMore: false,
+            nextCursor: null,
+        }, 'get_dialog_info');
     }));
     // ===== wait_for_stable =====
     server.tool('wait_for_stable', '等待页面 DOM 稳定（无新增/删除节点且无待处理网络请求）', {
@@ -726,7 +815,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         const result = await toolActions.waitForStable(toolCtx, sessionId, tab.id, { timeout, quietMs });
-        return textResult(result);
+        return textResult(result, 'wait_for_stable');
     }));
     // ===== get_network_logs =====
     server.tool('get_network_logs', '获取页面网络请求日志', {
@@ -742,7 +831,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
-            return textResult({ logs: [], totalCount: 0, truncated: false });
+            return textResult({ logs: [], totalCount: 0, truncated: false, topIssues: [], hasMore: false, nextCursor: null }, 'get_network_logs');
         }
         let logs = tab.events.getNetworkLogs();
         const totalCount = logs.length;
@@ -771,7 +860,12 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             logs = logs.slice(-limit);
         }
         sessionManager.updateActivity(sessionId);
-        return textResult({ logs, totalCount, truncated });
+        const hasMore = truncated;
+        const nextCursor = hasMore
+            ? { strategy: 'increase_max_entries', suggestedMaxEntries: Math.min((limit || 50) * 2, 1000) }
+            : null;
+        const topIssues = summarizeNetworkIssues(logs);
+        return textResult({ logs, totalCount, truncated, topIssues, hasMore, nextCursor }, 'get_network_logs');
     }));
     // ===== get_console_logs =====
     server.tool('get_console_logs', '获取页面控制台日志', {
@@ -785,7 +879,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
-            return textResult({ logs: [], truncated: false });
+            return textResult({ logs: [], truncated: false, topIssues: [], hasMore: false, nextCursor: null }, 'get_console_logs');
         }
         let logs = tab.events.getConsoleLogs();
         // Filter by level (default: error + warn)
@@ -802,7 +896,12 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             logs = logs.slice(-limit);
         }
         sessionManager.updateActivity(sessionId);
-        return textResult({ logs, truncated });
+        const hasMore = truncated;
+        const nextCursor = hasMore
+            ? { strategy: 'increase_max_entries', suggestedMaxEntries: Math.min((limit || 50) * 2, 1000) }
+            : null;
+        const topIssues = summarizeConsoleIssues(logs);
+        return textResult({ logs, truncated, topIssues, hasMore, nextCursor }, 'get_console_logs');
     }));
     // ===== upload_file =====
     server.tool('upload_file', '上传文件到 file input 元素（仅 local 模式可用）', {
@@ -841,7 +940,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         }
         await elementHandle.uploadFile(resolvedPath);
         sessionManager.updateActivity(sessionId);
-        return textResult({ success: true, filePath: resolvedPath });
+        return textResult({ success: true, filePath: resolvedPath }, 'upload_file');
     }));
     // ===== get_downloads =====
     server.tool('get_downloads', '获取当前页面的下载文件列表', {
@@ -850,10 +949,141 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
-            return textResult({ downloads: [] });
+            return textResult({ downloads: [], hasMore: false, nextCursor: null }, 'get_downloads');
+        }
+        sessionManager.updateActivity(sessionId);
+        return textResult({ downloads: tab.events.getDownloads(), hasMore: false, nextCursor: null }, 'get_downloads');
+    }));
+    // ===== Composite Tools =====
+    // fill_form: fill multiple form fields and optionally submit
+    server.tool('fill_form', '一次填写多个表单字段并可选提交。减少多次 type_text 调用', {
+        sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
+        fields: z.array(z.object({
+            element_id: z.string().describe('输入框的语义ID'),
+            value: z.string().describe('要输入的值'),
+        })).describe('要填写的字段列表'),
+        submit: z.object({
+            element_id: z.string().optional().describe('提交按钮的语义ID'),
+            pressEnter: z.boolean().optional().describe('是否按回车提交'),
+        }).optional().describe('提交方式'),
+    }, safe(async ({ sessionId: rawSessionId, fields, submit }) => {
+        const sessionId = await resolveSession(rawSessionId);
+        const tab = getActiveTab(sessionId);
+        const results = [];
+        for (const field of fields) {
+            try {
+                await executeAction(tab.page, 'type', field.element_id, field.value);
+                results.push({ element_id: field.element_id, success: true });
+            }
+            catch (err) {
+                results.push({ element_id: field.element_id, success: false, error: err.message });
+            }
+        }
+        let submitResult;
+        if (submit) {
+            try {
+                if (submit.element_id) {
+                    await executeAction(tab.page, 'click', submit.element_id);
+                    await new Promise(r => setTimeout(r, 200));
+                }
+                else if (submit.pressEnter) {
+                    await Promise.all([
+                        tab.page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 5000 }).catch(() => { }),
+                        tab.page.keyboard.press('Enter'),
+                    ]);
+                }
+                submitResult = { success: true };
+            }
+            catch (err) {
+                submitResult = { success: false, error: err.message };
+            }
+        }
+        await saveCookiesFromPage(tab.page);
+        sessionManager.updateActivity(sessionId);
+        return textResult({
+            fieldResults: results,
+            submitResult,
+            page: { url: tab.page.url(), title: await tab.page.title() },
+        }, 'fill_form');
+    }));
+    // click_and_wait: click then auto-wait for stability/navigation
+    server.tool('click_and_wait', '点击元素后自动等待页面稳定或导航完成', {
+        sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
+        element_id: z.string().describe('要点击的元素的语义ID'),
+        waitFor: z.string().optional().describe('等待条件: stable(默认) / navigation / selector'),
+        selector: z.string().optional().describe('当 waitFor=selector 时，等待此CSS选择器出现'),
+    }, safe(async ({ sessionId: rawSessionId, element_id, waitFor, selector }) => {
+        const sessionId = await resolveSession(rawSessionId);
+        const tab = getActiveTab(sessionId);
+        const waitType = waitFor || 'stable';
+        // Click
+        await executeAction(tab.page, 'click', element_id);
+        await new Promise(r => setTimeout(r, 200));
+        // Wait
+        let waitResult = { stable: true, method: waitType };
+        try {
+            if (waitType === 'navigation') {
+                await tab.page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 10000 });
+            }
+            else if (waitType === 'selector' && selector) {
+                await tab.page.waitForSelector(selector, { timeout: 10000 });
+            }
+            else {
+                // stable: wait for network idle + DOM quiet
+                await tab.page.waitForNetworkIdle({ timeout: 5000 }).catch(() => { });
+            }
+        }
+        catch {
+            waitResult.stable = false;
+        }
+        tab.url = tab.page.url();
+        await saveCookiesFromPage(tab.page);
+        // Check for popups
+        let newTabCreated;
+        if (tab.events) {
+            const popups = tab.events.getPopupPages();
+            for (const popupPage of popups) {
+                const newTab = await sessionManager.registerPopupAsTab(sessionId, popupPage);
+                if (newTab)
+                    newTabCreated = newTab.id;
+            }
+            tab.events.clearPopupPages();
         }
         sessionManager.updateActivity(sessionId);
-        return textResult({ downloads: tab.events.getDownloads() });
+        const result = {
+            success: true,
+            waitResult,
+            page: { url: tab.page.url(), title: await tab.page.title() },
+        };
+        if (newTabCreated)
+            result.newTabCreated = newTabCreated;
+        if (tab.events) {
+            const pending = tab.events.getPendingDialog();
+            if (pending)
+                result.dialog = pending;
+        }
+        return textResult(result, 'click_and_wait');
+    }));
+    // navigate_and_extract: navigate then immediately extract content
+    server.tool('navigate_and_extract', '导航到URL后立即提取内容，减少两次独立调用', {
+        sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
+        url: z.string().describe('要导航到的URL'),
+        extract: z.string().optional().describe('提取类型: content(默认) / elements / both'),
+    }, safe(async ({ sessionId: rawSessionId, url, extract }) => {
+        const sessionId = await resolveSession(rawSessionId);
+        const extractType = extract || 'content';
+        // Navigate
+        const navResult = await toolActions.navigate(toolCtx, sessionId, url);
+        const tab = getActiveTab(sessionId);
+        const result = { navigation: navResult };
+        // Extract based on type
+        if (extractType === 'content' || extractType === 'both') {
+            result.content = await toolActions.getPageContent(toolCtx, sessionId, tab.id, {});
+        }
+        if (extractType === 'elements' || extractType === 'both') {
+            result.elements = await toolActions.getPageInfo(toolCtx, sessionId, tab.id, {});
+        }
+        return textResult(result, 'navigate_and_extract');
     }));
     // ===== Task Template Tools (delegated to task-tools.ts) =====
     registerTaskTools(server, toolCtx, runManager, artifactStore, isRemote, safe, resolveSession, createIsolatedSession);