amalgm 0.1.149 → 0.1.150

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

@@ -6,6 +6,12 @@ const {
   replayGapAfter,
   subscribeStateEvents,
 } = require('./events');
+const appResources = require('./app-resources');
+
+function sendHandlerError(error, sendJson) {
+  const statusCode = Number(error?.statusCode) || 500;
+  sendJson(statusCode, { error: error?.message || 'internal error' });
+}
 
 function parsePositiveInt(value, fallback) {
   const parsed = Number(value);
@@ -29,9 +35,70 @@ function sendSseControl(res, type, payload) {
 }
 
 async function handleSnapshot(query, sendJson) {
+  // Restores persisted app registrations so their resources are readable
+  // even before the owning app has spoken this boot.
+  appResources.ensureAppResourcesLoaded();
   sendJson(200, buildSnapshot(query.resources));
 }
 
+async function handleResourceRegister(body, sendJson) {
+  try {
+    sendJson(200, appResources.registerAppResource(body?.resource));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleResourceUnregister(body, sendJson) {
+  try {
+    sendJson(200, appResources.unregisterAppResource(String(body?.resource || '')));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleResourceEmit(body, sendJson) {
+  try {
+    const events = body?.events ?? body?.event;
+    if (events == null) {
+      sendJson(400, { error: 'body requires "events" (array) or "event" (single object)' });
+      return;
+    }
+    sendJson(200, appResources.emitAppResourceEvents(body?.resource, events, { source: body?.source }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleDocOpen(body, sendJson) {
+  try {
+    sendJson(200, require('./docs').openDoc(body?.path));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleDocUpdate(body, sendJson) {
+  try {
+    const updates = body?.updates ?? body?.update;
+    if (updates == null) {
+      sendJson(400, { error: 'body requires "updates" (array of base64 Yjs updates) or "update"' });
+      return;
+    }
+    sendJson(200, require('./docs').applyDocUpdates(body?.path, updates));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleResourceList(sendJson) {
+  try {
+    sendJson(200, { resources: appResources.listAppResources() });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
 async function handleEvents(query, sendJson) {
   const after = parsePositiveInt(query.after, 0);
   const limit = parsePositiveInt(query.limit, 1000);
@@ -48,6 +115,7 @@ async function handleEvents(query, sendJson) {
 }
 
 function handleStream(req, res, query) {
+  appResources.ensureAppResourcesLoaded();
   const after = parsePositiveInt(query.after, 0);
 
   res.writeHead(200, {
@@ -98,7 +166,13 @@ function handleStream(req, res, query) {
 }
 
 module.exports = {
+  handleDocOpen,
+  handleDocUpdate,
   handleEvents,
+  handleResourceEmit,
+  handleResourceList,
+  handleResourceRegister,
+  handleResourceUnregister,
   handleSnapshot,
   handleStream,
 };

package/runtime/scripts/amalgm-mcp/state/snapshot.js

@@ -1,96 +1,16 @@
 'use strict';
 
 const { currentSeq } = require('./events');
+const registry = require('./registry');
 
-const DEFAULT_RESOURCES = ['automations', 'triggers', 'workflows', 'automation_runs', 'workflow_cell_runs', 'agents', 'agent_configs', 'skills', 'apps', 'ports', 'toolbox', 'tools', 'tool_actions', 'hooks', 'projects', 'workspaces', 'project_context', 'user_preferences', 'chat_payloads', 'mcp_connections', 'browser_profiles', 'browser_auth_bundles', 'browser_login_sessions'];
+require('./resources').registerBuiltinResources();
 
 function normalizeResources(resources) {
-  const values = resources ? String(resources).split(',') : DEFAULT_RESOURCES;
+  const values = resources
+    ? String(resources).split(',')
+    : registry.listDefaultResources();
   const clean = values.map((value) => String(value || '').trim()).filter(Boolean);
-  return clean.length > 0 ? Array.from(new Set(clean)) : DEFAULT_RESOURCES;
-}
-
-function automationGraph(cache) {
-  cache.automationGraph ||= require('../automations/store').listPublicAutomationGraph();
-  return cache.automationGraph;
-}
-
-function readResource(resource, cache) {
-  switch (resource) {
-    case 'automations':
-      return automationGraph(cache).automations;
-    case 'triggers':
-      return automationGraph(cache).triggers;
-    case 'automation_runs':
-      return require('../automations/store').listAutomationRuns({ limit: 300 });
-    case 'workflow_cell_runs':
-      return require('../automations/store').listWorkflowCellRuns({ limit: 300 });
-    case 'tasks':
-      return require('../tasks/store').loadTasks().tasks;
-    case 'task_runs':
-      return require('../tasks/store').listTaskRuns({ limit: 100 });
-    case 'event_runs':
-      return require('../events/store').listEventRuns({ limit: 100 });
-    case 'event_triggers':
-      return require('../events/store').loadEventTriggers().triggers;
-    case 'workflows':
-      return automationGraph(cache).workflows;
-    case 'agents': {
-      const { agentWithConfig } = require('../agent-config/store');
-      return require('../agents/store').getAllAgentsWithBuiltins()
-        .map((agent) => agentWithConfig(agent))
-        .filter(Boolean);
-    }
-    case 'agent_configs':
-      return require('../agent-config/store').listAgentConfigs();
-    case 'skills':
-      return require('../skills/store').listSkills();
-    case 'apps':
-      return require('../apps/store').loadApps().apps;
-    case 'ports':
-      return require('./ports').getCurrentPorts();
-    case 'toolbox':
-      cache.toolbox ||= require('../toolbox/service').defaultToolboxService.readCatalog();
-      return cache.toolbox;
-    case 'tools':
-      cache.toolbox ||= require('../toolbox/service').defaultToolboxService.readCatalog();
-      return cache.toolbox.tools;
-    case 'tool_actions':
-      cache.toolbox ||= require('../toolbox/service').defaultToolboxService.readCatalog();
-      return cache.toolbox.toolActions;
-    case 'hooks':
-      return require('../agents/hooks').collectNativeHooks();
-    case 'projects':
-    case 'workspaces': {
-      const workspaceStore = require('../workspace/store');
-      return workspaceStore.listWorkspaces();
-    }
-    case 'project_context':
-      return require('../project-context/store').listProjectContexts();
-    case 'user_preferences':
-      return require('../lib/prefs').readUserPreferences();
-    case 'chat_payloads':
-      return require('../lib/chat-payloads').listChatPayloads();
-    case 'uploads':
-      return require('../fs/rest')._private.buildUploadsResource();
-    case 'mcp_connections':
-      return require('../mcp-connections/rest').buildConnectionsSnapshot();
-    case 'browser_profiles':
-      return require('../browser/store').listBrowserProfiles();
-    case 'browser_auth_bundles':
-      return require('../browser/store').listBrowserAuthBundles();
-    case 'browser_login_sessions':
-      return require('../browser/store').listBrowserLoginSessions();
-    case 'browser_surfaces':
-      // Surface-open requests are commands, not state: delivered via the
-      // event stream only, so snapshots always start empty.
-      return [];
-    default:
-      if (String(resource).startsWith('files:')) {
-        return require('../fs/rest')._private.buildFilesResource(resource);
-      }
-      return undefined;
-  }
+  return clean.length > 0 ? Array.from(new Set(clean)) : registry.listDefaultResources();
 }
 
 function buildSnapshot(resourcesInput) {
@@ -99,15 +19,15 @@ function buildSnapshot(resourcesInput) {
 
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const beforeSeq = currentSeq();
-    // The cache is per-attempt on purpose: a retry exists because a write
-    // landed mid-read, so reusing reads across attempts would serve the very
-    // staleness the retry is trying to escape.
-    const cache = {};
+    // The read context is per-attempt on purpose: a retry exists because a
+    // write landed mid-read, so reusing reads across attempts would serve the
+    // very staleness the retry is trying to escape.
+    const ctx = {};
     const data = {};
     for (const resource of resources) {
       let value;
       try {
-        value = readResource(resource, cache);
+        value = registry.readRegisteredResource(resource, ctx);
       } catch (error) {
         console.warn(`[LocalLive] Failed to read snapshot resource "${resource}":`, error?.message || error);
         throw error;
@@ -128,4 +48,11 @@ function buildSnapshot(resourcesInput) {
   return { seq: currentSeq(), stable: true, resources: {} };
 }
 
-module.exports = { DEFAULT_RESOURCES, buildSnapshot, normalizeResources };
+module.exports = {
+  // Kept for existing callers; now derived from the registry.
+  get DEFAULT_RESOURCES() {
+    return registry.listDefaultResources();
+  },
+  buildSnapshot,
+  normalizeResources,
+};

package/runtime/scripts/amalgm-mcp/tests/automations-store-runner.test.js

@@ -361,3 +361,30 @@ test('automations tools list actions and compact run_now output', async () => {
   assert.equal(payload.output, undefined);
   assert.equal(payload.cellSummaries[0].name, 'quote');
 });
+
+test('workflow example published in tool descriptions compiles', () => {
+  const example = automationTools.WORKFLOW_EXAMPLE;
+  assert.equal(typeof example, 'string');
+
+  const validateTool = automationTools.find((tool) => tool.name === 'automations_validate');
+  assert.equal(validateTool.inputSchema.properties.workflowText.description.includes(example), true);
+
+  const ir = compileWorkflowText(example);
+  assert.equal(ir.cells.length, 2);
+  assert.equal(ir.cells[0].name, 'getData');
+  assert.equal(ir.cells[1].name, 'notify');
+});
+
+test('workflow compiler rejects non-array cells with a shape-specific error', () => {
+  assert.throws(
+    () => compileWorkflowText(`export default workflow({
+      trigger: "*.*",
+      cells: { getData: code("getData", () => ({})) },
+    });`),
+    /`cells` must be an array of cell-builder calls.*got object/,
+  );
+  assert.throws(
+    () => compileWorkflowText('export default workflow({ trigger: "*.*" });'),
+    /Workflow needs at least one cell/,
+  );
+});

package/runtime/scripts/amalgm-mcp/tests/state-app-resources.test.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-app-resources-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+
+const { closeLocalDb } = require('../state/db');
+const registry = require('../state/registry');
+const appResources = require('../state/app-resources');
+const { buildSnapshot } = require('../state/snapshot');
+const { listEventsAfter, currentSeq, subscribeStateEvents } = require('../state/events');
+
+test.after(() => {
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('register → emit → snapshot: an app resource rides the same rails', () => {
+  const result = appResources.registerAppResource('app:demo:notes');
+  assert.equal(result.created, true);
+  assert.equal(registry.hasResource('app:demo:notes'), true);
+
+  // Registration is idempotent.
+  assert.equal(appResources.registerAppResource('app:demo:notes').created, false);
+
+  const live = [];
+  const unsubscribe = subscribeStateEvents((event) => live.push(event));
+  const before = currentSeq();
+
+  const emitted = appResources.emitAppResourceEvents('app:demo:notes', [
+    { op: 'insert', id: 'n1', value: { id: 'n1', text: 'buy milk' } },
+    { op: 'insert', id: 'n2', value: { id: 'n2', text: 'call mom' } },
+    { op: 'update', id: 'n1', value: { id: 'n1', text: 'buy oat milk' } },
+  ]);
+  unsubscribe();
+
+  assert.equal(emitted.events.length, 3);
+  assert.equal(emitted.seq, before + 3);
+
+  // Live subscribers saw each event, in order, on the shared sequence.
+  assert.deepEqual(live.map((e) => [e.resource, e.op, e.id]), [
+    ['app:demo:notes', 'insert', 'n1'],
+    ['app:demo:notes', 'insert', 'n2'],
+    ['app:demo:notes', 'update', 'n1'],
+  ]);
+
+  // The mirror is what snapshots serve.
+  const snapshot = buildSnapshot('app:demo:notes');
+  assert.deepEqual(snapshot.resources['app:demo:notes'], [
+    { id: 'n1', text: 'buy oat milk' },
+    { id: 'n2', text: 'call mom' },
+  ]);
+
+  // Events landed in the log for reconnect replay.
+  const replay = listEventsAfter(before);
+  assert.equal(replay.length, 3);
+  assert.equal(replay[0].source, 'app:demo:notes');
+});
+
+test('delete and replace maintain the mirror', () => {
+  appResources.emitAppResourceEvents('app:demo:notes', { op: 'delete', id: 'n2' });
+  assert.deepEqual(
+    appResources.listAppResourceRows('app:demo:notes').map((row) => row.id),
+    ['n1'],
+  );
+
+  appResources.emitAppResourceEvents('app:demo:notes', {
+    op: 'replace',
+    value: [{ id: 'x1', text: 'fresh start' }],
+  });
+  assert.deepEqual(appResources.listAppResourceRows('app:demo:notes'), [
+    { id: 'x1', text: 'fresh start' },
+  ]);
+});
+
+test('registrations survive a registry restart (persisted + rewired)', () => {
+  // Simulate a fresh boot: the in-memory registration is gone, sqlite is not.
+  registry.unregisterResource('app:demo:notes');
+  assert.equal(registry.hasResource('app:demo:notes'), false);
+
+  // Force a reload pass the way rest.js does on first request.
+  const appResourcesPath = require.resolve('../state/app-resources');
+  delete require.cache[appResourcesPath];
+  const reloaded = require('../state/app-resources');
+  reloaded.ensureAppResourcesLoaded();
+
+  assert.equal(registry.hasResource('app:demo:notes'), true);
+  const snapshot = buildSnapshot('app:demo:notes');
+  assert.deepEqual(snapshot.resources['app:demo:notes'], [
+    { id: 'x1', text: 'fresh start' },
+  ]);
+});
+
+test('the door is namespaced and validated', () => {
+  // Built-in names cannot be claimed through the app door.
+  assert.throws(() => appResources.registerAppResource('skills'), /app:<appId>:<name>/);
+  assert.throws(() => appResources.registerAppResource('app:bad name:notes'), /app:<appId>:<name>/);
+
+  // Emitting to an unregistered resource 404s rather than auto-creating.
+  assert.throws(
+    () => appResources.emitAppResourceEvents('app:demo:ghost', { op: 'insert', id: '1', value: { id: '1' } }),
+    /not registered/,
+  );
+
+  // Malformed events are rejected with shape-explicit errors.
+  assert.throws(
+    () => appResources.emitAppResourceEvents('app:demo:notes', { op: 'insert', value: { text: 'no id' } }),
+    /requires an id/,
+  );
+  assert.throws(
+    () => appResources.emitAppResourceEvents('app:demo:notes', { op: 'replace', value: 'nope' }),
+    /full array of rows/,
+  );
+});
+
+test('unregister removes rows, frees the name, and tells listeners', () => {
+  const live = [];
+  const unsubscribe = subscribeStateEvents((event) => live.push(event));
+  const result = appResources.unregisterAppResource('app:demo:notes');
+  unsubscribe();
+
+  assert.equal(result.removed, true);
+  assert.equal(registry.hasResource('app:demo:notes'), false);
+  assert.equal(live.length, 1);
+  assert.equal(live[0].op, 'replace');
+  assert.deepEqual(live[0].value, []);
+  assert.equal(appResources.listAppResources().length, 0);
+
+  // Cascade cleared the mirror rows.
+  assert.deepEqual(appResources.listAppResourceRows('app:demo:notes'), []);
+});

package/runtime/scripts/amalgm-mcp/tests/state-docs.test.js

@@ -0,0 +1,193 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-live-docs-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+
+const Y = require('yjs');
+const { closeLocalDb } = require('../state/db');
+const docs = require('../state/docs');
+const { buildSnapshot } = require('../state/snapshot');
+const { listEventsAfter, currentSeq } = require('../state/events');
+
+const docDir = path.join(tempRoot, 'workspace');
+fs.mkdirSync(docDir, { recursive: true });
+
+function writeDoc(name, text) {
+  const target = path.join(docDir, name);
+  fs.writeFileSync(target, text, 'utf8');
+  return target;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function clientFromState(stateBase64) {
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, new Uint8Array(Buffer.from(stateBase64, 'base64')));
+  return doc;
+}
+
+function encodeLocalEdit(doc, mutate) {
+  let captured = null;
+  const listener = (update) => { captured = update; };
+  doc.on('update', listener);
+  mutate(doc.getText('content'));
+  doc.off('update', listener);
+  assert.ok(captured, 'edit should produce an update');
+  return Buffer.from(captured).toString('base64');
+}
+
+function applyEventsTo(doc, events) {
+  for (const event of events) {
+    if (event.patch?.yjs) {
+      Y.applyUpdate(doc, new Uint8Array(Buffer.from(event.patch.yjs, 'base64')));
+    }
+  }
+}
+
+test.after(() => {
+  docs.closeAllDocs();
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('open seeds the document from disk and returns usable state', () => {
+  const target = writeDoc('seed.md', '# hello\n');
+  const opened = docs.openDoc(target);
+
+  assert.equal(opened.path, target);
+  assert.ok(opened.resource.startsWith('doc:'));
+  assert.equal(docs.pathFromDocResource(opened.resource), target);
+
+  const client = clientFromState(opened.state);
+  assert.equal(client.getText('content').toString(), '# hello\n');
+});
+
+test('client updates apply, log as patch events, and flush back to disk', async () => {
+  const target = writeDoc('edit.md', 'hello world\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const before = currentSeq();
+
+  const update = encodeLocalEdit(client, (ytext) => ytext.insert(5, ','));
+  const result = docs.applyDocUpdates(target, [update]);
+  assert.equal(result.applied, 1);
+  assert.equal(docs.getDocText(target), 'hello, world\n');
+
+  // The event carries the update in the patch slot — no value payload.
+  const events = listEventsAfter(before).filter((e) => e.resource === opened.resource);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].op, 'update');
+  assert.equal(events[0].id, target);
+  assert.ok(events[0].patch?.yjs);
+  assert.equal(events[0].value, undefined);
+
+  // Debounced write-back lands on disk.
+  await sleep(500);
+  assert.equal(fs.readFileSync(target, 'utf8'), 'hello, world\n');
+});
+
+test('two clients editing concurrently converge to the same text', () => {
+  const target = writeDoc('merge.md', 'the middle\n');
+  const opened = docs.openDoc(target);
+  const clientA = clientFromState(opened.state);
+  const clientB = clientFromState(opened.state);
+  const before = currentSeq();
+
+  // Both edit from the SAME baseline, unaware of each other.
+  const updateA = encodeLocalEdit(clientA, (ytext) => ytext.insert(0, 'A: '));
+  const updateB = encodeLocalEdit(clientB, (ytext) => ytext.insert('the middle'.length, ' B'));
+
+  docs.applyDocUpdates(target, [updateA]);
+  docs.applyDocUpdates(target, [updateB]);
+
+  const engineText = docs.getDocText(target);
+  assert.equal(engineText, 'A: the middle B\n');
+
+  // Each client catches up from the relayed events and lands on the same text.
+  const events = listEventsAfter(before).filter((e) => e.resource === opened.resource);
+  applyEventsTo(clientA, events);
+  applyEventsTo(clientB, events);
+  assert.equal(clientA.getText('content').toString(), engineText);
+  assert.equal(clientB.getText('content').toString(), engineText);
+});
+
+test('external disk edits reconcile into the live doc via the watcher', async () => {
+  const target = writeDoc('agent.md', 'agent line 1\n');
+  const opened = docs.openDoc(target);
+  const before = currentSeq();
+
+  // An "agent" writes the file directly, bypassing the doc API.
+  fs.writeFileSync(target, 'agent line 1\nagent line 2\n', 'utf8');
+  await sleep(700);
+
+  assert.equal(docs.getDocText(target), 'agent line 1\nagent line 2\n');
+  const events = listEventsAfter(before).filter((e) => e.resource === opened.resource);
+  assert.ok(events.length >= 1, 'external edit should emit at least one doc event');
+  assert.equal(events[events.length - 1].source, 'doc:disk');
+});
+
+test('write-back does not echo into an event loop', async () => {
+  const target = writeDoc('loop.md', 'quiet\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  const update = encodeLocalEdit(client, (ytext) => ytext.insert(0, 'still '));
+  docs.applyDocUpdates(target, [update]);
+
+  // Let the write-back land AND the watcher's reconcile window pass.
+  await sleep(900);
+  const settled = currentSeq();
+  await sleep(700);
+  const after = listEventsAfter(settled).filter((e) => e.resource === opened.resource);
+  assert.equal(after.length, 0, `write-back must not re-emit (got ${JSON.stringify(after)})`);
+  assert.equal(fs.readFileSync(target, 'utf8'), 'still quiet\n');
+});
+
+test('documents survive close: persisted state + disk agree on reopen', () => {
+  const target = writeDoc('reopen.md', 'v1\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const update = encodeLocalEdit(client, (ytext) => ytext.insert(0, 'v2 over '));
+  docs.applyDocUpdates(target, [update]);
+
+  docs.closeAllDocs(); // flushes disk + state
+
+  const reopened = docs.openDoc(target);
+  const fresh = clientFromState(reopened.state);
+  assert.equal(fresh.getText('content').toString(), 'v2 over v1\n');
+  assert.equal(fs.readFileSync(target, 'utf8'), 'v2 over v1\n');
+});
+
+test('snapshots serve open docs only and never break on bad names', () => {
+  const target = writeDoc('snap.md', 'snapshot me\n');
+  const opened = docs.openDoc(target);
+
+  const withDoc = buildSnapshot(opened.resource);
+  assert.equal(clientFromState(withDoc.resources[opened.resource].state)
+    .getText('content').toString(), 'snapshot me\n');
+
+  // Unopened doc → absent, garbage name → absent; snapshot itself stays fine.
+  const unopened = docs.docResourceName(path.join(docDir, 'never-opened.md'));
+  const garbage = buildSnapshot(`doc:!!!not-base64!!!,${unopened}`);
+  assert.deepEqual(garbage.resources, {});
+});
+
+test('guards: binary, missing, oversized, and malformed inputs are rejected', () => {
+  assert.throws(() => docs.openDoc(writeDoc('image.png', 'not really')), /text files only/);
+  assert.throws(() => docs.openDoc(path.join(docDir, 'missing.md')), /not found/);
+
+  const big = writeDoc('big.md', 'x'.repeat(2 * 1024 * 1024 + 1));
+  assert.throws(() => docs.openDoc(big), /live document limit/);
+
+  const target = writeDoc('guarded.md', 'ok\n');
+  assert.throws(() => docs.applyDocUpdates(target, [123]), /base64-encoded/);
+  assert.throws(() => docs.applyDocUpdates(target, ['aGVsbG8=']), /invalid Yjs update/);
+});