amalgm 0.1.89 → 0.1.90

package/runtime/scripts/amalgm-mcp/browser/engine.js

@@ -1,60 +1,122 @@
 'use strict';
 
 /**
- * Browser engine: the verb set behind the browser/cua/recorder tools, with
- * backend routing.
+ * Browser engine: the verb set behind the browser toolbox entry, with
+ * deterministic backend routing by entrypoint.
  *
- * Backends, in order of preference:
- *  1. "attached"  — agent-browser connected over CDP to the Amalgm desktop
- *     app's visible in-tab webview. Requires the Electron bridge file to
- *     advertise a cdpUrl (or AMALGM_BROWSER_CDP_URL). Full agent-browser
- *     power against the splitscreen surface the user can see.
- *  2. "electron"  — legacy HTTP bridge into the desktop app's webview. Covers
- *     the core verbs; no CLI passthrough.
- *  3. "cli"       — standalone agent-browser session (headed window on
- *     desktop, headless on servers).
+ * Backends — exactly two:
+ *  1. "attached" — agent-browser connected over CDP to a visible chromium.
+ *     On desktop that is the Amalgm app's own webContents: the app enables
+ *     remote debugging on localhost and advertises its CDP URL in
+ *     electron-browser-bridge.json under the runtime state dir. The engine
+ *     attaches, asks the UI (via a browser_surfaces state event) to open the
+ *     in-tab split view, and selects that webview target — so commands drive
+ *     the surface the user is watching. An explicit AMALGM_BROWSER_CDP_URL
+ *     attaches to any other CDP endpoint the same way.
+ *  2. "cli" — standalone agent-browser chromium, headless. The deterministic
+ *     path for npm-only machines, servers, and the web entrypoint.
+ *
+ * The rule: a CDP advertisement (env or fresh bridge file) ⇒ attached;
+ * otherwise ⇒ cli. AMALGM_BROWSER_BACKEND forces a backend for debugging.
  *
  * Sessions map to durable profiles; the default session for a tool call is
  * the caller's chat session, so one conversation keeps one browser.
  */
 
-const electron = require('./electron-bridge');
 const cli = require('./cli');
 
 const attachedSessions = new Set();
 const knownSessions = new Map();
 
-function isPackagedDesktopRuntime() {
-  const execPath = process.execPath || '';
-  return process.env.ELECTRON_RUN_AS_NODE === '1' && execPath.includes('.app/Contents/MacOS/');
+const SURFACE_EVENT_RESOURCE = 'browser_surfaces';
+const WEBVIEW_MARKER_PREFIX = 'amalgm-bsid-';
+const WEBVIEW_WAIT_MS = 15_000;
+const WEBVIEW_POLL_MS = 500;
+
+// ---------------------------------------------------------------------------
+// Backend routing
+// ---------------------------------------------------------------------------
+
+function pidIsRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return Boolean(err && err.code === 'EPERM');
+  }
 }
 
