@melaya/runner 1.1.0 → 1.1.2

package/dist/browserAuthz.js

@@ -332,54 +332,54 @@ async function interceptWebSockets(page, policy, hooks) {
  *     IP leakage via STUN/TURN. Combined with the CDP Network.enable /
  *     setRTCConfiguration override (applied separately via CDP below), this
  *     provides layered defence. */
-const PAGE_GUARD_INIT_SCRIPT = `(function() {
-  // WebRTC neutralisation: remove peer connection constructors.
-  try { delete window.RTCPeerConnection; } catch (_) {}
-  try { delete window.RTCSessionDescription; } catch (_) {}
-  try { delete window.RTCIceCandidate; } catch (_) {}
-  // Also zero out webkit/moz-prefixed variants some legacy code still uses.
-  try { delete window.webkitRTCPeerConnection; } catch (_) {}
-  try { delete window.mozRTCPeerConnection; } catch (_) {}
-  // Override navigator.mediaDevices.getUserMedia to prevent media/camera
-  // capture that could be combined with a data channel.
-  try {
-    if (navigator.mediaDevices && typeof navigator.mediaDevices === 'object') {
-      Object.defineProperty(navigator, 'mediaDevices', { value: Object.assign({}, navigator.mediaDevices, { getUserMedia: () => Promise.reject(new DOMException('NotAllowedError')) }), configurable: false, writable: false });
-    }
-  } catch (_) {}
-  // WebSocket URL-blocking fallback (defence-in-depth, supplements
-  // routeWebSocket interception which fires at the Playwright layer).
-  var _NativeWS = window.WebSocket;
-  function _isForbiddenWsHost(url) {
-    try {
-      var u = new URL(url);
-      var h = u.hostname.replace(/^\\[|\\]$/g,'');
-      // Loopback / localhost
-      if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.endsWith('.localhost') || h.endsWith('.local')) return true;
-      // Link-local (169.254.x.x) — cloud metadata endpoints live here
-      if (/^169\\.254\\./.test(h)) return true;
-      // RFC1918
-      if (/^10\\./.test(h)) return true;
-      if (/^172\\.(1[6-9]|2[0-9]|3[01])\\./.test(h)) return true;
-      if (/^192\\.168\\./.test(h)) return true;
-      // CGNAT
-      if (/^100\\.(6[4-9]|[7-9][0-9]|1([01][0-9]|2[0-7]))\\./.test(h)) return true;
-      // Explicit metadata hosts
-      if (h === '100.100.100.200' || h === 'metadata.google.internal' || h === 'metadata.goog') return true;
-    } catch (_) {}
-    return false;
-  }
-  window.WebSocket = function WrappedWebSocket(url, protocols) {
-    if (_isForbiddenWsHost(String(url))) {
-      throw new DOMException('WebSocket connection to ' + url + ' is blocked by Melaya egress policy', 'SecurityError');
-    }
-    return protocols !== undefined ? new _NativeWS(url, protocols) : new _NativeWS(url);
-  };
-  window.WebSocket.prototype = _NativeWS.prototype;
-  window.WebSocket.CONNECTING = _NativeWS.CONNECTING;
-  window.WebSocket.OPEN = _NativeWS.OPEN;
-  window.WebSocket.CLOSING = _NativeWS.CLOSING;
-  window.WebSocket.CLOSED = _NativeWS.CLOSED;
+const PAGE_GUARD_INIT_SCRIPT = `(function() {
+  // WebRTC neutralisation: remove peer connection constructors.
+  try { delete window.RTCPeerConnection; } catch (_) {}
+  try { delete window.RTCSessionDescription; } catch (_) {}
+  try { delete window.RTCIceCandidate; } catch (_) {}
+  // Also zero out webkit/moz-prefixed variants some legacy code still uses.
+  try { delete window.webkitRTCPeerConnection; } catch (_) {}
+  try { delete window.mozRTCPeerConnection; } catch (_) {}
+  // Override navigator.mediaDevices.getUserMedia to prevent media/camera
+  // capture that could be combined with a data channel.
+  try {
+    if (navigator.mediaDevices && typeof navigator.mediaDevices === 'object') {
+      Object.defineProperty(navigator, 'mediaDevices', { value: Object.assign({}, navigator.mediaDevices, { getUserMedia: () => Promise.reject(new DOMException('NotAllowedError')) }), configurable: false, writable: false });
+    }
+  } catch (_) {}
+  // WebSocket URL-blocking fallback (defence-in-depth, supplements
+  // routeWebSocket interception which fires at the Playwright layer).
+  var _NativeWS = window.WebSocket;
+  function _isForbiddenWsHost(url) {
+    try {
+      var u = new URL(url);
+      var h = u.hostname.replace(/^\\[|\\]$/g,'');
+      // Loopback / localhost
+      if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.endsWith('.localhost') || h.endsWith('.local')) return true;
+      // Link-local (169.254.x.x) — cloud metadata endpoints live here
+      if (/^169\\.254\\./.test(h)) return true;
+      // RFC1918
+      if (/^10\\./.test(h)) return true;
+      if (/^172\\.(1[6-9]|2[0-9]|3[01])\\./.test(h)) return true;
+      if (/^192\\.168\\./.test(h)) return true;
+      // CGNAT
+      if (/^100\\.(6[4-9]|[7-9][0-9]|1([01][0-9]|2[0-7]))\\./.test(h)) return true;
+      // Explicit metadata hosts
+      if (h === '100.100.100.200' || h === 'metadata.google.internal' || h === 'metadata.goog') return true;
+    } catch (_) {}
+    return false;
+  }
+  window.WebSocket = function WrappedWebSocket(url, protocols) {
+    if (_isForbiddenWsHost(String(url))) {
+      throw new DOMException('WebSocket connection to ' + url + ' is blocked by Melaya egress policy', 'SecurityError');
+    }
+    return protocols !== undefined ? new _NativeWS(url, protocols) : new _NativeWS(url);
+  };
+  window.WebSocket.prototype = _NativeWS.prototype;
+  window.WebSocket.CONNECTING = _NativeWS.CONNECTING;
+  window.WebSocket.OPEN = _NativeWS.OPEN;
+  window.WebSocket.CLOSING = _NativeWS.CLOSING;
+  window.WebSocket.CLOSED = _NativeWS.CLOSED;
 })();`;
 /** Disable WebRTC at the CDP Network domain level in addition to the
  *  init-script layer (belt-and-suspenders). Silently skips if CDP

package/dist/browserBridge.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserGrant } from "./browserGrantVerify.js";
-import { type SpaceSpec } from "./sessionManager.js";
+import { type BrowserSessionRecord, type SpaceSpec } from "./sessionManager.js";
 import { type BrowserEngineId } from "./browserProvisioner.js";
 export interface BrowserRunSpec {
     runId: string;
@@ -24,6 +24,42 @@ export interface BrowserBridge {
     teardownRun(runId: string, reason: string): Promise<void>;
     teardownAll(reason: string): Promise<void>;
     hasRun(runId: string): boolean;
+    /**
+     * Launch a headed browser as an interactive (grant-free, read-only-watch)
+     * session tracked in sessionManager under `sessionId`.
+     *
+     * The session is governed by browserProvisioner for engine resolution
+     * and by sessionManager for lifecycle. It is discoverable by
+     * setWatchLease(sessionId, ...) and by getInteractiveSession(sessionId),
+     * which is the attach seam for the grant/run path.
+     *
+     * State transitions are reported via `onState(sessionId, state, engine)`:
+     *   "active"  - browser is open and ready to watch
+     *   "closed"  - browser was closed by the user or system
+     *   "failed"  - launch failed (engine not found, Playwright error, etc.)
+     *
+     * Errors during launch are caught internally; the caller receives
+     * "failed" via onState rather than a thrown exception.
+     */
+    launchInteractive(sessionId: string, engine: string, profile: string, onState: (sessionId: string, state: "active" | "closed" | "failed", engine: string) => void): Promise<void>;
+    /**
+     * Look up an active interactive session by the sessionId that was passed
+     * to launchInteractive. Returns the BrowserSessionRecord if the session
+     * is live, or undefined if it was never launched, has closed, or crashed.
+     *
+     * ATTACH SEAM: the grant/run path in ensureSession should call this
+     * before launching a new browser. If a record is returned the run can
+     * reuse rec.context and the existing page rather than opening a second
+     * browser for the same sessionId. Concretely, in ensureSession the
+     * "LAUNCH mode" block should check:
+     *
+     *   const interactive = bridge.getInteractiveSession(spec.sessionId);
+     *   if (interactive) { ... reuse interactive.context ... }
+     *
+     * This seam is left as a documented hook; full grant-attach wiring is
+     * a follow-up task once the grant schema carries a sessionId.
+     */
+    getInteractiveSession(sessionId: string): BrowserSessionRecord | undefined;
     /**
      * Set the watch-lease state for a session (plan Section 10.f).
      *
@@ -36,6 +72,10 @@ export interface BrowserBridge {
      *
      * The producer runs only while a viewer is watching and stops
      * automatically when the run is torn down.
+     *
+     * This method now finds both grant-scoped run sessions (looked up by
+     * runId) AND interactive sessions launched via launchInteractive
+     * (looked up by sessionId directly).
      */
     setWatchLease(sessionId: string, active: boolean, framePostUrl: string, runAuthHeader: string): void;
     shutdown(): Promise<void>;

package/dist/browserBridge.js

@@ -82,6 +82,12 @@ export async function startBrowserBridge(opts) {
     // Per-lease transient state the sessionManager types stay clean of.
     const frameMaps = new WeakMap();
     const cdpByPage = new WeakMap();
+    // 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();
     let playwrightMod = null;
     async function pw() {
         if (!playwrightMod)
@@ -198,6 +204,105 @@ export async function startBrowserBridge(opts) {
         void disableWebRtcViaCdp(cdp);
         return cdp;
     }
+    // -- Interactive launch (browser:launch, no grant) ---------------------
+    //
+    // Opens a headed browser tracked in sessionManager so setWatchLease can
+    // find and stream frames from it. The session is READ-ONLY from the
+    // bridge's perspective (no CDP intercept effects, no grant gates). The
+    // sessionId from the socket event is used directly as the runId in the
+    // session manager so the setWatchLease lookup (which already checks
+    // `runId === sessionId`) finds the record without any additional mapping.
+    async function launchInteractive(sessionId, engine, profile, onState) {
+        // Normalise engine to a known BrowserEngineId; default to "chrome".
+        const knownEngines = new Set(["chrome", "edge", "brave", "chromium"]);
+        const engineId = (knownEngines.has(engine) ? engine : "chrome");
+        // Resolve profile directory, mirroring simpleBrowserLauncher semantics:
+        //   "dedicated" => ephemeral per-session dir under tmpdir
+        //   anything else => persistent named dir under ~/.melaya-runner/browser-profiles/
+        // spaceUserDataDir() already handles ephemeral vs persistent; map to SpaceSpec.
+        const spaceSpec = profile === "dedicated"
+            ? { kind: "ephemeral" }
+            : { kind: "persistent", id: `browser-profiles-${engineId}-${profile}` };
+        // Reject duplicate launches for the same sessionId.
+        if (interactiveSessions.has(sessionId)) {
+            log(`[browser-launch] sessionId=${sessionId.slice(0, 16)} already active; ignoring duplicate launch`);
+            return;
+        }
+        try {
+            const playwright = await pw();
+            const resolved = await ensureEngine(engineId, { log });
+            const { dir: userDataDir, ephemeral } = spaceUserDataDir(spaceSpec, sessionId);
+            // Create the session record BEFORE launch so teardownAll can find it
+            // even if the launch is still in progress.
+            const rec = sessions.createSession({
+                runId: sessionId,
+                ownership: "owned",
+                engine: engineId,
+                space: spaceSpec,
+                // Interactive sessions have a longer idle TTL (30 min) because the
+                // user may leave the browser open without actively using the runner.
+                idleTtlMs: 30 * 60 * 1000,
+                maxLifetimeMs: 4 * 60 * 60 * 1000,
+            });
+            interactiveSessions.set(sessionId, rec);
+            let context;
+            try {
+                context = await playwright.chromium.launchPersistentContext(userDataDir, {
+                    executablePath: resolved.executablePath,
+                    headless: false,
+                    viewport: { width: 1280, height: 800 },
+                    acceptDownloads: false,
+                    args: [
+                        "--no-first-run",
+                        "--no-default-browser-check",
+                        "--disable-background-networking",
+                        "--disable-sync",
+                    ],
+                });
+            }
+            catch (launchErr) {
+                // Clean up the session record we created before failing.
+                interactiveSessions.delete(sessionId);
+                await sessions.teardownRun(sessionId, "interactive_launch_failed").catch(() => { });
+                log(`[browser-launch] launch failed sessionId=${sessionId.slice(0, 16)}: ${launchErr?.message || launchErr}`);
+                onState(sessionId, "failed", engine);
+                return;
+            }
+            sessions.attachHandles(rec, {
+                context,
+                ephemeralUserDataDir: ephemeral ? userDataDir : null,
+            });
+            log(`[browser-launch] interactive session active sessionId=${sessionId.slice(0, 16)} engine=${engineId}`);
+            onState(sessionId, "active", engine);
+            // Detect browser close: context 'close' fires when the user shuts
+            // the browser window or when teardown closes it.
+            context.once("close", () => {
+                interactiveSessions.delete(sessionId);
+                // Only emit "closed" if the session was not already torn down by
+                // teardownAll/shutdown (rec.state will be "closed" in that case).
+                if (rec.state !== "closed") {
+                    sessions.teardownRun(sessionId, "interactive_context_closed").catch(() => { });
+                    log(`[browser-launch] interactive session closed sessionId=${sessionId.slice(0, 16)}`);
+                    onState(sessionId, "closed", engine);
+                }
+            });
+        }
+        catch (err) {
+            interactiveSessions.delete(sessionId);
+            log(`[browser-launch] unexpected error sessionId=${sessionId.slice(0, 16)}: ${err?.message || err}`);
+            onState(sessionId, "failed", engine);
+        }
+    }
+    function getInteractiveSession(sessionId) {
+        const rec = interactiveSessions.get(sessionId);
+        if (!rec)
+            return undefined;
+        if (rec.state === "closed" || rec.state === "crashed") {
+            interactiveSessions.delete(sessionId);
+            return undefined;
+        }
+        return rec;
+    }
     async function captureSnapshot(rec, lease, scope) {
         const page = lease.page;
         const generation = sessions.beginSnapshot(lease);
@@ -708,19 +813,57 @@ export async function startBrowserBridge(opts) {
     async function captureAndSchedule(lease) {
         if (!lease.active)
             return;
-        const reg = byRunId.get(lease.runId);
-        if (!reg || reg.cancelled) {
-            lease.active = false;
-            return;
-        }
         try {
             const rec = sessions.peekSession(lease.runId);
             if (!rec || rec.state === "crashed" || rec.state === "closed") {
                 lease.active = false;
                 return;
             }
-            const target = sessions.getLease(rec, reg.spec.grant.target.ref);
-            const { image_b64: jpegB64 } = await takeScreenshot(target);
+            // Resolve the target page. Interactive sessions (no grant, no registered
+            // run) use the first available page in the context. Grant-scoped run
+            // sessions use the leased target ref from the registration.
+            let targetLease = null;
+            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.
+                const context = rec.context;
+                if (!context) {
+                    lease.active = false;
+                    return;
+                }
+                let page = context.pages()[0];
+                if (!page) {
+                    try {
+                        page = await context.newPage();
+                    }
+                    catch {
+                        lease.active = false;
+                        return;
+                    }
+                }
+                // Lease the page under a stable "interactive" ref. leaseTarget is
+                // idempotent (returns existing lease if the ref already exists).
+                targetLease = sessions.leaseTarget(rec, "interactive", page);
+            }
+            else {
+                const reg = byRunId.get(lease.runId);
+                if (!reg || reg.cancelled) {
+                    lease.active = false;
+                    return;
+                }
+                try {
+                    targetLease = sessions.getLease(rec, reg.spec.grant.target.ref);
+                }
+                catch {
+                    // Target lease not yet established (session still initialising) or gone.
+                    if (lease.active) {
+                        lease.timer = setTimeout(() => { void captureAndSchedule(lease); }, 1000);
+                    }
+                    return;
+                }
+            }
+            const { image_b64: jpegB64 } = await takeScreenshot(targetLease);
             const changed = jpegB64 !== lease.lastJpegB64;
             if (changed) {
                 lease.lastJpegB64 = jpegB64;
@@ -757,24 +900,39 @@ export async function startBrowserBridge(opts) {
             stopWatchLease(sessionId);
             return;
         }
-        // Find which runId corresponds to this sessionId (session ids map 1:1
-        // to runIds in Phase 1 — one session per run).
+        // Find which runId corresponds to this sessionId.
+        // Priority order:
+        //   1. Interactive session: sessionId is both the key in interactiveSessions
+        //      AND the runId used in sessionManager (so peek will find it directly).
+        //   2. Grant-scoped run session: iterate byRunId and check rec.id or runId.
         let matchedRunId = "";
-        for (const [runId, reg] of byRunId) {
-            const rec = sessions.peekSession(runId);
-            if (rec && rec.id === sessionId) {
-                matchedRunId = runId;
-                break;
+        // Check interactive sessions first (launched via launchInteractive).
+        if (interactiveSessions.has(sessionId)) {
+            const rec = interactiveSessions.get(sessionId);
+            if (rec && rec.state !== "closed" && rec.state !== "crashed") {
+                matchedRunId = sessionId; // sessionId is used as runId for interactive sessions
             }
-            // Also accept runId directly as sessionId (used when the server
-            // addresses the watch by runId rather than the session UUID).
-            if (runId === sessionId) {
-                matchedRunId = runId;
-                break;
+        }
+        // Fall back to grant-scoped run sessions (session ids map 1:1 to runIds
+        // in Phase 1, one session per run).
+        if (!matchedRunId) {
+            for (const [runId, reg] of byRunId) {
+                const rec = sessions.peekSession(runId);
+                if (rec && rec.id === sessionId) {
+                    matchedRunId = runId;
+                    break;
+                }
+                // Also accept runId directly as sessionId (used when the server
+                // addresses the watch by runId rather than the session UUID).
+                if (runId === sessionId) {
+                    matchedRunId = runId;
+                    break;
+                }
+                void reg; // suppress unused variable warning
             }
         }
         if (!matchedRunId) {
-            log(`[watch] browser:watch active=true for unknown sessionId ${sessionId.slice(0, 16)} — ignored`);
+            log(`[watch] browser:watch active=true for unknown sessionId ${sessionId.slice(0, 16)} - ignored`);
             return;
         }
         // Stop any existing lease for this session before starting a new one.
@@ -985,8 +1143,23 @@ export async function startBrowserBridge(opts) {
         log(`browser run torn down: ${runId.slice(0, 10)} reason=${reason}`);
     };
     const teardownAll = async (reason) => {
-        const ids = [...byRunId.keys()];
-        await Promise.all(ids.map((id) => teardownRun(id, reason)));
+        // Tear down grant-scoped run sessions.
+        const runIds = [...byRunId.keys()];
+        // Tear down interactive sessions (those not already covered by byRunId).
+        const interactiveIds = [...interactiveSessions.keys()].filter((id) => !byRunId.has(id));
+        await Promise.all([
+            ...runIds.map((id) => teardownRun(id, reason)),
+            ...interactiveIds.map(async (id) => {
+                // Stop watch-lease producers for this interactive session.
+                for (const [sid, wl] of watchLeases) {
+                    if (wl.runId === id)
+                        stopWatchLease(sid);
+                }
+                interactiveSessions.delete(id);
+                await sessions.teardownRun(id, reason);
+                log(`[browser-launch] interactive session torn down: ${id.slice(0, 16)} reason=${reason}`);
+            }),
+        ]);
     };
     return {
         url: `http://127.0.0.1:${port}`,
