@melaya/runner 1.1.9 → 1.1.12

package/dist/browserBridge.d.ts

@@ -90,6 +90,33 @@ export interface BrowserBridge {
      * grant-scoped run sessions (byRunId).
      */
     killInteractive(sessionId?: string): Promise<string[]>;
+    /**
+     * Set or clear the takeover pause flag (Fix 3).
+     *
+     * Called by the connection layer when the server emits a
+     * `browser:takeover { sessionId?, paused }` socket event.
+     *
+     * While paused, `performAct` blocks all consequential act kinds
+     * (navigate, click, tap, input_text, press_key, scroll,
+     * select_option, upload_file, submit, back, forward, batch,
+     * ask_user) and returns a `BridgeError("paused_by_user", ...)` so
+     * the agent stops trying and waits. Read-only ops (get_screen_tree,
+     * screenshot, get_text, current_target, wait,
+     * wait_for_network_idle) are not blocked.
+     *
+     * If sessionId is provided, only that interactive session is paused.
+     * If sessionId is omitted, ALL sessions on this runner are paused.
+     * The flag is cleared on teardownRun / session teardown.
+     */
+    setPaused(paused: boolean, sessionId?: string): void;
+    /**
+     * Switch the active tab for an interactive session to the page identified
+     * by `ref` (the opaque string returned by getTabRef). The frame producer
+     * follows the new active page on its next tick.
+     *
+     * Returns true if the tab was found and switched, false otherwise.
+     */
+    switchTabForSession(sessionId: string, ref: string): boolean;
     shutdown(): Promise<void>;
 }
 export declare function startBrowserBridge(opts: {

package/dist/browserBridge.js

@@ -48,6 +48,9 @@ import { runSandboxedScript } from "./codeWorker.js";
 // Palette: cyan #22D3EE primary accent, indigo #7C6FF0 subtle secondary,
 // slate/navy #0F172A base. Less purple than the prior version.
 const MELAYA_BRAND_SCRIPT = `(() => {
+  // Top document ONLY: injecting into sub-frames (e.g. the Google Sign-In
+  // iframe) rendered a stray badge on top of third-party widgets.
+  try { if (window.top !== window.self) return; } catch (e) { return; }
   if (window.__melayaBrand) return; window.__melayaBrand = true;
   const ID = "__melaya_brand";
   const LOGO = "data:image/png;base64,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";
@@ -56,7 +59,7 @@ const MELAYA_BRAND_SCRIPT = `(() => {
     if (document.getElementById(ID + "_border")) return;
     const style = document.createElement("style");
     style.id = ID + "_style";
-    style.textContent = "@keyframes melBrandPulse{0%,100%{box-shadow:inset 0 0 9px 2px rgba(34,211,238,.5),inset 0 0 30px 7px rgba(124,111,240,.18)}50%{box-shadow:inset 0 0 16px 4px rgba(34,211,238,.8),inset 0 0 54px 13px rgba(124,111,240,.32)}}@keyframes melBrandGlow{0%,100%{opacity:.78}50%{opacity:1}}#" + ID + "_border{position:fixed;inset:0;pointer-events:none;z-index:2147483647;border-radius:7px;animation:melBrandPulse 2.6s ease-in-out infinite}#" + ID + "_badge{position:fixed;top:10px;left:50%;transform:translateX(-50%);pointer-events:none;z-index:2147483647;font:600 12px/1 -apple-system,Segoe UI,Roboto,sans-serif;color:#E2E8F0;background:linear-gradient(180deg,rgba(15,23,42,.94),rgba(15,23,42,.82));padding:5px 13px 5px 7px;border-radius:999px;letter-spacing:.2px;border:1px solid rgba(34,211,238,.45);box-shadow:0 0 16px 1px rgba(34,211,238,.4),0 4px 14px rgba(0,0,0,.45);display:flex;align-items:center;gap:8px;backdrop-filter:blur(6px);animation:melBrandGlow 2.6s ease-in-out infinite}#" + ID + "_logo{height:16px;width:auto;display:block;filter:drop-shadow(0 0 4px rgba(34,211,238,.55))}";
+    style.textContent = "@keyframes melBrandPulse{0%,100%{box-shadow:inset 0 0 9px 2px rgba(34,211,238,.5),inset 0 0 30px 7px rgba(124,111,240,.18)}50%{box-shadow:inset 0 0 16px 4px rgba(34,211,238,.8),inset 0 0 54px 13px rgba(124,111,240,.32)}}@keyframes melBrandGlow{0%,100%{opacity:.78}50%{opacity:1}}#" + ID + "_border{position:fixed;inset:0;pointer-events:none;z-index:2147483647;border-radius:7px;animation:melBrandPulse 2.6s ease-in-out infinite}#" + ID + "_badge{position:fixed;top:10px;left:50%;transform:translateX(-50%);pointer-events:none;z-index:2147483647;font-family:-apple-system,Segoe UI,Roboto,sans-serif;font-weight:600;font-size:12px;line-height:1;white-space:nowrap;max-width:calc(100vw - 24px);box-sizing:border-box;color:#E2E8F0;background:linear-gradient(180deg,rgba(15,23,42,.94),rgba(15,23,42,.82));padding:5px 13px 5px 7px;border-radius:999px;letter-spacing:.2px;border:1px solid rgba(34,211,238,.45);box-shadow:0 0 16px 1px rgba(34,211,238,.4),0 4px 14px rgba(0,0,0,.45);display:flex;align-items:center;gap:8px;backdrop-filter:blur(6px);animation:melBrandGlow 2.6s ease-in-out infinite}#" + ID + "_logo{height:16px;width:auto;display:block;filter:drop-shadow(0 0 4px rgba(34,211,238,.55))}@media (max-width:600px){#" + ID + "_badge{font-size:10px;padding:4px 10px 4px 6px;gap:6px;top:6px}#" + ID + "_logo{height:13px}}";
     (document.head || root).appendChild(style);
     const border = document.createElement("div"); border.id = ID + "_border";
     const badge = document.createElement("div"); badge.id = ID + "_badge";
@@ -96,7 +99,20 @@ const KIND_MIN_EFFECT = {
     click: "read", dblclick: "read", hover: "read", scroll: "read",
     input_text: "read", press_key: "read", select_option: "read",
     wait: "read",
+    // Added kinds (Fix 1 + Fix 2):
+    tap: "read", // coordinate click; same effect ceiling as click
+    get_text: "read", // read-only page text extraction
+    wait_for_network_idle: "read", // read-only network wait
 };
+// Consequential act kinds blocked while the user has taken over the browser.
+// Read-only kinds (get_text, get_screen_tree path, screenshot, wait,
+// wait_for_network_idle) are intentionally excluded so the agent can observe.
+const CONSEQUENTIAL_KINDS = new Set([
+    "navigate", "back", "forward",
+    "click", "dblclick", "hover", "tap",
+    "input_text", "press_key", "scroll", "select_option",
+    "upload_file", "submit", "ask_user", "batch",
+]);
 // ---------------------------------------------------------------------
 // Bridge
 // ---------------------------------------------------------------------
@@ -123,12 +139,32 @@ export async function startBrowserBridge(opts) {
     // Active tab per run: tracks which page is currently active so tab ops
     // and the frame-producer all follow the same page pointer.
     const activePageByRunId = new Map();
+    // The active page for a SESSION (used by the interactive frame producer so the
+    // live mirror follows whichever tab the agent opened/switched to). The agent
+    // drives via a grant-run ATTACHED to the interactive session, so the active
+    // page is tracked under the grant-run's id; resolve it back to the session via
+    // the grant's browserSession claim. Falls back to the newest open tab.
+    function activePageForSession(sessionId) {
+        for (const [runId, pg] of activePageByRunId) {
+            if (pg.isClosed())
+                continue;
+            const r = byRunId.get(runId);
+            if (r && r.spec.grant.browserSession === sessionId)
+                return pg;
+        }
+        return null;
+    }
     // Interactive sessions: launched via launchInteractive(), tracked by the
     // sessionId from the browser:launch socket event. The sessionManager record
     // is stored here as well as in sessions (keyed by sessionId as runId) so
     // getInteractiveSession and setWatchLease can find them without iterating
     // the full grant-scoped run registry.
     const interactiveSessions = new Map();
+    // Takeover pause state (Fix 3).
+    // A sessionId entry means that specific interactive session is paused.
+    // The sentinel key "" means ALL sessions on this runner are paused.
+    // Cleared per-session on teardown, or globally on teardownAll.
+    const pausedSessions = new Set();
     let playwrightMod = null;
     async function pw() {
         if (!playwrightMod)
@@ -729,6 +765,17 @@ export async function startBrowserBridge(opts) {
         }
         throw new BridgeError("act_args_invalid", `kind '${args.kind}' needs a ref or x/y coordinates`);
     }
+    // Returns true if the given run's session is currently paused by a takeover.
+    // The global sentinel "" pauses all sessions; a specific sessionId pauses
+    // only sessions attached to that interactive session.
+    function isActPaused(reg) {
+        if (pausedSessions.has(""))
+            return true;
+        const browserSessionId = String(reg.spec.grant?.browserSession || "");
+        if (browserSessionId && pausedSessions.has(browserSessionId))
+            return true;
+        return false;
+    }
     async function performAct(reg, args) {
         const kind = String(args.kind || "");
         if (!(kind in KIND_MIN_EFFECT)) {
@@ -744,6 +791,13 @@ export async function startBrowserBridge(opts) {
             if (!d.allowed)
                 throw new BridgeError(d.code, d.message);
         }
+        // Takeover pause gate (Fix 3): block consequential acts while the user
+        // has manually taken over the browser. Read-only kinds pass through.
+        if (CONSEQUENTIAL_KINDS.has(kind) && isActPaused(reg)) {
+            throw new BridgeError("paused_by_user", "The user has taken manual control of the browser; agent actions are " +
+                "paused until they hand control back. Wait and retry, or call " +
+                "browser_get_screen_tree / browser_screenshot to observe the page.");
+        }
         const { rec, lease } = await getLease(reg);
         return sessions.runOnTarget(lease, async () => {
             if (reg.cancelled)
@@ -769,6 +823,40 @@ export async function startBrowserBridge(opts) {
                 case "click":
                 case "dblclick":
                 case "hover": {
+                    // Fix 2: if a "text" arg is present and there is no ref or x/y,
+                    // resolve the text to an element point via Playwright locators
+                    // (case-insensitive; prefers exact match, falls back to contains;
+                    // scoped to visible elements). If nothing matches, give the model
+                    // a clear directive to re-snapshot and use a @eN ref instead.
+                    if (args.text && !args.ref && args.x === undefined) {
+                        const label = String(args.text);
+                        // Try exact visible text first, then partial, then ARIA name.
+                        let locator = page.getByText(label, { exact: true }).first();
+                        let box = await locator.boundingBox({ timeout: 2_000 }).catch(() => null);
+                        if (!box) {
+                            locator = page.getByText(label, { exact: false }).first();
+                            box = await locator.boundingBox({ timeout: 2_000 }).catch(() => null);
+                        }
+                        if (!box) {
+                            locator = page.getByRole("button", { name: label, exact: false }).first();
+                            box = await locator.boundingBox({ timeout: 2_000 }).catch(() => null);
+                        }
+                        if (!box) {
+                            locator = page.getByRole("link", { name: label, exact: false }).first();
+                            box = await locator.boundingBox({ timeout: 2_000 }).catch(() => null);
+                        }
+                        if (!box) {
+                            throw new BridgeError("act_args_invalid", `click by text: no visible element matched "${label}". ` +
+                                "Call browser_get_screen_tree to get fresh @eN refs and retry " +
+                                "with a ref instead of a text label.");
+                        }
+                        const pt = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+                        if (kind === "hover")
+                            await page.mouse.move(pt.x, pt.y);
+                        else
+                            await page.mouse.click(pt.x, pt.y, { clickCount: kind === "dblclick" ? 2 : 1 });
+                        return { at: { x: Math.round(pt.x), y: Math.round(pt.y) }, matched_text: label };
+                    }
                     const pt = await resolveActionPoint(reg, rec, lease, args);
                     if (kind === "hover")
                         await page.mouse.move(pt.x, pt.y);
@@ -776,6 +864,14 @@ export async function startBrowserBridge(opts) {
                         await page.mouse.click(pt.x, pt.y, { clickCount: kind === "dblclick" ? 2 : 1 });
                     return { at: { x: Math.round(pt.x), y: Math.round(pt.y) } };
                 }
+                case "tap": {
+                    // Fix 1: tap is a coordinate click (canvas/vision fallback).
+                    // browser.py sends {x, y} as 0..1 fractions or CSS px.
+                    // resolveActionPoint already handles the fraction/px heuristic.
+                    const pt = await resolveActionPoint(reg, rec, lease, args);
+                    await page.mouse.click(pt.x, pt.y);
+                    return { at: { x: Math.round(pt.x), y: Math.round(pt.y) } };
+                }
                 case "input_text": {
                     const text = String(args.text ?? args.value ?? "");
                     if (text.length > 20_000)
@@ -801,9 +897,67 @@ export async function startBrowserBridge(opts) {
                         await cdp.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: binding.backendNodeId }).catch(() => { });
                         return { scrolled: "into_view" };
                     }
-                    const dy = Math.max(-4000, Math.min(4000, Number(args.dy ?? 600)));
-                    await page.mouse.wheel(0, dy);
-                    return { scrolled: dy };
+                    // Fix 1 (scroll): browser.py sends {value: "small"|"medium"|"large",
+                    // text: "down"|"up"|"left"|"right"}. Map to pixel deltas.
+                    // Fall back to args.dy for callers that send raw pixel deltas directly.
+                    let dx = 0;
+                    let dy = 0;
+                    if (args.value !== undefined || args.text !== undefined) {
+                        const amountMap = { small: 200, medium: 600, large: 1400 };
+                        const amount = amountMap[String(args.value || "medium")] ?? 600;
+                        const dir = String(args.text || "down").toLowerCase();
+                        if (dir === "down")
+                            dy = amount;
+                        else if (dir === "up")
+                            dy = -amount;
+                        else if (dir === "right")
+                            dx = amount;
+                        else if (dir === "left")
+                            dx = -amount;
+                        else
+                            dy = amount;
+                    }
+                    else {
+                        dy = Math.max(-4000, Math.min(4000, Number(args.dy ?? 600)));
+                    }
+                    await page.mouse.wheel(dx, dy);
+                    return { scrolled: { dx, dy } };
+                }
+                case "get_text": {
+                    // Fix 1: read-only page-text extraction.
+                    // browser.py sends {ref?: "@eN"} (optional scoped element).
+                    // The ref arg arrives under args.ref; if absent, read full body text.
+                    const TEXT_BUDGET = 12_000;
+                    let text;
+                    if (args.ref) {
+                        // Scope to the element's innerText via CDP object resolution.
+                        const binding = sessions.resolveRef(lease, args.ref);
+                        const cdp = await getCdp(rec, page);
+                        const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId });
+                        const result = await cdp.send("Runtime.callFunctionOn", {
+                            objectId: resolved.object.objectId,
+                            functionDeclaration: `function(){ return (this.innerText || this.textContent || "").trim(); }`,
+                            returnByValue: true,
+                        });
+                        text = String(result.result.value ?? "");
+                    }
+                    else {
+                        text = await page.evaluate(() => (document.body?.innerText || document.body?.textContent || "").trim());
+                    }
+                    const truncated = text.length > TEXT_BUDGET;
+                    return {
+                        text: text.slice(0, TEXT_BUDGET) + (truncated ? `\n...[truncated; ${text.length} chars total]` : ""),
+                    };
+                }
+                case "wait_for_network_idle": {
+                    // Fix 1: wait for network idle. browser.py sends {value: seconds}.
+                    const maxMs = 30_000;
+                    const timeoutMs = Math.min(Math.max(1_000, Math.round(Number(args.value ?? 10) * 1_000)), maxMs);
+                    await page.waitForLoadState("networkidle", { timeout: timeoutMs }).catch(() => {
+                        // Timeout is not fatal: the page may have long-polling connections.
+                        // Return ok anyway; the agent will re-snapshot and observe.
+                    });
+                    return { network_idle: true, waited_ms: timeoutMs };
                 }
                 case "select_option": {
                     if (!args.ref)
@@ -890,11 +1044,14 @@ export async function startBrowserBridge(opts) {
     }
     // sessionId -> WatchLease
     const watchLeases = new Map();
-    function postFrame(lease, jpegB64) {
+    function postFrame(lease, jpegB64, tabs) {
         // Never send if the lease has been deactivated concurrently.
         if (!lease.active)
             return;
-        const body = JSON.stringify({ sessionId: lease.sessionId, runId: lease.runId, jpegB64 });
+        const bodyObj = { sessionId: lease.sessionId, runId: lease.runId, jpegB64 };
+        if (tabs !== undefined)
+            bodyObj.tabs = tabs;
+        const body = JSON.stringify(bodyObj);
         const url = lease.framePostUrl;
         try {
             const u = new URL(url);
@@ -933,13 +1090,15 @@ export async function startBrowserBridge(opts) {
             const isInteractive = interactiveSessions.has(lease.runId) ||
                 (interactiveSessions.has(lease.sessionId) && lease.sessionId === lease.runId);
             if (isInteractive) {
-                // Interactive: grab the first page in the context, or create one.
+                // Interactive: mirror the tab the agent is CURRENTLY driving (active
+                // page for this session), else the newest open tab, else the first.
                 const context = rec.context;
                 if (!context) {
                     lease.active = false;
                     return;
                 }
-                let page = context.pages()[0];
+                const openPages = context.pages().filter((p) => !p.isClosed());
+                let page = activePageForSession(lease.sessionId) ?? openPages[openPages.length - 1] ?? context.pages()[0];
                 if (!page) {
                     try {
                         page = await context.newPage();
@@ -950,8 +1109,12 @@ export async function startBrowserBridge(opts) {
                     }
                 }
                 // Lease the page under a stable "interactive" ref. leaseTarget is
-                // idempotent (returns existing lease if the ref already exists).
+                // idempotent (returns existing lease if the ref already exists); when the
+                // active tab changed, repoint the existing lease at the new page so the
+                // captured frames follow it.
                 targetLease = sessions.leaseTarget(rec, "interactive", page);
+                if (targetLease.page !== page)
+                    targetLease.page = page;
             }
             else {
                 const reg = byRunId.get(lease.runId);
@@ -970,11 +1133,46 @@ export async function startBrowserBridge(opts) {
                     return;
                 }
             }
+            // Compute the tab list for this session (interactive sessions only).
+            // Done defensively after the screenshot so a failing title/url read
+            // never blocks frame delivery. Sent only when the list changed.
+            let tabsPayload = undefined;
+            if (isInteractive) {
+                const context = rec.context;
+                if (context) {
+                    const openPages = context.pages().filter((p) => !p.isClosed());
+                    const activePg = activePageForSession(lease.sessionId) ?? openPages[openPages.length - 1] ?? null;
+                    // Build tab descriptors synchronously where possible; fetch titles async.
+                    const tabDescs = openPages.map((p) => ({
+                        ref: getTabRef(p),
+                        title: "",
+                        url: p.url().slice(0, 200),
+                        active: p === activePg,
+                    }));
+                    // Fetch titles best-effort; skip any that reject or time out.
+                    await Promise.all(openPages.map(async (p, i) => {
+                        try {
+                            tabDescs[i].title = (await p.title()).slice(0, 80);
+                        }
+                        catch { /* skip */ }
+                    }));
+                    const tabsJson = JSON.stringify(tabDescs);
+                    if (tabsJson !== lease.lastTabsJson) {
+                        lease.lastTabsJson = tabsJson;
+                        tabsPayload = tabDescs;
+                    }
+                }
+            }
             const { image_b64: jpegB64 } = await takeScreenshot(targetLease);
             const changed = jpegB64 !== lease.lastJpegB64;
             if (changed) {
                 lease.lastJpegB64 = jpegB64;
-                postFrame(lease, jpegB64);
+                postFrame(lease, jpegB64, tabsPayload);
+            }
+            else if (tabsPayload !== undefined) {
+                // Tabs changed but frame did not; send frame anyway so the tab update
+                // is not dropped (the frame body carries the tabs field).
+                postFrame(lease, jpegB64, tabsPayload);
             }
             // Adaptive FPS: 250 ms (4 fps) when changed, 500 ms (2 fps) when
             // the page is static. The cap is 4 fps; do not go lower than 2 fps
@@ -1063,6 +1261,7 @@ export async function startBrowserBridge(opts) {
             active: true,
             timer: null,
             lastJpegB64: "",
+            lastTabsJson: "",
         };
         watchLeases.set(sessionId, lease);
         log(`[watch] frame producer started for session ${sessionId.slice(0, 16)} run=${matchedRunId.slice(0, 10)}`);
@@ -1442,6 +1641,8 @@ export async function startBrowserBridge(opts) {
                     // producer) are preserved.
                     interactive.targets.delete(reg.spec.grant.target.ref);
                 }
+                // Clear any per-session pause flag so a restarted run is not stuck.
+                pausedSessions.delete(browserSessionId);
             }
             log(`browser run detached (non-owner): ${runId.slice(0, 10)} reason=${reason}`);
         }
@@ -1454,6 +1655,8 @@ export async function startBrowserBridge(opts) {
         }
     };
     const teardownAll = async (reason) => {
+        // Clear all pause flags so nothing is left paused after a full teardown.
+        pausedSessions.clear();
         // Tear down grant-scoped run sessions.
         const runIds = [...byRunId.keys()];
         // Tear down interactive sessions (those not already covered by byRunId).
@@ -1472,6 +1675,18 @@ export async function startBrowserBridge(opts) {
             }),
         ]);
     };
+    // setPaused: set or clear the takeover pause flag (Fix 3).
+    // sessionId present -> pause only that interactive session.
+    // sessionId absent  -> pause/resume all sessions (global sentinel "").
+    const setPaused = (paused, sessionId) => {
+        const key = sessionId ?? "";
+        if (paused) {
+            pausedSessions.add(key);
+        }
+        else {
+            pausedSessions.delete(key);
+        }
+    };
     // killInteractive: close one or all interactive sessions (emergency stop).
     // Does NOT touch grant-scoped run sessions in byRunId.
     const killInteractive = async (sessionId) => {
@@ -1504,6 +1719,36 @@ export async function startBrowserBridge(opts) {
         }));
         return closed;
     };
+    // switchTabForSession: repoints the active page for an interactive session
+    // so the frame producer + page-event handling follow the new tab.
+    // The caller supplies the opaque tab ref from getTabRef.
+    function switchTabForSession(sessionId, ref) {
+        const rec = interactiveSessions.get(sessionId);
+        if (!rec || rec.state === "closed" || rec.state === "crashed")
+            return false;
+        const context = rec.context;
+        if (!context)
+            return false;
+        const pages = context.pages().filter((p) => !p.isClosed());
+        const target = pages.find((p) => getTabRef(p) === ref);
+        if (!target)
+            return false;
+        // Update the active page for every grant-run attached to this session,
+        // and also force the watch-lease lastTabsJson to "" so the next frame
+        // tick re-broadcasts the updated active flag to the client.
+        for (const [runId, reg] of byRunId) {
+            if (String(reg.spec.grant.browserSession || "") === sessionId) {
+                activePageByRunId.set(runId, target);
+            }
+        }
+        // Reset the tab change sentinel so the next frame pick broadcasts the new state.
+        const wl = watchLeases.get(sessionId);
+        if (wl)
+            wl.lastTabsJson = "";
+        // Bring the tab to front best-effort (headed sessions).
+        target.bringToFront().catch(() => { });
+        return true;
+    }
     return {
         url: `http://127.0.0.1:${port}`,
         port,
@@ -1517,6 +1762,8 @@ export async function startBrowserBridge(opts) {
         getInteractiveSession,
         setWatchLease,
         killInteractive,
+        setPaused,
+        switchTabForSession,
         async shutdown() {
             // Stop all watch-lease producers before closing sessions.
             for (const sid of [...watchLeases.keys()])

package/dist/connection.js

@@ -360,6 +360,48 @@ export async function connect(opts) {
             console.log(chalk.yellow(`  ! browser:kill error: ${e?.message || e}`));
         }
     });
+    // ── BrowserControlPage takeover pause (browser:takeover) ─────────────
+    // The server emits browser:takeover { sessionId?, paused } when the user
+    // clicks "Take control" (paused:true) or "Hand back" (paused:false) in
+    // the BrowserControlPage UI. While paused, the bridge blocks all
+    // consequential acts (click, navigate, input_text, etc.) with a
+    // paused_by_user BridgeError so the agent waits instead of racing with
+    // the user. Read-only ops (get_screen_tree, screenshot, get_text, wait)
+    // are not blocked. If sessionId is absent the pause applies to all
+    // sessions on this runner.
+    socket.on("browser:takeover", (payload) => {
+        const sessionId = payload?.sessionId ? String(payload.sessionId) : undefined;
+        const paused = Boolean(payload?.paused);
+        if (!browserBridge) {
+            if (opts.verbose)
+                console.log(chalk.gray("  [browser-takeover] bridge not ready, ignoring"));
+            return;
+        }
+        browserBridge.setPaused(paused, sessionId);
+        if (opts.verbose) {
+            console.log(chalk.gray(`  [browser-takeover] paused=${paused} sessionId=${sessionId ? sessionId.slice(0, 16) : "(all)"}`));
+        }
+    });
+    // ── BrowserControlPage tab switch (browser:switch-tab) ───────────────
+    // The server emits browser:switch-tab { sessionId, ref } when the user
+    // clicks a non-active tab in the live-mirror tab strip. The bridge
+    // repoints the active page for that interactive session so the frame
+    // producer and any attached agent ops follow the new tab.
+    socket.on("browser:switch-tab", (payload) => {
+        const sessionId = String(payload?.sessionId || "");
+        const ref = String(payload?.ref || "");
+        if (!sessionId || !ref)
+            return;
+        if (!browserBridge) {
+            if (opts.verbose)
+                console.log(chalk.gray("  [browser-switch-tab] bridge not ready, ignoring"));
+            return;
+        }
+        const switched = browserBridge.switchTabForSession(sessionId, ref);
+        if (opts.verbose) {
+            console.log(chalk.gray(`  [browser-switch-tab] sessionId=${sessionId.slice(0, 16)} ref=${ref} switched=${switched}`));
+        }
+    });
     // ── Heartbeat ──────────────────────────────────────────────────────
     setInterval(() => {
         if (socket.connected)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.9",
+  "version": "1.1.12",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "UNLICENSED",
   "private": false,