amalgm 0.1.88 → 0.1.89

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

@@ -1,409 +1,92 @@
+'use strict';
+
 /**
- * Browser MCP tools. In the desktop app they drive Amalgm's visible
- * Electron browser surface; elsewhere they fall back to agent-browser.
+ * Browser tools — the thin surface.
+ *
+ * Nine verbs, built on the agent-browser CLI (vercel-labs/agent-browser).
+ * The loop is: open → snapshot (refs) → click/fill (@ref) → re-snapshot.
+ * Everything else agent-browser can do (scroll, hover, cookies, network
+ * mocking, traces, diffs, React inspection, ...) is reachable through
+ * browser_cli without widening this schema.
+ *
+ * In the Amalgm desktop app these drive the visible in-tab splitscreen
+ * browser; elsewhere they drive a standalone chromium.
  */
 
 const { textResult, errorResult } = require('../lib/tool-result');
-const {
-  clipboardBrowser,
-  closeBrowser,
-  clickBrowser,
-  cuaBrowser,
-  evaluateBrowser,
-  getTextBrowser,
-  locatorCountBrowser,
-  locatorTextBrowser,
-  loadStateBrowser,
-  navigateBrowser,
-  pressBrowser,
-  screenshotBrowser,
-  saveStateBrowser,
-  snapshotBrowser,
-  startVideoBrowser,
-  stateBrowser,
-  stopVideoBrowser,
-  tabNavigationBrowser,
-  tabsGetBrowser,
-  tabsListBrowser,
-  tabsNewBrowser,
-  tabsSelectBrowser,
-  tabsSelectedBrowser,
-  typeBrowser,
-  waitForLoadStateBrowser,
-  waitForSelectorBrowser,
-  waitForURLBrowser,
-} = require('./page');
-const {
-  createBrowserLoginSession,
-  listBrowserAuthBundles,
-  listBrowserLoginSessions,
-  listBrowserProfiles,
-  markBrowserAuthBundleImported,
-  readEncryptedStateBundle,
-  safeId,
-  touchBrowserProfile,
-  writeEncryptedStateBundle,
-} = require('./store');
+const engine = require('./engine');
 
