amalgm 0.1.88 → 0.1.89

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

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * CUA (computer-use) tools — coordinate-based browser control, split out from
+ * the main browser surface. Use these only for vision-model loops that work
+ * from screenshots; for everything else the snapshot/@ref tools in the
+ * browser group are faster and more reliable.
+ */
+
+const { textResult, errorResult } = require('../lib/tool-result');
+const engine = require('./engine');
+
+const sessionProperty = {
+  session: { type: 'string', description: 'Browser session/profile id. Defaults to your chat session.' },
+};
+
+function coordinate(value, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) throw new Error(`${name} must be a finite number`);
+  return number;
+}
+
+function handlerFor(action, prepare) {
+  return async (args, ctx) => {
+    try {
+      const prepared = prepare ? prepare(args) : args;
+      const result = await engine.cua(action, prepared, ctx);
+      return textResult(`ok (session: ${result.session || result.browserSessionId || 'default'})`);
+    } catch (err) {
+      return errorResult(`${action} failed: ${err.message}`);
+    }
+  };
+}
+
+module.exports = [
+  {
+    name: 'cua_screenshot',
+    description: 'Capture the browser viewport for a vision loop. Coordinates in the image map 1:1 to cua_click/cua_move coordinates.',
+    inputSchema: { type: 'object', properties: sessionProperty },
+    async handler(args, ctx) {
+      try {
+        const capture = await engine.screenshot({ ...args, fullPage: false }, ctx);
+        return {
+          content: [
+            { type: 'image', data: capture.base64, mimeType: 'image/png' },
+            { type: 'text', text: `Viewport screenshot (${capture.bytes} bytes)` },
+          ],
+        };
+      } catch (err) {
+        return errorResult(`cua_screenshot failed: ${err.message}`);
+      }
+    },
+  },
+  {
+    name: 'cua_click',
+    description: 'Click viewport coordinates.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        x: { type: 'number' },
+        y: { type: 'number' },
+        button: { type: 'number', description: '1 left (default), 2 middle, 3 right' },
+        ...sessionProperty,
+      },
+      required: ['x', 'y'],
+    },
+    handler: handlerFor('cua_click', (args) => ({ ...args, x: coordinate(args.x, 'x'), y: coordinate(args.y, 'y') })),
+  },
+  {
+    name: 'cua_double_click',
+    description: 'Double-click viewport coordinates.',
+    inputSchema: {
+      type: 'object',
+      properties: { x: { type: 'number' }, y: { type: 'number' }, ...sessionProperty },
+      required: ['x', 'y'],
+    },
+    handler: handlerFor('cua_double_click', (args) => ({ ...args, x: coordinate(args.x, 'x'), y: coordinate(args.y, 'y') })),
+  },
+  {
+    name: 'cua_move',
+    description: 'Move the mouse to viewport coordinates.',
+    inputSchema: {
+      type: 'object',
+      properties: { x: { type: 'number' }, y: { type: 'number' }, ...sessionProperty },
+      required: ['x', 'y'],
+    },
+    handler: handlerFor('cua_move', (args) => ({ ...args, x: coordinate(args.x, 'x'), y: coordinate(args.y, 'y') })),
+  },
+  {
+    name: 'cua_scroll',
+    description: 'Scroll from viewport coordinates by scrollX/scrollY pixels.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        x: { type: 'number' },
+        y: { type: 'number' },
+        scrollX: { type: 'number' },
+        scrollY: { type: 'number' },
+        ...sessionProperty,
+      },
+      required: ['x', 'y', 'scrollX', 'scrollY'],
+    },
+    handler: handlerFor('cua_scroll', (args) => ({
+      ...args,
+      x: coordinate(args.x, 'x'),
+      y: coordinate(args.y, 'y'),
+      scrollX: Number(args.scrollX || 0),
+      scrollY: Number(args.scrollY || 0),
+    })),
+  },
+  {
+    name: 'cua_type',
+    description: 'Type text at the focused element with real keystrokes.',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string' }, ...sessionProperty },
+      required: ['text'],
+    },
+    handler: handlerFor('cua_type'),
+  },
+  {
+    name: 'cua_keypress',
+    description: 'Press a key combination, e.g. ["Control", "a"] or ["Enter"].',
+    inputSchema: {
+      type: 'object',
+      properties: { keys: { type: 'array', items: { type: 'string' } }, ...sessionProperty },
+      required: ['keys'],
+    },
+    handler: handlerFor('cua_keypress'),
+  },
+  {
+    name: 'cua_drag',
+    description: 'Drag the mouse through a list of viewport points.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'array',
+          items: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, required: ['x', 'y'] },
+        },
+        ...sessionProperty,
+      },
+      required: ['path'],
+    },
+    handler: handlerFor('cua_drag'),
+  },
+];

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

