@te-river/opencode-team-mode 1.5.10 → 1.5.12

package/dist/tm/browser.js

@@ -1,36 +1,71 @@
 /**
  * tm_browser — governed interactive browser (Plan C: the user's own
- * Chromium-family browser driven headful over the CDP pipe protocol).
+ * Chromium-family browser, headful by default on desktops).
  *
- * Feasibility proven by smoke (Edge + --remote-debugging-pipe + JSON/NUL
- * framing over fds 3/4 — zero deps, no WebSocket implementation).  Qoder's
- * hardening ideas are ported where the plugin can reach them:
- *   - isolated temp user-data-dir (never the user's real profile);
- *   - per-navigation allowlist enforced at the NETWORK layer via CDP
- *     Fetch.requestPaused (non-allowlisted hosts get BlockedByClient —
- *     the per-hop re-check analog);
- *   - hardened webPreferences are the spawn's own flags (no-first-run,
- *     no-extensions, mute);
- *   - hard per-command timeout + explicit close; dispose kills the child.
+ * T5 engine split (design board ② "TM_BROWSER_ENGINE" + R2 verdict):
+ *   - PRIMARY engine: playwright-core — dynamic import ONLY (the package is
+ *     declared in dependencies but NOT installed at build time; a static
+ *     import would break tsc).  A failed import or node < 20 degrades the
+ *     session to the cdp-legacy engine automatically, per plugin instance.
+ *   - cdp-legacy engine: the original hand-rolled CDP pipe transport
+ *     (JSON + NUL framing over fds 3/4, zero deps — smoke-proven) kept
+ *     verbatim as the fallback.  On cdp-legacy only the core subset works
+ *     (open/navigate/read/screenshot/close + navigate_page/take_screenshot/
+ *     list_pages/evaluate_script aliases); the snapshot-first actions
+ *     (take_snapshot + uid addressing, 16-verb chrome-devtools-mcp surface)
+ *     require the playwright engine.
+ *
+ * Action surface aligns with chrome-devtools-mcp's 16 verbs (R2 mapping):
+ *   navigate_page · take_snapshot · click · fill · hover · drag ·
+ *   press_key · select_page · upload_file · wait_for · evaluate_script ·
+ *   list_console_messages · list_network_requests · list_pages ·
+ *   take_screenshot · handle_dialog
+ * plus the legacy compatibility verbs open / navigate / read /
+ * screenshot / close.  Snapshot-first discipline: take_snapshot returns
+ * the ariaSnapshot YAML with an INJECTED [uid=eN] per node (playwright has
+ * no uid concept — SnapshotIndex below is our own snapshot→locator
+ * registry); follow-up actions address nodes by that uid (or an explicit
+ * selector escape hatch) instead of guessed locators.
+ *
+ * Hardening (unchanged from the CDP era, ported to both engines):
+ *   - isolated temp profile (never the user's real browser profile);
+ *     persistent login is ONLY via an explicit TM_BROWSER_USER_DATA_DIR;
+ *   - domain allowlist enforced at the NETWORK layer: playwright
+ *     context.route() abort / CDP Fetch.requestPaused fail — every request
+ *     and every redirect hop re-checked (per-hop analog);
+ *   - out-of-allowlist open/navigate routes through the OFFICIAL dialog
+ *     BEFORE any spawn; approved hosts also pass the network layer;
+ *   - hardened context: real-Chrome UA + zh-CN Accept-Language,
+ *     no-first-run / no-extensions / mute launch flags, 3 s default action
+ *     timeout (the prompt's "3000 ms budget" is the tool's default, not an
+ *     aspiration), no networkidle waits anywhere;
+ *   - dispose kills the child / closes the browser.
  *
  * Environment adaptivity (different OpenCode hosts):
  *   - headful by default (Plan C); display-less Linux (no DISPLAY/
  *     WAYLAND_DISPLAY) automatically falls back to headless; TM_BROWSER_
  *     HEADLESS=1|0 forces either way;
- *   - browser discovery: TM_BROWSER_PATH override, then per-OS candidate
- *     paths (Edge first on Windows — it is always there; Chrome/Chromium
- *     elsewhere).  No browser → structured error, the agent falls back to
- *     tm_webfetch / user MCP tools per the priority ladder.
+ *   - browser discovery (SHARED by both engines): TM_BROWSER_PATH
+ *     override, then the USER'S DEFAULT browser (Windows registry / Linux
+ *     xdg-settings) when it is Chromium-family — CDP is Chromium-proprietary
+ *     and playwright channels only speak Chromium too, so a Firefox default
+ *     falls through — then per-OS candidate paths (Edge first on Windows;
+ *     Chrome/Chromium elsewhere).  No browser → structured error, the agent
+ *     falls back to tm_webfetch / user MCP tools.
  *
- * Role access mirrors tm_webfetch: network roles (team + researcher) only.
+ * Role access mirrors tm_webfetch: network roles (team + researcher) only,
+ * tester browser-only (UI verification).
  */
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { checkWebUrl } from "./webfetch.js";
+import { checkWebUrl, seedWebfetchDomains } from "./webfetch.js";
 import { askUserForTarget } from "./perm-ask.js";
+import { assertReadablePath } from "./guard.js";
+import { isEnvFilePath } from "../envprotect.js";
 import { tmError, toToolResult } from "./result.js";
+import { estimateTokens } from "./config.js";
 import { rmForceSafe } from "../fs-safe.js";
 /** Per-OS browser candidates, in preference order (first hit wins). */
 const BROWSER_CANDIDATES = {
@@ -54,8 +89,77 @@ const BROWSER_CANDIDATES = {
         "/snap/bin/chromium",
     ],
 };