-function cdpUrl() {
-  if (process.env.AMALGM_BROWSER_CDP_URL) return process.env.AMALGM_BROWSER_CDP_URL;
+/**
+ * Bridge advertisement candidates, most specific first. Every runtime
+ * generation can find the file written by the desktop app:
+ *  - Electron-spawned and LaunchAgent runtimes have AMALGM_RUNTIME_STATE_DIR;
+ *  - runtimes with only AMALGM_DIR (+ label) derive the same path;
+ *  - bare dev runtimes fall back to the unscoped roots.
+ */
+function bridgeFileCandidates() {
+  const path = require('path');
+  const os = require('os');
+  const dirs = [];
+  if (process.env.AMALGM_RUNTIME_STATE_DIR) dirs.push(process.env.AMALGM_RUNTIME_STATE_DIR);
+  const amalgmDir = process.env.AMALGM_DIR;
+  const label = process.env.AMALGM_RUNTIME_LABEL || process.env.AMALGM_BRANCH;
+  if (amalgmDir && label) dirs.push(path.join(amalgmDir, 'runtimes', label));
+  if (amalgmDir) dirs.push(amalgmDir);
+  dirs.push(path.join(os.homedir(), '.amalgm'));
+  return [...new Set(dirs)].map((dir) => path.join(dir, 'electron-browser-bridge.json'));
+}
+
+function readBridgeAdvertisement() {
+  const fs = require('fs');
+  for (const file of bridgeFileCandidates()) {
+    try {
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (typeof data?.cdpUrl !== 'string' || !data.cdpUrl) continue;
+      if (typeof data?.pid === 'number' && !pidIsRunning(data.pid)) continue;
+      return { cdpUrl: data.cdpUrl, cdpPort: data.cdpPort, label: data.label, file };
+    } catch {}
+  }
+  return null;
+}
+
+/** Reduce a CDP url/port advertisement to the value agent-browser's --cdp flag takes. */
+function cdpFlagValue(input) {
+  const raw = String(input || '').trim();
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) return raw;
   try {
-    const fs = require('fs');
-    const path = require('path');
-    const file = path.join(cli.amalgmDir(), 'electron-browser-bridge.json');
-    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (typeof data?.cdpUrl === 'string' && data.cdpUrl) return data.cdpUrl;
-    if (Number.isInteger(data?.cdpPort) && data.cdpPort > 0) return String(data.cdpPort);
+    const url = new URL(raw);
+    if (url.port) return url.port;
   } catch {}
-  return null;
+  return raw;
+}
+
+/**
+ * The CDP endpoint for attached mode, as a --cdp flag value. agent-browser's
+ * `connect` command launches a managed browser; raw --cdp attach is the mode
+ * that discovers Electron <webview> targets, so that is all we use.
+ */
+function cdpEndpoint() {
+  if (process.env.AMALGM_BROWSER_CDP_URL) return cdpFlagValue(process.env.AMALGM_BROWSER_CDP_URL);
+  const advertisement = readBridgeAdvertisement();
+  if (!advertisement) return null;
+  if (advertisement.cdpPort) return String(advertisement.cdpPort);
+  return cdpFlagValue(advertisement.cdpUrl);
 }
 
 function mode() {
   const requested = (process.env.AMALGM_BROWSER_BACKEND || '').toLowerCase();
-  if (requested === 'agent-browser' || requested === 'external' || requested === 'cli') return 'cli';
-  if (requested === 'electron') return 'electron';
-
-  if (electron.isConfigured() || isPackagedDesktopRuntime()) {
-    return cdpUrl() ? 'attached' : 'electron';
-  }
-  return 'cli';
+  if (['agent-browser', 'external', 'cli', 'headless'].includes(requested)) return 'cli';
+  if (['attached', 'cdp', 'electron'].includes(requested)) return 'attached';
+  return cdpEndpoint() ? 'attached' : 'cli';
 }
 