-const tabTargetProperties = {
-  tabId: { type: 'string', description: 'Explicit browser tab id returned by browser_tabs_* or browser_navigate' },
-  browserSessionId: { type: 'string', description: 'Stable browser automation session id' },
-  browserProfileId: { type: 'string', description: 'Durable browser profile id; aliases browserSessionId for login persistence' },
+const sessionProperty = {
+  session: {
+    type: 'string',
+    description: 'Browser session/profile id. Defaults to your chat session — omit it unless you need a second browser.',
+  },
 };
 
-const locatorProperties = {
-  ...tabTargetProperties,
-  ref: { type: 'string', description: 'Snapshot ref such as @e1' },
-  selector: { type: 'string', description: 'CSS selector for the target element' },
-  text: { type: 'string', description: 'Visible text to match' },
-  role: { type: 'string', description: 'ARIA role, e.g. button, link, textbox' },
-  name: { type: 'string', description: 'Accessible name or visible name used with role/text matching' },
-  label: { type: 'string', description: 'Form label text' },
-  placeholder: { type: 'string', description: 'Input placeholder text' },
-  testId: { type: 'string', description: 'data-testid, data-test-id, or data-test value' },
-  exact: { type: 'boolean', description: 'Require exact text/name match' },
-  strict: { type: 'boolean', description: 'Require the locator to resolve to exactly one visible element' },
-  timeoutMs: { type: 'number', description: 'Maximum wait time in milliseconds' },
+const targetProperty = {
+  target: {
+    type: 'string',
+    description: 'Element target: a snapshot ref like "@e12" (preferred — run browser_snapshot first), a CSS selector, or "text=Visible label".',
+  },
 };
 
-function jsonText(value) {
-  return textResult(JSON.stringify(value, null, 2));
-}
-
-function targetLine(result) {
-  const bits = [];
-  if (result?.tabId) bits.push(`Tab: ${result.tabId}`);
-  if (result?.browserSessionId) bits.push(`Session: ${result.browserSessionId}`);
-  return bits.length ? `\n${bits.join('\n')}` : '';
-}
-
-function requireFiniteCoordinate(value, name) {
-  const number = Number(value);
-  if (!Number.isFinite(number)) throw new Error(`${name} must be a finite number`);
-  return number;
-}
-
-function authDomainsFrom(inputDomains, fallbackUrl) {
-  if (Array.isArray(inputDomains) && inputDomains.length > 0) return inputDomains;
-  try {
-    const hostname = new URL(fallbackUrl).hostname;
-    return hostname ? [hostname] : [];
-  } catch {
-    return [];
-  }
+function line(result, extra = '') {
+  const bits = [extra, result?.url ? `URL: ${result.url}` : '', result?.session ? `Session: ${result.session}` : '']
+    .filter(Boolean);
+  return bits.join('\n');
 }
 
 module.exports = [
   {
-    name: 'browser_profiles_list',
-    description: 'List durable Amalgm browser profiles on this computer.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler() {
-      try {
-        return jsonText({ profiles: listBrowserProfiles() });
-      } catch (err) {
-        return errorResult(`List browser profiles failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_auth_bundles_list',
-    description: 'List encrypted browser auth bundles available on this computer. Raw cookies/storage are never returned.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler() {
-      try {
-        return jsonText({ bundles: listBrowserAuthBundles() });
-      } catch (err) {
-        return errorResult(`List browser auth bundles failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_login_sessions_list',
-    description: 'List temporary browser login links on this computer. Raw tokens and cookies are never returned.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler() {
-      try {
-        return jsonText({ sessions: listBrowserLoginSessions() });
-      } catch (err) {
-        return errorResult(`List browser login sessions failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_auth_link_create',
-    description: 'Create a short-lived browser login link for the user. Use this when an agent needs the user to log into a site before QA or browser work.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        targetUrl: { type: 'string', description: 'The site or app URL the user should log into.' },
-        browserProfileId: { type: 'string', description: 'Durable browser profile id that will receive the login.' },
-        browserSessionId: { type: 'string', description: 'Alias for browserProfileId.' },
-        name: { type: 'string', description: 'Human-readable login/bundle name.' },
-        domains: { type: 'array', items: { type: 'string' }, description: 'Domains to save after login, e.g. app.example.com.' },
-        transport: { type: 'string', description: 'Optional live-view transport: electron-splitview, novnc, or auto.' },
-        liveUrl: { type: 'string', description: 'Optional noVNC/live-view URL for web/mobile login.' },
-        appBaseUrl: { type: 'string', description: 'Optional Amalgm app base URL used to build an absolute link.' },
-        ttlMs: { type: 'number', description: 'Optional link lifetime in milliseconds. Defaults to 15 minutes, max 1 hour.' },
-      },
-      required: ['targetUrl'],
-    },
-    async handler(args, ctx) {
-      try {
-        const profileId = safeId(
-          args.browserProfileId
-            || args.browserSessionId
-            || ctx?.callerSessionId
-            || `login-${Date.now().toString(36)}`,
-        );
-        const result = createBrowserLoginSession({
-          ...args,
-          browserProfileId: profileId,
-          profileId,
-        }, { source: 'browser-auth-link-tool' });
-        return jsonText({
-          session: result.session,
-          authLink: result.authLink,
-          authLinkPath: result.authLinkPath,
-          message: `Open this temporary login link: ${result.authLink}`,
-        });
-      } catch (err) {
-        return errorResult(`Create browser auth link failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_auth_save',
-    description: 'Save the current browser profile cookies/storage into an encrypted auth bundle for later agent use.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        browserSessionId: { type: 'string', description: 'Browser session/profile id to save from' },
-        browserProfileId: { type: 'string', description: 'Durable browser profile id to save from' },
-        name: { type: 'string', description: 'Human-readable bundle name' },
-        domains: { type: 'array', items: { type: 'string' }, description: 'Optional domains to include, e.g. example.com' },
-      },
-    },
-    async handler(args, ctx) {
-      try {
-        const profileId = safeId(args.browserProfileId || args.browserSessionId || ctx?.callerSessionId || 'default');
-        const saved = await saveStateBrowser({ ...args, browserProfileId: profileId, browserSessionId: profileId }, ctx);
-        const bundle = writeEncryptedStateBundle({
-          name: args.name || saved.title || profileId,
-          profileId,
-          domains: authDomainsFrom(args.domains, saved.url),
-          state: saved.state || {},
-        });
-        touchBrowserProfile({
-          id: profileId,
-          name: args.name || profileId,
-          source: saved.backend || 'browser-auth-save',
-        }, { source: 'browser-auth-save' });
-        return jsonText({ bundle });
-      } catch (err) {
-        return errorResult(`Save browser auth bundle failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_auth_load',
-    description: 'Load an encrypted browser auth bundle into a durable browser profile so an agent can start past login.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: 'Auth bundle id' },
-        browserSessionId: { type: 'string', description: 'Target browser session/profile id' },
-        browserProfileId: { type: 'string', description: 'Target durable browser profile id' },
-      },
-      required: ['id'],
-    },
-    async handler(args, ctx) {
-      try {
-        const { bundle, payload } = readEncryptedStateBundle(args.id);
-        const profileId = safeId(args.browserProfileId || args.browserSessionId || bundle.profileId);
-        const loaded = await loadStateBrowser({
-          ...args,
-          browserProfileId: profileId,
-          browserSessionId: profileId,
-          state: payload.state,
-        }, ctx);
-        const updated = markBrowserAuthBundleImported(args.id, profileId);
-        touchBrowserProfile({
-          id: profileId,
-          name: profileId,
-          source: loaded.backend || 'browser-auth-load',
-        }, { source: 'browser-auth-load' });
-        return jsonText({ bundle: updated, loaded });
-      } catch (err) {
-        return errorResult(`Load browser auth bundle failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_tabs_list',
-    description: 'List visible Amalgm browser-use tabs/surfaces.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler(_args, ctx) {
-      try {
-        return jsonText(await tabsListBrowser(ctx));
-      } catch (err) {
-        return errorResult(`List browser tabs failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_tabs_selected',
-    description: 'Return the most recently used browser-use tab.',
-    inputSchema: { type: 'object', properties: {} },
-    async handler(_args, ctx) {
-      try {
-        return jsonText(await tabsSelectedBrowser(ctx));
-      } catch (err) {
-        return errorResult(`Get selected browser tab failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_tabs_new',
-    description: 'Create a new visible browser-use tab/surface, optionally navigating it to a URL.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        url: { type: 'string', description: 'Optional URL to open' },
-        browserSessionId: { type: 'string', description: 'Optional session id; generated if omitted' },
-      },
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await tabsNewBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Create browser tab failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_tabs_get',
-    description: 'Get state for a browser tab by tabId or browserSessionId.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await tabsGetBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Get browser tab failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_tabs_select',
-    description: 'Select/focus a browser-use tab by tabId or browserSessionId.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await tabsSelectBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Select browser tab failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_tabs_close',
-    description: 'Close a browser-use tab by tabId or browserSessionId.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        await closeBrowser(args, ctx);
-        return textResult('Browser tab closed.');
-      } catch (err) {
-        return errorResult(`Close browser tab failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_state',
-    description: 'Return URL/title/loading state for the current or specified browser tab.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await stateBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Browser state failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_navigate',
-    description: 'Navigate a visible browser tab to a URL. Returns tabId and browserSessionId for follow-up calls.',
+    name: 'browser_open',
+    description: 'Open a URL in the browser. In the Amalgm desktop app this appears in the in-tab splitscreen surface. Follow with browser_snapshot to see interactive elements.',
     inputSchema: {
       type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        url: { type: 'string', description: 'The URL to navigate to' },
-      },
+      properties: { url: { type: 'string', description: 'URL to open' }, ...sessionProperty },
       required: ['url'],
     },
     async handler(args, ctx) {
       if (!args.url) return errorResult('url is required');
       try {
-        const result = await navigateBrowser(args, ctx);
-        return textResult(`Navigated to ${result.url || args.url}\nStatus: ${result.status}\nTitle: ${result.title || ''}${targetLine(result)}`);
+        const result = await engine.open(args, ctx);
+        return textResult(line(result, `Opened: ${result.title || args.url}`)
+          + '\n\nNext: browser_snapshot lists interactive elements as @refs.');
       } catch (err) {
-        return errorResult(`Navigation failed: ${err.message}`);
+        return errorResult(`Open failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_back',
-    description: 'Navigate the browser tab back in history.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await tabNavigationBrowser('back', args, ctx));
-      } catch (err) {
-        return errorResult(`Browser back failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_forward',
-    description: 'Navigate the browser tab forward in history.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await tabNavigationBrowser('forward', args, ctx));
-      } catch (err) {
-        return errorResult(`Browser forward failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_reload',
-    description: 'Reload the browser tab.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
+    name: 'browser_snapshot',
+    description: 'Accessibility snapshot of the current page with stable @refs for every interactive element. This is how you see the page; use the refs with browser_click and browser_fill.',
+    inputSchema: { type: 'object', properties: sessionProperty },
     async handler(args, ctx) {
       try {
-        return jsonText(await tabNavigationBrowser('reload', args, ctx));
+        const result = await engine.snapshot(args, ctx);
+        const header = `Page: ${result.title || ''}\nURL: ${result.url || ''}\n\n`;
+        return textResult(header + (result.snapshotText || '(empty page)').slice(0, 12_000));
       } catch (err) {
-        return errorResult(`Browser reload failed: ${err.message}`);
+        return errorResult(`Snapshot failed: ${err.message}`);
       }
     },
   },
   {
     name: 'browser_screenshot',
-    description: 'Take a screenshot of the current or specified browser tab. Returns a base64-encoded PNG.',
+    description: 'Screenshot the current page (PNG). Use browser_snapshot for interaction targets; use this when you need to see pixels.',
     inputSchema: {
       type: 'object',
       properties: {
-        ...tabTargetProperties,
-        full_page: { type: 'boolean', description: 'Capture the full scrollable page' },
+        fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport' },
+        ...sessionProperty,
       },
     },
     async handler(args, ctx) {
       try {
-        const capture = await screenshotBrowser({ ...args, fullPage: args.full_page || false }, ctx);
+        const capture = await engine.screenshot(args, ctx);
         return {
           content: [
             { type: 'image', data: capture.base64, mimeType: 'image/png' },
-            { type: 'text', text: `Screenshot captured (${capture.bytes} bytes, ${capture.mode})${targetLine(capture)}` },
+            { type: 'text', text: `Screenshot (${capture.bytes} bytes, ${capture.mode || 'viewport'})` },
           ],
         };
       } catch (err) {
@@ -411,449 +94,139 @@ module.exports = [
       }
     },
   },
-  {
-    name: 'browser_snapshot',
-    description: 'Get a token-efficient DOM/text snapshot of the current or specified browser tab.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        const snapshot = await snapshotBrowser(args, ctx);
-        let result = `Page: ${snapshot.title}\nURL: ${snapshot.url}${targetLine(snapshot)}\n\n`;
-        result += (snapshot.snapshotText || '(empty)').slice(0, 10_000);
-        return textResult(result);
-      } catch (err) {
-        return errorResult(`Snapshot failed: ${err.message}`);
-      }
-    },
-  },
   {
     name: 'browser_click',
-    description: 'Click an element by selector, text, role/name, label, placeholder, or testId.',
-    inputSchema: { type: 'object', properties: locatorProperties },
+    description: 'Click an element. Target with a snapshot @ref, CSS selector, or "text=Label".',
+    inputSchema: {
+      type: 'object',
+      properties: { ...targetProperty, ...sessionProperty },
+      required: ['target'],
+    },
     async handler(args, ctx) {
-      if (!args.ref && !args.selector && !args.text && !args.role && !args.label && !args.placeholder && !args.testId && !args.name) {
-        return errorResult('A ref, selector, text, role, label, placeholder, testId, or name is required');
-      }
+      if (!args.target) return errorResult('target is required (e.g. "@e3", "#submit", "text=Sign in")');
       try {
-        const result = await clickBrowser(args, ctx);
-        return textResult(`${result.description}${targetLine(result)}`);
+        const result = await engine.click(args, ctx);
+        return textResult(`Clicked ${args.target}\nSession: ${result.session}\n\nRe-run browser_snapshot if the page changed.`);
       } catch (err) {
         return errorResult(`Click failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_type',
-    description: 'Type text into a focused element or a target matched by selector/role/label/placeholder/testId.',
+    name: 'browser_fill',
+    description: 'Clear a field and type into it. Optionally press Enter to submit.',
     inputSchema: {
       type: 'object',
       properties: {
-        ...locatorProperties,
-        text: { type: 'string', description: 'The text to type' },
-        clear: { type: 'boolean', description: 'Clear the field before typing (default: true)' },
+        ...targetProperty,
+        text: { type: 'string', description: 'Text to enter' },
+        submit: { type: 'boolean', description: 'Press Enter after typing' },
+        ...sessionProperty,
       },
-      required: ['text'],
+      required: ['target', 'text'],
     },
     async handler(args, ctx) {
-      if (typeof args.text !== 'string') return errorResult('text is required');
+      if (!args.target || typeof args.text !== 'string') return errorResult('target and text are required');
       try {
-        const result = await typeBrowser(args, ctx);
-        return textResult(`${result.description}${targetLine(result)}`);
+        const result = await engine.fill(args, ctx);
+        return textResult(`Filled ${args.target}${result.submitted ? ' and pressed Enter' : ''}\nSession: ${result.session}`);
       } catch (err) {
-        return errorResult(`Type failed: ${err.message}`);
+        return errorResult(`Fill failed: ${err.message}`);
       }
     },
   },
   {
     name: 'browser_press',
-    description: 'Press a key on a target element or the focused element.',
+    description: 'Press a key or combination at the focused element, e.g. "Enter", "Escape", "Tab", "Control+a".',
     inputSchema: {
       type: 'object',
-      properties: {
-        ...locatorProperties,
-        key: { type: 'string', description: 'Key to press, e.g. Enter, Escape, A' },
-      },
+      properties: { key: { type: 'string', description: 'Key or combination' }, ...sessionProperty },
       required: ['key'],
     },
     async handler(args, ctx) {
+      if (!args.key) return errorResult('key is required');
       try {
-        return jsonText(await pressBrowser(args, ctx));
+        const result = await engine.press(args, ctx);
+        return textResult(`Pressed ${args.key}\nSession: ${result.session}`);
       } catch (err) {
         return errorResult(`Press failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_get_text',
-    description: 'Extract text content from the current page or a CSS selector.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        ref: { type: 'string', description: 'Snapshot ref such as @e1' },
-        selector: { type: 'string', description: 'CSS selector to extract (omit for full page)' },
-      },
-    },
-    async handler(args, ctx) {
-      try {
-        let text = (await getTextBrowser(args, ctx)).text;
-        if (text && text.length > 15_000) {
-          text = `${text.slice(0, 15_000)}\n\n... (truncated, use a selector for specific content)`;
-        }
-        return textResult(text || '(empty)');
-      } catch (err) {
-        return errorResult(`Get text failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_locator_count',
-    description: 'Count visible elements matching a locator.',
-    inputSchema: { type: 'object', properties: locatorProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await locatorCountBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Locator count failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_locator_text',
-    description: 'Return visible text for the first element matching a locator, plus match count.',
-    inputSchema: { type: 'object', properties: locatorProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await locatorTextBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Locator text failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_evaluate',
-    description: 'Execute JavaScript in the browser page context.',
+    name: 'browser_eval',
+    description: 'Run JavaScript in the page and return the result. The general-purpose escape hatch for reading or mutating page state.',
     inputSchema: {
       type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        script: { type: 'string' },
-      },
+      properties: { script: { type: 'string', description: 'JavaScript to evaluate' }, ...sessionProperty },
       required: ['script'],
     },
     async handler(args, ctx) {
       if (!args.script) return errorResult('script is required');
       try {
-        const { result } = await evaluateBrowser(args, ctx);
-        const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result);
-        return textResult(output);
-      } catch (err) {
-        return errorResult(`Evaluate failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_wait_for_load_state',
-    description: 'Wait for the browser tab to reach load, domcontentloaded, or networkidle.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        state: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] },
-        timeoutMs: { type: 'number' },
-      },
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await waitForLoadStateBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Wait for load state failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_wait_for_url',
-    description: 'Wait for the browser tab URL to match a string. Supports * wildcards in Electron mode.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        url: { type: 'string' },
-        waitUntil: { type: 'string', enum: ['commit', 'load', 'domcontentloaded', 'networkidle'] },
-        timeoutMs: { type: 'number' },
-      },
-      required: ['url'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await waitForURLBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Wait for URL failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_wait_for_selector',
-    description: 'Wait for a CSS selector to become attached, detached, visible, or hidden.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        selector: { type: 'string' },
-        state: { type: 'string', enum: ['attached', 'detached', 'visible', 'hidden'] },
-        timeoutMs: { type: 'number' },
-      },
-      required: ['selector'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await waitForSelectorBrowser(args, ctx));
-      } catch (err) {
-        return errorResult(`Wait for selector failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_cua_click',
-    description: 'Click viewport coordinates in the visible browser tab.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        x: { type: 'number' },
-        y: { type: 'number' },
-        button: { type: 'number', description: '1 left, 2 middle, 3 right' },
-        keypress: { type: 'array', items: { type: 'string' } },
-      },
-      required: ['x', 'y'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await cuaBrowser('cua_click', { ...args, x: requireFiniteCoordinate(args.x, 'x'), y: requireFiniteCoordinate(args.y, 'y') }, ctx));
-      } catch (err) {
-        return errorResult(`CUA click failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_cua_double_click',
-    description: 'Double-click viewport coordinates in the visible browser tab.',
-    inputSchema: {
-      type: 'object',
-      properties: { ...tabTargetProperties, x: { type: 'number' }, y: { type: 'number' }, keypress: { type: 'array', items: { type: 'string' } } },
-      required: ['x', 'y'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await cuaBrowser('cua_double_click', { ...args, x: requireFiniteCoordinate(args.x, 'x'), y: requireFiniteCoordinate(args.y, 'y') }, ctx));
-      } catch (err) {
-        return errorResult(`CUA double-click failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_cua_move',
-    description: 'Move the browser mouse to viewport coordinates.',
-    inputSchema: {
-      type: 'object',
-      properties: { ...tabTargetProperties, x: { type: 'number' }, y: { type: 'number' }, keys: { type: 'array', items: { type: 'string' } } },
-      required: ['x', 'y'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await cuaBrowser('cua_move', { ...args, x: requireFiniteCoordinate(args.x, 'x'), y: requireFiniteCoordinate(args.y, 'y') }, ctx));
+        const { result } = await engine.evaluate(args, ctx);
+        const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+        return textResult(output.slice(0, 15_000) || '(no result)');
       } catch (err) {
-        return errorResult(`CUA move failed: ${err.message}`);
+        return errorResult(`Eval failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_cua_scroll',
-    description: 'Scroll the visible browser tab from viewport coordinates.',
+    name: 'browser_wait',
+    description: 'Wait for a CSS selector to appear, a URL substring/wildcard to match, or a fixed number of milliseconds.',
     inputSchema: {
       type: 'object',
       properties: {
-        ...tabTargetProperties,
-        x: { type: 'number' },
-        y: { type: 'number' },
-        scrollX: { type: 'number' },
-        scrollY: { type: 'number' },
-        keypress: { type: 'array', items: { type: 'string' } },
+        selector: { type: 'string', description: 'CSS selector to wait for' },
+        url: { type: 'string', description: 'URL substring or *-wildcard to wait for' },
+        ms: { type: 'number', description: 'Plain delay in milliseconds (max 60000)' },
+        timeoutMs: { type: 'number', description: 'Timeout (default 30000)' },
+        ...sessionProperty,
       },
-      required: ['x', 'y', 'scrollX', 'scrollY'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await cuaBrowser('cua_scroll', {
-          ...args,
-          x: requireFiniteCoordinate(args.x, 'x'),
-          y: requireFiniteCoordinate(args.y, 'y'),
-          scrollX: Number(args.scrollX || 0),
-          scrollY: Number(args.scrollY || 0),
-        }, ctx));
-      } catch (err) {
-        return errorResult(`CUA scroll failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_cua_type',
-    description: 'Type text at the currently focused browser element.',
-    inputSchema: {
-      type: 'object',
-      properties: { ...tabTargetProperties, text: { type: 'string' } },
-      required: ['text'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await cuaBrowser('cua_type', args, ctx));
-      } catch (err) {
-        return errorResult(`CUA type failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_cua_keypress',
-    description: 'Press a key combination in the visible browser tab.',
-    inputSchema: {
-      type: 'object',
-      properties: { ...tabTargetProperties, keys: { type: 'array', items: { type: 'string' } } },
-      required: ['keys'],
     },
     async handler(args, ctx) {
       try {
-        return jsonText(await cuaBrowser('cua_keypress', args, ctx));
+        const result = await engine.wait(args, ctx);
+        return textResult(`Done: ${result.matched || result.waited}\nSession: ${result.session}`);
       } catch (err) {
-        return errorResult(`CUA keypress failed: ${err.message}`);
+        return errorResult(`Wait failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_cua_drag',
-    description: 'Drag through a list of viewport points.',
+    name: 'browser_cli',
+    description: 'Run any agent-browser CLI command against this session — the full surface beyond the core verbs: ["scroll","down"], ["hover","@e3"], ["back"], ["tab"], ["get","html","@e1"], ["cookies","get"], ["network","requests"], ["find","role","button","click","--name","Submit"], and more. Run ["--help"] for the command list.',
     inputSchema: {
       type: 'object',
       properties: {
-        ...tabTargetProperties,
-        path: { type: 'array', items: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, required: ['x', 'y'] } },
-        keys: { type: 'array', items: { type: 'string' } },
+        args: { type: 'array', items: { type: 'string' }, description: 'agent-browser argv, e.g. ["scroll", "down", "400"]' },
+        timeoutMs: { type: 'number', description: 'Timeout (default 60000)' },
+        ...sessionProperty,
       },
-      required: ['path'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await cuaBrowser('cua_drag', args, ctx));
-      } catch (err) {
-        return errorResult(`CUA drag failed: ${err.message}`);
-      }
+      required: ['args'],
     },
-  },
-  {
-    name: 'browser_cua_screenshot',
-    description: 'Capture the visible browser tab viewport.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
     async handler(args, ctx) {
       try {
-        const capture = await screenshotBrowser({ ...args, fullPage: false }, ctx);
-        return {
-          content: [
-            { type: 'image', data: capture.base64, mimeType: 'image/png' },
-            { type: 'text', text: `Visible browser screenshot captured (${capture.bytes} bytes)${targetLine(capture)}` },
-          ],
-        };
+        const { result } = await engine.passthrough(args, ctx);
+        const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+        return textResult(output.slice(0, 15_000) || 'ok');
       } catch (err) {
-        return errorResult(`CUA screenshot failed: ${err.message}`);
+        return errorResult(`browser_cli failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_clipboard_read_text',
-    description: 'Read plain text from the browser page clipboard API.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await clipboardBrowser('clipboard_read_text', args, ctx));
-      } catch (err) {
-        return errorResult(`Clipboard read failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_clipboard_write_text',
-    description: 'Write plain text through the browser page clipboard API.',
-    inputSchema: {
-      type: 'object',
-      properties: { ...tabTargetProperties, text: { type: 'string' } },
-      required: ['text'],
-    },
-    async handler(args, ctx) {
-      try {
-        return jsonText(await clipboardBrowser('clipboard_write_text', args, ctx));
-      } catch (err) {
-        return errorResult(`Clipboard write failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_start_video',
-    description: 'Start recording the browser session to a local WebM video. Saved when browser_stop_video is called.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        ...tabTargetProperties,
-        fps: { type: 'number', description: 'Recording frames per second (default: 12, max: 30)' },
-        session_id: { type: 'string', description: 'Deprecated alias for recording_id. Optional recording folder name under ~/.amalgm/browser-sessions' },
-        recording_id: { type: 'string', description: 'Optional recording folder name under ~/.amalgm/browser-sessions' },
-      },
-    },
+    name: 'browser_close',
+    description: 'Close the browser session. A fresh one launches on the next browser call.',
+    inputSchema: { type: 'object', properties: sessionProperty },
     async handler(args, ctx) {
       try {
-        const result = await startVideoBrowser({
-          ...args,
-          fps: args.fps,
-          sessionId: args.recording_id || args.session_id,
-        }, ctx);
-        return textResult(`Browser video recording started (${result.fps || 'default'} fps).${targetLine(result)}`);
+        await engine.close(args, ctx);
+        return textResult('Browser closed.');
       } catch (err) {
-        return errorResult(`Start video failed: ${err.message}`);
+        return errorResult(`Close failed: ${err.message}`);
       }
     },
   },
-  {
-    name: 'browser_stop_video',
-    description: 'Stop browser video recording and save it under ~/.amalgm/browser-sessions/.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      try {
-        const result = await stopVideoBrowser(args, ctx);
-        if (!result.path) return textResult(`Browser video recording stopped.${targetLine(result)}`);
-        const urlLine = result.url ? `\nOpen: ${result.url}` : '';
-        return {
-          content: [
-            { type: 'text', text: `Browser video saved: ${result.path}\nBytes: ${result.bytes || 0}${urlLine}${targetLine(result)}` },
-          ],
-          metadata: {
-            browserVideo: result.browserVideo || {
-              path: result.path,
-              relativePath: result.relativePath,
-              url: result.url,
-              bytes: result.bytes,
-              mimeType: result.mimeType || 'video/webm',
-            },
-          },
-        };
-      } catch (err) {
-        return errorResult(`Stop video failed: ${err.message}`);
-      }
-    },
-  },
-  {
-    name: 'browser_close',
-    description: 'Close the current or specified browser tab/surface.',
-    inputSchema: { type: 'object', properties: tabTargetProperties },
-    async handler(args, ctx) {
-      await closeBrowser(args, ctx);
-      return textResult('Browser closed. A new instance will launch on the next browser_* call.');
-    },
-  },
 ];