ai-browser 0.2.1 → 0.2.3

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

@@ -3,20 +3,22 @@ import fs from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { executeAction, escapeCSS, setValueByAccessibility } from '../browser/actions.js';
-import { validateUrl } from '../utils/url-validator.js';
 import { ElementCollector, PageAnalyzer, RegionDetector, ContentExtractor, ElementMatcher, } from '../semantic/index.js';
-// Structured error codes for Agent consumption
-export var ErrorCode;
-(function (ErrorCode) {
-    ErrorCode["ELEMENT_NOT_FOUND"] = "ELEMENT_NOT_FOUND";
-    ErrorCode["NAVIGATION_TIMEOUT"] = "NAVIGATION_TIMEOUT";
-    ErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
-    ErrorCode["PAGE_CRASHED"] = "PAGE_CRASHED";
-    ErrorCode["INVALID_PARAMETER"] = "INVALID_PARAMETER";
-    ErrorCode["EXECUTION_ERROR"] = "EXECUTION_ERROR";
-})(ErrorCode || (ErrorCode = {}));
+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';
+export { ErrorCode } from '../task/error-codes.js';
+import { ErrorCode } from '../task/error-codes.js';
 export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     const server = new McpServer({ name: 'browser-mcp-server', version: '0.1.0' }, { capabilities: { tools: {} } });
+    // Derive URL validation options from trustLevel (with backward compat for urlValidation)
+    const isRemote = options?.trustLevel === 'remote';
+    const urlOpts = isRemote
+        ? { blockPrivate: true, allowFile: false }
+        : options?.trustLevel === 'local'
+            ? { allowFile: true, blockPrivate: false }
+            : options?.urlValidation ?? {};
     const elementCollector = new ElementCollector();
     const pageAnalyzer = new PageAnalyzer();
     const regionDetector = new RegionDetector();
@@ -70,15 +72,29 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         // Use promise lock to prevent concurrent creation of multiple default sessions
         if (!defaultSessionPromise) {
             defaultSessionPromise = (async () => {
-                const sessionOpts = options?.headless !== undefined ? { headless: options.headless } : {};
-                const session = await sessionManager.create(sessionOpts);
-                defaultSessionId = session.id;
-                defaultSessionPromise = null;
-                return session.id;
+                try {
+                    const sessionOpts = options?.headless !== undefined ? { headless: options.headless } : {};
+                    const session = await sessionManager.create(sessionOpts);
+                    defaultSessionId = session.id;
+                    defaultSessionPromise = null;
+                    options?.onSessionCreated?.(session.id);
+                    return session.id;
+                }
+                catch (err) {
+                    defaultSessionPromise = null; // Reset lock to allow retry
+                    throw err;
+                }
             })();
         }
         return defaultSessionPromise;
     }
+    // Create an isolated session for task runs (not bound to defaultSessionId)
+    async function createIsolatedSession() {
+        const sessionOpts = options?.headless !== undefined ? { headless: options.headless } : {};
+        const session = await sessionManager.create(sessionOpts);
+        options?.onSessionCreated?.(session.id);
+        return session.id;
+    }
     // Helper: get active tab for a session
     function getActiveTab(sessionId) {
         const tab = sessionManager.getActiveTab(sessionId);
@@ -118,6 +134,11 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             return ErrorCode.SESSION_NOT_FOUND;
         return undefined;
     }
+    function invalidParameterError(message) {
+        const err = new Error(message);
+        err.errorCode = ErrorCode.INVALID_PARAMETER;
+        return err;
+    }
     // Helper: wrap async handler with try/catch to prevent unhandled exceptions
     function safe(fn) {
         return (async (...args) => {
@@ -130,6 +151,21 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
             }
         });
     }