-function usesElectronBridge() {
-  return mode() === 'electron';
+/** Options every cli call needs for the current backend. */
+function cliOptions(session, extra = {}) {
+  const options = { session, ...extra };
+  if (mode() === 'attached') options.cdp = cdpEndpoint();
+  return options;
 }
 
 function sessionFor(args = {}, context = {}) {
@@ -94,34 +156,154 @@ function sessionInfo(session, extra = {}) {
   return info;
 }
 
+// ---------------------------------------------------------------------------
+// Attached mode: surface open + webview target selection
+// ---------------------------------------------------------------------------
+
+/**
+ * Ask the UI to open the in-tab browser surface for this session. Published
+ * on the runtime state-event bus; ChatView subscribes to browser_surfaces
+ * and mounts the split-view webview with a marker URL the target scan below
+ * can recognize.
+ */
+function requestSurfaceOpen(session, context) {
+  try {
+    const { appendStateEvent } = require('../state/events');
+    appendStateEvent({
+      resource: SURFACE_EVENT_RESOURCE,
+      op: 'insert',
+      id: session,
+      value: {
+        browserSessionId: session,
+        callerSessionId: context?.callerSessionId || null,
+        marker: `${WEBVIEW_MARKER_PREFIX}${session}`,
+        requestedAt: new Date().toISOString(),
+      },
+      source: 'browser-engine',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listWebviewTabs(session) {
+  const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
+  const list = tabs?.data?.tabs || tabs?.tabs || [];
+  return list.filter((tab) => tab.type === 'webview');
+}
+
+function matchWebview(webviews, session) {
+  const marker = `${WEBVIEW_MARKER_PREFIX}${session}`;
+  const byMarker = webviews.find((tab) => String(tab.url || '').includes(marker)
+    || String(tab.title || '').includes(marker));
+  if (byMarker) return byMarker;
+  const previous = knownSessions.get(session)?.webviewTabId;
+  if (previous) {
+    const byPrevious = webviews.find((tab) => tab.tabId === previous);
+    if (byPrevious) return byPrevious;
+  }
+  if (webviews.length === 1) return webviews[0];
+  return null;
+}
+
 /**
- * In attached mode, connect the session to the desktop app's chromium on
- * first use and select the in-tab webview target so commands drive the
- * surface the user is looking at.
+ * In attached mode, connect the session to the advertised chromium on first
+ * use and select the in-tab webview target so commands drive the surface the
+ * user is looking at. Fails closed: if no webview target can be found we
+ * error with instructions instead of silently driving the outer app window.
  */
-async function ensureReady(session) {
+async function ensureReady(session, context) {
   if (mode() !== 'attached' || attachedSessions.has(session)) return;
-  const target = cdpUrl();
-  await cli.runCli(['connect', target], { session });
+
+  let webviews = await listWebviewTabs(session);
+  let selected = matchWebview(webviews, session);
+
+  if (!selected) {
+    requestSurfaceOpen(session, context);
+    const deadline = Date.now() + WEBVIEW_WAIT_MS;
+    while (!selected && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
+      webviews = await listWebviewTabs(session);
+      selected = matchWebview(webviews, session);
+    }
+  }
+
+  if (!selected && webviews.length === 0 && process.env.AMALGM_BROWSER_CDP_URL) {
+    // Explicit external CDP endpoints (plain chromium) have page targets,
+    // not webviews — drive whatever the daemon selected by default.
+    attachedSessions.add(session);
+    return;
+  }
+
+  if (!selected) {
+    throw new Error(
+      'Browser surface did not open in the desktop app. '
+      + 'Retry, or force a headless browser with AMALGM_BROWSER_BACKEND=cli.',
+    );
+  }
+
+  await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+  await focusWebviewHost(session, selected);
+  knownSessions.set(session, { ...knownSessions.get(session), webviewTabId: selected.tabId });
+  attachedSessions.add(session);
+}
+
+/**
+ * Chromium drops CDP Input events to an Electron <webview> guest until the
+ * guest widget has focus (verified live: clicks report success but never
+ * land). One focus pass after target selection fixes input for the session:
+ * focus the <webview> element from the embedder page, then self-focus the
+ * guest. Best-effort — failures leave snapshot/eval working regardless.
+ */
+async function focusWebviewHost(session, selected) {
+  const marker = `${WEBVIEW_MARKER_PREFIX}${session}`;
   try {
-    const tabs = await cli.runCli(['tab'], { session, timeoutMs: 15_000 });
+    const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
     const list = tabs?.data?.tabs || tabs?.tabs || [];
-    const webview = list.find((tab) => tab.type === 'webview');
-    if (webview?.tabId) await cli.runCli(['tab', webview.tabId], { session, timeoutMs: 15_000 });
+    const outer = list.find((tab) => tab.type === 'page');
+    if (outer) {
+      const script = `(() => {
+        const views = [...document.querySelectorAll('webview')];
+        const target = views.find((w) => (w.getAttribute('src') || '').includes(${JSON.stringify(marker)}))
+          || views.find((w) => (w.src || '') === ${JSON.stringify(String(selected.url || ''))})
+          || views[views.length - 1];
+        if (target) target.focus();
+        return views.length;
+      })()`;
+      await cli.runCli(['tab', outer.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+      await cli.runCli(['eval', script], cliOptions(session, { timeoutMs: 15_000 }));
+      await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+    }
+    await cli.runCli(['eval', 'window.focus()'], cliOptions(session, { timeoutMs: 15_000 }));
   } catch {
-    // No webview target yet — the outer page target still works.
+    // Snapshot/eval still work without focus; input may need a retry.
   }
-  attachedSessions.add(session);
+}
+
+function looksLikeLostConnection(err) {
+  return /clos|connect|target|socket|detach/i.test(String(err?.message || err || ''));
 }
 
 async function run(session, commandArgs, options = {}) {
-  await ensureReady(session);
-  return cli.runCli(commandArgs, { session, ...options });
+  const { context, ...cliExtra } = options;
+  await ensureReady(session, context);
+  try {
+    return await cli.runCli(commandArgs, cliOptions(session, cliExtra));
+  } catch (err) {
+    if (mode() === 'attached' && attachedSessions.has(session) && looksLikeLostConnection(err)) {
+      // The app restarted or the webview remounted; re-attach once.
+      attachedSessions.delete(session);
+      await ensureReady(session, context);
+      return cli.runCli(commandArgs, cliOptions(session, cliExtra));
+    }
+    throw err;
+  }
 }
 
 async function readText(session, commandArgs, timeoutMs) {
   await ensureReady(session);
-  return cli.readText(commandArgs, session, timeoutMs);
+  return cli.readText(commandArgs, session, timeoutMs, mode() === 'attached' ? cdpEndpoint() : null);
 }
 
 /**
@@ -141,20 +323,12 @@ function findArgs(target, action, value) {
   return command;
 }
 
-function electronLocator(target) {
-  if (target.startsWith('@')) return { ref: target };
-  if (target.startsWith('text=')) return { text: target.slice('text='.length) };
-  return { selector: target };
-}
-
 // ---------------------------------------------------------------------------
 // Core verbs
 // ---------------------------------------------------------------------------
 
 async function state(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) return electron.stateBrowser({ browserSessionId: session }, context);
-
   let url = '';
   let title = '';
   try { url = await readText(session, ['get', 'url']); } catch {}
@@ -164,39 +338,24 @@ async function state(args = {}, context) {
 
 async function open(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    const result = await electron.navigateBrowser({ url: args.url, browserSessionId: session }, context);
-    return sessionInfo(session, { url: result.url || args.url, title: result.title || '' });
-  }
-  await run(session, ['open', args.url]);
+  await run(session, ['open', args.url], { context });
   return state(args, context);
 }
 
 async function snapshot(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    const result = await electron.snapshotBrowser({ browserSessionId: session }, context);
-    return sessionInfo(session, {
-      url: result.url,
-      title: result.title,
-      snapshotText: result.snapshotText || result.snapshot || '',
-    });
-  }
-  const result = await run(session, ['snapshot', '-i'], { timeoutMs: 30_000 });
+  const result = await run(session, ['snapshot', '-i'], { timeoutMs: 30_000, context });
   const current = await state(args, context);
   return { ...current, snapshotText: cli.asText(result) };
 }
 
 async function screenshot(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    return electron.screenshotBrowser({ browserSessionId: session, fullPage: args.fullPage }, context);
-  }
   const fs = require('fs');
   const path = require('path');
   const crypto = require('crypto');
   const file = path.join(cli.screenshotDir(), `${session}-${Date.now()}-${crypto.randomUUID()}.png`);
-  await run(session, ['screenshot', ...(args.fullPage ? ['--full'] : []), file]);
+  await run(session, ['screenshot', ...(args.fullPage ? ['--full'] : []), file], { context });
   const buffer = fs.readFileSync(file);
   return {
     ...sessionInfo(session),
@@ -210,13 +369,9 @@ async function screenshot(args = {}, context) {
 async function click(args = {}, context) {
   const session = sessionFor(args, context);
   const target = String(args.target || '');
-  if (usesElectronBridge()) {
-    await electron.clickBrowser({ ...electronLocator(target), browserSessionId: session }, context);
-    return sessionInfo(session, { clicked: target });
-  }
   await run(session, target.startsWith('text=')
     ? findArgs(target, 'click')
-    : ['click', target]);
+    : ['click', target], { context });
   return sessionInfo(session, { clicked: target });
 }
 
@@ -224,35 +379,22 @@ async function fill(args = {}, context) {
   const session = sessionFor(args, context);
   const target = String(args.target || '');
   const text = String(args.text ?? '');
-  if (usesElectronBridge()) {
-    await electron.typeBrowser({ ...electronLocator(target), text, browserSessionId: session }, context);
-    if (args.submit) await electron.pressBrowser({ key: 'Enter', browserSessionId: session }, context);
-    return sessionInfo(session, { filled: target, submitted: Boolean(args.submit) });
-  }
   await run(session, target.startsWith('text=')
     ? findArgs(target, 'fill', text)
-    : ['fill', target, text]);
-  if (args.submit) await run(session, ['press', 'Enter']);
+    : ['fill', target, text], { context });
+  if (args.submit) await run(session, ['press', 'Enter'], { context });
   return sessionInfo(session, { filled: target, submitted: Boolean(args.submit) });
 }
 
 async function press(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    await electron.pressBrowser({ key: args.key, browserSessionId: session }, context);
-    return sessionInfo(session, { pressed: args.key });
-  }
-  await run(session, ['press', args.key]);
+  await run(session, ['press', args.key], { context });
   return sessionInfo(session, { pressed: args.key });
 }
 
 async function evaluate(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    const { result } = await electron.evaluateBrowser({ script: args.script, browserSessionId: session }, context);
-    return { ...sessionInfo(session), result };
-  }
-  const result = await run(session, ['eval', args.script || '']);
+  const result = await run(session, ['eval', args.script || ''], { context });
   const data = result?.data ?? result;
   // agent-browser wraps eval results as { origin, result }.
   const value = data && typeof data === 'object' && 'result' in data ? data.result : data;
@@ -268,10 +410,6 @@ async function wait(args = {}, context) {
     return sessionInfo(session, { waited: `${args.ms}ms` });
   }
   if (args.url) {
-    if (usesElectronBridge()) {
-      await electron.waitForURLBrowser({ url: args.url, timeoutMs, browserSessionId: session }, context);
-      return sessionInfo(session, { matched: args.url });
-    }
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       const current = await readText(session, ['get', 'url']);
@@ -281,11 +419,7 @@ async function wait(args = {}, context) {
     throw new Error(`Timed out waiting for URL ${args.url}`);
   }
   if (args.selector) {
-    if (usesElectronBridge()) {
-      await electron.waitForSelectorBrowser({ selector: args.selector, timeoutMs, browserSessionId: session }, context);
-      return sessionInfo(session, { matched: args.selector });
-    }
-    await run(session, ['wait', args.selector], { timeoutMs });
+    await run(session, ['wait', args.selector], { timeoutMs, context });
     return sessionInfo(session, { matched: args.selector });
   }
   throw new Error('wait requires one of: selector, url, ms');
@@ -293,19 +427,13 @@ async function wait(args = {}, context) {
 
 async function tabs(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    if (args.action === 'select' && args.tab) {
-      return electron.tabsSelectBrowser({ tabId: args.tab, browserSessionId: session }, context);
-    }
-    return electron.tabsListBrowser(context);
-  }
   if (args.action === 'select' && args.tab) {
-    return run(session, ['tab', args.tab]);
+    return run(session, ['tab', args.tab], { context });
   }
   if (args.action === 'new') {
-    return run(session, ['tab', 'new', ...(args.url ? [args.url] : [])]);
+    return run(session, ['tab', 'new', ...(args.url ? [args.url] : [])], { context });
   }
-  const result = await run(session, ['tab']);
+  const result = await run(session, ['tab'], { context });
   return { ...sessionInfo(session), tabs: result?.data?.tabs || result?.tabs || [] };
 }
 
@@ -316,47 +444,65 @@ async function tabs(args = {}, context) {
  */
 async function passthrough(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    throw new Error(
-      'browser_cli needs the agent-browser backend. The desktop bridge does not expose it; '
-      + 'set AMALGM_BROWSER_BACKEND=agent-browser or enable the CDP bridge (cdpUrl).',
-    );
-  }
   const commandArgs = (args.args || []).map(String);
   if (!commandArgs.length) throw new Error('args is required, e.g. ["scroll", "down"] or ["get", "text", "@e1"]');
-  const result = await run(session, commandArgs, { timeoutMs: args.timeoutMs || 60_000 });
+  const result = await run(session, commandArgs, { timeoutMs: args.timeoutMs || 60_000, context });
   return { ...sessionInfo(session), result: result?.data ?? result };
 }
 
+/** Schema convention is 1 left / 2 middle / 3 right; agent-browser's mouse
+ * commands take left|middle|right strings. */
+function mouseButton(value) {
+  const raw = String(value ?? '').toLowerCase();
+  if (raw === 'left' || raw === 'middle' || raw === 'right') return raw;
+  if (raw === '2') return 'middle';
+  if (raw === '3') return 'right';
+  return 'left';
+}
+
 async function cua(action, args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) return electron.cuaBrowser(action, { ...args, browserSessionId: session }, context);
+  const options = { context };
 
   const x = Math.round(Number(args.x || 0));
   const y = Math.round(Number(args.y || 0));
-  if (action === 'cua_move') await run(session, ['mouse', 'move', x, y]);
+  if (action === 'cua_move') await run(session, ['mouse', 'move', x, y], options);
   if (action === 'cua_click') {
-    await run(session, ['mouse', 'move', x, y]);
-    await run(session, ['mouse', 'down', args.button || 1]);
-    await run(session, ['mouse', 'up', args.button || 1]);
+    const button = mouseButton(args.button);
+    await run(session, ['mouse', 'move', x, y], options);
+    await run(session, ['mouse', 'down', button], options);
+    await run(session, ['mouse', 'up', button], options);
   }
   if (action === 'cua_double_click') {
-    await run(session, ['mouse', 'move', x, y]);
+    await run(session, ['mouse', 'move', x, y], options);
     for (let i = 0; i < 2; i += 1) {
-      await run(session, ['mouse', 'down', 1]);
-      await run(session, ['mouse', 'up', 1]);
+      await run(session, ['mouse', 'down', 'left'], options);
+      await run(session, ['mouse', 'up', 'left'], options);
     }
+    // agent-browser's mouse events always carry clickCount:1, so the renderer
+    // never coalesces the pair above into a native dblclick. Dispatch the
+    // dblclick event directly at the point; the two real clicks before it
+    // keep focus/selection side effects honest.
+    await run(session, ['eval', `(() => {
+      const el = document.elementFromPoint(${x}, ${y});
+      if (!el) return false;
+      el.dispatchEvent(new MouseEvent('dblclick', {
+        bubbles: true, cancelable: true, view: window,
+        clientX: ${x}, clientY: ${y}, button: 0, detail: 2,
+      }));
+      return true;
+    })()`], options);
   }
-  if (action === 'cua_scroll') await run(session, ['mouse', 'wheel', args.scrollY || 0, args.scrollX || 0]);
-  if (action === 'cua_type') await run(session, ['keyboard', 'type', args.text || '']);
-  if (action === 'cua_keypress') await run(session, ['press', (args.keys || []).join('+')]);
+  if (action === 'cua_scroll') await run(session, ['mouse', 'wheel', args.scrollY || 0, args.scrollX || 0], options);
+  if (action === 'cua_type') await run(session, ['keyboard', 'type', args.text || ''], options);
+  if (action === 'cua_keypress') await run(session, ['press', (args.keys || []).join('+')], options);
   if (action === 'cua_drag') {
     const points = Array.isArray(args.path) ? args.path : [];
     if (points.length < 2) throw new Error('drag path must contain at least two points');
-    await run(session, ['mouse', 'move', points[0].x, points[0].y]);
-    await run(session, ['mouse', 'down', 1]);
-    for (const point of points.slice(1)) await run(session, ['mouse', 'move', point.x, point.y]);
-    await run(session, ['mouse', 'up', 1]);
+    await run(session, ['mouse', 'move', points[0].x, points[0].y], options);
+    await run(session, ['mouse', 'down', 'left'], options);
+    for (const point of points.slice(1)) await run(session, ['mouse', 'move', point.x, point.y], options);
+    await run(session, ['mouse', 'up', 'left'], options);
   }
   return sessionInfo(session, { ok: true });
 }
@@ -367,14 +513,12 @@ async function cua(action, args = {}, context) {
 
 async function saveState(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) return electron.saveStateBrowser({ ...args, browserSessionId: session }, context);
-
   const fs = require('fs');
   const os = require('os');
   const path = require('path');
   const crypto = require('crypto');
   const file = args.path || path.join(os.tmpdir(), `amalgm-browser-state-${session}-${Date.now()}-${crypto.randomUUID()}.json`);
-  await run(session, ['state', 'save', file]);
+  await run(session, ['state', 'save', file], { context });
   const stateData = JSON.parse(fs.readFileSync(file, 'utf8'));
   if (!args.path) {
     try { fs.rmSync(file, { force: true }); } catch {}
@@ -390,8 +534,6 @@ async function saveState(args = {}, context) {
 
 async function loadState(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) return electron.loadStateBrowser({ ...args, browserSessionId: session }, context);
-
   const fs = require('fs');
   const os = require('os');
   const path = require('path');
@@ -404,7 +546,7 @@ async function loadState(args = {}, context) {
     fs.writeFileSync(file, `${JSON.stringify(args.state, null, 2)}\n`, { mode: 0o600 });
     temporary = true;
   }
-  await run(session, ['state', 'load', file]);
+  await run(session, ['state', 'load', file], { context });
   if (temporary) {
     try { fs.rmSync(file, { force: true }); } catch {}
   }
@@ -413,9 +555,9 @@ async function loadState(args = {}, context) {
 
 async function close(args = {}, context) {
   const session = sessionFor(args, context);
-  if (usesElectronBridge()) {
-    await electron.closeBrowser({ browserSessionId: session }, context);
-  } else {
+  // Attached mode drives the user's visible surface — never close it from
+  // the tool; just forget the session bookkeeping.
+  if (mode() !== 'attached') {
     await cli.runCli(['close'], { session });
   }
   attachedSessions.delete(session);
@@ -425,11 +567,13 @@ async function close(args = {}, context) {
 /** Resolve the CDP websocket URL for a session — recorder needs it. */
 async function cdpUrlForSession(session) {
   await ensureReady(session);
-  const result = await cli.runCli(['get', 'cdp-url'], { session, timeoutMs: 15_000 });
+  const result = await cli.runCli(['get', 'cdp-url'], cliOptions(session, { timeoutMs: 15_000 }));
   return result?.data?.cdpUrl || result?.cdpUrl || null;
 }
 
 module.exports = {
+  bridgeFileCandidates,
+  cdpEndpoint,
   cdpUrlForSession,
   click,
   close,
@@ -442,6 +586,7 @@ module.exports = {
   open,
   passthrough,
   press,
+  readBridgeAdvertisement,
   saveState,
   screenshot,
   sessionFor,
@@ -449,6 +594,5 @@ module.exports = {
   snapshot,
   state,
   tabs,
-  usesElectronBridge,
   wait,
 };