@tea-agent/loop-agent 0.44.0-next.12 → 0.44.0-next.14

package/dist/worker/console/chat/browser-automation.js

@@ -5,40 +5,78 @@
  * isolated from the user's normal browser without contaminating the repo.
  */
 import { randomUUID } from "node:crypto";
-import { mkdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { mkdir, open, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { chromium, } from "playwright-core";
+import { pickBrowserElement } from "./browser-pick.js";
+import { browserHtmlToMarkdown, captureBrowserHtml } from "./browser-content.js";
+import { exportBrowserStorage, mergeBrowserStorage, readBrowserStorage } from "./browser-storage.js";
+import { evaluateBrowserExpression, waitForBrowserOperation } from "./browser-evaluation.js";
+import { BrowserOperationQueue } from "./browser-operation-queue.js";
 import { normalizeBrowserUrl } from "./browser-policy.js";
+import { BrowserDiagnostics } from "./browser-diagnostics.js";
 export const BROWSER_VIEWPORT_WIDTH = 1280;
 export const BROWSER_VIEWPORT_HEIGHT = 900;
 const SEARCH_INPUT_SELECTORS = [
     "input[name='wd']",
     "input[name='q']",
     "input[name='query']",
+    "input[name='search']",
     "input[type='search']",
+    "[role='searchbox']",
+    "textarea[name='wd']",
+    "textarea[name='q']",
+    "textarea[name='query']",
+    "textarea[type='search']",
     "input[type='text']",
+    "textarea",
 ];
 const SEARCH_SUBMIT_SELECTORS = [
     "button[type='submit']",
     "input[type='submit']",
-    "button:not([type])",
 ];
-const DEFAULT_SEARCH_ENGINE_URL = "https://www.baidu.com/";
+export const DEFAULT_SEARCH_ENGINE_URL = "https://www.bing.com/";
 const SEARCH_TYPING_DELAY_MS = 45;
 const DEFAULT_ACTION_TIMEOUT_MS = 15_000;
+const NAVIGATION_SETTLE_WINDOW_MS = 400;
+const NAVIGATION_SETTLE_CAP_MS = 2_000;
+const SEARCH_RESULT_TIMEOUT_MS = 15_000;
 const MAX_SNAPSHOT_CHARS = 24_000;
 const MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
 export class BrowserAutomationService {
     options;
+    operations = new BrowserOperationQueue();
+    snapshots = new WeakMap();
+    recovering = new WeakSet();
     browserPromise;
     activePage;
+    diagnostics = new BrowserDiagnostics();
     tabs = new Map();
     nextTabId = 1;
     disposed = false;
     dialogQueue = [];
     downloadQueue = [];
+    mirrorPage;
+    mirrorSession;
+    mirrorSeq = 0;
+    mirrorFrame;
     constructor(options) {
         this.options = options;
+        // The visible window stays the default so human picking works out of the
+        // box. LOOP_BROWSER_HEADLESS=1 (or "true"/"on") switches the browser to a
+        // background (headless) instance that never opens a window.
+        if (this.options.headless === undefined) {
+            this.options.headless = browserHeadlessEnabled();
+        }
+    }
+    /** Runtime entrypoint: tools and HTTP must enter once, binding the target before queuing. */
+    run(input, operation) {
+        const page = input.tabId === undefined ? this.activePage : this.tabs.get(input.tabId);
+        if (input.tabId !== undefined && (!page || page.isClosed())) {
+            return Promise.reject(new BrowserAutomationError("TAB_NOT_FOUND", `tab ${input.tabId} does not exist`));
+        }
+        return this.operations.run({ page }, input.signal, operation);
     }
     async navigate(rawUrl) {
         const normalized = normalizeBrowserUrl(rawUrl);
@@ -54,6 +92,7 @@ export class BrowserAutomationService {
         try {
             const page = await this.page();
             await page.goto(normalized.url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+            await settleNavigation(page);
             const snapshot = await this.snapshot({ screenshot: false });
             return { ok: true, page: snapshot };
         }
@@ -64,23 +103,31 @@ export class BrowserAutomationService {
     async reload() {
         const page = await this.page();
         await page.reload({ waitUntil: "domcontentloaded", timeout: 30_000 });
+        await settleNavigation(page);
         return this.snapshot({ screenshot: false });
     }
     async goBack() {
         const page = await this.page();
         await page.goBack({ waitUntil: "domcontentloaded", timeout: 30_000 });
+        await settleNavigation(page);
         return this.snapshot({ screenshot: false });
     }
     async goForward() {
         const page = await this.page();
         await page.goForward({ waitUntil: "domcontentloaded", timeout: 30_000 });
+        await settleNavigation(page);
         return this.snapshot({ screenshot: false });
     }
     async snapshot(options) {
-        const page = await this.page();
+        const page = options?.tabId === undefined ? await this.page() : this.tabs.get(options.tabId);
+        if (!page || page.isClosed())
+            throw new BrowserAutomationError("TAB_NOT_FOUND", "requested tab is unavailable");
+        if (this.recovering.has(page))
+            throw new BrowserAutomationError("PAGE_BUSY", "page script may still be running; wait or explicitly close this tab");
         const dialog = this.dialogFor(page);
         if (dialog) {
             return {
+                tabId: this.trackPage(page),
                 url: page.url(),
                 title: "浏览器弹窗",
                 tabs: await this.tabSummaries(),
@@ -88,7 +135,7 @@ export class BrowserAutomationService {
                 ariaSnapshot: "",
                 ...(options?.screenshot === false
                     ? {}
-                    : { screenshot: await this.captureScreenshot(page) }),
+                    : await this.captureScreenshot(page, options?.fullPage)),
             };
         }
         const [title, aria] = await Promise.all([
@@ -97,15 +144,19 @@ export class BrowserAutomationService {
         ]);
         const download = await this.nextDownloadResult();
         const screenshot = options?.screenshot === false
-            ? undefined
-            : await this.captureScreenshot(page);
+            ? {}
+            : await this.captureScreenshot(page, options?.fullPage);
+        const snapshotId = randomUUID();
+        this.snapshots.set(page, snapshotId);
         return {
+            tabId: this.trackPage(page),
+            snapshotId,
             url: page.url(),
             title,
             tabs: await this.tabSummaries(),
             dialog,
             ariaSnapshot: truncateText(aria, MAX_SNAPSHOT_CHARS),
-            ...(screenshot ? { screenshot } : {}),
+            ...screenshot,
             ...(download ? { download } : {}),
         };
     }
@@ -115,18 +166,53 @@ export class BrowserAutomationService {
      */
     async state() {
         if (!this.browserPromise && !this.disposed)
-            return emptyBrowserState();
-        const page = await this.page();
+            return { ...emptyBrowserState(), headless: this.options.headless === true };
+        // Polling never starts a context, changes selection, or waits on a quarantined page.
+        const page = this.operations.current?.target.page ?? this.activePage;
+        if (!page || page.isClosed())
+            return { ...emptyBrowserState(), running: !!this.browserPromise, headless: this.options.headless === true, tabs: await this.tabSummaries() };
         const state = {
             running: true,
+            headless: this.options.headless === true,
+            tabId: this.trackPage(page),
             url: page.url(),
-            title: await page.title().catch(() => ""),
+            title: this.recovering.has(page) ? "Page busy — script may still be running" : await page.title().catch(() => ""),
             tabs: await this.tabSummaries(),
             dialog: this.dialogFor(page),
             ariaSnapshot: "",
         };
         return state;
     }
+    /**
+     * Passive screencast frame of the active page for the panel mirror view.
+     * Like state(), polling never launches the browser and never touches the
+     * operation queue, so a stuck page cannot block the panel.
+     */
+    async panelFrame(since = 0) {
+        if (!this.browserPromise || this.disposed) {
+            await this.stopMirror().catch(() => undefined);
+            return { running: false, changed: false, seq: this.mirrorSeq };
+        }
+        const page = this.operations.current?.target.page ?? this.activePage;
+        if (!page || page.isClosed()) {
+            return { running: true, changed: false, seq: this.mirrorSeq };
+        }
+        if (page !== this.mirrorPage || !this.mirrorSession) {
+            await this.startMirror(page);
+        }
+        const frame = this.mirrorFrame;
+        if (!frame || this.mirrorSeq <= since) {
+            return { running: true, changed: false, seq: this.mirrorSeq };
+        }
+        return {
+            running: true,
+            changed: true,
+            seq: this.mirrorSeq,
+            url: page.url(),
+            title: await page.title().catch(() => ""),
+            image: `data:image/jpeg;base64,${frame.data}`,
+        };
+    }
     async search(rawQuery, rawUrl) {
         const query = rawQuery.trim();
         if (!query)
@@ -139,6 +225,7 @@ export class BrowserAutomationService {
         const page = await this.page();
         await page.bringToFront();
         await page.goto(normalized.url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+        await settleNavigation(page);
         const input = await findSearchInput(page);
         if (!input) {
             throw new BrowserAutomationError("SEARCH_INPUT_NOT_FOUND", "the search page did not expose a recognizable search input");
@@ -148,14 +235,22 @@ export class BrowserAutomationService {
             delay: SEARCH_TYPING_DELAY_MS,
             timeout: DEFAULT_ACTION_TIMEOUT_MS,
         });
-        await Promise.all([
-            page.waitForNavigation({ waitUntil: "domcontentloaded", timeout: 30_000 }),
-            submitSearchForm(page, input),
+        // Search forms may navigate (URL change) or submit client-side (no URL
+        // change). Wait for whichever settles first, but never return while a
+        // navigation is still pending: url-commit and network-idle both race here.
+        const beforeSubmit = page.url();
+        await submitSearchForm(input);
+        await Promise.race([
+            page.waitForURL((url) => url.toString() !== beforeSubmit, { timeout: SEARCH_RESULT_TIMEOUT_MS, waitUntil: "domcontentloaded" }).catch(() => undefined),
+            page.waitForLoadState("networkidle", { timeout: SEARCH_RESULT_TIMEOUT_MS }).catch(() => undefined),
         ]);
+        await settleNavigation(page);
         return this.snapshot({ screenshot: false });
     }
     async act(request) {
+        validateBrowserInput(request);
         const page = await this.page();
+        this.checkSnapshot(page, request.snapshotId);
         const ref = request.ref.trim();
         if (!/^(f\d+)?e\d+$/.test(ref)) {
             throw new BrowserAutomationError("INVALID_REF", "element ref must come from a fresh browser snapshot");
@@ -171,6 +266,12 @@ export class BrowserAutomationService {
             else if (request.type === "press") {
                 await locator.press(request.key, { timeout: DEFAULT_ACTION_TIMEOUT_MS });
             }
+            else if (request.type === "select") {
+                await locator.selectOption(request.options, { timeout: DEFAULT_ACTION_TIMEOUT_MS });
+            }
+            else if (request.type === "setChecked") {
+                await locator.setChecked(request.checked, { timeout: DEFAULT_ACTION_TIMEOUT_MS });
+            }
             else {
                 await locator.hover({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
             }
@@ -184,6 +285,21 @@ export class BrowserAutomationService {
         await page.waitForLoadState("domcontentloaded", { timeout: 3_000 }).catch(() => undefined);
         return { action: request.type, ref, page: await this.snapshot({ screenshot: false }) };
     }
+    /** Reading diagnostics never launches a browser or consumes snapshot/download state. */
+    consoleMessages(query = {}) {
+        return this.diagnostics.console(query, this.diagnosticTabId(query.tabId));
+    }
+    networkRequests(query = {}) {
+        return this.diagnostics.network(query, this.diagnosticTabId(query.tabId));
+    }
+    diagnosticTabId(tabId) {
+        if (tabId !== undefined) {
+            if (!this.tabs.has(tabId))
+                throw new BrowserAutomationError("TAB_NOT_FOUND", `tab ${tabId} does not exist`);
+            return tabId;
+        }
+        return this.activePage ? tabIdForValue(this.tabs, this.activePage) ?? null : null;
+    }
     async scroll(input) {
         const page = await this.page();
         const amount = clamp(input.amount ?? 600, 50, 3000);
@@ -201,7 +317,7 @@ export class BrowserAutomationService {
         const page = this.tabs.get(tabId);
         if (!page)
             throw new BrowserAutomationError("TAB_NOT_FOUND", `tab ${tabId} does not exist`);
-        this.activePage = page;
+        this.selectPage(page);
         await page.bringToFront();
         return this.snapshot({ screenshot: false });
     }
@@ -209,7 +325,7 @@ export class BrowserAutomationService {
         const context = await this.context();
         const page = await context.newPage();
         this.trackPage(page);
-        this.activePage = page;
+        this.selectPage(page);
         if (rawUrl) {
             const result = await this.navigate(rawUrl);
             if (!result.ok)
@@ -222,10 +338,12 @@ export class BrowserAutomationService {
         const page = tabId === undefined ? await this.page() : this.tabs.get(tabId);
         if (!page)
             throw new BrowserAutomationError("TAB_NOT_FOUND", `tab ${tabId} does not exist`);
-        this.tabs.delete(tabIdForValue(this.tabs, page) ?? 0);
         await page.close();
         if (this.activePage === page)
             this.activePage = undefined;
+        const current = this.operations.current;
+        if (current?.target.page === page)
+            current.target.page = undefined;
         return this.snapshot({ screenshot: false });
     }
     async handleDialog(action, promptText) {
@@ -266,10 +384,17 @@ export class BrowserAutomationService {
         await page.keyboard.type(text);
         return { ok: true };
     }
-    async screenshot() {
-        return this.snapshot({ screenshot: true });
+    async screenshot(options) {
+        return this.snapshot({ ...options, screenshot: true });
+    }
+    /** True when this service runs a visible browser instead of the background default. */
+    get visibleBrowser() {
+        return this.options.headless === false;
     }
     async focus() {
+        if (!this.visibleBrowser) {
+            throw new BrowserAutomationError("HEADLESS_NO_WINDOW", "浏览器正在后台运行（LOOP_BROWSER_HEADLESS=1），没有可聚焦的窗口；取消该设置并重启 Console 可恢复可见窗口，或在右侧面板预览当前页面");
+        }
         const page = await this.page();
         await page.bringToFront();
         return { ok: true };
@@ -279,12 +404,136 @@ export class BrowserAutomationService {
         await page.waitForTimeout(clamp(ms, 0, 10_000));
         return this.snapshot({ screenshot: false });
     }
+    async pick(input) {
+        if (this.options.headless === true)
+            throw new BrowserAutomationError("PICK_UNAVAILABLE", "human picking requires the visible external browser; unset LOOP_BROWSER_HEADLESS (or set it to 0) and restart the console to launch one");
+        const page = await this.page();
+        await page.bringToFront();
+        const element = await pickBrowserElement(page, input.message, clamp(input.timeoutMs ?? 30_000, 1, 60_000), this.operations.current?.signal).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "PAGE_BUSY")
+                this.recovering.add(page);
+            throw error;
+        });
+        try {
+            const snapshot = await this.snapshot({ screenshot: false });
+            for (const match of snapshot.ariaSnapshot.matchAll(/\[ref=((?:f\d+)?e\d+)\]/g)) {
+                const ref = match[1];
+                if (!ref)
+                    continue;
+                const same = await page.locator(`aria-ref=${ref}`).evaluate((candidate, selected) => candidate === selected, element).catch(() => false);
+                if (same)
+                    return { ref, tabId: snapshot.tabId, snapshotId: snapshot.snapshotId, page: snapshot };
+            }
+            throw new BrowserAutomationError("PICK_UNSUPPORTED", "selected element has no current ARIA ref (including unsupported frames); select an accessible control or inspect with eval");
+        }
+        finally {
+            await element.dispose();
+        }
+    }
+    async find(input) {
+        if (!input.text.trim())
+            throw new BrowserAutomationError("EMPTY_QUERY", "find requires visible text");
+        const page = await this.page();
+        const snapshot = await this.snapshot({ screenshot: false });
+        const candidates = [];
+        const limit = clamp(input.limit ?? 20, 1, 100);
+        let matchCount = 0;
+        for (const line of snapshot.ariaSnapshot.split("\n")) {
+            const match = /^\s*- (\w+)(?: "(.*?)")?[^\n]*?\[ref=((?:f\d+)?e\d+)\]/.exec(line);
+            if (!match?.[1] || !match[3])
+                continue;
+            const role = match[1];
+            const name = match[2] ?? "";
+            if (input.role && role !== input.role)
+                continue;
+            if (!name.toLocaleLowerCase().includes(input.text.toLocaleLowerCase()))
+                continue;
+            const locator = page.locator(`aria-ref=${match[3]}`);
+            if (!await locator.isVisible())
+                continue;
+            matchCount += 1;
+            if (candidates.length >= limit)
+                continue;
+            const context = await locator.evaluate((element) => (element.closest('tr,[role="row"],li,fieldset,section,[role="dialog"]')?.textContent ?? element.parentElement?.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 500));
+            candidates.push({ ref: match[3], role, name, context });
+        }
+        return { tabId: snapshot.tabId, snapshotId: snapshot.snapshotId, url: snapshot.url, candidates, matchCount, truncated: matchCount > candidates.length || snapshot.ariaSnapshot.includes("[snapshot truncated]") };
+    }
+    async content(input = {}) {
+        const page = await this.page();
+        if (input.ref)
+            this.checkSnapshot(page, input.snapshotId);
+        if (input.ref && !/^(f\d+)?e\d+$/.test(input.ref))
+            throw new BrowserAutomationError("INVALID_REF", "content region requires a current ref");
+        const html = await captureBrowserHtml(page.locator(input.ref ? `aria-ref=${input.ref}` : "html"));
+        return { tabId: this.trackPage(page), url: page.url(), ...browserHtmlToMarkdown(html, page.url(), input.mode) };
+    }
+    async cookies(includeValues = false) {
+        const context = await this.context();
+        const cookies = await context.cookies();
+        return { cookies: cookies.map(({ value, ...cookie }) => includeValues ? { ...cookie, value } : cookie), valuesIncluded: includeValues };
+    }
+    async exportStorage() {
+        return exportBrowserStorage(await this.context(), path.join(this.options.profileDir, "..", "storage"));
+    }
+    async importStorage(filename, mode) {
+        if (mode !== "merge")
+            throw new BrowserAutomationError("INVALID_STORAGE_MODE", "explicit merge mode is required; existing entries not listed in the file are preserved");
+        const state = await readBrowserStorage(filename, path.join(this.options.profileDir, "..", "storage"));
+        for (const page of this.tabs.values()) {
+            if (this.recovering.has(page))
+                throw new BrowserAutomationError("PAGE_BUSY", "wait for page scripts before importing login state");
+            this.snapshots.delete(page);
+        }
+        return mergeBrowserStorage(await this.context(), state);
+    }
+    async evaluate(expression, options = {}) {
+        if (!expression.trim() || expression.length > 100_000)
+            throw new BrowserAutomationError("INVALID_EXPRESSION", "provide a nonempty expression up to 100000 characters; use an async IIFE for statements");
+        const page = await this.page();
+        this.snapshots.delete(page);
+        this.recovering.add(page);
+        const pending = evaluateBrowserExpression(page, expression).finally(() => {
+            this.recovering.delete(page);
+            this.snapshots.delete(page);
+        });
+        return waitForBrowserOperation(pending, clamp(options.timeoutMs ?? 15_000, 1, 60_000), this.operations.current?.signal);
+    }
+    async waitUntil(input) {
+        if ([input.text, input.url, input.ref].filter((value) => value !== undefined).length !== 1) {
+            throw new BrowserAutomationError("INVALID_WAIT", "specify exactly one of text, url or ref");
+        }
+        const page = await this.page();
+        const timeout = clamp(input.timeoutMs ?? 15_000, 1, 60_000);
+        try {
+            if (input.url !== undefined)
+                await page.waitForURL(input.url, { timeout, waitUntil: "domcontentloaded" });
+            else if (input.text !== undefined)
+                await page.getByText(input.text, { exact: true }).first().waitFor({ state: input.state ?? "visible", timeout });
+            else {
+                this.checkSnapshot(page, input.snapshotId);
+                if (!/^(f\d+)?e\d+$/.test(input.ref ?? ""))
+                    throw new BrowserAutomationError("INVALID_REF", "invalid wait ref");
+                await page.locator(`aria-ref=${input.ref}`).waitFor({ state: input.state ?? "visible", timeout });
+            }
+        }
+        catch (cause) {
+            if (cause instanceof BrowserAutomationError)
+                throw cause;
+            throw new BrowserAutomationError("WAIT_TIMEOUT", errorMessage(cause), { cause });
+        }
+        return this.snapshot({ screenshot: false });
+    }
     async dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
+        await this.stopMirror().catch(() => undefined);
         const pending = this.browserPromise;
         this.browserPromise = undefined;
+        this.diagnostics.reset();
+        this.dialogQueue.length = 0;
+        this.downloadQueue.length = 0;
         this.tabs.clear();
         this.activePage = undefined;
         if (!pending)
@@ -292,18 +541,44 @@ export class BrowserAutomationService {
         const context = await pending.catch(() => undefined);
         await context?.close().catch(() => undefined);
     }
+    checkSnapshot(page, snapshotId) {
+        if (this.operations.current && !snapshotId)
+            throw new BrowserAutomationError("INVALID_REF", "snapshotId is required for ref operations");
+        if (snapshotId !== undefined && this.snapshots.get(page) !== snapshotId) {
+            throw new BrowserAutomationError("STALE_REF", "snapshot is stale or belongs to another tab; take a fresh snapshot");
+        }
+    }
+    /** Updates the operation-local page as well as the UI's last-selected page. */
+    selectPage(page) {
+        this.activePage = page;
+        const current = this.operations.current;
+        if (current)
+            current.target.page = page;
+    }
     async page() {
+        const bound = this.operations.current?.target.page;
+        if (bound) {
+            if (bound.isClosed())
+                throw new BrowserAutomationError("TAB_NOT_FOUND", "bound tab was closed; select a current tab");
+            if (this.recovering.has(bound))
+                throw new BrowserAutomationError("PAGE_BUSY", "page script may still be running; wait or explicitly close this tab");
+            return bound;
+        }
         const context = await this.context();
-        if (this.activePage && !this.activePage.isClosed())
+        if (this.activePage && !this.activePage.isClosed()) {
+            if (this.recovering.has(this.activePage))
+                throw new BrowserAutomationError("PAGE_BUSY", "page script may still be running; wait or explicitly close this tab");
+            this.selectPage(this.activePage);
             return this.activePage;
+        }
         const existing = context.pages().find((page) => this.tabs.has(tabIdForValue(this.tabs, page) ?? -1));
         if (existing) {
-            this.activePage = existing;
+            this.selectPage(existing);
             return existing;
         }
         const page = await context.newPage();
         this.trackPage(page);
-        this.activePage = page;
+        this.selectPage(page);
         return page;
     }
     async context() {
@@ -316,6 +591,10 @@ export class BrowserAutomationService {
                 mkdir(this.options.screenshotsDir, { recursive: true }),
             ]);
             const browser = await this.launchBrowser();
+            if (this.disposed) {
+                await browser.close();
+                throw new BrowserAutomationError("BROWSER_CLOSED", "browser service is disposed");
+            }
             this.wireContext(browser);
             const page = browser.pages()[0] ?? await browser.newPage();
             this.trackPage(page);
@@ -333,6 +612,9 @@ export class BrowserAutomationService {
         }
     }
     wireContext(context) {
+        this.diagnostics.attachContext(context, (page) => this.trackPage(page));
+        for (const page of context.pages())
+            this.trackPage(page);
         context.on("page", (page) => {
             this.trackPage(page);
             if (!this.activePage || this.activePage.isClosed())
@@ -344,7 +626,13 @@ export class BrowserAutomationService {
                     if (current === context) {
                         this.browserPromise = undefined;
                         this.activePage = undefined;
+                        this.diagnostics.reset();
+                        this.dialogQueue.length = 0;
+                        this.downloadQueue.length = 0;
                         this.tabs.clear();
+                        this.mirrorPage = undefined;
+                        this.mirrorSession = undefined;
+                        this.mirrorFrame = undefined;
                     }
                 });
             }
@@ -385,13 +673,60 @@ export class BrowserAutomationService {
         const id = this.nextTabId;
         this.nextTabId += 1;
         this.tabs.set(id, page);
+        this.diagnostics.trackPage(page, id);
+        page.on("framenavigated", () => this.snapshots.delete(page));
         page.on("close", () => {
+            this.diagnostics.removePage(id);
             this.tabs.delete(id);
             if (this.activePage === page)
                 this.activePage = undefined;
+            if (this.mirrorPage === page) {
+                this.mirrorPage = undefined;
+                this.mirrorSession = undefined;
+                this.mirrorFrame = undefined;
+            }
         });
         return id;
     }
+    /** Attaches a CDP screencast to the page, replacing any previous session. */
+    async startMirror(page) {
+        await this.stopMirror();
+        this.mirrorFrame = undefined;
+        try {
+            const session = await page.context().newCDPSession(page);
+            session.on("Page.screencastFrame", (frame) => {
+                this.mirrorSeq += 1;
+                this.mirrorFrame = { data: frame.data };
+                void session.send("Page.screencastFrameAck", { sessionId: frame.sessionId }).catch(() => undefined);
+            });
+            await session.send("Page.startScreencast", {
+                format: "jpeg",
+                quality: 85,
+                maxWidth: BROWSER_VIEWPORT_WIDTH,
+                maxHeight: BROWSER_VIEWPORT_HEIGHT,
+                everyNthFrame: 1,
+            });
+            this.mirrorSession = session;
+            this.mirrorPage = page;
+        }
+        catch {
+            await this.stopMirror().catch(() => undefined);
+        }
+    }
+    async stopMirror() {
+        const session = this.mirrorSession;
+        this.mirrorSession = undefined;
+        this.mirrorPage = undefined;
+        if (!session)
+            return;
+        try {
+            await session.send("Page.stopScreencast");
+        }
+        catch {
+            // The session may already be gone with its page or context.
+        }
+        await session.detach().catch(() => undefined);
+    }
     dialogFor(page) {
         const index = this.dialogQueue.findIndex((entry) => entry.page === page);
         const dialog = index >= 0 ? this.dialogQueue[index]?.dialog : undefined;
@@ -407,19 +742,34 @@ export class BrowserAutomationService {
         return Promise.all([...this.tabs.entries()].map(async ([id, page]) => ({
             id,
             url: page.url(),
-            title: page.isClosed() ? "" : await page.title().catch(() => ""),
+            title: page.isClosed() || this.recovering.has(page) ? "" : await page.title().catch(() => ""),
             active: !page.isClosed() && page === this.activePage,
         })));
     }
-    async captureScreenshot(page) {
-        const buffer = await page.screenshot({
-            type: "png",
-            fullPage: false,
-            timeout: 15_000,
-        });
-        if (buffer.byteLength > MAX_SCREENSHOT_BYTES)
-            return undefined;
-        return `data:image/png;base64,${buffer.toString("base64")}`;
+    async readScreenshot(filename) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.png$/.test(filename)) {
+            throw new BrowserAutomationError("SCREENSHOT_NOT_FOUND", "invalid screenshot identity");
+        }
+        const handle = await open(path.join(this.options.screenshotsDir, filename), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.size > 32 * 1024 * 1024)
+                throw new BrowserAutomationError("SCREENSHOT_TOO_LARGE", "screenshot exceeds the 32 MiB preview limit");
+            return await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async captureScreenshot(page, fullPage = false) {
+        const buffer = await page.screenshot({ type: "png", fullPage, timeout: 15_000 });
+        const screenshotPath = path.join(this.options.screenshotsDir, `${randomUUID()}.png`);
+        await writeFile(screenshotPath, buffer, { mode: 0o600, flag: "wx" });
+        const screenshotUrl = this.options.workspaceId ? `/api/operator/v1/chat/browser/screenshots/${path.basename(screenshotPath)}?workspaceId=${encodeURIComponent(this.options.workspaceId)}` : undefined;
+        if (buffer.byteLength > MAX_SCREENSHOT_BYTES) {
+            return { screenshotPath, screenshotUrl, screenshotError: "SCREENSHOT_TOO_LARGE: image exceeds 4 MiB; evidence saved, request a viewport screenshot" };
+        }
+        return { screenshotPath, screenshotUrl, screenshot: `data:image/png;base64,${buffer.toString("base64")}` };
     }
     async nextDownloadResult() {
         const index = this.downloadQueue.findIndex((entry) => !entry.consumed);
@@ -446,6 +796,25 @@ export class BrowserAutomationService {
         }
     }
 }
+function validateBrowserInput(request) {
+    if (request.type === "setChecked" && typeof request.checked !== "boolean") {
+        throw new BrowserAutomationError("INVALID_ACTION", "setChecked requires an explicit checked boolean");
+    }
+    if (request.type !== "select")
+        return;
+    if (!Array.isArray(request.options) || request.options.length > 100 || !request.options.every(validSelectOption)) {
+        throw new BrowserAutomationError("INVALID_ACTION", "select requires up to 100 options, each with exactly one value, label or non-negative index");
+    }
+}
+function validSelectOption(option) {
+    if (!option || typeof option !== "object" || Object.keys(option).length !== 1)
+        return false;
+    if ("value" in option)
+        return typeof option.value === "string";
+    if ("label" in option)
+        return typeof option.label === "string";
+    return "index" in option && Number.isSafeInteger(option.index) && option.index >= 0;
+}
 function emptyBrowserState() {
     return {
         running: false,
@@ -456,17 +825,55 @@ function emptyBrowserState() {
         ariaSnapshot: "",
     };
 }
-function chromiumLaunchOptions(headless) {
+/** Linux GitHub runners (and similar CI) have no usable Chromium sandbox. */
+export function chromiumSandboxEnabled(env = process.env) {
+    return env.GITHUB_ACTIONS !== "true" && env.CI !== "true";
+}
+export function chromiumLaunchOptions(headless, env = process.env) {
     return {
         headless: headless ?? false,
         viewport: undefined,
         acceptDownloads: true,
         locale: "zh-CN",
         timezoneId: "Asia/Shanghai",
-        args: ["--start-maximized", "--disable-blink-features=AutomationControlled"],
+        // Desktop: drop Playwright's implicit --no-sandbox so Chrome does not show
+        // the "unsupported command-line flag" infobar. CI Linux has no usable
+        // user-namespace sandbox, so keep Playwright's --no-sandbox there.
+        chromiumSandbox: chromiumSandboxEnabled(env),
+        args: ["--disable-blink-features=AutomationControlled"],
         ignoreDefaultArgs: ["--enable-automation"],
     };
 }
+/** LOOP_BROWSER_HEADLESS=1/true/on runs the browser in the background (headless). */
+export function browserHeadlessEnabled(env = process.env) {
+    const raw = env.LOOP_BROWSER_HEADLESS?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "on";
+}
+/**
+ * Bounded settle after a committed navigation. `domcontentloaded` fires before
+ * late client-side redirects (for example an engine that reroutes to a regional
+ * host), so a trailing short stability window keeps the next operation from
+ * racing an in-flight navigation. The cap keeps slow or long-polling pages from
+ * stalling the tool.
+ */
+async function settleNavigation(page) {
+    const deadline = Date.now() + NAVIGATION_SETTLE_CAP_MS;
+    let lastUrl = page.url();
+    let stableSince = Date.now();
+    while (Date.now() < deadline) {
+        await page.waitForTimeout(100).catch(() => undefined);
+        if (page.isClosed())
+            return;
+        const current = page.url();
+        if (current !== lastUrl) {
+            lastUrl = current;
+            stableSince = Date.now();
+            continue;
+        }
+        if (Date.now() - stableSince >= NAVIGATION_SETTLE_WINDOW_MS)
+            return;
+    }
+}
 async function findSearchInput(page) {
     for (const selector of SEARCH_INPUT_SELECTORS) {
         const locator = page.locator(selector).first();
@@ -475,13 +882,20 @@ async function findSearchInput(page) {
     }
     return undefined;
 }
-async function submitSearchForm(page, input) {
-    for (const selector of SEARCH_SUBMIT_SELECTORS) {
-        const locator = page.locator(selector).first();
-        if (!await locator.isVisible().catch(() => false))
-            continue;
-        await locator.click({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
-        return;
+async function submitSearchForm(input) {
+    // Prefer a submit control INSIDE the input's owning form. A page-level
+    // `button:not([type])` fallback can click an unrelated chrome button (for
+    // example a headful search engine renders extra visible buttons), which
+    // looks like a submit but never navigates.
+    const form = input.locator("xpath=ancestor-or-self::form[1]");
+    if (await form.count().catch(() => 0) > 0) {
+        for (const selector of SEARCH_SUBMIT_SELECTORS) {
+            const locator = form.locator(selector).first();
+            if (!await locator.isVisible().catch(() => false))
+                continue;
+            await locator.click({ timeout: DEFAULT_ACTION_TIMEOUT_MS });
+            return;
+        }
     }
     await input.press("Enter", { timeout: DEFAULT_ACTION_TIMEOUT_MS });
 }