amalgm 0.1.72 → 0.1.73

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

@@ -0,0 +1,81 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const {
+  buildSystemToolboxCatalog,
+  mergeSystemToolboxCatalog,
+  persistedCatalogWithoutLegacyAggregate,
+} = require('../toolbox/system-catalog');
+
+test('system toolbox catalog exposes first-party default tools', () => {
+  const catalog = buildSystemToolboxCatalog();
+
+  assert.equal(catalog.tools['amalgm.browser'].name, 'Amalgm Browser');
+  assert.equal(catalog.tools['amalgm.browser'].origin, 'system');
+  assert.equal(catalog.tools['amalgm.browser'].policy.firstParty, true);
+  assert.equal(
+    catalog.toolActions['amalgm.browser.browser_navigate'].sourceAction.mcpToolName,
+    'toolbox__amalgm_browser_browser_navigate',
+  );
+  assert.equal(
+    catalog.toolActions['amalgm.browser.browser_navigate'].sourceAction.handlerName,
+    'browser_navigate',
+  );
+  assert.equal(
+    catalog.toolActions['amalgm.notifications.notify_user'].sourceAction.mcpToolName,
+    'toolbox__amalgm_notifications_notify_user',
+  );
+});
+
+test('system toolbox catalog merge preserves persisted records', () => {
+  const merged = mergeSystemToolboxCatalog({
+    version: 1,
+    tools: {
+      'amalgm.browser': {
+        id: 'amalgm.browser',
+        name: 'Persisted Browser',
+        origin: 'system',
+      },
+      'custom.cli': {
+        id: 'custom.cli',
+        name: 'Custom CLI',
+        origin: 'user',
+      },
+    },
+    toolActions: {
+      'amalgm.browser.browser_navigate': {
+        id: 'amalgm.browser.browser_navigate',
+        toolId: 'amalgm.browser',
+        name: 'persisted_navigate',
+      },
+    },
+  });
+
+  assert.equal(merged.tools['amalgm.browser'].name, 'Persisted Browser');
+  assert.equal(merged.tools['custom.cli'].name, 'Custom CLI');
+  assert.equal(
+    merged.toolActions['amalgm.browser.browser_navigate'].name,
+    'persisted_navigate',
+  );
+  assert.equal(merged.toolActions['amalgm.apps.apps_list'].name, 'apps_list');
+});
+
+test('system toolbox catalog omits legacy aggregate amalgm records', () => {
+  const filtered = persistedCatalogWithoutLegacyAggregate({
+    tools: {
+      amalgm: { id: 'amalgm', origin: 'system' },
+      'custom.cli': { id: 'custom.cli', origin: 'user' },
+    },
+    toolActions: {
+      'amalgm.notify_user': { id: 'amalgm.notify_user', toolId: 'amalgm' },
+      'custom.cli.run': { id: 'custom.cli.run', toolId: 'custom.cli' },
+    },
+  });
+
+  assert.equal(filtered.tools.amalgm, undefined);
+  assert.equal(filtered.toolActions['amalgm.notify_user'], undefined);
+  assert.equal(filtered.tools['custom.cli'].id, 'custom.cli');
+  assert.equal(filtered.toolActions['custom.cli.run'].id, 'custom.cli.run');
+});

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

