amalgm 0.1.246 → 0.1.247

package/README.md

@@ -22,9 +22,11 @@ amalgm register path/to/file path/to/folder
 
 `amalgm register` watches the selected local ground and saves its entity
 records and file contents to the signed-in user's private Amalgm cloud
-resource. `amalgm add` is reserved for the inverse operation—bringing an
-existing cloud entity onto a machine—and is not available until
-materialization ships.
+resource. Use `amalgm add <entity-uuid> [directory]` on another machine to
+bring an existing cloud-backed workspace or file tree onto that machine. It
+uses one verified current cloud snapshot, downloads its immutable file bytes,
+preserves the UUIDs, and starts a local watcher. It does not replay old cloud
+mutations to rebuild the tree.
 
 If you start from the Amalgm web app or are setting up a remote/headless machine, create a setup code from the web app and run:
 

package/lib/cli.js

@@ -119,7 +119,7 @@ function usage() {
     '  amalgm run [--local-only]',
     '  amalgm stop',
     '  amalgm register [path ...] Register local ground (default: current directory)',
-    '  amalgm add <entity-uuid> [path] Add a cloud-backed entity to this machine (coming with materialization)',
+    '  amalgm add <entity-uuid> [directory] Add a cloud-backed tree to this machine',
     '  amalgm status',
     '  amalgm doctor',
     '  amalgm service [install|start|stop|status|uninstall] [--mode auto|systemd|launchd|windows|portable]',
@@ -1491,6 +1491,72 @@ async function register(positionals) {
   }
 }
 
+/** `amalgm add <cloud-root-uuid> [directory]` — ask the local runtime to
+ * materialize one compacted cloud head beneath a fresh child in `directory`.
+ * The CLI never speaks cloud storage itself: the runtime owns the pinned
+ * snapshot, content verification, and watcher binding. */
+async function add(positionals) {
+  if (positionals.length < 1 || positionals.length > 2) {
+    throw new Error('Usage: amalgm add <entity-uuid> [directory]');
+  }
+  const uuid = positionals[0];
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid)) {
+    throw new Error('amalgm add requires a cloud entity UUID');
+  }
+  const targetPath = path.resolve(positionals[1] || process.cwd());
+  const port = servicePorts().find(([name]) => name === 'amalgm-mcp')?.[1];
+  let answer = null;
+  if (port) {
+    // A live entity commit may have reached this machine a moment before
+    // the gateway returns its newly compacted head. The runtime refuses to
+    // materialize the old snapshot plus that tail; wait for the tunnel's
+    // immediate refresh instead of weakening that boundary.
+    const refreshDeadline = Date.now() + 30_000;
+    while (!answer) {
+      try {
+        const candidate = await runtimePost(port, '/entities/add', { uuid, path: targetPath });
+        if (candidate.status !== 409
+          || !/catalog is not pinned to the active cloud head/i.test(candidate.payload?.error || '')
+          || Date.now() >= refreshDeadline) {
+          answer = candidate;
+          break;
+        }
+        await sleep(200);
+      } catch (error) {
+        if (error.code !== 'ECONNREFUSED') throw error;
+        break;
+      }
+    }
+  }
+  if (!answer) {
+    console.error('Amalgm runtime is not running. Start it with `amalgm start`.');
+    process.exitCode = 1;
+    return;
+  }
+  if (![200, 202].includes(answer.status)) {
+    console.error(`Error: ${answer.payload?.error || `runtime responded ${answer.status}`}`);
+    process.exitCode = 1;
+    return;
+  }
+  let job = answer.payload;
+  const deadline = Date.now() + 120_000;
+  while (job?.state === 'waiting_for_content' || job?.state === 'materializing') {
+    if (Date.now() > deadline) {
+      console.error(`Still fetching cloud content for ${uuid}. Run the same command again to check progress.`);
+      process.exitCode = 1;
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    job = (await runtimeGet(port, `/entities/add/${encodeURIComponent(job.jobId)}`)).payload;
+  }
+  if (job?.state !== 'complete') {
+    console.error(`Error: ${job?.error || 'cloud materialization failed'}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Added ${job.entityUuid} to ${job.targetPath}`);
+}
+
 /** POST JSON to a local runtime service, carrying the runtime token. */
 function runtimePost(port, requestPath, body) {
   const payload = JSON.stringify(body);
@@ -1525,6 +1591,30 @@ function runtimePost(port, requestPath, body) {
   });
 }
 
