@farazirfan/costar-server-executor 1.7.30 → 1.7.32

package/dist/tools/browser.js

@@ -1,78 +1,55 @@
 /**
- * CoStar Server Executor - Complete Browser Tool
- * Replicates OpenClaw's browser-tool.ts behavior using direct Playwright
+ * CoStar Server Executor - Browser Tool
  *
- * Implements all 15 actions with AI snapshots, labeled screenshots, and full automation
+ * Same architecture as OpenClaw: Chrome child process + CDP connection.
+ * All pw-* functions receive { cdpUrl, targetId } — identical to OpenClaw.
  */
 import { Type } from "@sinclair/typebox";
-import { chromium } from "playwright";
 import { jsonResult, readStringParam, readBooleanParam, readNumberParam, readArrayParam, } from "../utils/tool-helpers.js";
-// OpenClaw exact BROWSER_ACT_KINDS (from browser-tool.schema.ts)
+// ─── OpenClaw browser modules (verbatim copy) ──────────────────────
+import { 
+// Session state
+ensurePageState, getPageForTargetId, closePlaywrightBrowserConnection, listPagesViaPlaywright, createPageViaPlaywright, closePageByTargetIdViaPlaywright, focusPageByTargetIdViaPlaywright, 
+// Interactions (all take { cdpUrl, targetId })
+clickViaPlaywright, hoverViaPlaywright, dragViaPlaywright, selectOptionViaPlaywright, pressKeyViaPlaywright, typeViaPlaywright, fillFormViaPlaywright, evaluateViaPlaywright, waitForViaPlaywright, takeScreenshotViaPlaywright, screenshotWithLabelsViaPlaywright, 
+// Snapshots & navigation
+snapshotRoleViaPlaywright, navigateViaPlaywright, resizeViewportViaPlaywright, pdfViaPlaywright, 
+// Downloads & uploads
+armFileUploadViaPlaywright, armDialogViaPlaywright, 
+// Process isolation (Chrome child process + CDP)
+launchCostarChrome, stopCostarChrome, } from "../browser/index.js";
+// ─── Sandbox browser (Docker container) ─────────────────────────────
+import { startSandboxBrowser, stopSandboxBrowser, } from "../sandbox/index.js";
+// ─── Schema definitions (OpenClaw exact) ────────────────────────────
 const BROWSER_ACT_KINDS = [
-    "click",
-    "type",
-    "press",
-    "hover",
-    "drag",
-    "select",
-    "fill",
-    "resize",
-    "wait",
-    "evaluate",
-    "close",
+    "click", "type", "press", "hover", "drag",
+    "select", "fill", "resize", "wait", "evaluate", "close",
 ];
-// OpenClaw exact BROWSER_TOOL_ACTIONS (from browser-tool.schema.ts)
 const BROWSER_TOOL_ACTIONS = [
-    "status",
-    "start",
-    "stop",
-    "profiles",
-    "tabs",
-    "open",
-    "focus",
-    "close",
-    "snapshot",
-    "screenshot",
-    "navigate",
-    "console",
-    "pdf",
-    "upload",
-    "dialog",
-    "act",
+    "status", "start", "stop", "profiles", "tabs", "open", "focus", "close",
+    "snapshot", "screenshot", "navigate", "console", "pdf", "upload", "dialog", "act",
 ];
-// OpenClaw exact BrowserActSchema (from browser-tool.schema.ts)
 const BrowserActSchema = Type.Object({
     kind: Type.Union(BROWSER_ACT_KINDS.map(k => Type.Literal(k))),
-    // Common fields
     targetId: Type.Optional(Type.String()),
     ref: Type.Optional(Type.String()),
-    // click
     doubleClick: Type.Optional(Type.Boolean()),
     button: Type.Optional(Type.String()),
     modifiers: Type.Optional(Type.Array(Type.String())),
-    // type
     text: Type.Optional(Type.String()),
     submit: Type.Optional(Type.Boolean()),
     slowly: Type.Optional(Type.Boolean()),
-    // press
     key: Type.Optional(Type.String()),
-    // drag
     startRef: Type.Optional(Type.String()),
     endRef: Type.Optional(Type.String()),
-    // select
     values: Type.Optional(Type.Array(Type.String())),
-    // fill - use permissive array of objects
     fields: Type.Optional(Type.Array(Type.Object({}, { additionalProperties: true }))),
-    // resize
     width: Type.Optional(Type.Number()),
     height: Type.Optional(Type.Number()),
-    // wait
     timeMs: Type.Optional(Type.Number()),
     textGone: Type.Optional(Type.String()),
-    // evaluate
     fn: Type.Optional(Type.String()),
 });
