amalgm 0.1.257 → 0.1.258

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

@@ -12,14 +12,25 @@
  */
 
 const path = require('path');
-const { AMALGM_DIR } = require('../config');
-const { ensureDir, readJson, writeJsonAtomic } = require('../lib/storage');
+const { readJson } = require('../lib/storage');
 const { openLocalDb } = require('../state/db');
 const { insertStateEvent, publishStateEvent } = require('../state/events');
+const {
+  TOOLBOX_DIR,
+  TOOLBOX_INDEX_FILE,
+  isSystemToolId,
+  readToolArtifacts,
+  removeUserToolArtifact,
+  writeToolArtifact,
+  writeToolboxIndex,
+} = require('./artifacts');
 
 const TOOLBOX_VERSION = 1;
-const TOOLBOX_DIR = path.join(AMALGM_DIR, 'toolbox');
-const TOOLBOX_FILE = path.join(TOOLBOX_DIR, 'toolbox.json');
+// `toolbox.index.json` is a local cache, deliberately outside the registered
+// toolbox folder. Individual `toolbox/*.json` artifacts are the portable
+// source of truth; `toolbox/toolbox.json` remains only a legacy import path.
+const TOOLBOX_FILE = TOOLBOX_INDEX_FILE;
+const LEGACY_TOOLBOX_FILE = path.join(TOOLBOX_DIR, 'toolbox.json');
 
 const TOOL_TYPES = new Set(['mcp', 'api', 'cli']);
 const TOOL_ORIGINS = new Set(['system', 'user', 'catalog']);
@@ -528,19 +539,32 @@ function writeToolboxToDb(toolbox, options = {}) {
 }
 
 function exportToolboxJson(toolbox) {
-  ensureDir(TOOLBOX_DIR);
-  writeJsonAtomic(TOOLBOX_FILE, normalizeToolbox(toolbox));
+  writeToolboxIndex(normalizeToolbox(toolbox), { toolboxDir: TOOLBOX_DIR });
 }
 
 function migrateLegacyToolboxFileIfNeeded() {
   const db = openLocalDb();
   if (toolboxRowCount(db) > 0) return;
 
-  const legacyToolbox = dropInheritedHarnessTools(normalizeToolbox(readJson(TOOLBOX_FILE, emptyToolbox())));
+  const legacyToolbox = dropInheritedHarnessTools(normalizeToolbox(readJson(LEGACY_TOOLBOX_FILE, emptyToolbox())));
   if (Object.keys(legacyToolbox.tools).length === 0 && Object.keys(legacyToolbox.toolActions).length === 0) return;
   writeToolboxToDb(legacyToolbox, { replace: true });
 }
 
+function writeUserToolArtifacts(toolbox) {
+  for (const tool of Object.values(toolbox.tools || {})) {
+    if (!tool || isSystemToolId(tool.id) || tool.origin === 'system') continue;
+    writeToolArtifact({ tool, actions: toolActionsForTool(toolbox, tool.id) }, { toolboxDir: TOOLBOX_DIR });
+  }
+}
+
+function cacheToolboxFromArtifacts(toolbox) {
+  const normalized = normalizeToolbox(toolbox);
+  writeToolboxToDb(normalized, { replace: true });
+  exportToolboxJson(normalized);
+  return normalized;
+}
+
 function publishCommittedEvents(events) {
   for (const event of events) publishStateEvent(event);
 }
@@ -569,14 +593,18 @@ function insertToolActionEvent(db, op, action, options = {}) {
 
 function readToolbox() {
   migrateLegacyToolboxFileIfNeeded();
-  const toolbox = readToolboxFromDb();
-  const removedLegacyAggregate = dropLegacyAggregateAmalgmTool(toolbox);
-  if (removedLegacyAggregate) writeToolbox(toolbox);
+  // An existing device may still have user records only in its local cache.
+  // Give each one a portable artifact before treating artifacts as canonical.
+  const cached = readToolboxFromDb();
+  dropLegacyAggregateAmalgmTool(cached);
+  writeUserToolArtifacts(cached);
+  const toolbox = cacheToolboxFromArtifacts(readToolArtifacts({ toolboxDir: TOOLBOX_DIR }));
   return toolbox;
 }
 
 function writeToolbox(toolbox) {
   const normalized = writeToolboxToDb(toolbox, { replace: true });
+  writeUserToolArtifacts(normalized);
   exportToolboxJson(normalized);
   return normalized;
 }
@@ -614,6 +642,9 @@ function upsertTool(input) {
   const existing = input?.id ? toolbox.tools[sanitizeId(input.id)] : null;
   const existingActionIds = new Set(Object.keys(toolbox.toolActions));
   const tool = normalizeTool(input, existing);
+  if (isSystemToolId(tool.id) || tool.origin === 'system') {
+    throw new Error('System tools are managed by Amalgm and cannot be created or replaced here');
+  }
   toolbox.tools[tool.id] = tool;
 
   const actions = [];
@@ -659,6 +690,8 @@ function upsertTool(input) {
     }
     return inserted;
   })();
+  writeToolArtifact({ tool, actions: toolActionsForTool(toolbox, tool.id) }, { toolboxDir: TOOLBOX_DIR });
+  exportToolboxJson(toolbox);
   publishCommittedEvents(events);
   return { tool, actions };
 }
