@automagik/omni 2.260906.2 → 2.260906.3

package/db/drizzle/0057_connector_lifecycle_contract.sql

@@ -0,0 +1,40 @@
+-- Connector lifecycle contract (#961) — liveness, heartbeat, declared
+-- window/mutation semantics on webhook_sources.
+--
+-- A source that declares expected_interval_seconds promises "≥1 event or
+-- heartbeat per N seconds". The liveness sweeper compares the most recent
+-- signal — GREATEST(last_received_at, last_heartbeat_at, liveness_armed_at) —
+-- against that window and owns every liveness_status transition, so
+-- system.connector.stalled / system.connector.recovered are emitted exactly
+-- once per transition.
+--
+--   expected_interval_seconds  integer      declared cadence; NULL = unsupervised
+--   last_heartbeat_at          timestamptz  "I ran, zero events found" — the
+--                                           heartbeat verb's compacted trace
+--                                           (no journal event per heartbeat)
+--   heartbeat_count            integer      total heartbeats received
+--   liveness_status            varchar(20)  'healthy' | 'stalled'; NULL = unsupervised
+--   liveness_armed_at          timestamptz  when the cadence was (re)declared —
+--                                           a fresh window before a stall can fire
+--   stalled_at                 timestamptz  when the current stall began
+--   window_semantics           varchar(40)  'future_only' | 'includes_in_progress'
+--   mutation_policy            varchar(20)  'same_id' | 'new_id' (feeds #958's
+--                                           idempotency key template choice)
+--
+-- Hand-written following the 0044-0055 precedent (snapshot drift keeps
+-- drizzle-kit generate interactive). Additive + idempotent. No explicit
+-- BEGIN/COMMIT — the boot migrator executes this file on a pooled postgres-js
+-- connection, which rejects raw transaction control.
+
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "expected_interval_seconds" integer;
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "last_heartbeat_at" timestamp with time zone;
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "heartbeat_count" integer DEFAULT 0 NOT NULL;
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "liveness_status" varchar(20);
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "liveness_armed_at" timestamp with time zone;
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "stalled_at" timestamp with time zone;
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "window_semantics" varchar(40);
+ALTER TABLE "webhook_sources" ADD COLUMN IF NOT EXISTS "mutation_policy" varchar(20);
+
+-- The liveness sweeper's scan: enabled sources with a declared cadence.
+CREATE INDEX IF NOT EXISTS "webhook_sources_supervised_idx"
+  ON "webhook_sources" ("enabled") WHERE "expected_interval_seconds" IS NOT NULL;

package/db/drizzle/meta/_journal.json

@@ -400,6 +400,13 @@
       "when": 1785600000000,
       "tag": "0056_event_schema_registry",
       "breakpoints": true
+    },
+    {
+      "idx": 57,
+      "version": "7",
+      "when": 1785700000000,
+      "tag": "0057_connector_lifecycle_contract",
+      "breakpoints": true
     }
   ]
 }

package/dist/commands/webhooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/commands/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,UAAU,sBAAsB;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAcD;;;;;GAKG;AACH,iBAAe,sBAAsB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,MAAM,OAAO,CAAC,MAAM,CAAuB,GACrD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqC7B;AAED,6FAA6F;AAC7F,iBAAS,oBAAoB,CAAC,OAAO,EAAE;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,0BAA0B,GAAG,SAAS,CAczC;AAED;;;;;GAKG;AACH,iBAAS,6BAA6B,CACpC,eAAe,EAAE,0BAA0B,GAAG,SAAS,EACvD,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,IAAI,CAQN;AAED,wBAAgB,qBAAqB,IAAI,OAAO,CA2P/C;AAED,wDAAwD;AACxD,eAAO,MAAM,WAAW;;;;CAAkF,CAAC"}
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/commands/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,UAAU,sBAAsB;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAcD;;;;;GAKG;AACH,iBAAe,sBAAsB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,MAAM,OAAO,CAAC,MAAM,CAAuB,GACrD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqC7B;AAED,6FAA6F;AAC7F,iBAAS,oBAAoB,CAAC,OAAO,EAAE;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,0BAA0B,GAAG,SAAS,CAczC;AAED;;;;;GAKG;AACH,iBAAS,6BAA6B,CACpC,eAAe,EAAE,0BAA0B,GAAG,SAAS,EACvD,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,IAAI,CAQN;AA4DD,wBAAgB,qBAAqB,IAAI,OAAO,CA6S/C;AAED,wDAAwD;AACxD,eAAO,MAAM,WAAW;;;;CAAkF,CAAC"}

