minimal-agent 0.13.0 → 0.14.0

package/src/tools/webbrowser/browserBatch.ts

@@ -0,0 +1,2382 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import {
+  copyFile,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import { basename, extname, isAbsolute, join, relative } from 'node:path';
+import { z } from 'zod';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { configService } from '../../config/configService.js';
+import type {
+  DeliverableManifest,
+  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 {
+  BROWSER_SESSION,
+  browserArtifactDir,
+  createArtifactPath,
+  sessionArgs,
+  spawnRunner,
+} from './browser.js';
+import {
+  BROWSER_TAB_MARKER_KEY,
+  type CdpEvent,
+  configureDownloads,
+  getBrowserAutomation,
+} from './browserAutomation.js';
+import {
+  type BrowserAxNode,
+  conciseAxTree,
+  diffAxTree,
+  normalizeAxTree,
+} from './browserAxState.js';
+import {
+  type BrowserCondition,
+  conditionToScript,
+} from './browserConditions.js';
+import {
+  type BrowserPageAsset,
+  type BrowserPageContent,
+  CLIPBOARD_READ_EXPRESSION,
+  CLIPBOARD_READ_TEXT_EXPRESSION,
+  PAGE_ASSETS_EXPRESSION,
+  browserAssetFetchExpression,
+  bundlePageAssets,
+  clipboardWriteExpression,
+  clipboardWriteTextExpression,
+  googleWorkspaceExportExpression,
+  markdownFromPageContent,
+  pageContentExpression,
+  readUrlsInBackground,
+} from './browserContent.js';
+import { detectBrowserChallenge } from './browserControl.js';
+import { ensureDaemon } from './browserDaemon.js';
+import {
+  type BrowserFrameInfo,
+  normalizeFrameInfo,
+  normalizeFrameTree,
+} from './browserFrames.js';
+import { resolveInteractionStrategy } from './browserInteractionResolver.js';
+import {
+  type BrowserLocator,
+  buildLocatorExpression,
+  buildTargetExpression,
+} from './browserLocator.js';
+import { withBrowserRecovery } from './browserRecovery.js';
+import { browserRunRegistry } from './browserRunRegistry.js';
+import { browserService } from './browserService.js';
+import { getBrowserStream } from './browserStream.js';
+import {
+  claimConversationTabById,
+  ensureConversationTab,
+  parseTabList,
+} from './browserTabs.js';
+
+export type { BrowserLocator } from './browserLocator.js';
+
+const locatorLeafSchema = z.object({
+  by: z.enum([
+    'css',
+    'ax',
+    'role',
+    'text',
+    'label',
+    'placeholder',
+    'alt',
+    'title',
+    'testid',
+  ]),
+  value: z.string(),
+  name: z.string().optional(),
+  exact: z.boolean().optional(),
+  strict: z.boolean().optional(),
+  nth: z.number().int().nonnegative().optional(),
+  has_text: z.string().optional(),
+  generation: z.number().int().positive().optional(),
+  frameId: z.string().min(1).optional(),
+  frame_id: z.string().min(1).optional(),
+});
+// Keep the public JSON Schema finite. A single nested scope and a finite frame
+// chain cover the browser pages we support while avoiding recursive-schema
+// fallbacks that turn the model contract into `any`.
+const locatorSchema = z.object({
+  ...locatorLeafSchema.shape,
+  within: locatorLeafSchema.optional(),
+  frame: z.array(locatorLeafSchema).optional(),
+  framePath: z.array(locatorLeafSchema).optional(),
+  frame_path: z.array(locatorLeafSchema).optional(),
+}) as z.ZodType<BrowserLocator>;
+const expectationSchema = z.object({
+  navigation: z
+    .object({
+      url: z.string().optional(),
+      wait_until: z.enum(['commit', 'domcontentloaded', 'load']).optional(),
+    })
+    .optional(),
+  new_tab: z.object({ url: z.string().optional() }).optional(),
+  download: z.object({ filename: z.string().optional() }).optional(),
+  file_chooser: z.object({ files: z.array(z.string()).optional() }).optional(),
+  conditions: z
+    .array(
+      z.union([
+        z.object({ type: z.literal('url'), pattern: z.string() }),
+        z.object({
+          type: z.literal('text'),
+          value: z.string(),
+          exact: z.boolean().optional(),
+        }),
+        z.object({
+          type: z.literal('element-visible'),
+          locator: locatorSchema.optional(),
+          selector: z.string().optional(),
+        }),
+        z.object({
+          type: z.literal('element-hidden'),
+          locator: locatorSchema.optional(),
+          selector: z.string().optional(),
+        }),
+        z.object({
+          type: z.literal('load-state'),
+          state: z.enum(['domcontentloaded', 'load', 'networkidle']),
+        }),
+        z.object({ type: z.literal('page-change') }),
+        z.object({
+          type: z.literal('download'),
+          filename: z.string().optional(),
+        }),
+        z.object({ type: z.literal('new-tab'), url: z.string().optional() }),
+        z.object({
+          type: z.literal('dialog'),
+          dialogType: z
+            .enum(['alert', 'confirm', 'prompt', 'beforeunload'])
+            .optional(),
+        }),
+      ]),
+    )
+    .max(8)
+    .optional(),
+});
+const stepSchema = z.object({
+  id: z.string().min(1).max(100).optional(),
+  action: z.enum([
+    'navigate',
+    'click',
+    'doubleClick',
+    'fill',
+    'type',
+    'hover',
+    'press',
+    'check',
+    'uncheck',
+    'setChecked',
+    'getState',
+    'drag',
+    'wait',
+    'waitForURL',
+    'waitForDownload',
+    'waitForFileChooser',
+    'snapshot',
+    'frameInfo',
+    'visibleDom',
+    'clickNode',
+    'typeNode',
+    'scrollNode',
+    'upload',
+    'pageAssets',
+    'listPageAssets',
+    'bundlePageAssets',
+    'exportContent',
+    'readUrls',
+    'clipboardReadText',
+    'clipboardWriteText',
+    'clipboardRead',
+    'clipboardWrite',
+  ]),
+  selector: z.string().optional(),
+  locator: locatorSchema.optional(),
+  trigger_selector: z.string().optional(),
+  trigger_locator: locatorSchema.optional(),
+  value: z.string().optional(),
+  files: z.array(z.string()).optional(),
+  key: z.string().optional(),
+  node_id: z.number().int().nonnegative().optional(),
+  checked: z.boolean().optional(),
+  url: z.string().optional(),
+  wait_ms: z.number().int().min(1).max(120_000).optional(),
+  drag_path: z
+    .array(z.object({ x: z.number(), y: z.number() }))
+    .min(2)
+    .optional(),
+  expect: expectationSchema.optional(),
+  intent: z.enum(['normal', 'submit']).optional(),
+  export_format: z
+    .enum([
+      'text',
+      'txt',
+      'markdown',
+      'md',
+      'html',
+      'json',
+      'page',
+      'google-workspace',
+      'youtube-transcript',
+      'pdf',
+      'docx',
+      'xlsx',
+      'csv',
+      'pptx',
+    ])
+    .optional(),
+  urls: z.array(z.string().url()).max(20).optional(),
+  concurrency: z.number().int().min(1).max(8).optional(),
+  content_type: z.enum(['text', 'html', 'domSnapshot']).optional(),
+  bundle_dir: z.string().optional(),
+  bundle_assets: z.boolean().optional(),
+  clipboard_text: z.string().optional(),
+  clipboard_items: z
+    .array(z.object({ type: z.string().min(1), base64: z.string() }))
+    .optional(),
+  is_multiple: z.boolean().optional(),
+  artifact: z
+    .object({
+      save_as: z.string().min(1).max(255),
+      label: z.string().max(200).optional(),
+    })
+    .optional(),
+});
+type Step = z.infer<typeof stepSchema>;
+const inputSchema = z.object({
+  tab_id: z.string().optional(),
+  retention: z
+    .enum(['ephemeral', 'conversation', 'handoff', 'deliverable'])
+    .optional(),
+  tab_title: z.string().max(200).optional(),
+  steps: z.array(stepSchema).min(1).max(50),
+  stop_on_error: z.boolean().default(true),
+  timeout_ms: z.number().int().min(1_000).max(300_000).default(120_000),
+  final_snapshot: z.enum(['none', 'auto', 'full', 'diff']).default('auto'),
+  capture: z.enum(['none', 'state', 'screenshot', 'both']).default('state'),
+});
+type Input = z.infer<typeof inputSchema>;
+
+type Snapshot = {
+  id: string;
+  revision: number;
+  generation: number;
+  url: string;
+  text: string;
+  nodes: Map<string, BrowserAxNode>;
+  updatedAt: number;
+};
+type FrameInfo = BrowserFrameInfo;
+type DownloadItem = {
+  id: string;
+  url: string;
+  filename: string;
+  path: string;
+  state: 'start' | 'progress' | 'complete' | 'canceled';
+  receivedBytes?: number;
+  totalBytes?: number;
+  error?: string;
+  startedAt: number;
+};
+const snapshots = new Map<string, Snapshot>();
+const MAX_SNAPSHOTS = 256;
+const SNAPSHOT_TTL_MS = 15 * 60_000;
+
+function jsString(value: string): string {
+  return JSON.stringify(value);
+}
+
+const DOWNLOAD_MIME_BY_EXT: Record<string, string> = {
+  '.csv': 'text/csv',
+  '.docx':
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.pptx':
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.zip': 'application/zip',
+};
+
+async function hashFile(path: string): Promise<string> {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function materializeDownloadArtifact(
+  sourcePath: string,
+  saveAs: string,
+): Promise<DeliverableManifest> {
+  const name = basename(saveAs);
+  if (!name || name !== saveAs || name === '.' || name === '..')
+    throw new Error('artifact.save_as 只能是工作区根目录下的文件名');
+  const root = await realpath(getWorkingDir()).catch(() => getWorkingDir());
+  const destination = join(root, name);
+  const source = await realpath(sourcePath);
+  await stat(source);
+  const temporary = join(root, `.${name}.${randomUUID()}.partial`);
+  try {
+    await copyFile(source, temporary);
+    await rename(temporary, destination);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => undefined);
+  }
+  const info = await stat(destination);
+  const relativePath = name;
+  return {
+    status: 'final',
+    summary: `已下载并提交 ${name}`,
+    files: [
+      {
+        relativePath,
+        sha256: await hashFile(destination),
+        mime:
+          DOWNLOAD_MIME_BY_EXT[extname(name).toLowerCase()] ??
+          'application/octet-stream',
+        size: info.size,
+        modifiedAt: info.mtimeMs,
+        verification: 'not_run',
+        purpose: 'deliverable',
+      },
+    ],
+    warnings: [],
+  };
+}
+
+async function waitForDownloadedFile(
+  directory: string,
+  item: DownloadItem,
+  timeout: number,
+  signal?: AbortSignal,
+): Promise<string> {
+  const deadline = Date.now() + timeout;
+  let previousPath = '';
+  let previousSize = -1;
+  let stableSamples = 0;
+  while (Date.now() < deadline) {
+    const entries = await readdir(directory, { withFileTypes: true }).catch(
+      () => [],
+    );
+    const candidates = await Promise.all(
+      entries
+        .filter(
+          (entry) => entry.isFile() && !entry.name.endsWith('.crdownload'),
+        )
+        .map(async (entry) => {
+          const path = join(directory, entry.name);
+          const info = await stat(path).catch(() => null);
+          return info
+            ? { path, name: entry.name, mtimeMs: info.mtimeMs, size: info.size }
+            : null;
+        }),
+    );
+    const usable = candidates
+      .filter(
+        (candidate): candidate is NonNullable<typeof candidate> =>
+          candidate !== null,
+      )
+      .filter((candidate) => candidate.mtimeMs >= item.startedAt - 1_000)
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const exact = usable.find((candidate) => candidate.name === item.filename);
+    const candidate = exact ?? usable[0];
+    if (candidate) {
+      const expectedSize = item.totalBytes;
+      const sizeMatches =
+        expectedSize === undefined ||
+        expectedSize <= 0 ||
+        candidate.size === expectedSize;
+      if (sizeMatches) {
+        if (candidate.path === previousPath && candidate.size === previousSize)
+          stableSamples += 1;
+        else {
+          previousPath = candidate.path;
+          previousSize = candidate.size;
+          stableSamples = 1;
+        }
+        if (stableSamples >= 2) return candidate.path;
+      }
+    }
+    await sleepWithSignal(100, signal);
+  }
+  throw new Error(`下载已完成但文件未稳定落盘：${item.filename}`);
+}
+
+async function materializeExportArtifact(
+  value: unknown,
+  format: string,
+  saveAs: string,
+): Promise<DeliverableManifest> {
+  const name = basename(saveAs);
+  if (!name || name !== saveAs || name === '.' || name === '..')
+    throw new Error('artifact.save_as 只能是工作区根目录下的文件名');
+  const root = await realpath(getWorkingDir()).catch(() => getWorkingDir());
+  const destination = join(root, name);
+  let bytes: Buffer;
+  if (
+    value &&
+    typeof value === 'object' &&
+    '__browser_pdf_base64' in value &&
+    typeof (value as { __browser_pdf_base64?: unknown })
+      .__browser_pdf_base64 === 'string'
+  ) {
+    bytes = Buffer.from(
+      (value as { __browser_pdf_base64: string }).__browser_pdf_base64,
+      'base64',
+    );
+  } else if (
+    value &&
+    typeof value === 'object' &&
+    '__browser_binary_base64' in value &&
+    typeof (value as { __browser_binary_base64?: unknown })
+      .__browser_binary_base64 === 'string'
+  ) {
+    bytes = Buffer.from(
+      (value as { __browser_binary_base64: string }).__browser_binary_base64,
+      'base64',
+    );
+  } else if (format === 'html' && value && typeof value === 'object') {
+    bytes = Buffer.from(
+      String((value as { html?: unknown }).html ?? ''),
+      'utf8',
+    );
+  } else if (format === 'json') {
+    bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  } else if (typeof value === 'string') {
+    bytes = Buffer.from(value.endsWith('\n') ? value : `${value}\n`, 'utf8');
+  } else if (value && typeof value === 'object' && 'text' in value) {
+    bytes = Buffer.from(
+      `${String((value as { text?: unknown }).text ?? '')}\n`,
+      'utf8',
+    );
+  } else {
+    bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  }
+  const temporary = join(root, `.${name}.${randomUUID()}.partial`);
+  try {
+    await writeFile(temporary, bytes, { mode: 0o600 });
+    await rename(temporary, destination);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => undefined);
+  }
+  const info = await stat(destination);
+  return {
+    status: 'final',
+    summary: `已导出并提交 ${name}`,
+    files: [
+      {
+        relativePath: name,
+        sha256: await hashFile(destination),
+        mime:
+          DOWNLOAD_MIME_BY_EXT[extname(name).toLowerCase()] ??
+          'application/octet-stream',
+        size: info.size,
+        modifiedAt: info.mtimeMs,
+        verification: 'not_run',
+        purpose: 'deliverable',
+      },
+    ],
+    warnings: [],
+  };
+}
+
+export function mergeArtifactManifests(
+  current: DeliverableManifest | undefined,
+  next: DeliverableManifest,
+): DeliverableManifest {
+  if (!current) return next;
+  const files = new Map<string, DeliverableManifest['files'][number]>();
+  for (const file of [...current.files, ...next.files]) {
+    // A repeated save_as represents the latest version of the same artifact;
+    // distinct paths remain distinct formal deliverables.
+    files.set(file.relativePath, file);
+  }
+  const links = new Map<
+    string,
+    NonNullable<DeliverableManifest['links']>[number]
+  >();
+  for (const link of [...(current.links ?? []), ...(next.links ?? [])])
+    links.set(link.url, link);
+  const allFiles = [...files.values()];
+  const warnings = [...new Set([...current.warnings, ...next.warnings])];
+  return {
+    status:
+      current.status === 'final' && next.status === 'final' && !warnings.length
+        ? 'final'
+        : 'draft',
+    summary: `已提交 ${allFiles.length} 个成果文件`,
+    files: allFiles,
+    ...(links.size ? { links: [...links.values()] } : {}),
+    warnings,
+  };
+}
+
+async function evaluate(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  expression: string,
+  signal?: AbortSignal,
+  frameId?: string,
+): Promise<unknown> {
+  if (frameId) {
+    const result = (await cdp.evaluateInFrame(frameId, expression, signal)) as {
+      result?: { value?: unknown; description?: string };
+    };
+    return result.result?.value ?? result.result?.description;
+  }
+  const result = (await cdp.send(
+    'Runtime.evaluate',
+    {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    },
+    undefined,
+    30_000,
+    signal,
+  )) as {
+    result?: { value?: unknown; description?: string };
+  };
+  return result.result?.value ?? result.result?.description;
+}
+async function waitFor(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  predicate: (event: CdpEvent) => boolean,
+  timeout: number,
+  afterSequence = 0,
+  signal?: AbortSignal,
+): Promise<CdpEvent> {
+  const pageEvent = (event: CdpEvent): boolean => {
+    // Browser.* events are browser-scoped and intentionally remain visible
+    // (downloads do not carry a page session in all Chromium versions).
+    // Page/DOM/Input/etc. events must belong to this connection's attached
+    // page, otherwise another tab can satisfy a navigation or dialog wait.
+    const pageDomain =
+      /^(Accessibility|DOM|Input|Log|Network|Page|Performance|Runtime|Security)\./;
+    return (
+      !pageDomain.test(event.method) ||
+      event.sessionId === cdp.attachedPageSessionId
+    );
+  };
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error('Browser event wait aborted'),
+      );
+      return;
+    }
+    const existing = cdp
+      .read(afterSequence)
+      .find((event) => pageEvent(event) && predicate(event));
+    if (existing) return resolve(existing);
+    let settled = false;
+    let off: () => void = () => {};
+    const cleanup = () => {
+      clearTimeout(timer);
+      off();
+      signal?.removeEventListener('abort', onAbort);
+    };
+    const finish = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    const onAbort = () =>
+      finish(() =>
+        reject(
+          signal?.reason instanceof Error
+            ? signal.reason
+            : new Error('Browser event wait aborted'),
+        ),
+      );
+    const timer = setTimeout(
+      () => finish(() => reject(new Error('Browser event wait timed out'))),
+      timeout,
+    );
+    off = cdp.subscribe((event) => {
+      if (pageEvent(event) && predicate(event)) finish(() => resolve(event));
+    });
+    signal?.addEventListener('abort', onAbort, { once: true });
+    // Close the tiny read/subscribe race without changing the event cursor contract.
+    const raced = cdp
+      .read(afterSequence)
+      .find((event) => pageEvent(event) && predicate(event));
+    if (raced) finish(() => resolve(raced));
+  });
+}
+
+// Some agent-browser/CDP endpoints expose Runtime/Page but not the optional
+// Accessibility domain. Keep a deterministic DOM-semantic fallback so a
+// missing AX domain does not make an otherwise usable supervised browser fail.
+const domSemanticSnapshotExpression = `(() => Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6,p,li,a,button,input,textarea,select,[role],[contenteditable="true"]')).map((el,index) => { const r=el.getBoundingClientRect(); const s=getComputedStyle(el); const visible=!!(r.width||r.height)&&s.display!=='none'&&s.visibility!=='hidden'&&s.pointerEvents!=='none'; const tag=el.tagName.toLowerCase(); const explicit=el.getAttribute('role'); const role=explicit||(['button','a','textarea','select'].includes(tag)?({button:'button',a:'link',textarea:'textbox',select:'combobox'})[tag]:(tag==='input'?(['checkbox','radio','button','submit','reset'].includes((el.getAttribute('type')||'text').toLowerCase())?(el.getAttribute('type')||'text').toLowerCase():'textbox'):tag)); const name=(el.getAttribute('aria-label')||el.textContent||el.getAttribute('placeholder')||'').trim().replace(/\\s+/g,' ').slice(0,240); const value=el instanceof HTMLInputElement||el instanceof HTMLTextAreaElement||el instanceof HTMLSelectElement?el.value:undefined; return {node_id:index,role,text:name,value,visible,x:r.x,y:r.y,width:r.width,height:r.height}; }).filter((node) => node.visible).slice(0,500))()`;
+
+async function readBrowserAxTree(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  signal?: AbortSignal,
+): Promise<BrowserAxNode[]> {
+  try {
+    return normalizeAxTree(
+      await cdp.send(
+        'Accessibility.getFullAXTree',
+        {},
+        undefined,
+        30_000,
+        signal,
+      ),
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/-32601|not found|unknown method/i.test(message)) throw error;
+    const domNodes = await evaluate(cdp, domSemanticSnapshotExpression, signal);
+    if (!Array.isArray(domNodes)) return [];
+    return normalizeAxTree({
+      nodes: domNodes.map((value) => {
+        const node =
+          value && typeof value === 'object'
+            ? (value as Record<string, unknown>)
+            : {};
+        const number = (key: string) =>
+          typeof node[key] === 'number' ? node[key] : undefined;
+        return {
+          nodeId: `dom-${String(node.node_id ?? '')}`,
+          role: { value: String(node.role ?? 'generic') },
+          name: { value: String(node.text ?? '') },
+          ...(node.value !== undefined
+            ? { properties: [{ name: 'value', value: { value: node.value } }] }
+            : {}),
+          bounds: {
+            x: number('x') ?? 0,
+            y: number('y') ?? 0,
+            width: number('width') ?? 0,
+            height: number('height') ?? 0,
+          },
+        };
+      }),
+    });
+  }
+}
+
+async function snapshot(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  key: string,
+  mode: Input['final_snapshot'],
+  signal?: AbortSignal,
+): Promise<{
+  mode: 'full' | 'diff';
+  snapshot_id: string;
+  base_snapshot_id?: string;
+  page_revision: number;
+  generation: number;
+  tree: string;
+  frames: FrameInfo[];
+}> {
+  const now = Date.now();
+  for (const [staleKey, stale] of snapshots) {
+    if (now - stale.updatedAt > SNAPSHOT_TTL_MS) snapshots.delete(staleKey);
+  }
+  const tree = await readBrowserAxTree(cdp, signal);
+  const url = String(
+    await evaluate(cdp, 'location.href', signal).catch(() => ''),
+  );
+  const frameResult = (await cdp
+    .send('Page.getFrameTree', {}, undefined, 30_000, signal)
+    .catch(() => ({}))) as {
+    frameTree?: unknown;
+  };
+  const frames: FrameInfo[] = normalizeFrameTree(frameResult.frameTree);
+  const prior = snapshots.get(key);
+  const revision = (prior?.revision ?? 0) + 1;
+  const id = randomUUID();
+  const generation =
+    prior && prior.url !== url
+      ? prior.generation + 1
+      : (prior?.generation ?? 1);
+  const samePageNodes = prior && prior.url === url ? prior.nodes : undefined;
+  const diff = diffAxTree(
+    samePageNodes,
+    tree,
+    generation,
+    revision,
+    mode === 'full' || (!samePageNodes && mode !== 'diff'),
+  );
+  snapshots.set(key, {
+    id,
+    revision,
+    generation,
+    url,
+    text: JSON.stringify(tree),
+    nodes: new Map(tree.map((node) => [node.id, node])),
+    updatedAt: now,
+  });
+  if (snapshots.size > MAX_SNAPSHOTS) {
+    const stale = [...snapshots.entries()]
+      .sort((left, right) => left[1].updatedAt - right[1].updatedAt)
+      .slice(0, snapshots.size - MAX_SNAPSHOTS);
+    for (const [staleKey] of stale) snapshots.delete(staleKey);
+  }
+  const body =
+    mode === 'full' || !samePageNodes ? { nodes: tree, ...diff } : diff;
+  const compact = JSON.stringify(body);
+  return {
+    mode: diff.full ? 'full' : 'diff',
+    snapshot_id: id,
+    ...(prior ? { base_snapshot_id: prior.id } : {}),
+    page_revision: revision,
+    generation,
+    tree: (mode === 'full' || !prior ? conciseAxTree(tree) : compact).slice(
+      0,
+      DEFAULT_MAX_RESULT_SIZE_CHARS,
+    ),
+    frames,
+  };
+}
+
+async function resolveAxLocator(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  locator: BrowserLocator | undefined,
+  snapshotKey: string,
+  signal?: AbortSignal,
+): Promise<BrowserLocator | undefined> {
+  if (!locator || locator.by !== 'ax') return locator;
+  const current = await readBrowserAxTree(cdp, signal);
+  const prior = snapshots.get(snapshotKey);
+  if (locator.generation !== undefined && !prior) {
+    throw new Error(
+      'AX 引用缺少对应 snapshot；请先 snapshot 后再使用 generation',
+    );
+  }
+  if (
+    locator.generation !== undefined &&
+    prior &&
+    locator.generation !== prior.generation
+  ) {
+    throw new Error(
+      `AX 引用已过期：引用 generation=${locator.generation}，当前页面 generation=${prior.generation}；请重新 snapshot`,
+    );
+  }
+  if (locator.generation !== undefined && prior) {
+    const currentUrl = String(
+      await evaluate(cdp, 'location.href', signal).catch(() => ''),
+    );
+    if (currentUrl !== prior.url) {
+      throw new Error(
+        `AX 引用已过期：页面已从 ${prior.url} 导航到 ${currentUrl}；请重新 snapshot`,
+      );
+    }
+  }
+  const indexMatch = /^index:(\d+)$/.exec(locator.value);
+  const numeric = indexMatch ? Number(indexMatch[1]) : Number(locator.value);
+  const node =
+    current.find((item) => item.id === locator.value) ??
+    (Number.isInteger(numeric) && numeric >= 0 && numeric < current.length
+      ? current[numeric]
+      : undefined);
+  if (!node)
+    throw new Error(`AX 引用未找到：${locator.value}；请重新 snapshot`);
+  if (!node.name && !node.role)
+    throw new Error(`AX 引用没有可执行的语义信息：${locator.value}`);
+  const resolved: BrowserLocator = node.name
+    ? {
+        by: 'role',
+        value: node.role ?? 'generic',
+        name: node.name,
+        exact: true,
+        strict: true,
+      }
+    : { by: 'text', value: node.value ?? '', exact: true, strict: true };
+  const framePath = locator.frame ?? locator.framePath ?? locator.frame_path;
+  const frameId = locator.frameId ?? locator.frame_id;
+  return {
+    ...resolved,
+    ...(framePath?.length ? { frame: framePath } : {}),
+    ...(frameId ? { frameId } : {}),
+  };
+}
+
+function eventMatchesCondition(
+  condition: BrowserCondition,
+  event: CdpEvent,
+): boolean {
+  if (condition.type === 'download') {
+    return (
+      event.method === 'Browser.downloadWillBegin' &&
+      (!condition.filename ||
+        String(event.params.suggestedFilename ?? '') === condition.filename)
+    );
+  }
+  if (condition.type === 'new-tab') {
+    return (
+      event.method === 'Target.targetCreated' &&
+      (!condition.url || JSON.stringify(event.params).includes(condition.url))
+    );
+  }
+  if (condition.type === 'dialog') {
+    return (
+      event.method === 'Page.javascriptDialogOpening' &&
+      (!condition.dialogType ||
+        String(event.params.type ?? '') === condition.dialogType)
+    );
+  }
+  return false;
+}
+
+const visibleDomExpression = `(() => Array.from(document.querySelectorAll('a,button,input,textarea,select,[role],[contenteditable="true"]')).map((el, index) => { const r=el.getBoundingClientRect(); const s=getComputedStyle(el); const visible=!!(r.width||r.height)&&s.display!=='none'&&s.visibility!=='hidden'&&s.pointerEvents!=='none'; const label=el.labels?.length?Array.from(el.labels).map((item)=>String(item.textContent||'').trim()).filter(Boolean).join(' '):undefined; const role=el.getAttribute('role')||el.tagName.toLowerCase(); const editable=el instanceof HTMLInputElement||el instanceof HTMLTextAreaElement||el.isContentEditable; const clickable=el instanceof HTMLButtonElement||el instanceof HTMLAnchorElement||role==='button'||typeof el.onclick==='function'; return {node_id:index,tag:el.tagName.toLowerCase(),role,text:(el.innerText||el.getAttribute('aria-label')||label||el.getAttribute('placeholder')||'').trim().slice(0,240),label,placeholder:el.getAttribute('placeholder')||undefined,testId:el.getAttribute('data-testid')||undefined,cssCandidates:[el.id?'#'+CSS.escape(el.id):'',el.getAttribute('data-testid')?'[data-testid="'+CSS.escape(el.getAttribute('data-testid'))+'"]':''].filter(Boolean),framePath:[],x:r.x,y:r.y,width:r.width,height:r.height,visible,enabled:!el.disabled,editable,clickable,confidence:el.id||el.getAttribute('data-testid')?'high':'medium'}; }).filter((node) => node.visible).slice(0,500))()`;
+export const visibleDomTarget = (nodeId: number) =>
+  `(() => { const nodes=${visibleDomExpression}; const n=nodes[${nodeId}]; if(!n) throw new Error('visible DOM node not found'); const all=Array.from(document.querySelectorAll('a,button,input,textarea,select,[role],[contenteditable="true"]')); const e=all[n.node_id]; if(!e) throw new Error('visible DOM node is stale'); return e; })()`;
+
+async function waitForCondition(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  condition: BrowserCondition,
+  timeout: number,
+  baseline?: unknown,
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const deadline = Date.now() + timeout;
+  const script = conditionToScript(condition, (locator, selector) =>
+    buildTargetExpression(locator, selector),
+  );
+  let lastValue: unknown;
+  while (Date.now() < deadline) {
+    if (signal?.aborted)
+      throw signal.reason instanceof Error
+        ? signal.reason
+        : new Error('Browser condition wait aborted');
+    const challenge = await readBrowserChallenge(cdp, signal);
+    if (challenge) throw new Error(`页面需要人工验证：${challenge.summary}`);
+    const value = await evaluate(cdp, script, signal);
+    lastValue = value;
+    if (condition.type === 'page-change' ? value !== baseline : value === true)
+      return value;
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+      }, 100);
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(
+          signal?.reason instanceof Error
+            ? signal.reason
+            : new Error('Browser condition wait aborted'),
+        );
+      };
+      if (signal?.aborted) onAbort();
+      else signal?.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+  throw new Error(
+    `Browser condition timed out: ${condition.type} (last=${JSON.stringify(lastValue)})`,
+  );
+}
+
+async function readBrowserChallenge(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  signal?: AbortSignal,
+): Promise<ReturnType<typeof detectBrowserChallenge>> {
+  const text = String(
+    await evaluate(
+      cdp,
+      `location.href + '\\n' + (document.body?.innerText || '').slice(0, 20000)`,
+      signal,
+    ).catch(() => ''),
+  );
+  return detectBrowserChallenge(text);
+}
+
+async function waitForBrowserChallenge(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  timeout: number,
+  signal?: AbortSignal,
+): Promise<NonNullable<ReturnType<typeof detectBrowserChallenge>> | null> {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline && !signal?.aborted) {
+    const challenge = await readBrowserChallenge(cdp, signal);
+    if (challenge) return challenge;
+    await sleepWithSignal(250, signal).catch(() => undefined);
+  }
+  return null;
+}
+
+async function waitForEventOrBrowserChallenge(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  predicate: (event: CdpEvent) => boolean,
+  timeout: number,
+  afterSequence = 0,
+  signal?: AbortSignal,
+): Promise<CdpEvent> {
+  const challengeAbort = new AbortController();
+  const challengeRace = waitForBrowserChallenge(
+    cdp,
+    timeout,
+    challengeAbort.signal,
+  ).then((challenge) => {
+    if (challenge) throw new Error(`页面需要人工验证：${challenge.summary}`);
+    return new Promise<never>(() => undefined);
+  });
+  try {
+    return await Promise.race([
+      waitFor(cdp, predicate, timeout, afterSequence, signal),
+      challengeRace,
+    ]);
+  } finally {
+    challengeAbort.abort();
+  }
+}
+
+type BrowserPoint = { x: number; y: number };
+
+async function elementPoint(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  target: string,
+  framePath: BrowserLocator[] = [],
+  signal?: AbortSignal,
+  frameId?: string,
+): Promise<BrowserPoint> {
+  if (frameId) {
+    const value = await evaluate(
+      cdp,
+      `(() => { const e=${target}; e.scrollIntoView({block:'center',inline:'center'}); const r=e.getBoundingClientRect(); const s=getComputedStyle(e); if (!r.width || !r.height || s.visibility==='hidden' || s.pointerEvents==='none') throw new Error('Locator matched a non-actionable element'); return {x:r.left+r.width/2,y:r.top+r.height/2}; })()`,
+      signal,
+      frameId,
+    );
+    if (!value || typeof value !== 'object')
+      throw new Error('无法取得浏览器元素坐标');
+    const point = value as { x?: unknown; y?: unknown };
+    if (typeof point.x !== 'number' || typeof point.y !== 'number')
+      throw new Error('浏览器元素坐标无效');
+    const offset = await cdp.frameOwnerOffset(frameId, signal);
+    return { x: point.x + offset.x, y: point.y + offset.y };
+  }
+  let frameOffsets = '';
+  let frameRoot = 'document';
+  for (const [index, frame] of framePath.entries()) {
+    const frameExpression = buildLocatorExpression(frame, undefined, frameRoot);
+    frameOffsets += `const __frame${index}=(${frameExpression})[0]; if(!__frame${index}||!__frame${index}.contentDocument) throw new Error('frameLocator could not resolve a same-origin iframe'); const __frameRect${index}=__frame${index}.getBoundingClientRect(); __offsetX+=__frameRect${index}.left; __offsetY+=__frameRect${index}.top; __frameRoot=__frame${index}.contentDocument;`;
+    frameRoot = '__frameRoot';
+  }
+  const value = await evaluate(
+    cdp,
+    `(() => { let __offsetX=0,__offsetY=0,__frameRoot=document; ${frameOffsets} const e=${target}; e.scrollIntoView({block:'center',inline:'center'}); const r=e.getBoundingClientRect(); const s=getComputedStyle(e); if (!r.width || !r.height || s.visibility==='hidden' || s.pointerEvents==='none') throw new Error('Locator matched a non-actionable element'); return {x:r.left+r.width/2+__offsetX,y:r.top+r.height/2+__offsetY}; })()`,
+    signal,
+  );
+  if (!value || typeof value !== 'object')
+    throw new Error('无法取得浏览器元素坐标');
+  const point = value as { x?: unknown; y?: unknown };
+  if (typeof point.x !== 'number' || typeof point.y !== 'number')
+    throw new Error('浏览器元素坐标无效');
+  return { x: point.x, y: point.y };
+}
+
+async function trustedClick(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  target: string,
+  framePath: BrowserLocator[] = [],
+  signal?: AbortSignal,
+  clickCount = 1,
+  frameId?: string,
+): Promise<void> {
+  const point = await elementPoint(cdp, target, framePath, signal, frameId);
+  await cdp.send(
+    'Input.dispatchMouseEvent',
+    {
+      type: 'mouseMoved',
+      x: point.x,
+      y: point.y,
+    },
+    undefined,
+    30_000,
+    signal,
+  );
+  await cdp.send(
+    'Input.dispatchMouseEvent',
+    {
+      type: 'mousePressed',
+      x: point.x,
+      y: point.y,
+      button: 'left',
+      buttons: 1,
+      clickCount,
+    },
+    undefined,
+    30_000,
+    signal,
+  );
+  await cdp.send(
+    'Input.dispatchMouseEvent',
+    {
+      type: 'mouseReleased',
+      x: point.x,
+      y: point.y,
+      button: 'left',
+      buttons: 0,
+      clickCount,
+    },
+    undefined,
+    30_000,
+    signal,
+  );
+}
+
+async function focusTarget(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  target: string,
+  signal?: AbortSignal,
+  frameId?: string,
+): Promise<void> {
+  await evaluate(
+    cdp,
+    `(()=>{const e=${target};e.scrollIntoView({block:'center',inline:'nearest'});e.focus();})()`,
+    signal,
+    frameId,
+  );
+}
+
+async function insertText(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  target: string,
+  value: string,
+  replace: boolean,
+  signal?: AbortSignal,
+  frameId?: string,
+): Promise<void> {
+  await focusTarget(cdp, target, signal, frameId);
+  if (replace) {
+    const mac = await evaluate(
+      cdp,
+      `navigator.platform.includes('Mac')`,
+      signal,
+      frameId,
+    );
+    const modifiers = mac === true ? 4 : 2;
+    await cdp.send(
+      'Input.dispatchKeyEvent',
+      {
+        type: 'keyDown',
+        key: 'a',
+        code: 'KeyA',
+        modifiers,
+      },
+      undefined,
+      30_000,
+      signal,
+    );
+    await cdp.send(
+      'Input.dispatchKeyEvent',
+      {
+        type: 'keyUp',
+        key: 'a',
+        code: 'KeyA',
+        modifiers,
+      },
+      undefined,
+      30_000,
+      signal,
+    );
+  }
+  await cdp.send(
+    'Input.insertText',
+    { text: value },
+    undefined,
+    30_000,
+    signal,
+  );
+}
+
+function sleepWithSignal(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error('Browser step aborted'),
+      );
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(
+        signal?.reason instanceof Error
+          ? signal.reason
+          : new Error('Browser step aborted'),
+      );
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+async function resumeBatchAfterHuman(
+  stream: ReturnType<typeof getBrowserStream>,
+  ctx: ToolCallContext,
+  signal: AbortSignal | undefined,
+  summary: string,
+): Promise<'resumed' | 'stopped'> {
+  ctx.reportProgress?.(`${summary}，等待你在浏览器中处理`);
+  const resolution = await stream.waitForHuman(signal);
+  if (resolution === 'resumed')
+    ctx.reportProgress?.('人工处理完成，正在重新读取页面状态并继续批量任务');
+  return resolution;
+}
+
+async function executeStep(
+  cdp: Awaited<ReturnType<typeof getBrowserAutomation>>,
+  step: Step,
+  timeout: number,
+  afterSequence = 0,
+  snapshotKey = 'step',
+  signal?: AbortSignal,
+): Promise<unknown> {
+  await cdp
+    .send('Page.enable', {}, undefined, 30_000, signal)
+    .catch(() => undefined);
+  const resolvedLocator = await resolveAxLocator(
+    cdp,
+    step.locator,
+    snapshotKey,
+    signal,
+  );
+  const frameId = resolvedLocator?.frameId ?? resolvedLocator?.frame_id;
+  const targetLocator: BrowserLocator | undefined =
+    resolvedLocator && frameId
+      ? {
+          ...resolvedLocator,
+          frame: undefined,
+          framePath: undefined,
+          frame_path: undefined,
+        }
+      : resolvedLocator;
+  const target = () => {
+    if (targetLocator && step.selector) {
+      const semantic = buildTargetExpression(targetLocator, undefined);
+      const cssFallback = buildTargetExpression(undefined, step.selector);
+      return `(() => { try { return ${semantic}; } catch { return ${cssFallback}; } })()`;
+    }
+    return buildTargetExpression(targetLocator, step.selector);
+  };
+  switch (step.action) {
+    case 'navigate':
+      if (!step.url) throw new Error('navigate requires url');
+      return cdp.send(
+        'Page.navigate',
+        { url: step.url },
+        undefined,
+        30_000,
+        signal,
+      );
+    case 'click':
+      return trustedClick(
+        cdp,
+        target(),
+        resolvedLocator?.frame ??
+          resolvedLocator?.framePath ??
+          resolvedLocator?.frame_path ??
+          [],
+        signal,
+        1,
+        frameId,
+      );
+    case 'doubleClick':
+      return trustedClick(
+        cdp,
+        target(),
+        resolvedLocator?.frame ??
+          resolvedLocator?.framePath ??
+          resolvedLocator?.frame_path ??
+          [],
+        signal,
+        2,
+        frameId,
+      );
+    case 'fill':
+      if (step.value === undefined) throw new Error('fill requires value');
+      return insertText(cdp, target(), step.value, true, signal, frameId);
+    case 'type':
+      if (step.value === undefined) throw new Error('type requires value');
+      return insertText(cdp, target(), step.value, false, signal, frameId);
+    case 'hover': {
+      const point = await elementPoint(
+        cdp,
+        target(),
+        resolvedLocator?.frame ??
+          resolvedLocator?.framePath ??
+          resolvedLocator?.frame_path ??
+          [],
+        signal,
+        frameId,
+      );
+      return cdp.send(
+        'Input.dispatchMouseEvent',
+        {
+          type: 'mouseMoved',
+          x: point.x,
+          y: point.y,
+        },
+        undefined,
+        30_000,
+        signal,
+      );
+    }
+    case 'press':
+      if (!step.key) throw new Error('press requires key');
+      if (step.locator || step.selector)
+        await focusTarget(cdp, target(), signal, frameId);
+      return cdp
+        .send(
+          'Input.dispatchKeyEvent',
+          { type: 'keyDown', key: step.key },
+          undefined,
+          30_000,
+          signal,
+        )
+        .then(() =>
+          cdp.send(
+            'Input.dispatchKeyEvent',
+            { type: 'keyUp', key: step.key },
+            undefined,
+            30_000,
+            signal,
+          ),
+        );
+    case 'check':
+      return evaluate(
+        cdp,
+        `Boolean(${target()}.checked)`,
+        signal,
+        frameId,
+      ).then((checked) =>
+        checked
+          ? undefined
+          : trustedClick(
+              cdp,
+              target(),
+              resolvedLocator?.frame ??
+                resolvedLocator?.framePath ??
+                resolvedLocator?.frame_path ??
+                [],
+              signal,
+              1,
+              frameId,
+            ),
+      );
+    case 'uncheck':
+      return evaluate(
+        cdp,
+        `Boolean(${target()}.checked)`,
+        signal,
+        frameId,
+      ).then((checked) =>
+        checked
+          ? trustedClick(
+              cdp,
+              target(),
+              resolvedLocator?.frame ??
+                resolvedLocator?.framePath ??
+                resolvedLocator?.frame_path ??
+                [],
+              signal,
+              1,
+              frameId,
+            )
+          : undefined,
+      );
+    case 'setChecked':
+      if (step.checked === undefined)
+        throw new Error('setChecked requires checked');
+      return evaluate(
+        cdp,
+        `Boolean(${target()}.checked)`,
+        signal,
+        frameId,
+      ).then((checked) =>
+        checked === step.checked
+          ? undefined
+          : trustedClick(
+              cdp,
+              target(),
+              resolvedLocator?.frame ??
+                resolvedLocator?.framePath ??
+                resolvedLocator?.frame_path ??
+                [],
+              signal,
+              1,
+              frameId,
+            ),
+      );
+    case 'getState':
+      return evaluate(
+        cdp,
+        `(()=>{const e=${target()};const s=getComputedStyle(e);return {visible:!!(e.offsetWidth||e.offsetHeight||e.getClientRects().length)&&s.visibility!=='hidden',enabled:!e.disabled,checked:!!e.checked}})()`,
+        signal,
+        frameId,
+      );
+    case 'drag': {
+      const points = step.drag_path;
+      if (!points?.length) throw new Error('drag requires drag_path');
+      for (const [index, point] of points.entries())
+        await cdp.send(
+          'Input.dispatchMouseEvent',
+          {
+            type:
+              index === 0
+                ? 'mousePressed'
+                : index === points.length - 1
+                  ? 'mouseReleased'
+                  : 'mouseMoved',
+            x: point.x,
+            y: point.y,
+            button: 'left',
+            buttons: index === 0 ? 1 : index === points.length - 1 ? 0 : 1,
+          },
+          undefined,
+          30_000,
+          signal,
+        );
+      return { points: points.length };
+    }
+    case 'wait':
+      await sleepWithSignal(step.wait_ms ?? 250, signal);
+      return { waited_ms: step.wait_ms ?? 250 };
+    case 'waitForURL':
+      if (!step.url) throw new Error('waitForURL requires url');
+      return waitFor(
+        cdp,
+        (event) =>
+          /Page\.frame(Navigated|StartedLoading)/.test(event.method) &&
+          JSON.stringify(event.params).includes(step.url!),
+        timeout,
+        afterSequence,
+        signal,
+      );
+    case 'waitForDownload':
+      return waitFor(
+        cdp,
+        (event) =>
+          event.method === 'Browser.downloadWillBegin' ||
+          event.method === 'Browser.downloadProgress',
+        timeout,
+        afterSequence,
+        signal,
+      );
+    case 'waitForFileChooser':
+      return waitFor(
+        cdp,
+        (event) => event.method === 'Page.fileChooserOpened',
+        timeout,
+        afterSequence,
+        signal,
+      );
+    case 'snapshot':
+      return snapshot(cdp, snapshotKey, 'full', signal);
+    case 'frameInfo':
+      return normalizeFrameInfo(
+        normalizeFrameTree(
+          (
+            (await cdp.send(
+              'Page.getFrameTree',
+              {},
+              undefined,
+              30_000,
+              signal,
+            )) as { frameTree?: unknown }
+          ).frameTree,
+        ),
+      );
+    case 'visibleDom':
+      return evaluate(cdp, visibleDomExpression, signal, frameId);
+    case 'clickNode':
+      if (step.node_id === undefined)
+        throw new Error('clickNode requires node_id');
+      return trustedClick(cdp, visibleDomTarget(step.node_id), [], signal);
+    case 'typeNode':
+      if (step.node_id === undefined || step.value === undefined)
+        throw new Error('typeNode requires node_id and value');
+      return insertText(
+        cdp,
+        visibleDomTarget(step.node_id),
+        step.value,
+        false,
+        signal,
+        frameId,
+      );
+    case 'scrollNode':
+      if (step.node_id === undefined)
+        throw new Error('scrollNode requires node_id');
+      return evaluate(
+        cdp,
+        `(()=>{const e=${visibleDomTarget(step.node_id)};e.scrollIntoView({block:'center',inline:'nearest'});return {node_id:${step.node_id}}})()`,
+        signal,
+        frameId,
+      );
+    case 'upload': {
+      if (!step.files?.length) throw new Error('upload requires files');
+      if (step.trigger_selector || step.trigger_locator) {
+        const trigger = buildTargetExpression(
+          step.trigger_locator,
+          step.trigger_selector,
+        );
+        await trustedClick(cdp, trigger, [], signal);
+        return { files: step.files, chooser_triggered: true };
+      }
+      if (!step.selector)
+        throw new Error('upload requires selector or trigger_selector');
+      const documentResult = (await cdp.send(
+        'DOM.getDocument',
+        {
+          depth: -1,
+        },
+        undefined,
+        30_000,
+        signal,
+      )) as {
+        root?: { nodeId?: number };
+      };
+      if (!documentResult.root?.nodeId) throw new Error('无法取得 DOM 根节点');
+      const found = (await cdp.send(
+        'DOM.querySelector',
+        {
+          nodeId: documentResult.root.nodeId,
+          selector: step.selector,
+        },
+        undefined,
+        30_000,
+        signal,
+      )) as { nodeId?: number };
+      if (!found.nodeId) throw new Error('upload selector matched no input');
+      await cdp.send(
+        'DOM.setFileInputFiles',
+        {
+          files: step.files,
+          nodeId: found.nodeId,
+        },
+        undefined,
+        30_000,
+        signal,
+      );
+      return { files: step.files, uploaded: true };
+    }
+    case 'pageAssets':
+    case 'listPageAssets':
+    case 'bundlePageAssets': {
+      const assets = await evaluate(cdp, PAGE_ASSETS_EXPRESSION, signal);
+      if (!Array.isArray(assets)) throw new Error('页面资产清单格式无效');
+      if (step.bundle_assets || step.action === 'bundlePageAssets') {
+        if (!step.bundle_dir)
+          throw new Error('bundle_assets requires bundle_dir');
+        const bundle = await bundlePageAssets(
+          assets as BrowserPageAsset[],
+          step.bundle_dir,
+          async (url) => {
+            const fetched = await evaluate(
+              cdp,
+              browserAssetFetchExpression(url),
+              signal,
+            );
+            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 { assets, bundle };
+      }
+      return { assets };
+    }
+    case 'exportContent': {
+      const format = step.export_format ?? 'page';
+      if (format === 'pdf') {
+        const pdf = (await cdp.send(
+          'Page.printToPDF',
+          {
+            printBackground: true,
+            preferCSSPageSize: true,
+          },
+          undefined,
+          30_000,
+          signal,
+        )) as { data?: string };
+        if (!pdf.data) throw new Error('浏览器未返回 PDF 内容');
+        return { __browser_pdf_base64: pdf.data };
+      }
+      if (['docx', 'xlsx', 'csv', 'pptx'].includes(format)) {
+        const exported = await evaluate(
+          cdp,
+          googleWorkspaceExportExpression(
+            format as 'docx' | 'xlsx' | 'csv' | 'pptx',
+          ),
+          signal,
+        );
+        if (exported && typeof exported === 'object' && 'error' in exported)
+          throw new Error(String((exported as { error?: unknown }).error));
+        if (
+          !exported ||
+          typeof exported !== 'object' ||
+          typeof (exported as { __browser_binary_base64?: unknown })
+            .__browser_binary_base64 !== 'string'
+        )
+          throw new Error('Workspace 未返回可保存的文件内容');
+        return exported;
+      }
+      const content = await evaluate(
+        cdp,
+        pageContentExpression(format, step.selector),
+        signal,
+      );
+      if (!content || typeof content !== 'object')
+        throw new Error('页面内容导出失败');
+      if (format === 'markdown' || format === 'md')
+        return markdownFromPageContent(content as BrowserPageContent);
+      return content;
+    }
+    case 'readUrls': {
+      if (!step.urls?.length) throw new Error('readUrls requires urls');
+      return readUrlsInBackground(
+        cdp,
+        step.urls,
+        timeout,
+        step.content_type,
+        step.concurrency,
+        signal,
+      );
+    }
+    case 'clipboardReadText':
+      return evaluate(cdp, CLIPBOARD_READ_TEXT_EXPRESSION, signal);
+    case 'clipboardWriteText':
+      if (step.clipboard_text === undefined)
+        throw new Error('clipboardWriteText requires clipboard_text');
+      return evaluate(
+        cdp,
+        clipboardWriteTextExpression(step.clipboard_text),
+        signal,
+      );
+    case 'clipboardRead':
+      return evaluate(cdp, CLIPBOARD_READ_EXPRESSION, signal);
+    case 'clipboardWrite':
+      if (!step.clipboard_items?.length)
+        throw new Error('clipboardWrite requires clipboard_items');
+      return evaluate(
+        cdp,
+        clipboardWriteExpression(step.clipboard_items),
+        signal,
+      );
+  }
+}
+
+async function call(
+  input: Input,
+  signal?: AbortSignal,
+  ctx: ToolCallContext = {},
+): Promise<ToolResult> {
+  // Tool runners normally apply the Zod default, but callWithContext is also
+  // used by the local runtime and deterministic E2E harnesses directly. Keep
+  // the execution core safe when that adapter is intentionally bypassed.
+  const timeoutMs = input.timeout_ms ?? 120_000;
+  const stopOnError = input.stop_on_error ?? true;
+  const finalSnapshotMode = input.final_snapshot ?? 'auto';
+  const captureMode = input.capture ?? 'state';
+  if (!(await configService.browser()).enabled)
+    return { ok: false, error: '内置浏览器已在设置中关闭' };
+  if (ctx.browserRun?.supervised !== true)
+    return {
+      ok: false,
+      error: 'BrowserBatch 仅可在 Desktop 的受监督浏览器会话中使用',
+    };
+  const bin = await resolveAgentBrowserPath();
+  if (!bin)
+    return { ok: false, error: '内置浏览器不可用：未找到 agent-browser' };
+  const runId = ctx.browserRun?.runId ?? ctx.toolCallId ?? randomUUID();
+  const conversationKey =
+    ctx.browserRun?.conversationKey ?? `headless:${process.pid}`;
+  const run = browserRunRegistry.ensure({
+    conversationKey,
+    runId,
+    grants: ctx.browserRun?.grants,
+    allowedUploadRoots: ctx.browserRun?.allowedUploadRoots,
+  });
+  try {
+    browserRunRegistry.requireGrant(run, 'interact');
+    if (input.steps.some((step) => step.intent === 'submit'))
+      browserRunRegistry.requireGrant(run, 'submit');
+    const uploadSteps = input.steps.filter((step) => step.action === 'upload');
+    if (uploadSteps.length) {
+      browserRunRegistry.requireGrant(run, 'upload');
+      const roots = await Promise.all(
+        run.allowedUploadRoots.map(async (root) => {
+          try {
+            return await realpath(root);
+          } catch {
+            return root;
+          }
+        }),
+      );
+      if (!roots.length)
+        throw new Error('当前浏览器任务没有获批的文件上传范围');
+      for (const file of uploadSteps.flatMap((step) => step.files ?? [])) {
+        const canonical = await realpath(file).catch(() => '');
+        if (!canonical) throw new Error(`上传文件不存在或不可读取：${file}`);
+        const allowed = roots.some((root) => {
+          const child = relative(root, canonical);
+          return (
+            child === '' || (!child.startsWith('..') && !isAbsolute(child))
+          );
+        });
+        if (!allowed) throw new Error(`上传文件超出当前任务批准范围：${file}`);
+      }
+    }
+    const bundleDirs = input.steps
+      .filter(
+        (step) =>
+          ['pageAssets', 'bundlePageAssets'].includes(step.action) &&
+          (step.bundle_assets || step.action === 'bundlePageAssets'),
+      )
+      .map((step) => step.bundle_dir)
+      .filter((value): value is string => Boolean(value));
+    for (const bundleDir of bundleDirs) {
+      const roots = [browserArtifactDir(), getWorkingDir()];
+      const target = await realpath(bundleDir).catch(() => bundleDir);
+      const allowed = roots.some((root) => {
+        const child = relative(root, target);
+        return child === '' || (!child.startsWith('..') && !isAbsolute(child));
+      });
+      if (!allowed)
+        throw new Error(
+          `资产打包目录不在浏览器产物或工作区范围内：${bundleDir}`,
+        );
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  try {
+    let claimedTabId = input.tab_id
+      ? await claimConversationTabById(
+          {
+            context: run,
+            sessionName: BROWSER_SESSION,
+            bin,
+            globals: sessionArgs(BROWSER_SESSION),
+            runner: spawnRunner,
+            signal,
+          },
+          input.tab_id,
+        )
+      : await ensureConversationTab({
+          context: run,
+          sessionName: BROWSER_SESSION,
+          bin,
+          globals: sessionArgs(BROWSER_SESSION),
+          runner: spawnRunner,
+          signal,
+        });
+    if (input.retention) {
+      browserRunRegistry.markTab(run, claimedTabId, {
+        retention: input.retention,
+        ...(input.tab_title ? { title: input.tab_title } : {}),
+      });
+    }
+    const serviceInput = {
+      sessionName: BROWSER_SESSION,
+      bin,
+      runner: spawnRunner,
+      signal,
+    };
+    const runExclusive = <T>(task: () => Promise<T>): Promise<T> =>
+      browserService.exclusive(serviceInput, async () => task());
+    // Do not hold the process-wide browser mutation lock while waiting for a
+    // human. Desktop must be able to click/type during waiting_human; only
+    // each setup/action/final-observation critical section is serialized.
+    return await (async () => {
+      const tabMarker = `${conversationKey}:${runId}:${randomUUID()}`;
+      const markActiveTab = async (
+        markerSignal?: AbortSignal,
+      ): Promise<void> => {
+        const marked = await spawnRunner(
+          bin,
+          [
+            ...sessionArgs(BROWSER_SESSION),
+            'eval',
+            `globalThis[${JSON.stringify(BROWSER_TAB_MARKER_KEY)}]=${JSON.stringify(tabMarker)}`,
+          ],
+          markerSignal,
+        );
+        if (marked.code !== 0)
+          throw new Error(marked.stderr || '无法标记当前浏览器会话标签');
+      };
+      // Reuse the same owned tab policy as WebBrowser before opening CDP.  This
+      // makes a batch one atomic lease instead of an accidental shared tab.
+      // Setup is serialized, but this lock is released before any human wait.
+      const setup = await runExclusive(async () => {
+        const switched = await spawnRunner(
+          bin,
+          [...sessionArgs(BROWSER_SESSION), 'tab', claimedTabId],
+          signal,
+        );
+        if (switched.code !== 0)
+          throw new Error(switched.stderr || '无法切换到已认领的浏览器标签页');
+        await markActiveTab(signal);
+        // The daemon exposes a browser-level CDP endpoint. Prefer the URL of
+        // the tab we just claimed when attaching a page target, otherwise a
+        // multi-tab session could silently bind the last unrelated tab.
+        const currentPage = await spawnRunner(
+          bin,
+          [...sessionArgs(BROWSER_SESSION), 'get', 'url'],
+          signal,
+        );
+        const lastKnownUrl =
+          currentPage.code === 0 ? currentPage.stdout.trim() : undefined;
+        const cdp = await getBrowserAutomation(
+          BROWSER_SESSION,
+          bin,
+          spawnRunner,
+          signal,
+          lastKnownUrl,
+          tabMarker,
+        );
+        return { cdp, lastKnownUrl };
+      });
+      let { cdp, lastKnownUrl } = setup;
+      const snapshotKey = () => `${conversationKey}:${runId}:${claimedTabId}`;
+
+      /**
+       * Rebind both sides of the tab lease after a daemon/page restart.
+       * A CDP reconnect alone is insufficient: the old tab id may have
+       * disappeared with the browser process, and attaching the last page
+       * would silently send the next action to another conversation.
+       */
+      const rebindTab = async (recoverySignal?: AbortSignal): Promise<void> => {
+        const rebound = await spawnRunner(
+          bin,
+          [...sessionArgs(BROWSER_SESSION), 'tab', claimedTabId],
+          recoverySignal,
+        );
+        if (rebound.code === 0) {
+          const active = await spawnRunner(
+            bin,
+            [...sessionArgs(BROWSER_SESSION), 'get', 'url'],
+            recoverySignal,
+          );
+          if (active.code === 0) lastKnownUrl = active.stdout.trim();
+        } else {
+          const beforeResult = await spawnRunner(
+            bin,
+            [...sessionArgs(BROWSER_SESSION), 'tab', 'list', '--json'],
+            recoverySignal,
+          );
+          if (beforeResult.code !== 0)
+            throw new Error(
+              beforeResult.stderr || '浏览器重启后无法读取标签列表',
+            );
+          const beforeIds = new Set(
+            parseTabList(beforeResult.stdout).map((tab) => tab.id),
+          );
+          const created = await spawnRunner(
+            bin,
+            [
+              ...sessionArgs(BROWSER_SESSION),
+              'tab',
+              'new',
+              lastKnownUrl || 'about:blank',
+            ],
+            recoverySignal,
+          );
+          if (created.code !== 0)
+            throw new Error(created.stderr || '浏览器重启后无法创建恢复标签');
+          const afterResult = await spawnRunner(
+            bin,
+            [...sessionArgs(BROWSER_SESSION), 'tab', 'list', '--json'],
+            recoverySignal,
+          );
+          if (afterResult.code !== 0)
+            throw new Error(
+              afterResult.stderr || '浏览器重启后无法确认恢复标签',
+            );
+          const added = parseTabList(afterResult.stdout).filter(
+            (tab) => !beforeIds.has(tab.id),
+          );
+          const replacement = added.find((tab) => tab.active) ?? added.at(-1);
+          if (!replacement)
+            throw new Error('浏览器重启后未返回新的恢复标签 ID');
+          browserRunRegistry.releaseTab(run.conversationKey, claimedTabId);
+          browserRunRegistry.claimTab(run, replacement.id);
+          claimedTabId = replacement.id;
+        }
+        const active = await spawnRunner(
+          bin,
+          [...sessionArgs(BROWSER_SESSION), 'get', 'url'],
+          recoverySignal,
+        );
+        if (active.code === 0) lastKnownUrl = active.stdout.trim();
+        await markActiveTab(recoverySignal);
+      };
+      const rebindTabAndPage = async (
+        recoverySignal?: AbortSignal,
+      ): Promise<void> => {
+        await rebindTab(recoverySignal);
+        await cdp.attachToPage(lastKnownUrl, true, tabMarker);
+      };
+      const downloadDir = await runExclusive(() =>
+        configureDownloads(cdp, conversationKey, runId),
+      );
+      const stream = getBrowserStream(BROWSER_SESSION);
+      let currentStepAbort: AbortController | undefined;
+      let offControl: (() => void) | undefined;
+      let offDownload: (() => void) | undefined;
+      // ⚠️ 取锁必须是 try 的第一行，释放必须在同一个 finally 内——这把锁是进程级
+      // 单例，唯一释放路径是下面的 finally。此前 beginAgentAction 与
+      // stream.finishAgentAction 分属两个不同的 try 块（中间横跨整段初始化 +
+      // 整个逐步执行循环），ctx.reportProgress（宿主注入回调）等任何一步抛错都会
+      // 跳过 finishAgentAction，锁永久不释放——对齐 webbrowser.ts 的写法（见其头注）。
+      try {
+        stream.beginAgentAction({ runId, conversationKey, action: 'batch' });
+        offControl = stream.subscribeControl((state) => {
+          if (state.status === 'waiting_human')
+            currentStepAbort?.abort(new Error('浏览器已交给用户处理'));
+        });
+        stream.setAgentActing(true, 'batch', `${input.steps.length} 个步骤`);
+        ctx.reportProgress?.(
+          `开始浏览器批量任务，共 ${input.steps.length} 个步骤`,
+        );
+      const downloads = new Map<string, DownloadItem>();
+      const subscribeDownloadEvents = (
+        connection: Awaited<ReturnType<typeof getBrowserAutomation>>,
+      ): (() => void) =>
+        connection.subscribe((event) => {
+          if (event.method === 'Browser.downloadWillBegin') {
+            const id = String(event.params.guid ?? randomUUID());
+            const item = {
+              id,
+              url: String(event.params.url ?? ''),
+              filename:
+                basename(
+                  String(event.params.suggestedFilename ?? 'download'),
+                ) || 'download',
+              path: join(
+                downloadDir,
+                basename(
+                  String(event.params.suggestedFilename ?? 'download'),
+                ) || 'download',
+              ),
+              state: 'start' as const,
+              startedAt: Date.now(),
+            };
+            downloads.set(id, item);
+            stream.publish({ type: 'download', ...item, state: 'start' });
+          }
+          if (event.method === 'Browser.downloadProgress') {
+            const id = String(event.params.guid ?? '');
+            const item = downloads.get(id);
+            if (!item) return;
+            const state =
+              event.params.state === 'completed'
+                ? 'complete'
+                : event.params.state === 'canceled'
+                  ? 'canceled'
+                  : 'progress';
+            item.state = state;
+            item.receivedBytes =
+              Number(event.params.receivedBytes ?? 0) || undefined;
+            item.totalBytes = Number(event.params.totalBytes ?? 0) || undefined;
+            item.error =
+              typeof event.params.error === 'string'
+                ? event.params.error
+                : undefined;
+            stream.publish({
+              type: 'download',
+              ...item,
+              state,
+              receivedBytes: item.receivedBytes,
+              totalBytes: item.totalBytes,
+              ...(item.error ? { error: item.error } : {}),
+            });
+          }
+        });
+      offDownload = subscribeDownloadEvents(cdp);
+      const results: Array<Record<string, unknown>> = [];
+      let artifactManifest: DeliverableManifest | undefined;
+      for (const [index, step] of input.steps.entries()) {
+        const started = Date.now();
+        const stepAbort = new AbortController();
+        currentStepAbort = stepAbort;
+        const abortFromParent = () => stepAbort.abort(signal?.reason);
+        if (signal?.aborted) stepAbort.abort(signal.reason);
+        else signal?.addEventListener('abort', abortFromParent, { once: true });
+        const waits: Promise<CdpEvent>[] = [];
+        try {
+          ctx.reportProgress?.(
+            `浏览器批量任务 ${index + 1}/${input.steps.length}：${step.action}`,
+          );
+          const conditions = step.expect?.conditions ?? [];
+          const preHuman = await runExclusive(async () => {
+            const eventCursor = cdp.read(0).at(-1)?.sequence ?? 0;
+            const baseline = await evaluate(
+              cdp,
+              `location.href + '|' + (document.body?.innerText || '').slice(0, 4000)`,
+              stepAbort.signal,
+            ).catch(() => undefined);
+            if (step.expect?.navigation)
+              waits.push(
+                waitFor(
+                  cdp,
+                  (e) =>
+                    e.method.startsWith('Page.frame') &&
+                    (!step.expect?.navigation?.url ||
+                      JSON.stringify(e.params).includes(
+                        step.expect.navigation.url,
+                      )),
+                  timeoutMs,
+                  eventCursor,
+                  stepAbort.signal,
+                ),
+              );
+            if (step.expect?.new_tab)
+              waits.push(
+                waitFor(
+                  cdp,
+                  (e) =>
+                    e.method === 'Target.targetCreated' &&
+                    (!step.expect?.new_tab?.url ||
+                      JSON.stringify(e.params).includes(
+                        step.expect.new_tab.url,
+                      )),
+                  timeoutMs,
+                  eventCursor,
+                  stepAbort.signal,
+                ),
+              );
+            if (step.expect?.download)
+              waits.push(
+                waitFor(
+                  cdp,
+                  (e) =>
+                    e.method === 'Browser.downloadWillBegin' &&
+                    (!step.expect?.download?.filename ||
+                      String(e.params.suggestedFilename ?? '').includes(
+                        step.expect.download.filename,
+                      )),
+                  timeoutMs,
+                  eventCursor,
+                  stepAbort.signal,
+                ),
+              );
+            const uploadChooser =
+              step.action === 'upload' &&
+              (step.trigger_selector || step.trigger_locator)
+                ? { files: step.files }
+                : undefined;
+            if (step.expect?.file_chooser || uploadChooser)
+              waits.push(
+                waitFor(
+                  cdp,
+                  (e) => e.method === 'Page.fileChooserOpened',
+                  timeoutMs,
+                  eventCursor,
+                  stepAbort.signal,
+                ),
+              );
+            for (const condition of step.expect?.conditions ?? []) {
+              if (
+                condition.type === 'download' ||
+                condition.type === 'new-tab' ||
+                condition.type === 'dialog'
+              ) {
+                waits.push(
+                  waitFor(
+                    cdp,
+                    (event) =>
+                      eventMatchesCondition(
+                        condition as BrowserCondition,
+                        event,
+                      ),
+                    timeoutMs,
+                    eventCursor,
+                    stepAbort.signal,
+                  ),
+                );
+              }
+            }
+            const value = await withBrowserRecovery(
+              () =>
+                executeStep(
+                  cdp,
+                  step,
+                  timeoutMs,
+                  eventCursor,
+                  snapshotKey(),
+                  stepAbort.signal,
+                ),
+              {
+                signal: stepAbort.signal,
+                reconnect: async () => {
+                  await ensureDaemon(BROWSER_SESSION, {
+                    signal: stepAbort.signal,
+                    forceRestart: true,
+                  });
+                  browserRunRegistry.invalidateAllTabs();
+                  // A daemon restart can publish a new browser-level WebSocket
+                  // URL. Rebind the tab first, then mark that exact tab, and
+                  // only then create a fresh page-scoped CDP connection.
+                  await rebindTab(stepAbort.signal);
+                  const previousCdp = cdp;
+                  offDownload?.();
+                  cdp = await getBrowserAutomation(
+                    BROWSER_SESSION,
+                    bin,
+                    spawnRunner,
+                    stepAbort.signal,
+                    lastKnownUrl,
+                    tabMarker,
+                  );
+                  offDownload = subscribeDownloadEvents(cdp);
+                  previousCdp.close();
+                },
+                rebindTab: async () => {
+                  await rebindTabAndPage(stepAbort.signal);
+                },
+              },
+            );
+            if (step.action === 'navigate' && step.url) lastKnownUrl = step.url;
+            let events: CdpEvent[] = [];
+            if (waits.length) {
+              const challengeAbort = new AbortController();
+              const challengeRace = waitForBrowserChallenge(
+                cdp,
+                timeoutMs,
+                challengeAbort.signal,
+              ).then((challenge) => {
+                if (challenge)
+                  throw new Error(`页面需要人工验证：${challenge.summary}`);
+                return new Promise<never>(() => undefined);
+              });
+              try {
+                events = await Promise.race([
+                  Promise.all(waits),
+                  challengeRace,
+                ]);
+              } finally {
+                challengeAbort.abort();
+              }
+            }
+            if (step.artifact && step.action === 'exportContent') {
+              const nextManifest = await materializeExportArtifact(
+                value,
+                step.export_format ?? 'page',
+                step.artifact.save_as,
+              );
+              if (step.artifact.label)
+                nextManifest.files[0].label = step.artifact.label;
+              artifactManifest = mergeArtifactManifests(
+                artifactManifest,
+                nextManifest,
+              );
+            } else if (step.artifact) {
+              const startedDownload = events.find(
+                (event) => event.method === 'Browser.downloadWillBegin',
+              );
+              const downloadId = String(startedDownload?.params.guid ?? '');
+              const item = downloadId
+                ? downloads.get(downloadId)
+                : [...downloads.values()].at(-1);
+              if (!item) throw new Error('未捕获到要保存为成果的下载');
+              if (item.state !== 'complete') {
+                const completed = await waitForEventOrBrowserChallenge(
+                  cdp,
+                  (event) =>
+                    event.method === 'Browser.downloadProgress' &&
+                    String(event.params.guid ?? '') === item.id &&
+                    ['completed', 'canceled'].includes(
+                      String(event.params.state ?? ''),
+                    ),
+                  timeoutMs,
+                  eventCursor,
+                  stepAbort.signal,
+                );
+                if (completed.params.state !== 'completed')
+                  throw new Error(
+                    `下载未完成：${String(completed.params.state ?? 'unknown')}`,
+                  );
+                item.state = 'complete';
+              }
+              item.path = await waitForDownloadedFile(
+                downloadDir,
+                item,
+                timeoutMs,
+                stepAbort.signal,
+              );
+              const nextManifest = await materializeDownloadArtifact(
+                item.path,
+                step.artifact.save_as,
+              );
+              if (step.artifact.label) {
+                nextManifest.files[0].label = step.artifact.label;
+              }
+              artifactManifest = mergeArtifactManifests(
+                artifactManifest,
+                nextManifest,
+              );
+            }
+            const chooser = step.expect?.file_chooser ?? uploadChooser;
+            if (chooser?.files?.length) {
+              const opened = events.find(
+                (event) => event.method === 'Page.fileChooserOpened',
+              );
+              const backendNodeId = Number(opened?.params.backendNodeId ?? 0);
+              if (!backendNodeId)
+                throw new Error(
+                  'Browser did not provide the file chooser node',
+                );
+              await cdp.send('DOM.setFileInputFiles', {
+                files: chooser.files,
+                backendNodeId,
+              });
+            }
+            for (const condition of conditions) {
+              if (
+                condition.type === 'download' ||
+                condition.type === 'new-tab' ||
+                condition.type === 'dialog'
+              )
+                continue;
+              await waitForCondition(
+                cdp,
+                condition as BrowserCondition,
+                timeoutMs,
+                baseline,
+                stepAbort.signal,
+              );
+            }
+            const challenge = await readBrowserChallenge(cdp, stepAbort.signal);
+            return { value, events, challenge };
+          });
+          const { value, events, challenge } = preHuman;
+          let humanSnapshot: Awaited<ReturnType<typeof snapshot>> | undefined;
+          if (challenge) {
+            stream.requestHuman(challenge.reason, {
+              runId,
+              conversationKey,
+              ownerId: 'local-owner',
+              summary: challenge.summary,
+            });
+            const resolution = await resumeBatchAfterHuman(
+              stream,
+              ctx,
+              signal,
+              challenge.summary,
+            );
+            if (resolution === 'stopped')
+              throw new Error('浏览器批量任务已由用户停止');
+            humanSnapshot = await runExclusive(() =>
+              snapshot(cdp, snapshotKey(), 'full', signal),
+            );
+          }
+          results.push({
+            id: step.id ?? String(index + 1),
+            ok: true,
+            duration_ms: Date.now() - started,
+            result: value,
+            resolution_strategy: resolveInteractionStrategy(step),
+            events,
+            ...(humanSnapshot
+              ? {
+                  human_intervention: 'resumed',
+                  post_intervention_snapshot: humanSnapshot,
+                }
+              : {}),
+            ...(conditions.length
+              ? {
+                  conditions_satisfied: conditions.map(
+                    (condition) => condition.type,
+                  ),
+                }
+              : {}),
+          });
+        } catch (error) {
+          await Promise.allSettled(waits);
+          let errorMessage =
+            error instanceof Error ? error.message : String(error);
+          if (stream.getControlState().status !== 'waiting_human') {
+            const challenge = await runExclusive(() =>
+              readBrowserChallenge(cdp).catch(() => null),
+            );
+            if (challenge) {
+              stream.requestHuman(challenge.reason, {
+                runId,
+                conversationKey,
+                ownerId: 'local-owner',
+                summary: challenge.summary,
+              });
+            }
+          }
+          if (stream.getControlState().status === 'waiting_human') {
+            const resolution = await resumeBatchAfterHuman(
+              stream,
+              ctx,
+              signal,
+              '浏览器批量步骤已暂停',
+            );
+            if (resolution === 'resumed') {
+              const recovered = await runExclusive(() =>
+                snapshot(cdp, snapshotKey(), 'full', signal),
+              );
+              results.push({
+                id: step.id ?? String(index + 1),
+                ok: false,
+                duration_ms: Date.now() - started,
+                resolution_strategy: resolveInteractionStrategy(step),
+                error:
+                  '人工接管中断了当前步骤；浏览器已恢复，但该步骤是否完成无法自动确认。请依据最新快照重新确认后再继续。',
+                result: {
+                  human_intervention: 'resumed_unverified',
+                  post_intervention_snapshot: recovered,
+                },
+              });
+              // Never continue subsequent steps with an unknown side effect:
+              // a click may have landed before the handoff, while a form
+              // submission may still be pending. The next model turn can
+              // inspect the fresh snapshot and deliberately resume.
+              break;
+            }
+            errorMessage = '浏览器批量任务已由用户停止';
+          }
+          results.push({
+            id: step.id ?? String(index + 1),
+            ok: false,
+            duration_ms: Date.now() - started,
+            resolution_strategy: resolveInteractionStrategy(step),
+            error: errorMessage,
+          });
+          if (stopOnError) break;
+        } finally {
+          stepAbort.abort();
+          signal?.removeEventListener('abort', abortFromParent);
+          if (currentStepAbort === stepAbort) currentStepAbort = undefined;
+        }
+      }
+      let final: Awaited<ReturnType<typeof snapshot>> | undefined;
+      let finalScreenshot: string | undefined;
+      await runExclusive(async () => {
+          final =
+            finalSnapshotMode === 'none'
+              ? undefined
+              : await snapshot(
+                  cdp,
+                  `${conversationKey}:${runId}:${claimedTabId}`,
+                  finalSnapshotMode,
+                  signal,
+                );
+          if (captureMode === 'screenshot' || captureMode === 'both') {
+            const path = await createArtifactPath('browser-batch-final', 'png');
+            const captured = (await cdp.send('Page.captureScreenshot', {
+              format: 'png',
+              fromSurface: true,
+            })) as { data?: string };
+            if (!captured.data) throw new Error('浏览器未返回最终截图');
+            await writeFile(path, Buffer.from(captured.data, 'base64'), {
+              mode: 0o600,
+            });
+            finalScreenshot = path;
+          }
+        });
+        const failed = results.some((result) => result.ok === false);
+        const content = JSON.stringify({
+          tab_id: claimedTabId,
+          download_dir: downloadDir,
+          results,
+          ...(final ? { final_snapshot: final } : {}),
+          ...(finalScreenshot ? { final_screenshot: finalScreenshot } : {}),
+        });
+        // A direct export (PDF/MD/Workspace formats) has no Browser.download*
+        // event, but it is still a formal browser deliverable. Keep one
+        // metadata envelope for the Desktop delivery ledger and allow an empty
+        // downloads list for that case.
+        const metadata =
+          downloads.size || artifactManifest
+            ? {
+                kind: 'browser_download' as const,
+                downloads: [...downloads.values()],
+                ...(artifactManifest ? { artifact: artifactManifest } : {}),
+              }
+            : undefined;
+        return failed
+          ? { ok: false, error: content, ...(metadata ? { metadata } : {}) }
+          : { ok: true, content, ...(metadata ? { metadata } : {}) };
+      } finally {
+        offDownload?.();
+        offControl?.();
+        currentStepAbort?.abort();
+        currentStepAbort = undefined;
+        cdp.close();
+        stream.finishAgentAction(runId);
+        try {
+          stream.setAgentActing(false);
+        } catch {
+          // UI decoration failure must not hide the batch result or leak control state.
+        }
+      }
+    })();
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    // AX snapshots are part of the BrowserBatch contract: the model may use
+    // the returned generation in the next tool call. Keep them behind the
+    // bounded TTL/capacity eviction in captureFinalSnapshot instead of
+    // invalidating the reference as soon as this call returns.
+    browserRunRegistry.finish(conversationKey, runId);
+  }
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: Tool's schema parser supplies the inferred output type.
+export const browserBatchTool: Tool<any> = {
+  name: 'BrowserBatch',
+  description:
+    'Executes multiple visible-browser actions under one tab claim and one persistent CDP connection. Supports semantic locators, event expectations, downloads, waits and final snapshots.',
+  inputSchema,
+  parameters: toToolParameters(inputSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call,
+  callWithContext: call,
+};