minimal-agent 0.13.0 → 0.14.0

package/src/tools/webbrowser/webbrowser.ts

@@ -25,15 +25,24 @@
 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 type { ImageInputSpec, Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
 import { configService } from '../../config/configService.js';
-import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import type {
+  ImageInputSpec,
+  Tool,
+  ToolCallContext,
+  ToolResult,
+} from '../../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { resolveAgentBrowserPath } from './agentBrowserPath.js';
 import {
+  type AgentBrowserRun,
+  type AgentBrowserRunner,
+  BROWSER_SESSION,
   browserArtifactDir,
   createArtifactPath,
   isAllowedBrowserScheme,
@@ -41,31 +50,45 @@ import {
   sessionArgs,
   spawnRunner,
   validateArtifactOutputPath,
-  BROWSER_SESSION,
-  type AgentBrowserRun,
-  type AgentBrowserRunner,
 } from './browser.js';
-import { getWorkingDir } from '../../bootstrap/workingDir.js';
-import { ensureDaemon, stopDaemon, getStreamPort } from './browserDaemon.js';
-import { getBrowserStream, type BrowserStream } from './browserStream.js';
-import { browserService } from './browserService.js';
-import { detectBrowserChallenge } from './browserControl.js';
+import { browserDownloadDir } from './browserAutomation.js';
 import {
-  browserRunRegistry,
-  isLikelyIrreversibleBrowserTarget,
-} from './browserRunRegistry.js';
+  type BrowserPageAsset,
+  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,
-  BROWSER_FAILURE_LIMIT,
-  VERIFIED_BROWSER_ACTIONS,
 } from './browserOutcome.js';
+import {
+  recoverableAgentBrowserRunFailure,
+  withBrowserRecovery,
+} from './browserRecovery.js';
+import {
+  browserRunRegistry,
+  isLikelyIrreversibleBrowserTarget,
+} from './browserRunRegistry.js';
+import { browserService } from './browserService.js';
+import { type BrowserStream, getBrowserStream } from './browserStream.js';
 import {
   BrowserTabError,
+  claimConversationTabById,
   createConversationTab,
   ensureConversationTab,
   listBrowserTabs,
@@ -83,7 +106,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']);
@@ -161,7 +191,12 @@ async function viewportPoint(
   } 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 侧不报错，只会点到边缘，症状是"点了但没反应"。
@@ -192,11 +227,16 @@ async function runPointerAt(
       code: 1,
       stdout: '',
       stderr:
-        '无法取得视口尺寸，坐标点击已放弃 —— 与其按一个猜出来的尺寸点在错误位置，'
-        + '不如不点。请确认页面已加载（先 navigate 或 snapshot），或改用选择器定位。',
+        '无法取得视口尺寸，坐标点击已放弃 —— 与其按一个猜出来的尺寸点在错误位置，' +
+        '不如不点。请确认页面已加载（先 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') {
     return { ...moved, stdout: `hovered at (${point.px}, ${point.py})` };
@@ -205,7 +245,10 @@ async function runPointerAt(
   if (down.code !== 0) return down;
   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}]`,
+  };
 }
 
 /**
@@ -233,9 +276,16 @@ async function resolveLiveUrl(
   }
 }
 
-function requireAllowedDeveloperOrigin(url: string, allowedOrigins: string[]): string | null {
+function requireAllowedDeveloperOrigin(
+  url: string,
+  allowedOrigins: string[],
+): string | null {
   let origin: string;
-  try { origin = new URL(url).origin; } catch { return '当前页面没有可授权的 HTTP(S) 站点'; }
+  try {
+    origin = new URL(url).origin;
+  } catch {
+    return '当前页面没有可授权的 HTTP(S) 站点';
+  }
   if (!/^https?:\/\//i.test(origin) || !allowedOrigins.includes(origin)) {
     return `Developer Mode 尚未授权当前站点：${origin}。请在“设置 → 浏览器”添加该站点。`;
   }
@@ -252,7 +302,16 @@ const inputSchema = z.object({
       'forward',
       'reload',
       'snapshot',
+      'frameInfo',
       'getContent',
+      'pageAssets',
+      'listPageAssets',
+      'bundlePageAssets',
+      'exportContent',
+      'clipboardReadText',
+      'clipboardWriteText',
+      'clipboardRead',
+      'clipboardWrite',
       'screenshot',
       'click',
       'fill',
@@ -296,13 +355,27 @@ 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()
-    .describe('Element selector: CSS selector, @eN ref from snapshot, or data-ab-pick-ref from pick'),
+    .describe(
+      'Element selector: CSS selector, @eN ref from snapshot, or data-ab-pick-ref from pick',
+    ),
   /**
    * 视口比例坐标（0–1000），`click` / `hover` 在**没有可用选择器**时的兜底定位。
    *
@@ -314,19 +387,74 @@ const inputSchema = z.object({
    *
    * 与 ComputerUse 的坐标系**刻意一致**（同为 0–1000），模型不必为两个工具切换心智。
    */
-  x: z.number().min(0).max(1000).optional()
-    .describe('视口比例横坐标 0-1000（左=0，右=1000）。仅在没有可用选择器时用；必须与 y 同时提供'),
-  y: z.number().min(0).max(1000).optional()
-    .describe('视口比例纵坐标 0-1000（上=0，下=1000）。仅在没有可用选择器时用；必须与 x 同时提供'),
+  x: z
+    .number()
+    .min(0)
+    .max(1000)
+    .optional()
+    .describe(
+      '视口比例横坐标 0-1000（左=0，右=1000）。仅在没有可用选择器时用；必须与 y 同时提供',
+    ),
+  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)'),
+    .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)'),
   annotate: z
     .boolean()
     .optional()
@@ -339,18 +467,48 @@ 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({
@@ -362,19 +520,53 @@ 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()
@@ -388,20 +580,53 @@ const inputSchema = z.object({
     // 探测 → 元素盒子 → 前置快照 → 动作 → 稳定重探 → 可选噪声基线」，这个预算盖住
     // 全部。描述必须说清楚，否则调用方按「单个动作」估的值会把前后探测一起掐掉。
     .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)',
+      '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'),
+    .describe(
+      'Use submit for the final irreversible action, such as publish, purchase, delete, or form submission',
+    ),
 });
 type WebBrowserInput = z.infer<typeof inputSchema>;
 
 const OBSERVE_ACTIONS = new Set<WebBrowserInput['action']>([
-  '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<WebBrowserInput['action']>([
+  'pageAssets',
+  'exportContent',
+  'clipboardReadText',
+  'clipboardWriteText',
+  'clipboardRead',
+  'clipboardWrite',
+  'frameInfo',
+  'listPageAssets',
+  'bundlePageAssets',
 ]);
 
 const parameters = toToolParameters(inputSchema);
@@ -444,7 +669,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.
@@ -526,12 +756,14 @@ const defaultDeps: WebBrowserDeps = {
  * 表驱动，新增一个写文件的动作却忘了登记，会在 `call()` 里拿不到已解析路径而立刻暴露，
  * 而不是悄悄绕过校验。
  */
-export const ARTIFACT_ACTIONS: Record<string, { prefix: string; ext: string }> = {
-  screenshot: { prefix: 'browser-screenshot', ext: 'png' },
-  pdf: { prefix: 'browser-page', ext: 'pdf' },
-  recordStart: { prefix: 'recording', ext: 'webm' },
-  traceStop: { prefix: 'browser-trace', ext: 'json' },
-};
+export const ARTIFACT_ACTIONS: Record<string, { prefix: string; ext: string }> =
+  {
+    screenshot: { prefix: 'browser-screenshot', ext: 'png' },
+    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` 校验的落盘路径。
@@ -541,14 +773,24 @@ export const ARTIFACT_ACTIONS: Record<string, { prefix: string; ext: string }> =
 function buildSubArgs(
   input: WebBrowserInput,
   resolvedOutPath?: string,
-): { args: string[]; outPath?: string; metaAction?: string; pointerAction?: 'click' | 'hover' } | { error: string } {
+):
+  | {
+      args: string[];
+      outPath?: string;
+      metaAction?: string;
+      pointerAction?: 'click' | 'hover';
+    }
+  | { error: string } {
   const { action } = input;
 
   switch (action) {
     case 'start': {
       const args: string[] = [];
       if (input.viewportWidth && input.viewportHeight) {
-        args.push('--viewport', `${input.viewportWidth}x${input.viewportHeight}`);
+        args.push(
+          '--viewport',
+          `${input.viewportWidth}x${input.viewportHeight}`,
+        );
       }
       return { args, metaAction: 'start' };
     }
@@ -574,13 +816,47 @@ function buildSubArgs(
 
     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() 校验后传入）` };
+      if (!out)
+        return {
+          error: `${action} 需要已解析的输出路径（由 call() 校验后传入）`,
+        };
       const args = ['screenshot', out];
       if (input.annotate) args.push('--annotate');
       if (input.fullPage) args.push('--full');
@@ -592,10 +868,30 @@ function buildSubArgs(
       // 那三条必须在同一把锁内连发，中途被别的会话插进来就点在别的地方了。
       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' };
@@ -609,14 +905,17 @@ function buildSubArgs(
     case 'hover':
       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': {
       const args = ['scroll'];
       if (input.selector) args.push(input.selector);
-      if (input.direction) args.push('--' + input.direction);
+      if (input.direction) args.push(`--${input.direction}`);
       if (input.scrollY) args.push('--by-y', String(input.scrollY));
       if (input.scrollX) args.push('--by-x', String(input.scrollX));
       return { args };
@@ -624,14 +923,18 @@ function buildSubArgs(
 
     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,
@@ -642,8 +945,21 @@ function buildSubArgs(
       if (input.waitText) return { args: ['wait', '--text', input.waitText] };
       if (input.waitLoad) 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' };
@@ -651,7 +967,10 @@ function buildSubArgs(
 
     case 'pdf': {
       const out = resolvedOutPath ?? input.path;
-      if (!out) return { error: `${action} 需要已解析的输出路径（由 call() 校验后传入）` };
+      if (!out)
+        return {
+          error: `${action} 需要已解析的输出路径（由 call() 校验后传入）`,
+        };
       return { args: ['pdf', out], outPath: out };
     }
 
@@ -659,9 +978,15 @@ function buildSubArgs(
       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' };
       return { args: ['tab', input.tabId] };
@@ -673,15 +998,26 @@ function buildSubArgs(
     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': {
@@ -689,7 +1025,11 @@ function buildSubArgs(
       if (input.devicePreset) {
         args.push(input.devicePreset);
       } else if (input.viewportWidth && input.viewportHeight) {
-        args.push('--viewport', String(input.viewportWidth), String(input.viewportHeight));
+        args.push(
+          '--viewport',
+          String(input.viewportWidth),
+          String(input.viewportHeight),
+        );
       }
       return { args };
     }
@@ -697,20 +1037,28 @@ function buildSubArgs(
     case 'setMedia': {
       const args = ['set', 'media'];
       if (input.colorScheme) args.push('--color-scheme', input.colorScheme);
-      if (input.offline !== undefined) args.push('--offline', input.offline ? 'on' : 'off');
+      if (input.offline !== undefined)
+        args.push('--offline', input.offline ? 'on' : 'off');
       return { args };
     }
 
     case 'recordStart': {
       const out = resolvedOutPath ?? input.path;
-      if (!out) return { error: `${action} 需要已解析的输出路径（由 call() 校验后传入）` };
+      if (!out)
+        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'] };
 
@@ -720,7 +1068,8 @@ function buildSubArgs(
       return { args: [], metaAction: 'pickElement' };
     }
     case 'markElement': {
-      if (!input.selector) return { error: 'markElement requires selector parameter' };
+      if (!input.selector)
+        return { error: 'markElement requires selector parameter' };
       return { args: [], metaAction: 'markElement' };
     }
     case 'clearMarks':
@@ -732,25 +1081,45 @@ function buildSubArgs(
       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() 校验后传入）` };
+      if (!out)
+        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' };
+      if (!input.reactId)
+        return { error: 'reactInspect requires reactId parameter' };
       return { args: ['react', 'inspect', input.reactId] };
 
     default:
@@ -780,7 +1149,8 @@ async function handleMetaAction(
     switch (action) {
       case 'start': {
         const info = await ensureDaemon(BROWSER_SESSION, { signal });
-        const streamPort = info.streamPort ?? (await getStreamPort(BROWSER_SESSION));
+        const streamPort =
+          info.streamPort ?? (await getStreamPort(BROWSER_SESSION));
         stream.setMode('browse');
         // actor 点亮媒体面：受监督宿主下把截屏流连上，面板从此刻起就能显示 agent 的画面，
         // 不再依赖面板自启动（曾因面板 browser/start 竞态/连到坏 daemon 而「开着却全黑」）。
@@ -805,7 +1175,10 @@ async function handleMetaAction(
         // ⚠️ 这只覆盖「显式 stop」这一条路径；进程被 kill、宿主直接丢弃会话时仍然
         // 留残留——彻底收口需要宿主在会话结束时主动调 `forgetConversation`。
         const key = ctx.browserRun?.conversationKey;
-        if (key) { browserRunRegistry.forgetConversation(key); browserAttempts.forget(key); }
+        if (key) {
+          browserRunRegistry.forgetConversation(key);
+          browserAttempts.forget(key);
+        }
         return { ok: true, content: '[stop] browser stopped' };
       }
       case 'streamInfo': {
@@ -827,7 +1200,11 @@ async function handleMetaAction(
         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': {
@@ -837,15 +1214,30 @@ async function handleMetaAction(
       }
       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 });
+        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: 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}` };
       }
@@ -865,27 +1257,45 @@ async function handleMetaAction(
 function describeAction(input: WebBrowserInput): string {
   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 枚举）。 */
-function pointerActionFor(action: WebBrowserInput['action']): 'move' | 'click' | 'type' | 'hover' {
+function pointerActionFor(
+  action: WebBrowserInput['action'],
+): 'move' | 'click' | 'type' | 'hover' {
   if (action === 'fill' || action === 'type') return 'type';
   if (action === 'hover') return 'hover';
   if (action === 'drag') return 'move';
@@ -900,7 +1310,10 @@ async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
       signal?.removeEventListener('abort', onAbort);
       resolve();
     }, ms);
-    const onAbort = () => { clearTimeout(timer); resolve(); };
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
     signal?.addEventListener('abort', onAbort, { once: true });
   });
 }
@@ -909,7 +1322,12 @@ async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  * Pure visual enhancement - failures are silently ignored (never block the action). */
 function flashTargetElement(stream: BrowserStream, selector: string): void {
   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 {
     // Highlight is cosmetic only; failures must never break the action.
@@ -922,7 +1340,12 @@ function parsePointerCenter(
 ): { x: number; y: number } | null {
   try {
     if (result.code !== 0) return null;
-    const box = JSON.parse(result.stdout.trim()) as { x?: number; y?: number; width?: number; height?: number };
+    const box = JSON.parse(result.stdout.trim()) as {
+      x?: number;
+      y?: number;
+      width?: number;
+      height?: number;
+    };
     const x = Number(box.x);
     const y = Number(box.y);
     const w = Number(box.width);
@@ -970,7 +1393,10 @@ export async function settleSnapshot(
 }
 
 /** C1：成功且拿到探测快照时，把「操作后页面快照」并入动作结果，省掉模型再单独调 snapshot 的往返。 */
-function withPostActionSnapshot(base: ToolResult, snapshot: string): ToolResult {
+function withPostActionSnapshot(
+  base: ToolResult,
+  snapshot: string,
+): ToolResult {
   if (!base.ok || !snapshot) return base;
   // 成功路径同样要走预算：一次 navigate 后的整页快照在真实站点上轻松几万字符，
   // 而模型下一步真正会用到的只是那些带 ref 的可操作行。
@@ -985,7 +1411,8 @@ async function call(
   ctx: ToolCallContext = {},
 ): Promise<ToolResult> {
   const browserConfig = await configService.browser();
-  if (!browserConfig.enabled) return { ok: false, error: '内置浏览器已在设置中关闭' };
+  if (!browserConfig.enabled)
+    return { ok: false, error: '内置浏览器已在设置中关闭' };
 
   // 顺序是有讲究的：**纯参数校验排在一切副作用之前**。
   // 解析二进制、起 daemon、问页面 URL 都是有代价的动作，参数本来就不合法时不该发生
@@ -994,12 +1421,14 @@ async function call(
 
   // `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 授权）。`,
     };
   }
 
@@ -1014,13 +1443,45 @@ async function call(
         ...(ctx.browserRun?.allowedUploadRoots ?? []),
       ];
       const checked = await validateArtifactOutputPath(input.path, roots);
-      if (!checked.ok) return { ok: false, error: `[${input.action}] ${checked.error}` };
+      if (!checked.ok)
+        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 };
 
@@ -1039,17 +1500,24 @@ async function call(
         '简单网页读取可改用 WebFetch（无需浏览器）。',
     };
   }
-
   // 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();
-  const conversationKey = ctx.browserRun?.conversationKey ?? `headless:${process.pid}`;
+  const conversationKey =
+    ctx.browserRun?.conversationKey ?? `headless:${process.pid}`;
   const browserContext = browserRunRegistry.ensure({
     conversationKey,
     runId,
@@ -1059,36 +1527,65 @@ async function call(
     allowedUploadRoots: ctx.browserRun?.allowedUploadRoots,
   });
   try {
-    browserRunRegistry.requireGrant(browserContext, OBSERVE_ACTIONS.has(input.action) ? 'observe' : 'interact');
+    browserRunRegistry.requireGrant(
+      browserContext,
+      OBSERVE_ACTIONS.has(input.action) ? 'observe' : 'interact',
+    );
     if (input.action === 'upload') {
       browserRunRegistry.requireGrant(browserContext, 'upload');
-      const roots = await Promise.all(browserContext.allowedUploadRoots.map(async (root) => {
-        try { return await realpath(root); } catch { return resolve(root); }
-      }));
-      if (roots.length === 0) return { ok: false, error: '当前浏览器任务没有获批的文件上传范围' };
+      const roots = await Promise.all(
+        browserContext.allowedUploadRoots.map(async (root) => {
+          try {
+            return await realpath(root);
+          } catch {
+            return resolve(root);
+          }
+        }),
+      );
+      if (roots.length === 0)
+        return { ok: false, error: '当前浏览器任务没有获批的文件上传范围' };
       for (const file of input.files ?? []) {
         let canonical: string;
-        try { canonical = await realpath(file); }
-        catch { return { ok: false, error: `上传文件不存在或不可读取：${file}` }; }
+        try {
+          canonical = await realpath(file);
+        } catch {
+          return { ok: false, error: `上传文件不存在或不可读取：${file}` };
+        }
         const allowed = roots.some((root) => {
           const rel = relative(root, canonical);
           return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
         });
-        if (!allowed) return { ok: false, error: `上传文件超出当前任务批准范围：${file}` };
+        if (!allowed)
+          return { ok: false, error: `上传文件超出当前任务批准范围：${file}` };
       }
     }
-    if (input.intent === 'submit') browserRunRegistry.requireGrant(browserContext, 'submit');
+    if (input.intent === 'submit')
+      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: ReturnType<typeof setTimeout> | null = setTimeout(() => preCtrl.abort(), input.timeout ?? 120_000);
+  let preTimer: ReturnType<typeof setTimeout> | null = setTimeout(
+    () => preCtrl.abort(),
+    input.timeout ?? 120_000,
+  );
   const abortPreFromParent = () => preCtrl.abort(signal?.reason);
   if (signal) {
     if (signal.aborted) preCtrl.abort();
@@ -1123,27 +1620,70 @@ async function call(
       else 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({
-        sessionName: BROWSER_SESSION,
-        bin,
-        runner: deps.run,
-        signal: ac.signal,
-      }, async (run) => {
-        let tabEnsured = false;
-        // 标签页只在本序列的第一条命令前切一次：同一把锁内没人能把它切走，
-        // 每条都切纯属浪费一次子进程往返。
-        const scoped = async (args: string[]): Promise<AgentBrowserRun> => {
-          if (claimedTabId && !tabEnsured) {
-            const switched = await run([...sessionArgs(BROWSER_SESSION), 'tab', claimedTabId]);
-            if (switched.code !== 0) return switched;
-            tabEnsured = true;
-          }
-          return run([...sessionArgs(BROWSER_SESSION), ...args]);
-        };
-        return body(scoped);
-      });
+      return await withBrowserRecovery(
+        () =>
+          browserService.exclusive(
+            {
+              sessionName: BROWSER_SESSION,
+              bin,
+              runner: deps.run,
+              signal: ac.signal,
+            },
+            async (run) => {
+              let tabEnsured = false;
+              // 标签页只在本序列的第一条命令前切一次：同一把锁内没人能把它切走，
+              // 每条都切纯属浪费一次子进程往返。
+              const scoped = async (
+                args: string[],
+              ): Promise<AgentBrowserRun> => {
+                if (claimedTabId && !tabEnsured) {
+                  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;
+                }
+                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 {
       clearTimeout(to);
       signal?.removeEventListener('abort', onParent);
@@ -1155,14 +1695,18 @@ async function call(
   const runAction = (args: string[]): Promise<AgentBrowserRun> =>
     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：每个可见动作发一句人话旁白到对话/状态行
@@ -1176,15 +1720,21 @@ async function call(
     // different conversation and actions silently cross session boundaries.
     const globals = sessionArgs(BROWSER_SESSION);
     if (input.action === 'tabNew') {
-      const tabId = await createConversationTab({
-        context: browserContext,
-        sessionName: BROWSER_SESSION,
-        bin,
-        globals,
-        runner: deps.run,
-        signal: preCtrl.signal,
-      }, input.url ? normalizeUrl(input.url) : 'about:blank');
-      if (preTimer) { clearTimeout(preTimer); preTimer = null; }
+      const tabId = await createConversationTab(
+        {
+          context: browserContext,
+          sessionName: BROWSER_SESSION,
+          bin,
+          globals,
+          runner: deps.run,
+          signal: preCtrl.signal,
+        },
+        input.url ? normalizeUrl(input.url) : 'about:blank',
+      );
+      if (preTimer) {
+        clearTimeout(preTimer);
+        preTimer = null;
+      }
       return { ok: true, content: JSON.stringify({ tabId }) };
     }
     if (input.action === 'tabList') {
@@ -1195,13 +1745,30 @@ async function call(
         runner: deps.run,
         signal: preCtrl.signal,
       });
-      const claimed = new Set(browserRunRegistry.claimedTabs(browserContext.conversationKey));
-      if (preTimer) { clearTimeout(preTimer); preTimer = null; }
-      return { ok: true, content: JSON.stringify(tabs.filter((tab) => claimed.has(tab.id))) };
+      const claimed = new Set(
+        browserRunRegistry.claimedTabs(browserContext.conversationKey),
+      );
+      if (preTimer) {
+        clearTimeout(preTimer);
+        preTimer = null;
+      }
+      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);
       claimedTabId = input.tabId;
@@ -1215,19 +1782,27 @@ async function call(
         signal: preCtrl.signal,
       });
     }
-    if (preTimer) { clearTimeout(preTimer); preTimer = null; }
+    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 看清当前页面到底是什么状态（观测不受限制），换一个元素引用或换一条路径；如果判断不出来，就把现状如实告诉用户，不要继续盲试。`,
       };
     }
 
@@ -1239,27 +1814,40 @@ async function call(
     // 一段控制流——谁加一条提前 return，拿到的就是运行时 undefined。
     type SequenceOutcome =
       | { blocked: string }
-      | { blocked?: undefined; result: AgentBrowserRun; before?: string; probeSnapshot: string; noiseAfter?: string };
+      | {
+          blocked?: undefined;
+          result: AgentBrowserRun;
+          before?: string;
+          probeSnapshot: string;
+          noiseAfter?: string;
+        };
     const outcome = await runSequence<SequenceOutcome>(async (run) => {
       // 站点白名单：判据必须是**当前真实 URL**，而且要在**本次动作真正会落到的那个
       // 标签页**上取。缓存不行（navigate 只写「请求的」URL，非监督宿主恒 about:blank，
       // 一个 302 就让白名单以为你还在 allowed 站点）；锁外也不行（那时标签页还没切）。
       if (DEVELOPER_MODE_ACTIONS.has(input.action)) {
         const originError = requireAllowedDeveloperOrigin(
-          await resolveLiveUrl(run) ?? stream.getCurrentUrl(),
+          (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" 重试。',
+          };
         }
       }
 
@@ -1268,9 +1856,16 @@ async function call(
       // get box 是本地 daemon 调用（非 LLM 往返）；失败/找不到则不显示、动作照常执行（纯视觉增强，绝不阻断）。
       // 仅受监督(Desktop)驱动：headless 无面板 → 不调用、零开销。
       if (supervised && input.selector && POINTER_ACTIONS.has(input.action)) {
-        const targetCenter = parsePointerCenter(await run(['get', 'box', input.selector, '--json']));
+        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;
         }
@@ -1312,8 +1907,13 @@ async function call(
       // 再采样纯属白付一次往返 + 一段等待。噪声是页面的持续属性，动作后测与
       // 动作前测等价——而放在后面测，这段等待就不再推迟动作本身的发出。
       let noiseAfter: string | undefined;
-      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) noiseAfter = again.stdout.trim();
@@ -1321,20 +1921,31 @@ async function call(
 
       return { result, before, probeSnapshot, noiseAfter };
     });
-    if (outcome.blocked !== undefined) return { ok: false, error: outcome.blocked };
-    const { result, before: beforeSnapshot, probeSnapshot, noiseAfter } = outcome;
+    if (outcome.blocked !== undefined)
+      return { ok: false, error: outcome.blocked };
+    const {
+      result,
+      before: beforeSnapshot,
+      probeSnapshot,
+      noiseAfter,
+    } = outcome;
 
     if (result.code === 0 && input.action === 'tabSwitch') {
       browserContext.activeTabId = claimedTabId;
     } else if (result.code === 0 && input.action === 'tabClose') {
-      browserRunRegistry.releaseTab(browserContext.conversationKey, claimedTabId);
+      browserRunRegistry.releaseTab(
+        browserContext.conversationKey,
+        claimedTabId,
+      );
     }
 
     // 一次轻停（≤120ms）让点击落点/涟漪可见后再由 finally 淡出；不做更长的表演式停顿。
-    if (supervised && pointerShown && !signal?.aborted) await sleep(120, signal);
+    if (supervised && pointerShown && !signal?.aborted)
+      await sleep(120, signal);
 
     // 硬停止：整个 run 被父级 abort（底部 ■ / ESC / interrupt 队列）→ 立即返回，不进人工等待。
-    if (signal?.aborted) return { ok: false, error: `[${input.action}] 浏览器任务已被中断` };
+    if (signal?.aborted)
+      return { ok: false, error: `[${input.action}] 浏览器任务已被中断` };
 
     // URL 栏跟随 agent 导航（与 bridge 用户导航对齐，browserBridge.ts:228）：用户手输网址会更新 URL 栏，
     // agent 导航也应一致更新，否则面板「开着却网址栏空」。back/forward/reload 目标未知，靠媒体面连上后
@@ -1345,7 +1956,10 @@ async function call(
 
     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）
@@ -1354,25 +1968,31 @@ async function call(
       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，
     // 统一在此进入人工等待——接管已在 runAction 里即时掐断在跑动作，这里 result 可能是被掐断的部分结果。
-    if (challenge) stream.requestHuman(challenge.reason, {
-      runId,
-      conversationKey,
-      ownerId: 'local-owner',
-      summary: challenge.summary,
-    });
+    if (challenge)
+      stream.requestHuman(challenge.reason, {
+        runId,
+        conversationKey,
+        ownerId: 'local-owner',
+        summary: challenge.summary,
+      });
     if (supervised && stream.getControlState().status === 'waiting_human') {
       // 交人处理前先淡出 AI 指针：控制权已交给用户，橙色指针不该再滞留（否则像 Agent 还在指）。
-      if (pointerShown) { stream.setAgentPointer({ x: 0, y: 0, visible: false }); }
-      ctx.reportProgress?.(challenge ? `${challenge.summary}，等待你在浏览器中处理` : '你已接管浏览器，处理完成后点“完成并继续”');
+      if (pointerShown) {
+        stream.setAgentPointer({ x: 0, y: 0, visible: false });
+      }
+      ctx.reportProgress?.(
+        challenge
+          ? `${challenge.summary}，等待你在浏览器中处理`
+          : '你已接管浏览器，处理完成后点“完成并继续”',
+      );
       const resolution = await stream.waitForHuman(signal);
-      if (resolution === 'stopped') return { ok: false, error: `[${input.action}] 浏览器任务已由用户停止` };
+      if (resolution === 'stopped')
+        return { ok: false, error: `[${input.action}] 浏览器任务已由用户停止` };
       // resume 后控制权已回 running，runAction 取最新快照不会被误掐。
       const refreshed = await runAction(['snapshot']);
       const after = toToolResult('snapshot', refreshed);
@@ -1384,8 +2004,18 @@ async function call(
     }
     // ===== 成功率收口：失败要给现场 + 候选，成功要给「生效了没有」 =====
     if (VERIFIED_BROWSER_ACTIONS.has(input.action)) {
-      if (result.code === 0) browserAttempts.recordSuccess(conversationKey, input.action, input.selector);
-      else browserAttempts.recordFailure(conversationKey, input.action, input.selector);
+      if (result.code === 0)
+        browserAttempts.recordSuccess(
+          conversationKey,
+          input.action,
+          input.selector,
+        );
+      else
+        browserAttempts.recordFailure(
+          conversationKey,
+          input.action,
+          input.selector,
+        );
     }
 
     if (result.code !== 0) {
@@ -1405,23 +2035,84 @@ async function call(
           );
         }
         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,
           // 失败回执也走 clampResult：截断要说出来。以前这里是裸 `.slice()`，
           // 于是「后面还有内容」这件事只在成功路径告知，而失败恰恰是最需要知道的时候。
-          error: clampResult(`${base.error}${hint}\n\n【当前页面快照 @eN】\n${budgetSnapshot(probeSnapshot)}`),
+          error: clampResult(
+            `${base.error}${hint}\n\n【当前页面快照 @eN】\n${budgetSnapshot(probeSnapshot)}`,
+          ),
         };
       }
       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 as BrowserPageAsset[],
+          input.bundleDir!,
+          async (url) => {
+            const fetched = parseEvalJson(
+              (await runAction(['eval', browserAssetFetchExpression(url)]))
+                .stdout,
+            );
+            if (
+              !fetched ||
+              typeof fetched !== 'object' ||
+              (fetched as { ok?: unknown }).ok !== true ||
+              typeof (fetched as { base64?: unknown }).base64 !== 'string'
+            ) {
+              const status =
+                fetched && typeof fetched === 'object'
+                  ? String(
+                      (fetched as { status?: unknown }).status ?? 'unknown',
+                    )
+                  : 'unknown';
+              throw new Error(`浏览器上下文抓取资源失败 HTTP ${status}`);
+            }
+            const value = fetched as { base64: string; type?: string };
+            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)
+      ? classifyPageEffect(
+          beforeSnapshot,
+          probeSnapshot || undefined,
+          noiseAfter,
+        )
       : null;
     // 面板也要看得见：验证结论只进对话的话，盯着浏览器的人根本不知道刚那下没生效。
     // 走**自己的**帧而不是借 agent_acting——后者在 finally 里被无条件置回 false，
@@ -1445,38 +2136,62 @@ async function call(
     // 关键节点（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: ImageInputSpec[] = [{ source: shotPath, detail: 'low', maxLongSidePixel: 1400 }];
+          const shots: ImageInputSpec[] = [
+            { source: shotPath, detail: 'low', maxLongSidePixel: 1400 },
+          ];
           return {
             ...finalResult,
-            content: finalResult.content
-              + '\n\n[已在关键节点截取当前可见页面，见随后的实况画面——请对照核对是否真的到达/呈现了预期状态，不要假设成功。]',
+            content: `${finalResult.content}\n\n[已在关键节点截取当前可见页面，见随后的实况画面——请对照核对是否真的到达/呈现了预期状态，不要假设成功。]`,
             visionImages: shots,
           };
         }
-      } catch { /* 截图纯增强，失败不影响动作结果 */ }
+      } catch {
+        /* 截图纯增强，失败不影响动作结果 */
+      }
     }
     return finalResult;
   } catch (error) {
-    if (signal?.aborted) return { ok: false, error: `[${input.action}] 浏览器任务已被中断` };
+    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,
       error: `[${input.action}] ${error instanceof Error ? error.message : String(error)}`,
     };
   } 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);
   }
 }
 
@@ -1489,11 +2204,31 @@ function appendEffectNote(base: ToolResult, note: string | null): ToolResult {
 /** 把工具输出收进结果预算，超出时如实说明被截断（而不是悄悄截）。 */
 function clampResult(text: string): string {
   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: string): unknown {
+  const trimmed = stdout.trim();
+  if (!trimmed) return undefined;
+  try {
+    const value = JSON.parse(trimmed) as unknown;
+    if (typeof value === 'string') {
+      try {
+        return JSON.parse(value) as unknown;
+      } catch {
+        return value;
+      }
+    }
+    return value;
+  } catch {
+    return undefined;
+  }
 }
 
 function toToolResult(
@@ -1508,7 +2243,10 @@ function toToolResult(
     // 错误路径截了、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 || '[]' };
@@ -1534,7 +2272,8 @@ export const webbrowserTool: Tool<WebBrowserInput> = {
   isConcurrencySafe: false,
   maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
   call,
-  callWithContext: (input, signal, context) => call(input, signal, defaultDeps, context),
+  callWithContext: (input, signal, context) =>
+    call(input, signal, defaultDeps, context),
 };
 
 export const _webbrowserCall = call;