amalgm 0.1.257 → 0.1.259

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

@@ -35,7 +35,7 @@ test('system toolbox catalog exposes first-party default tools', () => {
   );
 });
 
-test('system toolbox catalog merge preserves persisted records', () => {
+test('system toolbox catalog merge preserves user records but keeps built-ins authoritative', () => {
   const merged = mergeSystemToolboxCatalog({
     version: 1,
     tools: {
@@ -59,12 +59,9 @@ test('system toolbox catalog merge preserves persisted records', () => {
     },
   });
 
-  assert.equal(merged.tools.browser.name, 'Persisted Browser');
+  assert.equal(merged.tools.browser.name, 'Browser');
   assert.equal(merged.tools['custom.cli'].name, 'Custom CLI');
-  assert.equal(
-    merged.toolActions['browser.browser_open'].name,
-    'persisted_navigate',
-  );
+  assert.equal(merged.toolActions['browser.browser_open'], undefined);
   assert.equal(merged.toolActions['apps.apps_list'].name, 'apps_list');
 });
 

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

@@ -0,0 +1,88 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+
+const {
+  SYSTEM_TOOL_ARTIFACTS,
+  artifactPathForTool,
+  isSystemToolId,
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+  readToolArtifacts,
+  writeToolArtifact,
+} = require('../toolbox/artifacts');
+
+function temporaryToolbox() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-toolbox-artifacts-'));
+  const toolboxDir = path.join(home, 'toolbox');
+  fs.mkdirSync(toolboxDir);
+  return { home, toolboxDir };
+}
+
+test('each built-in tool materializes as one distinct managed artifact', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    const first = materializeSystemToolArtifacts({ toolboxDir });
+    assert.deepEqual(first.changedRelativePaths, SYSTEM_TOOL_ARTIFACTS.map((entry) => entry.relativePath));
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.deepEqual(Object.keys(catalog.tools).sort(), SYSTEM_TOOL_ARTIFACTS.map((entry) => entry.toolId).sort());
+    for (const entry of SYSTEM_TOOL_ARTIFACTS) {
+      const tool = catalog.tools[entry.toolId];
+      assert.equal(tool.origin, 'system');
+      assert.equal(tool.owner, 'amalgm');
+      assert.deepEqual(tool.source, { transport: 'amalgm-runtime', service: 'mcp' },
+        'the cloud artifact has no machine-local port');
+      assert.equal(path.basename(artifactPathForTool(tool, { toolboxDir })), path.basename(entry.relativePath));
+      assert.equal(isSystemToolId(tool.id), true);
+    }
+    assert.deepEqual(materializeSystemToolArtifacts({ toolboxDir }).changedRelativePaths, [],
+      'rerunning login does not rewrite an unchanged built-in tool');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a user tool is a sibling artifact and remains independent of built-in ownership', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    materializeSystemToolArtifacts({ toolboxDir });
+    const tool = { id: 'aayush.stock-price', name: 'Stock Price', origin: 'user', owner: 'aayush' };
+    const actions = [{ id: 'aayush.stock-price.lookup', toolId: tool.id, name: 'lookup' }];
+    const target = writeToolArtifact({ tool, actions }, { toolboxDir });
+    assert.equal(path.basename(target), 'tool-aayush.stock-price.json');
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.equal(catalog.tools[tool.id].origin, 'user');
+    assert.equal(catalog.toolActions[actions[0].id].toolId, tool.id);
+    assert.equal(isSystemToolId(tool.id), false);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a legacy aggregate catalog becomes user tool artifacts before leaving the registered toolbox tree', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    fs.writeFileSync(path.join(toolboxDir, 'toolbox.json'), JSON.stringify({
+      version: 1,
+      tools: {
+        'user.example': { id: 'user.example', name: 'Example', origin: 'user', owner: 'user' },
+      },
+      toolActions: {
+        'user.example.run': { id: 'user.example.run', toolId: 'user.example', name: 'run' },
+      },
+    }));
+    const migrated = migrateLegacyToolboxCatalog({ toolboxDir });
+    assert.equal(migrated.migrated, true);
+    assert.equal(fs.existsSync(path.join(toolboxDir, 'toolbox.json')), false);
+    assert.equal(fs.existsSync(path.join(home, 'toolbox.legacy.json')), true);
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.equal(catalog.tools['user.example'].name, 'Example');
+    assert.equal(catalog.toolActions['user.example.run'].name, 'run');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * The full automatic rail for a user-created tool:
+ *
+ * toolbox API write → one sibling artifact → existing toolbox watcher
+ * → UUID registry → durable entity-cloud outbox.
+ *
+ * This must run in its own test file because AMALGM_DIR is intentionally read
+ * once by the runtime composition root.
+ */
+
+const assert = require('node:assert/strict');
+const Database = require('better-sqlite3');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-toolbox-cloud-'));
+process.env.AMALGM_DIR = home;
+
+const { createRegistrationService } = require('../registration/service');
+const { deleteTool, updateTool, upsertTool } = require('../toolbox/store');
+
+let service = null;
+
+test.after(() => {
+  service?.close();
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+async function waitFor(read, message) {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const value = read();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+  assert.fail(message);
+}
+
+test('a user tool becomes a cloud-backed entity through the existing toolbox watcher', async () => {
+  service = createRegistrationService({
+    dir: path.join(home, 'entities'),
+    homeDir: home,
+    cloudUserId: '11111111-1111-4111-8111-111111111111',
+    cloudDeviceId: 'toolbox-cloud-proof-device',
+  });
+  const userHome = await service.bootstrapUserHome();
+  const bootstrapRecords = await service.exactUserHomeCloudRecords();
+  const bootstrap = service.entityCloud.bootstrap(bootstrapRecords);
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+    bootstrapRecords,
+  });
+
+  assert.throws(() => updateTool({ id: 'browser', name: 'Changed Browser' }),
+    /System tools cannot be modified/);
+  assert.throws(() => deleteTool('browser'), /System tools cannot be deleted/);
+
+  upsertTool({
+    id: 'proof.stock',
+    name: 'Proof Stock',
+    type: 'cli',
+    origin: 'user',
+    owner: 'user',
+    source: { command: 'echo' },
+  });
+
+  const toolbox = userHome.roots.find((entry) => entry.key === 'toolbox').record;
+  const artifact = await waitFor(
+    () => service.registration.registry.activeAt(toolbox.uuid, 'tool-proof.stock.json'),
+    'the watcher did not register the user tool artifact',
+  );
+  assert.ok(fs.existsSync(path.join(home, 'toolbox', 'tool-proof.stock.json')));
+
+  const db = new Database(path.join(home, 'entities', 'identity.db'), { readonly: true });
+  try {
+    const rows = db.prepare('SELECT operation_json FROM entity_cloud_mutations').all();
+    assert.equal(rows.some((row) => JSON.parse(row.operation_json).record?.uuid === artifact.uuid), true,
+      'registration wrote one durable cloud delivery intent for the tool entity');
+  } finally {
+    db.close();
+  }
+});

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

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * Toolbox filesystem artifacts.
+ *
+ * Purpose: one tool must have one cloud-addressable file, so a user-created
+ * tool can travel between machines without ever granting it the authority of
+ * a built-in Amalgm tool.
+ *
+ * Axioms:
+ * - A tool definition and every action belonging to it live in one artifact.
+ * - Built-in artifact paths are the exact managed nodes declared by layout.
+ * - User artifacts are siblings, never children of a managed tool path.
+ * - Portable artifacts never carry a machine-local address or watcher fact.
+ * - The SQLite toolbox tables and toolbox.index.json are local derived caches;
+ *   artifact files are the portable representation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { AMALGM_DIR } = require('../config');
+const { SYSTEM_TOOL_ARTIFACTS } = require('../lib/layout');
+const { ensureDir, readJson, writeJsonAtomic } = require('../lib/storage');
+
+const TOOL_ARTIFACT_SCHEMA_VERSION = 1;
+const TOOLBOX_DIR = path.join(AMALGM_DIR, 'toolbox');
+const TOOLBOX_INDEX_FILE = path.join(AMALGM_DIR, 'toolbox.index.json');
+const LEGACY_TOOLBOX_FILE_NAME = 'toolbox.json';
+
+function safeToolId(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]+/g, '.')
+    .replace(/\.+/g, '.')
+    .replace(/^[._-]+|[._-]+$/g, '');
+}
+
+function systemArtifactForTool(toolId) {
+  return SYSTEM_TOOL_ARTIFACTS.find((entry) => entry.toolId === toolId) || null;
+}
+
+function isSystemToolId(toolId) {
+  return !!systemArtifactForTool(toolId);
+}
+
+function userArtifactFileName(toolId) {
+  const id = safeToolId(toolId);
+  if (!id) throw new Error('tool artifact requires a stable tool id');
+  return `tool-${id}.json`;
+}
+
+function toolboxDirFor(options = {}) {
+  return path.resolve(options.toolboxDir || TOOLBOX_DIR);
+}
+
+function indexFileFor(toolboxDir) {
+  return path.join(path.dirname(toolboxDir), 'toolbox.index.json');
+}
+
+function artifactPathForTool(tool, options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const toolId = safeToolId(tool?.id || tool);
+  const system = systemArtifactForTool(toolId);
+  if (system) return path.join(toolboxDir, path.basename(system.relativePath));
+  return path.join(toolboxDir, userArtifactFileName(toolId));
+}
+
+function artifactDocument({ tool, actions = [] }) {
+  if (!tool || typeof tool !== 'object' || !safeToolId(tool.id)) {
+    throw new Error('tool artifact requires a tool with an id');
+  }
+  const toolId = safeToolId(tool.id);
+  const normalizedActions = Array.isArray(actions)
+    ? actions.filter((action) => action && action.toolId === toolId)
+    : [];
+  const portableTool = isSystemToolId(toolId)
+    ? {
+        ...tool,
+        id: toolId,
+        // `127.0.0.1:<port>` is a device binding, not tool identity. The
+        // system catalog resolves the current runtime endpoint when serving
+        // the local tool surface.
+        source: { transport: 'amalgm-runtime', service: 'mcp' },
+      }
+    : { ...tool, id: toolId };
+  return {
+    schemaVersion: TOOL_ARTIFACT_SCHEMA_VERSION,
+    kind: 'amalgm-tool',
+    tool: portableTool,
+    actions: normalizedActions
+      .map((action) => ({ ...action, toolId }))
+      .sort((left, right) => String(left.id).localeCompare(String(right.id))),
+  };
+}
+
+function validDocument(value) {
+  return !!value
+    && value.schemaVersion === TOOL_ARTIFACT_SCHEMA_VERSION
+    && value.kind === 'amalgm-tool'
+    && value.tool
+    && typeof value.tool === 'object'
+    && !!safeToolId(value.tool.id)
+    && Array.isArray(value.actions)
+    && value.actions.every((action) => action && action.toolId === safeToolId(value.tool.id));
+}
+
+function writeToolArtifact({ tool, actions }, options = {}) {
+  const target = artifactPathForTool(tool, options);
+  ensureDir(path.dirname(target));
+  const document = artifactDocument({ tool, actions });
+  const current = readJson(target, null);
+  if (JSON.stringify(current) !== JSON.stringify(document)) writeJsonAtomic(target, document);
+  return target;
+}
+
+function removeUserToolArtifact(toolId, options = {}) {
+  if (isSystemToolId(safeToolId(toolId))) {
+    throw new Error('System tool artifacts cannot be removed');
+  }
+  const target = artifactPathForTool(toolId, options);
+  try { fs.unlinkSync(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return target;
+}
+
+function readToolArtifacts(options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const tools = {};
+  const toolActions = {};
+  let entries = [];
+  try { entries = fs.readdirSync(toolboxDir, { withFileTypes: true }); } catch { return { tools, toolActions }; }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name === LEGACY_TOOLBOX_FILE_NAME) continue;
+    const document = readJson(path.join(toolboxDir, entry.name), null);
+    if (!validDocument(document)) continue;
+    const toolId = safeToolId(document.tool.id);
+    const expected = artifactPathForTool(toolId, { toolboxDir });
+    if (path.resolve(expected) !== path.resolve(path.join(toolboxDir, entry.name))) continue;
+    tools[toolId] = { ...document.tool, id: toolId };
+    for (const action of document.actions) toolActions[action.id] = { ...action, toolId };
+  }
+  return { tools, toolActions };
+}
+
+function writeToolboxIndex(toolbox, options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const target = options.indexFile || indexFileFor(toolboxDir);
+  const document = {
+    version: 1,
+    tools: toolbox?.tools || {},
+    toolActions: toolbox?.toolActions || {},
+  };
+  const current = readJson(target, null);
+  if (JSON.stringify(current) !== JSON.stringify(document)) writeJsonAtomic(target, document);
+  return target;
+}
+
+function materializeSystemToolArtifacts(options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const { buildSystemToolboxCatalog } = require('./system-catalog');
+  const catalog = buildSystemToolboxCatalog();
+  const changedRelativePaths = [];
+  for (const system of SYSTEM_TOOL_ARTIFACTS) {
+    const tool = catalog.tools[system.toolId];
+    if (!tool) throw new Error(`built-in toolbox definition missing for ${system.toolId}`);
+    const target = artifactPathForTool(tool, { toolboxDir });
+    const document = artifactDocument({
+      tool,
+      actions: Object.values(catalog.toolActions).filter((action) => action.toolId === tool.id),
+    });
+    if (JSON.stringify(readJson(target, null)) !== JSON.stringify(document)) {
+      ensureDir(path.dirname(target));
+      writeJsonAtomic(target, document);
+      changedRelativePaths.push(system.relativePath);
+    }
+  }
+  return { catalog, changedRelativePaths };
+}
+
+/** Move the old aggregate catalog out of the registered toolbox tree only
+ * after all its user records have a per-tool replacement. The new index is a
+ * local cache next to, not inside, the cloud-backed toolbox folder. */
+function migrateLegacyToolboxCatalog(options = {}) {
+  const toolboxDir = toolboxDirFor(options);
+  const legacy = path.join(toolboxDir, LEGACY_TOOLBOX_FILE_NAME);
+  if (!fs.existsSync(legacy)) return { migrated: false, artifactPaths: [] };
+  const parsed = readJson(legacy, null);
+  if (!parsed || typeof parsed !== 'object' || !parsed.tools || typeof parsed.tools !== 'object') {
+    return { migrated: false, artifactPaths: [] };
+  }
+  const artifactPaths = [];
+  for (const [rawId, rawTool] of Object.entries(parsed.tools)) {
+    const toolId = safeToolId(rawTool?.id || rawId);
+    if (!toolId || isSystemToolId(toolId) || !rawTool || typeof rawTool !== 'object') continue;
+    const actions = Object.values(parsed.toolActions || {})
+      .filter((action) => action && action.toolId === toolId);
+    artifactPaths.push(writeToolArtifact({ tool: { ...rawTool, id: toolId }, actions }, { toolboxDir }));
+  }
+  writeToolboxIndex({ tools: parsed.tools || {}, toolActions: parsed.toolActions || {} }, { toolboxDir });
+  let migrated = path.join(path.dirname(toolboxDir), 'toolbox.legacy.json');
+  if (fs.existsSync(migrated)) migrated = path.join(path.dirname(toolboxDir), `toolbox.legacy-${Date.now()}.json`);
+  fs.renameSync(legacy, migrated);
+  return { migrated: true, artifactPaths };
+}
+
+module.exports = {
+  LEGACY_TOOLBOX_FILE_NAME,
+  SYSTEM_TOOL_ARTIFACTS,
+  TOOL_ARTIFACT_SCHEMA_VERSION,
+  TOOLBOX_DIR,
+  TOOLBOX_INDEX_FILE,
+  artifactDocument,
+  artifactPathForTool,
+  indexFileFor,
+  isSystemToolId,
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+  readToolArtifacts,
+  removeUserToolArtifact,
+  safeToolId,
+  userArtifactFileName,
+  writeToolArtifact,
+  writeToolboxIndex,
+};

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,
 };