@@ -735,6 +768,8 @@ function updateTool(input) {
       source: 'toolbox:update-tool',
     })];
   })();
+  writeToolArtifact({ tool, actions: toolActionsForTool(toolbox, tool.id) }, { toolboxDir: TOOLBOX_DIR });
+  exportToolboxJson(toolbox);
   publishCommittedEvents(events);
   return { tool, actions: toolActionsForTool(toolbox, tool.id) };
 }
@@ -744,6 +779,7 @@ function upsertToolAction(input) {
   const toolId = sanitizeId(input?.toolId || input?.providerId || input?.tool);
   const tool = toolbox.tools[toolId];
   if (!tool) throw new Error(`Unknown tool: ${toolId}`);
+  if (tool.origin === 'system' || isSystemToolId(tool.id)) throw new Error('System tool actions cannot be modified');
   const existing = input?.id ? toolbox.toolActions[sanitizeId(input.id)] : null;
   const action = normalizeAction(input, tool, existing);
   toolbox.toolActions[action.id] = action;
@@ -755,6 +791,8 @@ function upsertToolAction(input) {
       source: 'toolbox:upsert-action',
     })];
   })();
+  writeToolArtifact({ tool, actions: toolActionsForTool(toolbox, tool.id) }, { toolboxDir: TOOLBOX_DIR });
+  exportToolboxJson(toolbox);
   publishCommittedEvents(events);
   return action;
 }
@@ -805,6 +843,8 @@ function updateToolAction(input) {
       source: 'toolbox:update-action',
     })];
   })();
+  writeToolArtifact({ tool, actions: toolActionsForTool(toolbox, tool.id) }, { toolboxDir: TOOLBOX_DIR });
+  exportToolboxJson(toolbox);
   publishCommittedEvents(events);
   return action;
 }
@@ -830,6 +870,12 @@ function deleteTool(id, options = {}) {
     }));
     return inserted;
   })();
+  removeUserToolArtifact(toolId, { toolboxDir: TOOLBOX_DIR });
+  exportToolboxJson({
+    ...toolbox,
+    tools: Object.fromEntries(Object.entries(toolbox.tools).filter(([id]) => id !== toolId)),
+    toolActions: Object.fromEntries(Object.entries(toolbox.toolActions).filter(([, action]) => action.toolId !== toolId)),
+  });
   publishCommittedEvents(events);
   scrubToolFromApps(toolId);
   return { ok: true, deleted: true };
@@ -867,6 +913,9 @@ function deleteToolAction(id, options = {}) {
       source: 'toolbox:delete-action',
     })];
   })();
+  delete toolbox.toolActions[actionId];
+  writeToolArtifact({ tool, actions: toolActionsForTool(toolbox, tool.id) }, { toolboxDir: TOOLBOX_DIR });
+  exportToolboxJson(toolbox);
   publishCommittedEvents(events);
   return { ok: true, deleted: true };
 }

package/runtime/scripts/amalgm-mcp/toolbox/system-catalog.js

@@ -3,9 +3,10 @@
 /**
  * Virtual first-party Toolbox catalog entries.
  *
- * These records make Amalgm's default capabilities look like normal Toolbox
- * tools/actions to UI and control-plane consumers without changing the legacy
- * MCP tool names or writing additional system rows to local storage.
+ * These records are the canonical definitions materialized as one exact
+ * `toolbox/amalgm-*.json` artifact per built-in tool. The overlay keeps the
+ * legacy MCP surface stable and refuses a stale local cache from overriding a
+ * product-managed definition.
  */
 
 const { PORT } = require('../config');
@@ -29,6 +30,10 @@ function coreToolGroups() {
   return require('../server/core-tools').CORE_TOOL_GROUPS || [];
 }
 
+function systemToolIds() {
+  return new Set(coreToolGroups().map((group) => group.id));
+}
+
 function systemToolForGroup(group) {
   return {
     id: group.id,
@@ -95,12 +100,15 @@ function buildSystemToolboxCatalog() {
 function persistedCatalogWithoutLegacyAggregate(toolbox) {
   const tools = { ...(toolbox?.tools || {}) };
   const toolActions = { ...(toolbox?.toolActions || {}) };
+  const systemIds = systemToolIds();
   delete tools.amalgm;
+  for (const systemId of systemIds) delete tools[systemId];
   for (const toolId of LEGACY_FIRST_PARTY_TOOL_IDS) delete tools[toolId];
   for (const [actionId, action] of Object.entries(toolActions)) {
     const legacyGroupId = actionId.split('.').slice(0, 2).join('.');
     if (
       action?.toolId === 'amalgm'
+      || systemIds.has(action?.toolId)
       || LEGACY_FIRST_PARTY_TOOL_IDS.has(action?.toolId)
       || LEGACY_FIRST_PARTY_TOOL_IDS.has(legacyGroupId)
     ) {
@@ -116,18 +124,19 @@ function mergeSystemToolboxCatalog(toolbox) {
   return {
     ...toolbox,
     tools: {
-      ...catalog.tools,
       ...persisted.tools,
+      ...catalog.tools,
     },
     toolActions: {
-      ...catalog.toolActions,
       ...persisted.toolActions,
+      ...catalog.toolActions,
     },
   };
 }
 
 module.exports = {
   buildSystemToolboxCatalog,
+  systemToolIds,
   mergeSystemToolboxCatalog,
   persistedCatalogWithoutLegacyAggregate,
 };