+    // ToolContext for extracted toolActions (shared by MCP handlers and template executor)
+    const toolCtx = {
+        sessionManager,
+        cookieStore,
+        urlOpts,
+        trustLevel: options?.trustLevel ?? 'local',
+        resolveSession,
+        getActiveTab,
+        getTab: (sid, tid) => sessionManager.getTab(sid, tid),
+        injectCookies: injectCookiesToPage,
+        saveCookies: saveCookiesFromPage,
+    };
+    // RunManager + ArtifactStore for task template execution
+    const runManager = new RunManager();
+    const artifactStore = new ArtifactStore();
     // ===== create_session / close_session =====
     server.tool('create_session', '创建新的浏览器会话', {}, safe(async () => {
         const sessionOpts = options?.headless !== undefined ? { headless: options.headless } : {};
@@ -138,16 +174,23 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         if (!defaultSessionId || !sessionManager.get(defaultSessionId)) {
             defaultSessionId = session.id;
         }
+        options?.onSessionCreated?.(session.id);
         return textResult({ sessionId: session.id });
     }));
-    server.tool('close_session', '关闭浏览器会话', { sessionId: z.string().optional().describe('会话ID，不传则使用默认会话') }, safe(async ({ sessionId: rawSessionId }) => {
+    server.tool('close_session', '关闭浏览器会话（headful 会话会保留，不会被自动关闭）', {
+        sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
+        force: z.boolean().optional().describe('是否强制关闭 headful 会话，默认 false'),
+    }, 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' });
+        }
         const sessionId = await resolveSession(rawSessionId);
-        // 关闭前保存当前会话 + 所有 headful 会话的 cookie
         await sessionManager.saveAllCookies(sessionId);
-        // headful 会话不自动关闭，保留给用户手动操作
+        // 默认保留 headful 会话，force=true 时允许主动关闭。
         const session = sessionManager.get(sessionId);
-        if (session && !session.headless) {
-            return textResult({ success: true, kept: true, reason: 'headful session preserved' });
+        if (session && !session.headless && !force) {
+            return textResult({ success: true, kept: true, reason: 'headful session preserved (set force=true to close)' });
         }
         const closed = await sessionManager.close(sessionId);
         // Clear default session if it was closed
@@ -161,62 +204,8 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
         url: z.string().describe('要导航到的完整URL'),
     }, safe(async ({ sessionId: rawSessionId, url }) => {
-        // URL validation
-        const check = validateUrl(url, options?.urlValidation ?? {});
-        if (!check.valid) {
-            const err = new Error(check.reason);
-            err.errorCode = ErrorCode.INVALID_PARAMETER;
-            throw err;
-        }
         const sessionId = await resolveSession(rawSessionId);
-        const tab = getActiveTab(sessionId);
-        // 导航前先从 headful 会话同步最新 cookie（用户可能手动登录了）
-        await sessionManager.syncHeadfulCookies();
-        // 注入已保存的 cookies（通过 CDP 注入全部 cookie，支持跨域 SSO）
-        await injectCookiesToPage(tab.page);
-        let partial = false;
-        let statusCode;
-        try {
-            const response = await tab.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-            statusCode = response?.status();
-        }
-        catch (err) {
-            if (err.name === 'TimeoutError' || err.message?.includes('timeout')) {
-                partial = true;
-            }
-            else {
-                throw new Error(err.message || 'Navigation failed');
-            }
-        }
-        // 给 SPA 页面额外渲染时间
-        try {
-            await tab.page.waitForNetworkIdle({ timeout: 3000 });
-        }
-        catch {
-            // 忽略超时，不阻塞
-        }
-        tab.url = tab.page.url();
-        await saveCookiesFromPage(tab.page);
-        sessionManager.updateActivity(sessionId);
-        let title = '';
-        try {
-            title = await tab.page.title();
-        }
-        catch {
-            title = '(无法获取标题)';
-        }
-        const result = {
-            success: true,
-            partial,
-            statusCode,
-            page: { url: tab.page.url(), title },
-        };
-        // Check for pending dialog after navigation
-        if (tab.events) {
-            const pending = tab.events.getPendingDialog();
-            if (pending)
-                result.dialog = pending;
-        }
+        const result = await toolActions.navigate(toolCtx, sessionId, url);
         return textResult(result);
     }));
     // ===== get_page_info =====
@@ -227,66 +216,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, maxElements, visibleOnly }) => {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
-        const limit = maxElements ?? 50;
-        const filterVisible = visibleOnly ?? true;
-        const [elements, analysis, regions] = await Promise.all([
-            elementCollector.collect(tab.page),
-            pageAnalyzer.analyze(tab.page),
-            regionDetector.detect(tab.page),
-        ]);
-        let filtered = elements;
-        // Filter to viewport-visible elements
-        if (filterVisible) {
-            const viewport = tab.page.viewport();
-            if (viewport) {
-                filtered = filtered.filter((el) => {
-                    const b = el.bounds;
-                    if (!b || (b.width === 0 && b.height === 0))
-                        return true; // keep elements without bounds
-                    return b.y + b.height > 0 && b.y < viewport.height && b.x + b.width > 0 && b.x < viewport.width;
-                });
-            }
-        }
-        // Sort by y position and truncate
-        const totalElements = filtered.length;
-        filtered.sort((a, b) => (a.bounds?.y ?? 0) - (b.bounds?.y ?? 0));
-        const truncated = filtered.length > limit;
-        if (truncated) {
-            filtered = filtered.slice(0, limit);
-        }
-        // Mask sensitive field values
-        for (const el of filtered) {
-            if (el.type === 'textbox' || el.type === 'input') {
-                const idLower = (el.id || '').toLowerCase();
-                const labelLower = (el.label || '').toLowerCase();
-                const isPassword = idLower.includes('password') || idLower.includes('secret') || idLower.includes('token')
-                    || labelLower.includes('password') || labelLower.includes('secret') || labelLower.includes('token');
-                if (isPassword && el.state?.value) {
-                    el.state.value = '********';
-                }
-            }
-        }
-        sessionManager.updateActivity(sessionId);
-        const result = {
-            page: {
-                url: tab.page.url(),
-                title: await tab.page.title(),
-                type: analysis.pageType,
-                summary: analysis.summary,
-            },
-            elements: filtered,
-            totalElements,
-            truncated,
-            regions,
-            intents: analysis.intents,
-        };
-        // Add stability and dialog info from PageEventTracker
-        if (tab.events) {
-            result.stability = tab.events.getStabilityState();
-            const pending = tab.events.getPendingDialog();
-            if (pending)
-                result.pendingDialog = pending;
-        }
+        const result = await toolActions.getPageInfo(toolCtx, sessionId, tab.id, { maxElements, visibleOnly });
         return textResult(result);
     }));
     // ===== get_page_content =====