-/** Resolve the browser executable: TM_BROWSER_PATH override, then per-OS
- *  candidates.  %LOCALAPPDATA% style vars are expanded on win32. */
+const defaultRunner = (cmd, args) => String(execFileSync(cmd, args, { encoding: "utf8", timeout: 3000, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }));
+/** Chromium-family binaries only — --remote-debugging-pipe is a Chromium
+ *  protocol; Firefox/WebKit as the default browser cannot drive tm_browser. */
+const CHROMIUM_FAMILY_RE = /(?:^|[\\/])(?:chrome|msedge|brave|vivaldi|chromium|chromium-browser|opera|yandex)(?:\.exe)?$/i;
+export function isChromiumFamily(exePath) {
+    return CHROMIUM_FAMILY_RE.test(String(exePath ?? "").trim());
+}
+/** Parse `reg query "...UrlAssociations\http\UserChoice" /v ProgId` output. */
+export function parseProgId(stdout) {
+    const m = /ProgId\s+REG_SZ\s+(\S+)/i.exec(String(stdout ?? ""));
+    return m ? m[1] : null;
+}
+/** Parse `reg query "...\shell\open\command" /ve` output → exe path.
+ *  The quoted capture stops at the closing quote, so the `" -- %1"` style
+ *  URL-template tail never leaks into the returned path. */
+export function parseRegCommand(stdout) {
+    const m = /REG_SZ\s+(?:"([^"]+)"|(\S+))/i.exec(String(stdout ?? ""));
+    return m ? (m[1] ?? m[2]) : null;
+}
+/** Parse the Exec= line of an xdg .desktop file. */
+export function parseDesktopExec(text) {
+    const m = /^Exec\s*=\s*(?:"([^"]+)"|(\S+))/m.exec(String(text ?? ""));
+    return m ? (m[1] ?? m[2]) : null;
+}
+/** The user's DEFAULT browser, when it is Chromium-family and present.
+ *  null → the caller falls back to the per-OS probe list (detection is
+ *  best-effort and must never throw into tool discovery). */
+export function defaultBrowserExecutable(env = process.env, run = defaultRunner) {
+    try {
+        if (process.platform === "win32") {
+            const choice = run("reg", [
+                "query",
+                "HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\http\\UserChoice",
+                "/v",
+                "ProgId",
+            ]);
+            const progId = parseProgId(choice);
+            if (!progId)
+                return null;
+            const cmd = run("reg", ["query", `HKCU\\Software\\Classes\\${progId}\\shell\\open\\command`, "/ve"]);
+            const exe = parseRegCommand(cmd);
+            return exe && isChromiumFamily(exe) && fs.existsSync(exe) ? exe : null;
+        }
+        if (process.platform === "linux") {
+            const desk = run("xdg-settings", ["get", "default-web-browser"]).trim();
+            if (!desk)
+                return null;
+            const name = desk.endsWith(".desktop") ? desk : desk + ".desktop";
+            const dirs = [
+                "/usr/share/applications",
+                "/usr/local/share/applications",
+                path.join(String(env.HOME ?? ""), ".local/share/applications"),
+            ];
+            for (const dir of dirs) {
+                const f = path.join(dir, name);
+                if (!fs.existsSync(f))
+                    continue;
+                const exe = parseDesktopExec(fs.readFileSync(f, "utf8"));
+                if (exe && isChromiumFamily(exe) && fs.existsSync(exe))
+                    return exe;
+            }
+        }
+    }
+    catch {
+        /* best-effort — the probe list takes over */
+    }
+    return null;
+}
+/** Resolve the browser executable: TM_BROWSER_PATH override → the user's
+ *  DEFAULT browser (Chromium-family only) → per-OS candidate paths.
+ *  %LOCALAPPDATA% style vars are expanded on win32. */
 export function findBrowserExecutable(env = process.env) {
     const override = String(env.TM_BROWSER_PATH ?? "").trim();
     const tryPath = (p) => {
@@ -69,6 +173,9 @@ export function findBrowserExecutable(env = process.env) {
     };
     if (override)
         return tryPath(override);
+    const def = defaultBrowserExecutable(env);
+    if (def)
+        return def;
     for (const c of BROWSER_CANDIDATES[process.platform] ?? []) {
         const hit = tryPath(c);
         if (hit)
@@ -99,7 +206,7 @@ class PipeCdp {
     pending = new Map();
     buf = Buffer.alloc(0);
     events = [];
-    onEvent = (handler) => this.eventHandler = handler;
+    onEvent = (handler) => (this.eventHandler = handler);
     eventHandler = () => { };
     constructor(child) {
         this.child = child;
@@ -158,28 +265,262 @@ class PipeCdp {
         }
     }
 }
+/** playwright-core 1.63 targets node >= 20; on anything older we refuse the
+ *  engine up-front and stay on the zero-dependency CDP pipe (the node>=18
+ *  package floor keeps the plugin itself loadable — only the playwright
+ *  PRIMARY is gated here, cdp-legacy carries node 18/19 hosts). */
+export const PLAYWRIGHT_MIN_NODE_MAJOR = 20;
+/** "v22.3.1" / "20" -> major number; unparseable -> 0 (fail toward the
+ *  always-available cdp-legacy engine). */
+export function nodeMajorOf(version) {
+    const m = /^v?(\d+)/.exec(String(version ?? "").trim());
+    return m ? Number(m[1]) : 0;
+}
+/** The REAL loader — a VARIABLE specifier so tsc never tries to resolve
+ *  "playwright-core" at build time (types ship inside the package, which may
+ *  be absent from node_modules).  Under ESM, import(variable) yields the
+ *  module namespace typed as any. */
+export async function defaultImportPlaywright() {
+    const specifier = "playwright-core";
+    return await import(specifier);
+}
+/** Pure engine-selection seam (exported for test-browser.mjs):
+ *  cdp-legacy preference → legacy WITHOUT ever importing; node < 20 →
+ *  legacy without importing; playwright preference → import, verify the
+ *  chromium.launch shape, degrade to legacy on ANY failure. */
+export async function selectBrowserEngine(opts) {
+    const preference = opts.preference === "cdp-legacy" ? "cdp-legacy" : "playwright";
+    if (preference === "cdp-legacy") {
+        return { kind: "cdp-legacy", reason: "TM_BROWSER_ENGINE=cdp-legacy 偏好" };
+    }
+    if (opts.nodeMajor < PLAYWRIGHT_MIN_NODE_MAJOR) {
+        return {
+            kind: "cdp-legacy",
+            reason: `node ${opts.nodeMajor || "?"} < ${PLAYWRIGHT_MIN_NODE_MAJOR} — playwright-core 不受支持，自动降级 cdp-legacy`,
+        };
+    }
+    try {
+        const mod = (await opts.importPlaywright());
+        if (!mod || typeof mod.chromium?.launch !== "function") {
+            throw new Error("playwright-core 模块形状异常（缺 chromium.launch）");
+        }
+        return { kind: "playwright", pw: mod };
+    }
+    catch (e) {
+        return {
+            kind: "cdp-legacy",
+            reason: `playwright-core 加载失败：${e?.message ?? String(e)} — 自动降级 cdp-legacy（快照类动作不可用）`,
+        };
+    }
+}
+/** ariaSnapshot yields plain YAML with NO addressable id, while the
+ *  chrome-devtools-mcp muscle memory this tool aligns to is uid-addressed.
+ *  The missing layer is built here: each take_snapshot re-indexes every YAML
+ *  node (`- <role> "<name>" …`), injects `[uid=eN]` inline, and remembers
+ *  (role, name, nth-of-kind); later actions resolve uid →
+ *  `page.getByRole(role, { name, exact: true }).nth(nth)`.  Uids are
+ *  renumbered on every snapshot (one action, one observation); an
+ *  unknown/stale uid errors back to take_snapshot instead of falling back
+ *  to guessed locators. */
+export class SnapshotIndex {
+    entries = new Map();
+    next = 0;
+    get size() {
+        return this.entries.size;
+    }
+    /** Reset + parse + annotate the ariaSnapshot YAML in one pass. */
+    annotate(yaml) {
+        this.entries.clear();
+        this.next = 0;
+        const counters = new Map();
+        const out = [];
+        for (const line of String(yaml ?? "").split(/\r?\n/)) {
+            // `- role`, `- role "name"`, `- role:`, `- role "name" [attrs]` …
+            // the `text` pseudo-role carries no interactive semantics: skip it.
+            const m = /^(\s*-\s+)([A-Za-z][\w-]*)((?:"[^"]*"|.)*?)$/.exec(line);
+            if (!m || m[2] === "text") {
+                out.push(line);
+                continue;
+            }
+            const role = m[2];
+            const rest = m[3];
+            const uid = `e${++this.next}`;
+            const rawName = /"((?:[^"\\]|\\.)*)"/.exec(rest)?.[1];
+            const name = rawName === undefined ? undefined : unescapeAriaName(rawName);
+            const key = `${role}\u0000${name ?? ""}`;
+            const nth = counters.get(key) ?? 0;
+            counters.set(key, nth + 1);
+            this.entries.set(uid, { role, name, nth });
+            // container lines (`- list:`) get the uid BEFORE the colon so the
+            // YAML `key:` child-anchor semantics stay intact; names may contain
+            // colons, hence the startsWith check instead of a split.
+            out.push(rest.startsWith(":") ? `${m[1]}${role} [uid=${uid}]${rest}` : `${line} [uid=${uid}]`);
+        }
+        return out.join("\n");
+    }
+    get(uid) {
+        return this.entries.get(String(uid ?? "").trim());
+    }
+    /** uid → playwright locator; null = unknown uid / role the engine cannot
+     *  address (the caller renders the take_snapshot-first guidance). */
+    locatorFor(page, uid) {
+        const entry = this.get(uid);
+        if (!entry)
+            return null;
+        try {
+            const base = entry.name !== undefined ? page.getByRole(entry.role, { name: entry.name, exact: true }) : page.getByRole(entry.role);
+            return base.nth(entry.nth);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** ariaSnapshot escapes whitespace/quotes inside names (\s \n \t \" \\). */
+export function unescapeAriaName(raw) {
+    return String(raw).replace(/\\(.)/g, (_, c) => (c === "s" ? " " : c === "n" ? "\n" : c === "t" ? "\t" : c));
+}
+// ---------- action surface (R2: chrome-devtools-mcp 16-verb alignment) --------
+/** The 16 canonical verbs, named byte-identical to chrome-devtools-mcp. */
+export const BROWSER_PLAYWRIGHT_ACTIONS = [
+    "navigate_page",
+    "take_snapshot",
+    "click",
+    "fill",
+    "hover",
+    "drag",
+    "press_key",
+    "select_page",
+    "upload_file",
+    "wait_for",
+    "evaluate_script",
+    "list_console_messages",
+    "list_network_requests",
+    "list_pages",
+    "take_screenshot",
+    "handle_dialog",
+];
+/** Legacy compat verbs that ride on top of the 16 (both engines). */
+export const BROWSER_COMPAT_ACTIONS = ["open", "navigate", "read", "screenshot", "close"];
+/** What the cdp-legacy fallback can still do (R2: degradation must keep the
+ *  §6o behavior; everything snapshot-shaped is playwright-only). */
+export const BROWSER_LEGACY_ACTIONS = [
+    "open",
+    "navigate",
+    "navigate_page",
+    "read",
+    "screenshot",
+    "take_screenshot",
+    "list_pages",
+    "evaluate_script",
+    "close",
+];
+/** Default action/wait budget — the prompt's "3000 ms" discipline is the
+ *  ENGINE default, so agents that forget a timeout still fail fast. */
+const PW_DEFAULT_TIMEOUT_MS = 3000;
+const OBSERVE_BUFFER_CAP = 200;
+const HARDENED_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
 const SPAWN_TIMEOUT_MS = 15_000;
 const NAVIGATE_EVENT_TIMEOUT_MS = 15_000;
-// ---------- tool ----------------------------------------------------------------
 export function buildTmBrowserTool(deps) {
     const { pipelines } = deps;
     const env = deps.env ?? process.env;
     const tool = "tm_browser";
     const traj = (e) => pipelines.store.appendTrajectory({ tool, ...e });
     let session = null;
-    const allowlist = deps.cfg.webfetchAllowedDomains
-        ?? ["*"];
+    // m2 (fix round): SAME seed policy as tm_webfetch / tm_search — the
+    // built-in default list gains the T4 engine home hosts (api.stackexchange
+    // .com, hn.algolia.com) so jump-reading a search hit stops re-popping the
+    // dialog; a narrowed TM_WEBFETCH_ALLOWED_DOMAINS is never widened.
+    const allowlist = seedWebfetchDomains(deps.cfg.webfetchAllowedDomains ?? ["*"]);
     // hosts approved through the OFFICIAL dialog this plugin lifetime — the
-    // CDP network-layer block consults this in addition to the static allowlist
+    // network layer (both engines) consults this in addition to the static allowlist
     const approvedHosts = new Set();
-    async function ensureSession(headless) {
-        if (session)
-            return session;
-        const executable = findBrowserExecutable(env);
-        if (!executable) {
-            throw new Error("本机未找到可用的浏览器（按 Edge/Chrome/Chromium 顺序探测失败）。" +
-                "设置 TM_BROWSER_PATH 指向浏览器可执行文件，或改用 tm_webfetch / 用户 MCP 工具。");
+    const snapshotBudget = Math.max(10, Number(deps.cfg?.browserSnapshotMaxTokens) || 1200);
+    // ---------- engine selection (cached per plugin instance) ----------
+    let selPromise = null;
+    let lastSel = null;
+    const preference = String(deps.cfg?.browserEngine ?? "playwright");
+    const selection = () => {
+        if (!selPromise) {
+            selPromise = selectBrowserEngine({
+                preference,
+                nodeMajor: deps.nodeMajor ?? nodeMajorOf(process.versions.node),
+                importPlaywright: deps.importPlaywright ?? defaultImportPlaywright,
+            }).then((sel) => {
+                lastSel = sel;
+                traj({ step_id: "browser", event: "engine", kind: sel.kind, reason: (sel.reason ?? "").slice(0, 200) });
+                return sel;
+            });
+        }
+        return selPromise;
+    };
+    /** Observe-payload cap shared by snapshot / console / network / eval. */
+    function capTokens(text, note) {
+        if (estimateTokens(text) <= snapshotBudget)
+            return text;
+        const lines = text.split("\n");
+        let acc = 0;
+        let i = 0;
+        for (; i < lines.length; i++) {
+            const cost = estimateTokens(lines[i]) + 1;
+            if (acc + cost > snapshotBudget)
+                break;
+            acc += cost;
+        }
+        return `${lines.slice(0, i).join("\n")}\n${note}`;
+    }
+    function saveShotPng(bytes, stepId) {
+        const png = Buffer.from(bytes);
+        const dir = path.join(pipelines.store.stepsRoot(), stepId);
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, "screenshot.png");
+        fs.writeFileSync(file, png);
+        traj({ step_id: stepId, event: "result", bytes: png.length });
+        return { file, png };
+    }
+    function shotOutput(file, bytes) {
+        return `截图已保存（${bytes} bytes）：${file}\n（PNG 已落 run store；上下文只携带路径，不携带像素。）`;
+    }
+    function pageTextOutput(url, text) {
+        return `页面文本（${url}）：\n${text.slice(0, 20000)}${text.length > 20000 ? "\n…(截断)" : ""}`;
+    }
+    function discoveryError() {
+        return new Error("本机未找到可用的浏览器（按 Edge/Chrome/Chromium 顺序探测失败）。" +
+            "设置 TM_BROWSER_PATH 指向浏览器可执行文件，或改用 tm_webfetch / 用户 MCP 工具。");
+    }
+    /**
+     * M1 (upload_file exfil): the domain allowlist constrains the network
+     * DESTINATION but never the local SOURCE — an unguarded filePath could
+     * upload .env / key files to a whitelisted host's form. Reuses the read
+     * pipeline's P2 containment verbatim (workspace root + blackboard +
+     * trajectory; realpath-verified, fail-closed on unresolvable paths) and
+     * then applies the R6 env-file classifier, so *.env / shell-rc files are
+     * refused INSIDE the root too. The env refusal echoes no path (R6 privacy
+     * line); the scope verdict keeps the tm_read/tm_grep message shape.
+     */
+    function uploadExfilGuard(args, ctx) {
+        const raw = (args.filePath ?? args.files);
+        const files = (Array.isArray(raw) ? raw : [raw]).map((f) => String(f ?? "").trim()).filter(Boolean);
+        if (!files.length)
+            return null; // "缺少 filePath" stays act()'s own args error
+        const d = ctx?.directory;
+        const root = typeof d === "string" && d ? d : process.cwd();
+        const extra = [pipelines.store.blackboardRoot, pipelines.store.trajectoryRoot].filter((p) => typeof p === "string" && p.length > 0);
+        for (const f of files) {
+            if (isEnvFilePath(f))
+                return "拒绝上传（R6 红线：.env / shell rc 家族文件永不离开本机）";
+            const scope = assertReadablePath(root, f, extra);
+            if (!scope.ok)
+                return scope.message;
         }
+        return null;
+    }
+    // ================= cdp-legacy engine (原手写 CDP 管道，保留不删) =============
+    async function openLegacySession(headless) {
+        const executable = findBrowserExecutable(env);
+        if (!executable)
+            throw discoveryError();
         const profileDir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-browser-"));
         const child = spawn(executable, [
             headless ? "--headless=new" : "--start-maximized",
@@ -187,7 +528,7 @@ export function buildTmBrowserTool(deps) {
             `--user-data-dir=${profileDir}`,
             // real-Chrome UA even under --headless=new (which some sites detect
             // via the "HeadlessChrome" token otherwise) + zh-CN Accept-Language
-            "--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+            `--user-agent=${HARDENED_UA}`,
             "--accept-lang=zh-CN,zh;q=0.9,en;q=0.8",
             "--no-first-run", "--no-default-browser-check", "--disable-extensions",
             "--disable-background-networking", "--mute-audio",
@@ -214,7 +555,7 @@ export function buildTmBrowserTool(deps) {
         const page = targets.targetInfos.find((t) => t.type === "page");
         if (!page)
             throw new Error("浏览器启动后未找到 page target");
-        const { sessionId } = await cdp.call("Target.attachToTarget", { targetId: page.targetId, flatten: true });
+        const { sessionId } = (await cdp.call("Target.attachToTarget", { targetId: page.targetId, flatten: true }));
         await cdp.call("Page.enable", {}, sessionId);
         // network-layer allowlist enforcement (Qoder's per-hop re-check analog)
         await cdp.call("Fetch.enable", { patterns: [{ urlPattern: "*" }] }, sessionId);
@@ -242,8 +583,78 @@ export function buildTmBrowserTool(deps) {
                 void cdp.call("Fetch.failRequest", { requestId, errorReason: "BlockedByClient" }, sessionId, 5000).catch(() => { });
             }
         });
-        child.on("exit", () => {
-            session = null;
+        const sess = {
+            kind: "cdp-legacy",
+            currentUrl: "about:blank",
+            async act(action, args, stepId) {
+                if (action === "navigate" || action === "navigate_page") {
+                    const url = String(args.url ?? "").trim();
+                    await cdp.call("Page.navigate", { url }, sessionId);
+                    await cdp.waitEvent("Page.loadEventFired", sessionId, NAVIGATE_EVENT_TIMEOUT_MS).catch(() => { });
+                    sess.currentUrl = url;
+                    return `已导航：${url}`;
+                }
+                if (action === "read") {
+                    traj({ step_id: stepId, event: "call", url: sess.currentUrl.slice(0, 200) });
+                    const ev = await cdp.call("Runtime.evaluate", { expression: "document.body ? document.body.innerText : ''", returnByValue: true }, sessionId);
+                    const text = String(ev.result?.value ?? "");
+                    traj({ step_id: stepId, event: "result", tokens: Math.ceil(text.length / 4) });
+                    return pageTextOutput(sess.currentUrl, text);
+                }
+                if (action === "screenshot" || action === "take_screenshot") {
+                    traj({ step_id: stepId, event: "call", kind: "screenshot", url: sess.currentUrl.slice(0, 200) });
+                    const shot = await cdp.call("Page.captureScreenshot", { format: "png" }, sessionId);
+                    const png = Buffer.from(String(shot.data ?? ""), "base64");
+                    const { file } = saveShotPng(new Uint8Array(png), stepId);
+                    return shotOutput(file, png.length);
+                }
+                if (action === "list_pages") {
+                    const t = await cdp.call("Target.getTargets");
+                    const pages = t.targetInfos.filter((x) => x.type === "page");
+                    const lines = pages.map((p, i) => `${i}: ${String(p.url ?? "")} ${String(p.title ?? "")}`.trimEnd());
+                    return `标签页（${pages.length}）：\n${lines.join("\n") || "（无）"}`;
+                }
+                if (action === "evaluate_script") {
+                    const src = String(args.function ?? args.expression ?? "").trim();
+                    if (!src)
+                        throw new Error('缺少 expression/function 参数（evaluate_script 需要一个 JS 表达式）');
+                    traj({ step_id: stepId, event: "call", kind: "evaluate" });
+                    const ev = await cdp.call("Runtime.evaluate", { expression: src, returnByValue: true }, sessionId);
+                    const value = ev.result?.value;
+                    return capTokens(`执行结果：${JSON.stringify(value ?? null)}`, "…(结果超长已截断)");
+                }
+                throw new Error(`action "${action}" 需要 playwright 引擎（当前为 cdp-legacy 降级：playwright-core 未安装或 node<20）。` +
+                    `cdp-legacy 可用: ${BROWSER_LEGACY_ACTIONS.filter((a) => a !== "open" && a !== "close").join(" | ")}`);
+            },
+            async close() {
+                child.off?.("exit", onExit);
+                await cdp.call("Browser.close", {}, undefined, 3000).catch(() => { });
+                if (child.exitCode === null) {
+                    child.kill();
+                }
+                // wait briefly for the process to release the profile (Windows file
+                // locks linger while the browser is still shutting down)
+                await new Promise((res) => {
+                    if (child.exitCode !== null)
+                        return res();
+                    const t = setTimeout(res, 3000);
+                    child.once("exit", () => {
+                        clearTimeout(t);
+                        res();
+                    });
+                });
+                try {
+                    rmForceSafe(profileDir, { recursive: true });
+                }
+                catch {
+                    /* a locked leftover temp dir is reclaimed by the OS — never fail close */
+                }
+                return "浏览器会话已关闭，临时配置目录已清理。";
+            },
+        };
+        const onExit = () => {
+            if (session === sess)
+                session = null;
             // best-effort: the profile may still be file-locked during shutdown —
             // a leftover temp dir is reclaimed by the OS, never an error for the task
             try {
@@ -252,38 +663,359 @@ export function buildTmBrowserTool(deps) {
             catch {
                 /* ignore */
             }
-        });
-        session = { child, cdp, sessionId, profileDir, currentUrl: "about:blank" };
-        return session;
+        };
+        child.on("exit", onExit);
+        return sess;
     }
-    async function closeSession() {
-        if (!session)
-            return "没有打开的浏览器会话。";
-        const { child, cdp, profileDir } = session;
-        session = null;
-        await cdp.call("Browser.close", {}, undefined, 3000).catch(() => { });
-        if (child.exitCode === null) {
-            child.kill();
+    // ================= playwright engine (primary) ==============================
+    async function openPlaywrightSession(pw, headless) {
+        const executable = findBrowserExecutable(env);
+        if (!executable)
+            throw discoveryError();
+        const launchArgs = [
+            "--no-first-run", "--no-default-browser-check", "--disable-extensions",
+            "--disable-background-networking", "--mute-audio",
+            ...(headless ? [] : ["--start-maximized"]),
+        ];
+        const contextOpts = {
+            userAgent: HARDENED_UA,
+            locale: "zh-CN",
+            extraHTTPHeaders: { "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8" },
+            // the 3000 ms observation budget is the engine default (see header)
+            timeout: PW_DEFAULT_TIMEOUT_MS,
+            // headful: honor --start-maximized (null viewport = the OS window size)
+            viewport: headless ? undefined : null,
+        };
+        const persistentDir = String(env.TM_BROWSER_USER_DATA_DIR ?? "").trim();
+        // R2: channel launches are cross-version-fragile (official warning), so
+        // they are a SMOKE-ONLY attempt; any failure retries with the explicit
+        // executablePath from our own discovery layer.
+        const channel = /msedge/i.test(executable) ? "msedge" : /chrome/i.test(executable) ? "chrome" : undefined;
+        let browser = null;
+        let context;
+        let via = "executablePath";
+        if (persistentDir) {
+            context = await pw.chromium.launchPersistentContext(persistentDir, {
+                ...contextOpts,
+                ...(channel ? { channel } : { executablePath: executable }),
+                headless,
+                args: launchArgs,
+            });
+            via = `persistent(${channel ?? "executablePath"})`;
         }
-        // wait briefly for the process to release the profile (Windows file
-        // locks linger while the browser is still shutting down)
-        await new Promise((res) => {
-            if (child.exitCode !== null)
-                return res();
-            const t = setTimeout(res, 3000);
-            child.once("exit", () => {
-                clearTimeout(t);
-                res();
+        else {
+            try {
+                browser = await pw.chromium.launch({ ...(channel ? { channel } : { executablePath: executable }), headless, args: launchArgs });
+                via = channel ? `channel(${channel})` : "executablePath";
+            }
+            catch (e1) {
+                if (!channel)
+                    throw e1;
+                browser = await pw.chromium.launch({ executablePath: executable, headless, args: launchArgs });
+                via = "executablePath(channel 回退)";
+            }
+            context = await browser.newContext(contextOpts);
+        }
+        const snapIndex = new SnapshotIndex();
+        const state = {
+            page: context.pages()[0] ?? (await context.newPage()),
+            dialogs: [],
+            consoleBuf: [],
+            netBuf: [],
+        };
+        const attached = new WeakSet();
+        const attach = (p) => {
+            if (attached.has(p))
+                return; // select_page may bounce back to an already-hooked tab
+            attached.add(p);
+            p.on("console", (msg) => {
+                state.consoleBuf.push({ type: String(msg?.type?.() ?? "log"), text: String(msg?.text?.() ?? "") });
+                if (state.consoleBuf.length > OBSERVE_BUFFER_CAP)
+                    state.consoleBuf.shift();
             });
-        });
+            p.on("pageerror", (err) => {
+                state.consoleBuf.push({ type: "pageerror", text: String(err?.message ?? err) });
+                if (state.consoleBuf.length > OBSERVE_BUFFER_CAP)
+                    state.consoleBuf.shift();
+            });
+            p.on("request", (req) => {
+                state.netBuf.push({ method: req?.method?.() ?? "?", url: String(req?.url?.() ?? "").slice(0, 300) });
+                if (state.netBuf.length > OBSERVE_BUFFER_CAP)
+                    state.netBuf.shift();
+            });
+            p.on("response", (res) => {
+                state.netBuf.push({
+                    method: res?.request?.()?.method?.() ?? "?",
+                    url: String(res?.url?.() ?? "").slice(0, 300),
+                    status: Number(res?.status?.() ?? 0) || undefined,
+                });
+                if (state.netBuf.length > OBSERVE_BUFFER_CAP)
+                    state.netBuf.shift();
+            });
+            p.on("requestfailed", (req) => {
+                state.netBuf.push({ method: req?.method?.() ?? "?", url: String(req?.url?.() ?? "").slice(0, 300), failure: "requestfailed" });
+                if (state.netBuf.length > OBSERVE_BUFFER_CAP)
+                    state.netBuf.shift();
+            });
+            // dialogs are HELD for handle_dialog (registering the handler opts us
+            // out of playwright's implicit auto-dismiss)
+            p.on("dialog", (d) => {
+                state.dialogs.push(d);
+                if (state.dialogs.length > 8)
+                    state.dialogs.shift();
+            });
+        };
+        attach(state.page);
+        // ---- network-layer allowlist: context.route() (CDP Fetch 的迁移面) ----
+        const routeHandler = async (route, request) => {
+            const u = String(request.url?.() ?? "");
+            // data:/blob:/about: never reach playwright's route anyway; keep the
+            // non-http hard-reject semantics identical to the CDP-era behavior
+            if (/^(about|data|blob):/i.test(u)) {
+                await route.continue().catch(() => { });
+                return;
+            }
+            const verdict = checkWebUrl(u, allowlist);
+            let pass = verdict.ok;
+            if (!pass) {
+                try {
+                    pass = approvedHosts.has(new URL(u).hostname);
+                }
+                catch {
+                    pass = false;
+                }
+            }
+            if (pass) {
+                await route.continue().catch(() => { });
+            }
+            else {
+                // per-hop re-check lands here for every redirect hop too
+                traj({ step_id: "browser", event: "blocked", url: u.slice(0, 200) });
+                state.netBuf.push({ method: request.method?.() ?? "?", url: u.slice(0, 300), blocked: true });
+                await route.abort().catch(() => { });
+            }
+        };
+        // M2 (fix round) fail-closed: the route gate is playwright's analog of
+        // the CDP leg's AWAITED Fetch.enable — if registration fails the session
+        // would browse with NO network whitelist. Close the context (persistent:
+        // the only handle; launched: plus the browser) and surface an execute
+        // error; a swallowed .catch(()=>{}) was a fail-open hole.
         try {
-            rmForceSafe(profileDir, { recursive: true });
+            await Promise.resolve(context.route("**/*", routeHandler));
         }
-        catch {
-            /* a locked leftover temp dir is reclaimed by the OS — never fail close */
+        catch (e) {
+            await Promise.resolve(context.close()).catch(() => { });
+            if (browser)
+                await Promise.resolve(browser.close()).catch(() => { });
+            traj({ step_id: "browser", event: "gate_register_failed", reason: String(e?.message ?? e).slice(0, 200) });
+            throw new Error(`网络白名单闸注册失败（context.route）——已 fail-closed 关闭浏览器会话，不会留下无白名单的窗口。` +
+                `原因：${String(e?.message ?? e)}`);
         }
-        return "浏览器会话已关闭，临时配置目录已清理。";
+        /** uid → locator with the snapshot-first guidance errors (R2: 禁猜
+         *  locator — only uid addressing or an explicit selector escape). */
+        const targetOf = (uidKey, selKey, args) => {
+            const uid = String(args[uidKey] ?? "").trim();
+            if (uid) {
+                const loc = snapIndex.locatorFor(state.page, uid);
+                if (!loc) {
+                    throw new Error(`uid "${uid}" 不在当前快照中（快照会重新编号）——先 action:"take_snapshot" 再用返回的 [uid=...] 寻址`);
+                }
+                return loc;
+            }
+            const sel = String(args[selKey] ?? "").trim();
+            if (sel)
+                return state.page.locator(sel);
+            throw new Error(`缺少 ${uidKey}/selector——tm_browser 快照优先：先 action:"take_snapshot"，动作只按快照里的 [uid=...] 寻址（或显式 selector 逃生舱），禁止猜 locator`);
+        };
+        /** Human-readable addressing echo for action results (no full locators
+         *  into context — uid tokens only). */
+        const describeTarget = (args, uidKey = "uid") => {
+            const uid = String(args[uidKey] ?? "").trim();
+            if (uid)
+                return `uid "${uid}"`;
+            const sel = String(args[uidKey === "uid" ? "selector" : "targetSelector"] ?? "").trim();
+            return sel ? `selector "${sel.slice(0, 60)}"` : "目标";
+        };
+        const sess = {
+            kind: "playwright",
+            currentUrl: "about:blank",
+            async act(action, args, stepId) {
+                if (action === "navigate" || action === "navigate_page") {
+                    const url = String(args.url ?? "").trim();
+                    // domcontentloaded ONLY — networkidle is banned (prompt discipline)
+                    await state.page.goto(url, { waitUntil: "domcontentloaded", timeout: 20_000 });
+                    sess.currentUrl = state.page.url?.() || url;
+                    return `已导航：${url}`;
+                }
+                if (action === "read") {
+                    traj({ step_id: stepId, event: "call", url: sess.currentUrl.slice(0, 200) });
+                    const text = String((await state.page.evaluate("document.body ? document.body.innerText : ''")) ?? "");
+                    traj({ step_id: stepId, event: "result", tokens: Math.ceil(text.length / 4) });
+                    return pageTextOutput(sess.currentUrl, text);
+                }
+                if (action === "screenshot" || action === "take_screenshot") {
+                    traj({ step_id: stepId, event: "call", kind: "screenshot", url: sess.currentUrl.slice(0, 200) });
+                    const bytes = await state.page.screenshot({ type: "png", fullPage: Boolean(args.fullPage) });
+                    const { file, png } = saveShotPng(bytes, stepId);
+                    return shotOutput(file, png.length);
+                }
+                if (action === "take_snapshot") {
+                    traj({ step_id: stepId, event: "call", kind: "snapshot", url: sess.currentUrl.slice(0, 200) });
+                    let yaml;
+                    try {
+                        yaml = await state.page.locator("body").ariaSnapshot();
+                    }
+                    catch (e) {
+                        throw new Error(`ariaSnapshot 不可用（playwright-core 版本过旧或缺失）：${e.message} —— 升级 playwright-core（需 ≥1.65 才有 locator.ariaSnapshot）`);
+                    }
+                    const annotated = snapIndex.annotate(yaml);
+                    traj({ step_id: stepId, event: "result", tokens: estimateTokens(annotated), nodes: snapIndex.size });
+                    const body = capTokens(annotated, `…(快照超过 browserSnapshotMaxTokens=${snapshotBudget}，后续行已截断——用 read 拿原文或先滚动再快照)`);
+                    const hint = state.dialogs.length ? `\n注意：有 ${state.dialogs.length} 个未处理对话框——先 handle_dialog` : "";
+                    return `ARIA 快照（${sess.currentUrl} · ${snapIndex.size} 个可寻址节点）——后续动作按行内 [uid=eN] 寻址：\n${body}${hint}`;
+                }
+                if (action === "click") {
+                    const loc = targetOf("uid", "selector", args);
+                    await loc.click();
+                    return `已点击 ${describeTarget(args)}${state.dialogs.length ? "；有未处理对话框——handle_dialog（同轮观察，勿另起动作）" : ""}`;
+                }
+                if (action === "fill") {
+                    const loc = targetOf("uid", "selector", args);
+                    const text = String(args.text ?? "");
+                    await loc.fill(text);
+                    return `已填充 ${describeTarget(args)}（${text.length} 字符）`;
+                }
+                if (action === "hover") {
+                    const loc = targetOf("uid", "selector", args);
+                    await loc.hover();
+                    return `已悬停 ${describeTarget(args)}`;
+                }
+                if (action === "drag") {
+                    const from = targetOf("uid", "selector", args);
+                    const to = targetOf("targetUid", "targetSelector", args);
+                    await from.dragTo(to);
+                    return `已拖拽 ${describeTarget(args, "uid")} → ${describeTarget(args, "targetUid")}`;
+                }
+                if (action === "press_key") {
+                    const key = String(args.key ?? "").trim();
+                    if (!key)
+                        throw new Error('缺少 key 参数（如 "Enter"、"Control+A"）');
+                    await state.page.keyboard.press(key);
+                    return `已按键：${key}`;
+                }
+                if (action === "upload_file") {
+                    const loc = targetOf("uid", "selector", args);
+                    const raw = args.filePath ?? args.files;
+                    const files = (Array.isArray(raw) ? raw : [raw]).map((f) => String(f ?? "").trim()).filter(Boolean);
+                    if (!files.length)
+                        throw new Error("缺少 filePath 参数（文件或文件数组，本机路径）");
+                    for (const f of files) {
+                        if (!fs.existsSync(f))
+                            throw new Error(`上传文件不存在：${f.slice(0, 200)}`);
+                    }
+                    await loc.setInputFiles(files);
+                    return `已上传 ${files.length} 个文件到 ${describeTarget(args)}`;
+                }
+                if (action === "wait_for") {
+                    const uid = String(args.uid ?? "").trim();
+                    const text = String(args.text ?? "").trim();
+                    const timeout = Math.min(30_000, Math.max(100, Number(args.timeoutMs) || PW_DEFAULT_TIMEOUT_MS));
+                    const what = uid ? `uid "${uid}"` : text ? `文本 "${text.slice(0, 80)}"` : "";
+                    if (!uid && !text)
+                        throw new Error('wait_for 需要 text 或 uid');
+                    const loc = uid ? targetOf("uid", "selector", { uid }) : state.page.getByText(text);
+                    await loc.waitFor({ state: "visible", timeout });
+                    return `等待命中：${what}（≤${timeout}ms 内可见）`;
+                }
+                if (action === "evaluate_script") {
+                    const src = String(args.function ?? args.expression ?? "").trim();
+                    if (!src)
+                        throw new Error('缺少 expression/function 参数（JS 函数源或表达式）');
+                    traj({ step_id: stepId, event: "call", kind: "evaluate" });
+                    const value = await state.page.evaluate(src);
+                    return capTokens(`执行结果：${JSON.stringify(value ?? null)}`, "…(结果超长已截断)");
+                }
+                if (action === "list_pages") {
+                    const pages = context.pages();
+                    const lines = [];
+                    for (let i = 0; i < pages.length; i++) {
+                        const p = pages[i];
+                        const title = await Promise.resolve(p.title?.()).catch(() => "");
+                        lines.push(`${i}${p === state.page ? "（当前）" : ""}: ${String(p.url?.() ?? "")} ${String(title ?? "")}`.trimEnd());
+                    }
+                    return `标签页（${pages.length}）：\n${lines.join("\n") || "（无）"}\n用 select_page { index } 切换。`;
+                }
+                if (action === "select_page") {
+                    const idx = Number(args.index);
+                    const pages = context.pages();
+                    if (!Number.isInteger(idx) || idx < 0 || idx >= pages.length) {
+                        throw new Error(`index 越界（0..${pages.length - 1}）——先 list_pages`);
+                    }
+                    state.page = pages[idx];
+                    attach(state.page);
+                    await Promise.resolve(state.page.bringToFront?.()).catch(() => { });
+                    sess.currentUrl = String(state.page.url?.() ?? "");
+                    return `已切换到标签页 ${idx}：${sess.currentUrl}`;
+                }
+                if (action === "list_console_messages") {
+                    const lines = state.consoleBuf.map((m, i) => `${i + 1}. [${m.type}] ${m.text.slice(0, 300)}`);
+                    if (args.clear)
+                        state.consoleBuf.length = 0;
+                    return capTokens(`控制台消息（缓冲 ${lines.length}/${OBSERVE_BUFFER_CAP}）：\n${lines.join("\n") || "（无）"}`, "…(消息超长已截断)");
+                }
+                if (action === "list_network_requests") {
+                    const lines = state.netBuf.map((r, i) => `${i + 1}. ${r.method} ${r.url}${r.status !== undefined ? ` → ${r.status}` : ""}${r.blocked ? " [被白名单拦截]" : r.failure ? ` [${r.failure}]` : ""}`);
+                    return capTokens(`网络请求（缓冲 ${lines.length}/${OBSERVE_BUFFER_CAP}）：\n${lines.join("\n") || "（无）"}`, "…(列表超长已截断)");
+                }
+                if (action === "handle_dialog") {
+                    const d = state.dialogs.shift();
+                    if (!d)
+                        return "没有待处理的对话框（弹窗会在 click/submit 后出现——出现时 take_snapshot 的头部会提示，再 handle_dialog）。";
+                    const verdict = String(args.dialogAction ?? "accept").trim().toLowerCase();
+                    if (verdict === "dismiss") {
+                        await d.dismiss();
+                    }
+                    else {
+                        await d.accept(typeof args.promptText === "string" ? args.promptText : undefined);
+                    }
+                    return `已处理对话框（${d.type()}：「${d.message().slice(0, 120)}」→ ${verdict === "dismiss" ? "dismiss" : "accept"}）`;
+                }
+                throw new Error(`playwright 引擎未知 action "${action}"`);
+            },
+            async close() {
+                state.dialogs.length = 0;
+                await Promise.resolve(context.close()).catch(() => { });
+                if (browser)
+                    await Promise.resolve(browser.close()).catch(() => { });
+                if (persistentDir) {
+                    return `浏览器会话已关闭；持久配置目录已保留（下次 open 复用登录态）：${persistentDir}`;
+                }
+                // playwright owns (and self-reclaims) the ephemeral profile under
+                // the browser process — nothing on our side to delete
+                return "浏览器会话已关闭，临时配置目录已清理。";
+            },
+        };
+        return sess;
     }
+    // ---------- engine-neutral session lifecycle ----------
+    async function ensureSession(headless) {
+        if (session)
+            return session;
+        const sel = await selection();
+        session =
+            sel.kind === "playwright" && sel.pw
+                ? await openPlaywrightSession(sel.pw, headless)
+                : await openLegacySession(headless);
+        return session;
+    }
+    async function closeActive() {
+        const s = session;
+        if (!s)
+            return "没有打开的浏览器会话。";
+        session = null;
+        return s.close();
+    }
+    const ALL_ACTIONS = new Set([...BROWSER_PLAYWRIGHT_ACTIONS, ...BROWSER_COMPAT_ACTIONS, "navigate_page"]);
     const execute = async (rawArgs, ctx) => {
         try {
             const args = rawArgs ?? {};
@@ -291,8 +1023,10 @@ export function buildTmBrowserTool(deps) {
             const url = String(args.url ?? "").trim();
             // allowlist FIRST — an out-of-allowlist URL only proceeds after the
             // OFFICIAL dialog approves it (then the host passes the network layer
-            // too); hard red lines (scheme / env-file) reject with no dialog
-            if ((action === "open" || action === "navigate") && url) {
+            // too); hard red lines (scheme / env-file) reject with no dialog.
+            // NOTE: this gate runs BEFORE engine selection — a blocked target
+            // never touches playwright nor spawns anything (§6o invariant).
+            if ((action === "open" || action === "navigate" || action === "navigate_page") && url) {
                 const verdict = checkWebUrl(url, allowlist);
                 if (!verdict.ok) {
                     if (!verdict.askable || !verdict.url) {
@@ -315,80 +1049,88 @@ export function buildTmBrowserTool(deps) {
                     return toToolResult(tmError(tool, "args", "缺少 url 参数"));
                 if (session) {
                     // already open: navigate instead of spawning a second browser
-                    return toToolResult(await navigateTo(url));
+                    return toToolResult(await session.act("navigate", { url }, "browser"));
                 }
                 const headless = args.headless != null ? Boolean(args.headless) : resolveHeadless(env);
                 const s = await ensureSession(headless);
-                const out = await navigateTo(url);
+                const out = await s.act("navigate", { url }, "browser");
                 traj({ step_id: "browser", event: "open", headless });
-                return toToolResult(`浏览器已启动（${headless ? "无头" : "有头窗口"}，隔离临时配置）。${out}`);
+                const mode = headless ? "无头" : "有头窗口";
+                const profile = String(env.TM_BROWSER_USER_DATA_DIR ?? "").trim() ? "持久登录配置" : "隔离临时配置";
+                const note = lastSel && preference !== "cdp-legacy" && lastSel.kind === "cdp-legacy"
+                    ? `\n（引擎：cdp-legacy 降级——${lastSel.reason ?? ""}；完整 16 动作需 npm install playwright-core + node≥20）`
+                    : "";
+                return toToolResult(`浏览器已启动（${mode}，${profile}）。${out}${note}`);
             }
-            if (action === "navigate") {
+            if (action === "navigate" || action === "navigate_page") {
                 if (!url)
                     return toToolResult(tmError(tool, "args", "缺少 url 参数"));
                 if (!session)
-                    return toToolResult(tmError(tool, "args", "没有打开的浏览器会话——先用 action:\"open\""));
-                return toToolResult(await navigateTo(url));
-            }
-            if (action === "read") {
-                if (!session)
-                    return toToolResult(tmError(tool, "args", "没有打开的浏览器会话——先用 action:\"open\""));
-                const stepId = pipelines.nextStepId();
-                traj({ step_id: stepId, event: "call", url: session.currentUrl.slice(0, 200) });
-                const ev = await session.cdp.call("Runtime.evaluate", { expression: "document.body ? document.body.innerText : ''", returnByValue: true }, session.sessionId);
-                const text = String(ev.result?.value ?? "");
-                traj({ step_id: stepId, event: "result", tokens: Math.ceil(text.length / 4) });
-                return toToolResult(`页面文本（${session.currentUrl}）：\n${text.slice(0, 20000)}${text.length > 20000 ? "\n…(截断)" : ""}`);
-            }
-            if (action === "screenshot") {
-                if (!session)
-                    return toToolResult(tmError(tool, "args", "没有打开的浏览器会话——先用 action:\"open\""));
-                const stepId = pipelines.nextStepId();
-                traj({ step_id: stepId, event: "call", kind: "screenshot", url: session.currentUrl.slice(0, 200) });
-                const shot = await session.cdp.call("Page.captureScreenshot", { format: "png" }, session.sessionId);
-                const data = String(shot.data ?? "");
-                const png = Buffer.from(data, "base64");
-                const dir = path.join(pipelines.store.stepsRoot(), stepId);
-                fs.mkdirSync(dir, { recursive: true });
-                const file = path.join(dir, "screenshot.png");
-                fs.writeFileSync(file, png);
-                traj({ step_id: stepId, event: "result", bytes: png.length });
-                return toToolResult(`截图已保存（${png.length} bytes）：${file}\n（PNG 已落 run store；上下文只携带路径，不携带像素。）`);
+                    return toToolResult(tmError(tool, "args", '没有打开的浏览器会话——先用 action:"open"'));
+                return toToolResult(await session.act(action, { url }, "browser"));
             }
             if (action === "close") {
                 traj({ step_id: "browser", event: "close" });
-                return toToolResult(await closeSession());
+                return toToolResult(await closeActive());
+            }
+            if (!ALL_ACTIONS.has(action)) {
+                return toToolResult(tmError(tool, "args", `未知 action "${String(action).slice(0, 30)}"——可用: open | navigate | take_snapshot | click | fill | hover | drag | press_key | select_page | upload_file | wait_for | evaluate_script | list_console_messages | list_network_requests | list_pages | take_screenshot | handle_dialog | read | screenshot | close（快照优先：先 take_snapshot，按 [uid=…] 寻址）`));
             }
-            return toToolResult(tmError(tool, "args", `未知 action "${String(action).slice(0, 30)}"——可用: open | navigate | read | screenshot | close`));
+            if (!session)
+                return toToolResult(tmError(tool, "args", '没有打开的浏览器会话——先用 action:"open"'));
+            // M1: upload_file SOURCE containment runs at the execute layer — the
+            // engine act() has no host ctx. Out-of-P2 paths and R6 env files are
+            // refused before setInputFiles can move any bytes.
+            if (action === "upload_file") {
+                const refusal = uploadExfilGuard(args, ctx);
+                if (refusal) {
+                    traj({ step_id: "browser", event: "upload_refused", reason: refusal.slice(0, 200) });
+                    return toToolResult(tmError(tool, "permission", refusal));
+                }
+            }
+            const stepId = pipelines.nextStepId();
+            return toToolResult(await session.act(action, args, stepId));
         }
         catch (err) {
             const e = err;
             return toToolResult(tmError(tool, "execute", String(e?.message ?? err ?? "browser 操作失败")));
         }
     };
-    async function navigateTo(url) {
-        const s = session;
-        await s.cdp.call("Page.navigate", { url }, s.sessionId);
-        await s.cdp.waitEvent("Page.loadEventFired", s.sessionId, NAVIGATE_EVENT_TIMEOUT_MS).catch(() => { });
-        s.currentUrl = url;
-        return `已导航：${url}`;
-    }
-    const DESCRIPTION = `Interactive browser (governed, Plan C): drives the user's own Chromium-family browser HEADFUL via CDP pipe — a visible window opens on desktops; display-less Linux hosts automatically run headless (TM_BROWSER_HEADLESS=1|0 forces either way).  Actions:
-- open: { url } — launch (or reuse) the session and navigate.  Isolated temp profile (never your real profile); per-request DOMAIN ALLOWLIST enforced at the network layer (seeded = tm_webfetch's hosts; extend via TM_WEBFETCH_ALLOWED_DOMAINS).
-- navigate: { url } · read: extract page text (threshold-governed like tm_read) · screenshot: save PNG into the run store, only the path enters context · close: kill + cleanup.
-- Fixed priority ladder: ① tm_* governed tools → ② user MCP/plugin tools → ③ reasoning (never fabricate).  If no browser is installed (TM_BROWSER_PATH override exists), a structured error tells you to fall back to tm_webfetch / MCP.
-- Network roles: team + researcher full grant, tester browser-only (UI verification).  Out-of-allowlist open/navigate routes through the OFFICIAL confirmation dialog (approved hosts pass the network layer for the session); env-file URLs and non-http(s) schemes hard-reject.`;
+    const DESCRIPTION = `Interactive browser (governed, Plan C): drives the user's own Chromium-family browser HEADFUL — playwright-core engine primary (npm install + node>=20; auto-degrades to the zero-dep CDP pipe when absent, snapshot actions then unavailable). Snapshot-first flow: open → take_snapshot → act by [uid] → observe again.
+- 16 actions (chrome-devtools-mcp aligned): navigate_page { url } · take_snapshot { } → ariaSnapshot YAML with injected [uid=eN] · click/fill{text}/hover { uid|selector } · drag { uid, targetUid } · press_key { key } · select_page { index } · upload_file { uid, filePath } (filePath must live INSIDE the workspace/blackboard scope — .env & shell-rc files are refused) · wait_for { text|uid, timeoutMs<=3000 default } · evaluate_script { function } · list_console_messages · list_network_requests · list_pages · take_screenshot { fullPage? } → PNG path into the run store (pixels never enter context) · handle_dialog { dialogAction: accept|dismiss, promptText }.
+- Compat actions: open { url } — launch/reuse + navigate; TM_BROWSER_PATH override → DEFAULT browser (Chromium-family only; Edge/Chrome probes fall through when it is Firefox). Isolated temp profile by default; persistent login ONLY via TM_BROWSER_USER_DATA_DIR (the real profile is never touched). navigate / read (page text) / screenshot / close also work.
+- Discipline (enforced by defaults): act ONLY on uids from the latest take_snapshot — no guessed locators; one action then one observation; fold dialogs into the same round (snapshot header warns while a dialog is held); 3000 ms action budget; networkidle is never waited on; screenshots are the visual-last-resort, not the primary read.
+- Network: per-request domain allowlist enforced INSIDE the page (playwright context.route abort / CDP Fetch interception), re-checked on every redirect hop; seeded = tm_webfetch's hosts (extend via TM_WEBFETCH_ALLOWED_DOMAINS). Out-of-allowlist open/navigate routes through the OFFICIAL confirmation dialog BEFORE any spawn; approved hosts pass the network layer for the session; env-file URLs and non-http(s) schemes hard-reject.
+- Fixed priority ladder: ① tm_* governed tools → ② user MCP/plugin tools → ③ reasoning (never fabricate).  No browser installed → structured error, fall back to tm_webfetch / MCP.  Role grant: team + researcher full, tester browser-only (UI verification).`;
     return {
         description: DESCRIPTION,
         args: deps.args ?? {
-            action: { descriptor: "action: open|navigate|read|screenshot|close (required)" },
-            url: { descriptor: "url: string (open/navigate, allowlisted https)" },
+            action: { descriptor: "action: take_snapshot|click|fill|navigate_page|... (16 playwright verbs + open/navigate/read/screenshot/close)" },
+            url: { descriptor: "url: string (open/navigate/navigate_page, allowlisted https)" },
             headless: { descriptor: "headless: boolean (open, optional — default auto)" },
+            uid: { descriptor: "uid: snapshot [uid=eN] token (click/fill/hover/drag/upload_file/wait_for)" },
+            selector: { descriptor: "selector: CSS/text locator escape hatch (only when a snapshot cannot express the node)" },
+            targetUid: { descriptor: "targetUid: drag destination uid" },
+            targetSelector: { descriptor: "targetSelector: drag destination selector" },
+            text: { descriptor: "text: fill value / wait_for visible text" },
+            key: { descriptor: "key: press_key chord, e.g. Enter|Control+A" },
+            function: { descriptor: "function: JS function source for evaluate_script" },
+            filePath: { descriptor: "filePath: local file path(s) for upload_file" },
+            index: { descriptor: "index: select_page target from list_pages" },
+            timeoutMs: { descriptor: "timeoutMs: wait_for budget (default 3000)" },
+            fullPage: { descriptor: "fullPage: take_screenshot full page (default viewport only)" },
+            dialogAction: { descriptor: "dialogAction: accept|dismiss for handle_dialog (default accept)" },
+            promptText: { descriptor: "promptText: prompt-dialog reply for handle_dialog accept" },
+            clear: { descriptor: "clear: drain the console buffer after list_console_messages" },
         },
         execute,
         dispose: () => {
-            void closeSession().catch(() => { });
+            void closeActive().catch(() => { });
         },
+        engineInfo: () => ({
+            kind: lastSel?.kind ?? null,
+            reason: lastSel?.reason ?? null,
+        }),
     };
 }
 //# sourceMappingURL=browser.js.map