@automagik/omni 2.260906.2 → 2.260906.3

package/dist/server/index.js

@@ -22567,7 +22567,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({
@@ -38946,6 +38963,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;
@@ -43678,6 +43802,7 @@ __export(exports_src, {
   tenantLabelBucketCount: () => tenantLabelBucketCount,
   tenantEventsProcessed: () => tenantEventsProcessed,
   sweepFollowUps: () => sweepFollowUps,
+  sweepConnectorLiveness: () => sweepConnectorLiveness,
   substituteTemplateObject: () => substituteTemplateObject,
   substituteTemplate: () => substituteTemplate,
   stampsEqual: () => stampsEqual,
@@ -43740,6 +43865,7 @@ __export(exports_src, {
   natsConnectionStatus: () => natsConnectionStatus,
   matchesPattern: () => matchesPattern,
   markdownToWhatsApp: () => markdownToWhatsApp,
+  latestConnectorSignal: () => latestConnectorSignal,
   jsonEquals: () => jsonEquals,
   isValidUuid: () => isValidUuid,
   isValidJsonSchema: () => isValidJsonSchema,
@@ -44065,6 +44191,7 @@ var init_src = __esm(() => {
   init_observability();
   init_secrets();
   init_automations();
+  init_connectors();
   init_reset();
   init_providers();
   init_cache();
@@ -172164,6 +172291,9 @@ __export(exports_schema, {
   conversations: () => conversations,
   contentTypes: () => contentTypes,
   consumerOffsets: () => consumerOffsets,
+  connectorWindowSemanticsValues: () => connectorWindowSemanticsValues,
+  connectorMutationPolicies: () => connectorMutationPolicies,
+  connectorLivenessStatuses: () => connectorLivenessStatuses,
   conditionOperators: () => conditionOperators,
   closeContactOutcomes: () => closeContactOutcomes,
   closeContactLogs: () => closeContactLogs,
@@ -172212,7 +172342,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();
@@ -173425,6 +173555,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(),
@@ -173436,6 +173569,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" })
@@ -173443,7 +173584,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(),
@@ -177895,6 +178037,9 @@ __export(exports_src3, {
   conversations: () => conversations,
   contentTypes: () => contentTypes,
   consumerOffsets: () => consumerOffsets,
+  connectorWindowSemanticsValues: () => connectorWindowSemanticsValues,
+  connectorMutationPolicies: () => connectorMutationPolicies,
+  connectorLivenessStatuses: () => connectorLivenessStatuses,
   conditionOperators: () => conditionOperators,
   closeDb: () => closeDb,
   closeContactOutcomes: () => closeContactOutcomes,
@@ -250680,7 +250825,7 @@ var init_sentry_scrub = __esm(() => {
 var require_package7 = __commonJS((exports, module) => {
   module.exports = {
     name: "@omni/api",
-    version: "2.260906.2",
+    version: "2.260906.3",
     private: true,
     type: "module",
     exports: {
@@ -302543,6 +302688,7 @@ var init_route_ownership = __esm(() => {
     "POST /api/v2/voice/leave",
     "POST /api/v2/webhook-sources",
     "POST /api/v2/webhooks/:source",
+    "POST /api/v2/webhooks/:source/heartbeat",
     "PUT /api/v2/agent-state/:agentId/:chatId",
     "PUT /api/v2/follow-up/agents/:id",
     "PUT /api/v2/follow-up/chats/:id",
@@ -358067,6 +358213,9 @@ class DeadLetterService {
   }
   async create(options) {
     const insertData = prepareDeadLetterInsert(options);
+    if (options.autoRetry === false) {
+      insertData.nextAutoRetryAt = null;
+    }
     const [result] = await this.db.insert(deadLetterEvents).values(insertData).returning();
     if (!result) {
       throw new Error("Failed to create dead letter entry");
@@ -363201,7 +363350,10 @@ class WebhookService {
     if (data.signatureSecret && !data.signatureConfig) {
       throw new ValidationError2("signatureSecret cannot be set without a signatureConfig");
     }
-    const values2 = data.signatureSecret ? { ...data, signatureSecret: sealCredentialField(this.tenantId, data.signatureSecret) } : data;
+    let values2 = data.signatureSecret ? { ...data, signatureSecret: sealCredentialField(this.tenantId, data.signatureSecret) } : data;
+    if (values2.expectedIntervalSeconds != null) {
+      values2 = { ...values2, livenessArmedAt: new Date, livenessStatus: "healthy" };
+    }
     const [created] = await this.db.insert(webhookSources).values(values2).returning();
     if (!created) {
       throw new Error("Failed to create webhook source");
@@ -363227,12 +363379,28 @@ class WebhookService {
         patch.signatureSecret = null;
       }
     }
+    await this.applyLivenessArming(id, data, patch);
     const [updated] = await this.db.update(webhookSources).set({ ...patch, updatedAt: new Date }).where(eq(webhookSources.id, id)).returning();
     if (!updated) {
       throw new NotFoundError("WebhookSource", id);
     }
     return updated;
   }
+  async applyLivenessArming(id, data, patch) {
+    if (data.expectedIntervalSeconds === undefined)
+      return;
+    if (data.expectedIntervalSeconds === null) {
+      patch.livenessStatus = null;
+      patch.livenessArmedAt = null;
+      patch.stalledAt = null;
+      return;
+    }
+    patch.livenessArmedAt = new Date;
+    const existing = await this.getById(id);
+    if (existing.livenessStatus === null) {
+      patch.livenessStatus = "healthy";
+    }
+  }
   async delete(id) {
     const result = await this.db.delete(webhookSources).where(eq(webhookSources.id, id)).returning();
     if (!result.length) {
@@ -363360,6 +363528,101 @@ class WebhookService {
     }
     return { eventId, published: false };
   }
+  async heartbeat(sourceName) {
+    const source = await this.getByName(sourceName);
+    if (!source) {
+      throw new NotFoundError("WebhookSource", sourceName);
+    }
+    if (!source.enabled) {
+      throw new OmniError({
+        code: ERROR_CODES.FORBIDDEN,
+        message: `Webhook source '${sourceName}' is disabled`,
+        context: { sourceName }
+      });
+    }
+    const now = new Date;
+    await this.db.update(webhookSources).set({
+      lastHeartbeatAt: now,
+      heartbeatCount: sql`${webhookSources.heartbeatCount} + 1`,
+      updatedAt: now
+    }).where(eq(webhookSources.id, source.id));
+    return {
+      ok: true,
+      source: sourceName,
+      heartbeatAt: now.toISOString(),
+      livenessStatus: source.livenessStatus,
+      expectedIntervalSeconds: source.expectedIntervalSeconds
+    };
+  }
+  async sweepLiveness(options = {}) {
+    const { deadLetters } = options;
+    const hooks2 = deadLetters ? {
+      onStalled: (row, payload, publishedEventId) => fileStallDeadLetter(deadLetters, row, payload, publishedEventId),
+      onRecovered: (row) => resolveStallDeadLetters(deadLetters, row)
+    } : {};
+    return sweepConnectorLiveness({
+      repo: this.livenessRepo(),
+      eventBus: this.eventBus,
+      logger: log111,
+      ...hooks2
+    });
+  }
+  livenessRepo() {
+    return {
+      findSupervised: async () => {
+        const rows = await this.db.select().from(webhookSources).where(and2(eq(webhookSources.enabled, true), isNotNull(webhookSources.expectedIntervalSeconds)));
+        return rows.filter((row) => row.expectedIntervalSeconds !== null).map((row) => ({
+          id: row.id,
+          name: row.name,
+          expectedIntervalSeconds: row.expectedIntervalSeconds,
+          lastReceivedAt: row.lastReceivedAt,
+          lastHeartbeatAt: row.lastHeartbeatAt,
+          livenessArmedAt: row.livenessArmedAt,
+          livenessStatus: row.livenessStatus,
+          stalledAt: row.stalledAt,
+          createdAt: row.createdAt,
+          tenantId: row.tenantId
+        }));
+      },
+      markStalled: async (id, at) => {
+        const res = await this.db.update(webhookSources).set({ livenessStatus: "stalled", stalledAt: at, updatedAt: at }).where(and2(eq(webhookSources.id, id), sql`${webhookSources.livenessStatus} IS DISTINCT FROM 'stalled'`)).returning({ id: webhookSources.id });
+        return res.length > 0;
+      },
+      markRecovered: async (id, at) => {
+        const res = await this.db.update(webhookSources).set({ livenessStatus: "healthy", stalledAt: null, updatedAt: at }).where(and2(eq(webhookSources.id, id), eq(webhookSources.livenessStatus, "stalled"))).returning({ id: webhookSources.id });
+        return res.length > 0;
+      }
+    };
+  }
+}
+async function fileStallDeadLetter(deadLetters, row, payload, publishedEventId) {
+  const event = {
+    id: publishedEventId ?? generateId(),
+    type: "system.connector.stalled",
+    payload: { ...payload },
+    metadata: {
+      correlationId: generateId(),
+      source: "connector-liveness",
+      ...row.tenantId ? { tenantId: row.tenantId } : {}
+    },
+    timestamp: payload.stalledAt
+  };
+  await deadLetters.create({
+    event,
+    subject: "system.connector.stalled.internal.global",
+    error: new Error(`Connector '${row.name}' declared >=1 event or heartbeat per ${row.expectedIntervalSeconds}s ` + `but has been silent for ${payload.silentForSeconds}s`),
+    retryCount: 0,
+    autoRetry: false
+  });
+}
+async function resolveStallDeadLetters(deadLetters, row) {
+  const { items } = await deadLetters.list({ status: ["pending"], eventType: ["system.connector.stalled"] });
+  for (const entry of items) {
+    const stored = entry.payload;
+    if (stored.payload?.sourceId === row.id) {
+      await deadLetters.resolve(entry.id, "connector-liveness: recovered");
+    }
+  }
 }
 var log111;
 var init_webhooks = __esm(() => {
@@ -369789,6 +370052,7 @@ function registerWebhookSchemas(registry4) {
   registry4.register("CreateWebhookSourceRequest", CreateWebhookSourceSchema);
   registry4.register("TriggerEventRequest", TriggerEventSchema);
   registry4.register("WebhookReceiveResponse", WebhookReceiveResponseSchema);
+  registry4.register("WebhookHeartbeatResponse", WebhookHeartbeatResponseSchema);
   registry4.registerPath({
     method: "get",
     path: "/webhook-sources",
@@ -369887,6 +370151,25 @@ function registerWebhookSchemas(registry4) {
       400: { description: "Body is not a JSON object", content: { "application/json": { schema: ErrorSchema } } }
     }
   });
+  registry4.registerPath({
+    method: "post",
+    path: "/webhooks/{source}/heartbeat",
+    operationId: "heartbeatWebhookSource",
+    tags: ["Webhooks"],
+    summary: "Connector heartbeat",
+    description: 'Record a connector heartbeat: "I ran, zero events found". Resets the liveness window of a supervised ' + "source (one declaring expectedIntervalSeconds) so silence-beyond-window detection can tell quiet from " + "dead. Creates NO journal event \u2014 only the stalled/recovered transitions are journaled. No request body.",
+    request: {
+      params: exports_external.object({ source: exports_external.string().openapi({ description: "Source name" }) })
+    },
+    responses: {
+      200: {
+        description: "Heartbeat recorded",
+        content: { "application/json": { schema: WebhookHeartbeatResponseSchema } }
+      },
+      403: { description: "Source disabled", content: { "application/json": { schema: ErrorSchema } } },
+      404: { description: "Source not found", content: { "application/json": { schema: ErrorSchema } } }
+    }
+  });
   registry4.registerPath({
     method: "post",
     path: "/webhooks/ingress/{source}",
@@ -369925,7 +370208,7 @@ function registerWebhookSchemas(registry4) {
     }
   });
 }
-var WebhookSignatureConfigSchema, WebhookEventTypeMappingSchema, WebhookSourceSchema, CreateWebhookSourceSchema, TriggerEventSchema, WebhookReceiveResponseSchema;
+var WebhookSignatureConfigSchema, WebhookEventTypeMappingSchema, WebhookSourceSchema, CreateWebhookSourceSchema, WebhookHeartbeatResponseSchema, TriggerEventSchema, WebhookReceiveResponseSchema;
 var init_webhooks2 = __esm(() => {
   init_src5();
   init_zod_openapi();
@@ -369963,6 +370246,16 @@ var init_webhooks2 = __esm(() => {
     }),
     hasSignatureSecret: exports_external.boolean().openapi({ description: "Whether a signature secret is stored (secret is write-only)" }),
     enabled: exports_external.boolean().openapi({ description: "Whether enabled" }),
+    lastReceivedAt: exports_external.string().datetime().nullable().openapi({ description: "When the last webhook was received" }),
+    totalReceived: exports_external.number().int().openapi({ description: "Total webhooks received" }),
+    expectedIntervalSeconds: exports_external.number().int().nullable().openapi({ description: "Declared cadence: >=1 event or heartbeat per N seconds. Null = unsupervised" }),
+    lastHeartbeatAt: exports_external.string().datetime().nullable().openapi({ description: 'Last heartbeat ("ran, zero events")' }),
+    heartbeatCount: exports_external.number().int().openapi({ description: "Total heartbeats received" }),
+    livenessStatus: exports_external.enum(connectorLivenessStatuses).nullable().openapi({ description: "Liveness state; null = unsupervised. Transitions emit system.connector.* events" }),
+    livenessArmedAt: exports_external.string().datetime().nullable().openapi({ description: "When the cadence was (re)declared" }),
+    stalledAt: exports_external.string().datetime().nullable().openapi({ description: "When the current stall began" }),
+    windowSemantics: exports_external.enum(connectorWindowSemanticsValues).nullable().openapi({ description: "Declared window semantics; null = undeclared" }),
+    mutationPolicy: exports_external.enum(connectorMutationPolicies).nullable().openapi({ description: "Declared upstream-mutation re-emit policy; null = undeclared" }),
     createdAt: exports_external.string().datetime().openapi({ description: "Creation timestamp" }),
     updatedAt: exports_external.string().datetime().openapi({ description: "Last update timestamp" })
   });
@@ -369979,7 +370272,23 @@ var init_webhooks2 = __esm(() => {
     eventTypeMapping: WebhookEventTypeMappingSchema.nullable().optional().openapi({
       description: "Semantic event-type extraction (e.g. header X-GitHub-Event: push emits custom.{source}.push). " + "Null or absent keeps the legacy collapsed custom.webhook.{source} type for every delivery."
     }),
-    enabled: exports_external.boolean().default(true).openapi({ description: "Whether enabled" })
+    enabled: exports_external.boolean().default(true).openapi({ description: "Whether enabled" }),
+    expectedIntervalSeconds: exports_external.number().int().min(1).max(2592000).nullable().optional().openapi({
+      description: "Declared cadence: the connector promises >=1 event or heartbeat per N seconds (1s-30d). Declaring it " + "arms liveness supervision (silence beyond the window emits system.connector.stalled and marks the " + "source unhealthy); null disarms it."
+    }),
+    windowSemantics: exports_external.enum(connectorWindowSemanticsValues).nullable().optional().openapi({
+      description: "Declared time-window semantics: 'future_only' (only not-yet-started items) or 'includes_in_progress'. " + "Informational contract for consumers; null = undeclared."
+    }),
+    mutationPolicy: exports_external.enum(connectorMutationPolicies).nullable().optional().openapi({
+      description: "How the source re-emits a changed upstream item: 'same_id' (reschedule case \u2014 consumers must key on " + "id+content) or 'new_id'. Feeds the idempotency key template choice; null = undeclared."
+    })
+  });
+  WebhookHeartbeatResponseSchema = exports_external.object({
+    ok: exports_external.literal(true).openapi({ description: "Heartbeat recorded" }),
+    source: exports_external.string().openapi({ description: "Webhook source name" }),
+    heartbeatAt: exports_external.string().datetime().openapi({ description: "When the heartbeat was recorded" }),
+    livenessStatus: exports_external.enum(connectorLivenessStatuses).nullable().openapi({ description: "Status before this heartbeat (a stalled source recovers on the next sweep tick)" }),
+    expectedIntervalSeconds: exports_external.number().int().nullable().openapi({ description: "Declared cadence, if any" })
   });
   TriggerEventSchema = exports_external.object({
     eventType: exports_external.string().min(1).openapi({ description: "Event type (must start with custom.)" }),
@@ -382522,6 +382831,12 @@ var init_webhooks3 = __esm(() => {
     });
     return c.json(result);
   });
+  webhooksRoutes.post("/webhooks/:source/heartbeat", async (c) => {
+    const sourceName = c.req.param("source");
+    const services = c.get("services");
+    const result = await services.webhooks.heartbeat(sourceName);
+    return c.json(result);
+  });
   triggerEventSchema = exports_external.object({
     eventType: exports_external.string().min(1).refine((t) => t.startsWith("custom."), { message: 'Event type must start with "custom."' }).describe("Event type (must be custom.*)"),
     payload: exports_external.record(exports_external.string(), exports_external.unknown()).describe("Event payload"),
@@ -386672,6 +386987,26 @@ function setupScheduler(services, channelRegistry2) {
       });
     }
   });
+  scheduler.register({
+    name: "connector-liveness-sweeper",
+    cron: "*/30 * * * * *",
+    runOnStart: false,
+    handler: async () => {
+      await withCronMonitor("connector-liveness-sweeper", "*/30 * * * * *", 1, 1, async () => {
+        const startTime3 = Date.now();
+        try {
+          const stats = await services.webhooks.sweepLiveness({ deadLetters: services.deadLetters });
+          recordScheduledJob("connector-liveness-sweeper", "success", (Date.now() - startTime3) / 1000);
+          if (stats.stalled > 0 || stats.recovered > 0) {
+            log130.info("Connector liveness sweep tick", { ...stats });
+          }
+        } catch (err2) {
+          recordScheduledJob("connector-liveness-sweeper", "failure", (Date.now() - startTime3) / 1000);
+          throw err2;
+        }
+      });
+    }
+  });
   if (channelRegistry2) {
     const scheduledMessages2 = createScheduledMessageSweeper(services, channelRegistry2);
     scheduler.register({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automagik/omni",
-  "version": "2.260906.2",
+  "version": "2.260906.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/automagik-dev/omni.git",