-// OpenClaw exact BrowserToolSchema (from browser-tool.schema.ts)
 const BrowserSchema = Type.Object({
     action: Type.Union(BROWSER_TOOL_ACTIONS.map(a => Type.Literal(a))),
     profile: Type.Optional(Type.String()),
@@ -80,8 +57,8 @@ const BrowserSchema = Type.Object({
     targetId: Type.Optional(Type.String()),
     limit: Type.Optional(Type.Number()),
     maxChars: Type.Optional(Type.Number()),
-    mode: Type.Optional(Type.String()), // "efficient"
-    refs: Type.Optional(Type.String()), // "role" or "aria"
+    mode: Type.Optional(Type.String()),
+    refs: Type.Optional(Type.String()),
     interactive: Type.Optional(Type.Boolean()),
     compact: Type.Optional(Type.Boolean()),
     depth: Type.Optional(Type.Number()),
@@ -91,7 +68,7 @@ const BrowserSchema = Type.Object({
     fullPage: Type.Optional(Type.Boolean()),
     ref: Type.Optional(Type.String()),
     element: Type.Optional(Type.String()),
-    type: Type.Optional(Type.String()), // "png" or "jpeg"
+    type: Type.Optional(Type.String()),
     level: Type.Optional(Type.String()),
     paths: Type.Optional(Type.Array(Type.String())),
     inputRef: Type.Optional(Type.String()),
@@ -100,1076 +77,308 @@ const BrowserSchema = Type.Object({
     promptText: Type.Optional(Type.String()),
     request: Type.Optional(BrowserActSchema),
 });
-// OpenClaw's INTERACTIVE_ROLES - elements that get refs
-const INTERACTIVE_ROLES = new Set([
-    "button",
-    "link",
-    "textbox",
-    "checkbox",
-    "radio",
-    "combobox",
-    "listbox",
-    "menuitem",
-    "menuitemcheckbox",
-    "menuitemradio",
-    "option",
-    "searchbox",
-    "slider",
-    "spinbutton",
-    "switch",
-    "tab",
-    "treeitem",
-]);
-const CONTENT_ROLES = new Set([
-    "heading",
-    "cell",
-    "gridcell",
-    "columnheader",
-    "rowheader",
-    "listitem",
-    "article",
-    "region",
-    "main",
-    "navigation",
-]);
-/**
- * Parse Playwright's ariaSnapshot output and build refs map (OpenClaw style)
- */
-function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
-    const lines = ariaSnapshot.split("\n");
-    const refs = {};
-    // Track role+name combinations for nth handling
-    const counts = new Map();
-    const refsByKey = new Map();
-    const getKey = (role, name) => `${role}:${name ?? ""}`;
-    let counter = 0;
-    const nextRef = () => {
-        counter += 1;
-        return `e${counter}`;
-    };
-    const getIndentLevel = (line) => {
-        const match = line.match(/^(\s*)/);
-        return match ? Math.floor(match[1].length / 2) : 0;
-    };
-    const result = [];
-    for (const line of lines) {
-        const depth = getIndentLevel(line);
-        if (options.maxDepth !== undefined && depth > options.maxDepth)
-            continue;
-        // Parse line: "- role "name" [other stuff]"
-        const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-        if (!match) {
-            if (!options.interactive)
-                result.push(line);
-            continue;
-        }
-        const [, prefix, roleRaw, name, suffix] = match;
-        if (roleRaw.startsWith("/")) {
-            if (!options.interactive)
-                result.push(line);
-            continue;
-        }
-        const role = roleRaw.toLowerCase();
-        const isInteractive = INTERACTIVE_ROLES.has(role);
-        const isContent = CONTENT_ROLES.has(role);
-        // If interactive-only mode, skip non-interactive
-        if (options.interactive && !isInteractive)
-            continue;
-        // Determine if this element should have a ref
-        const shouldHaveRef = isInteractive || (isContent && name);
-        if (!shouldHaveRef) {
-            if (!options.interactive)
-                result.push(line);
-            continue;
-        }
-        const ref = nextRef();
-        const key = getKey(role, name);
-        const nth = counts.get(key) ?? 0;
-        counts.set(key, nth + 1);
-        const keyRefs = refsByKey.get(key) ?? [];
-        keyRefs.push(ref);
-        refsByKey.set(key, keyRefs);
-        refs[ref] = { role, name, nth };
-        // Build enhanced line with ref
-        let enhanced = `${prefix}${roleRaw}`;
-        if (name)
-            enhanced += ` "${name}"`;
-        enhanced += ` [ref=${ref}]`;
-        if (nth > 0)
-            enhanced += ` [nth=${nth}]`;
-        if (suffix && suffix.includes("["))
-            enhanced += suffix;
-        result.push(enhanced);
-    }
-    // Remove nth from non-duplicates
-    for (const [_key, keyRefs] of refsByKey) {
-        if (keyRefs.length === 1) {
-            const ref = keyRefs[0];
-            if (refs[ref])
-                delete refs[ref].nth;
-        }
-    }
-    return {
-        snapshot: result.join("\n") || "(empty)",
-        refs,
-    };
-}
-// OpenClaw-style WeakMap to store state per Page object
-const pageStates = new WeakMap();
-// Global cache by targetId (backup for when Playwright returns different Page object)
-const roleRefsByTarget = new Map();
-const MAX_ROLE_REFS_CACHE = 50;
-// Ensure page has a state object (OpenClaw-style)
-function ensurePageState(page) {
-    const existing = pageStates.get(page);
-    if (existing)
-        return existing;
-    const newState = {
-        console: [],
-        errors: [],
-        requests: [],
-    };
-    pageStates.set(page, newState);
-    return newState;
-}
-// Global browser state (singleton)
+const DEFAULT_CDP_PORT = 18800;
 const state = {
-    browser: null,
-    context: null,
-    pages: new Map(),
-    consoleLogs: new Map(),
-    networkRequests: new Map(),
-    pageErrors: new Map(),
     running: false,
-    connectionMode: "launched",
+    cdpUrl: "",
+    mode: "local",
 };
-/**
- * Get the page to use for an action, tracking last active (OpenClaw-style)
- */
-function getPageForAction(targetId) {
-    if (targetId) {
-        const existingPage = state.pages.get(targetId);
-        if (!existingPage) {
-            throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-        }
-        state.lastActiveTargetId = targetId;
-        return { page: existingPage, usedTargetId: targetId };
-    }
-    if (state.pages.size === 0) {
-        throw new Error("No tabs open. Use action=open to open a URL first.");
-    }
-    // Prefer last active tab (the one most recently used for snapshot/action)
-    if (state.lastActiveTargetId && state.pages.has(state.lastActiveTargetId)) {
-        const page = state.pages.get(state.lastActiveTargetId);
-        return { page, usedTargetId: state.lastActiveTargetId };
-    }
-    // Fall back to first tab
-    const firstEntry = Array.from(state.pages.entries())[0];
-    state.lastActiveTargetId = firstEntry[0];
-    return { page: firstEntry[1], usedTargetId: firstEntry[0] };
-}
-/**
- * Restore role refs for a target (OpenClaw-style)
- * This ensures refs are available for the page even if they were stored under a different targetId
- */
-/**
- * Store role refs for a target (OpenClaw-style)
- * Stores BOTH on page's WeakMap state AND in global cache
- */
-function storeRoleRefsForTarget(opts) {
-    // Store on page's WeakMap state
-    const pageState = ensurePageState(opts.page);
-    pageState.roleRefs = opts.refs;
-    pageState.roleRefsFrameSelector = opts.frameSelector;
-    pageState.roleRefsMode = opts.mode;
-    // Store in global cache by targetId (for backup)
-    const targetId = opts.targetId?.trim();
-    if (!targetId)
-        return;
-    roleRefsByTarget.set(targetId, {
-        refs: opts.refs,
-        ...(opts.frameSelector ? { frameSelector: opts.frameSelector } : {}),
-        mode: opts.mode,
+// ─── Browser lifecycle (OpenClaw pattern: always Chrome child process) ──
+async function isDockerAvailable() {
+    const { execFile } = await import("node:child_process");
+    return new Promise((resolve) => {
+        execFile("docker", ["info"], { timeout: 5000 }, (err) => resolve(!err));
     });
-    // Limit cache size
-    while (roleRefsByTarget.size > MAX_ROLE_REFS_CACHE) {
-        const first = roleRefsByTarget.keys().next();
-        if (first.done)
-            break;
-        roleRefsByTarget.delete(first.value);
-    }
-    console.log(`[BROWSER] Stored ${Object.keys(opts.refs).length} refs for targetId "${targetId}"`);
 }
 /**
- * Restore role refs for a target (OpenClaw-style)
- * Copies from global cache to page's WeakMap state
+ * Start the browser in the best available mode.
+ * Priority: docker sandbox > local Chrome child process.
+ * Override: BROWSER_SANDBOX=false forces local mode.
  */
-function restoreRoleRefsForTarget(page, targetId) {
-    const tid = targetId?.trim() || "";
-    if (!tid)
-        return;
-    // Check if page already has refs (no need to restore)
-    const pageState = ensurePageState(page);
-    if (pageState.roleRefs) {
-        console.log(`[BROWSER] Page already has ${Object.keys(pageState.roleRefs).length} refs`);
-        return;
-    }
-    // Try to restore from global cache
-    const cached = roleRefsByTarget.get(tid);
-    if (cached) {
-        pageState.roleRefs = cached.refs;
-        pageState.roleRefsFrameSelector = cached.frameSelector;
-        pageState.roleRefsMode = cached.mode;
-        console.log(`[BROWSER] Restored ${Object.keys(cached.refs).length} refs from cache for "${tid}"`);
+async function startBrowser(options) {
+    if (state.running)
         return;
-    }
-    // Fallback: try any targetId that has refs
-    for (const [storedTargetId, storedData] of roleRefsByTarget.entries()) {
-        if (Object.keys(storedData.refs).length > 0) {
-            pageState.roleRefs = storedData.refs;
-            pageState.roleRefsFrameSelector = storedData.frameSelector;
-            pageState.roleRefsMode = storedData.mode;
-            console.log(`[BROWSER] Restored ${Object.keys(storedData.refs).length} refs from "${storedTargetId}" (fallback)`);
+    const forceLocal = process.env.BROWSER_SANDBOX === "false";
+    // ─── Try Docker sandbox (production on Hetzner, local dev with Docker Desktop) ───
+    if (!forceLocal && await isDockerAvailable()) {
+        const headless = options?.headless ?? process.env.BROWSER_SANDBOX_HEADLESS !== "false";
+        console.log(`[BROWSER] Starting Docker sandbox browser (headless: ${headless})...`);
+        try {
+            const sandboxState = await startSandboxBrowser({ headless });
+            state.sandboxState = sandboxState;
+            state.cdpUrl = sandboxState.cdpUrl;
+            state.mode = "sandbox";
+            state.running = true;
+            console.log(`[BROWSER] Docker sandbox ready, CDP: ${state.cdpUrl}`);
             return;
         }
+        catch (err) {
+            console.warn(`[BROWSER] Docker sandbox failed, falling back to local Chrome: ${err instanceof Error ? err.message : err}`);
+        }
     }
-    console.log(`[BROWSER] No refs available to restore`);
-}
-function generateTargetId() {
-    return `page-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
-}
-async function startBrowser(options = {}) {
-    if (state.running) {
-        return;
-    }
-    // Check if we should run in headless mode (default true, can be overridden by env var or param)
-    const headlessMode = options.headless ?? process.env.BROWSER_HEADLESS !== "false";
-    const launchOptions = {
-        headless: headlessMode,
-        args: ["--no-sandbox", "--disable-setuid-sandbox"],
-    };
-    // Support persistent profile directory
-    if (options.profilePath) {
-        console.log(`[BROWSER] Using profile: ${options.profilePath}`);
-        // For persistent context, we use launchPersistentContext instead
-        state.context = await chromium.launchPersistentContext(options.profilePath, {
-            ...launchOptions,
-            viewport: { width: 1280, height: 720 },
-            userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
-        });
-        state.browser = null; // Persistent context doesn't have separate browser
+    // ─── Local mode: Chrome child process (fallback) ───
+    {
+        const headlessMode = options?.headless ?? process.env.BROWSER_HEADLESS !== "false";
+        const cdpPort = DEFAULT_CDP_PORT;
+        const resolvedConfig = {
+            enabled: true,
+            evaluateEnabled: true,
+            controlPort: 0,
+            cdpProtocol: "http",
+            cdpHost: "127.0.0.1",
+            cdpIsLoopback: true,
+            remoteCdpTimeoutMs: 5000,
+            remoteCdpHandshakeTimeoutMs: 5000,
+            color: "#FF4500",
+            headless: headlessMode,
+            noSandbox: true,
+            attachOnly: false,
+            defaultProfile: "costar",
+            profiles: {},
+            extraArgs: [],
+        };
+        const resolvedProfile = {
+            name: "costar",
+            cdpPort,
+            cdpUrl: `http://127.0.0.1:${cdpPort}`,
+            cdpHost: "127.0.0.1",
+            cdpIsLoopback: true,
+            color: "#FF4500",
+            driver: "openclaw",
+        };
+        console.log(`[BROWSER] Starting Chrome (headless: ${headlessMode}, CDP port: ${cdpPort})...`);
+        const running = await launchCostarChrome(resolvedConfig, resolvedProfile);
+        state.chromeProcess = running;
+        state.cdpUrl = resolvedProfile.cdpUrl;
+        state.mode = "local";
         state.running = true;
-        state.connectionMode = "launched";
-        console.log(`[BROWSER] Started with persistent profile (headless: ${headlessMode})`);
-        return;
+        console.log(`[BROWSER] Chrome started (pid: ${running.pid}), CDP: ${state.cdpUrl}`);
     }
-    console.log(`[BROWSER] Starting Chromium... (headless: ${headlessMode})`);
-    state.browser = await chromium.launch(launchOptions);
-    state.context = await state.browser.newContext({
-        viewport: { width: 1280, height: 720 },
-        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
-    });
-    state.running = true;
-    state.connectionMode = "launched";
-    console.log("[BROWSER] Started");
-}
-/**
- * Set up page event listeners (extracted for reuse)
- */
-function setupPageListeners(page, targetId) {
-    let nextRequestId = 0;
-    const requestIds = new WeakMap();
-    // Capture console logs
-    page.on("console", (msg) => {
-        const logs = state.consoleLogs.get(targetId) || [];
-        logs.push(msg);
-        if (logs.length > 500)
-            logs.shift();
-        state.consoleLogs.set(targetId, logs);
-    });
-    // Capture page errors
-    page.on("pageerror", (err) => {
-        const errors = state.pageErrors.get(targetId) || [];
-        errors.push({
-            message: err?.message || String(err),
-            name: err?.name,
-            stack: err?.stack,
-            timestamp: new Date().toISOString(),
-        });
-        if (errors.length > 200)
-            errors.shift();
-        state.pageErrors.set(targetId, errors);
-    });
-    // Capture network requests
-    page.on("request", (req) => {
-        nextRequestId += 1;
-        const id = `r${nextRequestId}`;
-        requestIds.set(req, id);
-        const requests = state.networkRequests.get(targetId) || [];
-        requests.push({
-            id,
-            timestamp: new Date().toISOString(),
-            method: req.method(),
-            url: req.url(),
-            resourceType: req.resourceType(),
-        });
-        if (requests.length > 500)
-            requests.shift();
-        state.networkRequests.set(targetId, requests);
-    });
-    page.on("response", (resp) => {
-        const req = resp.request();
-        const id = requestIds.get(req);
-        if (!id)
-            return;
-        const requests = state.networkRequests.get(targetId) || [];
-        const rec = requests.find((r) => r.id === id);
-        if (rec) {
-            rec.status = resp.status();
-            rec.ok = resp.ok();
-        }
-    });
-    page.on("requestfailed", (req) => {
-        const id = requestIds.get(req);
-        if (!id)
-            return;
-        const requests = state.networkRequests.get(targetId) || [];
-        const rec = requests.find((r) => r.id === id);
-        if (rec) {
-            rec.failureText = req.failure()?.errorText;
-            rec.ok = false;
-        }
-    });
 }
 async function stopBrowser() {
-    if (!state.running) {
+    if (!state.running)
         return;
+    console.log("[BROWSER] Stopping...");
+    // Close Playwright connection managed by pw-session
+    await closePlaywrightBrowserConnection().catch(() => { });
+    if (state.mode === "sandbox" && state.sandboxState) {
+        // Stop Docker container
+        await stopSandboxBrowser(state.sandboxState);
+        state.sandboxState = undefined;
     }
-    const isConnected = state.connectionMode === "connected";
-    console.log(`[BROWSER] Stopping... (mode: ${state.connectionMode})`);
-    // Close all pages we opened (but not pre-existing pages in CDP mode)
-    for (const [id, page] of state.pages.entries()) {
-        try {
-            await page.close();
-        }
-        catch (err) {
-            console.warn(`[BROWSER] Error closing page ${id}:`, err);
-        }
-    }
-    state.pages.clear();
-    state.consoleLogs.clear();
-    state.networkRequests.clear();
-    state.pageErrors.clear();
-    roleRefsByTarget.clear(); // Clear the OpenClaw-style global cache
-    // For CDP connections, we disconnect but don't close the browser
-    if (isConnected) {
-        if (state.browser) {
-            // disconnect() keeps the browser running
-            state.browser.close(); // This disconnects for CDP
-            state.browser = null;
-        }
-        state.context = null;
-        state.wsEndpoint = undefined;
-        console.log("[BROWSER] Disconnected from CDP");
-    }
-    else {
-        // For launched browsers, close everything
-        if (state.context) {
-            await state.context.close();
-            state.context = null;
-        }
-        if (state.browser) {
-            await state.browser.close();
-            state.browser = null;
-        }
-        console.log("[BROWSER] Stopped");
+    else if (state.chromeProcess) {
+        // Kill Chrome child process
+        console.log(`[BROWSER] Stopping Chrome (pid: ${state.chromeProcess.pid})...`);
+        await stopCostarChrome(state.chromeProcess);
+        state.chromeProcess = undefined;
     }
     state.running = false;
-    state.connectionMode = "launched";
+    state.cdpUrl = "";
+    state.mode = "local";
+    state.lastActiveTargetId = undefined;
+    console.log("[BROWSER] Stopped");
 }
-async function openPage(url) {
-    if (!state.running || !state.context) {
-        await startBrowser();
+// ─── Helpers ────────────────────────────────────────────────────────
+function requireRunning() {
+    if (!state.running || !state.cdpUrl) {
+        throw new Error("Browser not running. Use action=start first.");
     }
-    const page = await state.context.newPage();
-    const targetId = generateTargetId();
-    state.pages.set(targetId, page);
-    state.consoleLogs.set(targetId, []);
-    state.networkRequests.set(targetId, []);
-    state.pageErrors.set(targetId, []);
-    // Track as last active tab
-    state.lastActiveTargetId = targetId;
-    // Set up event listeners
-    setupPageListeners(page, targetId);
-    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
-    return { targetId, page };
+    return state.cdpUrl;
 }
-/**
- * Build role snapshot from Playwright's AI snapshot output (OpenClaw style)
- * Preserves Playwright's own aria-ref ids (e.g. ref=e13)
- */
-function buildRoleSnapshotFromAiSnapshot(aiSnapshot, options = {}) {
-    const lines = String(aiSnapshot ?? "").split("\n");
-    const refs = {};
-    const getIndentLevel = (line) => {
-        const match = line.match(/^(\s*)/);
-        return match ? Math.floor(match[1].length / 2) : 0;
-    };
-    const parseAiSnapshotRef = (suffix) => {
-        const match = suffix.match(/\[ref=(e\d+)\]/i);
-        return match ? match[1] : null;
-    };
-    if (options.interactive) {
-        const out = [];
-        for (const line of lines) {
-            const depth = getIndentLevel(line);
-            if (options.maxDepth !== undefined && depth > options.maxDepth)
-                continue;
-            const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-            if (!match)
-                continue;
-            const [, , roleRaw, name, suffix] = match;
-            if (roleRaw.startsWith("/"))
-                continue;
-            const role = roleRaw.toLowerCase();
-            if (!INTERACTIVE_ROLES.has(role))
-                continue;
-            const ref = parseAiSnapshotRef(suffix);
-            if (!ref)
-                continue;
-            refs[ref] = { role, ...(name ? { name } : {}) };
-            out.push(`- ${roleRaw}${name ? ` "${name}"` : ""}${suffix}`);
-        }
-        return {
-            snapshot: out.join("\n") || "(no interactive elements)",
-            refs,
-        };
-    }
-    const out = [];
-    for (const line of lines) {
-        const depth = getIndentLevel(line);
-        if (options.maxDepth !== undefined && depth > options.maxDepth)
-            continue;
-        const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
-        if (!match) {
-            out.push(line);
-            continue;
-        }
-        const [, , roleRaw, name, suffix] = match;
-        if (roleRaw.startsWith("/")) {
-            out.push(line);
-            continue;
-        }
-        const role = roleRaw.toLowerCase();
-        const ref = parseAiSnapshotRef(suffix);
-        if (ref)
-            refs[ref] = { role, ...(name ? { name } : {}) };
-        out.push(line);
+function resolveTargetId(params) {
+    const targetId = readStringParam(params, "targetId");
+    if (targetId) {
+        state.lastActiveTargetId = targetId;
+        return targetId;
     }
-    const tree = out.join("\n") || "(empty)";
-    return { snapshot: tree, refs };
+    return state.lastActiveTargetId;
 }
-/**
- * Get AI-formatted snapshot of page (OpenClaw-style)
- * Uses Playwright's _snapshotForAI() for accurate role detection and ref building
- * This captures the FULL accessibility tree including modals/overlays
- *
- * Ref modes:
- * - "role" (default): Generates refs based on role+name from ariaSnapshot, requires snapshot context
- * - "aria": Uses Playwright's aria-ref IDs, self-resolving across calls
- */
-async function getAISnapshot(page, targetId, options) {
-    const maxChars = options.maxChars || 50000;
-    const labels = options.labels || false;
-    const refsMode = options.refs || "role";
-    let ariaSnapshotText = "";
-    let refsMap;
-    let roleSnapshot;
-    // OpenClaw-style: Two separate modes, NO fallback
-    if (refsMode === "aria") {
-        // refs="aria" mode: Use _snapshotForAI for self-resolving refs
-        // This captures the FULL accessibility tree including modals/overlays
-        if (options.selector || options.frame) {
-            throw new Error("refs=aria does not support selector/frame snapshots yet.");
-        }
-        const maybePage = page;
-        if (!maybePage._snapshotForAI) {
-            throw new Error("refs=aria requires Playwright _snapshotForAI support. Upgrade playwright-core.");
-        }
-        console.log(`[BROWSER] Using _snapshotForAI for aria mode (captures modals/overlays)`);
-        const result = await maybePage._snapshotForAI({
-            timeout: 5000,
-            track: "response",
-        });
-        ariaSnapshotText = String(result?.full ?? "");
-        console.log(`[BROWSER] _snapshotForAI returned ${ariaSnapshotText.length} chars`);
-        // Parse AI snapshot - refs are self-resolving via aria-ref=
-        const built = buildRoleSnapshotFromAiSnapshot(ariaSnapshotText, {
-            interactive: options.interactive,
-            maxDepth: options.maxDepth,
-            compact: options.compact,
-        });
-        refsMap = built.refs;
-        roleSnapshot = built.snapshot;
-        console.log(`[BROWSER] Aria mode - refs are self-resolving via aria-ref=`);
-    }
-    else {
-        // refs="role" mode (default): Use locator.ariaSnapshot()
-        // Refs are resolved via getByRole with the stored ref map
-        const frameSelector = options.frame?.trim() || "";
-        const selector = options.selector?.trim() || "";
-        const locator = frameSelector
-            ? selector
-                ? page.frameLocator(frameSelector).locator(selector)
-                : page.frameLocator(frameSelector).locator(":root")
-            : selector
-                ? page.locator(selector)
-                : page.locator(":root");
-        console.log(`[BROWSER] Using ariaSnapshot() for role mode`);
-        ariaSnapshotText = await locator.ariaSnapshot();
-        console.log(`[BROWSER] ariaSnapshot() returned ${ariaSnapshotText.length} chars`);
-        // Parse aria snapshot - we generate refs that require role map for resolution
-        const built = buildRoleSnapshotFromAriaSnapshot(ariaSnapshotText, {
-            interactive: options.interactive,
-            maxDepth: options.maxDepth,
-            compact: options.compact,
-        });
-        refsMap = built.refs;
-        roleSnapshot = built.snapshot;
-        console.log(`[BROWSER] Role mode - refs require role map for resolution`);
-    }
-    // Step 2: Store refs using OpenClaw-style function (stores to BOTH WeakMap and global cache)
-    console.log(`[BROWSER] Snapshot generated ${Object.keys(refsMap).length} refs for targetId "${targetId}"`);
-    if (Object.keys(refsMap).length > 0) {
-        storeRoleRefsForTarget({
-            page,
-            targetId,
-            refs: refsMap,
-            frameSelector: options.frame,
-            mode: refsMode,
-        });
-        console.log(`[BROWSER] Stored refs with mode="${refsMode}". Sample: ${Object.keys(refsMap).slice(0, 5).join(", ")}`);
-    }
-    else {
-        console.log(`[BROWSER] WARNING: No refs generated from snapshot. Snapshot length: ${ariaSnapshotText.length}`);
-        console.log(`[BROWSER] Snapshot preview: ${ariaSnapshotText.slice(0, 500)}`);
-    }
-    // Step 4: If labels requested, create labeled screenshot using stored refs
+// ─── Snapshot helper ────────────────────────────────────────────────
+async function getAISnapshot(cdpUrl, targetId, options) {
+    const maxChars = options?.maxChars || 50000;
+    const labels = options?.labels || false;
+    const refsMode = options?.refs || "role";
+    const snapshotResult = await snapshotRoleViaPlaywright({
+        cdpUrl,
+        targetId,
+        selector: options?.selector,
+        frameSelector: options?.frame,
+        refsMode,
+        options: {
+            interactive: options?.interactive,
+            maxDepth: options?.maxDepth,
+            compact: options?.compact,
+        },
+    });
+    const refsMap = snapshotResult.refs;
+    console.log(`[BROWSER] Snapshot: ${Object.keys(refsMap).length} refs`);
     let imagePath;
     let labelsCount = 0;
     if (labels && Object.keys(refsMap).length > 0) {
-        const maxLabels = 150;
-        const viewport = await page.evaluate(() => ({
-            scrollX: window.scrollX || 0,
-            scrollY: window.scrollY || 0,
-            width: window.innerWidth || 0,
-            height: window.innerHeight || 0,
-        }));
-        const refs = Object.keys(refsMap);
-        const boxes = [];
-        let skipped = 0;
-        // Get bounding boxes using role-based locators (OpenClaw style)
-        for (const ref of refs) {
-            if (boxes.length >= maxLabels) {
-                skipped += 1;
-                continue;
-            }
-            try {
-                const info = refsMap[ref];
-                let refLocator;
-                if (info.name) {
-                    refLocator = page.getByRole(info.role, { name: info.name, exact: true });
-                    if (info.nth !== undefined)
-                        refLocator = refLocator.nth(info.nth);
-                }
-                else {
-                    refLocator = page.getByRole(info.role);
-                    if (info.nth !== undefined)
-                        refLocator = refLocator.nth(info.nth);
-                }
-                const box = await refLocator.boundingBox();
-                if (!box) {
-                    skipped += 1;
-                    continue;
-                }
-                // Check if in viewport
-                const x0 = box.x;
-                const y0 = box.y;
-                const x1 = box.x + box.width;
-                const y1 = box.y + box.height;
-                const vx0 = viewport.scrollX;
-                const vy0 = viewport.scrollY;
-                const vx1 = viewport.scrollX + viewport.width;
-                const vy1 = viewport.scrollY + viewport.height;
-                if (x1 < vx0 || x0 > vx1 || y1 < vy0 || y0 > vy1) {
-                    skipped += 1;
-                    continue;
-                }
-                boxes.push({
-                    ref,
-                    x: x0 - viewport.scrollX,
-                    y: y0 - viewport.scrollY,
-                    w: Math.max(1, box.width),
-                    h: Math.max(1, box.height),
-                });
-            }
-            catch {
-                skipped += 1;
-            }
-        }
-        labelsCount = boxes.length;
-        try {
-            if (boxes.length > 0) {
-                // Inject labels overlay (OpenClaw style)
-                await page.evaluate((labelBoxes) => {
-                    const existing = document.querySelectorAll("[data-browser-labels]");
-                    existing.forEach((el) => el.remove());
-                    const root = document.createElement("div");
-                    root.setAttribute("data-browser-labels", "1");
-                    root.style.position = "fixed";
-                    root.style.left = "0";
-                    root.style.top = "0";
-                    root.style.zIndex = "2147483647";
-                    root.style.pointerEvents = "none";
-                    root.style.fontFamily = '"SF Mono","SFMono-Regular",Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace';
-                    for (const label of labelBoxes) {
-                        const box = document.createElement("div");
-                        box.setAttribute("data-browser-labels", "1");
-                        box.style.position = "absolute";
-                        box.style.left = `${label.x}px`;
-                        box.style.top = `${label.y}px`;
-                        box.style.width = `${label.w}px`;
-                        box.style.height = `${label.h}px`;
-                        box.style.border = "2px solid #ffb020";
-                        box.style.boxSizing = "border-box";
-                        const tag = document.createElement("div");
-                        tag.setAttribute("data-browser-labels", "1");
-                        tag.textContent = label.ref;
-                        tag.style.position = "absolute";
-                        tag.style.left = `${label.x}px`;
-                        tag.style.top = `${Math.min(20000, Math.max(0, label.y - 18))}px`;
-                        tag.style.background = "#ffb020";
-                        tag.style.color = "#1a1a1a";
-                        tag.style.fontSize = "12px";
-                        tag.style.lineHeight = "14px";
-                        tag.style.padding = "1px 4px";
-                        tag.style.borderRadius = "3px";
-                        tag.style.boxShadow = "0 1px 2px rgba(0,0,0,0.35)";
-                        tag.style.whiteSpace = "nowrap";
-                        root.appendChild(box);
-                        root.appendChild(tag);
-                    }
-                    document.documentElement.appendChild(root);
-                }, boxes);
-            }
-            // Take screenshot
-            const screenshot = await page.screenshot({ type: "png" });
-            // Save to temp file
-            const fs = await import("fs/promises");
-            const path = await import("path");
-            const tmpDir = await import("os").then((os) => os.tmpdir());
-            const filename = `browser-snapshot-${Date.now()}.png`;
-            imagePath = path.join(tmpDir, filename);
-            await fs.writeFile(imagePath, screenshot);
-        }
-        finally {
-            // Clean up labels
-            await page.evaluate(() => {
-                const existing = document.querySelectorAll("[data-browser-labels]");
-                existing.forEach((el) => el.remove());
-            }).catch(() => { });
-        }
+        const { buffer, labels: labelCount, skipped } = await screenshotWithLabelsViaPlaywright({
+            cdpUrl,
+            targetId,
+            refs: refsMap,
+            maxLabels: 150,
+            type: "png",
+        });
+        labelsCount = labelCount;
+        console.log(`[BROWSER] Labels screenshot: ${labelCount} labels, ${skipped} skipped`);
+        const fs = await import("fs/promises");
+        const pathMod = await import("path");
+        const tmpDir = await import("os").then((os) => os.tmpdir());
+        const filename = `browser-snapshot-${Date.now()}.png`;
+        imagePath = pathMod.join(tmpDir, filename);
+        await fs.writeFile(imagePath, buffer);
     }
-    // Step 5: Build final snapshot text
+    // Build final snapshot text
+    const page = await getPageForTargetId({ cdpUrl, targetId });
     const title = await page.title().catch(() => "");
     const url = page.url();
     let snapshot = `# ${title}\n\nURL: ${url}\n\n`;
-    if (roleSnapshot && roleSnapshot !== "(empty)") {
+    if (snapshotResult.snapshot && snapshotResult.snapshot !== "(empty)") {
         snapshot += "## Accessibility Tree\n";
-        snapshot += roleSnapshot;
+        snapshot += snapshotResult.snapshot;
         snapshot += "\n\n";
     }
-    // Truncate if needed
     if (snapshot.length > maxChars) {
         snapshot = snapshot.slice(0, maxChars) + "\n\n... (content truncated)";
     }
-    return {
-        snapshot,
-        imagePath,
-        labelsCount,
-        refs: Object.keys(refsMap).length > 0 ? refsMap : undefined,
-        targetId,
-    };
+    return { snapshot, imagePath, labelsCount, refs: Object.keys(refsMap).length > 0 ? refsMap : undefined, targetId };
 }
-/**
- * Resolve a ref to a Playwright locator (OpenClaw-style)
- * Uses stored role+name info instead of DOM attributes for stability across navigation
- */
-/**
- * Normalize timeout to safe range (OpenClaw-style exact copy)
- * From: pw-tools-core.shared.ts - uses 120s max instead of 60s
- */
-function normalizeTimeoutMs(timeoutMs, fallback) {
-    return Math.max(500, Math.min(120_000, timeoutMs ?? fallback));
-}
-/**
- * Resolve ref to locator (OpenClaw-style)
- * Reads from page's WeakMap state (restoreRoleRefsForTarget must be called first)
- */
-function refLocator(page, ref) {
-    // Normalize ref (remove @ or ref= prefix if present) - OpenClaw style
-    const normalized = ref.startsWith("@")
-        ? ref.slice(1)
-        : ref.startsWith("ref=")
-            ? ref.slice(4)
-            : ref;
-    // Check if it's an element ref (e1, e2, etc.)
-    if (/^e\d+$/.test(normalized)) {
-        // Read from page's WeakMap state (OpenClaw-style)
-        const pageState = pageStates.get(page);
-        // Handle aria mode - refs are self-resolving via aria-ref= syntax
-        if (pageState?.roleRefsMode === "aria") {
-            const scope = pageState.roleRefsFrameSelector
-                ? page.frameLocator(pageState.roleRefsFrameSelector)
-                : page;
-            return scope.locator(`aria-ref=${normalized}`);
-        }
-        // Role mode: Get ref info from page state
-        const info = pageState?.roleRefs?.[normalized];
-        if (!info) {
-            throw new Error(`Element "${normalized}" not found or not visible. ` +
-                `Run a new snapshot to see current page elements.`);
-        }
-        // Build locator using getByRole (OpenClaw-style)
-        const scope = pageState?.roleRefsFrameSelector
-            ? page.frameLocator(pageState.roleRefsFrameSelector)
-            : page;
-        const locAny = scope;
-        const locator = info.name
-            ? locAny.getByRole(info.role, { name: info.name, exact: true })
-            : locAny.getByRole(info.role);
-        return info.nth !== undefined ? locator.nth(info.nth) : locator;
-    }
-    // Not an element ref - treat as aria-ref (OpenClaw-style)
-    return page.locator(`aria-ref=${normalized}`);
-}
-/**
- * Transform Playwright errors into AI-friendly messages (OpenClaw-style exact copy)
- * From: pw-tools-core.shared.ts
- */
-function toAIFriendlyError(error, selector) {
-    const message = error instanceof Error ? error.message : String(error);
-    // Multiple elements matched
-    if (message.includes("strict mode violation")) {
-        const countMatch = message.match(/resolved to (\d+) elements/);
-        const count = countMatch ? countMatch[1] : "multiple";
-        return new Error(`Selector "${selector}" matched ${count} elements. ` +
-            `Run a new snapshot to get updated refs, or use a different ref.`);
-    }
-    // Element not found or not visible
-    if ((message.includes("Timeout") || message.includes("waiting for")) &&
-        (message.includes("to be visible") || message.includes("not visible"))) {
-        return new Error(`Element "${selector}" not found or not visible. ` +
-            `Run a new snapshot to see current page elements.`);
-    }
-    // Element covered by overlay or not interactable (OpenClaw exact)
-    if (message.includes("intercepts pointer events") ||
-        message.includes("not visible") ||
-        message.includes("not receive pointer events")) {
-        return new Error(`Element "${selector}" is not interactable (hidden or covered). ` +
-            `Try scrolling it into view, closing overlays, or re-snapshotting.`);
-    }
-    return error instanceof Error ? error : new Error(message);
-}
-/**
- * Execute browser automation action (act)
- */
-async function executeBrowserAct(page, request, targetId = "default") {
+// ─── Act dispatcher (OpenClaw cdpUrl pattern) ───────────────────────
+async function executeBrowserAct(cdpUrl, request, targetId) {
     const kind = request.kind;
-    // OpenClaw-style: Restore refs for this target before any action
-    restoreRoleRefsForTarget(page, targetId);
     switch (kind) {
         case "click": {
-            const ref = request.ref;
-            const doubleClick = request.doubleClick;
-            const button = request.button || "left";
-            const modifiers = request.modifiers || [];
-            const force = request.force;
-            // OpenClaw uses normalizeTimeoutMs with 8000ms default
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 8000);
-            if (!ref)
-                throw new Error("ref is required for click action");
-            const locator = refLocator(page, ref);
-            try {
-                if (doubleClick) {
-                    await locator.dblclick({
-                        timeout,
-                        button: button,
-                        modifiers: modifiers,
-                        force: force ?? false,
-                    });
-                }
-                else {
-                    await locator.click({
-                        timeout,
-                        button: button,
-                        modifiers: modifiers,
-                        force: force ?? false,
-                    });
-                }
-            }
-            catch (err) {
-                throw toAIFriendlyError(err, ref);
-            }
+            await clickViaPlaywright({
+                cdpUrl, targetId,
+                ref: request.ref,
+                doubleClick: request.doubleClick,
+                button: request.button || "left",
+                modifiers: request.modifiers,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "type": {
-            const ref = request.ref;
-            const text = String(request.text ?? "");
-            const submit = request.submit;
-            const slowly = request.slowly;
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 8000);
-            if (!ref)
-                throw new Error("ref is required for type action");
-            const locator = refLocator(page, ref);
-            try {
-                // OpenClaw: slowly mode clicks first, then types with delay
-                if (slowly) {
-                    await locator.click({ timeout });
-                    await locator.type(text, { timeout, delay: 75 });
-                }
-                else {
-                    await locator.fill(text, { timeout });
-                }
-                if (submit) {
-                    await locator.press("Enter", { timeout });
-                }
-            }
-            catch (err) {
-                throw toAIFriendlyError(err, ref);
-            }
+            await typeViaPlaywright({
+                cdpUrl, targetId,
+                ref: request.ref,
+                text: String(request.text ?? ""),
+                submit: request.submit,
+                slowly: request.slowly,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "press": {
-            const key = String(request.key ?? "").trim();
-            if (!key)
-                throw new Error("key is required for press action");
-            const delayMs = Math.max(0, Math.floor(request.delayMs ?? 0));
-            await page.keyboard.press(key, { delay: delayMs });
+            await pressKeyViaPlaywright({
+                cdpUrl, targetId,
+                key: String(request.key ?? ""),
+                delayMs: request.delayMs,
+            });
             return { ok: true };
         }
         case "hover": {
-            const ref = request.ref;
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 8000);
-            if (!ref)
-                throw new Error("ref is required for hover action");
-            const locator = refLocator(page, ref);
-            try {
-                await locator.hover({ timeout });
-            }
-            catch (err) {
-                throw toAIFriendlyError(err, ref);
-            }
+            await hoverViaPlaywright({
+                cdpUrl, targetId,
+                ref: request.ref,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "drag": {
-            const startRef = request.startRef;
-            const endRef = request.endRef;
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 8000);
-            if (!startRef)
-                throw new Error("startRef is required for drag action");
-            if (!endRef)
-                throw new Error("endRef is required for drag action");
-            const startLocator = refLocator(page, startRef);
-            const endLocator = refLocator(page, endRef);
-            try {
-                // OpenClaw uses dragTo() method
-                await startLocator.dragTo(endLocator, { timeout });
-            }
-            catch (err) {
-                throw toAIFriendlyError(err, `${startRef} -> ${endRef}`);
-            }
+            await dragViaPlaywright({
+                cdpUrl, targetId,
+                startRef: request.startRef,
+                endRef: request.endRef,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "select": {
-            const ref = request.ref;
-            const values = request.values;
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 8000);
-            if (!ref)
-                throw new Error("ref is required for select action");
-            if (!values || !Array.isArray(values))
-                throw new Error("values array is required for select action");
-            const locator = refLocator(page, ref);
-            try {
-                await locator.selectOption(values, { timeout });
-            }
-            catch (err) {
-                throw toAIFriendlyError(err, ref);
-            }
+            await selectOptionViaPlaywright({
+                cdpUrl, targetId,
+                ref: request.ref,
+                values: request.values,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "fill": {
-            // OpenClaw-style form filling with checkbox/radio support
             const fields = request.fields;
             if (!fields || !Array.isArray(fields))
                 throw new Error("fields array is required for fill action");
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 8000);
-            for (const field of fields) {
-                const ref = String(field.ref ?? "").trim();
-                const type = String(field.type ?? "").trim();
-                const rawValue = field.value;
-                const value = typeof rawValue === "string"
-                    ? rawValue
-                    : typeof rawValue === "number" || typeof rawValue === "boolean"
-                        ? String(rawValue)
-                        : "";
-                if (!ref)
-                    continue;
-                const locator = refLocator(page, ref);
-                try {
-                    // OpenClaw: handle checkbox/radio with setChecked
-                    if (type === "checkbox" || type === "radio") {
-                        const checked = rawValue === true || rawValue === 1 || rawValue === "1" || rawValue === "true";
-                        await locator.setChecked(checked, { timeout });
-                        continue;
-                    }
-                    await locator.fill(value, { timeout });
-                }
-                catch (err) {
-                    throw toAIFriendlyError(err, ref);
-                }
-            }
+            await fillFormViaPlaywright({
+                cdpUrl, targetId,
+                fields: fields.map(f => ({
+                    ref: String(f.ref ?? ""),
+                    type: String(f.type ?? ""),
+                    value: f.value,
+                })),
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "resize": {
-            const width = request.width;
-            const height = request.height;
-            await page.setViewportSize({ width, height });
+            await resizeViewportViaPlaywright({
+                cdpUrl, targetId,
+                width: request.width,
+                height: request.height,
+            });
             return { ok: true };
         }
         case "wait": {
-            const timeMs = request.timeMs;
-            const text = request.text;
-            const textGone = request.textGone;
-            const selector = request.selector;
-            const url = request.url;
-            const loadState = request.loadState;
-            const fn = request.fn;
-            // OpenClaw uses 20000ms default for wait (normalizeTimeoutMs uses 120s max)
-            const timeout = normalizeTimeoutMs(request.timeoutMs, 20000);
-            if (typeof timeMs === "number" && Number.isFinite(timeMs)) {
-                // Wait for specific time
-                await page.waitForTimeout(Math.max(0, timeMs));
-            }
-            if (text) {
-                // Wait for text to appear (OpenClaw uses getByText, not waitForSelector)
-                await page.getByText(text).first().waitFor({ state: "visible", timeout });
-            }
-            if (textGone) {
-                // Wait for text to disappear
-                await page.getByText(textGone).first().waitFor({ state: "hidden", timeout });
-            }
-            if (selector) {
-                // Wait for selector
-                const sel = String(selector).trim();
-                if (sel) {
-                    await page.locator(sel).first().waitFor({ state: "visible", timeout });
-                }
-            }
-            if (url) {
-                // Wait for URL pattern
-                const urlPattern = String(url).trim();
-                if (urlPattern) {
-                    await page.waitForURL(urlPattern, { timeout });
-                }
-            }
-            if (fn) {
-                // Wait for JavaScript function to return true
-                const fnStr = String(fn).trim();
-                if (fnStr) {
-                    await page.waitForFunction(fnStr, { timeout });
-                }
-            }
-            if (loadState) {
-                // Wait for specific load state
-                await page.waitForLoadState(loadState, { timeout });
-            }
+            await waitForViaPlaywright({
+                cdpUrl, targetId,
+                timeMs: request.timeMs,
+                text: request.text,
+                textGone: request.textGone,
+                selector: request.selector,
+                url: request.url,
+                loadState: request.loadState,
+                fn: request.fn,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true };
         }
         case "evaluate": {
-            // OpenClaw-style evaluate using Function constructor
-            // This avoids esbuild adding __name helper which doesn't exist in browser
-            const fnText = String(request.fn ?? "").trim();
-            const ref = request.ref;
-            if (!fnText)
-                throw new Error("fn is required for evaluate action");
-            if (ref) {
-                // Evaluate with element context
-                const locator = refLocator(page, ref);
-                // eslint-disable-next-line @typescript-eslint/no-implied-eval
-                const elementEvaluator = new Function("el", "fnBody", `
-          "use strict";
-          try {
-            var candidate = eval("(" + fnBody + ")");
-            return typeof candidate === "function" ? candidate(el) : candidate;
-          } catch (err) {
-            throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
-          }
-          `);
-                const result = await locator.evaluate(elementEvaluator, fnText);
-                return { ok: true, result };
-            }
-            // Evaluate in page context (no element)
-            // eslint-disable-next-line @typescript-eslint/no-implied-eval
-            const browserEvaluator = new Function("fnBody", `
-        "use strict";
-        try {
-          var candidate = eval("(" + fnBody + ")");
-          return typeof candidate === "function" ? candidate() : candidate;
-        } catch (err) {
-          throw new Error("Invalid evaluate function: " + (err && err.message ? err.message : String(err)));
-        }
-        `);
-            const result = await page.evaluate(browserEvaluator, fnText);
+            const result = await evaluateViaPlaywright({
+                cdpUrl, targetId,
+                fn: String(request.fn ?? ""),
+                ref: request.ref,
+                timeoutMs: request.timeoutMs,
+            });
             return { ok: true, result };
         }
         case "close": {
-            await page.close();
+            if (!targetId)
+                throw new Error("targetId is required for close action");
+            await closePageByTargetIdViaPlaywright({ cdpUrl, targetId });
             return { ok: true };
         }
         default:
             throw new Error(`Unknown act kind: ${kind}`);
     }
 }
-/**
- * Create image result from file (base64 encoded)
- */
+// ─── Image result helper ────────────────────────────────────────────
 async function imageResultFromFile(options) {
     const fs = await import("fs/promises");
     const buffer = await fs.readFile(options.path);
     const base64 = buffer.toString("base64");
     const content = [];
     if (options.extraText) {
-        content.push({
-            type: "text",
-            text: options.extraText,
-        });
+        content.push({ type: "text", text: options.extraText });
     }
-    content.push({
-        type: "image",
-        data: base64,
-        mimeType: "image/png",
-    });
-    return {
-        content,
-        details: options.details,
-    };
+    content.push({ type: "image", data: base64, mimeType: "image/png" });
+    return { content, details: options.details };
 }
+// ─── Tool export ────────────────────────────────────────────────────
 export function createBrowserTool() {
     return {
         name: "browser",
         label: "Browser",
-        // OpenClaw exact description (from browser-tool.ts)
         description: [
             "Control the browser via Playwright (status/start/stop/profiles/tabs/open/snapshot/screenshot/actions).",
             "When using refs from snapshot (e.g. e12), keep the same tab: prefer passing targetId from the snapshot response into subsequent actions (act/click/type/etc).",
@@ -1184,446 +393,238 @@ export function createBrowserTool() {
                     case "status":
                         return jsonResult({
                             running: state.running,
-                            connectionMode: state.connectionMode,
-                            wsEndpoint: state.wsEndpoint,
-                            tabCount: state.pages.size,
-                            tabs: Array.from(state.pages.keys()),
+                            cdpUrl: state.cdpUrl,
+                            mode: state.mode,
+                            pid: state.chromeProcess?.pid,
+                            sandbox: state.sandboxState ? {
+                                containerId: state.sandboxState.containerId,
+                                containerName: state.sandboxState.containerName,
+                                vncUrl: state.sandboxState.vncUrl,
+                            } : undefined,
                         });
                     case "start": {
                         const headless = readBooleanParam(params, "headless");
-                        const profilePath = readStringParam(params, "profilePath");
-                        await startBrowser({
-                            headless: headless ?? undefined,
-                            profilePath: profilePath ?? undefined,
-                        });
+                        await startBrowser({ headless: headless ?? undefined });
                         return jsonResult({
                             running: state.running,
-                            connectionMode: state.connectionMode,
-                            message: profilePath
-                                ? `Browser started with profile: ${profilePath}`
-                                : "Browser started successfully",
+                            cdpUrl: state.cdpUrl,
+                            mode: state.mode,
+                            pid: state.chromeProcess?.pid,
+                            vncUrl: state.sandboxState?.vncUrl ?? null,
+                            message: "Browser started",
                         });
                     }
-                    case "stop":
+                    case "stop": {
+                        const wasMode = state.mode;
                         await stopBrowser();
-                        return jsonResult({
-                            running: state.running,
-                            message: state.connectionMode === "connected"
-                                ? "Disconnected from browser"
-                                : "Browser stopped successfully",
-                        });
-                    case "profiles": {
-                        // OpenClaw has profiles - we just return a simple response
-                        return jsonResult({
-                            profiles: ["default"],
-                            message: "Single default profile available",
-                        });
+                        return jsonResult({ running: false, mode: wasMode, message: "Browser stopped" });
                     }
+                    case "profiles":
+                        return jsonResult({ profiles: ["costar"], message: "Single profile available" });
                     case "tabs": {
-                        if (!state.running || state.pages.size === 0) {
-                            return jsonResult({ tabs: [], message: "No tabs open" });
-                        }
-                        const tabs = await Promise.all(Array.from(state.pages.entries()).map(async ([id, page]) => {
-                            try {
-                                return {
-                                    targetId: id,
-                                    title: await page.title(),
-                                    url: page.url(),
-                                };
-                            }
-                            catch (err) {
-                                return {
-                                    targetId: id,
-                                    title: "(error)",
-                                    url: "(error)",
-                                    error: String(err),
-                                };
-                            }
+                        const cdpUrl = requireRunning();
+                        const pages = await listPagesViaPlaywright({ cdpUrl });
+                        const tabs = pages.map((p) => ({
+                            targetId: p.targetId,
+                            title: p.title,
+                            url: p.url,
                         }));
                         return jsonResult({ tabs });
                     }
                     case "open": {
+                        if (!state.running)
+                            await startBrowser();
+                        const cdpUrl = requireRunning();
                         const targetUrl = readStringParam(params, "targetUrl", { required: true });
-                        const { targetId: newTargetId, page } = await openPage(targetUrl);
+                        const result = await createPageViaPlaywright({ cdpUrl, url: targetUrl });
+                        state.lastActiveTargetId = result.targetId;
                         return jsonResult({
-                            targetId: newTargetId,
-                            url: page.url(),
-                            title: await page.title(),
-                            message: `Opened ${targetUrl} in new tab`,
+                            targetId: result.targetId,
+                            url: result.url,
+                            title: result.title,
+                            message: `Opened ${targetUrl}`,
                         });
                     }
                     case "focus": {
-                        const targetId = readStringParam(params, "targetId", { required: true });
-                        const page = state.pages.get(targetId);
-                        if (!page) {
-                            throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                        }
-                        await page.bringToFront();
-                        return jsonResult({
-                            ok: true,
-                            targetId,
-                            message: `Focused tab ${targetId}`,
-                        });
+                        const cdpUrl = requireRunning();
+                        const targetId = readStringParam(params, "targetId");
+                        if (!targetId)
+                            throw new Error("targetId is required for focus action");
+                        await focusPageByTargetIdViaPlaywright({ cdpUrl, targetId });
+                        return jsonResult({ ok: true, message: "Focused tab" });
                     }
                     case "navigate": {
+                        const cdpUrl = requireRunning();
                         const targetUrl = readStringParam(params, "targetUrl", { required: true });
-                        const targetId = readStringParam(params, "targetId");
-                        let page;
-                        let usedTargetId;
-                        if (targetId) {
-                            const existingPage = state.pages.get(targetId);
-                            if (!existingPage) {
-                                throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs or use action=open to create a new tab.`);
-                            }
-                            page = existingPage;
-                            usedTargetId = targetId;
-                        }
-                        else {
-                            // Use first page or create new one
-                            if (state.pages.size > 0) {
-                                const firstEntry = Array.from(state.pages.entries())[0];
-                                page = firstEntry[1];
-                                usedTargetId = firstEntry[0];
-                            }
-                            else {
-                                const result = await openPage(targetUrl);
-                                return jsonResult({
-                                    targetId: result.targetId,
-                                    url: result.page.url(),
-                                    title: await result.page.title(),
-                                    message: `Created new tab and navigated to ${targetUrl}`,
-                                });
-                            }
-                        }
-                        await page.goto(targetUrl, { waitUntil: "domcontentloaded", timeout: 30000 });
+                        const targetId = resolveTargetId(params);
+                        const result = await navigateViaPlaywright({ cdpUrl, targetId, url: targetUrl });
+                        const page = await getPageForTargetId({ cdpUrl, targetId });
                         return jsonResult({
-                            targetId: usedTargetId,
-                            url: page.url(),
+                            targetId,
+                            url: result.url,
                             title: await page.title(),
                             message: `Navigated to ${targetUrl}`,
                         });
                     }
                     case "snapshot": {
-                        if (!state.running || state.pages.size === 0) {
-                            throw new Error("No tabs open. Use action=open to open a URL first.");
-                        }
-                        const targetId = readStringParam(params, "targetId");
+                        const cdpUrl = requireRunning();
+                        const targetId = resolveTargetId(params);
                         const maxChars = readNumberParam(params, "maxChars") || 50000;
                         const labels = readBooleanParam(params, "labels", false);
                         const refs = (readStringParam(params, "refs") || "role");
                         const selector = readStringParam(params, "selector");
                         const frame = readStringParam(params, "frame");
                         const interactive = readBooleanParam(params, "interactive", false);
-                        // Use helper to get page and track last active
-                        const { page, usedTargetId } = getPageForAction(targetId ?? undefined);
-                        // OpenClaw-style: Only generate screenshot if labels explicitly requested
-                        const snapshotResult = await getAISnapshot(page, usedTargetId, {
-                            maxChars,
-                            labels, // Only generate screenshot when explicitly requested
-                            refs,
-                            selector,
-                            frame,
+                        const snapshotResult = await getAISnapshot(cdpUrl, targetId, {
+                            maxChars, labels, refs,
+                            selector: selector ?? undefined,
+                            frame: frame ?? undefined,
                             interactive,
                         });
-                        // If labels requested, return image with text
                         if (labels && snapshotResult.imagePath) {
+                            const page = await getPageForTargetId({ cdpUrl, targetId });
                             return await imageResultFromFile({
                                 path: snapshotResult.imagePath,
                                 extraText: snapshotResult.snapshot,
                                 details: {
-                                    targetId: usedTargetId,
+                                    targetId,
                                     url: page.url(),
                                     title: await page.title(),
                                     format: "ai",
                                     labels: true,
                                     labelsCount: snapshotResult.labelsCount,
                                     refs: snapshotResult.refs,
-                                    contentLength: snapshotResult.snapshot.length,
-                                    truncated: snapshotResult.snapshot.includes("(content truncated"),
                                 },
                             });
                         }
-                        // Default: Return tree only (no screenshot)
+                        const page = await getPageForTargetId({ cdpUrl, targetId });
                         return {
-                            content: [
-                                {
-                                    type: "text",
-                                    text: snapshotResult.snapshot,
-                                },
-                            ],
+                            content: [{ type: "text", text: snapshotResult.snapshot }],
                             details: {
-                                targetId: usedTargetId,
+                                targetId,
                                 url: page.url(),
                                 title: await page.title(),
                                 format: "ai",
                                 refs: snapshotResult.refs,
-                                contentLength: snapshotResult.snapshot.length,
-                                truncated: snapshotResult.snapshot.includes("(content truncated"),
                             },
                         };
                     }
                     case "screenshot": {
-                        if (!state.running || state.pages.size === 0) {
-                            throw new Error("No tabs open. Use action=open to open a URL first.");
-                        }
-                        const targetId = readStringParam(params, "targetId");
+                        const cdpUrl = requireRunning();
+                        const targetId = resolveTargetId(params);
                         const fullPage = readBooleanParam(params, "fullPage", false);
-                        let page;
-                        let usedTargetId;
-                        if (targetId) {
-                            const existingPage = state.pages.get(targetId);
-                            if (!existingPage) {
-                                throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                            }
-                            page = existingPage;
-                            usedTargetId = targetId;
-                        }
-                        else {
-                            const firstEntry = Array.from(state.pages.entries())[0];
-                            page = firstEntry[1];
-                            usedTargetId = firstEntry[0];
-                        }
-                        const screenshot = await page.screenshot({
-                            fullPage,
-                            type: "png",
+                        const ref = readStringParam(params, "ref");
+                        const element = readStringParam(params, "element");
+                        const screenshotType = (readStringParam(params, "type") || "png");
+                        const { buffer } = await takeScreenshotViaPlaywright({
+                            cdpUrl, targetId,
+                            ref: ref ?? undefined,
+                            element: element ?? undefined,
+                            fullPage, type: screenshotType,
                         });
-                        // Save screenshot to temp file
                         const fs = await import("fs/promises");
-                        const path = await import("path");
+                        const pathMod = await import("path");
                         const tmpDir = await import("os").then((os) => os.tmpdir());
-                        const filename = `browser-screenshot-${Date.now()}.png`;
-                        const filepath = path.join(tmpDir, filename);
-                        await fs.writeFile(filepath, screenshot);
+                        const filename = `browser-screenshot-${Date.now()}.${screenshotType}`;
+                        const filepath = pathMod.join(tmpDir, filename);
+                        await fs.writeFile(filepath, buffer);
+                        const page = await getPageForTargetId({ cdpUrl, targetId });
                         return await imageResultFromFile({
                             path: filepath,
-                            details: {
-                                targetId: usedTargetId,
-                                url: page.url(),
-                                title: await page.title(),
-                                path: filepath,
-                                fullPage,
-                            },
+                            details: { targetId, url: page.url(), path: filepath, fullPage },
                         });
                     }
                     case "console": {
-                        const targetId = readStringParam(params, "targetId");
+                        const cdpUrl = requireRunning();
+                        const targetId = resolveTargetId(params);
                         const level = readStringParam(params, "level");
-                        let usedTargetId;
-                        let messages;
-                        if (targetId) {
-                            if (!state.consoleLogs.has(targetId)) {
-                                throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                            }
-                            messages = state.consoleLogs.get(targetId);
-                            usedTargetId = targetId;
-                        }
-                        else {
-                            if (state.pages.size === 0) {
-                                throw new Error("No tabs open. Use action=open to open a URL first.");
-                            }
-                            const firstId = Array.from(state.pages.keys())[0];
-                            messages = state.consoleLogs.get(firstId) || [];
-                            usedTargetId = firstId;
-                        }
-                        // Filter by level if specified
-                        if (level) {
-                            messages = messages.filter((msg) => msg.type() === level);
-                        }
-                        const formattedMessages = messages.map((msg) => ({
-                            type: msg.type(),
-                            text: msg.text(),
-                            location: msg.location(),
-                        }));
+                        const page = await getPageForTargetId({ cdpUrl, targetId });
+                        const pageState = ensurePageState(page);
+                        let messages = pageState.console ?? [];
+                        if (level)
+                            messages = messages.filter((msg) => msg.type === level);
                         return jsonResult({
                             ok: true,
-                            targetId: usedTargetId,
-                            messages: formattedMessages,
+                            messages: messages.map((msg) => ({
+                                type: msg.type,
+                                text: msg.text,
+                                location: msg.location,
+                            })),
                         });
                     }
                     case "pdf": {
-                        const targetId = readStringParam(params, "targetId");
-                        let page;
-                        let usedTargetId;
-                        if (targetId) {
-                            const existingPage = state.pages.get(targetId);
-                            if (!existingPage) {
-                                throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                            }
-                            page = existingPage;
-                            usedTargetId = targetId;
-                        }
-                        else {
-                            if (state.pages.size === 0) {
-                                throw new Error("No tabs open. Use action=open to open a URL first.");
-                            }
-                            const firstEntry = Array.from(state.pages.entries())[0];
-                            page = firstEntry[1];
-                            usedTargetId = firstEntry[0];
-                        }
-                        const path = await import("path");
+                        const cdpUrl = requireRunning();
+                        const targetId = resolveTargetId(params);
+                        const { buffer } = await pdfViaPlaywright({ cdpUrl, targetId });
+                        const pathMod = await import("path");
+                        const fs = await import("fs/promises");
                         const tmpDir = await import("os").then((os) => os.tmpdir());
                         const filename = `browser-pdf-${Date.now()}.pdf`;
-                        const filepath = path.join(tmpDir, filename);
-                        await page.pdf({
-                            path: filepath,
-                            format: "A4",
-                        });
-                        return {
-                            content: [
-                                {
-                                    type: "text",
-                                    text: `PDF saved to ${filepath}`,
-                                },
-                            ],
-                            details: {
-                                ok: true,
-                                targetId: usedTargetId,
-                                path: filepath,
-                            },
-                        };
+                        const filepath = pathMod.join(tmpDir, filename);
+                        await fs.writeFile(filepath, buffer);
+                        return { content: [{ type: "text", text: `PDF saved to ${filepath}` }], details: { ok: true, path: filepath } };
                     }
                     case "upload": {
+                        const cdpUrl = requireRunning();
+                        const targetId = resolveTargetId(params);
                         const paths = readArrayParam(params, "paths", { required: true });
-                        const targetId = readStringParam(params, "targetId");
                         const timeoutMs = readNumberParam(params, "timeoutMs") || 30000;
-                        let page;
-                        let usedTargetId;
-                        if (targetId) {
-                            const existingPage = state.pages.get(targetId);
-                            if (!existingPage) {
-                                throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                            }
-                            page = existingPage;
-                            usedTargetId = targetId;
-                        }
-                        else {
-                            if (state.pages.size === 0) {
-                                throw new Error("No tabs open. Use action=open to open a URL first.");
-                            }
-                            const firstEntry = Array.from(state.pages.entries())[0];
-                            page = firstEntry[1];
-                            usedTargetId = firstEntry[0];
-                        }
-                        // Set up file chooser handler
-                        const fileChooserPromise = page.waitForEvent("filechooser", { timeout: timeoutMs });
-                        // Wait for file chooser to appear (user must trigger it)
-                        const fileChooser = await fileChooserPromise;
-                        await fileChooser.setFiles(paths);
-                        return jsonResult({
-                            ok: true,
-                            targetId: usedTargetId,
-                            filesUploaded: paths.length,
-                            message: `File chooser armed and files uploaded: ${paths.join(", ")}`,
-                        });
+                        await armFileUploadViaPlaywright({ cdpUrl, targetId, paths, timeoutMs });
+                        return jsonResult({ ok: true, filesUploaded: paths.length, message: `Upload armed: ${paths.join(", ")}` });
                     }
                     case "dialog": {
+                        const cdpUrl = requireRunning();
+                        const targetId = resolveTargetId(params);
                         const accept = readBooleanParam(params, "accept", true);
                         const promptText = readStringParam(params, "promptText");
-                        const targetId = readStringParam(params, "targetId");
                         const timeoutMs = readNumberParam(params, "timeoutMs") || 30000;
-                        let page;
-                        let usedTargetId;
-                        if (targetId) {
-                            const existingPage = state.pages.get(targetId);
-                            if (!existingPage) {
-                                throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                            }
-                            page = existingPage;
-                            usedTargetId = targetId;
-                        }
-                        else {
-                            if (state.pages.size === 0) {
-                                throw new Error("No tabs open. Use action=open to open a URL first.");
-                            }
-                            const firstEntry = Array.from(state.pages.entries())[0];
-                            page = firstEntry[1];
-                            usedTargetId = firstEntry[0];
-                        }
-                        // Set up dialog handler
-                        const dialogPromise = page.waitForEvent("dialog", { timeout: timeoutMs });
-                        // Wait for dialog to appear
-                        const dialog = await dialogPromise;
-                        if (accept) {
-                            await dialog.accept(promptText);
-                        }
-                        else {
-                            await dialog.dismiss();
-                        }
-                        return jsonResult({
-                            ok: true,
-                            targetId: usedTargetId,
-                            dialogType: dialog.type(),
-                            dialogMessage: dialog.message(),
-                            accepted: accept,
-                        });
+                        await armDialogViaPlaywright({ cdpUrl, targetId, accept, promptText: promptText ?? undefined, timeoutMs });
+                        return jsonResult({ ok: true, message: `Dialog handler armed (accept: ${accept})` });
                     }
                     case "close": {
+                        const cdpUrl = requireRunning();
                         const targetId = readStringParam(params, "targetId");
-                        if (!targetId) {
-                            throw new Error("targetId is required for close action. Run action=tabs to see available targetIds.");
-                        }
-                        const page = state.pages.get(targetId);
-                        if (!page) {
-                            throw new Error(`Tab ${targetId} not found. Run action=tabs to see available tabs.`);
-                        }
-                        await page.close();
-                        state.pages.delete(targetId);
-                        state.consoleLogs.delete(targetId);
-                        return jsonResult({
-                            targetId,
-                            message: `Closed tab ${targetId}`,
-                            remainingTabs: state.pages.size,
-                        });
+                        if (!targetId)
+                            throw new Error("targetId is required for close action");
+                        await closePageByTargetIdViaPlaywright({ cdpUrl, targetId });
+                        return jsonResult({ ok: true, message: "Closed tab" });
                     }
                     case "act": {
-                        // Support both OpenClaw-style (request object) and direct parameters
+                        const cdpUrl = requireRunning();
                         const request = params.request;
                         const actParams = request || params;
-                        // Check if we have act parameters (either kind or any act-specific param)
                         if (!actParams.kind && !actParams.ref && !actParams.text && !actParams.key) {
-                            throw new Error("act action requires 'kind' parameter or use 'request' object with act parameters");
+                            throw new Error("act requires 'kind' parameter");
                         }
-                        const targetId = readStringParam(actParams, "targetId");
-                        // Use helper to get page and track last active
-                        const { page, usedTargetId } = getPageForAction(targetId ?? undefined);
-                        const result = await executeBrowserAct(page, actParams, usedTargetId);
-                        return jsonResult({
-                            ok: result.ok,
-                            targetId: usedTargetId,
-                            url: page.url(),
-                            result: result.result,
-                        });
+                        const targetId = resolveTargetId(actParams);
+                        const result = await executeBrowserAct(cdpUrl, actParams, targetId);
+                        const page = await getPageForTargetId({ cdpUrl, targetId });
+                        return jsonResult({ ok: result.ok, targetId, url: page.url(), result: result.result });
                     }
                     default:
-                        throw new Error(`Unknown action: ${action}. Valid actions: ${BROWSER_TOOL_ACTIONS.join(", ")}`);
+                        throw new Error(`Unknown action: ${action}. Valid: ${BROWSER_TOOL_ACTIONS.join(", ")}`);
                 }
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                console.error(`[BROWSER] Error in action ${action}:`, message);
-                // Return structured error
+                console.error(`[BROWSER] Error in ${action}:`, message);
                 return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Browser error in action "${action}": ${message}`,
-                        },
-                    ],
-                    details: {
-                        error: "browser_error",
-                        action,
-                        message,
-                    },
+                    content: [{ type: "text", text: `Browser error in "${action}": ${message}` }],
+                    details: { error: "browser_error", action, message },
                 };
             }
         },
     };
 }
+// ─── Public getters (for REST API) ───────────────────────────────
+/** Returns the sandbox VNC URL if the browser is running in sandbox mode, else null. */
+export function getBrowserVncUrl() {
+    if (state.running && state.mode === "sandbox" && state.sandboxState?.vncUrl) {
+        return state.sandboxState.vncUrl;
+    }
+    return null;
+}
 // Cleanup on process exit
-process.on("SIGINT", async () => {
-    await stopBrowser();
-});
-process.on("SIGTERM", async () => {
-    await stopBrowser();
-});
+process.on("SIGINT", async () => { await stopBrowser(); });
+process.on("SIGTERM", async () => { await stopBrowser(); });
 //# sourceMappingURL=browser.js.map