minimal-agent 0.13.0 → 0.15.0

package/src/tools/webbrowser/webbrowser.js

@@ -23,21 +23,25 @@
  */
 import { z } from 'zod';
 import { randomUUID } from 'node:crypto';
-import { realpath } from 'node:fs/promises';
-import { isAbsolute, relative, resolve } from 'node:path';
+import { mkdir, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
 import { configService } from '../../config/configService.js';
-import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { resolveAgentBrowserPath } from './agentBrowserPath.js';
-import { browserArtifactDir, createArtifactPath, isAllowedBrowserScheme, normalizeUrl, sessionArgs, spawnRunner, validateArtifactOutputPath, BROWSER_SESSION, } from './browser.js';
-import { getWorkingDir } from '../../bootstrap/workingDir.js';
-import { ensureDaemon, stopDaemon, getStreamPort } from './browserDaemon.js';
-import { getBrowserStream } from './browserStream.js';
-import { browserService } from './browserService.js';
+import { BROWSER_SESSION, browserArtifactDir, createArtifactPath, isAllowedBrowserScheme, normalizeUrl, sessionArgs, spawnRunner, validateArtifactOutputPath, } from './browser.js';
+import { browserDownloadDir } from './browserAutomation.js';
+import { CLIPBOARD_READ_EXPRESSION, CLIPBOARD_READ_TEXT_EXPRESSION, PAGE_ASSETS_EXPRESSION, browserAssetFetchExpression, bundlePageAssets, clipboardWriteExpression, clipboardWriteTextExpression, pageContentExpression, } from './browserContent.js';
 import { detectBrowserChallenge } from './browserControl.js';
+import { ensureDaemon, getStreamPort, stopDaemon } from './browserDaemon.js';
+import { FRAME_INFO_EXPRESSION } from './browserFrames.js';
+import { BROWSER_FAILURE_LIMIT, VERIFIED_BROWSER_ACTIONS, browserAttempts, budgetSnapshot, classifyPageEffect, describeEffect, differingLineIndexes, suggestSelectorCandidates, } from './browserOutcome.js';
+import { recoverableAgentBrowserRunFailure, withBrowserRecovery, } from './browserRecovery.js';
 import { browserRunRegistry, isLikelyIrreversibleBrowserTarget, } from './browserRunRegistry.js';
-import { browserAttempts, budgetSnapshot, classifyPageEffect, describeEffect, differingLineIndexes, suggestSelectorCandidates, BROWSER_FAILURE_LIMIT, VERIFIED_BROWSER_ACTIONS, } from './browserOutcome.js';
-import { BrowserTabError, createConversationTab, ensureConversationTab, listBrowserTabs, } from './browserTabs.js';
+import { browserService } from './browserService.js';
+import { getBrowserStream } from './browserStream.js';
+import { BrowserTabError, claimConversationTabById, createConversationTab, ensureConversationTab, listBrowserTabs, } from './browserTabs.js';
 const CHALLENGE_PROBE_ACTIONS = new Set([
     'navigate',
     'click',
@@ -51,7 +55,14 @@ const CHALLENGE_PROBE_ACTIONS = new Set([
     'dialogAccept',
 ]);
 // C4：驱动可见 AI 指针的交互动作（有明确元素目标）。navigate/press/dialogAccept 无元素目标不列入。
-const POINTER_ACTIONS = new Set(['click', 'fill', 'type', 'hover', 'select', 'drag']);
+const POINTER_ACTIONS = new Set([
+    'click',
+    'fill',
+    'type',
+    'hover',
+    'select',
+    'drag',
+]);
 // 关键节点截图核验：这些是「页面到达/读取评估」的确定性检查点，成功后自动截当前可见画面喂视觉模型自我核验，
 // 根治「AI 以为成功了、实际页面不是那回事」。不是每个动作都截（点击/输入等中间步不截），故不会「一直截图」。
 const KEY_NODE_SHOT_ACTIONS = new Set(['navigate', 'snapshot']);
@@ -123,7 +134,10 @@ async function viewportPoint(run, x, y) {
     catch {
         return null;
     }
-    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    if (!Number.isFinite(width) ||
+        !Number.isFinite(height) ||
+        width <= 0 ||
+        height <= 0) {
         return null;
     }
     // 夹在视口内：越界坐标在 CDP 侧不报错，只会点到边缘，症状是"点了但没反应"。
@@ -147,11 +161,16 @@ async function runPointerAt(run, input, kind) {
         return {
             code: 1,
             stdout: '',
-            stderr: '无法取得视口尺寸，坐标点击已放弃 —— 与其按一个猜出来的尺寸点在错误位置，'
-                + '不如不点。请确认页面已加载（先 navigate 或 snapshot），或改用选择器定位。',
+            stderr: '无法取得视口尺寸，坐标点击已放弃 —— 与其按一个猜出来的尺寸点在错误位置，' +
+                '不如不点。请确认页面已加载（先 navigate 或 snapshot），或改用选择器定位。',
         };
     }
-    const moved = await run(['mouse', 'move', String(point.px), String(point.py)]);
+    const moved = await run([
+        'mouse',
+        'move',
+        String(point.px),
+        String(point.py),
+    ]);
     if (moved.code !== 0)
         return moved;
     if (kind === 'hover') {
@@ -163,7 +182,10 @@ async function runPointerAt(run, input, kind) {
     const up = await run(['mouse', 'up']);
     if (up.code !== 0)
         return up;
-    return { ...up, stdout: `clicked at (${point.px}, ${point.py}) [视口比例 ${input.x}, ${input.y}]` };
+    return {
+        ...up,
+        stdout: `clicked at (${point.px}, ${point.py}) [视口比例 ${input.x}, ${input.y}]`,
+    };
 }
 /**
  * 取**当前真实**页面 URL，供站点白名单判定。
@@ -212,7 +234,16 @@ const inputSchema = z.object({
         'forward',
         'reload',
         'snapshot',
+        'frameInfo',
         'getContent',
+        'pageAssets',
+        'listPageAssets',
+        'bundlePageAssets',
+        'exportContent',
+        'clipboardReadText',
+        'clipboardWriteText',
+        'clipboardRead',
+        'clipboardWrite',
         'screenshot',
         'click',
         'fill',
@@ -256,9 +287,21 @@ const inputSchema = z.object({
         'traceStop',
         'reactTree',
         'reactInspect',
+        'download',
+        'doubleClick',
+        'check',
+        'uncheck',
+        'setChecked',
+        'getState',
+        'waitForURL',
+        'waitForDownload',
+        'waitForFileChooser',
     ])
         .describe('Browser action to perform'),
-    url: z.string().optional().describe('URL to navigate to (for navigate/tabNew)'),
+    url: z
+        .string()
+        .optional()
+        .describe('URL to navigate to (for navigate/tabNew)'),
     selector: z
         .string()
         .optional()
@@ -274,19 +317,64 @@ const inputSchema = z.object({
      *
      * 与 ComputerUse 的坐标系**刻意一致**（同为 0–1000），模型不必为两个工具切换心智。
      */
-    x: z.number().min(0).max(1000).optional()
+    x: z
+        .number()
+        .min(0)
+        .max(1000)
+        .optional()
         .describe('视口比例横坐标 0-1000（左=0，右=1000）。仅在没有可用选择器时用；必须与 y 同时提供'),
-    y: z.number().min(0).max(1000).optional()
+    y: z
+        .number()
+        .min(0)
+        .max(1000)
+        .optional()
         .describe('视口比例纵坐标 0-1000（上=0，下=1000）。仅在没有可用选择器时用；必须与 x 同时提供'),
     value: z.string().optional().describe('Text value for fill/type/select'),
+    clipboardText: z
+        .string()
+        .optional()
+        .describe('Text to write to the browser profile clipboard'),
+    clipboardItems: z
+        .array(z.object({ type: z.string().min(1), base64: z.string() }))
+        .optional()
+        .describe('Binary clipboard items for clipboardWrite, encoded as base64'),
+    exportFormat: z
+        .enum([
+        'text',
+        'txt',
+        'markdown',
+        'md',
+        'html',
+        'json',
+        'page',
+        'google-workspace',
+        'youtube-transcript',
+        'pdf',
+        'docx',
+        'xlsx',
+        'csv',
+        'pptx',
+    ])
+        .optional()
+        .describe('Format for exportContent'),
+    bundleDir: z
+        .string()
+        .optional()
+        .describe('Directory under the workspace or browser artifact root for bundlePageAssets'),
     values: z.array(z.string()).optional().describe('Values for multi-select'),
-    key: z.string().optional().describe('Key to press (for press): Enter, Tab, Escape, ArrowUp/Down/Left/Right, etc.'),
+    key: z
+        .string()
+        .optional()
+        .describe('Key to press (for press): Enter, Tab, Escape, ArrowUp/Down/Left/Right, etc.'),
     js: z.string().optional().describe('JavaScript to run (for eval)'),
     path: z
         .string()
         .optional()
         .describe('Output file path for screenshot/pdf/recording (optional; defaults to temp file)'),
-    files: z.array(z.string()).optional().describe('File paths to upload (for upload)'),
+    files: z
+        .array(z.string())
+        .optional()
+        .describe('File paths to upload (for upload)'),
     annotate: z
         .boolean()
         .optional()
@@ -299,16 +387,46 @@ const inputSchema = z.object({
         .enum(['up', 'down', 'top', 'bottom'])
         .optional()
         .describe('scroll direction'),
-    scrollX: z.number().optional().describe('scroll pixels horizontally (positive=right, negative=left)'),
-    scrollY: z.number().optional().describe('scroll pixels vertically (positive=down, negative=up)'),
-    waitMs: z.number().int().positive().optional().describe('Wait time in milliseconds'),
-    waitSelector: z.string().optional().describe('Wait until this selector appears'),
-    waitText: z.string().optional().describe('Wait until this text appears on page'),
+    scrollX: z
+        .number()
+        .optional()
+        .describe('scroll pixels horizontally (positive=right, negative=left)'),
+    scrollY: z
+        .number()
+        .optional()
+        .describe('scroll pixels vertically (positive=down, negative=up)'),
+    waitMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Wait time in milliseconds'),
+    waitSelector: z
+        .string()
+        .optional()
+        .describe('Wait until this selector appears'),
+    waitText: z
+        .string()
+        .optional()
+        .describe('Wait until this text appears on page'),
     waitLoad: z
         .enum(['load', 'domcontentloaded', 'networkidle'])
         .optional()
         .describe("Wait until the page reaches a load state after navigation. 'load' / 'domcontentloaded' settle quickly; 'networkidle' can wait up to ~25s on pages with long-lived connections."),
+    waitUrl: z
+        .string()
+        .optional()
+        .describe('Wait until the current URL matches this pattern'),
     tabId: z.string().optional().describe('Tab ID for tab operations'),
+    retention: z
+        .enum(['ephemeral', 'conversation', 'handoff', 'deliverable'])
+        .optional()
+        .describe('Retention policy for the claimed tab'),
+    tabTitle: z
+        .string()
+        .max(200)
+        .optional()
+        .describe('Human-readable title for a retained tab'),
     cookies: z
         .array(z.object({
         name: z.string(),
@@ -318,19 +436,51 @@ const inputSchema = z.object({
     }))
         .optional()
         .describe('Cookies to set (for cookiesSet)'),
-    viewportWidth: z.number().int().positive().optional().describe('Viewport width'),
-    viewportHeight: z.number().int().positive().optional().describe('Viewport height'),
-    devicePreset: z.string().optional().describe('Device preset name (iPhone 15, iPad, Pixel 9, etc.)'),
-    colorScheme: z.enum(['light', 'dark', 'no-preference']).optional().describe('Color scheme preference'),
+    viewportWidth: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Viewport width'),
+    viewportHeight: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Viewport height'),
+    devicePreset: z
+        .string()
+        .optional()
+        .describe('Device preset name (iPhone 15, iPad, Pixel 9, etc.)'),
+    colorScheme: z
+        .enum(['light', 'dark', 'no-preference'])
+        .optional()
+        .describe('Color scheme preference'),
     offline: z.boolean().optional().describe('Enable offline mode'),
-    mode: z.enum(['browse', 'assist', 'auto']).optional().describe('Deprecated compatibility field; supervised Desktop control is automatic'),
-    dialogText: z.string().optional().describe('Text to enter in prompt dialog (for dialogAccept)'),
+    mode: z
+        .enum(['browse', 'assist', 'auto'])
+        .optional()
+        .describe('Deprecated compatibility field; supervised Desktop control is automatic'),
+    dialogText: z
+        .string()
+        .optional()
+        .describe('Text to enter in prompt dialog (for dialogAccept)'),
     pickX: z.number().optional().describe('X coordinate for pickElement'),
     pickY: z.number().optional().describe('Y coordinate for pickElement'),
     markLabel: z.string().optional().describe('Label for marked element'),
-    markColor: z.string().optional().describe('Color for marked element highlight'),
+    markColor: z
+        .string()
+        .optional()
+        .describe('Color for marked element highlight'),
     dragTo: z.string().optional().describe('Target selector for drag action'),
-    reactId: z.string().optional().describe('React fiber id returned by reactTree'),
+    checked: z
+        .boolean()
+        .optional()
+        .describe('Desired checkbox state for setChecked'),
+    reactId: z
+        .string()
+        .optional()
+        .describe('React fiber id returned by reactTree'),
     timeout: z
         .number()
         .int()
@@ -343,17 +493,47 @@ const inputSchema = z.object({
         // ⚠️ 语义是**整个序列**的总时长，不是单条命令。一次 click 在锁内会跑「目标文案
         // 探测 → 元素盒子 → 前置快照 → 动作 → 稳定重探 → 可选噪声基线」，这个预算盖住
         // 全部。描述必须说清楚，否则调用方按「单个动作」估的值会把前后探测一起掐掉。
-        .describe('Timeout in milliseconds for the whole action sequence — including the pre-action probe, '
-        + 'the action itself, and the post-action settle/verify probes (default: 120000, max: 300000)'),
+        .describe('Timeout in milliseconds for the whole action sequence — including the pre-action probe, ' +
+        'the action itself, and the post-action settle/verify probes (default: 120000, max: 300000)'),
     intent: z
         .enum(['normal', 'submit'])
         .optional()
         .describe('Use submit for the final irreversible action, such as publish, purchase, delete, or form submission'),
 });
 const OBSERVE_ACTIONS = new Set([
-    'snapshot', 'getContent', 'screenshot', 'tabList', 'streamInfo',
-    'console', 'errors', 'networkRequests', 'getStyles', 'vitals',
-    'reactTree', 'reactInspect',
+    'snapshot',
+    'frameInfo',
+    'getContent',
+    'pageAssets',
+    'listPageAssets',
+    'bundlePageAssets',
+    'exportContent',
+    'clipboardReadText',
+    'clipboardRead',
+    'screenshot',
+    'tabList',
+    'streamInfo',
+    'console',
+    'errors',
+    'networkRequests',
+    'getStyles',
+    'vitals',
+    'reactTree',
+    'reactInspect',
+]);
+// These capabilities use fixed internal expressions. They are not an escape
+// hatch for arbitrary JavaScript; caller supplied code remains the `eval`
+// action and keeps its Developer Mode gate.
+const INTERNAL_SCRIPT_ACTIONS = new Set([
+    'pageAssets',
+    'exportContent',
+    'clipboardReadText',
+    'clipboardWriteText',
+    'clipboardRead',
+    'clipboardWrite',
+    'frameInfo',
+    'listPageAssets',
+    'bundlePageAssets',
 ]);
 const parameters = toToolParameters(inputSchema);
 const description = `Controls KakadeAI Desktop's visible, human-supervised browser for browser automation.
@@ -394,7 +574,12 @@ Navigation:
 
 Page Reading:
   snapshot                 - Accessibility tree with @eN refs (LLM gold standard for seeing page).
+  frameInfo                - List the current page's iframe/frame handles and URLs.
   getContent [selector]    - Plain text of page or element (default body).
+  pageAssets               - List images, media, styles, scripts, fonts and icons referenced by the page.
+  exportContent            - Export page, Google Workspace or YouTube transcript content as structured data.
+  clipboardReadText        - Read text from the browser profile clipboard.
+  clipboardWriteText       - Write clipboardText to the browser profile clipboard.
   screenshot [--annotate] [--fullPage] [--path] - Save PNG; --annotate numbers interactive elements.
   pdf [path]               - Save page as PDF.
   eval <js>                - Run JavaScript, return result.
@@ -470,6 +655,7 @@ export const ARTIFACT_ACTIONS = {
     pdf: { prefix: 'browser-page', ext: 'pdf' },
     recordStart: { prefix: 'recording', ext: 'webm' },
     traceStop: { prefix: 'browser-trace', ext: 'json' },
+    download: { prefix: 'browser-download', ext: 'download' },
 };
 /**
  * @param resolvedOutPath 已经过 `validateArtifactOutputPath` 校验的落盘路径。
@@ -506,12 +692,44 @@ function buildSubArgs(input, resolvedOutPath) {
             return { args: ['reload'] };
         case 'snapshot':
             return { args: ['snapshot'] };
+        case 'frameInfo':
+            return { args: ['eval', FRAME_INFO_EXPRESSION] };
         case 'getContent':
             return { args: ['get', 'text', input.selector ?? 'body'] };
+        case 'pageAssets':
+        case 'listPageAssets':
+            return { args: ['eval', PAGE_ASSETS_EXPRESSION] };
+        case 'bundlePageAssets':
+            return { args: ['eval', PAGE_ASSETS_EXPRESSION] };
+        case 'exportContent':
+            return {
+                args: [
+                    'eval',
+                    pageContentExpression(input.exportFormat ?? 'page', input.selector),
+                ],
+            };
+        case 'clipboardReadText':
+            return { args: ['eval', CLIPBOARD_READ_TEXT_EXPRESSION] };
+        case 'clipboardWriteText':
+            if (input.clipboardText === undefined)
+                return { error: 'clipboardWriteText requires clipboardText' };
+            return {
+                args: ['eval', clipboardWriteTextExpression(input.clipboardText)],
+            };
+        case 'clipboardRead':
+            return { args: ['eval', CLIPBOARD_READ_EXPRESSION] };
+        case 'clipboardWrite':
+            if (!input.clipboardItems?.length)
+                return { error: 'clipboardWrite requires clipboardItems' };
+            return {
+                args: ['eval', clipboardWriteExpression(input.clipboardItems)],
+            };
         case 'screenshot': {
             const out = resolvedOutPath ?? input.path;
             if (!out)
-                return { error: `${action} 需要已解析的输出路径（由 call() 校验后传入）` };
+                return {
+                    error: `${action} 需要已解析的输出路径（由 call() 校验后传入）`,
+                };
             const args = ['screenshot', out];
             if (input.annotate)
                 args.push('--annotate');
@@ -525,9 +743,31 @@ function buildSubArgs(input, resolvedOutPath) {
             if (!input.selector) {
                 if (hasPointCoords(input))
                     return { args: [], pointerAction: 'click' };
-                return { error: 'click 需要 selector；没有可用选择器时可改用视口比例坐标 x/y（0-1000）' };
+                return {
+                    error: 'click 需要 selector；没有可用选择器时可改用视口比例坐标 x/y（0-1000）',
+                };
             }
             return { args: ['click', input.selector] };
+        case 'doubleClick':
+            if (!input.selector)
+                return { error: 'doubleClick requires selector' };
+            return { args: ['dblclick', input.selector] };
+        case 'check':
+            if (!input.selector)
+                return { error: 'check requires selector' };
+            return { args: ['check', input.selector] };
+        case 'uncheck':
+            if (!input.selector)
+                return { error: 'uncheck requires selector' };
+            return { args: ['uncheck', input.selector] };
+        case 'setChecked':
+            if (!input.selector || input.checked === undefined)
+                return { error: 'setChecked requires selector and checked' };
+            return { args: [input.checked ? 'check' : 'uncheck', input.selector] };
+        case 'getState':
+            if (!input.selector)
+                return { error: 'getState requires selector' };
+            return { args: ['is', 'visible', input.selector] };
         case 'fill':
             if (!input.selector || input.value === undefined)
                 return { error: 'fill requires selector and value parameters' };
@@ -540,7 +780,9 @@ function buildSubArgs(input, resolvedOutPath) {
             if (!input.selector) {
                 if (hasPointCoords(input))
                     return { args: [], pointerAction: 'hover' };
-                return { error: 'hover 需要 selector；没有可用选择器时可改用视口比例坐标 x/y（0-1000）' };
+                return {
+                    error: 'hover 需要 selector；没有可用选择器时可改用视口比例坐标 x/y（0-1000）',
+                };
             }
             return { args: ['hover', input.selector] };
         case 'scroll': {
@@ -548,7 +790,7 @@ function buildSubArgs(input, resolvedOutPath) {
             if (input.selector)
                 args.push(input.selector);
             if (input.direction)
-                args.push('--' + input.direction);
+                args.push(`--${input.direction}`);
             if (input.scrollY)
                 args.push('--by-y', String(input.scrollY));
             if (input.scrollX)
@@ -557,14 +799,18 @@ function buildSubArgs(input, resolvedOutPath) {
         }
         case 'select': {
             if (!input.selector || (input.value === undefined && !input.values))
-                return { error: 'select requires selector and value/values parameters' };
+                return {
+                    error: 'select requires selector and value/values parameters',
+                };
             const vals = input.values ?? [input.value];
             return { args: ['select', input.selector, ...vals] };
         }
         case 'press':
             if (!input.key)
                 return { error: 'press requires key parameter' };
-            return { args: ['press', input.key, ...(input.selector ? [input.selector] : [])] };
+            return {
+                args: ['press', input.key, ...(input.selector ? [input.selector] : [])],
+            };
         case 'wait': {
             // agent-browser `wait` grammar: bare positional `wait <ms>` = plain sleep,
             // `wait <selector>` = wait-for-element; only --text/--load/--url/--fn are flags.
@@ -578,8 +824,20 @@ function buildSubArgs(input, resolvedOutPath) {
                 return { args: ['wait', '--load', input.waitLoad] };
             if (input.waitMs)
                 return { args: ['wait', String(input.waitMs)] };
-            return { error: 'wait requires waitMs / waitSelector / waitText / waitLoad' };
+            return {
+                error: 'wait requires waitMs / waitSelector / waitText / waitLoad',
+            };
         }
+        case 'waitForURL':
+            if (!input.waitUrl && !input.url)
+                return { error: 'waitForURL requires waitUrl or url' };
+            return { args: ['wait', '--url', input.waitUrl ?? input.url] };
+        case 'waitForDownload':
+            return { args: ['wait', '--download'] };
+        case 'waitForFileChooser':
+            return {
+                error: 'waitForFileChooser is available in BrowserBatch, where it can be atomically paired with its triggering action',
+            };
         case 'eval':
             if (!input.js)
                 return { error: 'eval requires js parameter' };
@@ -587,15 +845,23 @@ function buildSubArgs(input, resolvedOutPath) {
         case 'pdf': {
             const out = resolvedOutPath ?? input.path;
             if (!out)
-                return { error: `${action} 需要已解析的输出路径（由 call() 校验后传入）` };
+                return {
+                    error: `${action} 需要已解析的输出路径（由 call() 校验后传入）`,
+                };
             return { args: ['pdf', out], outPath: out };
         }
         case 'close':
             return { args: ['close'] };
         case 'tabNew':
-            return { args: input.url ? ['tab', 'new', normalizeUrl(input.url)] : ['tab', 'new'] };
+            return {
+                args: input.url
+                    ? ['tab', 'new', normalizeUrl(input.url)]
+                    : ['tab', 'new'],
+            };
         case 'tabClose':
-            return { args: input.tabId ? ['tab', 'close', input.tabId] : ['tab', 'close'] };
+            return {
+                args: input.tabId ? ['tab', 'close', input.tabId] : ['tab', 'close'],
+            };
         case 'tabSwitch':
             if (!input.tabId)
                 return { error: 'tabSwitch requires tabId parameter' };
@@ -607,14 +873,25 @@ function buildSubArgs(input, resolvedOutPath) {
         case 'cookiesSet': {
             if (!input.cookies || input.cookies.length === 0)
                 return { error: 'cookiesSet requires cookies array' };
-            return { args: ['cookies', 'set', '--json', JSON.stringify(input.cookies)] };
+            return {
+                args: ['cookies', 'set', '--json', JSON.stringify(input.cookies)],
+            };
         }
         case 'cookiesClear':
             return { args: ['cookies', 'clear'] };
         case 'setViewport': {
             if (!input.viewportWidth || !input.viewportHeight)
-                return { error: 'setViewport requires viewportWidth and viewportHeight' };
-            return { args: ['set', 'viewport', String(input.viewportWidth), String(input.viewportHeight)] };
+                return {
+                    error: 'setViewport requires viewportWidth and viewportHeight',
+                };
+            return {
+                args: [
+                    'set',
+                    'viewport',
+                    String(input.viewportWidth),
+                    String(input.viewportHeight),
+                ],
+            };
         }
         case 'setDevice': {
             const args = ['set', 'device'];
@@ -637,13 +914,19 @@ function buildSubArgs(input, resolvedOutPath) {
         case 'recordStart': {
             const out = resolvedOutPath ?? input.path;
             if (!out)
-                return { error: `${action} 需要已解析的输出路径（由 call() 校验后传入）` };
+                return {
+                    error: `${action} 需要已解析的输出路径（由 call() 校验后传入）`,
+                };
             return { args: ['record', 'start', out], outPath: out };
         }
         case 'recordStop':
             return { args: ['record', 'stop'] };
         case 'dialogAccept':
-            return { args: input.dialogText ? ['dialog', 'accept', '--text', input.dialogText] : ['dialog', 'accept'] };
+            return {
+                args: input.dialogText
+                    ? ['dialog', 'accept', '--text', input.dialogText]
+                    : ['dialog', 'accept'],
+            };
         case 'dialogDismiss':
             return { args: ['dialog', 'dismiss'] };
         case 'pickElement': {
@@ -663,24 +946,43 @@ function buildSubArgs(input, resolvedOutPath) {
                 return { error: 'upload requires selector and files parameters' };
             return { args: ['upload', input.selector, ...input.files] };
         }
+        case 'download': {
+            if (!input.selector)
+                return { error: 'download requires selector' };
+            const out = resolvedOutPath ?? input.path;
+            if (!out)
+                return { error: 'download requires output path' };
+            return { args: ['download', input.selector, out], outPath: out };
+        }
         case 'drag': {
             if (!input.selector || !input.dragTo)
-                return { error: 'drag requires selector (from) and dragTo (to) parameters' };
+                return {
+                    error: 'drag requires selector (from) and dragTo (to) parameters',
+                };
             return { args: ['drag', input.selector, input.dragTo] };
         }
-        case 'console': return { args: ['console'] };
-        case 'errors': return { args: ['errors'] };
-        case 'networkRequests': return { args: ['network', 'requests', '--json'] };
-        case 'getStyles': return { args: ['get', 'styles', input.selector ?? 'body', '--json'] };
-        case 'vitals': return { args: ['vitals', ...(input.url ? [input.url] : []), '--json'] };
-        case 'traceStart': return { args: ['trace', 'start'] };
+        case 'console':
+            return { args: ['console'] };
+        case 'errors':
+            return { args: ['errors'] };
+        case 'networkRequests':
+            return { args: ['network', 'requests', '--json'] };
+        case 'getStyles':
+            return { args: ['get', 'styles', input.selector ?? 'body', '--json'] };
+        case 'vitals':
+            return { args: ['vitals', ...(input.url ? [input.url] : []), '--json'] };
+        case 'traceStart':
+            return { args: ['trace', 'start'] };
         case 'traceStop': {
             const out = resolvedOutPath ?? input.path;
             if (!out)
-                return { error: `${action} 需要已解析的输出路径（由 call() 校验后传入）` };
+                return {
+                    error: `${action} 需要已解析的输出路径（由 call() 校验后传入）`,
+                };
             return { args: ['trace', 'stop', out], outPath: out };
         }
-        case 'reactTree': return { args: ['react', 'tree'] };
+        case 'reactTree':
+            return { args: ['react', 'tree'] };
         case 'reactInspect':
             if (!input.reactId)
                 return { error: 'reactInspect requires reactId parameter' };
@@ -755,7 +1057,11 @@ async function handleMetaAction(action, input, signal, ctx = {}) {
                 const port = stream.getPort();
                 return {
                     ok: true,
-                    content: JSON.stringify({ connected: stream.isConnected(), port, status }),
+                    content: JSON.stringify({
+                        connected: stream.isConnected(),
+                        port,
+                        status,
+                    }),
                 };
             }
             case 'setMode': {
@@ -766,15 +1072,29 @@ async function handleMetaAction(action, input, signal, ctx = {}) {
             case 'pickElement': {
                 const el = await stream.pickElement(input.pickX, input.pickY);
                 if (!el)
-                    return { ok: false, error: 'pickElement: no element found at coordinates' };
-                stream.markElement({ ref: el.ref, tag: el.tag, text: el.text, boundingBox: el.boundingBox, label: el.ref });
+                    return {
+                        ok: false,
+                        error: 'pickElement: no element found at coordinates',
+                    };
+                stream.markElement({
+                    ref: el.ref,
+                    tag: el.tag,
+                    text: el.text,
+                    boundingBox: el.boundingBox,
+                    label: el.ref,
+                });
                 return {
                     ok: true,
                     content: JSON.stringify(el),
                 };
             }
             case 'markElement': {
-                const el = { ref: input.selector, tag: input.selector, label: input.markLabel, color: input.markColor };
+                const el = {
+                    ref: input.selector,
+                    tag: input.selector,
+                    label: input.markLabel,
+                    color: input.markColor,
+                };
                 stream.markElement(el);
                 return { ok: true, content: `[markElement] marked ${input.selector}` };
             }
@@ -794,22 +1114,38 @@ async function handleMetaAction(action, input, signal, ctx = {}) {
 function describeAction(input) {
     const target = input.selector ?? input.url ?? '';
     switch (input.action) {
-        case 'navigate': return `正在打开 ${input.url ?? ''}`.trim();
-        case 'click': return `正在点击 ${target}`.trim();
-        case 'fill': return `正在填写 ${input.selector ?? ''}`.trim();
-        case 'type': return `正在输入到 ${input.selector ?? ''}`.trim();
-        case 'hover': return `正在悬停 ${input.selector ?? ''}`.trim();
-        case 'select': return `正在选择 ${input.selector ?? ''}`.trim();
-        case 'press': return `正在按键 ${input.key ?? ''}`.trim();
-        case 'scroll': return '正在滚动页面';
-        case 'drag': return `正在拖拽 ${input.selector ?? ''}`.trim();
-        case 'upload': return '正在上传文件';
-        case 'back': return '正在后退';
-        case 'forward': return '正在前进';
-        case 'reload': return '正在刷新页面';
-        case 'screenshot': return '正在截图';
-        case 'pdf': return '正在导出 PDF';
-        default: return `正在执行 ${input.action}`;
+        case 'navigate':
+            return `正在打开 ${input.url ?? ''}`.trim();
+        case 'click':
+            return `正在点击 ${target}`.trim();
+        case 'fill':
+            return `正在填写 ${input.selector ?? ''}`.trim();
+        case 'type':
+            return `正在输入到 ${input.selector ?? ''}`.trim();
+        case 'hover':
+            return `正在悬停 ${input.selector ?? ''}`.trim();
+        case 'select':
+            return `正在选择 ${input.selector ?? ''}`.trim();
+        case 'press':
+            return `正在按键 ${input.key ?? ''}`.trim();
+        case 'scroll':
+            return '正在滚动页面';
+        case 'drag':
+            return `正在拖拽 ${input.selector ?? ''}`.trim();
+        case 'upload':
+            return '正在上传文件';
+        case 'back':
+            return '正在后退';
+        case 'forward':
+            return '正在前进';
+        case 'reload':
+            return '正在刷新页面';
+        case 'screenshot':
+            return '正在截图';
+        case 'pdf':
+            return '正在导出 PDF';
+        default:
+            return `正在执行 ${input.action}`;
     }
 }
 /** C4：把工具动作映射成指针动效类型（协议 action 枚举）。 */
@@ -831,7 +1167,10 @@ async function sleep(ms, signal) {
             signal?.removeEventListener('abort', onAbort);
             resolve();
         }, ms);
-        const onAbort = () => { clearTimeout(timer); resolve(); };
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
         signal?.addEventListener('abort', onAbort, { once: true });
     });
 }
@@ -839,7 +1178,12 @@ async function sleep(ms, signal) {
  * Pure visual enhancement - failures are silently ignored (never block the action). */
 function flashTargetElement(stream, selector) {
     try {
-        stream.markElement({ ref: selector, tag: selector, color: '#22c55e', label: '' });
+        stream.markElement({
+            ref: selector,
+            tag: selector,
+            color: '#22c55e',
+            label: '',
+        });
         setTimeout(() => stream.unmarkElement(selector), 350);
     }
     catch {
@@ -912,12 +1256,12 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
     // 于是排成：scheme 白名单 → 输出路径校验 → argv 拼装 → metaAction → 解析二进制 → 门禁。
     // `javascript:` 是在页面里执行代码，必须走受门禁约束的 `eval`，不能靠一个看起来像
     // "打开网址"的动作绕过去；`data:` 可构造带脚本的文档，等价同一件事。
-    if ((input.action === 'navigate' || input.action === 'tabNew') && input.url
-        && !isAllowedBrowserScheme(input.url)) {
+    if ((input.action === 'navigate' || input.action === 'tabNew') &&
+        input.url &&
+        !isAllowedBrowserScheme(input.url)) {
         return {
             ok: false,
-            error: `[${input.action}] 不支持的地址协议：${input.url.split(':')[0]}:。仅允许 http/https/about/file；`
-                + '要在页面里执行脚本请用 eval（需 Developer Mode 授权）。',
+            error: `[${input.action}] 不支持的地址协议：${input.url.split(':')[0]}:。仅允许 http/https/about/file；要在页面里执行脚本请用 eval（需 Developer Mode 授权）。`,
         };
     }
     // 会落盘的动作：先把输出路径解析并校验好，再拼命令。
@@ -935,10 +1279,33 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
                 return { ok: false, error: `[${input.action}] ${checked.error}` };
             resolvedOutPath = checked.path;
         }
+        else if (input.action === 'download') {
+            const dir = browserDownloadDir(ctx.browserRun?.conversationKey, ctx.browserRun?.runId ?? ctx.toolCallId);
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            resolvedOutPath = join(dir, `download-${Date.now()}-${randomUUID().slice(0, 8)}.download`);
+        }
         else {
             resolvedOutPath = await createArtifactPath(artifact.prefix, artifact.ext);
         }
     }
+    // Asset bundling writes a manifest and fetched files. Validate its root
+    // before starting the browser or evaluating the page, just like the other
+    // browser write actions.
+    if (input.action === 'bundlePageAssets') {
+        if (!input.bundleDir)
+            return { ok: false, error: 'bundlePageAssets requires bundleDir' };
+        const roots = [browserArtifactDir(), getWorkingDir()];
+        const target = await realpath(input.bundleDir).catch(() => resolve(input.bundleDir));
+        const allowed = roots.some((root) => {
+            const child = relative(root, target);
+            return child === '' || (!child.startsWith('..') && !isAbsolute(child));
+        });
+        if (!allowed)
+            return {
+                ok: false,
+                error: `资产打包目录不在浏览器产物或工作区范围内：${input.bundleDir}`,
+            };
+    }
     const built = buildSubArgs(input, resolvedOutPath);
     if ('error' in built)
         return { ok: false, error: built.error };
@@ -958,8 +1325,13 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
     // Developer Mode 的开关本身是纯配置判定，没有副作用，在这里挡掉最省事。
     // 但**站点 origin 判定不在这里**——它需要「当前真实 URL」，而那取决于本次动作会
     // 落在哪个标签页，此刻还没认领。它挪进了下面的动作序列内（见 `requireLiveOrigin`）。
-    if (DEVELOPER_MODE_ACTIONS.has(input.action) && !browserConfig.developerMode) {
-        return { ok: false, error: '完整浏览器调试未授权。请先在“设置 → 浏览器”开启 Developer Mode。' };
+    if (DEVELOPER_MODE_ACTIONS.has(input.action) &&
+        !INTERNAL_SCRIPT_ACTIONS.has(input.action) &&
+        !browserConfig.developerMode) {
+        return {
+            ok: false,
+            error: '完整浏览器调试未授权。请先在“设置 → 浏览器”开启 Developer Mode。',
+        };
     }
     const stream = getBrowserStream(BROWSER_SESSION);
     const runId = ctx.browserRun?.runId ?? ctx.toolCallId ?? randomUUID();
@@ -1006,12 +1378,23 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             browserRunRegistry.requireGrant(browserContext, 'submit');
     }
     catch (error) {
-        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
     }
     // 仅当宿主声明「有可见浏览器 + 真人可接管」（Desktop）才允许遇关卡阻塞等人；
     // CLI -p / TUI / gateway 不设 browserRun → supervised=false → 据实非阻塞返回，绝不挂起。
     const supervised = ctx.browserRun?.supervised === true;
-    const visibleAgentAction = !['snapshot', 'getContent', 'console', 'errors', 'networkRequests', 'getStyles', 'vitals'].includes(input.action);
+    const visibleAgentAction = ![
+        'snapshot',
+        'getContent',
+        'console',
+        'errors',
+        'networkRequests',
+        'getStyles',
+        'vitals',
+    ].includes(input.action);
     // 预备步（认领会话标签页）专用控制器：受父级中断 + 超时约束，但不被「接管」打断（快速一次性）。
     const preCtrl = new AbortController();
     let preTimer = setTimeout(() => preCtrl.abort(), input.timeout ?? 120_000);
@@ -1050,10 +1433,12 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
                 signal.addEventListener('abort', onParent, { once: true });
         }
         // subscribe 立即以当前状态回调一次：动作开始时是 running（不掐）；中途进入 waiting_human 才掐断。
-        const unsub = stream.subscribeControl((state) => { if (state.status === 'waiting_human')
-            ac.abort(); });
+        const unsub = stream.subscribeControl((state) => {
+            if (state.status === 'waiting_human')
+                ac.abort();
+        });
         try {
-            return await browserService.exclusive({
+            return await withBrowserRecovery(() => browserService.exclusive({
                 sessionName: BROWSER_SESSION,
                 bin,
                 runner: deps.run,
@@ -1064,14 +1449,41 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
                 // 每条都切纯属浪费一次子进程往返。
                 const scoped = async (args) => {
                     if (claimedTabId && !tabEnsured) {
-                        const switched = await run([...sessionArgs(BROWSER_SESSION), 'tab', claimedTabId]);
-                        if (switched.code !== 0)
+                        const switched = await run([
+                            ...sessionArgs(BROWSER_SESSION),
+                            'tab',
+                            claimedTabId,
+                        ]);
+                        if (switched.code !== 0) {
+                            const recoverable = recoverableAgentBrowserRunFailure(switched);
+                            if (recoverable)
+                                throw recoverable;
                             return switched;
+                        }
                         tabEnsured = true;
                     }
-                    return run([...sessionArgs(BROWSER_SESSION), ...args]);
+                    const result = await run([
+                        ...sessionArgs(BROWSER_SESSION),
+                        ...args,
+                    ]);
+                    const recoverable = recoverableAgentBrowserRunFailure(result);
+                    if (recoverable)
+                        throw recoverable;
+                    return result;
                 };
                 return body(scoped);
+            }), {
+                signal: ac.signal,
+                reconnect: async () => {
+                    await deps.ensureDaemon(BROWSER_SESSION, { signal: ac.signal });
+                },
+                rebindTab: async () => {
+                    if (!claimedTabId)
+                        return;
+                    const rebound = await deps.run(bin, [...sessionArgs(BROWSER_SESSION), 'tab', claimedTabId], ac.signal);
+                    if (rebound.code !== 0)
+                        throw new Error(rebound.stderr || '浏览器标签页已失效，无法重新绑定');
+                },
             });
         }
         finally {
@@ -1082,13 +1494,17 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
     };
     /** 单条命令 = 只有一步的序列。人工等待之后的收尾快照走这个（此时不该再持锁）。 */
     const runAction = (args) => runSequence((run) => run(args));
-    stream.beginAgentAction({ runId, conversationKey, action: input.action });
     let pointerShown = false; // C4：本次是否点亮了 AI 指针（finally 淡出用）
-    // ⚠️ 拿到锁之后**必须立刻进 try**：finally 里的 finishAgentAction 是唯一的释放路径。
-    // 下面这段旁白曾经放在 try 之外 —— `ctx.reportProgress` 是宿主注入的回调，它一抛错
-    // 就会跳过整个 try/finally，锁再也不会被释放；此后该进程内**任何**会话调
-    // beginAgent 都会撞上「浏览器正在执行另一个会话的原子操作」，且现场已经没了。
+    // ⚠️ 取锁是 try 的**第一行**。这把锁是进程级单例，唯一的释放路径是下面的 finally，
+    // 所以「拿到锁却没能进 try」必须在结构上不可能发生 —— 而不是靠后来者记得别往
+    // begin 与 try 之间插代码。历史上这里正是 begin 在外、旁白（ctx.reportProgress，
+    // 宿主注入的回调）也在外：它一抛错就跳过整个 try/finally，锁再不释放，此后该进程内
+    // **任何**会话都撞「正在执行另一个会话的原子操作」，且现场已经没了。
+    //
+    // 取锁本身失败（锁被别人持有）时 finally 照常执行 finishAgentAction，这是安全的：
+    // finishAgent 校验 state.runId === runId，持有者是别人就不会被误释放。
     try {
+        stream.beginAgentAction({ runId, conversationKey, action: input.action });
         if (visibleAgentAction) {
             stream.setAgentActing(true, input.action, input.selector ?? input.url);
             ctx.reportProgress?.(describeAction(input)); // C3：每个可见动作发一句人话旁白到对话/状态行
@@ -1129,11 +1545,20 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
                 clearTimeout(preTimer);
                 preTimer = null;
             }
-            return { ok: true, content: JSON.stringify(tabs.filter((tab) => claimed.has(tab.id))) };
+            return {
+                ok: true,
+                content: JSON.stringify(tabs.filter((tab) => claimed.has(tab.id))),
+            };
         }
         if (input.action === 'tabSwitch' && input.tabId) {
-            browserRunRegistry.assertTab(browserContext, input.tabId);
-            claimedTabId = input.tabId;
+            claimedTabId = await claimConversationTabById({
+                context: browserContext,
+                sessionName: BROWSER_SESSION,
+                bin,
+                globals,
+                runner: deps.run,
+                signal: preCtrl.signal,
+            }, input.tabId);
         }
         else if (input.action === 'tabClose' && input.tabId) {
             browserRunRegistry.assertTab(browserContext, input.tabId);
@@ -1149,20 +1574,24 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
                 signal: preCtrl.signal,
             });
         }
+        if (input.retention) {
+            browserRunRegistry.markTab(browserContext, claimedTabId, {
+                retention: input.retention,
+                ...(input.tabTitle ? { title: input.tabTitle } : {}),
+            });
+        }
         if (preTimer) {
             clearTimeout(preTimer);
             preTimer = null;
         }
         // 同一 (动作, 选择器) 连续失败到上限 → 拒绝再试，强制换路径。
         // 挡的是「原地换着选择器盲猜三五轮然后放弃」这个最常见的失败形状。
-        if (VERIFIED_BROWSER_ACTIONS.has(input.action)
-            && browserAttempts.failures(conversationKey, input.action, input.selector) >= BROWSER_FAILURE_LIMIT) {
+        if (VERIFIED_BROWSER_ACTIONS.has(input.action) &&
+            browserAttempts.failures(conversationKey, input.action, input.selector) >=
+                BROWSER_FAILURE_LIMIT) {
             return {
                 ok: false,
-                error: `[${input.action}] 这个目标（${input.selector ?? '无选择器'}）已经连续失败 `
-                    + `${BROWSER_FAILURE_LIMIT} 次，引擎暂停了对它的重试。\n`
-                    + '请先 snapshot 看清当前页面到底是什么状态（观测不受限制），换一个元素引用或换一条路径；'
-                    + '如果判断不出来，就把现状如实告诉用户，不要继续盲试。',
+                error: `[${input.action}] 这个目标（${input.selector ?? '无选择器'}）已经连续失败 ${BROWSER_FAILURE_LIMIT} 次，引擎暂停了对它的重试。\n请先 snapshot 看清当前页面到底是什么状态（观测不受限制），换一个元素引用或换一条路径；如果判断不出来，就把现状如实告诉用户，不要继续盲试。`,
             };
         }
         const outcome = await runSequence(async (run) => {
@@ -1170,18 +1599,22 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             // 标签页**上取。缓存不行（navigate 只写「请求的」URL，非监督宿主恒 about:blank，
             // 一个 302 就让白名单以为你还在 allowed 站点）；锁外也不行（那时标签页还没切）。
             if (DEVELOPER_MODE_ACTIONS.has(input.action)) {
-                const originError = requireAllowedDeveloperOrigin(await resolveLiveUrl(run) ?? stream.getCurrentUrl(), browserConfig.allowedCdpOrigins);
+                const originError = requireAllowedDeveloperOrigin((await resolveLiveUrl(run)) ?? stream.getCurrentUrl(), browserConfig.allowedCdpOrigins);
                 if (originError)
                     return { blocked: originError };
             }
-            if (input.action === 'click' && input.selector && input.intent !== 'submit') {
+            if (input.action === 'click' &&
+                input.selector &&
+                input.intent !== 'submit') {
                 // The model is expected to mark final actions, but safety cannot depend
                 // solely on model compliance. Inspect the actual target's visible label
                 // and reject an obvious irreversible click until it is explicitly marked.
                 const target = await run(['get', 'text', input.selector]);
                 const targetLabel = `${input.selector}\n${target.code === 0 ? target.stdout : ''}`;
                 if (isLikelyIrreversibleBrowserTarget(targetLabel)) {
-                    return { blocked: '该控件看起来会执行发布、提交、购买、删除或发送操作。请仅在用户当前任务已明确授权时，使用 intent="submit" 重试。' };
+                    return {
+                        blocked: '该控件看起来会执行发布、提交、购买、删除或发送操作。请仅在用户当前任务已明确授权时，使用 intent="submit" 重试。',
+                    };
                 }
             }
             // C4：交互动作前点亮 AI 指针——把目标元素中心作为语义终点发给面板，让用户看见「手」移到目标 + 动作动效。
@@ -1191,7 +1624,12 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             if (supervised && input.selector && POINTER_ACTIONS.has(input.action)) {
                 const targetCenter = parsePointerCenter(await run(['get', 'box', input.selector, '--json']));
                 if (targetCenter) {
-                    stream.setAgentPointer({ x: targetCenter.x, y: targetCenter.y, visible: true, action: pointerActionFor(input.action) });
+                    stream.setAgentPointer({
+                        x: targetCenter.x,
+                        y: targetCenter.y,
+                        visible: true,
+                        action: pointerActionFor(input.action),
+                    });
                     flashTargetElement(stream, input.selector); // 点亮目标元素绿框，强化「AI 在点这里」
                     pointerShown = true;
                 }
@@ -1231,8 +1669,11 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             // 再采样纯属白付一次往返 + 一段等待。噪声是页面的持续属性，动作后测与
             // 动作前测等价——而放在后面测，这段等待就不再推迟动作本身的发出。
             let noiseAfter;
-            if (verified && result.code === 0 && before !== undefined && probeSnapshot
-                && differingLineIndexes(before, probeSnapshot)?.size) {
+            if (verified &&
+                result.code === 0 &&
+                before !== undefined &&
+                probeSnapshot &&
+                differingLineIndexes(before, probeSnapshot)?.size) {
                 await sleep(NOISE_BASELINE_GAP_MS, signal);
                 const again = await run(['snapshot']);
                 if (again.code === 0)
@@ -1242,7 +1683,7 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
         });
         if (outcome.blocked !== undefined)
             return { ok: false, error: outcome.blocked };
-        const { result, before: beforeSnapshot, probeSnapshot, noiseAfter } = outcome;
+        const { result, before: beforeSnapshot, probeSnapshot, noiseAfter, } = outcome;
         if (result.code === 0 && input.action === 'tabSwitch') {
             browserContext.activeTabId = claimedTabId;
         }
@@ -1262,7 +1703,10 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             stream.setCurrentUrl(normalizeUrl(input.url));
         }
         const challengeText = `${result.stdout}\n${result.stderr}\n${probeSnapshot}`;
-        const challenge = result.code === 0 ? detectBrowserChallenge(challengeText) : null;
+        // A failed click/navigation is a common way to discover a login, CAPTCHA,
+        // or bot-check page.  Do not gate detection on the CLI exit code or the
+        // agent will retry the challenge as if it were an ordinary locator miss.
+        const challenge = detectBrowserChallenge(challengeText);
         if (challenge && !supervised) {
             // 非受监督宿主（CLI -p / TUI / gateway）无可见浏览器、无人可接管：绝不阻塞等人。
             // 拿一张现场快照，连同「需真人验证、当前环境无法越过」如实返回。用 ok:true（非 ok:false）
@@ -1271,9 +1715,7 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             const snapshot = probe.code === 0 ? probe.stdout.trim() : '';
             return {
                 ok: true,
-                content: `⚠️ ${challenge.summary}。当前为非交互环境（无可见浏览器供真人介入），无法自动越过该关卡。`
-                    + `请如实告知用户此页面需人工验证/登录后才能继续，不要反复重试或索要凭据。`
-                    + (snapshot ? `\n\n当前页面快照：\n${snapshot}` : ''),
+                content: `⚠️ ${challenge.summary}。当前为非交互环境（无可见浏览器供真人介入），无法自动越过该关卡。请如实告知用户此页面需人工验证/登录后才能继续，不要反复重试或索要凭据。${snapshot ? `\n\n当前页面快照：\n${snapshot}` : ''}`,
             };
         }
         // challenge 自动暂停 与 用户点「接管」（requestHuman('manual')）都会把控制切到 waiting_human，
@@ -1290,7 +1732,9 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             if (pointerShown) {
                 stream.setAgentPointer({ x: 0, y: 0, visible: false });
             }
-            ctx.reportProgress?.(challenge ? `${challenge.summary}，等待你在浏览器中处理` : '你已接管浏览器，处理完成后点“完成并继续”');
+            ctx.reportProgress?.(challenge
+                ? `${challenge.summary}，等待你在浏览器中处理`
+                : '你已接管浏览器，处理完成后点“完成并继续”');
             const resolution = await stream.waitForHuman(signal);
             if (resolution === 'stopped')
                 return { ok: false, error: `[${input.action}] 浏览器任务已由用户停止` };
@@ -1325,10 +1769,9 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
                     stream.setAgentCandidates(candidates.map((c) => ({ ref: c.ref, line: c.line })), input.selector);
                 }
                 const hint = candidates.length
-                    ? '\n\n【最接近的候选元素】直接用下面的 @eN 引用重试，不要再猜选择器：\n'
-                        // ⚠️ 必须显式给出 `@eN`。曾经只贴原始快照行，而行里写的是 `[ref=e3]` ——
-                        // 提示语让模型用 @eN，展示的却是另一种写法，等于什么也没告诉它。
-                        + candidates.map((c) => `  ${c.ref}  ←  ${c.line}`).join('\n')
+                    ? `\n\n【最接近的候选元素】直接用下面的 @eN 引用重试，不要再猜选择器：\n${candidates
+                        .map((c) => `  ${c.ref}  ←  ${c.line}`)
+                        .join('\n')}`
                     : '';
                 return {
                     ...base,
@@ -1339,6 +1782,48 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
             }
             return base;
         }
+        // WebBrowser's legacy page-assets action used to be only an eval alias.
+        // Materialize the requested bundle at this boundary so the advertised
+        // action actually creates `manifest.json` and asset files.
+        if (input.action === 'bundlePageAssets') {
+            const parsed = parseEvalJson(result.stdout);
+            if (!Array.isArray(parsed)) {
+                return {
+                    ok: false,
+                    error: '页面资产返回格式无效，无法打包。请先使用 pageAssets 查看页面资源。',
+                };
+            }
+            try {
+                const bundle = await bundlePageAssets(parsed, input.bundleDir, async (url) => {
+                    const fetched = parseEvalJson((await runAction(['eval', browserAssetFetchExpression(url)]))
+                        .stdout);
+                    if (!fetched ||
+                        typeof fetched !== 'object' ||
+                        fetched.ok !== true ||
+                        typeof fetched.base64 !== 'string') {
+                        const status = fetched && typeof fetched === 'object'
+                            ? String(fetched.status ?? 'unknown')
+                            : 'unknown';
+                        throw new Error(`浏览器上下文抓取资源失败 HTTP ${status}`);
+                    }
+                    const value = fetched;
+                    return new Response(Buffer.from(value.base64, 'base64'), {
+                        status: 200,
+                        headers: value.type ? { 'content-type': value.type } : undefined,
+                    });
+                });
+                return {
+                    ok: true,
+                    content: clampResult(JSON.stringify({ assets: parsed, bundle }, null, 2)),
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: `页面资产打包失败：${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
         const verdict = VERIFIED_BROWSER_ACTIONS.has(input.action)
             ? classifyPageEffect(beforeSnapshot, probeSnapshot || undefined, noiseAfter)
             : null;
@@ -1357,22 +1842,27 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
         // 关键节点（navigate 加载完成 / snapshot 读取页面）确定性截当前可见画面，作为「地面真相」附到结果上，
         // 由主循环回填成一条带图 user 消息喂视觉模型自我核验。仅基座支持识图时截（否则跳过，不浪费 I/O、不假装核验）；
         // 截图失败绝不影响原动作结果（纯增强）。
-        if (finalResult.ok && KEY_NODE_SHOT_ACTIONS.has(input.action)
-            && ctx.provider?.supportsVision === true && !signal?.aborted) {
+        if (finalResult.ok &&
+            KEY_NODE_SHOT_ACTIONS.has(input.action) &&
+            ctx.provider?.supportsVision === true &&
+            !signal?.aborted) {
             try {
                 const shotPath = await createArtifactPath('browser-verify', 'png');
                 const shot = await runAction(['screenshot', shotPath]);
                 if (shot.code === 0) {
-                    const shots = [{ source: shotPath, detail: 'low', maxLongSidePixel: 1400 }];
+                    const shots = [
+                        { source: shotPath, detail: 'low', maxLongSidePixel: 1400 },
+                    ];
                     return {
                         ...finalResult,
-                        content: finalResult.content
-                            + '\n\n[已在关键节点截取当前可见页面，见随后的实况画面——请对照核对是否真的到达/呈现了预期状态，不要假设成功。]',
+                        content: `${finalResult.content}\n\n[已在关键节点截取当前可见页面，见随后的实况画面——请对照核对是否真的到达/呈现了预期状态，不要假设成功。]`,
                         visionImages: shots,
                     };
                 }
             }
-            catch { /* 截图纯增强，失败不影响动作结果 */ }
+            catch {
+                /* 截图纯增强，失败不影响动作结果 */
+            }
         }
         return finalResult;
     }
@@ -1380,7 +1870,10 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
         if (signal?.aborted)
             return { ok: false, error: `[${input.action}] 浏览器任务已被中断` };
         if (error instanceof BrowserTabError) {
-            return { ok: false, error: `[${input.action}] ${error.code}: ${error.message}` };
+            return {
+                ok: false,
+                error: `[${input.action}] ${error.code}: ${error.message}`,
+            };
         }
         return {
             ok: false,
@@ -1388,14 +1881,29 @@ async function call(input, signal, deps = defaultDeps, ctx = {}) {
         };
     }
     finally {
-        if (visibleAgentAction)
-            stream.setAgentActing(false);
-        if (pointerShown)
-            stream.setAgentPointer({ x: 0, y: 0, visible: false }); // C4：动作结束淡出指针
+        // ⚠️ 释放排在**第一位**，且下面两个装饰动作各自吞掉异常。
+        // 它们都会 emit 到宿主注入的 listener（Desktop 面板 / server 推流），listener 一抛错
+        // 就会吃掉它后面的所有语句 —— 排在后面的释放因此永远不执行，锁泄漏。
+        // 一把进程级单例锁的命运不该由 UI 增强的成败决定；反过来，两个装饰之间也不该互相牵连。
         stream.finishAgentAction(runId);
+        try {
+            if (visibleAgentAction)
+                stream.setAgentActing(false);
+        }
+        catch {
+            /* 面板装饰，失败不影响动作结果，更不该影响锁 */
+        }
+        try {
+            if (pointerShown)
+                stream.setAgentPointer({ x: 0, y: 0, visible: false }); // C4：动作结束淡出指针
+        }
+        catch {
+            /* 同上 */
+        }
         if (preTimer)
             clearTimeout(preTimer);
         signal?.removeEventListener('abort', abortPreFromParent);
+        browserRunRegistry.finish(conversationKey, runId);
     }
 }
 /** 把「这次操作生效了没有」的结论并进结果。空结论不加噪声。 */
@@ -1408,9 +1916,33 @@ function appendEffectNote(base, note) {
 function clampResult(text) {
     if (text.length <= DEFAULT_MAX_RESULT_SIZE_CHARS)
         return text;
-    return (text.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)
-        + `\n\n…（输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符已截断；`
-        + '需要完整内容请缩小选择器范围或分段读取）');
+    return `${text.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n\n…（输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符已截断；需要完整内容请缩小选择器范围或分段读取）`;
+}
+/**
+ * agent-browser returns the value of `eval` as JSON in current releases, but
+ * older versions wrapped JSON strings in a quoted envelope. Keep this
+ * compatibility parsing at the adapter boundary so page-assets remains a
+ * real capability in WebBrowser rather than an alias that only lists assets.
+ */
+function parseEvalJson(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const value = JSON.parse(trimmed);
+        if (typeof value === 'string') {
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
 }
 function toToolResult(action, r, outPath) {
     if (r.code === 0) {
@@ -1420,7 +1952,10 @@ function toToolResult(action, r, outPath) {
         // 错误路径截了、withPostActionSnapshot 截了，唯独最常走的这条没截。
         const body = clampResult(r.stdout.trim());
         if (outPath) {
-            return { ok: true, content: body ? `${body}\nSaved: ${outPath}` : `Saved: ${outPath}` };
+            return {
+                ok: true,
+                content: body ? `${body}\nSaved: ${outPath}` : `Saved: ${outPath}`,
+            };
         }
         if (action === 'cookiesGet') {
             return { ok: true, content: body || '[]' };