@@ -997,6 +1170,8 @@ export async function startBrowserBridge(opts) {
         hasRun(runId) {
             return byRunId.has(runId);
         },
+        launchInteractive,
+        getInteractiveSession,
         setWatchLease,
         async shutdown() {
             // Stop all watch-lease producers before closing sessions.

package/dist/codeWorker.js

@@ -95,74 +95,74 @@ const WORKER_OP_ALLOWLIST = new Set([
 // boundary is the process + OS sandbox around it. The vm context exposes
 // exactly: browser.<op>(), console.log/warn/error, sleep(ms), and
 // JSON/Math/Date via the fresh realm.
-const WORKER_ENTRY_SOURCE = `"use strict";
-const vm = require("node:vm");
-const readline = require("node:readline");
-
-let seq = 0;
-const pending = new Map();
-function send(msg) { process.stdout.write(JSON.stringify(msg) + "\\n"); }
-
-const rl = readline.createInterface({ input: process.stdin, terminal: false });
-let scriptSource = null;
-rl.on("line", (line) => {
-  let m;
-  try { m = JSON.parse(line); } catch { return; }
-  if (m.type === "start" && typeof m.script === "string" && scriptSource === null) {
-    scriptSource = m.script;
-    run(scriptSource);
-  } else if (m.type === "op_result" && pending.has(m.id)) {
-    const { resolve, reject } = pending.get(m.id);
-    pending.delete(m.id);
-    if (m.ok) resolve(m.result);
-    else reject(new Error(m.error || "op failed"));
-  }
-});
-
-function facadeOp(op) {
-  return (args) => new Promise((resolve, reject) => {
-    const id = ++seq;
-    pending.set(id, { resolve, reject });
-    send({ type: "op", id, op, args: args && typeof args === "object" ? args : {} });
-  });
-}
-
-async function run(source) {
-  const browser = Object.freeze({
-    currentTarget: facadeOp("current_target"),
-    getScreenTree: facadeOp("get_screen_tree"),
-    screenshot: facadeOp("screenshot"),
-    act: facadeOp("act"),
-    wait: facadeOp("wait"),
-  });
-  const consoleShim = {
-    log: (...a) => send({ type: "console", line: a.map(String).join(" ") }),
-    warn: (...a) => send({ type: "console", line: "[warn] " + a.map(String).join(" ") }),
-    error: (...a) => send({ type: "console", line: "[error] " + a.map(String).join(" ") }),
-  };
-  const sleep = (ms) => facadeOp("wait")({ ms });
-  const ctx = vm.createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false } });
-  ctx.browser = browser;
-  ctx.console = consoleShim;
-  ctx.sleep = sleep;
-  ctx.JSON = JSON;
-  try {
-    const script = new vm.Script(
-      "(async () => {\\n" + source + "\\n})()",
-      { filename: "model-script.js" },
-    );
-    const result = await script.runInContext(ctx, { timeout: 30000 });
-    send({ type: "done", result: safeJson(result) });
-  } catch (e) {
-    send({ type: "error", message: String((e && e.message) || e) });
-  }
-  process.exit(0);
-}
-
-function safeJson(v) {
-  try { return JSON.parse(JSON.stringify(v === undefined ? null : v)); }
-  catch { return String(v); }
-}
+const WORKER_ENTRY_SOURCE = `"use strict";
+const vm = require("node:vm");
+const readline = require("node:readline");
+
+let seq = 0;
+const pending = new Map();
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\\n"); }
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false });
+let scriptSource = null;
+rl.on("line", (line) => {
+  let m;
+  try { m = JSON.parse(line); } catch { return; }
+  if (m.type === "start" && typeof m.script === "string" && scriptSource === null) {
+    scriptSource = m.script;
+    run(scriptSource);
+  } else if (m.type === "op_result" && pending.has(m.id)) {
+    const { resolve, reject } = pending.get(m.id);
+    pending.delete(m.id);
+    if (m.ok) resolve(m.result);
+    else reject(new Error(m.error || "op failed"));
+  }
+});
+
+function facadeOp(op) {
+  return (args) => new Promise((resolve, reject) => {
+    const id = ++seq;
+    pending.set(id, { resolve, reject });
+    send({ type: "op", id, op, args: args && typeof args === "object" ? args : {} });
+  });
+}
+
+async function run(source) {
+  const browser = Object.freeze({
+    currentTarget: facadeOp("current_target"),
+    getScreenTree: facadeOp("get_screen_tree"),
+    screenshot: facadeOp("screenshot"),
+    act: facadeOp("act"),
+    wait: facadeOp("wait"),
+  });
+  const consoleShim = {
+    log: (...a) => send({ type: "console", line: a.map(String).join(" ") }),
+    warn: (...a) => send({ type: "console", line: "[warn] " + a.map(String).join(" ") }),
+    error: (...a) => send({ type: "console", line: "[error] " + a.map(String).join(" ") }),
+  };
+  const sleep = (ms) => facadeOp("wait")({ ms });
+  const ctx = vm.createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false } });
+  ctx.browser = browser;
+  ctx.console = consoleShim;
+  ctx.sleep = sleep;
+  ctx.JSON = JSON;
+  try {
+    const script = new vm.Script(
+      "(async () => {\\n" + source + "\\n})()",
+      { filename: "model-script.js" },
+    );
+    const result = await script.runInContext(ctx, { timeout: 30000 });
+    send({ type: "done", result: safeJson(result) });
+  } catch (e) {
+    send({ type: "error", message: String((e && e.message) || e) });
+  }
+  process.exit(0);
+}
+
+function safeJson(v) {
+  try { return JSON.parse(JSON.stringify(v === undefined ? null : v)); }
+  catch { return String(v); }
+}
 `;
 function nodePermissionFlags(scratchDir, entryPath) {
     const major = Number(process.version.replace(/^v/, "").split(".")[0]) || 0;

package/dist/connection.js

@@ -295,6 +295,38 @@ export async function connect(opts) {
             console.log(chalk.gray(`  [browser-bridge] watch lease sessionId=${sessionId.slice(0, 16)} active=${active}`));
         }
     });
+    // ── BrowserControlPage interactive browser launch (plan BrowserControlPage) ──
+    // The server emits browser:launch when the user clicks "Launch controllable
+    // browser" in the BrowserControlPage UI. Unlike runner:run browser grants,
+    // this is an unprivileged direct-launch (no grant, no CDP intercept) — the
+    // server just wants us to open a browser process the user can observe.
+    // State transitions are relayed back via browser:session so the server can
+    // update agents.browser_sessions.
+    socket.on("browser:launch", async (payload) => {
+        const sessionId = String(payload?.sessionId || "");
+        const engine = String(payload?.engine || "chrome");
+        const profile = String(payload?.profile || "dedicated");
+        if (!sessionId)
+            return;
+        if (opts.verbose) {
+            console.log(chalk.gray(`  [browser-launch] sessionId=${sessionId.slice(0, 16)} engine=${engine} profile=${profile}`));
+        }
+        // Ensure the governed bridge is running before delegating.
+        const bridge = await _ensureBrowserBridge();
+        if (!bridge) {
+            console.log(chalk.yellow(`  ! browser:launch: bridge unavailable for sessionId=${sessionId.slice(0, 16)}`));
+            socket.emit("browser:session", { sessionId, state: "failed", engine });
+            return;
+        }
+        // Delegate to the governed bridge. State transitions (active/closed/failed)
+        // are relayed back through the existing browser:session socket event.
+        await bridge.launchInteractive(sessionId, engine, profile, (sid, state, eng) => {
+            socket.emit("browser:session", { sessionId: sid, state, engine: eng });
+            if (opts.verbose) {
+                console.log(chalk.gray(`  [browser-launch] browser:session sessionId=${sid.slice(0, 16)} state=${state}`));
+            }
+        });
+    });
     // ── Heartbeat ──────────────────────────────────────────────────────
     setInterval(() => {
         if (socket.connected)

package/package.json

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