@@ -0,0 +1,454 @@
+'use strict';
+
+/**
+ * Browser engine: the verb set behind the browser/cua/recorder tools, with
+ * backend routing.
+ *
+ * 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).
+ *
+ * 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/');
+}
+
+function cdpUrl() {
+  if (process.env.AMALGM_BROWSER_CDP_URL) return process.env.AMALGM_BROWSER_CDP_URL;
+  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);
+  } catch {}
+  return null;
+}
+
+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';
+}
+
+function usesElectronBridge() {
+  return mode() === 'electron';
+}
+
+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;
+}
+
+/**
+ * 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.
+ */
+async function ensureReady(session) {
+  if (mode() !== 'attached' || attachedSessions.has(session)) return;
+  const target = cdpUrl();
+  await cli.runCli(['connect', target], { session });
+  try {
+    const tabs = await cli.runCli(['tab'], { 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 });
+  } catch {
+    // No webview target yet — the outer page target still works.
+  }
+  attachedSessions.add(session);
+}
+
+async function run(session, commandArgs, options = {}) {
+  await ensureReady(session);
+  return cli.runCli(commandArgs, { session, ...options });
+}
+
+async function readText(session, commandArgs, timeoutMs) {
+  await ensureReady(session);
+  return cli.readText(commandArgs, session, timeoutMs);
+}
+
+/**
+ * Target grammar shared by click/fill:
+ *   "@e12"        — ref from browser_snapshot (preferred)
+ *   "text=Sign in" — find by visible text
+ *   anything else — CSS selector
+ */
+function findArgs(target, action, value) {
+  if (target.startsWith('text=')) {
+    const command = ['find', 'text', target.slice('text='.length), action];
+    if (value !== undefined) command.push(value);
+    return command;
+  }
+  const command = [action === 'fill' || action === 'type' ? action : action, target];
+  if (value !== undefined) command.push(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 {}
+  try { title = await readText(session, ['get', 'title']); } catch {}
+  return sessionInfo(session, { url, title });
+}
+
+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]);
+  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 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]);
+  const buffer = fs.readFileSync(file);
+  return {
+    ...sessionInfo(session),
+    base64: buffer.toString('base64'),
+    bytes: buffer.length,
+    mode: args.fullPage ? 'full page' : 'viewport',
+    path: file,
+  };
+}
+
+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]);
+  return sessionInfo(session, { clicked: target });
+}
+
+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']);
+  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]);
+  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 data = result?.data ?? result;
+  // agent-browser wraps eval results as { origin, result }.
+  const value = data && typeof data === 'object' && 'result' in data ? data.result : data;
+  return { ...sessionInfo(session), result: value };
+}
+
+async function wait(args = {}, context) {
+  const session = sessionFor(args, context);
+  const timeoutMs = args.timeoutMs || 30_000;
+
+  if (args.ms) {
+    await new Promise((resolve) => setTimeout(resolve, Math.min(Number(args.ms) || 0, 60_000)));
+    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']);
+      if (current.includes(args.url.replace(/\*/g, ''))) return sessionInfo(session, { matched: current });
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    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 });
+    return sessionInfo(session, { matched: args.selector });
+  }
+  throw new Error('wait requires one of: selector, url, ms');
+}
+
+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]);
+  }
+  if (args.action === 'new') {
+    return run(session, ['tab', 'new', ...(args.url ? [args.url] : [])]);
+  }
+  const result = await run(session, ['tab']);
+  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,
+ * cookies, storage, traces, diffs, React inspection: all reachable here.
+ */
+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 });
+  return { ...sessionInfo(session), result: result?.data ?? result };
+}
+
+async function cua(action, args = {}, context) {
+  const session = sessionFor(args, context);
+  if (usesElectronBridge()) return electron.cuaBrowser(action, { ...args, browserSessionId: session }, 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_click') {
+    await run(session, ['mouse', 'move', x, y]);
+    await run(session, ['mouse', 'down', args.button || 1]);
+    await run(session, ['mouse', 'up', args.button || 1]);
+  }
+  if (action === 'cua_double_click') {
+    await run(session, ['mouse', 'move', x, y]);
+    for (let i = 0; i < 2; i += 1) {
+      await run(session, ['mouse', 'down', 1]);
+      await run(session, ['mouse', 'up', 1]);
+    }
+  }
+  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_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]);
+  }
+  return sessionInfo(session, { ok: true });
+}
+
+// ---------------------------------------------------------------------------
+// State save/load (used by browser auth bundles) and lifecycle
+// ---------------------------------------------------------------------------
+
+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]);
+  const stateData = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!args.path) {
+    try { fs.rmSync(file, { force: true }); } catch {}
+  }
+  const current = await state(args, context);
+  return {
+    ...current,
+    state: stateData,
+    path: args.path ? file : undefined,
+    storageKinds: ['cookies', 'localStorage', 'sessionStorage'],
+  };
+}
+
+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');
+  const crypto = require('crypto');
+  let file = args.path;
+  let temporary = false;
+  if (!file) {
+    if (!args.state || typeof args.state !== 'object') throw new Error('state or path is required');
+    file = path.join(os.tmpdir(), `amalgm-browser-state-load-${session}-${Date.now()}-${crypto.randomUUID()}.json`);
+    fs.writeFileSync(file, `${JSON.stringify(args.state, null, 2)}\n`, { mode: 0o600 });
+    temporary = true;
+  }
+  await run(session, ['state', 'load', file]);
+  if (temporary) {
+    try { fs.rmSync(file, { force: true }); } catch {}
+  }
+  return sessionInfo(session, { loaded: true, storageKinds: ['cookies', 'localStorage', 'sessionStorage'] });
+}
+
+async function close(args = {}, context) {
+  const session = sessionFor(args, context);
+  if (usesElectronBridge()) {
+    await electron.closeBrowser({ browserSessionId: session }, context);
+  } else {
+    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'], { session, timeoutMs: 15_000 });
+  return result?.data?.cdpUrl || result?.cdpUrl || null;
+}
+
+module.exports = {
+  cdpUrlForSession,
+  click,
+  close,
+  cua,
+  evaluate,
+  fill,
+  knownSessions,
+  loadState,
+  mode,
+  open,
+  passthrough,
+  press,
+  saveState,
+  screenshot,
+  sessionFor,
+  sessionInfo,
+  snapshot,
+  state,
+  tabs,
+  usesElectronBridge,
+  wait,
+};

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

@@ -0,0 +1,82 @@
+'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.
+ */
+
+const { textResult, errorResult } = require('../lib/tool-result');
+const recorder = require('./recorder');
+
+const commonProperties = {
+  session: { type: 'string', description: 'Browser session to record. Defaults to your chat session.' },
+  projectPath: {
+    type: 'string',
+    description: 'Amalgm project directory; the video is saved under <project>/.amalgm/recordings/. Defaults to the project this chat session belongs to, falling back to ~/.amalgm/browser-sessions/.',
+  },
+};
+
+module.exports = [
+  {
+    name: 'record_start',
+    description: 'Start recording the browser session to a WebM video. Stop with record_stop. One recording per session at a time.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Recording name used in the filename, e.g. "login-flow-qa"' },
+        fps: { type: 'number', description: 'Frames per second (1-30, default 10)' },
+        ...commonProperties,
+      },
+    },
+    async handler(args, ctx) {
+      try {
+        const result = await recorder.start(args, ctx);
+        return textResult(`Recording started (${result.fps} fps)\nFile: ${result.path}\nSession: ${result.session}`);
+      } catch (err) {
+        return errorResult(`record_start failed: ${err.message}`);
+      }
+    },
+  },
+  {
+    name: 'record_stop',
+    description: 'Stop the active recording and save the WebM file. Returns the local file path.',
+    inputSchema: { type: 'object', properties: commonProperties },
+    async handler(args, ctx) {
+      try {
+        const result = await recorder.stop(args, ctx);
+        return {
+          content: [{
+            type: 'text',
+            text: `Recording saved: ${result.path}\n`
+              + `${result.frames} frames, ${Math.round(result.durationMs / 1000)}s, ${result.bytes} bytes`,
+          }],
+          metadata: {
+            browserVideo: {
+              path: result.path,
+              relativePath: result.relativePath,
+              bytes: result.bytes,
+              mimeType: result.mimeType,
+            },
+          },
+        };
+      } catch (err) {
+        return errorResult(`record_stop failed: ${err.message}`);
+      }
+    },
+  },
+  {
+    name: 'record_list',
+    description: 'List saved recordings for a project (or the session fallback directory).',
+    inputSchema: { type: 'object', properties: commonProperties },
+    async handler(args, ctx) {
+      try {
+        const result = recorder.list(args, ctx);
+        return textResult(JSON.stringify(result, null, 2));
+      } catch (err) {
+        return errorResult(`record_list failed: ${err.message}`);
+      }
+    },
+  },
+];