@@ -296,27 +226,8 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, maxLength }) => {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
-        const content = await contentExtractor.extract(tab.page);
-        // Truncate sections if maxLength specified
-        if (maxLength && content.sections) {
-            let totalLen = 0;
-            const truncatedSections = [];
-            for (const section of content.sections) {
-                const sectionText = section.text || '';
-                if (totalLen + sectionText.length > maxLength) {
-                    const remaining = maxLength - totalLen;
-                    if (remaining > 0) {
-                        truncatedSections.push({ ...section, text: sectionText.slice(0, remaining) });
-                    }
-                    break;
-                }
-                truncatedSections.push(section);
-                totalLen += sectionText.length;
-            }
-            content.sections = truncatedSections;
-        }
-        sessionManager.updateActivity(sessionId);
-        return textResult(content);
+        const result = await toolActions.getPageContent(toolCtx, sessionId, tab.id, { maxLength });
+        return textResult(result);
     }));
     // ===== click =====
     server.tool('click', '点击页面上的元素', {
@@ -381,8 +292,11 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     // ===== scroll =====
     server.tool('scroll', '滚动页面', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
-        direction: z.enum(['down', 'up']).describe('滚动方向'),
+        direction: z.string().describe('滚动方向：down 或 up'),
     }, safe(async ({ sessionId: rawSessionId, direction }) => {
+        if (direction !== 'down' && direction !== 'up') {
+            throw invalidParameterError('direction must be one of: down, up');
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         await executeAction(tab.page, 'scroll', undefined, direction);
@@ -431,12 +345,17 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     server.tool('press_key', '按下键盘按键，支持组合键（如 Ctrl+A, Shift+Tab）。modifiers 可选: Control, Shift, Alt, Meta', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
         key: z.string().describe('按键名称，如 Enter, Escape, Tab, ArrowDown, a, c'),
-        modifiers: z.array(z.enum(['Control', 'Shift', 'Alt', 'Meta'])).optional().describe('修饰键数组，如 ["Control"] 表示 Ctrl+key'),
+        modifiers: z.array(z.string()).optional().describe('修饰键数组，如 ["Control"] 表示 Ctrl+key'),
     }, safe(async ({ sessionId: rawSessionId, key, modifiers }) => {
         if (modifiers && modifiers.length > 0) {
+            for (const mod of modifiers) {
+                if (!ALLOWED_MODIFIERS.includes(mod)) {
+                    throw invalidParameterError(`不允许的修饰键: ${mod}。允许: ${ALLOWED_MODIFIERS.join(', ')}`);
+                }
+            }
             // Combo key mode
             if (!isComboAllowed(modifiers, key)) {
-                throw new Error(`不允许的组合键: ${modifiers.join('+')}+${key}`);
+                throw invalidParameterError(`不允许的组合键: ${modifiers.join('+')}+${key}`);
             }
             const sessionId = await resolveSession(rawSessionId);
             const tab = getActiveTab(sessionId);
@@ -458,7 +377,7 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         }
         // Single key mode (original logic)
         if (!ALLOWED_KEYS.has(key)) {
-            throw new Error(`不允许的按键: ${key}。允许: ${[...ALLOWED_KEYS].join(', ')}`);
+            throw invalidParameterError(`不允许的按键: ${key}。允许: ${[...ALLOWED_KEYS].join(', ')}`);
         }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
@@ -471,7 +390,9 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         });
     }));
     // ===== go_back =====
-    server.tool('go_back', '返回上一页', { sessionId: z.string().optional().describe('会话ID，不传则使用默认会话') }, safe(async ({ sessionId: rawSessionId }) => {
+    server.tool('go_back', '返回上一页', {
+        sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
+    }, safe(async ({ sessionId: rawSessionId }) => {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         await executeAction(tab.page, 'back');
@@ -504,12 +425,16 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         });
     }));
     // ===== wait =====
-    server.tool('wait', '等待页面加载', {
+    server.tool('wait', '按条件等待：time / selector / networkidle / element_hidden', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
         milliseconds: z.number().optional().describe('等待的毫秒数，默认1000'),
         selector: z.string().optional().describe('等待指定CSS选择器的元素出现'),
-        condition: z.enum(['time', 'selector', 'networkidle', 'element_hidden']).optional().describe('等待条件类型'),
+        condition: z.string().optional().describe('等待条件类型：time / selector / networkidle / element_hidden'),
     }, safe(async ({ sessionId: rawSessionId, milliseconds, selector, condition }) => {
+        const allowedConditions = ['time', 'selector', 'networkidle', 'element_hidden'];
+        if (condition !== undefined && !allowedConditions.includes(condition)) {
+            throw invalidParameterError('condition must be one of: time, selector, networkidle, element_hidden');
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         // For condition-based waits, default timeout is 10s; for simple time wait, default is 1s
@@ -518,12 +443,12 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         }
         else if (condition === 'element_hidden') {
             if (!selector)
-                throw new Error('selector is required for element_hidden condition');
+                throw invalidParameterError('selector is required for element_hidden condition');
             await tab.page.waitForSelector(selector, { hidden: true, timeout: milliseconds || 10000 });
         }
         else if (condition === 'selector' || (!condition && selector)) {
             if (!selector)
-                throw new Error('selector is required for selector condition');
+                throw invalidParameterError('selector is required for selector condition');
             await tab.page.waitForSelector(selector, { timeout: milliseconds || 10000 });
         }
         else {
@@ -533,10 +458,13 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return textResult({ success: true });
     }));
     // ===== execute_javascript =====
-    server.tool('execute_javascript', '在当前页面执行 JavaScript 脚本。脚本必须通过表达式或 return 返回数据，console.log 的输出不会返回', {
+    server.tool('execute_javascript', '在当前页面执行 JavaScript（仅 local 模式可用）。脚本需通过表达式或 return 返回数据，console.log 不会作为返回值', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
         script: z.string().describe('要执行的 JavaScript 代码'),
     }, safe(async ({ sessionId: rawSessionId, script }) => {
+        if (isRemote) {
+            return errorResult('execute_javascript is disabled in remote mode', ErrorCode.INVALID_PARAMETER);
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         let result;
@@ -601,11 +529,8 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         tabId: z.string().describe('要关闭的标签页ID'),
     }, safe(async ({ sessionId: rawSessionId, tabId }) => {
         const sessionId = await resolveSession(rawSessionId);
-        const closed = await sessionManager.closeTab(sessionId, tabId);
-        if (!closed)
-            throw new Error(`Tab not found: ${tabId}`);
-        sessionManager.updateActivity(sessionId);
-        return textResult({ success: true });
+        const result = await toolActions.closeTab(toolCtx, sessionId, tabId);
+        return textResult(result);
     }));
     // ===== switch_tab =====
     server.tool('switch_tab', '切换到指定标签页', {
@@ -629,38 +554,8 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         url: z.string().optional().describe('新标签页要导航到的URL'),
     }, safe(async ({ sessionId: rawSessionId, url }) => {
         const sessionId = await resolveSession(rawSessionId);
-        const tab = await sessionManager.createTab(sessionId);
-        if (!tab)
-            throw new Error(`Session not found: ${sessionId}`);
-        // Auto-switch to the new tab
-        sessionManager.switchTab(sessionId, tab.id);
-        let partial = false;
-        if (url) {
-            const check = validateUrl(url, options?.urlValidation ?? {});
-            if (!check.valid) {
-                const err = new Error(check.reason);
-                err.errorCode = ErrorCode.INVALID_PARAMETER;
-                throw err;
-            }
-            // Inject saved cookies before navigation (consistent with navigate tool)
-            await injectCookiesToPage(tab.page);
-            try {
-                await tab.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
-            }
-            catch (err) {
-                if (err.name === 'TimeoutError' || err.message?.includes('timeout')) {
-                    partial = true;
-                }
-                else {
-                    throw err;
-                }
-            }
-            tab.url = tab.page.url();
-            // Save cookies after navigation
-            await saveCookiesFromPage(tab.page);
-        }
-        sessionManager.updateActivity(sessionId);
-        return textResult({ tabId: tab.id, url: tab.page.url(), partial });
+        const result = await toolActions.createTab(toolCtx, sessionId, url);
+        return textResult(result);
     }));
     // ===== list_tabs =====
     server.tool('list_tabs', '列出当前会话的所有标签页', {
@@ -689,12 +584,15 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
         fullPage: z.boolean().optional().describe('是否截取整个页面（包括滚动区域），默认 false'),
         element_id: z.string().optional().describe('截取指定元素的截图（优先于 fullPage）'),
-        format: z.enum(['png', 'jpeg', 'webp']).optional().describe('截图格式，默认 png'),
+        format: z.string().optional().describe('截图格式：png / jpeg / webp，默认 png'),
         quality: z.number().min(0).max(100).optional().describe('图片质量（仅 jpeg/webp 有效），默认 80'),
     }, safe(async ({ sessionId: rawSessionId, fullPage, element_id, format, quality }) => {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         const imgFormat = format || 'png';
+        if (!['png', 'jpeg', 'webp'].includes(imgFormat)) {
+            throw invalidParameterError('format must be one of: png, jpeg, webp');
+        }
         const mimeType = `image/${imgFormat}`;
         const screenshotOpts = {
             encoding: 'base64',
@@ -728,8 +626,9 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         const pageTitle = await tab.page.title().catch(() => '');
         return {
             content: [
-                { type: 'text', text: JSON.stringify({ captured: true, url: pageUrl, title: pageTitle, fullPage: !!fullPage, element: element_id || null }) },
+                // 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 }) },
             ],
         };
     }));
@@ -784,9 +683,12 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     // ===== handle_dialog =====
     server.tool('handle_dialog', '处理页面弹窗（alert/confirm/prompt），接受或拒绝', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
-        action: z.enum(['accept', 'dismiss']).describe('accept 接受弹窗，dismiss 拒绝弹窗'),
+        action: z.string().describe('accept 接受弹窗，dismiss 拒绝弹窗'),
         text: z.string().optional().describe('为 prompt 弹窗提供输入文本'),
     }, safe(async ({ sessionId: rawSessionId, action, text }) => {
+        if (action !== 'accept' && action !== 'dismiss') {
+            throw invalidParameterError('action must be one of: accept, dismiss');
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
@@ -823,23 +725,20 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     }, safe(async ({ sessionId: rawSessionId, timeout, quietMs }) => {
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
-        if (!tab.events) {
-            return textResult({ stable: true, domStable: true, networkPending: 0, loadState: 'loaded' });
-        }
-        const maxWait = Math.min(timeout ?? 5000, 30000);
-        const stable = await tab.events.waitForStable(maxWait, quietMs);
-        sessionManager.updateActivity(sessionId);
-        const state = tab.events.getStabilityState();
-        return textResult({ ...state, stable });
+        const result = await toolActions.waitForStable(toolCtx, sessionId, tab.id, { timeout, quietMs });
+        return textResult(result);
     }));
     // ===== get_network_logs =====
     server.tool('get_network_logs', '获取页面网络请求日志', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
-        filter: z.enum(['all', 'xhr', 'failed', 'slow']).optional().describe('过滤类型：all=全部, xhr=仅XHR/Fetch, failed=仅失败, slow=慢请求(>1s)'),
+        filter: z.string().optional().describe('过滤类型：all=全部, xhr=仅XHR/Fetch, failed=仅失败, slow=慢请求(>1s)'),
         maxEntries: z.number().optional().describe('最大返回条数，默认50'),
         includeHeaders: z.boolean().optional().describe('是否包含请求/响应头，默认false'),
         urlPattern: z.string().optional().describe('URL 匹配模式（子串匹配）'),
     }, safe(async ({ sessionId: rawSessionId, filter, maxEntries, includeHeaders, urlPattern }) => {
+        if (filter !== undefined && !['all', 'xhr', 'failed', 'slow'].includes(filter)) {
+            throw invalidParameterError('filter must be one of: all, xhr, failed, slow');
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
@@ -877,9 +776,12 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
     // ===== get_console_logs =====
     server.tool('get_console_logs', '获取页面控制台日志', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
-        level: z.enum(['error', 'warn', 'log', 'info', 'debug', 'all']).optional().describe('日志级别过滤，默认只返回 error+warn'),
+        level: z.string().optional().describe('日志级别过滤：error / warn / log / info / debug / all，默认只返回 error+warn'),
         maxEntries: z.number().optional().describe('最大返回条数，默认50'),
     }, safe(async ({ sessionId: rawSessionId, level, maxEntries }) => {
+        if (level !== undefined && !['error', 'warn', 'log', 'info', 'debug', 'all'].includes(level)) {
+            throw invalidParameterError('level must be one of: error, warn, log, info, debug, all');
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         if (!tab.events) {
@@ -903,11 +805,14 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         return textResult({ logs, truncated });
     }));
     // ===== upload_file =====
-    server.tool('upload_file', '上传文件到 file input 元素', {
+    server.tool('upload_file', '上传文件到 file input 元素（仅 local 模式可用）', {
         sessionId: z.string().optional().describe('会话ID，不传则使用默认会话'),
         element_id: z.string().describe('file input 元素的语义ID'),
         filePath: z.string().describe('要上传的文件路径'),
     }, safe(async ({ sessionId: rawSessionId, element_id, filePath: rawPath }) => {
+        if (isRemote) {
+            return errorResult('upload_file is disabled in remote mode', ErrorCode.INVALID_PARAMETER);
+        }
         const sessionId = await resolveSession(rawSessionId);
         const tab = getActiveTab(sessionId);
         const resolvedPath = path.resolve(rawPath);
@@ -950,6 +855,8 @@ export function createBrowserMcpServer(sessionManager, cookieStore, options) {
         sessionManager.updateActivity(sessionId);
         return textResult({ downloads: tab.events.getDownloads() });
     }));
+    // ===== Task Template Tools (delegated to task-tools.ts) =====
+    registerTaskTools(server, toolCtx, runManager, artifactStore, isRemote, safe, resolveSession, createIsolatedSession);
     return server;
 }
 //# sourceMappingURL=browser-mcp-server.js.map