@@ -0,0 +1,250 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const { createToolboxRest } = require('../toolbox/rest');
+const { toolboxMcpToolName } = require('../toolbox/names');
+const { createToolboxService } = require('../toolbox/service');
+
+function sampleToolbox() {
+  return {
+    version: 1,
+    tools: {
+      'acme.tool': {
+        id: 'acme.tool',
+        name: 'Acme Tool',
+        type: 'cli',
+        owner: 'user',
+        origin: 'user',
+        status: 'enabled',
+        source: { command: 'acme' },
+        discovery: { mode: 'single' },
+      },
+      'api.weather': {
+        id: 'api.weather',
+        name: 'Weather API',
+        type: 'api',
+        owner: 'user',
+        origin: 'user',
+        status: 'enabled',
+        source: { baseUrl: 'https://weather.example.test' },
+        discovery: { mode: 'static' },
+      },
+      'remote.mcp': {
+        id: 'remote.mcp',
+        name: 'Remote MCP',
+        type: 'mcp',
+        owner: 'user',
+        origin: 'user',
+        status: 'enabled',
+        source: { transport: 'http', url: 'https://mcp.example.test' },
+        discovery: { mode: 'dynamic' },
+      },
+      amalgm: {
+        id: 'amalgm',
+        name: 'amalgm',
+        type: 'mcp',
+        owner: 'amalgm',
+        origin: 'system',
+        status: 'enabled',
+        source: { transport: 'http', url: 'http://127.0.0.1:8083/mcp' },
+        discovery: { mode: 'dynamic' },
+      },
+    },
+    toolActions: {
+      'acme.tool.run': {
+        id: 'acme.tool.run',
+        toolId: 'acme.tool',
+        name: 'run',
+        description: 'Run Acme.',
+        status: 'enabled',
+        inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
+      },
+      'acme.tool.disabled': {
+        id: 'acme.tool.disabled',
+        toolId: 'acme.tool',
+        name: 'disabled',
+        status: 'disabled',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      'api.weather.lookup': {
+        id: 'api.weather.lookup',
+        toolId: 'api.weather',
+        name: 'lookup',
+        description: 'Look up weather.',
+        status: 'enabled',
+        inputSchema: {
+          type: 'object',
+          enum: ['unsupported-top-level-key'],
+          oneOf: [{ required: ['city'] }],
+          properties: { city: { type: 'string' } },
+        },
+      },
+      'remote.mcp.search': {
+        id: 'remote.mcp.search',
+        toolId: 'remote.mcp',
+        name: 'search',
+        status: 'enabled',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      'amalgm.notify_user': {
+        id: 'amalgm.notify_user',
+        toolId: 'amalgm',
+        name: 'notify_user',
+        status: 'enabled',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    },
+  };
+}
+
+function createRepository(toolbox = sampleToolbox()) {
+  return {
+    deleteTool(id, options) {
+      return { ok: true, deleted: true, id, options };
+    },
+    deleteToolAction(id, options) {
+      return { ok: true, deleted: true, id, options };
+    },
+    getTool(id, options = {}) {
+      const tool = toolbox.tools[id];
+      if (!tool) throw new Error(`Unknown tool: ${id}`);
+      const actions = Object.values(toolbox.toolActions).filter((action) => action.toolId === id);
+      return { tool, ...(options.includeActions === false ? {} : { actions }) };
+    },
+    getToolAction(id) {
+      const action = toolbox.toolActions[id];
+      if (!action) throw new Error(`Unknown tool action: ${id}`);
+      return { action };
+    },
+    readToolbox() {
+      return toolbox;
+    },
+    updateTool(input) {
+      return { tool: input, actions: [] };
+    },
+    updateToolAction(input) {
+      return input;
+    },
+    upsertTool(input) {
+      return { tool: input, actions: input.actions || [] };
+    },
+    upsertToolAction(input) {
+      return input;
+    },
+  };
+}
+
+function captureJson() {
+  const calls = [];
+  return {
+    calls,
+    sendJson(status, payload) {
+      calls.push({ status, payload });
+    },
+  };
+}
+
+test('toolbox service lists compact registry views', () => {
+  const service = createToolboxService(createRepository());
+  const payload = service.listTools({ type: 'cli', include_actions: true });
+
+  assert.deepEqual(payload.tools.map((tool) => tool.id), ['acme.tool']);
+  assert.equal(payload.tools[0].actionCount, 2);
+  assert.equal(payload.tools[0].actions[0].ref, 'acme.tool.run');
+  assert.equal(payload.tools[0].actions[0].mcpToolName, toolboxMcpToolName({ id: 'acme.tool.run' }));
+  assert.equal(payload.toolActions['api.weather.lookup'].name, 'lookup');
+});
+
+test('toolbox service overlays first-party system catalog entries', () => {
+  const service = createToolboxService(createRepository());
+  const catalog = service.readCatalog();
+  const browser = service.getTool('amalgm.browser', { includeActions: false });
+  const navigate = service.getAction('amalgm.browser.browser_navigate');
+
+  assert.equal(catalog.tools.amalgm, undefined);
+  assert.equal(catalog.toolActions['amalgm.notify_user'], undefined);
+  assert.equal(catalog.tools['amalgm.browser'].origin, 'system');
+  assert.equal(browser.tool.name, 'Amalgm Browser');
+  assert.equal(browser.actions, undefined);
+  assert.equal(navigate.action.sourceAction.mcpToolName, 'toolbox__amalgm_browser_browser_navigate');
+  assert.equal(service.listTools({ origin: 'system' }).tools.some((tool) => tool.id === 'amalgm.browser'), true);
+});
+
+test('toolbox service resolves only runnable CLI/API actions', () => {
+  const service = createToolboxService(createRepository());
+
+  assert.deepEqual(
+    service.listRunnableActions().map(({ action }) => action.id),
+    ['acme.tool.run', 'api.weather.lookup'],
+  );
+  assert.equal(service.resolveRunnableAction('api.weather', 'api.weather.lookup')?.action.id, 'api.weather.lookup');
+  assert.equal(service.resolveRunnableAction('remote.mcp', 'search'), null);
+  assert.equal(service.resolveRunnableAction('amalgm', 'notify_user'), null);
+
+  const selected = service.listRunnableActions({
+    sessionMetadata: { tools: { mode: 'selected', selectedToolIds: ['api.weather.lookup'] } },
+  });
+  assert.deepEqual(selected.map(({ action }) => action.id), ['api.weather.lookup']);
+});
+
+test('toolbox service derives only external MCP ids from selected tools', () => {
+  const service = createToolboxService(createRepository());
+
+  assert.deepEqual(service.externalMcpToolIdsForMode('all'), ['remote.mcp']);
+  assert.deepEqual(
+    service.externalMcpToolIdsForSelection([
+      'remote.mcp',
+      'amalgm.browser',
+      'api.weather',
+      'missing.tool',
+    ]),
+    ['remote.mcp'],
+  );
+});
+
+test('toolbox service exposes portable MCP descriptors', () => {
+  const service = createToolboxService(createRepository());
+  const descriptors = service.listMcpTools({
+    sessionMetadata: { tools: { mode: 'selected', selectedToolIds: ['api.weather.lookup'] } },
+  });
+
+  assert.equal(descriptors.length, 1);
+  assert.equal(descriptors[0].name, toolboxMcpToolName({ id: 'api.weather.lookup' }));
+  assert.equal(descriptors[0].inputSchema.enum, undefined);
+  assert.equal(descriptors[0].inputSchema.oneOf, undefined);
+  assert.deepEqual(descriptors[0].inputSchema.properties, { city: { type: 'string' } });
+});
+
+test('toolbox REST adapter delegates to service methods', async () => {
+  const service = createToolboxService(createRepository());
+  const rest = createToolboxRest(service);
+  const getTool = captureJson();
+  const updateAction = captureJson();
+  const missingDelete = captureJson();
+
+  await rest.handleGetTool({ id: 'acme.tool', include_actions: 'false' }, getTool.sendJson);
+  await rest.handleUpdateAction({
+    action: { id: 'acme.tool.run', description: 'New description' },
+    clientMutationId: 'mutation-1',
+  }, updateAction.sendJson);
+  await rest.handleDeleteTool({}, missingDelete.sendJson);
+
+  assert.deepEqual(getTool.calls, [{
+    status: 200,
+    payload: { tool: sampleToolbox().tools['acme.tool'] },
+  }]);
+  assert.deepEqual(updateAction.calls, [{
+    status: 200,
+    payload: {
+      ok: true,
+      action: {
+        id: 'acme.tool.run',
+        description: 'New description',
+        clientMutationId: 'mutation-1',
+      },
+    },
+  }]);
+  assert.deepEqual(missingDelete.calls, [{ status: 400, payload: { error: 'id is required' } }]);
+});

package/runtime/scripts/amalgm-mcp/toolbox/mcp-surface.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Toolbox MCP surface.
+ *
+ * This is the adapter-facing view of tools/actions. The MCP server should ask
+ * this module what tools exist and how to call them; it should not assemble
+ * built-ins, toolbox management tools, and user actions itself.
+ */
+
+const { errorResult } = require('../lib/tool-result');
+const { CORE_TOOLS } = require('../server/core-tools');
+const { toolboxMcpToolName } = require('./names');
+const { callToolboxMcpTool } = require('./runner');
+const {
+  selectedContainsToolOrAction,
+  selectedToolIdsForContext,
+} = require('./selection');
+const {
+  defaultToolboxService: toolboxService,
+} = require('./service');
+
+const DEFAULT_STATIC_MCP_TOOLS = [
+  ...CORE_TOOLS,
+  ...require('./tools'),
+];
+
+function toolDescriptor(tool) {
+  return {
+    name: mcpNameForStaticTool(tool),
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  };
+}
+
+function mcpNameForStaticTool(tool) {
+  return tool.toolboxActionId
+    ? toolboxMcpToolName({ id: tool.toolboxActionId })
+    : tool.name;
+}
+
+function defaultListDynamicTools(context) {
+  return toolboxService.listMcpTools(context);
+}
+
+function isStaticToolSelected(tool, selectedToolIds) {
+  return selectedContainsToolOrAction(
+    selectedToolIds,
+    tool.toolboxToolId,
+    tool.toolboxActionId,
+  );
+}
+
+function createToolboxMcpSurface(options = {}) {
+  const staticTools = Array.isArray(options.staticTools)
+    ? options.staticTools
+    : DEFAULT_STATIC_MCP_TOOLS;
+  const listDynamicTools = options.listDynamicTools || defaultListDynamicTools;
+  const callDynamicTool = options.callDynamicTool || callToolboxMcpTool;
+
+  function staticToolsForContext(context) {
+    const selectedToolIds = selectedToolIdsForContext(context);
+    return staticTools.filter((tool) => isStaticToolSelected(tool, selectedToolIds));
+  }
+
+  function findStaticTool(toolName, context) {
+    return staticToolsForContext(context)
+      .find((tool) => mcpNameForStaticTool(tool) === toolName) || null;
+  }
+
+  async function listTools(context) {
+    const dynamicTools = await listDynamicTools(context);
+    return [
+      ...staticToolsForContext(context).map(toolDescriptor),
+      ...(Array.isArray(dynamicTools) ? dynamicTools : []),
+    ];
+  }
+
+  async function callTool(toolName, toolArgs = {}, context) {
+    const staticTool = findStaticTool(toolName, context);
+    if (staticTool) {
+      try {
+        return await staticTool.handler(toolArgs, context);
+      } catch (error) {
+        return errorResult(`Error: ${error?.message || String(error)}`);
+      }
+    }
+
+    const dynamicResult = await callDynamicTool(toolName, toolArgs, context);
+    if (dynamicResult) return dynamicResult;
+    return errorResult(`Unknown tool: ${toolName}`);
+  }
+
+  return {
+    callTool,
+    findStaticTool,
+    listTools,
+  };
+}
+
+module.exports = {
+  DEFAULT_STATIC_MCP_TOOLS,
+  createToolboxMcpSurface,
+  mcpNameForStaticTool,
+  toolDescriptor,
+};

package/runtime/scripts/amalgm-mcp/toolbox/names.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const TOOLBOX_TOOL_PREFIX = 'toolbox__';
+const MODEL_UNSUPPORTED_TOP_LEVEL_SCHEMA_KEYS = ['anyOf', 'oneOf', 'allOf', 'not', 'enum'];
+
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function safeMcpName(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[^A-Za-z0-9_.-]+/g, '_')
+    .replace(/[.-]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    || 'tool';
+}
+
+function toolboxMcpToolName(action) {
+  return `${TOOLBOX_TOOL_PREFIX}${safeMcpName(action.id)}`;
+}
+
+function portableInputSchema(inputSchema) {
+  if (!isObject(inputSchema) || inputSchema.type !== 'object') {
+    return { type: 'object', properties: {}, additionalProperties: true };
+  }
+  const schema = { ...inputSchema };
+  for (const key of MODEL_UNSUPPORTED_TOP_LEVEL_SCHEMA_KEYS) {
+    delete schema[key];
+  }
+  if (!isObject(schema.properties)) schema.properties = {};
+  return schema;
+}
+
+module.exports = {
+  TOOLBOX_TOOL_PREFIX,
+  portableInputSchema,
+  safeMcpName,
+  toolboxMcpToolName,
+};

package/runtime/scripts/amalgm-mcp/toolbox/rest.js

@@ -7,69 +7,123 @@
  */
 
 const {
-  deleteTool,
-  deleteToolAction,
-  readToolbox,
-  upsertTool,
-  upsertToolAction,
-} = require('./store');
+  defaultToolboxService,
+} = require('./service');
 
-async function handleList(sendJson) {
-  sendJson(200, readToolbox());
-}
+function createToolboxRest(toolboxService = defaultToolboxService) {
+  async function handleList(sendJson) {
+    sendJson(200, toolboxService.readCatalog());
+  }
 
-async function handleUpsertTool(body, sendJson) {
-  try {
-    const rawTool = body?.tool && typeof body.tool === 'object' ? body.tool : body;
-    const tool = {
-      ...rawTool,
-      actions: body?.actions ?? rawTool?.actions,
-      clientMutationId: body?.clientMutationId ?? rawTool?.clientMutationId,
-    };
-    const saved = upsertTool(tool);
-    sendJson(200, { ok: true, ...saved });
-  } catch (error) {
-    sendJson(400, { error: error instanceof Error ? error.message : 'Failed to save tool' });
+  async function handleGetTool(query, sendJson) {
+    try {
+      const id = query?.id || query?.toolId;
+      const includeActions = query?.include_actions !== 'false' && query?.includeActions !== 'false';
+      sendJson(200, toolboxService.getTool(id, { includeActions }));
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to read tool' });
+    }
   }
-}
 
-async function handleDeleteTool(body, sendJson) {
-  try {
-    const id = body?.id || body?.toolId;
-    if (!id) return sendJson(400, { error: 'id is required' });
-    sendJson(200, deleteTool(id, { clientMutationId: body?.clientMutationId }));
-  } catch (error) {
-    sendJson(400, { error: error instanceof Error ? error.message : 'Failed to delete tool' });
+  async function handleUpsertTool(body, sendJson) {
+    try {
+      const rawTool = body?.tool && typeof body.tool === 'object' ? body.tool : body;
+      const tool = {
+        ...rawTool,
+        actions: body?.actions ?? rawTool?.actions,
+        clientMutationId: body?.clientMutationId ?? rawTool?.clientMutationId,
+      };
+      const saved = toolboxService.registerTool(tool);
+      sendJson(200, { ok: true, ...saved });
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to save tool' });
+    }
   }
-}
 
-async function handleUpsertAction(body, sendJson) {
-  try {
-    const rawAction = body?.action && typeof body.action === 'object' ? body.action : body;
-    const action = upsertToolAction({
-      ...rawAction,
-      clientMutationId: body?.clientMutationId ?? rawAction?.clientMutationId,
-    });
-    sendJson(200, { ok: true, action });
-  } catch (error) {
-    sendJson(400, { error: error instanceof Error ? error.message : 'Failed to save tool action' });
+  async function handleUpdateTool(body, sendJson) {
+    try {
+      const rawTool = body?.tool && typeof body.tool === 'object' ? body.tool : body;
+      const saved = toolboxService.updateTool({
+        ...rawTool,
+        clientMutationId: body?.clientMutationId ?? rawTool?.clientMutationId,
+      });
+      sendJson(200, { ok: true, ...saved });
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to update tool' });
+    }
+  }
+
+  async function handleDeleteTool(body, sendJson) {
+    try {
+      const id = body?.id || body?.toolId;
+      if (!id) return sendJson(400, { error: 'id is required' });
+      sendJson(200, toolboxService.deleteTool(id, { clientMutationId: body?.clientMutationId }));
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to delete tool' });
+    }
   }
-}
 
-async function handleDeleteAction(body, sendJson) {
-  try {
-    const id = body?.id || body?.actionId;
-    if (!id) return sendJson(400, { error: 'id is required' });
-    sendJson(200, deleteToolAction(id, { clientMutationId: body?.clientMutationId }));
-  } catch (error) {
-    sendJson(400, { error: error instanceof Error ? error.message : 'Failed to delete tool action' });
+  async function handleGetAction(query, sendJson) {
+    try {
+      const id = query?.id || query?.actionId;
+      sendJson(200, toolboxService.getAction(id));
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to read tool action' });
+    }
   }
+
+  async function handleUpsertAction(body, sendJson) {
+    try {
+      const rawAction = body?.action && typeof body.action === 'object' ? body.action : body;
+      const action = toolboxService.registerAction({
+        ...rawAction,
+        clientMutationId: body?.clientMutationId ?? rawAction?.clientMutationId,
+      });
+      sendJson(200, { ok: true, action });
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to save tool action' });
+    }
+  }
+
+  async function handleUpdateAction(body, sendJson) {
+    try {
+      const rawAction = body?.action && typeof body.action === 'object' ? body.action : body;
+      const action = toolboxService.updateAction({
+        ...rawAction,
+        clientMutationId: body?.clientMutationId ?? rawAction?.clientMutationId,
+      });
+      sendJson(200, { ok: true, action });
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to update tool action' });
+    }
+  }
+
+  async function handleDeleteAction(body, sendJson) {
+    try {
+      const id = body?.id || body?.actionId;
+      if (!id) return sendJson(400, { error: 'id is required' });
+      sendJson(200, toolboxService.deleteAction(id, { clientMutationId: body?.clientMutationId }));
+    } catch (error) {
+      sendJson(400, { error: error instanceof Error ? error.message : 'Failed to delete tool action' });
+    }
+  }
+
+  return {
+    handleDeleteAction,
+    handleDeleteTool,
+    handleGetAction,
+    handleGetTool,
+    handleList,
+    handleUpdateAction,
+    handleUpdateTool,
+    handleUpsertAction,
+    handleUpsertTool,
+  };
 }
 
+const defaultRest = createToolboxRest();
+
 module.exports = {
-  handleDeleteAction,
-  handleDeleteTool,
-  handleList,
-  handleUpsertAction,
-  handleUpsertTool,
+  createToolboxRest,
+  ...defaultRest,
 };