package/dist/index.js

@@ -30739,7 +30739,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({
@@ -47118,6 +47135,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;
@@ -75220,6 +75344,7 @@ __export(exports_src, {
   tenantLabelBucketCount: () => tenantLabelBucketCount,
   tenantEventsProcessed: () => tenantEventsProcessed,
   sweepFollowUps: () => sweepFollowUps,
+  sweepConnectorLiveness: () => sweepConnectorLiveness,
   substituteTemplateObject: () => substituteTemplateObject,
   substituteTemplate: () => substituteTemplate,
   stampsEqual: () => stampsEqual,
@@ -75282,6 +75407,7 @@ __export(exports_src, {
   natsConnectionStatus: () => natsConnectionStatus,
   matchesPattern: () => matchesPattern,
   markdownToWhatsApp: () => markdownToWhatsApp,
+  latestConnectorSignal: () => latestConnectorSignal,
   jsonEquals: () => jsonEquals,
   isValidUuid: () => isValidUuid,
   isValidJsonSchema: () => isValidJsonSchema,
@@ -75607,6 +75733,7 @@ var init_src2 = __esm(() => {
   init_observability();
   init_secrets();
   init_automations();
+  init_connectors();
   init_reset();
   init_providers();
   init_cache();
@@ -80968,6 +81095,9 @@ __export(exports_schema, {
   conversations: () => conversations,
   contentTypes: () => contentTypes,
   consumerOffsets: () => consumerOffsets,
+  connectorWindowSemanticsValues: () => connectorWindowSemanticsValues,
+  connectorMutationPolicies: () => connectorMutationPolicies,
+  connectorLivenessStatuses: () => connectorLivenessStatuses,
   conditionOperators: () => conditionOperators,
   closeContactOutcomes: () => closeContactOutcomes,
   closeContactLogs: () => closeContactLogs,
@@ -81016,7 +81146,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();
@@ -82229,6 +82359,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 +82373,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 +82388,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 +135444,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 +136258,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "@automagik/omni",
-  version: "2.260906.2",
+  version: "2.260906.3",
   repository: {
     type: "git",
     url: "git+https://github.com/automagik-dev/omni.git",
@@ -150609,6 +150758,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 +150822,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 +150843,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 +150863,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 +150882,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 +150952,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;
 }
 

package/dist/sdk/client.d.ts

@@ -663,7 +663,22 @@ export interface CreateWebhookSourceBody {
     signatureSecret?: string | null;
     /** Defaults to true server-side */
     enabled?: boolean;
+    /**
+     * Connector lifecycle contract (#961): declared cadence — the connector
+     * promises >=1 event or heartbeat per N seconds (1s-30d). Declaring it arms
+     * liveness supervision; null disarms it.
+     */
+    expectedIntervalSeconds?: number | null;
+    /** Declared window semantics; null = undeclared. */
+    windowSemantics?: 'future_only' | 'includes_in_progress' | null;
+    /** Declared upstream-mutation re-emit policy; null = undeclared. */
+    mutationPolicy?: 'same_id' | 'new_id' | null;
 }
+/**
+ * Response of the connector heartbeat verb (#961).
+ * Derived from the generated OpenAPI component so it cannot drift from the API.
+ */
+export type WebhookHeartbeatResponse = components['schemas']['WebhookHeartbeatResponse'];
 /**
  * Body for triggering a custom event
  */
@@ -1869,6 +1884,12 @@ export declare function createOmniClient(config: OmniClientConfig): {
             eventId: string;
             eventType: string;
         }>;
+        /**
+         * Record a connector heartbeat: "I ran, zero events found" (#961).
+         * Resets the source's liveness window without creating a journal event.
+         * Keyed on the source NAME (like the receiver), not the id.
+         */
+        heartbeat(source: string): Promise<WebhookHeartbeatResponse>;
     };
     /**
      * Payload management