amalgm 0.1.144 → 0.1.145

package/runtime/scripts/amalgm-mcp/tests/browser-tools-surface.test.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const { ACTIONS } = require('../browser');
+const delta = require('../browser/delta');
+
+function names() {
+  return ACTIONS.map((action) => action.name);
+}
+
+function action(name) {
+  return ACTIONS.find((entry) => entry.name === name);
+}
+
+test('tool surface: promoted verbs present, cua merged, no duplicates', () => {
+  const all = names();
+  assert.equal(new Set(all).size, all.length, `duplicate action names: ${all.join(', ')}`);
+
+  for (const expected of ['open', 'snapshot', 'click', 'fill', 'press', 'select', 'eval', 'wait', 'cli', 'close',
+    'dialog', 'tab', 'console', 'cua',
+    'record_start', 'record_stop', 'record_list',
+    'auth_list', 'auth_link_create', 'auth_save', 'auth_load']) {
+    assert.ok(all.includes(expected), `missing action: ${expected}`);
+  }
+  // The eight cua_* tools are merged into `cua`.
+  assert.equal(all.filter((name) => name.startsWith('cua_')).length, 0,
+    `cua_* actions should be merged into cua: ${all.filter((n) => n.startsWith('cua_')).join(', ')}`);
+});
+
+test('every action has a schema and handler; enums are well-formed', () => {
+  for (const entry of ACTIONS) {
+    assert.equal(typeof entry.handler, 'function', `${entry.name} has no handler`);
+    assert.equal(entry.inputSchema?.type, 'object', `${entry.name} has no object schema`);
+    assert.ok(entry.description, `${entry.name} has no description`);
+  }
+  assert.deepEqual(action('cua').inputSchema.properties.action.enum,
+    ['screenshot', 'click', 'double_click', 'move', 'scroll', 'type', 'keypress', 'drag']);
+  assert.deepEqual(action('dialog').inputSchema.properties.action.enum, ['accept', 'dismiss']);
+  assert.deepEqual(action('tab').inputSchema.properties.action.enum, ['list', 'switch', 'new', 'close']);
+});
+
+test('cua validates per-action arguments without touching a browser', async () => {
+  const bad = await action('cua').handler({ action: 'click', x: 'nope', y: 4 }, {});
+  assert.equal(bad.isError, true);
+  assert.match(bad.content[0].text, /x must be a finite number/);
+
+  const missingKeys = await action('cua').handler({ action: 'keypress' }, {});
+  assert.equal(missingKeys.isError, true);
+  assert.match(missingKeys.content[0].text, /keys is required/);
+
+  const shortPath = await action('cua').handler({ action: 'drag', path: [{ x: 1, y: 2 }] }, {});
+  assert.equal(shortPath.isError, true);
+  assert.match(shortPath.content[0].text, /at least two/);
+
+  const unknown = await action('cua').handler({ action: 'fly' }, {});
+  assert.equal(unknown.isError, true);
+  assert.match(unknown.content[0].text, /action must be one of/);
+});
+
+test('dialog and tab validate arguments without touching a browser', async () => {
+  const badDialog = await action('dialog').handler({ action: 'shrug' }, {});
+  assert.equal(badDialog.isError, true);
+
+  const badSwitch = await action('tab').handler({ action: 'switch' }, {});
+  assert.equal(badSwitch.isError, true);
+  assert.match(badSwitch.content[0].text, /id is required/);
+});
+
+test('clipOutput passes short text through and marks truncation explicitly', () => {
+  assert.equal(delta.clipOutput('hello', 100), 'hello');
+  const clipped = delta.clipOutput('x'.repeat(500), 100, 'Scope it.');
+  assert.ok(clipped.startsWith('x'.repeat(100)));
+  assert.match(clipped, /Output truncated: showing 100 of 500 chars\. Scope it\./);
+});
+
+test('delta remembers state and parses probe results', () => {
+  delta.remember('t-session', { url: 'https://a.example/', title: 'A' });
+  assert.deepEqual(delta.lastStates.get('t-session'), { url: 'https://a.example/', title: 'A' });
+  delta.remember('t-session', { url: '' }); // no url — must not overwrite
+  assert.equal(delta.lastStates.get('t-session').url, 'https://a.example/');
+  delta.lastStates.delete('t-session');
+
+  assert.deepEqual(
+    delta.parseProbe({ result: JSON.stringify({ url: 'https://b.example/', title: 'B' }) }),
+    { url: 'https://b.example/', title: 'B' },
+  );
+  assert.equal(delta.parseProbe({ result: 'not json' }), null);
+});
+
+test('delta render: warnings first, facts after, dialog short-circuits', () => {
+  const rendered = delta.render({
+    action: 'fill',
+    target: '#email',
+    targetEnabled: true,
+    value: { before: '', after: 'a@example.com', changed: true },
+    page: { url: 'https://x.example/form', title: 'Form', urlChanged: false },
+    warnings: [],
+  });
+  assert.match(rendered, /→ Value: "" → "a@example\.com"/);
+  assert.match(rendered, /→ Page: https:\/\/x\.example\/form \("Form"\) \(no navigation\)/);
+
+  const disabled = delta.render({
+    action: 'click',
+    target: '#save',
+    targetEnabled: false,
+    page: { url: 'https://x.example/', urlChanged: false },
+    warnings: ['Target #save was disabled when click ran — it likely had no effect.'],
+  });
+  assert.ok(disabled.startsWith('⚠ Target #save was disabled'), disabled);
+
+  const dialog = delta.render({
+    action: 'click',
+    target: '#confirm',
+    page: { dialog: 'A JavaScript confirm dialog is blocking the page.' },
+    warnings: [],
+  });
+  assert.match(dialog, /⚠ .*confirm dialog is blocking/);
+  assert.ok(!dialog.includes('→'), 'dialog delta should carry no page facts');
+
+  const navigated = delta.render({
+    action: 'click',
+    target: '@e3',
+    page: { url: 'https://x.example/next', title: 'Next', urlChanged: true },
+    warnings: [],
+  });
+  assert.match(navigated, /→ Navigated to https:\/\/x\.example\/next/);
+  assert.match(navigated, /stale — re-run snapshot/);
+
+  const deadKey = delta.render({
+    action: 'press',
+    keys: { dispatched: 0 },
+    page: { url: 'https://x.example/', urlChanged: false },
+    warnings: [],
+  });
+  assert.match(deadKey, /No keydown events reached the page/);
+
+  assert.equal(delta.render(null), '');
+});
+
+test('evidence verbs attach the typed delta object as metadata', () => {
+  // The contract: rendered text for the agent, machine-readable facts for
+  // everything else. Verified live in e2e; here we pin the result shape by
+  // checking the handler source wires evidenceResult for the element verbs.
+  const fs = require('node:fs');
+  const source = fs.readFileSync(require.resolve('../browser/tools.js'), 'utf8');
+  for (const verb of ["action: 'click'", "action: 'fill'", "action: 'press'", "action: 'select'"]) {
+    assert.ok(source.includes(verb), `${verb} not wired through withEvidence`);
+  }
+});
+
+test('auth_list summarizes by default and never dumps unbounded lists', async () => {
+  // The handler reads the real local store; whatever is in it, the summary
+  // contract must hold: totals + capped recent lists, full only on opt-in.
+  const result = await action('auth_list').handler({});
+  assert.ok(!result.isError, result.content?.[0]?.text);
+  const parsed = JSON.parse(result.content[0].text);
+  for (const key of ['profiles', 'bundles', 'loginSessions']) {
+    assert.equal(typeof parsed[key].total, 'number', `${key} missing total`);
+    assert.ok(Array.isArray(parsed[key].recent), `${key} missing recent`);
+    assert.ok(parsed[key].recent.length <= 15, `${key} recent not capped`);
+  }
+  assert.ok(result.content[0].text.length < 30_000, 'summary output should stay bounded');
+});

