@automagik/omni 2.260906.2 → 2.260906.4

package/dist/index.js

@@ -12345,6 +12345,19 @@ var init_types3 = __esm(() => {
     "flow.data_exchange"
   ];
 });
+// ../core/src/events/causality.ts
+import { AsyncLocalStorage } from "async_hooks";
+function runWithEventCausality(context, fn) {
+  return storage.run(context, fn);
+}
+function currentEventCausality() {
+  return storage.getStore();
+}
+var storage;
+var init_causality = __esm(() => {
+  storage = new AsyncLocalStorage;
+});
+
 // ../core/src/events/envelope.ts
 function classifyEnvelope(metadata) {
   if (metadata === null || metadata === undefined)
@@ -30370,6 +30383,38 @@ var init_logger = __esm(() => {
   rootLogger = createLogger("system");
 });
 
+// ../core/src/events/factory.ts
+function createOmniEvent(type, payload, metadata, serviceName) {
+  const eventId = crypto.randomUUID();
+  const timestamp = Date.now();
+  const tenantId = resolvePublishTenantId(metadata?.tenantId, metadata?.instanceId);
+  const ambient = currentEventCausality();
+  const causationId = metadata?.causationId ?? ambient?.causationId;
+  return {
+    id: eventId,
+    type,
+    payload,
+    timestamp,
+    metadata: {
+      correlationId: metadata?.correlationId ?? ambient?.correlationId ?? eventId,
+      ...causationId ? { causationId } : {},
+      instanceId: metadata?.instanceId,
+      channelType: metadata?.channelType,
+      personId: metadata?.personId,
+      platformIdentityId: metadata?.platformIdentityId,
+      traceId: metadata?.traceId ?? eventId,
+      source: metadata?.source ?? serviceName,
+      ingestMode: metadata?.ingestMode,
+      timings: metadata?.timings,
+      ...tenantId ? { envelopeVersion: CURRENT_ENVELOPE_VERSION, tenantId } : {}
+    }
+  };
+}
+var init_factory = __esm(() => {
+  init_causality();
+  init_envelope();
+});
+
 // ../core/src/events/nats/streams.ts
 function getStreamForEventType(eventType) {
   const prefix = eventType.split(".")[0] ?? "";
@@ -30739,7 +30784,24 @@ var init_registry = __esm(() => {
       component: exports_external.string(),
       reason: exports_external.string(),
       severity: exports_external.enum(["warning", "critical"])
-    }), { description: "System health degradation detected" })
+    }), { description: "System health degradation detected" }),
+    connectorStalled: createEventSchema("system.connector.stalled", exports_external.object({
+      sourceId: exports_external.string(),
+      sourceName: exports_external.string(),
+      expectedIntervalSeconds: exports_external.number(),
+      lastReceivedAt: exports_external.number().nullable(),
+      lastHeartbeatAt: exports_external.number().nullable(),
+      silentForSeconds: exports_external.number(),
+      stalledAt: exports_external.number()
+    }), { description: "A supervised connector went silent beyond its declared cadence" }),
+    connectorRecovered: createEventSchema("system.connector.recovered", exports_external.object({
+      sourceId: exports_external.string(),
+      sourceName: exports_external.string(),
+      expectedIntervalSeconds: exports_external.number(),
+      stalledForSeconds: exports_external.number(),
+      recoveredBy: exports_external.enum(["event", "heartbeat", "rearmed"]),
+      recoveredAt: exports_external.number()
+    }), { description: "A stalled connector signalled again (event, heartbeat, or re-declared cadence)" })
   };
   CustomEventSchemas = {
     chatUnreadUpdated: createEventSchema("custom.chat.unread-updated", exports_external.object({
@@ -31159,27 +31221,8 @@ class NatsEventBus {
   }
   async publishInternal(type, payload, metadata) {
     await this.ensureConnected();
-    const eventId = crypto.randomUUID();
-    const timestamp = Date.now();
-    const tenantId = resolvePublishTenantId(metadata?.tenantId, metadata?.instanceId);
-    const event = {
-      id: eventId,
-      type,
-      payload,
-      timestamp,
-      metadata: {
-        correlationId: metadata?.correlationId ?? eventId,
-        instanceId: metadata?.instanceId,
-        channelType: metadata?.channelType,
-        personId: metadata?.personId,
-        platformIdentityId: metadata?.platformIdentityId,
-        traceId: metadata?.traceId ?? eventId,
-        source: metadata?.source ?? this.config.serviceName,
-        ingestMode: metadata?.ingestMode,
-        timings: metadata?.timings,
-        ...tenantId ? { envelopeVersion: CURRENT_ENVELOPE_VERSION, tenantId } : {}
-      }
-    };
+    const event = createOmniEvent(type, payload, metadata, this.config.serviceName);
+    const eventId = event.id;
     let subject;
     if (metadata?.channelType && metadata?.instanceId) {
       subject = buildSubject(type, metadata.channelType, metadata.instanceId);
@@ -31455,7 +31498,7 @@ async function connectEventBus(config2) {
 var import_api2, import_nats, log4, DEFAULTS, ENSURE_CONNECTED_WAIT_MS = 5000;
 var init_client = __esm(() => {
   init_logger();
-  init_envelope();
+  init_factory();
   init_consumer();
   init_registry();
   init_streams();
@@ -39448,6 +39491,7 @@ function estimateCompletion(progress) {
 // ../core/src/events/index.ts
 var init_events = __esm(() => {
   init_types3();
+  init_causality();
   init_envelope();
   init_nats();
   init_dead_letter();
@@ -45127,13 +45171,7 @@ function resolveFollowUpValue(trimmed, followUp) {
       return;
   }
 }
-function resolveTemplatePath(path, context) {
-  const trimmed = path.trim();
-  if (!trimmed)
-    return;
-  const parts = trimmed.split(".");
-  const root = parts[0] ?? "";
-  const rest = parts.slice(1).join(".");
+function resolveSpecialValue(trimmed, root, rest, context) {
   if (context.debounce) {
     const debounceValue = resolveDebounceValue(trimmed, rest, context.debounce);
     if (debounceValue !== undefined)
@@ -45144,6 +45182,21 @@ function resolveTemplatePath(path, context) {
     if (followUpValue !== undefined)
       return followUpValue;
   }
+  if (root === "event" && context.event) {
+    return rest ? getNestedValue(context.event, rest) : context.event;
+  }
+  return;
+}
+function resolveTemplatePath(path, context) {
+  const trimmed = path.trim();
+  if (!trimmed)
+    return;
+  const parts = trimmed.split(".");
+  const root = parts[0] ?? "";
+  const rest = parts.slice(1).join(".");
+  const specialValue = resolveSpecialValue(trimmed, root, rest, context);
+  if (specialValue !== undefined)
+    return specialValue;
   if (root === "payload")
     return rest ? getNestedValue(context.payload, rest) : context.payload;
   if (root === "env")
@@ -45225,7 +45278,9 @@ function createTemplateContext(payload, options = {}) {
     variables: options.variables ?? {},
     env: process.env,
     debounce: options.debounce,
-    followUp
+    followUp,
+    event: options.event,
+    automation: options.automation
   };
 }
 var TEMPLATE_REGEX;
@@ -45797,8 +45852,12 @@ var init_egress = __esm(() => {
 });
 
 // ../core/src/automations/actions.ts
-function buildWebhookHeaders(config2, context) {
+function buildWebhookHeaders(config2, context, actionIndex) {
   const headers = { "Content-Type": "application/json" };
+  if (context.event) {
+    headers["X-Omni-Event-Id"] = context.event.id;
+    headers["X-Omni-Delivery-Id"] = `${context.event.id}:${context.automation?.id ?? "manual"}:${actionIndex}`;
+  }
   if (config2.headers) {
     for (const [key, value] of Object.entries(config2.headers)) {
       headers[key] = substituteTemplate(value, context);
@@ -45806,16 +45865,28 @@ function buildWebhookHeaders(config2, context) {
   }
   return headers;
 }
+function buildDefaultWebhookBody(config2, context) {
+  if (context.event && config2.includeEnvelope !== false) {
+    return JSON.stringify({
+      id: context.event.id,
+      type: context.event.type,
+      payload: context.payload,
+      metadata: context.event.metadata,
+      timestamp: context.event.timestamp
+    });
+  }
+  return JSON.stringify(context.payload);
+}
 async function parseWebhookResponse(response) {
   const contentType = response.headers.get("content-type") ?? "";
   return contentType.includes("application/json") ? response.json() : response.text();
 }
-async function executeWebhookAction(config2, context, _deps, trustedTenantId) {
+async function executeWebhookAction(config2, context, _deps, trustedTenantId, actionIndex = 0) {
   try {
     const url = substituteTemplate(config2.url, context);
     const method = config2.method ?? "POST";
-    const headers = buildWebhookHeaders(config2, context);
-    const body = config2.bodyTemplate ? substituteTemplate(config2.bodyTemplate, context) : JSON.stringify(context.payload);
+    const headers = buildWebhookHeaders(config2, context, actionIndex);
+    const body = config2.bodyTemplate ? substituteTemplate(config2.bodyTemplate, context) : buildDefaultWebhookBody(config2, context);
     logger2.debug(`Webhook ${method} ${url}`, { method, url, waitForResponse: config2.waitForResponse });
     const response = await brokeredFetch(url, {
       method,
@@ -45905,8 +45976,10 @@ async function executeEmitEventAction(config2, context, deps, trustedTenantId) {
       }
     }
     logger2.debug("Emitting event", { eventType });
+    const correlationId = context.event?.metadata.correlationId ?? context.payload.correlationId ?? undefined;
     const result = await deps.eventBus.publishGeneric(eventType, payload, {
-      correlationId: context.payload.correlationId ?? undefined,
+      correlationId,
+      causationId: context.event?.id,
       source: "automation",
       ...trustedTenantId ? { tenantId: trustedTenantId } : {}
     });
@@ -45999,7 +46072,12 @@ function extractAgentCallContext(config2, context) {
       threadId,
       senderId,
       senderName,
-      messages: messagesResult
+      messages: messagesResult,
+      event: context.event ? {
+        id: context.event.id,
+        type: context.event.type,
+        correlationId: context.event.metadata.correlationId
+      } : undefined
     }
   };
 }
@@ -46040,12 +46118,12 @@ async function executeCallAgentAction(config2, context, deps, trustedTenantId) {
     return { success: false, error: errorMessage };
   }
 }
-async function executeAction(action, context, deps, trustedTenantId) {
+async function executeAction(action, context, deps, trustedTenantId, actionIndex = 0) {
   const start = Date.now();
   let result;
   switch (action.type) {
     case "webhook":
-      result = await executeWebhookAction(action.config, context, deps, trustedTenantId);
+      result = await executeWebhookAction(action.config, context, deps, trustedTenantId, actionIndex);
       break;
     case "send_message":
       result = await executeSendMessageAction(action.config, context, deps, trustedTenantId);
@@ -46074,12 +46152,12 @@ async function executeAction(action, context, deps, trustedTenantId) {
 async function executeActions(actions, context, deps, trustedTenantId) {
   const results = [];
   const variables = { ...context.variables };
-  for (const action of actions) {
+  for (const [actionIndex, action] of actions.entries()) {
     const actionContext = {
       ...context,
       variables
     };
-    const result = await executeAction(action, actionContext, deps, trustedTenantId);
+    const result = await executeAction(action, actionContext, deps, trustedTenantId, actionIndex);
     results.push(result);
     if (action.type === "webhook" && action.config.responseAs && result.status === "success" && result.result) {
       variables[action.config.responseAs] = result.result;
@@ -46509,13 +46587,18 @@ class AutomationEngine {
       type: content?.type ?? "unknown",
       text: content?.text,
       timestamp: event.timestamp,
-      payload
+      payload,
+      eventId: event.id,
+      correlationId: event.metadata.correlationId
     };
     manager.addMessage(key, message2, from, instanceId, stamp);
   }
   async handleImmediate(automation, event) {
     const instanceId = event.metadata.instanceId ?? "global";
-    const context = createTemplateContext(event.payload);
+    const context = createTemplateContext(event.payload, {
+      event: { id: event.id, type: event.type, timestamp: event.timestamp, metadata: event.metadata },
+      automation: { id: automation.id }
+    });
     await this.queueExecution(automation, event, context, instanceId);
   }
   setupDebounceManager(automation) {
@@ -46525,28 +46608,35 @@ class AutomationEngine {
         logger4.warn("Debounce callback fired with empty messages array", { key });
         return;
       }
-      const context = createTemplateContext(lastMessage.payload, {
-        debounce: {
-          messages: messages2.map((m2) => ({
-            type: m2.type,
-            text: m2.text,
-            timestamp: m2.timestamp
-          })),
-          from,
-          instanceId
-        }
-      });
       const syntheticEvent = {
         id: generateId(),
         type: automation.triggerEventType,
         payload: lastMessage.payload,
         metadata: {
-          correlationId: generateId(),
+          correlationId: lastMessage.correlationId ?? generateId(),
           instanceId,
           ...stamp ? { envelopeVersion: stamp.envelopeVersion, tenantId: stamp.tenantId } : {}
         },
         timestamp: Date.now()
       };
+      const context = createTemplateContext(lastMessage.payload, {
+        debounce: {
+          messages: messages2.map((m2) => ({
+            type: m2.type,
+            text: m2.text,
+            timestamp: m2.timestamp
+          })),
+          from,
+          instanceId
+        },
+        event: {
+          id: lastMessage.eventId ?? syntheticEvent.id,
+          type: syntheticEvent.type,
+          timestamp: syntheticEvent.timestamp,
+          metadata: syntheticEvent.metadata
+        },
+        automation: { id: automation.id }
+      });
       await this.queueExecution(automation, syntheticEvent, context, instanceId);
     };
     const manager = new DebounceManager(automation.debounce, callback);
@@ -46634,7 +46724,10 @@ class AutomationEngine {
         await this.logExecution(result2, trustedTenantId);
         return result2;
       }
-      const actionsExecuted = await executeActions(automation.actions, context, this.deps, trustedTenantId);
+      const actionsExecuted = await runWithEventCausality({
+        correlationId: context.event?.metadata.correlationId ?? event.metadata.correlationId,
+        causationId: context.event?.id ?? event.id
+      }, () => executeActions(automation.actions, context, this.deps, trustedTenantId));
       const allSucceeded = actionsExecuted.every((a) => a.status === "success");
       const status = allSucceeded ? "success" : "failed";
       const result = {
@@ -46730,6 +46823,7 @@ function createAutomationEngine(config2) {
 }
 var logger4, QueueFullError;
 var init_engine = __esm(() => {
+  init_causality();
   init_envelope();
   init_ids();
   init_logger();
@@ -47118,6 +47212,113 @@ var init_automations = __esm(() => {
   init_sweeper();
 });
 
+// ../core/src/connectors/liveness.ts
+function latestConnectorSignal(row) {
+  let best = { at: row.createdAt, kind: "rearmed" };
+  const candidates = [
+    { at: row.livenessArmedAt, kind: "rearmed" },
+    { at: row.lastReceivedAt, kind: "event" },
+    { at: row.lastHeartbeatAt, kind: "heartbeat" }
+  ];
+  for (const candidate of candidates) {
+    if (candidate.at && candidate.at.getTime() >= best.at.getTime()) {
+      best = { at: candidate.at, kind: candidate.kind };
+    }
+  }
+  return best;
+}
+async function sweepConnectorLiveness(deps) {
+  const clock = deps.now ?? (() => new Date);
+  const now = clock();
+  const rows = await deps.repo.findSupervised();
+  const stats = { scanned: rows.length, stalled: 0, recovered: 0, errors: 0 };
+  for (const row of rows) {
+    try {
+      await processRow2(row, now, deps, stats);
+    } catch (err2) {
+      stats.errors += 1;
+      deps.logger.error("connector liveness: failed to process source", {
+        sourceId: row.id,
+        sourceName: row.name,
+        error: err2 instanceof Error ? err2.message : String(err2)
+      });
+    }
+  }
+  if (stats.stalled > 0 || stats.recovered > 0) {
+    deps.logger.info("connector liveness sweep tick", { ...stats });
+  }
+  return stats;
+}
+async function processRow2(row, now, deps, stats) {
+  const signal = latestConnectorSignal(row);
+  const silentMs = Math.max(0, now.getTime() - signal.at.getTime());
+  const overdue = silentMs > row.expectedIntervalSeconds * 1000;
+  const silentForSeconds = Math.round(silentMs / 1000);
+  if (overdue) {
+    if (row.livenessStatus === "stalled")
+      return;
+    if (!await deps.repo.markStalled(row.id, now))
+      return;
+    const payload = {
+      sourceId: row.id,
+      sourceName: row.name,
+      expectedIntervalSeconds: row.expectedIntervalSeconds,
+      lastReceivedAt: row.lastReceivedAt?.getTime() ?? null,
+      lastHeartbeatAt: row.lastHeartbeatAt?.getTime() ?? null,
+      silentForSeconds,
+      stalledAt: now.getTime()
+    };
+    const eventId = await publishTransition(deps, "system.connector.stalled", { ...payload }, row);
+    stats.stalled += 1;
+    await runHook(deps.logger, "onStalled", row, () => deps.onStalled?.(row, payload, eventId));
+    return;
+  }
+  if (row.livenessStatus === "stalled") {
+    if (!await deps.repo.markRecovered(row.id, now))
+      return;
+    const stalledSince = row.stalledAt ?? signal.at;
+    const payload = {
+      sourceId: row.id,
+      sourceName: row.name,
+      expectedIntervalSeconds: row.expectedIntervalSeconds,
+      stalledForSeconds: Math.max(0, Math.round((now.getTime() - stalledSince.getTime()) / 1000)),
+      recoveredBy: signal.kind,
+      recoveredAt: now.getTime()
+    };
+    await publishTransition(deps, "system.connector.recovered", { ...payload }, row);
+    stats.recovered += 1;
+    await runHook(deps.logger, "onRecovered", row, () => deps.onRecovered?.(row, payload));
+  }
+}
+async function publishTransition(deps, type, payload, row) {
+  if (!deps.eventBus) {
+    deps.logger.warn("connector liveness: no event bus, transition persisted without event", {
+      type,
+      sourceName: row.name
+    });
+    return null;
+  }
+  const result = await deps.eventBus.publishGeneric(type, payload, {
+    source: "connector-liveness",
+    ...row.tenantId ? { tenantId: row.tenantId } : {}
+  });
+  return result.id;
+}
+async function runHook(logger5, name, row, hook) {
+  try {
+    await hook();
+  } catch (err2) {
+    logger5.error(`connector liveness: ${name} hook failed`, {
+      sourceId: row.id,
+      sourceName: row.name,
+      error: err2 instanceof Error ? err2.message : String(err2)
+    });
+  }
+}
+
+// ../core/src/connectors/index.ts
+var init_connectors = () => {};
+
 // ../core/src/sessions/reset.ts
 class InMemorySessionActivityStore {
   activities = new Map;
@@ -74531,7 +74732,7 @@ function isProviderSchemaSupported(schema) {
 function getSupportedProviderSchemas() {
   return ["agno", "webhook", "openclaw", "claude-code", "ag-ui", "a2a", "nats-genie"];
 }
-var init_factory = __esm(() => {
+var init_factory2 = __esm(() => {
   init_a2a_client();
   init_ag_ui_client();
   init_agno_client();
@@ -74551,7 +74752,7 @@ var init_providers = __esm(() => {
   init_ag_ui_provider();
   init_a2a_provider();
   init_nats_genie_provider();
-  init_factory();
+  init_factory2();
 });
 
 // ../core/src/cache/types.ts
@@ -75220,6 +75421,7 @@ __export(exports_src, {
   tenantLabelBucketCount: () => tenantLabelBucketCount,
   tenantEventsProcessed: () => tenantEventsProcessed,
   sweepFollowUps: () => sweepFollowUps,
+  sweepConnectorLiveness: () => sweepConnectorLiveness,
   substituteTemplateObject: () => substituteTemplateObject,
   substituteTemplate: () => substituteTemplate,
   stampsEqual: () => stampsEqual,
@@ -75234,6 +75436,7 @@ __export(exports_src, {
   scheduledJobRuns: () => scheduledJobRuns,
   scheduledJobNextRun: () => scheduledJobNextRun,
   scheduledJobDuration: () => scheduledJobDuration,
+  runWithEventCausality: () => runWithEventCausality,
   rootLogger: () => rootLogger,
   resolveResetConfig: () => resolveResetConfig,
   resolvePublishTenantId: () => resolvePublishTenantId,
@@ -75282,6 +75485,7 @@ __export(exports_src, {
   natsConnectionStatus: () => natsConnectionStatus,
   matchesPattern: () => matchesPattern,
   markdownToWhatsApp: () => markdownToWhatsApp,
+  latestConnectorSignal: () => latestConnectorSignal,
   jsonEquals: () => jsonEquals,
   isValidUuid: () => isValidUuid,
   isValidJsonSchema: () => isValidJsonSchema,
@@ -75345,6 +75549,7 @@ __export(exports_src, {
   dbQueries: () => dbQueries,
   dbPoolSize: () => dbPoolSize,
   dbErrors: () => dbErrors,
+  currentEventCausality: () => currentEventCausality,
   createValidatedSubscription: () => createValidatedSubscription,
   createTemplateContext: () => createTemplateContext,
   createSubscription: () => createSubscription,
@@ -75607,6 +75812,7 @@ var init_src2 = __esm(() => {
   init_observability();
   init_secrets();
   init_automations();
+  init_connectors();
   init_reset();
   init_providers();
   init_cache();
@@ -80968,6 +81174,9 @@ __export(exports_schema, {
   conversations: () => conversations,
   contentTypes: () => contentTypes,
   consumerOffsets: () => consumerOffsets,
+  connectorWindowSemanticsValues: () => connectorWindowSemanticsValues,
+  connectorMutationPolicies: () => connectorMutationPolicies,
+  connectorLivenessStatuses: () => connectorLivenessStatuses,
   conditionOperators: () => conditionOperators,
   closeContactOutcomes: () => closeContactOutcomes,
   closeContactLogs: () => closeContactLogs,
@@ -81016,7 +81225,7 @@ __export(exports_schema, {
   accessRules: () => accessRules,
   accessModes: () => accessModes
 });
-var channelTypes, agentTypes, agentSystems, agentEntityTypes, debounceMode, splitDelayMode, supersedeMode, replyFilterMode, agentSessionStrategies, ruleTypes, accessModes, settingValueTypes, apiKeyStatuses, apiKeyProfiles, eventTypes, contentTypes, chatTypes, messageSources, messageTypes, messageStatuses, deliveryStatuses, scheduledMessageDeliveryModes, scheduledMessageStatuses, jobStatuses, providerSchemas, agentProviders, agents, agentRoutes, agentSessions, apiKeys, apiKeyAuditLogs, apiKeysRelations, apiKeyAuditLogsRelations, instances, whatsappTemplates, whatsappFlowKeys, scheduledMessages, persons, platformIdentities, conversations, chats, chatParticipants, omniGroups, messages2, omniEvents, handoffLogs, closeContactOutcomes, closeContactLogs, accessRules, globalSettings, settingChangeHistory, batchJobs, syncJobTypes, syncJobs, mediaContent, chatIdMappings, pluginStorage, agentProvidersRelations, agentsRelations, instancesRelations, syncJobsRelations, personsRelations, platformIdentitiesRelations, conversationsRelations, chatsRelations, chatParticipantsRelations, messagesRelations, omniEventsRelations, accessRulesRelations, globalSettingsRelations, settingChangeHistoryRelations, batchJobsRelations, mediaContentRelations, chatIdMappingsRelations, deadLetterStatuses, deadLetterEvents, payloadStorageConfig, payloadStages, eventPayloads, webhookSignatureAlgorithms, webhookSources, eventSchemas, conditionOperators, actionTypes, automationDebounceModes, automations2, automationLogStatuses, automationLogs, consumerOffsets, automationsRelations, automationLogsRelations, triggerLogs, triggerLogsRelations, agentRoutesRelations, agentTaskStatuses, agentTasks, agentTasksRelations, turnStatuses, turnActions, turns, turnsRelations, followUpDisarmReasons, chatFollowUpState, chatFollowUpStateRelations, processedEvents, genieHosts, tenantStatuses, principalTypes, principalStatuses, tenantRoles, membershipStatuses, credentialClasses, authCredentialStatuses, platformApiKeyStatuses, tenants, principals, tenantMemberships, tenantRolePolicies, platformApiKeys, tenantKeyLineage, authCredentials, tenantAuditLogs, platformAuditLogs, platformProviderCatalog, tenantProviderConfig, platformSettings, tenantSettings, platformSettingChangeHistory, tenantSettingChangeHistory, platformPluginStorage, tenantPluginStorage, platformPayloadStorageConfig, tenantPayloadStorageOverrides, tenantMigrationLedger, tenantMigrationLedgerHistory;
+var channelTypes, agentTypes, agentSystems, agentEntityTypes, debounceMode, splitDelayMode, supersedeMode, replyFilterMode, agentSessionStrategies, ruleTypes, accessModes, settingValueTypes, apiKeyStatuses, apiKeyProfiles, eventTypes, contentTypes, chatTypes, messageSources, messageTypes, messageStatuses, deliveryStatuses, scheduledMessageDeliveryModes, scheduledMessageStatuses, jobStatuses, providerSchemas, agentProviders, agents, agentRoutes, agentSessions, apiKeys, apiKeyAuditLogs, apiKeysRelations, apiKeyAuditLogsRelations, instances, whatsappTemplates, whatsappFlowKeys, scheduledMessages, persons, platformIdentities, conversations, chats, chatParticipants, omniGroups, messages2, omniEvents, handoffLogs, closeContactOutcomes, closeContactLogs, accessRules, globalSettings, settingChangeHistory, batchJobs, syncJobTypes, syncJobs, mediaContent, chatIdMappings, pluginStorage, agentProvidersRelations, agentsRelations, instancesRelations, syncJobsRelations, personsRelations, platformIdentitiesRelations, conversationsRelations, chatsRelations, chatParticipantsRelations, messagesRelations, omniEventsRelations, accessRulesRelations, globalSettingsRelations, settingChangeHistoryRelations, batchJobsRelations, mediaContentRelations, chatIdMappingsRelations, deadLetterStatuses, deadLetterEvents, payloadStorageConfig, payloadStages, eventPayloads, webhookSignatureAlgorithms, connectorLivenessStatuses, connectorWindowSemanticsValues, connectorMutationPolicies, webhookSources, eventSchemas, conditionOperators, actionTypes, automationDebounceModes, automations2, automationLogStatuses, automationLogs, consumerOffsets, automationsRelations, automationLogsRelations, triggerLogs, triggerLogsRelations, agentRoutesRelations, agentTaskStatuses, agentTasks, agentTasksRelations, turnStatuses, turnActions, turns, turnsRelations, followUpDisarmReasons, chatFollowUpState, chatFollowUpStateRelations, processedEvents, genieHosts, tenantStatuses, principalTypes, principalStatuses, tenantRoles, membershipStatuses, credentialClasses, authCredentialStatuses, platformApiKeyStatuses, tenants, principals, tenantMemberships, tenantRolePolicies, platformApiKeys, tenantKeyLineage, authCredentials, tenantAuditLogs, platformAuditLogs, platformProviderCatalog, tenantProviderConfig, platformSettings, tenantSettings, platformSettingChangeHistory, tenantSettingChangeHistory, platformPluginStorage, tenantPluginStorage, platformPayloadStorageConfig, tenantPayloadStorageOverrides, tenantMigrationLedger, tenantMigrationLedgerHistory;
 var init_schema2 = __esm(() => {
   init_events();
   init_types5();
@@ -81748,9 +81957,11 @@ var init_schema2 = __esm(() => {
     agentRequest: jsonb("agent_request").$type(),
     agentResponse: jsonb("agent_response").$type(),
     metadata: jsonb("metadata").$type(),
+    causationId: uuid("causation_id"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     tenantId: uuid("tenant_id").references(() => tenants.id, { onDelete: "restrict" })
   }, (table3) => ({
+    causationIdx: index("omni_events_causation_idx").on(table3.causationId),
     tenantIdx: index("omni_events_tenant_idx").on(table3.tenantId),
     tenantIdUq: uniqueIndex("omni_events_tenant_id_uq").on(table3.tenantId, table3.id),
     externalIdIdx: index("omni_events_external_id_idx").on(table3.externalId),
@@ -82229,6 +82440,9 @@ var init_schema2 = __esm(() => {
     eventStageIdx: index("event_payloads_event_stage_idx").on(table3.eventId, table3.stage)
   }));
   webhookSignatureAlgorithms = ["hmac-sha256", "hmac-sha1", "token-match"];
+  connectorLivenessStatuses = ["healthy", "stalled"];
+  connectorWindowSemanticsValues = ["future_only", "includes_in_progress"];
+  connectorMutationPolicies = ["same_id", "new_id"];
   webhookSources = pgTable("webhook_sources", {
     id: uuid("id").primaryKey().defaultRandom(),
     name: varchar("name", { length: 100 }).notNull().unique(),
@@ -82240,6 +82454,14 @@ var init_schema2 = __esm(() => {
     enabled: boolean2("enabled").notNull().default(true),
     lastReceivedAt: timestamp("last_received_at", { withTimezone: true }),
     totalReceived: integer("total_received").notNull().default(0),
+    expectedIntervalSeconds: integer("expected_interval_seconds"),
+    lastHeartbeatAt: timestamp("last_heartbeat_at", { withTimezone: true }),
+    heartbeatCount: integer("heartbeat_count").notNull().default(0),
+    livenessStatus: varchar("liveness_status", { length: 20 }).$type(),
+    livenessArmedAt: timestamp("liveness_armed_at", { withTimezone: true }),
+    stalledAt: timestamp("stalled_at", { withTimezone: true }),
+    windowSemantics: varchar("window_semantics", { length: 40 }).$type(),
+    mutationPolicy: varchar("mutation_policy", { length: 20 }).$type(),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
     tenantId: uuid("tenant_id").references(() => tenants.id, { onDelete: "restrict" })
@@ -82247,7 +82469,8 @@ var init_schema2 = __esm(() => {
     tenantIdx: index("webhook_sources_tenant_idx").on(table3.tenantId),
     tenantNameUq: uniqueIndex("webhook_sources_tenant_name_uq").on(table3.tenantId, table3.name).where(sql`${table3.tenantId} IS NOT NULL`),
     nameIdx: uniqueIndex("webhook_sources_name_idx").on(table3.name),
-    enabledIdx: index("webhook_sources_enabled_idx").on(table3.enabled)
+    enabledIdx: index("webhook_sources_enabled_idx").on(table3.enabled),
+    supervisedIdx: index("webhook_sources_supervised_idx").on(table3.enabled).where(sql`${table3.expectedIntervalSeconds} IS NOT NULL`)
   }));
   eventSchemas = pgTable("event_schemas", {
     id: uuid("id").primaryKey().defaultRandom(),
@@ -135302,6 +135525,13 @@ function createOmniClient(config) {
         const { data, error, response } = await client.POST("/events/trigger", { body });
         throwIfError(response, error);
         return data ?? { eventId: "", eventType: body.eventType };
+      },
+      async heartbeat(source) {
+        const { data, error, response } = await client.POST("/webhooks/{source}/heartbeat", {
+          params: { path: { source } }
+        });
+        throwIfError(response, error);
+        return data;
       }
     },
     payloads: {
@@ -136109,7 +136339,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "@automagik/omni",
-  version: "2.260906.2",
+  version: "2.260906.4",
   repository: {
     type: "git",
     url: "git+https://github.com/automagik-dev/omni.git",
@@ -142734,6 +142964,46 @@ ${title}:`);
   const items = Object.entries(record).sort(([, a], [, b2]) => b2 - a).map(([key, count]) => ({ [keyName]: key, count }));
   list(items);
 }
+async function fetchTrace(id) {
+  const config = loadConfig();
+  const baseUrl = config.apiUrl ?? "http://localhost:8882";
+  const resp = await fetch(`${baseUrl}/api/v2/events/${encodeURIComponent(id)}/trace`, {
+    headers: { "x-api-key": config.apiKey ?? "" }
+  });
+  if (!resp.ok) {
+    throw new Error(`API returned ${resp.status}: ${await resp.text()}`);
+  }
+  return (await resp.json()).data;
+}
+function formatTraceLine(event, marker) {
+  const time = new Date(event.receivedAt).toISOString().replace("T", " ").slice(0, 19);
+  const corr = event.metadata?.correlationId?.slice(0, 8) ?? "--------";
+  const text = event.textContent ? `  "${event.textContent.slice(0, 40)}"` : "";
+  return `${marker}${event.eventType}  ${event.id.slice(0, 8)}  ${time}  corr=${corr}${text}`;
+}
+function displayTrace(data2) {
+  if (getOutputFormat() === "json") {
+    data(data2);
+    return;
+  }
+  let indent = 0;
+  for (const ancestor of data2.ancestors) {
+    const label = indent === 0 && !ancestor.causationId ? " (root)" : "";
+    raw(`${"  ".repeat(indent)}${formatTraceLine(ancestor, indent === 0 ? "\u25CF " : "\u2514\u2500 ")}${label}`);
+    indent++;
+  }
+  const focusIsRoot = data2.ancestors.length === 0 && !data2.event.causationId;
+  raw(`${"  ".repeat(indent)}${formatTraceLine(data2.event, indent === 0 ? "\u25CF " : "\u2514\u2500 ")}${focusIsRoot ? " (root)" : ""}  \u2190 trace target`);
+  for (const { event, depth } of data2.descendants) {
+    raw(`${"  ".repeat(indent + depth)}${formatTraceLine(event, "\u2514\u2500 ")}`);
+  }
+  if (data2.descendants.length === 0) {
+    dim("(no descendants \u2014 nothing was caused by this event)");
+  }
+  if (data2.truncated) {
+    warn("Trace truncated (depth/node cap reached)");
+  }
+}
 async function schemaApiRequest(path, init = {}) {
   const config = loadConfig();
   const baseUrl = config.apiUrl ?? "http://localhost:8882";
@@ -142980,6 +143250,15 @@ function createEventsCommand() {
       error(`Failed to get event: ${message}`);
     }
   });
+  events.command("trace <id>").description("Walk the causality chain around an event: root \u2192 parents \u2192 this event \u2192 everything it caused").action(async (id) => {
+    try {
+      const data2 = await fetchTrace(id);
+      displayTrace(data2);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      error(`Failed to trace event: ${message}`);
+    }
+  });
   events.command("search <query>").description("Search events by content").option("--since <time>", "Events since (e.g., 24h, 7d)").option("--limit <n>", "Limit results", (v) => Number.parseInt(v, 10), 50).action(async (query, options) => {
     const client = getClient();
     try {
@@ -150609,6 +150888,53 @@ function assertPairedSignatureOnCreate(signatureConfig, signatureSecret) {
   }
   throw new Error(`--signature-algorithm and --signature-header require a signature secret (${SECRET_SOURCE_FLAGS})`);
 }
+var WINDOW_SEMANTICS = ["future_only", "includes_in_progress"];
+var MUTATION_POLICIES = ["same_id", "new_id"];
+function parseExpectedInterval(raw2) {
+  if (raw2 === undefined)
+    return;
+  const seconds = Number(raw2);
+  if (!Number.isInteger(seconds) || seconds < 1) {
+    error("--expected-interval must be a positive integer number of seconds");
+  }
+  return seconds;
+}
+function parseWindowSemantics(raw2) {
+  if (raw2 === undefined)
+    return;
+  const value = WINDOW_SEMANTICS.find((v4) => v4 === raw2);
+  if (!value) {
+    error(`Invalid --window-semantics; expected one of: ${WINDOW_SEMANTICS.join(", ")}`);
+  }
+  return value;
+}
+function parseMutationPolicy(raw2) {
+  if (raw2 === undefined)
+    return;
+  const value = MUTATION_POLICIES.find((v4) => v4 === raw2);
+  if (!value) {
+    error(`Invalid --mutation-policy; expected one of: ${MUTATION_POLICIES.join(", ")}`);
+  }
+  return value;
+}
+function buildLifecycleUpdates(options3) {
+  if (options3.clearCadence && options3.expectedInterval !== undefined) {
+    error("Use only one of --expected-interval and --clear-cadence");
+  }
+  const updates = {};
+  if (options3.clearCadence)
+    updates.expectedIntervalSeconds = null;
+  const expectedIntervalSeconds = parseExpectedInterval(options3.expectedInterval);
+  if (expectedIntervalSeconds !== undefined)
+    updates.expectedIntervalSeconds = expectedIntervalSeconds;
+  const windowSemantics = parseWindowSemantics(options3.windowSemantics);
+  if (windowSemantics !== undefined)
+    updates.windowSemantics = windowSemantics;
+  const mutationPolicy = parseMutationPolicy(options3.mutationPolicy);
+  if (mutationPolicy !== undefined)
+    updates.mutationPolicy = mutationPolicy;
+  return updates;
+}
 function createWebhooksCommand() {
   const webhooks = new Command("webhooks").description("Manage webhook sources");
   webhooks.command("list").description("List webhook sources").option("--enabled", "Show only enabled sources").option("--disabled", "Show only disabled sources").action(async (options3) => {
@@ -150626,6 +150952,8 @@ function createWebhooksCommand() {
         id: w.id,
         name: w.name,
         enabled: w.enabled ? "yes" : "no",
+        health: w.livenessStatus ?? "-",
+        cadence: w.expectedIntervalSeconds != null ? `${w.expectedIntervalSeconds}s` : "-",
         createdAt: w.createdAt
       }));
       list(items, { emptyMessage: "No webhook sources found." });
@@ -150645,7 +150973,7 @@ function createWebhooksCommand() {
       error(`Failed to get webhook source: ${message2}`);
     }
   });
-  webhooks.command("create").description("Create a webhook source").requiredOption("--name <name>", "Webhook source name").option("--description <desc>", "Description").option("--disabled", "Create in disabled state").option("--headers <json>", `Expected headers as JSON (e.g., '{"X-Secret": true}')`).option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only). Visible in shell history and process lists \u2014 prefer --signature-secret-env or --signature-secret-stdin").option("--signature-secret-env <VAR>", "Read the shared secret from environment variable VAR").option("--signature-secret-stdin", "Read the shared secret from stdin (trailing newline stripped)").action(async (options3) => {
+  webhooks.command("create").description("Create a webhook source").requiredOption("--name <name>", "Webhook source name").option("--description <desc>", "Description").option("--disabled", "Create in disabled state").option("--headers <json>", `Expected headers as JSON (e.g., '{"X-Secret": true}')`).option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only). Visible in shell history and process lists \u2014 prefer --signature-secret-env or --signature-secret-stdin").option("--signature-secret-env <VAR>", "Read the shared secret from environment variable VAR").option("--signature-secret-stdin", "Read the shared secret from stdin (trailing newline stripped)").option("--expected-interval <seconds>", "Declared cadence: >=1 event or heartbeat per N seconds. Arms liveness supervision (#961)").option("--window-semantics <value>", `Declared window semantics: ${WINDOW_SEMANTICS.join(" or ")}`).option("--mutation-policy <value>", `Declared mutation re-emit policy: ${MUTATION_POLICIES.join(" or ")}`).action(async (options3) => {
     const client = getClient();
     try {
       let expectedHeaders;
@@ -150665,7 +150993,10 @@ function createWebhooksCommand() {
         enabled: !options3.disabled,
         expectedHeaders,
         signatureConfig,
-        signatureSecret
+        signatureSecret,
+        expectedIntervalSeconds: parseExpectedInterval(options3.expectedInterval),
+        windowSemantics: parseWindowSemantics(options3.windowSemantics),
+        mutationPolicy: parseMutationPolicy(options3.mutationPolicy)
       });
       const details = {
         id: source.id,
@@ -150681,11 +151012,11 @@ function createWebhooksCommand() {
       error(`Failed to create webhook source: ${message2}`);
     }
   });
-  webhooks.command("update <id>").description("Update a webhook source").option("--name <name>", "New name").option("--description <desc>", "New description").option("--enable", "Enable the webhook").option("--disable", "Disable the webhook").option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only). Visible in shell history and process lists \u2014 prefer --signature-secret-env or --signature-secret-stdin").option("--signature-secret-env <VAR>", "Read the shared secret from environment variable VAR").option("--signature-secret-stdin", "Read the shared secret from stdin (trailing newline stripped)").option("--clear-signature", "Remove the signature config and stored secret").action(async (id, options3) => {
+  webhooks.command("update <id>").description("Update a webhook source").option("--name <name>", "New name").option("--description <desc>", "New description").option("--enable", "Enable the webhook").option("--disable", "Disable the webhook").option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only). Visible in shell history and process lists \u2014 prefer --signature-secret-env or --signature-secret-stdin").option("--signature-secret-env <VAR>", "Read the shared secret from environment variable VAR").option("--signature-secret-stdin", "Read the shared secret from stdin (trailing newline stripped)").option("--clear-signature", "Remove the signature config and stored secret").option("--expected-interval <seconds>", "Declared cadence: >=1 event or heartbeat per N seconds. (Re)arms liveness supervision (#961)").option("--clear-cadence", "Remove the declared cadence (disarms liveness supervision)").option("--window-semantics <value>", `Declared window semantics: ${WINDOW_SEMANTICS.join(" or ")}`).option("--mutation-policy <value>", `Declared mutation re-emit policy: ${MUTATION_POLICIES.join(" or ")}`).action(async (id, options3) => {
     const resolvedId = await resolveWebhookId(id);
     const client = getClient();
     try {
-      const updates = {};
+      const updates = buildLifecycleUpdates(options3);
       if (options3.name)
         updates.name = options3.name;
       if (options3.description)
@@ -150751,6 +151082,20 @@ function createWebhooksCommand() {
       error(`Failed to trigger event: ${message2}`);
     }
   });
+  webhooks.command("heartbeat <source>").description('Record a connector heartbeat ("ran, zero events found") \u2014 resets the liveness window (#961)').action(async (source) => {
+    const client = getClient();
+    try {
+      const result = await client.webhooks.heartbeat(source);
+      success(`Heartbeat recorded for '${result.source}'`, {
+        heartbeatAt: result.heartbeatAt,
+        livenessStatus: result.livenessStatus ?? "unsupervised",
+        expectedIntervalSeconds: result.expectedIntervalSeconds
+      });
+    } catch (err2) {
+      const message2 = err2 instanceof Error ? err2.message : "Unknown error";
+      error(`Failed to record heartbeat: ${message2}`);
+    }
+  });
   return webhooks;
 }