@melaya/runner 1.0.117 → 1.1.0

package/dist/browserBridge.js

@@ -0,0 +1,1021 @@
+// packages/runner/src/browserBridge.ts
+//
+// Melaya Browser, Phase 1 (plan Sections 3, 4, 7, 8, 9, 10): the governed
+// browser control bridge. Generalizes the localhost-HTTP-shell +
+// per-session-bearer-token + lazy-Playwright pattern proven by
+// lumaBrowserBridge.ts, and deliberately does NOT inherit its two known
+// bugs: screenshots are RECOMPRESSED (JPEG quality ladder + CSS-pixel
+// scale), never base64-sliced (luma :330), and teardown closes ONLY
+// owned browsers, never an externally attached user browser (luma :756).
+//
+// Connection modes:
+//   LAUNCH  - dedicated-profile browser (chrome | edge | brave |
+//             chromium, caller-selected) via launchPersistentContext on
+//             a Melaya-owned user-data-dir. NEVER the real default
+//             profile (Chrome 136+ ignores the debug port there).
+//   ATTACH  - chromium.connectOverCDP(ws) to a Melaya-launched
+//             controllable browser. Ownership tracked as "attached";
+//             teardown only severs the CDP connection.
+//
+// HTTP contract (shared verbatim with the Python tool agent):
+//   POST /browser/current_target  -> {ok, target:{ref, origin, title?}}
+//   POST /browser/get_screen_tree -> {ok, tree, generation, url, title, nodes}
+//   POST /browser/screenshot      -> {ok, image_b64, media_type}
+//   POST /browser/act             -> {ok, result, tree, generation} |
+//                                    {ok:false, error:{code, message}}
+//   POST /browser/run             -> {ok, result, console[], tree}
+//
+// Every act is ACT-AND-OBSERVE: it returns a fresh snapshot so the model
+// never acts twice on a stale world.
+import { createServer } from "node:http";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { buildOriginPolicy, evaluateUrlResolved, checkEffect, enforceOnContext, enforceOnPage, disableWebRtcViaCdp, } from "./browserAuthz.js";
+import { SessionManager, SessionError, spaceUserDataDir, } from "./sessionManager.js";
+import { ensureEngine } from "./browserProvisioner.js";
+import { runSandboxedScript } from "./codeWorker.js";
+// ---------------------------------------------------------------------
+// Limits and constants
+// ---------------------------------------------------------------------
+const MAX_BODY_BYTES = 512 * 1024; // /browser/run scripts included
+const NODE_CAP = 240; // snapshot node cap (Section 8)
+const SCREENSHOT_MAX_B64 = 1_400_000; // ~1 MB binary; ladder recompresses
+const ACT_SETTLE_MS = 500;
+const NAV_TIMEOUT_MS = 25_000;
+// Roles that read as actionable in the AX tree.
+const CLICK_ROLES = new Set([
+    "button", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "tab",
+    "checkbox", "radio", "switch", "option", "treeitem", "listbox", "combobox",
+    "slider", "spinbutton", "disclosuretriangle", "togglebutton",
+]);
+const EDIT_ROLES = new Set(["textbox", "searchbox", "combobox", "spinbutton", "textfield", "textarea"]);
+// Non-actionable roles still worth showing when named (context anchors).
+const CONTEXT_ROLES = new Set([
+    "heading", "img", "image", "alert", "alertdialog", "dialog", "status",
+    "tabpanel", "cell", "columnheader", "rowheader", "statictext", "text",
+    "listitem", "article", "banner", "navigation", "main", "form", "search",
+]);
+/** Runner-side minimum effect per act kind. The tool layer may DECLARE a
+ *  higher typed effect (message/publish/purchase/...) which is then
+ *  checked against the grant; the runner cannot infer those from a raw
+ *  click, so kind minima keep the second gate sound without blocking
+ *  read-ish interactions (full classification is the server's first
+ *  gate, plan Section 6). */
+const KIND_MIN_EFFECT = {
+    navigate: "navigate", back: "navigate", forward: "navigate",
+    click: "read", dblclick: "read", hover: "read", scroll: "read",
+    input_text: "read", press_key: "read", select_option: "read",
+    wait: "read",
+};
+// ---------------------------------------------------------------------
+// Bridge
+// ---------------------------------------------------------------------
+export async function startBrowserBridge(opts) {
+    const log = opts.log;
+    const byToken = new Map();
+    const byRunId = new Map();
+    const sessions = new SessionManager({ log: (m) => opts.verbose && log(m) });
+    // Per-lease transient state the sessionManager types stay clean of.
+    const frameMaps = new WeakMap();
+    const cdpByPage = new WeakMap();
+    let playwrightMod = null;
+    async function pw() {
+        if (!playwrightMod)
+            playwrightMod = await import("playwright");
+        return playwrightMod;
+    }
+    // -- Session establishment (lazy, once per run) -----------------------
+    async function ensureSession(reg) {
+        const existing = sessions.peekSession(reg.spec.runId);
+        if (existing && existing.state !== "closed" && existing.state !== "crashed")
+            return existing;
+        if (reg.sessionInit)
+            return reg.sessionInit;
+        reg.sessionInit = (async () => {
+            const playwright = await pw();
+            const space = reg.spec.space ?? { kind: "ephemeral" };
+            const hooks = {
+                onViolation: (v) => {
+                    reg.violations.push({ url: v.url.slice(0, 300), code: v.code, surface: v.surface, at: Date.now() });
+                    if (reg.violations.length > 200)
+                        reg.violations.shift();
+                    log(`[authz] DENY ${v.code} (${v.surface}) ${v.url.slice(0, 120)}`);
+                },
+                isCancelled: () => reg.cancelled,
+            };
+            if (reg.spec.mode === "attach") {
+                const ws = String(reg.spec.cdpWsEndpoint || "");
+                if (!/^wss?:\/\/(127\.0\.0\.1|localhost|\[::1\])[:/]/.test(ws)) {
+                    throw new BridgeError("attach_endpoint_invalid", "attach requires a loopback CDP websocket endpoint");
+                }
+                const rec = sessions.createSession({
+                    runId: reg.spec.runId, ownership: "attached",
+                    engine: reg.spec.engine || "chromium", space,
+                });
+                try {
+                    const browser = await playwright.chromium.connectOverCDP(ws, { timeout: 15_000 });
+                    const context = browser.contexts()[0];
+                    if (!context)
+                        throw new BridgeError("attach_no_context", "attached browser exposes no context");
+                    sessions.attachHandles(rec, { browser, context });
+                    const page = context.pages()[0] ?? (await context.newPage());
+                    const lease = sessions.leaseTarget(rec, reg.spec.grant.target.ref, page);
+                    // Attach mode: enforce on the LEASED page (and its popups)
+                    // only — we do not take over routing for the user's whole
+                    // externally owned context (plan Section 7 ownership rule;
+                    // context-wide routing is applied on owned contexts below).
+                    await enforceOnPage(page, reg.policy, hooks);
+                    void lease;
+                    return rec;
+                }
+                catch (e) {
+                    rec.state = "crashed";
+                    await sessions.teardownRun(reg.spec.runId, "attach_failed");
+                    throw e instanceof BridgeError ? e : new BridgeError("attach_failed", String(e?.message || e));
+                }
+            }
+            // LAUNCH mode: dedicated profile, never the browser's default dir.
+            const engineId = (reg.spec.engine || "chrome");
+            const engine = await ensureEngine(engineId, { log });
+            const { dir: userDataDir, ephemeral } = spaceUserDataDir(space, reg.spec.runId);
+            const rec = sessions.createSession({
+                runId: reg.spec.runId, ownership: "owned", engine: engineId, space,
+            });
+            try {
+                const context = await playwright.chromium.launchPersistentContext(userDataDir, {
+                    executablePath: engine.executablePath,
+                    headless: reg.spec.headless === true,
+                    viewport: { width: 1280, height: 800 },
+                    acceptDownloads: false, // downloads default-denied (Section 10)
+                    args: [
+                        "--no-first-run",
+                        "--no-default-browser-check",
+                        "--disable-background-networking",
+                        "--disable-sync",
+                    ],
+                });
+                sessions.attachHandles(rec, {
+                    context,
+                    ephemeralUserDataDir: ephemeral ? userDataDir : null,
+                });
+                await enforceOnContext(context, reg.policy, hooks);
+                const page = context.pages()[0] ?? (await context.newPage());
+                sessions.leaseTarget(rec, reg.spec.grant.target.ref, page);
+                log(`browser session up: run=${reg.spec.runId.slice(0, 10)} engine=${engineId} owned profile=${space.kind}`);
+                return rec;
+            }
+            catch (e) {
+                rec.state = "crashed";
+                await sessions.teardownRun(reg.spec.runId, "launch_failed");
+                throw e instanceof BridgeError ? e : new BridgeError("launch_failed", String(e?.message || e));
+            }
+        })();
+        reg.sessionInit.catch(() => { reg.sessionInit = null; });
+        return reg.sessionInit;
+    }
+    async function getLease(reg) {
+        if (reg.cancelled)
+            throw new BridgeError("run_cancelled", "run was cancelled/torn down");
+        const rec = await ensureSession(reg);
+        sessions.touch(rec);
+        const lease = sessions.getLease(rec, reg.spec.grant.target.ref);
+        return { rec, lease };
+    }
+    async function getCdp(rec, page) {
+        const cached = cdpByPage.get(page);
+        if (cached)
+            return cached;
+        const context = rec.context;
+        const cdp = await context.newCDPSession(page);
+        cdpByPage.set(page, cdp);
+        page.on("close", () => cdpByPage.delete(page));
+        // Belt-and-suspenders: also disable WebRTC at the CDP level (the init
+        // script neutralises it in JS; this kills it at the browser level too).
+        void disableWebRtcViaCdp(cdp);
+        return cdp;
+    }
+    async function captureSnapshot(rec, lease, scope) {
+        const page = lease.page;
+        const generation = sessions.beginSnapshot(lease);
+        const frames = new Map();
+        frames.set("main", page.mainFrame());
+        frameMaps.set(lease, frames);
+        const viewport = page.viewportSize() ?? { width: 1280, height: 800 };
+        const collected = [];
+        // Main target: covers the top document + all SAME-PROCESS iframes
+        // (the flattened DOMSnapshot + AX tree include them) + shadow DOM
+        // (the AX tree pierces shadow roots natively).
+        try {
+            const cdp = await getCdp(rec, page);
+            await collectFromTarget(cdp, "main", { x: 0, y: 0 }, viewport, collected);
+        }
+        catch (e) {
+            if (opts.verbose)
+                log(`snapshot main-target failed: ${e?.message || e}`);
+        }
+        // OOPIF descent: frames living in other renderer processes have
+        // their own CDP targets; newCDPSession(frame) succeeds only for
+        // those (throws for same-process frames, which are already covered).
+        let frameIdx = 0;
+        for (const frame of page.frames()) {
+            if (frame === page.mainFrame())
+                continue;
+            frameIdx += 1;
+            let fcdp = null;
+            try {
+                fcdp = await rec.context.newCDPSession(frame);
+            }
+            catch {
+                continue; // same-process frame -> already in the main capture
+            }
+            try {
+                const el = await frame.frameElement().catch(() => null);
+                const box = el ? await el.boundingBox().catch(() => null) : null;
+                if (el)
+                    await el.dispose().catch(() => { });
+                if (!box)
+                    continue;
+                const key = `f${frameIdx}`;
+                frames.set(key, frame);
+                await collectFromTarget(fcdp, key, { x: box.x, y: box.y }, viewport, collected);
+            }
+            catch { /* skip this OOPIF, keep the rest */ }
+            finally {
+                await fcdp?.detach().catch(() => { });
+            }
+        }
+        // Scope filter (optional substring over role/name), rank, cap.
+        const scopeLc = (scope || "").trim().toLowerCase();
+        let candidates = scopeLc
+            ? collected.filter((n) => n.role.toLowerCase().includes(scopeLc) || n.name.toLowerCase().includes(scopeLc))
+            : collected;
+        const total = candidates.length;
+        candidates = candidates
+            .sort((a, b) => (Number(!(a.click || a.edit)) - Number(!(b.click || b.edit))) || a.order - b.order)
+            .slice(0, NODE_CAP)
+            .sort((a, b) => a.order - b.order);
+        // Bind refs and render one line per node.
+        const lines = [];
+        let refNo = 0;
+        for (const n of candidates) {
+            refNo += 1;
+            const ref = `@e${refNo}`;
+            sessions.bindRef(lease, {
+                ref,
+                targetRef: lease.ref,
+                frameKey: n.frameKey,
+                backendNodeId: n.backendNodeId,
+                snapshotGeneration: generation,
+                documentGeneration: lease.documentGeneration,
+                role: n.role,
+                name: n.name,
+            });
+            const flags = `${n.click ? " click" : ""}${n.edit ? " edit" : ""}${n.covered ? " COVERED" : ""}`;
+            const name = n.name ? ` "${n.name.slice(0, 80).replace(/"/g, "'")}"` : ' ""';
+            const aria = n.aria ? ` ~${n.aria.slice(0, 40)}` : "";
+            const domId = n.domId ? ` #${n.domId.slice(0, 40)}` : "";
+            const href = n.href ? ` @${n.href.slice(0, 100)}` : "";
+            lines.push(`${ref} <${n.role}>${flags}${name}${aria}${domId}${href} <${Math.round(n.l)},${Math.round(n.t)},${Math.round(n.r)},${Math.round(n.b)}>`);
+        }
+        const url = page.url();
+        const title = await page.title().catch(() => "");
+        const header = `url=${url} title=${title.slice(0, 120)} gen=${generation} nodes=${lines.length}/${total}`;
+        let tree = `${header}\n${lines.join("\n")}`;
+        if (lines.length <= 2) {
+            tree += `\n[vision] The page exposes almost no accessible nodes (canvas/video/empty page). Call POST /browser/screenshot and act with coordinates: {"kind":"click","x":0.5,"y":0.4,"unit":"fraction"} (fractions of the viewport) or CSS pixel x/y.`;
+        }
+        return { tree, generation, url, title, nodes: lines.length };
+    }
+    async function collectFromTarget(cdp, frameKey, frameOffset, viewport, out) {
+        const STYLE_FILTER = ["display", "visibility", "opacity"];
+        const [snap, ax] = await Promise.all([
+            cdp.send("DOMSnapshot.captureSnapshot", {
+                computedStyles: STYLE_FILTER,
+                includePaintOrder: true,
+            }),
+            (async () => {
+                await cdp.send("Accessibility.enable").catch(() => { });
+                return cdp.send("Accessibility.getFullAXTree", {});
+            })(),
+        ]);
+        const strings = snap.strings;
+        const docs = snap.documents;
+        // Per-document viewport offset: root = frameOffset - scroll; child
+        // (same-process iframe) = parentOffset + iframe bounds - child scroll.
+        const docOffset = docs.map(() => null);
+        if (docs.length > 0) {
+            docOffset[0] = {
+                x: frameOffset.x - (docs[0].scrollOffsetX ?? 0),
+                y: frameOffset.y - (docs[0].scrollOffsetY ?? 0),
+            };
+        }
+        const layoutByDoc = docs.map((d) => {
+            const m = new Map();
+            for (let i = 0; i < d.layout.nodeIndex.length; i++) {
+                const styleIdx = d.layout.styles[i] || [];
+                const sv = (k) => {
+                    const si = styleIdx[k];
+                    return si !== undefined && si >= 0 ? String(strings[si] ?? "") : "";
+                };
+                const display = sv(0);
+                const visibility = sv(1);
+                const opacity = sv(2);
+                m.set(d.layout.nodeIndex[i], {
+                    bounds: d.layout.bounds[i],
+                    hidden: display === "none" || visibility === "hidden" || visibility === "collapse",
+                    opacity0: opacity !== "" && Number(opacity) === 0,
+                    paintOrder: d.layout.paintOrders?.[i] ?? 0,
+                    nodeIndex: d.layout.nodeIndex[i],
+                });
+            }
+            return m;
+        });
+        // Resolve child-document offsets via contentDocumentIndex links.
+        for (let di = 0; di < docs.length; di++) {
+            const cdi = docs[di].nodes.contentDocumentIndex;
+            if (!cdi)
+                continue;
+            for (let k = 0; k < cdi.index.length; k++) {
+                const iframeNodeIdx = cdi.index[k];
+                const childDoc = cdi.value[k];
+                if (childDoc === di || childDoc >= docs.length)
+                    continue;
+                const parentOff = docOffset[di];
+                const hit = layoutByDoc[di].get(iframeNodeIdx);
+                if (!parentOff || !hit)
+                    continue;
+                docOffset[childDoc] = {
+                    x: parentOff.x + hit.bounds[0] - (docs[childDoc].scrollOffsetX ?? 0),
+                    y: parentOff.y + hit.bounds[1] - (docs[childDoc].scrollOffsetY ?? 0),
+                };
+            }
+        }
+        const domByBackendId = new Map();
+        const clickableByDoc = docs.map((d) => new Set(d.nodes.isClickable?.index ?? []));
+        for (let di = 0; di < docs.length; di++) {
+            const ids = docs[di].nodes.backendNodeId ?? [];
+            for (let ni = 0; ni < ids.length; ni++) {
+                domByBackendId.set(ids[ni], { doc: di, layout: layoutByDoc[di].get(ni) ?? null, nodeIdx: ni });
+            }
+        }
+        const attr = (di, ni, wanted) => {
+            const attrs = docs[di].nodes.attributes?.[ni] ?? [];
+            for (let i = 0; i + 1 < attrs.length; i += 2) {
+                if (strings[attrs[i]] === wanted)
+                    return String(strings[attrs[i + 1]] ?? "");
+            }
+            return "";
+        };
+        const isAncestor = (di, maybeAncestor, node) => {
+            const parents = docs[di].nodes.parentIndex ?? [];
+            let cur = node;
+            for (let hops = 0; hops < 500 && cur !== undefined && cur >= 0; hops++) {
+                if (cur === maybeAncestor)
+                    return true;
+                cur = parents[cur];
+            }
+            return false;
+        };
+        // AX walk (DFS from roots) in document order.
+        const axById = new Map();
+        for (const n of ax.nodes)
+            axById.set(n.nodeId, n);
+        const hasParent = new Set();
+        for (const n of ax.nodes)
+            for (const c of n.childIds ?? [])
+                hasParent.add(c);
+        const roots = ax.nodes.filter((n) => !hasParent.has(n.nodeId) && !n.parentId);
+        let order = out.length * 1000;
+        const seenBackend = new Set();
+        const visit = (n, depth) => {
+            if (!n || depth > 80)
+                return;
+            order += 1;
+            if (!n.ignored) {
+                const role = String(n.role?.value ?? "").toLowerCase();
+                const name = String(n.name?.value ?? "").trim();
+                const backendId = n.backendDOMNodeId;
+                if (backendId && !seenBackend.has(backendId)) {
+                    const dom = domByBackendId.get(backendId);
+                    const domClickable = dom ? clickableByDoc[dom.doc].has(dom.nodeIdx) : false;
+                    const click = CLICK_ROLES.has(role) || domClickable;
+                    const edit = EDIT_ROLES.has(role);
+                    const interesting = click || edit || (name.length > 0 && (CONTEXT_ROLES.has(role) || role === "iframe"));
+                    if (interesting && dom?.layout && !dom.layout.hidden && !dom.layout.opacity0) {
+                        const off = docOffset[dom.doc];
+                        if (off) {
+                            const [bx, by, bw, bh] = dom.layout.bounds;
+                            const l = bx + off.x, t = by + off.y, r = l + bw, b = t + bh;
+                            const inViewport = bw > 0 && bh > 0 && r > 0 && b > 0 && l < viewport.width && t < viewport.height;
+                            if (inViewport) {
+                                seenBackend.add(backendId);
+                                // COVERED heuristic: some non-ancestor, non-descendant
+                                // layout node with a HIGHER paint order fully contains
+                                // the center point. Conservative: any doubt -> not set.
+                                let covered = false;
+                                try {
+                                    const cx = bx + bw / 2, cy = by + bh / 2;
+                                    for (const hit of layoutByDoc[dom.doc].values()) {
+                                        if (hit.nodeIndex === dom.nodeIdx || hit.hidden || hit.opacity0)
+                                            continue;
+                                        if (hit.paintOrder <= (dom.layout.paintOrder))
+                                            continue;
+                                        const [hx, hy, hw, hh] = hit.bounds;
+                                        if (cx >= hx && cx <= hx + hw && cy >= hy && cy <= hy + hh) {
+                                            if (!isAncestor(dom.doc, hit.nodeIndex, dom.nodeIdx) && !isAncestor(dom.doc, dom.nodeIdx, hit.nodeIndex)) {
+                                                covered = true;
+                                                break;
+                                            }
+                                        }
+                                    }
+                                }
+                                catch { /* unknown -> leave uncovered (conservative) */ }
+                                out.push({
+                                    frameKey,
+                                    backendNodeId: backendId,
+                                    role: role || "node",
+                                    name,
+                                    aria: String(n.description?.value ?? "").trim(),
+                                    domId: attr(dom.doc, dom.nodeIdx, "id"),
+                                    href: role === "link" ? attr(dom.doc, dom.nodeIdx, "href") : "",
+                                    click, edit, covered,
+                                    l, t, r, b,
+                                    order,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            for (const cid of n.childIds ?? [])
+                visit(axById.get(cid), depth + 1);
+        };
+        for (const root of roots)
+            visit(root, 0);
+    }
+    // -- Screenshot (recompress, NEVER slice base64) -----------------------
+    async function takeScreenshot(lease) {
+        const page = lease.page;
+        // Quality ladder: recompress smaller instead of truncating. scale:
+        // "css" downscales HiDPI captures to CSS-pixel resolution.
+        for (const quality of [60, 40, 25, 12]) {
+            const buf = await page.screenshot({ type: "jpeg", quality, fullPage: false, scale: "css", timeout: 15_000 });
+            const b64 = buf.toString("base64");
+            if (b64.length <= SCREENSHOT_MAX_B64 || quality === 12) {
+                return { image_b64: b64, media_type: "image/jpeg" };
+            }
+        }
+        throw new BridgeError("screenshot_failed", "unreachable");
+    }
+    async function resolveActionPoint(reg, rec, lease, args) {
+        const page = lease.page;
+        const viewport = page.viewportSize() ?? { width: 1280, height: 800 };
+        if (args.ref) {
+            const binding = sessions.resolveRef(lease, args.ref);
+            const frames = frameMaps.get(lease);
+            const frame = frames?.get(binding.frameKey);
+            // Element center via CDP box model on the owning target, plus the
+            // frame's main-viewport offset for OOPIFs.
+            let localCdp;
+            let offset = { x: 0, y: 0 };
+            let detachAfter = false;
+            if (binding.frameKey === "main" || !frame) {
+                localCdp = await getCdp(rec, page);
+            }
+            else {
+                localCdp = await rec.context.newCDPSession(frame);
+                detachAfter = true;
+                const el = await frame.frameElement().catch(() => null);
+                const box = el ? await el.boundingBox().catch(() => null) : null;
+                if (el)
+                    await el.dispose().catch(() => { });
+                if (box)
+                    offset = { x: box.x, y: box.y };
+            }
+            try {
+                await localCdp.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: binding.backendNodeId }).catch(() => { });
+                const bm = await localCdp.send("DOM.getBoxModel", { backendNodeId: binding.backendNodeId });
+                const q = bm.model.content; // 4 corner points, viewport coords of the owning target
+                const cx = (q[0] + q[2] + q[4] + q[6]) / 4 + offset.x;
+                const cy = (q[1] + q[3] + q[5] + q[7]) / 4 + offset.y;
+                return { x: cx, y: cy };
+            }
+            finally {
+                if (detachAfter)
+                    await localCdp.detach().catch(() => { });
+            }
+        }
+        if (typeof args.x === "number" && typeof args.y === "number") {
+            const fraction = args.unit === "fraction" || (args.x >= 0 && args.x <= 1 && args.y >= 0 && args.y <= 1);
+            return fraction
+                ? { x: args.x * viewport.width, y: args.y * viewport.height }
+                : { x: args.x, y: args.y };
+        }
+        throw new BridgeError("act_args_invalid", `kind '${args.kind}' needs a ref or x/y coordinates`);
+    }
+    async function performAct(reg, args) {
+        const kind = String(args.kind || "");
+        if (!(kind in KIND_MIN_EFFECT)) {
+            throw new BridgeError("act_kind_unknown", `unknown act kind '${kind}'`);
+        }
+        // Grant second gate: declared effect (if the tool layer classified
+        // one) AND the kind's minimum effect must both clear the grant.
+        const effects = new Set([KIND_MIN_EFFECT[kind]]);
+        if (args.effect)
+            effects.add(String(args.effect));
+        for (const eff of effects) {
+            const d = checkEffect(eff, reg.spec.grant);
+            if (!d.allowed)
+                throw new BridgeError(d.code, d.message);
+        }
+        const { rec, lease } = await getLease(reg);
+        return sessions.runOnTarget(lease, async () => {
+            if (reg.cancelled)
+                throw new BridgeError("run_cancelled", "run was cancelled/torn down");
+            const page = lease.page;
+            switch (kind) {
+                case "navigate": {
+                    const url = String(args.url || "");
+                    const d = await evaluateUrlResolved(url, reg.policy);
+                    if (!d.allowed)
+                        throw new BridgeError(d.code, d.message);
+                    await page.goto(url, { waitUntil: "domcontentloaded", timeout: NAV_TIMEOUT_MS });
+                    return { navigated: page.url() };
+                }
+                case "back": {
+                    await page.goBack({ waitUntil: "domcontentloaded", timeout: NAV_TIMEOUT_MS }).catch(() => { });
+                    return { url: page.url() };
+                }
+                case "forward": {
+                    await page.goForward({ waitUntil: "domcontentloaded", timeout: NAV_TIMEOUT_MS }).catch(() => { });
+                    return { url: page.url() };
+                }
+                case "click":
+                case "dblclick":
+                case "hover": {
+                    const pt = await resolveActionPoint(reg, rec, lease, args);
+                    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) } };
+                }
+                case "input_text": {
+                    const text = String(args.text ?? args.value ?? "");
+                    if (text.length > 20_000)
+                        throw new BridgeError("act_args_invalid", "text exceeds 20000 chars");
+                    const pt = await resolveActionPoint(reg, rec, lease, args);
+                    await page.mouse.click(pt.x, pt.y);
+                    // Clear-then-type: select-all + type preserves site key handlers.
+                    await page.keyboard.press(process.platform === "darwin" ? "Meta+A" : "Control+A").catch(() => { });
+                    await page.keyboard.type(text, { delay: 8 });
+                    return { typed: text.length };
+                }
+                case "press_key": {
+                    const key = String(args.key || "");
+                    if (!/^[A-Za-z0-9+]{1,32}$/.test(key))
+                        throw new BridgeError("act_args_invalid", `invalid key '${key}'`);
+                    await page.keyboard.press(key);
+                    return { pressed: key };
+                }
+                case "scroll": {
+                    if (args.ref) {
+                        const binding = sessions.resolveRef(lease, args.ref);
+                        const cdp = await getCdp(rec, page);
+                        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 };
+                }
+                case "select_option": {
+                    if (!args.ref)
+                        throw new BridgeError("act_args_invalid", "select_option requires a ref");
+                    const binding = sessions.resolveRef(lease, args.ref);
+                    const value = String(args.value ?? "");
+                    const cdp = await getCdp(rec, page);
+                    const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId });
+                    await cdp.send("Runtime.callFunctionOn", {
+                        objectId: resolved.object.objectId,
+                        functionDeclaration: `function(v){ this.value = v; this.dispatchEvent(new Event('input',{bubbles:true})); this.dispatchEvent(new Event('change',{bubbles:true})); }`,
+                        arguments: [{ value }],
+                    });
+                    return { selected: value };
+                }
+                case "wait": {
+                    const ms = Math.min(Math.max(0, Number(args.ms ?? 500)), 15_000);
+                    await page.waitForTimeout(ms);
+                    return { waited: ms };
+                }
+                default:
+                    throw new BridgeError("act_kind_unknown", `unhandled kind '${kind}'`);
+            }
+        });
+    }
+    async function actAndObserve(reg, args) {
+        const result = await performAct(reg, args);
+        const { rec, lease } = await getLease(reg);
+        await lease.page.waitForLoadState("domcontentloaded", { timeout: 5_000 }).catch(() => { });
+        await lease.page.waitForTimeout(ACT_SETTLE_MS);
+        const snap = await captureSnapshot(rec, lease);
+        return { ok: true, result, tree: snap.tree, generation: snap.generation };
+    }
+    // -- Governed facade for the code worker --------------------------------
+    function buildFacade(reg) {
+        return async (op, args) => {
+            if (reg.cancelled)
+                throw new BridgeError("run_cancelled", "run was cancelled/torn down");
+            switch (op) {
+                case "current_target": {
+                    const { lease } = await getLease(reg);
+                    return currentTarget(reg, lease);
+                }
+                case "get_screen_tree": {
+                    const { rec, lease } = await getLease(reg);
+                    const snap = await captureSnapshot(rec, lease, typeof args["scope"] === "string" ? args["scope"] : undefined);
+                    return snap;
+                }
+                case "screenshot": {
+                    const { lease } = await getLease(reg);
+                    return takeScreenshot(lease);
+                }
+                case "act":
+                    return actAndObserve(reg, args);
+                case "wait": {
+                    const { lease } = await getLease(reg);
+                    const ms = Math.min(Math.max(0, Number(args["ms"] ?? 500)), 10_000);
+                    await lease.page.waitForTimeout(ms);
+                    return { waited: ms };
+                }
+                default:
+                    throw new BridgeError("facade_op_unknown", `op '${op}' is not part of the governed facade`);
+            }
+        };
+    }
+    function currentTarget(reg, lease) {
+        let origin = "";
+        try {
+            origin = new URL(lease.page.url()).origin;
+        }
+        catch {
+            origin = "";
+        }
+        return {
+            ok: true,
+            target: {
+                ref: lease.ref,
+                origin,
+                // Title is optional metadata; kept local-only (never persisted
+                // by the runner) per plan Section 10 target-metadata rule.
+                title: undefined,
+            },
+        };
+    }
+    // sessionId -> WatchLease
+    const watchLeases = new Map();
+    function postFrame(lease, jpegB64) {
+        // 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 url = lease.framePostUrl;
+        try {
+            const u = new URL(url);
+            const isHttps = u.protocol === "https:";
+            const req = (isHttps ? httpsRequest : httpRequest)({
+                hostname: u.hostname,
+                port: u.port || (isHttps ? 443 : 80),
+                path: u.pathname + u.search,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Content-Length": Buffer.byteLength(body),
+                    "Authorization": lease.runAuthHeader,
+                },
+            }, (res) => { res.resume(); /* drain */ });
+            req.on("error", () => { });
+            req.end(body);
+        }
+        catch {
+            // URL parse or socket error — silently skip this frame.
+        }
+    }
+    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);
+            const changed = jpegB64 !== lease.lastJpegB64;
+            if (changed) {
+                lease.lastJpegB64 = jpegB64;
+                postFrame(lease, jpegB64);
+            }
+            // 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
+            // so the viewer sees a heartbeat even on a static page.
+            const nextMs = changed ? 250 : 500;
+            if (lease.active) {
+                lease.timer = setTimeout(() => { void captureAndSchedule(lease); }, nextMs);
+            }
+        }
+        catch {
+            // Screenshot failed (page crashed, navigating, etc.) — retry later.
+            if (lease.active) {
+                lease.timer = setTimeout(() => { void captureAndSchedule(lease); }, 1000);
+            }
+        }
+    }
+    function stopWatchLease(sessionId) {
+        const lease = watchLeases.get(sessionId);
+        if (!lease)
+            return;
+        lease.active = false;
+        if (lease.timer) {
+            clearTimeout(lease.timer);
+            lease.timer = null;
+        }
+        watchLeases.delete(sessionId);
+    }
+    function setWatchLease(sessionId, active, framePostUrl, runAuthHeader) {
+        if (!active) {
+            stopWatchLease(sessionId);
+            return;
+        }
+        // Find which runId corresponds to this sessionId (session ids map 1:1
+        // to runIds in Phase 1 — one session per run).
+        let 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;
+            }
+        }
+        if (!matchedRunId) {
+            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.
+        stopWatchLease(sessionId);
+        const lease = {
+            runId: matchedRunId,
+            sessionId,
+            framePostUrl,
+            runAuthHeader,
+            active: true,
+            timer: null,
+            lastJpegB64: "",
+        };
+        watchLeases.set(sessionId, lease);
+        log(`[watch] frame producer started for session ${sessionId.slice(0, 16)} run=${matchedRunId.slice(0, 10)}`);
+        void captureAndSchedule(lease);
+    }
+    // -- HTTP shell ---------------------------------------------------------
+    const server = createServer(async (req, res) => {
+        res.setHeader("X-Frame-Options", "DENY");
+        res.setHeader("Cache-Control", "no-store");
+        res.setHeader("Content-Type", "application/json");
+        const respond = (status, body) => {
+            res.statusCode = status;
+            res.end(JSON.stringify(body));
+        };
+        const fail = (status, code, message) => respond(status, { ok: false, error: { code, message } });
+        if (req.method !== "POST")
+            return fail(405, "method_not_allowed", "POST only");
+        // Per-run bearer token, constant-time compare.
+        const auth = String(req.headers["authorization"] || "");
+        const reg = findRegistrationByAuth(auth);
+        if (!reg)
+            return fail(401, "unauthorized", "missing or unknown bearer token");
+        if (reg.cancelled)
+            return fail(410, "run_cancelled", "run was torn down");
+        // Grants are short-lived; the SESSION may outlive grant exp (leases
+        // have their own TTLs) but ops after exp + tolerance are refused so
+        // a leaked token cannot outlive its authorization.
+        if (Date.now() / 1000 > reg.spec.grant.exp + 30) {
+            return fail(403, "grant_expired", "the browser grant for this run has expired");
+        }
+        const route = req.url || "";
+        let payload;
+        try {
+            payload = await readJsonBody(req);
+        }
+        catch (e) {
+            const code = e?.code || "invalid_json";
+            return fail(code === "payload_too_large" ? 413 : 400, code, String(e?.message || e));
+        }
+        try {
+            switch (route) {
+                case "/browser/current_target": {
+                    const { lease } = await getLease(reg);
+                    return respond(200, currentTarget(reg, lease));
+                }
+                case "/browser/get_screen_tree": {
+                    const { rec, lease } = await getLease(reg);
+                    const snap = await captureSnapshot(rec, lease, typeof payload["scope"] === "string" ? String(payload["scope"]) : undefined);
+                    return respond(200, { ok: true, ...snap });
+                }
+                case "/browser/screenshot": {
+                    const { lease } = await getLease(reg);
+                    const shot = await takeScreenshot(lease);
+                    return respond(200, { ok: true, ...shot });
+                }
+                case "/browser/act": {
+                    const out = await actAndObserve(reg, payload);
+                    return respond(200, out);
+                }
+                case "/browser/run": {
+                    if (!reg.spec.codeMode) {
+                        return fail(403, "code_mode_disabled", "code mode is not enabled for this run (Phase 2 capability)");
+                    }
+                    const script = String(payload["script"] || "");
+                    if (!script.trim())
+                        return fail(400, "script_missing", "body.script is required");
+                    if (script.length > 64 * 1024)
+                        return fail(413, "script_too_large", "script exceeds 64KB");
+                    const scratch = join(tmpdir(), `melaya-codeworker-${reg.spec.runId}`);
+                    mkdirSync(scratch, { recursive: true });
+                    const result = await runSandboxedScript({
+                        script,
+                        scratchDir: scratch,
+                        facade: buildFacade(reg),
+                        onTrace: (t) => {
+                            reg.traces.push(t);
+                            if (reg.traces.length > 500)
+                                reg.traces.shift();
+                            if (opts.verbose)
+                                log(`[code-worker trace] #${t.seq} ${t.op} ${t.ok ? "ok" : `FAIL ${t.error}`} (${t.ms}ms)`);
+                        },
+                        log: (m) => opts.verbose && log(m),
+                    });
+                    // Fresh observation after the script, per the run contract.
+                    let tree = "";
+                    try {
+                        const { rec, lease } = await getLease(reg);
+                        tree = (await captureSnapshot(rec, lease)).tree;
+                    }
+                    catch { /* session may have crashed mid-script */ }
+                    return respond(200, {
+                        ok: result.ok,
+                        result: result.result ?? null,
+                        console: result.console,
+                        tree,
+                        traces: result.traces,
+                        sandbox: result.sandbox,
+                        ...(result.error ? { error: result.error } : {}),
+                    });
+                }
+                default:
+                    return fail(404, "not_found", `unknown route ${route}`);
+            }
+        }
+        catch (e) {
+            if (e instanceof SessionError)
+                return fail(409, e.code, e.message);
+            if (e instanceof BridgeError)
+                return fail(422, e.code, e.message);
+            const msg = String(e?.message || e);
+            log(`bridge internal error on ${route}: ${msg}`);
+            return fail(500, "bridge_error", msg.slice(0, 500));
+        }
+    });
+    function findRegistrationByAuth(authHeader) {
+        if (!authHeader.startsWith("Bearer "))
+            return null;
+        const presented = Buffer.from(authHeader.slice(7));
+        for (const [token, reg] of byToken) {
+            const expected = Buffer.from(token);
+            if (presented.length === expected.length && timingSafeEqual(presented, expected))
+                return reg;
+        }
+        return null;
+    }
+    async function readJsonBody(req) {
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of req) {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES)
+                throw new BridgeError("payload_too_large", `body exceeds ${MAX_BODY_BYTES} bytes`);
+            chunks.push(chunk);
+        }
+        if (total === 0)
+            return {};
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+        }
+        catch {
+            throw new BridgeError("invalid_json", "body is not valid JSON");
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new BridgeError("invalid_json", "body must be a JSON object");
+        }
+        return parsed;
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === "string") {
+        server.close();
+        throw new BridgeError("bridge_listen_failed", "could not bind the browser bridge to 127.0.0.1");
+    }
+    const port = addr.port;
+    log(`browser bridge listening on http://127.0.0.1:${port}`);
+    const registerRun = (spec) => {
+        if (byRunId.has(spec.runId)) {
+            throw new BridgeError("duplicate_run", `run ${spec.runId} is already registered on the bridge`);
+        }
+        const token = randomBytes(24).toString("hex");
+        const reg = {
+            spec,
+            token,
+            policy: buildOriginPolicy(spec.grant.originScopes),
+            cancelled: false,
+            violations: [],
+            sessionInit: null,
+            traces: [],
+        };
+        byToken.set(token, reg);
+        byRunId.set(spec.runId, reg);
+        log(`browser run registered: ${spec.runId.slice(0, 10)} mode=${spec.mode} engine=${spec.engine || "chrome"} scopes=${spec.grant.originScopes.length} ceiling=${spec.grant.effectCeiling}`);
+        return { token };
+    };
+    const teardownRun = async (runId, reason) => {
+        const reg = byRunId.get(runId);
+        if (!reg)
+            return;
+        reg.cancelled = true; // cancels in-flight ops at their gates
+        byRunId.delete(runId);
+        byToken.delete(reg.token);
+        // Stop any active watch-lease frame producer for this run so the
+        // periodic screenshot timer does not fire on a dead session.
+        for (const [sid, lease] of watchLeases) {
+            if (lease.runId === runId)
+                stopWatchLease(sid);
+        }
+        await sessions.teardownRun(runId, reason);
+        // The grant object becomes unreachable here (revocation-by-forget:
+        // the jti was already burned at verification, the claims held only
+        // in this registration are dropped, and the bearer token dies).
+        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)));
+    };
+    return {
+        url: `http://127.0.0.1:${port}`,
+        port,
+        registerRun,
+        teardownRun,
+        teardownAll,
+        hasRun(runId) {
+            return byRunId.has(runId);
+        },
+        setWatchLease,
+        async shutdown() {
+            // Stop all watch-lease producers before closing sessions.
+            for (const sid of [...watchLeases.keys()])
+                stopWatchLease(sid);
+            await teardownAll("bridge_shutdown");
+            sessions.dispose();
+            await new Promise((r) => server.close(() => r()));
+        },
+    };
+}
+// ---------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------
+export class BridgeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "BridgeError";
+        this.code = code;
+    }
+}