package/runtime/scripts/amalgm-mcp/tests/core-tools.test.js

@@ -36,15 +36,15 @@ test('core tool actions carry stable toolbox ids', () => {
   const browserOpen = CORE_TOOLS.find((tool) => tool.name === 'open');
   const notifyUser = CORE_TOOLS.find((tool) => tool.name === 'notify_user');
   const listApps = CORE_TOOLS.find((tool) => tool.name === 'list_apps');
-  const cuaClick = CORE_TOOLS.find((tool) => tool.name === 'cua_click');
+  const cua = CORE_TOOLS.find((tool) => tool.name === 'cua');
   const recordStart = CORE_TOOLS.find((tool) => tool.name === 'record_start');
 
   assert.equal(browserOpen.toolboxToolId, 'browser');
   assert.equal(browserOpen.toolboxActionId, 'browser.open');
   assert.equal(listApps.toolboxToolId, 'computer-use');
   assert.equal(listApps.toolboxActionId, 'computer-use.list_apps');
-  assert.equal(cuaClick.toolboxToolId, 'browser');
-  assert.equal(cuaClick.toolboxActionId, 'browser.cua_click');
+  assert.equal(cua.toolboxToolId, 'browser');
+  assert.equal(cua.toolboxActionId, 'browser.cua');
   assert.equal(recordStart.toolboxActionId, 'browser.record_start');
   assert.equal(notifyUser.toolboxToolId, 'notifications');
   assert.equal(notifyUser.toolboxActionId, 'notifications.notify_user');
@@ -74,16 +74,12 @@ test('browser is a single toolbox entry holding every browser action', () => {
     'eval',
     'wait',
     'cli',
+    'dialog',
+    'tab',
+    'console',
     'close',
-    // computer use
-    'cua_screenshot',
-    'cua_click',
-    'cua_double_click',
-    'cua_move',
-    'cua_scroll',
-    'cua_type',
-    'cua_keypress',
-    'cua_drag',
+    // computer use — one action with an action field, not eight
+    'cua',
     // recording
     'record_start',
     'record_stop',
@@ -123,8 +119,8 @@ test('browser actions carry capability tags so UIs can section one card', () =>
     .filter((tool) => tool.capability === capability)
     .map((tool) => tool.name);
 
-  assert.equal(byCapability('core').length, 11);
-  assert.equal(byCapability('computer-use').every((name) => name.startsWith('cua_')), true);
+  assert.equal(byCapability('core').length, 14);
+  assert.deepEqual(byCapability('computer-use'), ['cua']);
   assert.deepEqual(byCapability('recording'), ['record_start', 'record_stop', 'record_list']);
   assert.deepEqual(byCapability('auth'), ['auth_list', 'auth_link_create', 'auth_save', 'auth_load']);
   assert.equal(browser.tools.every((tool) => Boolean(tool.capability)), true);
@@ -133,12 +129,19 @@ test('browser actions carry capability tags so UIs can section one card', () =>
 test('loadouts from every browser era still grant the current actions', () => {
   const { loadoutContainsToolOrAction } = require('../toolbox/loadout-context');
 
-  // Era-1 group id grants exactly that group's actions.
+  // Era-1 group id grants exactly that group's actions — including the
+  // era-4 merged `cua` action.
   const cuaLoadout = new Set(['browser_cua']);
+  assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.cua'), true);
   assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.cua_click'), true);
   assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.record_start'), false);
   assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.open'), false);
 
+  // Era-3 fine-grained cua_* grants cover the merged `cua` action.
+  const cuaActionLoadout = new Set(['browser.cua_click']);
+  assert.equal(loadoutContainsToolOrAction(cuaActionLoadout, 'browser', 'browser.cua'), true);
+  assert.equal(loadoutContainsToolOrAction(cuaActionLoadout, 'browser', 'browser.open'), false);
+
   // Era-1 fine-grained action ids map 1:1.
   const actionLoadout = new Set(['browser_recording.record_start']);
   assert.equal(loadoutContainsToolOrAction(actionLoadout, 'browser', 'browser.record_start'), true);

package/runtime/scripts/amalgm-mcp/toolbox/loadout-context.js

@@ -16,9 +16,14 @@ const FIRST_PARTY_TOOL_IDS = new Set([
 // granting the same capability. Frozen maps; these never grow.
 //   era 1: four toolbox entries (browser + browser_cua/_recording/_auth)
 //   era 2: one entry, prefixed action names (browser.browser_open)
-//   era 3 (now): one entry, short verbs (browser.open); the three auth list
+//   era 3: one entry, short verbs (browser.open); the three auth list
 //          actions merged into auth_list.
+//   era 4 (now): the eight cua_* actions merged into one `cua` action.
 const OLD_BROWSER_ACTION_NAMES = {
+  cua: [
+    'cua_screenshot', 'cua_click', 'cua_double_click', 'cua_move',
+    'cua_scroll', 'cua_type', 'cua_keypress', 'cua_drag',
+  ],
   open: ['browser_open'],
   snapshot: ['browser_snapshot'],
   screenshot: ['browser_screenshot'],
@@ -37,6 +42,7 @@ const OLD_BROWSER_ACTION_NAMES = {
 
 const LEGACY_BROWSER_GROUP_ACTIONS = {
   browser_cua: new Set([
+    'cua',
     'cua_screenshot', 'cua_click', 'cua_double_click', 'cua_move',
     'cua_scroll', 'cua_type', 'cua_keypress', 'cua_drag',
   ]),

package/runtime/scripts/chat-core/tool-shape.js

@@ -83,7 +83,7 @@ function toolKind(name = '', input = {}, metadata = {}) {
 function browserAction(name) {
   const match = String(name || '').match(/^(?:toolbox__browser_|browser_)(.+)$/);
   if (match) return match[1].replace(/^browser_/, '');
-  if (/^(?:record_(?:start|stop|list)|cua_[a-z_]+)$/.test(name)) return name;
+  if (/^(?:record_(?:start|stop|list)|cua(?:_[a-z_]+)?)$/.test(name)) return name;
   return null;
 }
 
@@ -99,6 +99,15 @@ function titleFromMcp(tool, input = {}) {
   if (action === 'eval') return 'Running JavaScript in browser';
   if (action === 'wait') return 'Waiting for page';
   if (action === 'cli') return Array.isArray(input.args) ? `Browser: ${compactText(input.args.join(' '), 60)}` : 'Running browser command';
+  if (action === 'cua') {
+    const cuaAction = String(input.action || '');
+    if (cuaAction === 'screenshot') return 'Taking browser screenshot';
+    if (cuaAction === 'type') return input.text ? `Typing "${compactText(input.text, 60)}"` : 'Typing in browser';
+    return cuaAction ? `Browser ${cuaAction.replace(/_/g, ' ')} (coordinates)` : 'Browser computer-use action';
+  }
+  if (action === 'dialog') return input.action === 'dismiss' ? 'Dismissing browser dialog' : 'Accepting browser dialog';
+  if (action === 'tab') return `Browser tab ${compactText(String(input.action || 'list'), 20)}`;
+  if (action === 'console') return 'Reading browser console';
   if (action === 'close') return 'Closing browser session';
   if (action === 'record_start') return 'Starting browser recording';
   if (action === 'record_stop') return 'Saving browser recording';

package/runtime/scripts/platform-context.txt

@@ -121,18 +121,21 @@ One persistent browser per chat session. When the Amalgm desktop app is open, th
 
 Browser actions are MCP tools named `toolbox__browser_<action>` (your harness may add its own prefix, e.g. `mcp__amalgm__toolbox__browser_open`).
 
-The loop: `open` a URL → `snapshot` to see interactive elements as @refs → `click`/`fill`/`select`/`press` by @ref → re-`snapshot` after the page changes.
+The loop: `open` a URL → `snapshot` to see interactive elements as @refs → `click`/`fill`/`select`/`press` by @ref. Every acting verb reports its own result — current URL, whether it navigated, and whether a dialog is now blocking — so you usually don't need a follow-up call to see what happened.
 
 - `open` — go to a URL (the session persists across calls; navigate once, then interact)
 - `snapshot` — read the page: every interactive element gets a stable @ref
 - `click` / `fill` / `press` — act on @refs, CSS selectors, or `text=Label` targets
 - `select` — choose an option in a native dropdown (clicks and key presses cannot drive those)
+- `dialog` — accept or dismiss a blocking alert/confirm/prompt (with optional prompt text)
+- `tab` — list/switch/new/close tabs; `_blank` links and popups become tabs with stable ids like "t2"
+- `console` — read the page's console logs and uncaught errors for this session
 - `eval` — run JavaScript in the page and get the result (bare expressions or `return` bodies both work)
 - `wait` — wait for a selector, URL, or delay
 - `screenshot` — PNG when you need pixels (snapshot is cheaper for driving); image coordinates match cua input 1:1
 - `cli` — the full agent-browser command surface: scroll, hover, back, cookies, storage, network, traces, find-by-role, and more
 - `close` — end the session (in the desktop app this also tidies away its split view)
-- `cua_screenshot` / `cua_click` / `cua_type` / … — coordinate-based control for vision loops. In the desktop app, text/key CUA actions are scoped inside the target page so they cannot type into Amalgm's own chat UI.
+- `cua` — coordinate-based control for vision loops, one tool with an action field (screenshot/click/double_click/move/scroll/type/keypress/drag). In the desktop app, text/key actions are scoped inside the target page so they cannot type into Amalgm's own chat UI.
 - `record_start` / `record_stop` / `record_list` — capture the session to a local WebM video (QA evidence)
 - `auth_list` / `auth_link_create` / `auth_save` / `auth_load` — reuse logins: in the desktop app the login page opens directly in the split view for the user to sign in; from the web, share the minted link. Save/load encrypted auth bundles afterward