+function runtimeGet(port, requestPath) {
+  const token = readJson(RUNTIME_TOKEN_FILE, null)?.token || '';
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: requestPath,
+      method: 'GET',
+      headers: token ? { 'x-amalgm-runtime-token': token } : {},
+    }, (res) => {
+      let text = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { text += chunk; });
+      res.on('end', () => {
+        let parsed = null;
+        try { parsed = JSON.parse(text); } catch {}
+        resolve({ status: res.statusCode, payload: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
 async function main(argv) {
   const { command, options, positionals } = parseArgs(argv);
 
@@ -1548,9 +1638,7 @@ async function main(argv) {
   }
   if (command === 'stop') return stop();
   if (command === 'register') return register(positionals);
-  if (command === 'add') {
-    throw new Error('`amalgm add` is reserved for cloud-to-local materialization, which is not available yet. Use `amalgm register <path>` for local ground.');
-  }
+  if (command === 'add') return add(positionals);
   if (command === 'status') return status();
   if (command === 'doctor') return doctor();
   if (command === 'service') return serviceCommand(options, positionals);

package/lib/shared-realtime-tunnel.js

@@ -33,6 +33,7 @@ function createSharedRealtimeTunnel({
   const mutationInflight = new Map();
   const entityMutationInflight = new Map();
   const entityContentInflight = new Map();
+  const entityContentDownloadInflight = new Map();
   const promotionInflight = new Map();
   const attachmentInflight = new Map();
   const privateEnsureInflight = new Map();
@@ -369,25 +370,44 @@ function createSharedRealtimeTunnel({
         leaseMs: CLAIM_LEASE_MS,
       });
       const upload = result?.upload;
-      if (!upload?.resourceId || !upload?.contentHash || !upload?.kind) return;
-      const requestId = `entity_content_${crypto.randomBytes(12).toString('hex')}`;
-      if (!sendLarge({
-        type: 'private.entity-content.put',
-        request_id: requestId,
-        resource_id: upload.resourceId,
-        content_hash: upload.contentHash,
-        kind: upload.kind,
-        part_index: upload.partIndex,
-        part_count: upload.partCount,
-        sha256: upload.sha256,
-        bytes: upload.bytes,
-        data_b64: upload.dataBase64,
-      })) {
-        await failEntityContent(upload, 'shared tunnel backpressure: entity content was not queued');
-        scheduleEntityContentDrain(RETRY_MS);
-        return;
+      if (upload?.resourceId && upload?.contentHash && upload?.kind) {
+        const requestId = `entity_content_${crypto.randomBytes(12).toString('hex')}`;
+        if (!sendLarge({
+          type: 'private.entity-content.put',
+          request_id: requestId,
+          resource_id: upload.resourceId,
+          content_hash: upload.contentHash,
+          kind: upload.kind,
+          part_index: upload.partIndex,
+          part_count: upload.partCount,
+          sha256: upload.sha256,
+          bytes: upload.bytes,
+          data_b64: upload.dataBase64,
+        })) {
+          await failEntityContent(upload, 'shared tunnel backpressure: entity content was not queued');
+          scheduleEntityContentDrain(RETRY_MS);
+        } else {
+          entityContentInflight.set(requestId, upload);
+        }
+      }
+      if (entityContentDownloadInflight.size === 0) {
+        const downloadResult = await localStateJson('POST', '/entities/cloud/content/downloads/claim', {});
+        const download = downloadResult?.download;
+        if (download?.resourceId && download?.contentHash && download?.kind) {
+          const requestId = `entity_content_get_${crypto.randomBytes(12).toString('hex')}`;
+          if (send({
+            type: 'private.entity-content.get',
+            request_id: requestId,
+            resource_id: download.resourceId,
+            content_hash: download.contentHash,
+            kind: download.kind,
+            part_index: download.partIndex,
+            ...(download.sha256 ? { sha256: download.sha256 } : {}),
+          })) {
+            entityContentDownloadInflight.set(requestId, download);
+          }
+        }
       }
-      entityContentInflight.set(requestId, upload);
     })().catch((error) => {
       localFailures += 1;
       if (localFailures === 1 || localFailures % 20 === 0) {
@@ -790,6 +810,27 @@ function createSharedRealtimeTunnel({
     });
   }
 
+  function handlePrivateEntityContentData(frame) {
+    const download = entityContentDownloadInflight.get(frame.request_id);
+    if (!download || download.contentHash !== frame.content_hash || download.kind !== frame.kind
+      || download.partIndex !== frame.part_index) return;
+    void localStateJson('POST', '/entities/cloud/content/downloads/receive', {
+      resourceId: download.resourceId,
+      contentHash: download.contentHash,
+      kind: download.kind,
+      partIndex: download.partIndex,
+      sha256: frame.sha256,
+      dataBase64: frame.data_b64,
+    }).then(() => {
+      entityContentDownloadInflight.delete(frame.request_id);
+      scheduleEntityContentDrain();
+    }).catch((error) => {
+      warn(`entity content ${download.contentHash} was not stored locally: ${error?.message || error}`);
+      entityContentDownloadInflight.delete(frame.request_id);
+      scheduleEntityContentDrain(RETRY_MS);
+    });
+  }
+
   function handleAttached(frame) {
     const identity = attachmentInflight.get(frame.request_id);
     if (!identity) return;
@@ -897,6 +938,11 @@ function createSharedRealtimeTunnel({
         committedAt: frame.committed_at,
       }).then(() => {
         entityMutationInflight.delete(frame.request_id);
+        // An acknowledgement advances the official head. Re-read the
+        // private resource immediately: the gateway compacts that head into
+        // one immutable snapshot before replying, so this device never has
+        // to use its mutation tail as an `amalgm add` starting point.
+        void ensurePrivateEntityRegistry();
         scheduleEntityMutationDrain();
       }).catch(() => {
         setTimeout(() => enabled && handleAck(frame), RETRY_MS).unref?.();
@@ -942,6 +988,11 @@ function createSharedRealtimeTunnel({
         });
       return;
     }
+    if (entityContentDownloadInflight.has(frame.request_id)) {
+      entityContentDownloadInflight.delete(frame.request_id);
+      scheduleEntityContentDrain(RETRY_MS);
+      return;
+    }
     const privateResource = privateEnsureInflight.get(frame.request_id);
     if (privateResource) {
       privateEnsureInflight.delete(frame.request_id);
@@ -1049,12 +1100,20 @@ function createSharedRealtimeTunnel({
       ? '/entities/cloud/mutations/ingest'
       : '/state/mutations/ingest';
     const prior = inboundChains.get(resourceId) || Promise.resolve();
+    const entityRegistryMutation = endpoint === '/entities/cloud/mutations/ingest';
     const next = prior.then(() => localStateJson('POST', endpoint, {
       envelope: frame.envelope,
       version: frame.version,
       committedAt: frame.committed_at,
       actorUserId: frame.actor_user_id,
-    })).catch((error) => {
+    })).then(() => {
+      if (entityRegistryMutation) {
+        // The live frame is useful for collaboration, but cannot become the
+        // reconstruction path for a new local binding. Ask the authority to
+        // compact and return its active snapshot before `add` can continue.
+        void ensurePrivateEntityRegistry();
+      }
+    }).catch((error) => {
       warn(`shared mutation ${frame.mutation_id || 'unknown'} was not materialized: ${error?.message || error}`);
       setTimeout(() => enabled && void joinReplicas(), RETRY_MS).unref?.();
     }).finally(() => {
@@ -1135,6 +1194,9 @@ function createSharedRealtimeTunnel({
       case 'private.entity-content.stored':
         handlePrivateEntityContentStored(frame);
         return true;
+      case 'private.entity-content.data':
+        handlePrivateEntityContentData(frame);
+        return true;
       case 'repo.object.stored':
         handleRepoObjectStored(frame);
         return true;
@@ -1162,6 +1224,7 @@ function createSharedRealtimeTunnel({
     mutationInflight.clear();
     entityMutationInflight.clear();
     entityContentInflight.clear();
+    entityContentDownloadInflight.clear();
     promotionInflight.clear();
     attachmentInflight.clear();
     privateEnsureInflight.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.246",
+  "version": "0.1.247",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/automations/deliveries.js

@@ -0,0 +1,276 @@
+'use strict';
+
+/**
+ * Durable local automation delivery inbox.
+ *
+ * Both scheduled slots and cloud-relayed events enter this table before any
+ * workflow starts. Receipt and execution are deliberately separate: HTTP and
+ * schedule producers only commit immutable input; this worker owns leases,
+ * retries, and terminal receipts.
+ */
+
+const crypto = require('crypto');
+
+const { openLocalDb } = require('../state/db');
+const { executeAutomationForTrigger } = require('./runner');
+
+const DEFAULT_BATCH_SIZE = 25;
+const DEFAULT_LEASE_MS = 10 * 60_000;
+const MAX_RETRY_DELAY_MS = 5 * 60_000;
+
+let draining = false;
+
+function nowIso(date = new Date()) {
+  return date.toISOString();
+}
+
+function parseJson(value, fallback) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+function rowToDelivery(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    kind: row.kind,
+    triggerId: row.trigger_id || null,
+    scheduledFor: row.scheduled_for || null,
+    payload: parseJson(row.payload_json, {}),
+    status: row.status,
+    attemptCount: Number(row.attempt_count) || 0,
+    nextAttemptAt: row.next_attempt_at || null,
+    leaseExpiresAt: row.lease_expires_at || null,
+    completedTriggerIds: parseJson(row.completed_trigger_ids_json, []),
+    result: parseJson(row.result_json, null),
+    lastError: row.last_error || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    completedAt: row.completed_at || null,
+  };
+}
+
+function eventDeliveryId(value) {
+  const cleaned = String(value || '').trim();
+  if (cleaned && cleaned.length <= 200 && /^[A-Za-z0-9._:-]+$/.test(cleaned)) {
+    return cleaned;
+  }
+  return `event:${crypto.randomUUID()}`;
+}
+
+function enqueueEventDelivery(input = {}) {
+  const timestamp = nowIso();
+  const id = eventDeliveryId(input.id);
+  const payload = {
+    rawBody: typeof input.rawBody === 'string' ? input.rawBody : '',
+    headers: input.headers && typeof input.headers === 'object' ? input.headers : {},
+    receivedAt: input.receivedAt || timestamp,
+  };
+  const db = openLocalDb();
+  db.prepare(`
+    INSERT INTO automation_deliveries (
+      id, kind, payload_json, status, next_attempt_at, created_at, updated_at
+    ) VALUES (?, 'event', ?, 'pending', ?, ?, ?)
+    ON CONFLICT(id) DO NOTHING
+  `).run(id, JSON.stringify(payload), timestamp, timestamp, timestamp);
+  return rowToDelivery(db.prepare('SELECT * FROM automation_deliveries WHERE id = ?').get(id));
+}
+
+function claimDeliveries(options = {}) {
+  const db = openLocalDb();
+  const now = options.now instanceof Date ? options.now : new Date();
+  const timestamp = nowIso(now);
+  const leaseExpiresAt = nowIso(new Date(now.getTime() + (Number(options.leaseMs) || DEFAULT_LEASE_MS)));
+  const limit = Math.max(1, Math.min(Number(options.limit) || DEFAULT_BATCH_SIZE, 100));
+
+  return db.transaction(() => {
+    const rows = db.prepare(`
+      SELECT *
+      FROM automation_deliveries
+      WHERE (
+        status = 'pending'
+        AND (next_attempt_at IS NULL OR next_attempt_at <= ?)
+      ) OR (
+        status = 'running'
+        AND lease_expires_at IS NOT NULL
+        AND lease_expires_at <= ?
+      )
+      ORDER BY datetime(created_at) ASC, id ASC
+      LIMIT ?
+    `).all(timestamp, timestamp, limit);
+
+    const update = db.prepare(`
+      UPDATE automation_deliveries
+      SET status = 'running',
+          attempt_count = attempt_count + 1,
+          lease_expires_at = ?,
+          next_attempt_at = NULL,
+          updated_at = ?
+      WHERE id = ?
+    `);
+    for (const row of rows) update.run(leaseExpiresAt, timestamp, row.id);
+    return rows.map((row) => rowToDelivery({
+      ...row,
+      status: 'running',
+      attempt_count: Number(row.attempt_count) + 1,
+      lease_expires_at: leaseExpiresAt,
+      next_attempt_at: null,
+      updated_at: timestamp,
+    }));
+  })();
+}
+
+function recordTriggerCompletion(deliveryId, triggerId) {
+  const db = openLocalDb();
+  return db.transaction(() => {
+    const row = db.prepare('SELECT * FROM automation_deliveries WHERE id = ?').get(deliveryId);
+    if (!row) return null;
+    const completed = new Set(parseJson(row.completed_trigger_ids_json, []));
+    completed.add(triggerId);
+    const timestamp = nowIso();
+    db.prepare(`
+      UPDATE automation_deliveries
+      SET completed_trigger_ids_json = ?, updated_at = ?
+      WHERE id = ?
+    `).run(JSON.stringify([...completed]), timestamp, deliveryId);
+    return [...completed];
+  })();
+}
+
+function finishDelivery(deliveryId, status, result = null) {
+  if (!['completed', 'rejected'].includes(status)) {
+    throw new Error(`Invalid terminal delivery status: ${status}`);
+  }
+  const timestamp = nowIso();
+  openLocalDb().prepare(`
+    UPDATE automation_deliveries
+    SET status = ?,
+        result_json = ?,
+        last_error = NULL,
+        lease_expires_at = NULL,
+        next_attempt_at = NULL,
+        completed_at = ?,
+        updated_at = ?
+    WHERE id = ?
+  `).run(status, result == null ? null : JSON.stringify(result), timestamp, timestamp, deliveryId);
+}
+
+function retryDelivery(deliveryId, error, options = {}) {
+  const db = openLocalDb();
+  const row = db.prepare('SELECT attempt_count FROM automation_deliveries WHERE id = ?').get(deliveryId);
+  if (!row) return null;
+  const attemptCount = Math.max(1, Number(row.attempt_count) || 1);
+  const delayMs = options.immediate
+    ? 0
+    : Math.min(MAX_RETRY_DELAY_MS, 1000 * (2 ** Math.min(attemptCount - 1, 8)));
+  const now = options.now instanceof Date ? options.now : new Date();
+  const timestamp = nowIso(now);
+  const nextAttemptAt = nowIso(new Date(now.getTime() + delayMs));
+  db.prepare(`
+    UPDATE automation_deliveries
+    SET status = 'pending',
+        next_attempt_at = ?,
+        lease_expires_at = NULL,
+        last_error = ?,
+        updated_at = ?,
+        completed_at = NULL
+    WHERE id = ?
+  `).run(nextAttemptAt, String(error?.message || error || 'Delivery failed').slice(0, 8000), timestamp, deliveryId);
+  return getDelivery(deliveryId);
+}
+
+function getDelivery(deliveryId) {
+  return rowToDelivery(openLocalDb().prepare(
+    'SELECT * FROM automation_deliveries WHERE id = ?',
+  ).get(String(deliveryId || '')));
+}
+
+function listDeliveries(options = {}) {
+  const conditions = [];
+  const params = [];
+  if (options.status) {
+    conditions.push('status = ?');
+    params.push(String(options.status));
+  }
+  if (options.kind) {
+    conditions.push('kind = ?');
+    params.push(String(options.kind));
+  }
+  const limit = Math.max(1, Math.min(Number(options.limit) || 100, 500));
+  const offset = Math.max(0, Number(options.offset) || 0);
+  params.push(limit, offset);
+  return openLocalDb().prepare(`
+    SELECT *
+    FROM automation_deliveries
+    ${conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''}
+    ORDER BY datetime(created_at) DESC, id DESC
+    LIMIT ? OFFSET ?
+  `).all(...params).map(rowToDelivery);
+}
+
+async function processDelivery(delivery) {
+  if (delivery.kind === 'scheduled') {
+    if (!delivery.triggerId) {
+      finishDelivery(delivery.id, 'rejected', { reason: 'Scheduled trigger no longer exists' });
+      return;
+    }
+    const event = {
+      id: delivery.id,
+      source: 'amalgm.scheduler',
+      event: 'scheduled',
+      payload: delivery.payload,
+      headers: {},
+      receivedAt: delivery.createdAt,
+    };
+    await executeAutomationForTrigger(delivery.triggerId, event);
+    recordTriggerCompletion(delivery.id, delivery.triggerId);
+    finishDelivery(delivery.id, 'completed', { triggerIds: [delivery.triggerId] });
+    return;
+  }
+
+  const { processEventEnvelope } = require('../events/processor');
+  const result = await processEventEnvelope({
+    deliveryId: delivery.id,
+    rawBody: delivery.payload.rawBody,
+    headers: delivery.payload.headers,
+    receivedAt: delivery.payload.receivedAt || delivery.createdAt,
+    completedTriggerIds: delivery.completedTriggerIds,
+    onTriggerComplete: (triggerId) => recordTriggerCompletion(delivery.id, triggerId),
+  });
+  finishDelivery(delivery.id, result.terminalStatus, result);
+}
+
+async function drainAutomationDeliveries(options = {}) {
+  if (draining) return { claimed: 0, busy: true };
+  draining = true;
+  let claimed = 0;
+  try {
+    const deliveries = claimDeliveries(options);
+    claimed = deliveries.length;
+    for (const delivery of deliveries) {
+      try {
+        await processDelivery(delivery);
+      } catch (error) {
+        retryDelivery(delivery.id, error);
+        console.error(`[AmalgmMCP:Automations] Delivery ${delivery.id} failed; retry remains pending:`, error.message || error);
+      }
+    }
+    return { claimed, busy: false };
+  } finally {
+    draining = false;
+  }
+}
+
+module.exports = {
+  claimDeliveries,
+  drainAutomationDeliveries,
+  enqueueEventDelivery,
+  finishDelivery,
+  getDelivery,
+  listDeliveries,
+  recordTriggerCompletion,
+  retryDelivery,
+};

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

@@ -21,6 +21,12 @@ const {
 } = require('./store');
 const { executeAutomationById } = require('./runner');
 const { validateWorkflowText } = require('./validator');
+const {
+  getDelivery,
+  listDeliveries,
+  retryDelivery,
+  drainAutomationDeliveries,
+} = require('./deliveries');
 
 function sendError(sendJson, status, error) {
   sendJson(status, { error: error.message || String(error) });
@@ -158,6 +164,49 @@ async function handleRunNow(body, sendJson) {
   }
 }
 
+async function handleDeliveries(body, sendJson) {
+  try {
+    const deliveryId = body?.delivery_id || body?.deliveryId;
+    if (deliveryId) {
+      const delivery = getDelivery(deliveryId);
+      if (!delivery) return sendJson(404, { error: 'Delivery not found' });
+      return sendJson(200, { ok: true, delivery });
+    }
+    const limit = Math.max(1, Math.min(Number(body?.limit) || 100, 500));
+    const offset = Math.max(0, Number(body?.offset) || 0);
+    const deliveries = listDeliveries({
+      status: body?.status,
+      kind: body?.kind,
+      limit: limit + 1,
+      offset,
+    });
+    sendJson(200, {
+      ok: true,
+      deliveries: deliveries.slice(0, limit),
+      hasMore: deliveries.length > limit,
+      limit,
+      offset,
+    });
+  } catch (error) {
+    sendError(sendJson, 400, error);
+  }
+}
+
+async function handleDeliveryRetry(body, sendJson) {
+  try {
+    const deliveryId = body?.delivery_id || body?.deliveryId;
+    if (!deliveryId) return sendJson(400, { error: 'delivery_id is required' });
+    if (!getDelivery(deliveryId)) return sendJson(404, { error: 'Delivery not found' });
+    const delivery = retryDelivery(deliveryId, 'Manual retry requested', { immediate: true });
+    void drainAutomationDeliveries().catch((error) => {
+      console.error('[AmalgmMCP:Automations] Manual delivery drain failed:', error.message || error);
+    });
+    sendJson(200, { ok: true, delivery });
+  } catch (error) {
+    sendError(sendJson, 400, error);
+  }
+}
+
 async function handleTriggerUpdate(body, sendJson) {
   try {
     const id = body?.trigger_id || body?.triggerId;
@@ -184,6 +233,8 @@ async function handleTriggerDelete(body, sendJson) {
 
 module.exports = {
   handleCreate,
+  handleDeliveries,
+  handleDeliveryRetry,
   handleDelete,
   handleGet,
   handleList,