amalgm 0.1.91 → 0.1.92

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

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * Minimal raw-CDP utilities — the only websocket/devtools plumbing in the
+ * browser module. attach.js uses it to verify the visible surface; capture.js
+ * uses it for pixels. No dependencies on other browser modules.
+ *
+ * Every exchange carries a hard deadline: a probe may fail, it can never
+ * wedge a caller.
+ */
+
+const CONNECT_TIMEOUT_MS = 10_000;
+const CALL_TIMEOUT_MS = 15_000;
+
+function deadline(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Minimal CDP client over one websocket: call/response with deadlines,
+ * fire-and-forget send (frame acks), event listeners.
+ */
+async function connectCdp(wsUrl) {
+  const WebSocket = require('ws');
+  const ws = new WebSocket(wsUrl, { perMessageDeflate: false });
+  try {
+    await deadline(new Promise((resolve, reject) => {
+      ws.once('open', resolve);
+      ws.once('error', reject);
+    }), CONNECT_TIMEOUT_MS, 'CDP connect');
+  } catch (err) {
+    // Free the half-open socket — a timed-out connect must not leak a
+    // connection that keeps the process (or a test run) alive.
+    try { ws.terminate(); } catch {}
+    throw err;
+  }
+
+  let nextId = 0;
+  const pending = new Map();
+  const listeners = new Map();
+
+  ws.on('message', (raw) => {
+    let msg;
+    try { msg = JSON.parse(raw); } catch { return; }
+    if (msg.id && pending.has(msg.id)) {
+      const entry = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.error) entry.reject(new Error(msg.error.message || 'CDP error'));
+      else entry.resolve(msg.result || {});
+      return;
+    }
+    if (msg.method && listeners.has(msg.method)) listeners.get(msg.method)(msg.params || {});
+  });
+  ws.on('close', () => {
+    for (const entry of pending.values()) entry.reject(new Error('CDP connection closed'));
+    pending.clear();
+  });
+  ws.on('error', () => {});
+
+  return {
+    call(method, params = {}, timeoutMs = CALL_TIMEOUT_MS) {
+      const id = ++nextId;
+      const result = new Promise((resolve, reject) => pending.set(id, { resolve, reject }));
+      try { ws.send(JSON.stringify({ id, method, params })); } catch (err) {
+        pending.delete(id);
+        return Promise.reject(err);
+      }
+      return deadline(result, timeoutMs, method).catch((err) => {
+        pending.delete(id);
+        throw err;
+      });
+    },
+    send(method, params = {}) {
+      try { ws.send(JSON.stringify({ id: ++nextId, method, params })); } catch {}
+    },
+    on(method, handler) { listeners.set(method, handler); },
+    close() { try { ws.close(); } catch {} },
+  };
+}
+
+/** GET /json/list on the debugger port — accepts a ws/http url or a bare port. */
+function targetListUrl(endpoint) {
+  const raw = String(endpoint || '').trim();
+  if (/^\d+$/.test(raw)) return `http://127.0.0.1:${raw}/json/list`;
+  const url = new URL(raw.replace(/^ws/, 'http'));
+  return `http://${url.hostname}:${url.port || 80}/json/list`;
+}
+
+async function listTargets(endpoint) {
+  const http = require('http');
+  return deadline(new Promise((resolve, reject) => {
+    const req = http.get(targetListUrl(endpoint), (res) => {
+      let raw = '';
+      res.on('data', (chunk) => { raw += chunk.toString(); });
+      res.on('end', () => {
+        try { resolve(JSON.parse(raw)); } catch (err) { reject(err); }
+      });
+    });
+    req.on('error', reject);
+  }), 5_000, 'CDP target list');
+}
+
+function pageTargets(targets) {
+  return (targets || []).filter((t) => t.type === 'page'
+    && t.webSocketDebuggerUrl
+    && !String(t.url || '').startsWith('devtools://'));
+}
+
+/**
+ * Locate the session's <webview> element inside a candidate app window:
+ * marker in the src attribute, exact current URL (the UI keeps src synced to
+ * the visible URL), then "the only webview". Returns layout geometry only
+ * when the element is actually visible — a hidden splitview reports 0x0 and
+ * resolves to null.
+ */
+function rectScript(markerText, currentUrl) {
+  const urlLiteral = JSON.stringify(String(currentUrl || ''));
+  return `(() => {
+    const views = [...document.querySelectorAll('webview')];
+    const byMarker = views.find((w) => (w.getAttribute('src') || '').includes(${JSON.stringify(markerText)}));
+    const byUrl = ${urlLiteral} ? views.find((w) => (w.src || '') === ${urlLiteral}) : null;
+    const match = byMarker || byUrl || (views.length === 1 ? views[0] : null);
+    if (!match) return null;
+    const r = match.getBoundingClientRect();
+    if (!r.width || !r.height) return null;
+    return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height, vw: window.innerWidth, vh: window.innerHeight, dpr: window.devicePixelRatio || 1 });
+  })()`;
+}
+
+async function embedderRect(cdp, markerText, currentUrl) {
+  const { result } = await cdp.call('Runtime.evaluate', {
+    expression: rectScript(markerText, currentUrl),
+    returnByValue: true,
+  });
+  const raw = result && result.value;
+  if (!raw || typeof raw !== 'string') return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+/**
+ * Find the app window hosting the session's webview and the webview's
+ * on-screen rectangle. Null when the surface is hidden (or no webview
+ * matches) — callers decide whether to reopen or fail.
+ */
+async function findSurfaceRect(endpoint, markerText, currentUrl) {
+  const targets = await listTargets(endpoint);
+  for (const page of pageTargets(targets)) {
+    const cdp = await connectCdp(page.webSocketDebuggerUrl).catch(() => null);
+    if (!cdp) continue;
+    try {
+      const rect = await embedderRect(cdp, markerText, currentUrl);
+      if (rect) return { pageWsUrl: page.webSocketDebuggerUrl, rect };
+    } catch {
+      // Try the next window.
+    } finally {
+      cdp.close();
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  connectCdp,
+  deadline,
+  embedderRect,
+  findSurfaceRect,
+  listTargets,
+  pageTargets,
+  rectScript,
+  targetListUrl,
+};

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

@@ -1,316 +1,34 @@
 'use strict';
 
 /**
- * Browser engine: the verb set behind the browser toolbox entry, with
- * deterministic backend routing by entrypoint.
+ * Browser verbs — the behavior behind every browser action.
  *
- * 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.
+ * Built on small single-concern modules:
+ *   backend.js  — which browser: visible desktop surface vs headless cli
+ *   attach.js   — the visible-surface handshake + command transport
+ *   capture.js  — pixels: screenshots, and the recorder's frame source
+ *   sessions.js — session identity, 1:1 with durable profiles
+ *   cli.js      — the agent-browser process wrapper
  *
- * 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.
+ * This module stays the single import for tool handlers and tests; the
+ * modules above are its implementation. Visibility is an environment fact,
+ * never an argument — no verb takes a mode.
  */
 
 const cli = require('./cli');
+const backend = require('./backend');
+const attach = require('./attach');
+const capture = require('./capture');
+const sessions = require('./sessions');
 
-const attachedSessions = new Set();
-const knownSessions = new Map();
-
-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');
-  }
-}
-
-/**
- * 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 url = new URL(raw);
-    if (url.port) return url.port;
-  } catch {}
-  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 (['agent-browser', 'external', 'cli', 'headless'].includes(requested)) return 'cli';
-  if (['attached', 'cdp', 'electron'].includes(requested)) return 'attached';
-  return cdpEndpoint() ? 'attached' : 'cli';
-}
-
-/** 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 = {}) {
-  return cli.safeId(
-    args.session
-      || args.profile
-      || args.browserProfileId
-      || args.browserSessionId
-      || args.sessionId
-      || args.tabId
-      || context?.callerSessionId
-      || cli.DEFAULT_SESSION,
-  );
-}
-
-function rememberProfile(session) {
-  try {
-    require('./profiles').touchBrowserProfile({
-      id: session,
-      name: session,
-      source: 'agent-browser',
-      profilePath: cli.profileDir(session),
-    }, { source: 'agent-browser' });
-  } catch {}
-}
-
-function sessionInfo(session, extra = {}) {
-  rememberProfile(session);
-  const info = {
-    session,
-    browserSessionId: session,
-    browserProfileId: session,
-    backend: mode(),
-    ...extra,
-  };
-  knownSessions.set(session, { ...knownSessions.get(session), ...info, lastActiveAt: Date.now() });
-  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 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, context) {
-  if (mode() !== 'attached' || attachedSessions.has(session)) return;
-
-  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'], cliOptions(session, { timeoutMs: 15_000 }));
-    const list = tabs?.data?.tabs || tabs?.tabs || [];
-    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 {
-    // Snapshot/eval still work without focus; input may need a retry.
-  }
-}
-
-function looksLikeLostConnection(err) {
-  return /clos|connect|target|socket|detach/i.test(String(err?.message || err || ''));
-}
-
-async function run(session, commandArgs, 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, mode() === 'attached' ? cdpEndpoint() : null);
-}
+const { sessionFor, sessionInfo } = sessions;
+const { run, readText } = attach;
 
 /**
  * Target grammar shared by click/fill:
- *   "@e12"        — ref from browser_snapshot (preferred)
+ *   "@e12"         — ref from snapshot (preferred)
  *   "text=Sign in" — find by visible text
- *   anything else — CSS selector
+ *   anything else  — CSS selector
  */
 function findArgs(target, action, value) {
   if (target.startsWith('text=')) {
@@ -318,15 +36,11 @@ function findArgs(target, action, value) {
     if (value !== undefined) command.push(value);
     return command;
   }
-  const command = [action === 'fill' || action === 'type' ? action : action, target];
+  const command = [action, target];
   if (value !== undefined) command.push(value);
   return command;
 }
 
-// ---------------------------------------------------------------------------
-// Core verbs
-// ---------------------------------------------------------------------------
-
 async function state(args = {}, context) {
   const session = sessionFor(args, context);
   let url = '';
@@ -351,19 +65,8 @@ async function snapshot(args = {}, context) {
 
 async function screenshot(args = {}, context) {
   const session = sessionFor(args, 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], { context });
-  const buffer = fs.readFileSync(file);
-  return {
-    ...sessionInfo(session),
-    base64: buffer.toString('base64'),
-    bytes: buffer.length,
-    mode: args.fullPage ? 'full page' : 'viewport',
-    path: file,
-  };
+  const shot = await capture.screenshot(session, args, context);
+  return { ...sessionInfo(session), ...shot };
 }
 
 async function click(args = {}, context) {
@@ -425,18 +128,6 @@ async function wait(args = {}, context) {
   throw new Error('wait requires one of: selector, url, ms');
 }
 
-async function tabs(args = {}, context) {
-  const session = sessionFor(args, context);
-  if (args.action === 'select' && args.tab) {
-    return run(session, ['tab', args.tab], { context });
-  }
-  if (args.action === 'new') {
-    return run(session, ['tab', 'new', ...(args.url ? [args.url] : [])], { context });
-  }
-  const result = await run(session, ['tab'], { context });
-  return { ...sessionInfo(session), tabs: result?.data?.tabs || result?.tabs || [] };
-}
-
 /**
  * Full agent-browser CLI passthrough — the escape hatch that keeps the tool
  * surface small while staying turing complete for browsers. Network mocking,
@@ -557,42 +248,36 @@ async function close(args = {}, context) {
   const session = sessionFor(args, context);
   // Attached mode drives the user's visible surface — never close it from
   // the tool; just forget the session bookkeeping.
-  if (mode() !== 'attached') {
+  if (backend.mode() !== 'attached') {
     await cli.runCli(['close'], { session });
   }
-  attachedSessions.delete(session);
-  knownSessions.delete(session);
-}
-
-/** 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'], cliOptions(session, { timeoutMs: 15_000 }));
-  return result?.data?.cdpUrl || result?.cdpUrl || null;
+  sessions.attachedSessions.delete(session);
+  sessions.knownSessions.delete(session);
 }
 
 module.exports = {
-  bridgeFileCandidates,
-  cdpEndpoint,
-  cdpUrlForSession,
+  // Routing façade (backend.js) — kept here so engine stays the one import.
+  bridgeFileCandidates: backend.bridgeFileCandidates,
+  cdpEndpoint: backend.cdpEndpoint,
+  mode: backend.mode,
+  readBridgeAdvertisement: backend.readBridgeAdvertisement,
+  // Session façade (sessions.js).
+  knownSessions: sessions.knownSessions,
+  sessionFor,
+  sessionInfo,
+  // Verbs.
   click,
   close,
   cua,
   evaluate,
   fill,
-  knownSessions,
   loadState,
-  mode,
   open,
   passthrough,
   press,
-  readBridgeAdvertisement,
   saveState,
   screenshot,
-  sessionFor,
-  sessionInfo,
   snapshot,
   state,
-  tabs,
   wait,
 };

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

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * The browser toolbox entry — one entry, four capability sections.
+ *
+ * Action names are short verbs; the toolbox layer prefixes them with the
+ * entry id, so agents see toolbox__browser_open, toolbox__browser_record_start,
+ * and so on. (Never toolbox__browser_browser_open — the name stutter that
+ * made agents guess wrong is dead.)
+ */
+
+function withCapability(tools, capability) {
+  return tools.map((tool) => ({ ...tool, capability }));
+}
+
+const DESCRIPTION = 'Web browsing with one persistent browser per chat session: '
+  + 'open pages, read them as @ref snapshots, click/fill/press, run JavaScript, '
+  + 'screenshot, record WebM videos, and reuse saved logins. Visible to the user '
+  + 'in the desktop app split view; headless everywhere else — same actions either way.';
+
+const ACTIONS = [
+  ...withCapability(require('./tools'), 'core'),
+  ...withCapability(require('./cua-tools'), 'computer-use'),
+  ...withCapability(require('./recorder-tools'), 'recording'),
+  ...withCapability(require('./auth-tools'), 'auth'),
+];
+
+module.exports = { ACTIONS, DESCRIPTION };

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

@@ -1,10 +1,10 @@
 'use strict';
 
 /**
- * Recorder tools — session recording as a first-class primitive any agent can
- * use (QA bots especially). Captures the browser session — including the
- * desktop app's visible in-tab webview — to a WebM file stored with the
- * Amalgm project the work belongs to.
+ * Recorder actions — session recording as a first-class primitive any agent
+ * can use (QA bots especially). Captures the browser session — including the
+ * desktop app's visible in-tab webview, cropped so the file shows only the
+ * page — to a local WebM stored with the Amalgm project the work belongs to.
  */
 
 const { textResult, errorResult } = require('../lib/tool-result');