amalgm 0.1.91 → 0.1.92

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

@@ -4,6 +4,7 @@ const assert = require('node:assert/strict');
 const test = require('node:test');
 
 const { CORE_TOOL_GROUPS, CORE_TOOLS } = require('../server/core-tools');
+const { toolboxMcpToolName } = require('../toolbox/names');
 
 test('core tools are grouped into first-party toolbox-style defaults', () => {
   assert.deepEqual(CORE_TOOL_GROUPS.map((group) => group.id), [
@@ -23,19 +24,19 @@ test('core tool grouping preserves handler definitions for MCP surface wrapping'
 
   assert.equal(CORE_TOOLS.length, groupedTools.length);
   assert.deepEqual(CORE_TOOLS.map((tool) => tool.name), groupedTools.map((tool) => tool.name));
-  assert.equal(CORE_TOOLS.some((tool) => tool.name === 'browser_open'), true);
+  assert.equal(CORE_TOOLS.some((tool) => tool.name === 'open' && tool.toolboxToolId === 'browser'), true);
   assert.equal(CORE_TOOLS.some((tool) => tool.name === 'notify_user'), true);
   assert.equal(CORE_TOOLS.some((tool) => tool.name === 'append_change_log'), true);
 });
 
 test('core tool actions carry stable toolbox ids', () => {
-  const browserOpen = CORE_TOOLS.find((tool) => tool.name === 'browser_open');
+  const browserOpen = CORE_TOOLS.find((tool) => tool.name === 'open');
   const notifyUser = CORE_TOOLS.find((tool) => tool.name === 'notify_user');
   const cuaClick = CORE_TOOLS.find((tool) => tool.name === 'cua_click');
   const recordStart = CORE_TOOLS.find((tool) => tool.name === 'record_start');
 
   assert.equal(browserOpen.toolboxToolId, 'browser');
-  assert.equal(browserOpen.toolboxActionId, 'browser.browser_open');
+  assert.equal(browserOpen.toolboxActionId, 'browser.open');
   assert.equal(cuaClick.toolboxToolId, 'browser');
   assert.equal(cuaClick.toolboxActionId, 'browser.cua_click');
   assert.equal(recordStart.toolboxActionId, 'browser.record_start');
@@ -47,16 +48,16 @@ test('browser is a single toolbox entry holding every browser action', () => {
   const browser = CORE_TOOL_GROUPS.find((group) => group.id === 'browser');
   assert.deepEqual(browser.tools.map((tool) => tool.name), [
     // core verbs
-    'browser_open',
-    'browser_snapshot',
-    'browser_screenshot',
-    'browser_click',
-    'browser_fill',
-    'browser_press',
-    'browser_eval',
-    'browser_wait',
-    'browser_cli',
-    'browser_close',
+    'open',
+    'snapshot',
+    'screenshot',
+    'click',
+    'fill',
+    'press',
+    'eval',
+    'wait',
+    'cli',
+    'close',
     // computer use
     'cua_screenshot',
     'cua_click',
@@ -71,12 +72,10 @@ test('browser is a single toolbox entry holding every browser action', () => {
     'record_stop',
     'record_list',
     // auth / profiles
-    'browser_profiles_list',
-    'browser_auth_bundles_list',
-    'browser_login_sessions_list',
-    'browser_auth_link_create',
-    'browser_auth_save',
-    'browser_auth_load',
+    'auth_list',
+    'auth_link_create',
+    'auth_save',
+    'auth_load',
   ]);
 
   // No other browser-ish groups exist.
@@ -86,6 +85,21 @@ test('browser is a single toolbox entry holding every browser action', () => {
   );
 });
 
+test('browser MCP names never stutter', () => {
+  // Regression for the 2026-06-10 trap: action ids like browser.browser_open
+  // rendered as toolbox__browser_browser_open, and agents reasonably guessed
+  // toolbox__browser_open — which did not exist. Short action names make the
+  // guessable name the real one.
+  const browser = CORE_TOOL_GROUPS.find((group) => group.id === 'browser');
+  for (const tool of browser.tools) {
+    const mcpName = toolboxMcpToolName({ id: tool.toolboxActionId });
+    assert.equal(mcpName.startsWith('toolbox__browser_'), true);
+    assert.equal(mcpName.includes('browser_browser'), false, `${mcpName} stutters`);
+  }
+  assert.equal(toolboxMcpToolName({ id: 'browser.open' }), 'toolbox__browser_open');
+  assert.equal(toolboxMcpToolName({ id: 'browser.record_start' }), 'toolbox__browser_record_start');
+});
+
 test('browser actions carry capability tags so UIs can section one card', () => {
   const browser = CORE_TOOL_GROUPS.find((group) => group.id === 'browser');
   const byCapability = (capability) => browser.tools
@@ -95,31 +109,47 @@ test('browser actions carry capability tags so UIs can section one card', () =>
   assert.equal(byCapability('core').length, 10);
   assert.equal(byCapability('computer-use').every((name) => name.startsWith('cua_')), true);
   assert.deepEqual(byCapability('recording'), ['record_start', 'record_stop', 'record_list']);
-  assert.equal(byCapability('auth').length, 6);
+  assert.deepEqual(byCapability('auth'), ['auth_list', 'auth_link_create', 'auth_save', 'auth_load']);
   assert.equal(browser.tools.every((tool) => Boolean(tool.capability)), true);
 });
 
-test('legacy capability-group loadouts still grant the collapsed actions', () => {
+test('loadouts from every browser era still grant the current actions', () => {
   const { loadoutContainsToolOrAction } = require('../toolbox/loadout-context');
 
-  // Old group id grants exactly that group's actions.
+  // Era-1 group id grants exactly that group's actions.
   const cuaLoadout = new Set(['browser_cua']);
   assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.cua_click'), true);
   assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.record_start'), false);
-  assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.browser_open'), false);
+  assert.equal(loadoutContainsToolOrAction(cuaLoadout, 'browser', 'browser.open'), false);
 
-  // Old fine-grained action ids map 1:1.
+  // 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);
   assert.equal(loadoutContainsToolOrAction(actionLoadout, 'browser', 'browser.record_stop'), false);
 
-  // New single entry grants everything.
+  // Era-1 auth group covers the merged auth_list (and its old spellings).
+  const authLoadout = new Set(['browser_auth']);
+  assert.equal(loadoutContainsToolOrAction(authLoadout, 'browser', 'browser.auth_list'), true);
+  assert.equal(loadoutContainsToolOrAction(authLoadout, 'browser', 'browser.auth_save'), true);
+  assert.equal(loadoutContainsToolOrAction(authLoadout, 'browser', 'browser.open'), false);
+  const authActionLoadout = new Set(['browser_auth.browser_profiles_list']);
+  assert.equal(loadoutContainsToolOrAction(authActionLoadout, 'browser', 'browser.auth_list'), true);
+
+  // Era-2 fine-grained grants (browser.browser_open) cover the renamed verbs.
+  const renamedLoadout = new Set(['browser.browser_open', 'browser.browser_eval']);
+  assert.equal(loadoutContainsToolOrAction(renamedLoadout, 'browser', 'browser.open'), true);
+  assert.equal(loadoutContainsToolOrAction(renamedLoadout, 'browser', 'browser.eval'), true);
+  assert.equal(loadoutContainsToolOrAction(renamedLoadout, 'browser', 'browser.click'), false);
+  const renamedAuthLoadout = new Set(['browser.browser_auth_bundles_list']);
+  assert.equal(loadoutContainsToolOrAction(renamedAuthLoadout, 'browser', 'browser.auth_list'), true);
+
+  // The single entry grants everything.
   const browserLoadout = new Set(['browser']);
-  assert.equal(loadoutContainsToolOrAction(browserLoadout, 'browser', 'browser.browser_open'), true);
+  assert.equal(loadoutContainsToolOrAction(browserLoadout, 'browser', 'browser.open'), true);
   assert.equal(loadoutContainsToolOrAction(browserLoadout, 'browser', 'browser.cua_click'), true);
-  assert.equal(loadoutContainsToolOrAction(browserLoadout, 'browser', 'browser.browser_auth_save'), true);
+  assert.equal(loadoutContainsToolOrAction(browserLoadout, 'browser', 'browser.auth_save'), true);
 
-  // Legacy amalgm.browser aggregate keeps granting browser actions.
+  // The ancient amalgm.browser aggregate keeps granting browser actions.
   const legacyAggregate = new Set(['amalgm.browser']);
-  assert.equal(loadoutContainsToolOrAction(legacyAggregate, 'browser', 'browser.browser_open'), true);
+  assert.equal(loadoutContainsToolOrAction(legacyAggregate, 'browser', 'browser.open'), true);
 });

package/runtime/scripts/amalgm-mcp/tests/platform-context.test.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The platform prompt is what every agent reads about the browser before its
+// first call. It documented a deleted tool surface once (browser_navigate et
+// al.) and agents spent whole sessions calling tools that did not exist —
+// keep it pinned to the real action names.
+
+const CONTEXT_PATH = path.join(__dirname, '..', '..', 'platform-context.txt');
+
+test('platform context documents the live browser surface, not a deleted one', () => {
+  const text = fs.readFileSync(CONTEXT_PATH, 'utf8');
+
+  for (const ghost of [
+    'browser_navigate',
+    'browser_type',
+    'browser_get_text',
+    'browser_evaluate',
+    'browser_start_video',
+    'browser_stop_video',
+  ]) {
+    assert.equal(text.includes(ghost), false, `platform context still documents deleted tool ${ghost}`);
+  }
+
+  assert.equal(text.includes('toolbox__browser_open'), true, 'platform context should show the real MCP name shape');
+  for (const action of ['`open`', '`snapshot`', '`record_start`', '`auth_link_create`']) {
+    assert.equal(text.includes(action), true, `platform context should document ${action}`);
+  }
+});
+
+test('platform context browser names match the registered actions', () => {
+  const text = fs.readFileSync(CONTEXT_PATH, 'utf8');
+  const { CORE_TOOL_GROUPS } = require('../server/core-tools');
+  const browser = CORE_TOOL_GROUPS.find((group) => group.id === 'browser');
+  // Every core verb the prompt teaches must exist under that exact name.
+  const documented = ['open', 'snapshot', 'click', 'fill', 'press', 'eval', 'wait', 'screenshot', 'cli', 'close'];
+  const registered = new Set(browser.tools.map((tool) => tool.name));
+  for (const name of documented) {
+    assert.equal(registered.has(name), true, `prompt documents "${name}" but the toolbox does not register it`);
+    assert.equal(text.includes(`\`${name}\``), true, `prompt should mention ${name}`);
+  }
+});

package/runtime/scripts/amalgm-mcp/tests/system-catalog.test.js

@@ -17,12 +17,12 @@ test('system toolbox catalog exposes first-party default tools', () => {
   assert.equal(catalog.tools.browser.origin, 'system');
   assert.equal(catalog.tools.browser.policy.firstParty, true);
   assert.equal(
-    catalog.toolActions['browser.browser_open'].sourceAction.mcpToolName,
-    'toolbox__browser_browser_open',
+    catalog.toolActions['browser.open'].sourceAction.mcpToolName,
+    'toolbox__browser_open',
   );
   assert.equal(
-    catalog.toolActions['browser.browser_open'].sourceAction.handlerName,
-    'browser_open',
+    catalog.toolActions['browser.open'].sourceAction.handlerName,
+    'open',
   );
   assert.equal(
     catalog.toolActions['notifications.notify_user'].sourceAction.mcpToolName,

package/runtime/scripts/amalgm-mcp/tests/toolbox-service.test.js

@@ -161,7 +161,7 @@ test('toolbox service overlays first-party system catalog entries', () => {
   const service = createToolboxService(createRepository());
   const catalog = service.readCatalog();
   const browser = service.getTool('browser', { includeActions: false });
-  const navigate = service.getAction('browser.browser_open');
+  const navigate = service.getAction('browser.open');
 
   assert.equal(catalog.tools.amalgm, undefined);
   assert.equal(catalog.toolActions['amalgm.notify_user'], undefined);
@@ -170,7 +170,7 @@ test('toolbox service overlays first-party system catalog entries', () => {
   assert.equal(catalog.tools.browser.owner, 'amalgm');
   assert.equal(browser.tool.name, 'Browser');
   assert.equal(browser.actions, undefined);
-  assert.equal(navigate.action.sourceAction.mcpToolName, 'toolbox__browser_browser_open');
+  assert.equal(navigate.action.sourceAction.mcpToolName, 'toolbox__browser_open');
   assert.equal(service.listTools({ origin: 'system' }).tools.some((tool) => tool.id === 'browser'), true);
 });
 

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

@@ -11,31 +11,54 @@ const FIRST_PARTY_TOOL_IDS = new Set([
   'browser',
 ]);
 
-// Browser used to ship as four toolbox entries; it is one (`browser`) now.
-// Loadouts saved against the old capability groups keep working: the old
-// group id grants exactly the actions that group contained, and old action
-// ids map 1:1 onto `browser.<action>`. Frozen sets — these never grow.
+// Browser action names through history — loadouts saved in any era keep
+// 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
+//          actions merged into auth_list.
+const OLD_BROWSER_ACTION_NAMES = {
+  open: ['browser_open'],
+  snapshot: ['browser_snapshot'],
+  screenshot: ['browser_screenshot'],
+  click: ['browser_click'],
+  fill: ['browser_fill'],
+  press: ['browser_press'],
+  eval: ['browser_eval'],
+  wait: ['browser_wait'],
+  cli: ['browser_cli'],
+  close: ['browser_close'],
+  auth_list: ['browser_profiles_list', 'browser_auth_bundles_list', 'browser_login_sessions_list'],
+  auth_link_create: ['browser_auth_link_create'],
+  auth_save: ['browser_auth_save'],
+  auth_load: ['browser_auth_load'],
+};
+
 const LEGACY_BROWSER_GROUP_ACTIONS = {
   browser_cua: new Set([
     'cua_screenshot', 'cua_click', 'cua_double_click', 'cua_move',
     'cua_scroll', 'cua_type', 'cua_keypress', 'cua_drag',
   ]),
   browser_recording: new Set(['record_start', 'record_stop', 'record_list']),
-  browser_auth: new Set([
-    'browser_profiles_list', 'browser_auth_bundles_list',
-    'browser_login_sessions_list', 'browser_auth_link_create',
-    'browser_auth_save', 'browser_auth_load',
-  ]),
+  browser_auth: new Set(['auth_list', 'auth_link_create', 'auth_save', 'auth_load']),
 };
 
 function legacyBrowserLoadoutHas(loadoutToolIds, actionId) {
   if (!actionId.startsWith('browser.')) return false;
   const action = actionId.slice('browser.'.length);
+  const oldNames = OLD_BROWSER_ACTION_NAMES[action] || [];
+  // Era-2 fine-grained grants: browser.browser_open ⇒ browser.open.
+  for (const oldName of oldNames) {
+    if (loadoutToolIds.has(`browser.${oldName}`)) return true;
+  }
+  // Era-1 group grants, including their fine-grained spellings.
   for (const [legacyId, actions] of Object.entries(LEGACY_BROWSER_GROUP_ACTIONS)) {
     if (!actions.has(action)) continue;
     if (loadoutToolIds.has(legacyId)) return true;
-    if (loadoutToolIds.has(`${legacyId}.${action}`)) return true;
     if (loadoutToolIds.has(`amalgm.${legacyId}`)) return true;
+    for (const name of [action, ...oldNames]) {
+      if (loadoutToolIds.has(`${legacyId}.${name}`)) return true;
+    }
   }
   return false;
 }

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

@@ -75,18 +75,35 @@ function toolKind(name = '', input = {}, metadata = {}) {
   return 'unknown';
 }
 
+/**
+ * Browser action out of a tool name, across naming eras: current
+ * toolbox__browser_open, era-2 toolbox__browser_browser_open / browser_open,
+ * and bare record_start/cua_click. Null for non-browser tools.
+ */
+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;
+  return null;
+}
+
 function titleFromMcp(tool, input = {}) {
   const name = String(tool || '');
-  const action = name.replace(/^browser_/, '');
-  if (name === 'browser_open') return input.url ? `Opening ${hostLabel(input.url)}` : 'Opening browser page';
-  if (name === 'browser_snapshot') return 'Reading browser page';
-  if (name === 'browser_screenshot') return 'Taking browser screenshot';
-  if (name === 'browser_fill') return input.text ? `Typing "${compactText(input.text, 60)}"` : 'Typing in browser';
-  if (name === 'browser_click') return 'Clicking in browser';
-  if (name === 'browser_wait') return 'Waiting for page';
-  if (name === 'browser_cli') return Array.isArray(input.args) ? `Browser: ${compactText(input.args.join(' '), 60)}` : 'Running browser command';
-  if (name === 'record_start') return 'Starting browser recording';
-  if (name === 'record_stop') return 'Saving browser recording';
+  const action = browserAction(name);
+  if (action === 'open') return input.url ? `Opening ${hostLabel(input.url)}` : 'Opening browser page';
+  if (action === 'snapshot') return 'Reading browser page';
+  if (action === 'screenshot' || action === 'cua_screenshot') return 'Taking browser screenshot';
+  if (action === 'fill') return input.text ? `Typing "${compactText(input.text, 60)}"` : 'Typing in browser';
+  if (action === 'click') return 'Clicking in browser';
+  if (action === 'press') return input.key ? `Pressing ${compactText(input.key, 20)}` : 'Pressing key in browser';
+  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 === 'close') return 'Closing browser session';
+  if (action === 'record_start') return 'Starting browser recording';
+  if (action === 'record_stop') return 'Saving browser recording';
+  if (action === 'record_list') return 'Listing browser recordings';
+  if (action === 'auth_list') return 'Listing browser logins';
   if (name === 'apps_register') return input.name ? `Registering app ${compactText(input.name, 60)}` : 'Registering app';
   if (name === 'apps_start') return 'Starting app';
   if (name === 'apps_stop') return 'Stopping app';

package/runtime/scripts/platform-context.txt

@@ -115,26 +115,27 @@ Discover and talk to other agents running on the platform.
 
 Agent communication is session-based. Pass the `session_id` on subsequent calls to continue the same conversation — the other agent retains full context. Use this for delegation, second opinions, or cross-model collaboration.
 
-## Browser — Visible Electron Session
-
-You have a persistent browser surface for navigation, interaction, screenshots, and scraping.
-
-- In the desktop app, `browser_*` tools drive Amalgm's visible in-tab Electron browser artifact surface.
-- Browser sessions persist after tool use. Hide/show the artifact surface without closing the session.
-- Outside Electron, the tools can fall back to `agent-browser` for headless/remote browser automation.
-
-- `browser_navigate` — Go to a URL.
-- `browser_screenshot` — Screenshot the current page (base64 PNG).
-- `browser_snapshot` — Token-efficient page snapshot with interactive refs such as `@e1`.
-- `browser_click` — Click an element by ref, CSS selector, text, role, label, placeholder, or test id.
-- `browser_type` — Type text into an input.
-- `browser_get_text` — Extract text content.
-- `browser_evaluate` — Run JavaScript in the page context.
-- `browser_start_video` — Start recording the browser session.
-- `browser_stop_video` — Stop recording and save a WebM under `~/.amalgm/browser-sessions/`.
-- `browser_close` — Close and release resources.
-
-The browser persists across tool calls — navigate once, then interact without re-navigating. Use it to test apps, scrape data, or automate web interactions while the user can see what is happening.
+## Browser
+
+One persistent browser per chat session. When the Amalgm desktop app is open, the user watches it live in a split view; everywhere else it runs headless in the background. Same actions either way — you never pick a mode.
+
+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`/`press` by @ref → re-`snapshot` after the page changes.
+
+- `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
+- `eval` — run JavaScript in the page and get the result
+- `wait` — wait for a selector, URL, or delay
+- `screenshot` — PNG when you need pixels (snapshot is cheaper for driving)
+- `cli` — the full agent-browser command surface: scroll, hover, back, tabs, cookies, storage, network, traces, find-by-role, and more
+- `close` — end the session
+- `cua_screenshot` / `cua_click` / `cua_type` / … — coordinate-based control for vision loops
+- `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: mint a link for the user to sign in, then save/load encrypted auth bundles
+
+Recordings and auth bundles stay on this computer. Use the browser to test apps, scrape data, or automate web interactions.
 
 ---