minimal-agent 0.13.0 → 0.15.0

package/src/tools/webbrowser/browserBatch.js

@@ -0,0 +1,1578 @@
+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 { 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, configureDownloads, getBrowserAutomation, } from './browserAutomation.js';
+import { conciseAxTree, diffAxTree, normalizeAxTree, } from './browserAxState.js';
+import { conditionToScript, } from './browserConditions.js';
+import { 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 { normalizeFrameInfo, normalizeFrameTree, } from './browserFrames.js';
+import { resolveInteractionStrategy } from './browserInteractionResolver.js';
+import { 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';
+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(),
+});
+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(),
+});
+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'),
+});
+const snapshots = new Map();
+const MAX_SNAPSHOTS = 256;
+const SNAPSHOT_TTL_MS = 15 * 60_000;
+function jsString(value) {
+    return JSON.stringify(value);
+}
+const DOWNLOAD_MIME_BY_EXT = {
+    '.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) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+async function materializeDownloadArtifact(sourcePath, saveAs) {
+    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, item, timeout, signal) {
+    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 !== 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, format, saveAs) {
+    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;
+    if (value &&
+        typeof value === 'object' &&
+        '__browser_pdf_base64' in value &&
+        typeof value
+            .__browser_pdf_base64 === 'string') {
+        bytes = Buffer.from(value.__browser_pdf_base64, 'base64');
+    }
+    else if (value &&
+        typeof value === 'object' &&
+        '__browser_binary_base64' in value &&
+        typeof value
+            .__browser_binary_base64 === 'string') {
+        bytes = Buffer.from(value.__browser_binary_base64, 'base64');
+    }
+    else if (format === 'html' && value && typeof value === 'object') {
+        bytes = Buffer.from(String(value.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.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, next) {
+    if (!current)
+        return next;
+    const files = new Map();
+    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();
+    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, expression, signal, frameId) {
+    if (frameId) {
+        const result = (await cdp.evaluateInFrame(frameId, expression, signal));
+        return result.result?.value ?? result.result?.description;
+    }
+    const result = (await cdp.send('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+    }, undefined, 30_000, signal));
+    return result.result?.value ?? result.result?.description;
+}
+async function waitFor(cdp, predicate, timeout, afterSequence = 0, signal) {
+    const pageEvent = (event) => {
+        // 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 = () => { };
+        const cleanup = () => {
+            clearTimeout(timer);
+            off();
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const finish = (callback) => {
+            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, signal) {
+    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
+                    : {};
+                const number = (key) => 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, key, mode, signal) {
+    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(() => ({})));
+    const frames = 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, locator, snapshotKey, signal) {
+    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 = 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, event) {
+    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) => `(() => { 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, condition, timeout, baseline, signal) {
+    const deadline = Date.now() + timeout;
+    const script = conditionToScript(condition, (locator, selector) => buildTargetExpression(locator, selector));
+    let lastValue;
+    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((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, signal) {
+    const text = String(await evaluate(cdp, `location.href + '\\n' + (document.body?.innerText || '').slice(0, 20000)`, signal).catch(() => ''));
+    return detectBrowserChallenge(text);
+}
+async function waitForBrowserChallenge(cdp, timeout, signal) {
+    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, predicate, timeout, afterSequence = 0, signal) {
+    const challengeAbort = new AbortController();
+    const challengeRace = waitForBrowserChallenge(cdp, timeout, challengeAbort.signal).then((challenge) => {
+        if (challenge)
+            throw new Error(`页面需要人工验证：${challenge.summary}`);
+        return new Promise(() => undefined);
+    });
+    try {
+        return await Promise.race([
+            waitFor(cdp, predicate, timeout, afterSequence, signal),
+            challengeRace,
+        ]);
+    }
+    finally {
+        challengeAbort.abort();
+    }
+}
+async function elementPoint(cdp, target, framePath = [], signal, frameId) {
+    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;
+        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;
+    if (typeof point.x !== 'number' || typeof point.y !== 'number')
+        throw new Error('浏览器元素坐标无效');
+    return { x: point.x, y: point.y };
+}
+async function trustedClick(cdp, target, framePath = [], signal, clickCount = 1, frameId) {
+    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, target, signal, frameId) {
+    await evaluate(cdp, `(()=>{const e=${target};e.scrollIntoView({block:'center',inline:'nearest'});e.focus();})()`, signal, frameId);
+}
+async function insertText(cdp, target, value, replace, signal, frameId) {
+    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, signal) {
+    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, ctx, signal, summary) {
+    ctx.reportProgress?.(`${summary}，等待你在浏览器中处理`);
+    const resolution = await stream.waitForHuman(signal);
+    if (resolution === 'resumed')
+        ctx.reportProgress?.('人工处理完成，正在重新读取页面状态并继续批量任务');
+    return resolution;
+}
+async function executeStep(cdp, step, timeout, afterSequence = 0, snapshotKey = 'step', signal) {
+    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 = 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)).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));
+            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));
+            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, step.bundle_dir, async (url) => {
+                    const fetched = await evaluate(cdp, browserAssetFetchExpression(url), signal);
+                    if (!fetched ||
+                        typeof fetched !== 'object' ||
+                        fetched.ok !== true ||
+                        typeof fetched.base64 !== 'string') {
+                        const status = fetched && typeof fetched === 'object'
+                            ? String(fetched.status ?? 'unknown')
+                            : 'unknown';
+                        throw new Error(`浏览器上下文抓取资源失败 HTTP ${status}`);
+                    }
+                    const value = fetched;
+                    return new Response(Buffer.from(value.base64, 'base64'), {
+                        status: 200,
+                        headers: value.type ? { 'content-type': value.type } : undefined,
+                    });
+                });
+                return { 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));
+                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), signal);
+                if (exported && typeof exported === 'object' && 'error' in exported)
+                    throw new Error(String(exported.error));
+                if (!exported ||
+                    typeof exported !== 'object' ||
+                    typeof exported
+                        .__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);
+            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, signal, ctx = {}) {
+    // 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) => 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 = (task) => 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) => {
+                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) => {
+                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) => {
+                await rebindTab(recoverySignal);
+                await cdp.attachToPage(lastKnownUrl, true, tabMarker);
+            };
+            const downloadDir = await runExclusive(() => configureDownloads(cdp, conversationKey, runId));
+            const stream = getBrowserStream(BROWSER_SESSION);
+            let currentStepAbort;
+            let offControl;
+            let offDownload;
+            // ⚠️ 取锁必须是 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();
+                const subscribeDownloadEvents = (connection) => 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',
+                            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 = [];
+                let artifactManifest;
+                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 = [];
+                    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, 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 = [];
+                            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(() => 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, timeoutMs, baseline, stepAbort.signal);
+                            }
+                            const challenge = await readBrowserChallenge(cdp, stepAbort.signal);
+                            return { value, events, challenge };
+                        });
+                        const { value, events, challenge } = preHuman;
+                        let humanSnapshot;
+                        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;
+                let finalScreenshot;
+                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,
+                        }));
+                        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',
+                        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 = {
+    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,
+};