@hogsend/engine 0.23.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.23.1",
-    "@hogsend/db": "^0.23.1",
-    "@hogsend/email": "^0.23.1",
-    "@hogsend/plugin-posthog": "^0.23.1",
-    "@hogsend/plugin-resend": "^0.23.1"
+    "@hogsend/core": "^0.25.0",
+    "@hogsend/db": "^0.25.0",
+    "@hogsend/email": "^0.25.0",
+    "@hogsend/plugin-posthog": "^0.25.0",
+    "@hogsend/plugin-resend": "^0.25.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.23.1"
+    "@hogsend/plugin-postmark": "^0.25.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/connectors/action-registry-singleton.ts

@@ -0,0 +1,52 @@
+import type { DefinedConnectorAction } from "./define-action.js";
+
+/**
+ * The process-wide connector-action registry, set once by `createHogsendClient`.
+ * Mirrors {@link ConnectorRegistry}: keyed by `${connectorId}:${name}`,
+ * last-writer-wins, with a lazy empty fallback so a self-booting context (the
+ * standalone {@link sendConnectorAction}) resolves cleanly even before any
+ * container ran (it just finds no actions).
+ */
+export class ConnectorActionRegistry {
+  private readonly byKey = new Map<string, DefinedConnectorAction>();
+
+  constructor(actions: DefinedConnectorAction[] = []) {
+    for (const action of actions) this.register(action);
+  }
+
+  register(action: DefinedConnectorAction): void {
+    this.byKey.set(`${action.connectorId}:${action.name}`, action);
+  }
+
+  get(connectorId: string, name: string): DefinedConnectorAction | undefined {
+    return this.byKey.get(`${connectorId}:${name}`);
+  }
+
+  getAll(): DefinedConnectorAction[] {
+    return [...this.byKey.values()];
+  }
+
+  count(): number {
+    return this.byKey.size;
+  }
+}
+
+let installed: ConnectorActionRegistry | undefined;
+let fallback: ConnectorActionRegistry | undefined;
+
+export function setConnectorActionRegistry(
+  registry: ConnectorActionRegistry,
+): void {
+  installed = registry;
+}
+
+export function getConnectorActionRegistry(): ConnectorActionRegistry {
+  if (installed) return installed;
+  if (!fallback) fallback = new ConnectorActionRegistry();
+  return fallback;
+}
+
+/** Reset the installed registry — only for test cleanup. */
+export function resetConnectorActionRegistry(): void {
+  installed = undefined;
+}

package/src/connectors/define-action.ts

@@ -0,0 +1,55 @@
+import type { Database } from "@hogsend/db";
+import type { Logger } from "../lib/logger.js";
+
+/**
+ * Connector OUTBOUND ACTIONS — the journey-callable, socket-free face of a
+ * connector. Distinct from event fan-out (the durable `emitOutbound` →
+ * destination spine): an action is an IMPERATIVE call a journey/workflow makes
+ * ("post this to #general", "@mention these members", "DM this user"). On
+ * Discord these are pure bot-REST calls needing only the bot token — so they run
+ * on ANY replica and are INDEPENDENT of the inbound gateway socket (a deployment
+ * with the gateway off can still send).
+ *
+ * A platform plugin contributes actions (e.g. `discordActions`); the consumer
+ * registers them via `createHogsendClient({ connectorActions })`. A journey
+ * invokes one through the standalone {@link sendConnectorAction} export (NOT on
+ * `ctx` — features are standalone imports, mirroring `sendEmail()`).
+ */
+/** A contact resolved for an outbound action — a platform-neutral projection. */
+export interface ResolvedActionContact {
+  id: string;
+  email: string | null;
+  discordId: string | null;
+  externalId: string | null;
+  properties: Record<string, unknown>;
+}
+
+export interface ConnectorActionCtx {
+  db: Database;
+  logger: Logger;
+  /**
+   * Resolve a contact by email, external id, or a platform id (e.g. a Discord
+   * snowflake). The engine owns the contacts schema, so a plugin action resolves
+   * a recipient WITHOUT coupling to `@hogsend/db`. Null when no live contact
+   * matches.
+   */
+  resolveContact(ref: string): Promise<ResolvedActionContact | null>;
+}
+
+export interface DefinedConnectorAction<A = unknown, R = unknown> {
+  /** The connector this action belongs to (e.g. "discord"). Keys the registry. */
+  connectorId: string;
+  /** Action name, unique within the connector (e.g. "sendChannelMessage"). */
+  name: string;
+  /** Optional human description (Studio enumeration / docs). */
+  description?: string;
+  /** Perform the outbound action. Single-object-in, result-out. */
+  run(args: A, ctx: ConnectorActionCtx): Promise<R>;
+}
+
+/** Identity/validating authoring helper (mirrors `defineConnector`/`defineDestination`). */
+export function defineConnectorAction<A, R>(
+  def: DefinedConnectorAction<A, R>,
+): DefinedConnectorAction<A, R> {
+  return def;
+}

package/src/connectors/runtime.ts

@@ -0,0 +1,291 @@
+import type { HogsendClient } from "../container.js";
+import {
+  type ConnectorHeartbeatHandle,
+  startConnectorHeartbeat,
+} from "../lib/connector-heartbeat.js";
+import { ingestEvent } from "../lib/ingestion.js";
+import {
+  acquireLeaderLease,
+  newLeaseToken,
+  releaseLeaderLease,
+  renewLeaderLease,
+} from "../lib/leader-lease.js";
+import type { Logger } from "../lib/logger.js";
+import type { DefinedConnector } from "./define-connector.js";
+
+/**
+ * The connector-agnostic INBOUND RUNTIME seam. A `gateway`-transport connector
+ * (Discord today, Slack tomorrow) needs a long-lived process holding a socket to
+ * the platform. Rather than a hand-wired standalone service per consumer, the
+ * engine boots that runtime INLINE inside the process every consumer already
+ * runs (the Hatchet worker by default), gated by a Redis LEADER LEASE so exactly
+ * ONE replica ever holds the socket — one bot token permits one live session.
+ *
+ * A platform plugin contributes a {@link ConnectorRuntimeFactory} (supplied to
+ * `createWorker({ connectorRuntimes })`); the engine owns everything
+ * platform-neutral: lease election, the in-process dispatch→transform→ingest
+ * sink (no HTTP hop, no shared secret), the owned heartbeat, and shutdown
+ * ordering. A second connector reuses this verbatim — it only writes a
+ * `defineConnector` + a runtime factory, and touches zero engine code.
+ */
+
+/** The minimal long-lived runtime a platform plugin supplies (e.g. a discord.js socket). */
+export interface ConnectorRuntime {
+  /** Open the socket. Rejects loudly on a fatal config error (bad token/intents). */
+  start(): Promise<void>;
+  /** Close the socket and clear timers (awaited on demotion / shutdown). */
+  stop(): Promise<void>;
+  /** Platform metadata to fold into the heartbeat (e.g. `{ intents }`). */
+  getMetadata(): Record<string, unknown>;
+}
+
+/**
+ * What the engine injects into a runtime factory. `ingest` is the in-process
+ * sink: hand it a raw platform dispatch and the engine runs the connector's own
+ * `transform` then `ingestEvent` — the EXACT pair the HTTP ingress route runs,
+ * minus the network hop. `onMetadata` folds a late-observed field (e.g. the
+ * guild id seen at GUILD_CREATE) into the live heartbeat.
+ */
+export interface ConnectorRuntimeDeps {
+  ingest(
+    dispatchType: string,
+    data: unknown,
+  ): Promise<{ ok: boolean; status: number }>;
+  onMetadata(patch: Record<string, unknown>): void;
+  logger: Logger;
+}
+
+/**
+ * Build a runtime for a connector, or return `null` when it is not configured to
+ * run here (e.g. the platform's bot token env is unset) — the engine then simply
+ * skips it without holding a lease.
+ */
+export type ConnectorRuntimeFactory = (
+  deps: ConnectorRuntimeDeps,
+) => ConnectorRuntime | null;
+
+export interface ConnectorRuntimesHandle {
+  /** Release every lease + delete heartbeats BEFORE stopping sockets. */
+  stop(): Promise<void>;
+}
+
+const LEASE_TTL_MS = 30_000;
+const RENEW_MS = 10_000;
+const ELECT_MS = 5_000;
+
+/** Build the in-process dispatch→transform→ingest sink for one connector. */
+function makeIngest(client: HogsendClient, connector: DefinedConnector) {
+  return async (
+    dispatchType: string,
+    data: unknown,
+  ): Promise<{ ok: boolean; status: number }> => {
+    try {
+      // Reconstruct the EXACT envelope the HTTP ingress route receives
+      // (`{ __t, d }`) so the connector transform is byte-identical whether the
+      // dispatch arrived over HTTP or in-process.
+      const payload = { __t: dispatchType, d: data };
+      const event = await connector.transform(payload, {
+        db: client.db,
+        logger: client.logger,
+        transport: "gateway",
+      });
+      if (!event) return { ok: true, status: 200 };
+      await ingestEvent({
+        db: client.db,
+        registry: client.registry,
+        hatchet: client.hatchet,
+        logger: client.logger,
+        event,
+        // Pass the active analytics provider so a Discord-keyed contact merge
+        // stitches the analytics person too (the HTTP route omits this; in-proc
+        // can do better since it already holds the container).
+        analytics: client.analytics,
+      });
+      return { ok: true, status: 200 };
+    } catch (err) {
+      client.logger.warn("Connector runtime in-process ingest failed", {
+        connectorId: connector.meta.id,
+        dispatchType,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return { ok: false, status: 500 };
+    }
+  };
+}
+
+/**
+ * Per-connector lease controller: a single timer loop that races for the lease,
+ * starts the runtime + heartbeat on a win, renews while it leads, and demotes
+ * (stop socket + heartbeat) the moment a renew is lost — then re-enters the
+ * race, giving bounded automatic failover within the TTL with no two-holder
+ * overlap.
+ */
+function startController(
+  client: HogsendClient,
+  connector: DefinedConnector,
+  factory: ConnectorRuntimeFactory,
+): ConnectorRuntimesHandle | null {
+  const { logger } = client;
+  const connectorId = connector.meta.id;
+  const leaseKey = `hogsend:connector-runtime:${connectorId}:leader`;
+
+  let heartbeat: ConnectorHeartbeatHandle | undefined;
+
+  const runtime = factory({
+    ingest: makeIngest(client, connector),
+    onMetadata: (patch) => heartbeat?.state.setMetadata(patch),
+    logger,
+  });
+  // `null` ⇒ not configured to run here (e.g. no bot token). Skip cleanly — no
+  // lease held, no heartbeat written, dashboard stays Offline (truthfully).
+  if (!runtime) {
+    logger.debug("Connector runtime not configured; skipping", { connectorId });
+    return null;
+  }
+  // Non-null alias the hoisted closures below capture (a const keeps TS's
+  // post-guard narrowing; the bare `runtime` widens back to `| null` inside
+  // them).
+  const rt = runtime;
+
+  let leading = false;
+  let token = "";
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  /** Drop leadership: heartbeat key deleted FIRST (immediate Offline), then socket. */
+  async function demote(): Promise<void> {
+    leading = false;
+    await heartbeat?.stop();
+    heartbeat = undefined;
+    try {
+      await rt.stop();
+    } catch (err) {
+      logger.warn("Connector runtime stop failed during demotion", {
+        connectorId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  async function tick(): Promise<void> {
+    if (stopped) return;
+    try {
+      if (!leading) {
+        token = newLeaseToken();
+        const won = await acquireLeaderLease({
+          key: leaseKey,
+          token,
+          ttlMs: LEASE_TTL_MS,
+        });
+        if (won) {
+          leading = true;
+          heartbeat = startConnectorHeartbeat(connectorId, logger);
+          heartbeat.state.setMetadata(rt.getMetadata());
+          logger.info("Connector runtime acquired lease; opening socket", {
+            connectorId,
+          });
+          try {
+            await rt.start();
+          } catch (err) {
+            // A fatal start (bad token / disallowed intents) — release the lease
+            // so another replica (or a fixed redeploy) can try, and surface it.
+            logger.error("Connector runtime failed to start; releasing lease", {
+              connectorId,
+              error: err instanceof Error ? err.message : String(err),
+            });
+            await heartbeat.stop();
+            heartbeat = undefined;
+            leading = false;
+            await releaseLeaderLease({ key: leaseKey, token });
+          }
+        }
+      } else {
+        const renewed = await renewLeaderLease({
+          key: leaseKey,
+          token,
+          ttlMs: LEASE_TTL_MS,
+        });
+        if (!renewed) {
+          logger.warn("Connector runtime lost lease; demoting", {
+            connectorId,
+          });
+          await demote();
+        }
+      }
+    } catch (err) {
+      logger.warn("Connector runtime election tick failed", {
+        connectorId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      if (!stopped) {
+        timer = setTimeout(() => void tick(), leading ? RENEW_MS : ELECT_MS);
+        timer.unref?.();
+      }
+    }
+  }
+
+  void tick();
+
+  return {
+    async stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      if (leading) {
+        await demote();
+        await releaseLeaderLease({ key: leaseKey, token });
+      }
+    },
+  };
+}
+
+export interface StartConnectorRuntimesArgs {
+  client: HogsendClient;
+  /** Platform runtime factories keyed by connector id (from createWorker opts). */
+  factories: Record<string, ConnectorRuntimeFactory>;
+}
+
+/**
+ * Boot the inline runtimes for every registered `gateway`-transport connector
+ * that has a supplied factory. Fire-and-forget per connector (each runs its own
+ * lease loop); returns a handle whose `stop()` releases all leases + deletes
+ * heartbeats before stopping sockets (graceful, heartbeat-first ordering).
+ *
+ * No-ops cleanly when there are no gateway connectors, no factories, or a
+ * factory declines (returns null) — so a deploy with nothing configured carries
+ * zero cost.
+ */
+export function startConnectorRuntimes(
+  args: StartConnectorRuntimesArgs,
+): ConnectorRuntimesHandle {
+  const { client, factories } = args;
+  const gateways = client.connectorRegistry.getByTransport("gateway");
+  const controllers: ConnectorRuntimesHandle[] = [];
+
+  for (const connector of gateways) {
+    const factory = factories[connector.meta.id];
+    if (!factory) {
+      client.logger.debug(
+        "Gateway connector has no runtime factory; skipping",
+        {
+          connectorId: connector.meta.id,
+        },
+      );
+      continue;
+    }
+    const controller = startController(client, connector, factory);
+    if (controller) controllers.push(controller);
+  }
+
+  if (controllers.length > 0) {
+    client.logger.info("Connector runtimes started", {
+      count: controllers.length,
+    });
+  }
+
+  return {
+    async stop() {
+      await Promise.allSettled(controllers.map((c) => c.stop()));
+    },
+  };
+}

package/src/container.ts

@@ -20,6 +20,11 @@ import {
   buildBucketRegistry,
   collectBucketReactionJourneys,
 } from "./buckets/registry.js";
+import {
+  ConnectorActionRegistry,
+  setConnectorActionRegistry,
+} from "./connectors/action-registry-singleton.js";
+import type { DefinedConnectorAction } from "./connectors/define-action.js";
 import type { DefinedConnector } from "./connectors/define-connector.js";
 import { connectorsFromEnv } from "./connectors/presets/index.js";
 import {
@@ -161,6 +166,13 @@ export interface HogsendClient {
    * `/v1/connectors/:id/*` routes read `get(id).handlers`.
    */
   connectorRegistry: ConnectorRegistry;
+  /**
+   * The connector OUTBOUND ACTION registry, keyed by `${connectorId}:${name}`.
+   * Holds the journey-callable imperative actions (Discord post / broadcast /
+   * mention / DM) the standalone `sendConnectorAction()` resolves. Socket-free —
+   * independent of any inbound gateway runtime. Empty when none are wired.
+   */
+  connectorActionRegistry: ConnectorActionRegistry;
   hatchet: HatchetClient;
   /**
    * The client repo's migration journal (`migrations/meta/_journal.json`),
@@ -281,6 +293,14 @@ export interface HogsendClientOptions {
    * connectors. Defaults to none.
    */
   connectors?: DefinedConnector[];
+  /**
+   * Connector OUTBOUND ACTIONS (e.g. `discordActions` from `@hogsend/plugin-discord`)
+   * — journey-callable imperative actions registered into the
+   * {@link ConnectorActionRegistry} and invoked via the standalone
+   * `sendConnectorAction()`. Socket-free; independent of any inbound gateway
+   * runtime. Defaults to none.
+   */
+  connectorActions?: DefinedConnectorAction[];
   /**
    * @deprecated pass `connectors` instead. Back-compat array of
    * `defineWebhookSource()` sources; converted to webhook-transport connectors.
@@ -679,6 +699,15 @@ export function createHogsendClient(
     `Connector registry loaded: ${connectorRegistry.count()} connectors`,
   );
 
+  // Build + install the connector ACTION registry (outbound imperative actions),
+  // the action sibling of the connector registry above. Runs in BOTH the API and
+  // worker (both call createHogsendClient), so `sendConnectorAction()` resolves
+  // in either process.
+  const connectorActionRegistry = new ConnectorActionRegistry(
+    opts.connectorActions ?? [],
+  );
+  setConnectorActionRegistry(connectorActionRegistry);
+
   // Optional: auto-seed a PostHog DESTINATION on the outbound spine so the email
   // lifecycle fans out to PostHog durably. Default OFF (ENABLE_POSTHOG_DESTINATION)
   // to avoid double-emit alongside the fire-and-forget capture path. Idempotent +
@@ -725,6 +754,7 @@ export function createHogsendClient(
     bucketRegistry,
     listRegistry,
     connectorRegistry,
+    connectorActionRegistry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
     defaults,

package/src/env.ts

@@ -207,6 +207,19 @@ export const env = createEnv({
     // (the route 401s), so a gateway worker cannot relay without it. MUST be
     // high-entropy — generate with `openssl rand -base64 32`.
     CONNECTOR_INGRESS_SECRET: z.string().min(32).optional(),
+    // --- Connector runtimes (inline gateway sockets) ---
+    // The long-lived inbound socket for gateway-transport connectors (Discord)
+    // runs INLINE inside the host process below, gated by a Redis leader lease so
+    // exactly ONE replica holds it. Auto-on: a registered gateway connector +
+    // its bot token present is enough. Enum (not z.coerce.boolean) so an explicit
+    // "false" actually disables it (z.coerce.boolean treats "false" as true).
+    ENABLE_CONNECTOR_RUNTIMES: z.enum(["true", "false"]).default("true"),
+    // Which already-deployed process hosts the inline runtime. "worker" (default)
+    // is the committed home; "standalone" defers to the advanced discord-worker
+    // entry; "api" is reserved (host it yourself via startConnectorRuntimes).
+    CONNECTOR_RUNTIME_HOST: z
+      .enum(["worker", "api", "standalone"])
+      .default("worker"),
     // --- Outbound destination presets (Phase 3) ---
     // Which `defineDestination()` PRESETS are registered into the process
     // destination registry the delivery task resolves by `endpoint.kind`. csv of

package/src/index.ts

@@ -91,6 +91,18 @@ export {
   resetBucketRegistry,
   setBucketRegistry,
 } from "./buckets/registry-singleton.js";
+export {
+  ConnectorActionRegistry,
+  getConnectorActionRegistry,
+  resetConnectorActionRegistry,
+  setConnectorActionRegistry,
+} from "./connectors/action-registry-singleton.js";
+export {
+  type ConnectorActionCtx,
+  type DefinedConnectorAction,
+  defineConnectorAction,
+  type ResolvedActionContact,
+} from "./connectors/define-action.js";
 // --- Inbound connectors: unified authoring layer ---
 export {
   type ConnectorCtx,
@@ -115,6 +127,13 @@ export {
   resetConnectorRegistry,
   setConnectorRegistry,
 } from "./connectors/registry-singleton.js";
+export {
+  type ConnectorRuntime,
+  type ConnectorRuntimeDeps,
+  type ConnectorRuntimeFactory,
+  type ConnectorRuntimesHandle,
+  startConnectorRuntimes,
+} from "./connectors/runtime.js";
 export {
   createHogsendClient,
   type HogsendClient,
@@ -201,6 +220,18 @@ export {
   type BucketTransitionSource,
   emitBucketTransition,
 } from "./lib/bucket-emit.js";
+// --- Connector outbound actions (journey-callable, socket-free) ---
+export {
+  type SendConnectorActionArgs,
+  sendConnectorAction,
+} from "./lib/connector-actions.js";
+// --- Connector-runtime liveness heartbeat (connector-neutral) ---
+export {
+  type ConnectorHeartbeat,
+  type ConnectorHeartbeatHandle,
+  getConnectorHeartbeat,
+  startConnectorHeartbeat,
+} from "./lib/connector-heartbeat.js";
 // --- Single-use link codes (native connector /link → /verify identify loop) ---
 export {
   type CreateLinkCodeResult,
@@ -289,6 +320,13 @@ export {
   type IngestResult,
   ingestEvent,
 } from "./lib/ingestion.js";
+// --- Leader lease (connector-runtime singleton election) ---
+export {
+  acquireLeaderLease,
+  newLeaseToken,
+  releaseLeaderLease,
+  renewLeaderLease,
+} from "./lib/leader-lease.js";
 // --- Logging ---
 export { createLogger, type Logger } from "./lib/logger.js";
 export { createTrackedMailer } from "./lib/mailer.js";

package/src/journeys/journey-context.ts

@@ -21,6 +21,7 @@ import {
 import type {
   IfPast,
   JourneyContext,
+  RecentEvent,
   TimeOfDayBuilder,
   WaitForEventResult,
   Weekday,
@@ -451,6 +452,36 @@ export function createJourneyContext(
           count: total,
         };
       },
+
+      async events({
+        userId: targetUserId,
+        limit = 50,
+        within,
+      }): Promise<RecentEvent[]> {
+        const conditions = [eq(userEvents.userId, targetUserId)];
+        if (within) {
+          const since = new Date(Date.now() - durationToMs(within));
+          conditions.push(gte(userEvents.occurredAt, since));
+        }
+        const rows = await db
+          .select({
+            event: userEvents.event,
+            properties: userEvents.properties,
+            occurredAt: userEvents.occurredAt,
+          })
+          .from(userEvents)
+          .where(and(...conditions))
+          .orderBy(desc(userEvents.occurredAt))
+          .limit(limit);
+        return rows.map((row) => ({
+          event: row.event,
+          properties: row.properties ?? null,
+          occurredAt:
+            row.occurredAt instanceof Date
+              ? row.occurredAt.toISOString()
+              : String(row.occurredAt),
+        }));
+      },
     },
   };
 }

package/src/lib/connector-actions.ts

@@ -0,0 +1,90 @@
+import { contacts, type Database } from "@hogsend/db";
+import { and, eq, isNull, or } from "drizzle-orm";
+import { getConnectorActionRegistry } from "../connectors/action-registry-singleton.js";
+import type { ResolvedActionContact } from "../connectors/define-action.js";
+import { env } from "../env.js";
+import { getDb } from "./db.js";
+import { createLogger } from "./logger.js";
+
+/**
+ * Resolve a contact for an outbound action by email, external id, or a platform
+ * id (e.g. a Discord snowflake). Matches text columns only (NOT the uuid `id`,
+ * which would force an invalid-uuid cast error for an email ref). First live
+ * match wins.
+ */
+async function resolveContact(
+  db: Database,
+  ref: string,
+): Promise<ResolvedActionContact | null> {
+  if (!ref) return null;
+  const rows = await db
+    .select({
+      id: contacts.id,
+      email: contacts.email,
+      discordId: contacts.discordId,
+      externalId: contacts.externalId,
+      properties: contacts.properties,
+    })
+    .from(contacts)
+    .where(
+      and(
+        isNull(contacts.deletedAt),
+        or(
+          eq(contacts.email, ref),
+          eq(contacts.externalId, ref),
+          eq(contacts.discordId, ref),
+        ),
+      ),
+    )
+    .limit(1);
+  const row = rows[0];
+  if (!row) return null;
+  return {
+    id: row.id,
+    email: row.email ?? null,
+    discordId: row.discordId ?? null,
+    externalId: row.externalId ?? null,
+    properties: (row.properties ?? {}) as Record<string, unknown>,
+  };
+}
+
+export interface SendConnectorActionArgs {
+  /** The connector the action belongs to (e.g. "discord"). */
+  connectorId: string;
+  /** The action name (e.g. "sendChannelMessage"). */
+  action: string;
+  /** The action's own args object (shape defined by the action). */
+  args?: unknown;
+}
+
+/**
+ * Invoke a registered connector outbound action from a journey/workflow. The
+ * standalone, socket-free counterpart to `sendEmail()` — single-object-in,
+ * result-out, NOT on `JourneyContext` (features are standalone imports). Throws
+ * when the action isn't registered (wire it via
+ * `createHogsendClient({ connectorActions })`).
+ *
+ * Independent of any inbound gateway runtime: a deployment with the gateway off
+ * (or "Worker Offline") can still send — Discord actions are bot-REST needing
+ * only the bot token.
+ */
+export async function sendConnectorAction(
+  input: SendConnectorActionArgs,
+): Promise<unknown> {
+  const action = getConnectorActionRegistry().get(
+    input.connectorId,
+    input.action,
+  );
+  if (!action) {
+    throw new Error(
+      `no connector action "${input.connectorId}:${input.action}" is registered ` +
+        "(pass it via createHogsendClient({ connectorActions }))",
+    );
+  }
+  const db = getDb();
+  return action.run(input.args, {
+    db,
+    logger: createLogger(env.LOG_LEVEL),
+    resolveContact: (ref: string) => resolveContact(db, ref),
+  });
+}

package/src/lib/connector-heartbeat.ts

@@ -0,0 +1,177 @@
+import type { Logger } from "./logger.js";
+import { getRedis } from "./redis.js";
+
+/**
+ * Connector-runtime liveness heartbeat — the connector-neutral generalization of
+ * {@link ./discord-gateway-heartbeat.ts}. A long-lived inbound runtime (the
+ * leased gateway socket) writes a TTL'd Redis key on an interval; readers (the
+ * admin `/connectors` projection Studio reads) treat a fresh key as "this
+ * connector's runtime is alive". Because ONLY the lease-holder writes it (see
+ * connectors/runtime.ts), a fresh key means "this deployment's elected leader
+ * owns the socket" — liveness is OWNED, not merely observed, so a stray process
+ * can no longer light the dashboard green.
+ *
+ * The payload carries an opaque `metadata` blob (e.g. `{ guildId, intents }` for
+ * Discord) folded in by the runtime — so the heartbeat stays platform-neutral
+ * while still surfacing the bits Studio shows. Everything is best-effort: a
+ * missing/unreachable Redis never crashes the runtime and reads back as "down".
+ *
+ * The legacy Discord key (`hogsend:discord-gateway:heartbeat`, still written by
+ * the standalone `discord-worker.ts` hatch via {@link startDiscordGatewayHeartbeat})
+ * is honoured as a READ fallback for `connectorId === "discord"`, so a
+ * mid-rollout deploy where the old standalone worker is still the writer keeps
+ * showing green until the inline runtime takes over.
+ */
+const TTL_SECONDS = 30;
+const REFRESH_MS = 10_000;
+
+const heartbeatKey = (connectorId: string) =>
+  `hogsend:connector-runtime:${connectorId}:heartbeat`;
+
+/** The legacy standalone-Discord key — read-only fallback for one minor. */
+const LEGACY_DISCORD_KEY = "hogsend:discord-gateway:heartbeat";
+
+export interface ConnectorHeartbeat {
+  /** True when a fresh runtime heartbeat is present in Redis. */
+  alive: boolean;
+  /** ISO timestamp the runtime last wrote, when alive. */
+  lastSeenAt?: string;
+  /** Opaque platform metadata the runtime folded in (e.g. guildId, intents). */
+  metadata?: Record<string, unknown>;
+}
+
+/** The JSON shape persisted under {@link heartbeatKey}. */
+interface HeartbeatPayload {
+  lastSeenAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ConnectorHeartbeatState {
+  /**
+   * Merge a metadata patch (read-merge-write) and flush immediately, so Studio
+   * reflects a late-observed field (e.g. the guild id seen at GUILD_CREATE)
+   * without waiting for the next refresh tick.
+   */
+  setMetadata(patch: Record<string, unknown>): void;
+}
+
+export interface ConnectorHeartbeatHandle {
+  state: ConnectorHeartbeatState;
+  /** Clear the timer and delete the key for an immediate "down" on demotion. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Begin writing a connector-runtime heartbeat. Writes once immediately, then
+ * refreshes every {@link REFRESH_MS} with a {@link TTL_SECONDS} expiry — so an
+ * ungraceful death (or a lost lease) is reflected as "down" within the TTL.
+ */
+export function startConnectorHeartbeat(
+  connectorId: string,
+  logger: Logger,
+): ConnectorHeartbeatHandle {
+  let warned = false;
+  let metadata: Record<string, unknown> = {};
+  const key = heartbeatKey(connectorId);
+
+  const write = async () => {
+    const payload: HeartbeatPayload = {
+      lastSeenAt: new Date().toISOString(),
+      ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+    };
+    try {
+      await getRedis().set(key, JSON.stringify(payload), "EX", TTL_SECONDS);
+    } catch (err) {
+      if (!warned) {
+        warned = true;
+        logger.debug("Connector heartbeat write failed (Redis unreachable?)", {
+          connectorId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  };
+
+  void write();
+  const timer = setInterval(() => void write(), REFRESH_MS);
+  // Never hold the process open for the heartbeat alone.
+  timer.unref?.();
+
+  return {
+    state: {
+      setMetadata(patch: Record<string, unknown>) {
+        metadata = { ...metadata, ...patch };
+        void write();
+      },
+    },
+    async stop() {
+      clearInterval(timer);
+      try {
+        await getRedis().del(key);
+      } catch {
+        // Best-effort — the TTL expires it anyway.
+      }
+    },
+  };
+}
+
+/** Normalize a stored payload string into a {@link ConnectorHeartbeat}. */
+function parsePayload(raw: string): ConnectorHeartbeat {
+  try {
+    const parsed = JSON.parse(raw) as HeartbeatPayload;
+    return {
+      alive: true,
+      lastSeenAt: parsed.lastSeenAt,
+      ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
+    };
+  } catch {
+    // Legacy plain-string value (a bare ISO timestamp) — alive, no metadata.
+    return { alive: true, lastSeenAt: raw };
+  }
+}
+
+/**
+ * Normalize the LEGACY Discord heartbeat (`{ lastSeenAt, guildId?, intents? }`)
+ * into the connector-neutral shape so the admin projection reads one schema.
+ */
+function parseLegacyDiscord(raw: string): ConnectorHeartbeat {
+  try {
+    const parsed = JSON.parse(raw) as {
+      lastSeenAt: string;
+      guildId?: string;
+      intents?: number;
+    };
+    const metadata: Record<string, unknown> = {};
+    if (parsed.guildId) metadata.guildId = parsed.guildId;
+    if (typeof parsed.intents === "number") metadata.intents = parsed.intents;
+    return {
+      alive: true,
+      lastSeenAt: parsed.lastSeenAt,
+      ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+    };
+  } catch {
+    return { alive: true, lastSeenAt: raw };
+  }
+}
+
+/**
+ * Read a connector-runtime heartbeat. Resolves to `{ alive: false }` when the
+ * key is missing or Redis is unreachable. For `connectorId === "discord"`, falls
+ * back to the legacy standalone-worker key so a mid-rollout deploy stays green.
+ */
+export async function getConnectorHeartbeat(
+  connectorId: string,
+): Promise<ConnectorHeartbeat> {
+  try {
+    const redis = getRedis();
+    const raw = await redis.get(heartbeatKey(connectorId));
+    if (raw) return parsePayload(raw);
+    if (connectorId === "discord") {
+      const legacy = await redis.get(LEGACY_DISCORD_KEY);
+      if (legacy) return parseLegacyDiscord(legacy);
+    }
+    return { alive: false };
+  } catch {
+    return { alive: false };
+  }
+}

package/src/lib/leader-lease.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import type { Redis } from "ioredis";
+import { getRedis } from "./redis.js";
+
+/**
+ * A connector-neutral distributed leader lease over Redis. The connector runtime
+ * needs EXACTLY ONE process (across N replicated Hatchet workers) to hold a given
+ * platform socket at a time — one bot token permits one live Gateway session — so
+ * the runtime races for a lease keyed by connector id and only the winner opens
+ * the socket. Losers idle and re-race, giving bounded automatic failover within
+ * the TTL with no two-holders overlap.
+ *
+ * The lease is a `SET key token NX PX ttl` (atomic acquire-if-absent with an
+ * expiry), renewed by a Lua compare-then-PEXPIRE and released by a Lua
+ * compare-then-DEL. The compare on the caller's unique `token` is the fence: a
+ * process that has LOST the lease (expired, taken over) can neither renew nor
+ * release it, so it can never stomp the new holder. Built on the shared engine
+ * Redis singleton ({@link getRedis}); every op accepts an explicit client for
+ * tests.
+ *
+ * Everything is best-effort against Redis faults: acquire/renew return `false`
+ * (caller stays/loses leader, never opens a second socket), release swallows.
+ * Fail-safe means "no lease ⇒ no socket", never "two sockets".
+ */
+
+/** Renew the lease ONLY if we still own it, then extend its expiry. */
+const RENEW_LUA =
+  'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("pexpire", KEYS[1], ARGV[2]) else return 0 end';
+
+/** Delete the lease ONLY if we still own it (never delete someone else's). */
+const RELEASE_LUA =
+  'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end';
+
+/** A process-unique fencing token to stamp on an acquired lease. */
+export function newLeaseToken(): string {
+  return randomUUID();
+}
+
+/**
+ * Try to acquire the lease. Returns `true` only when this call set the key (it
+ * was absent). A `false` means another holder owns it OR Redis is unreachable —
+ * either way the caller must NOT open the socket.
+ */
+export async function acquireLeaderLease(args: {
+  key: string;
+  token: string;
+  ttlMs: number;
+  redis?: Redis;
+}): Promise<boolean> {
+  const redis = args.redis ?? getRedis();
+  try {
+    const res = await redis.set(args.key, args.token, "PX", args.ttlMs, "NX");
+    return res === "OK";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Renew our hold on the lease (compare-and-extend). Returns `false` if we no
+ * longer own it (expired / taken over) or Redis is unreachable — the caller must
+ * then self-demote and stop the socket.
+ */
+export async function renewLeaderLease(args: {
+  key: string;
+  token: string;
+  ttlMs: number;
+  redis?: Redis;
+}): Promise<boolean> {
+  const redis = args.redis ?? getRedis();
+  try {
+    const res = await redis.eval(
+      RENEW_LUA,
+      1,
+      args.key,
+      args.token,
+      String(args.ttlMs),
+    );
+    return res === 1;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Release the lease if (and only if) we still own it. Best-effort: a failure is
+ * swallowed because the TTL expires the key anyway. Returns `true` when our own
+ * key was deleted.
+ */
+export async function releaseLeaderLease(args: {
+  key: string;
+  token: string;
+  redis?: Redis;
+}): Promise<boolean> {
+  const redis = args.redis ?? getRedis();
+  try {
+    const res = await redis.eval(RELEASE_LUA, 1, args.key, args.token);
+    return res === 1;
+  } catch {
+    return false;
+  }
+}

package/src/routes/admin/connectors.ts

@@ -4,8 +4,8 @@ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import { and, count, isNotNull, isNull } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
 import { getDestinationRegistry } from "../../destinations/registry-singleton.js";
+import { getConnectorHeartbeat } from "../../lib/connector-heartbeat.js";
 import { signConnectorState } from "../../lib/connector-state.js";
-import { getDiscordGatewayHeartbeat } from "../../lib/discord-gateway-heartbeat.js";
 import {
   getDerivedCredential,
   getProviderCredential,
@@ -281,14 +281,25 @@ export const adminConnectorsRouter = new OpenAPIHono<AppEnv>()
           const derived = (await getDerivedCredential(db, id).catch(
             () => null,
           )) as Record<string, unknown> | null;
-          const heartbeat = await getDiscordGatewayHeartbeat();
+          const heartbeat = await getConnectorHeartbeat(id);
+          // guildId/intents ride in the connector-neutral heartbeat metadata
+          // blob (folded in by the inline runtime; the legacy Discord key is
+          // normalized into the same shape on read).
+          const heartbeatGuildId =
+            typeof heartbeat.metadata?.guildId === "string"
+              ? heartbeat.metadata.guildId
+              : null;
+          const heartbeatIntents =
+            typeof heartbeat.metadata?.intents === "number"
+              ? heartbeat.metadata.intents
+              : null;
 
           const derivedGuildId =
             typeof derived?.discordGuildId === "string"
               ? derived.discordGuildId
               : null;
           // Prefer the live worker-observed guild; fall back to the stored one.
-          const guildId = heartbeat.guildId ?? derivedGuildId;
+          const guildId = heartbeatGuildId ?? derivedGuildId;
           // Prefer the LIVE worker-reported intents (the derived credential never
           // carries discordIntents — install writes only the guild id); fall back
           // to the derived value for forward-compat if it ever IS written.
@@ -296,7 +307,7 @@ export const adminConnectorsRouter = new OpenAPIHono<AppEnv>()
             typeof derived?.discordIntents === "number"
               ? derived.discordIntents
               : null;
-          const intents = heartbeat.intents ?? derivedIntents;
+          const intents = heartbeatIntents ?? derivedIntents;
           // Tri-state: a guild id (either source) confirms the bot is in a
           // server; otherwise unknown (null), NOT a false "not installed".
           const botInstalled: boolean | null = guildId ? true : null;
@@ -354,10 +365,14 @@ export const adminConnectorsRouter = new OpenAPIHono<AppEnv>()
     const derived = (await getDerivedCredential(db, "discord").catch(
       () => null,
     )) as Record<string, unknown> | null;
-    const heartbeat = await getDiscordGatewayHeartbeat();
+    const heartbeat = await getConnectorHeartbeat("discord");
     // Prefer the live worker-observed guild; fall back to the stored one.
+    const heartbeatGuildId =
+      typeof heartbeat.metadata?.guildId === "string"
+        ? heartbeat.metadata.guildId
+        : null;
     const guildId =
-      heartbeat.guildId ??
+      heartbeatGuildId ??
       (typeof derived?.discordGuildId === "string"
         ? derived.discordGuildId
         : null);

package/src/routes/webhooks/sources.ts

@@ -135,7 +135,15 @@ export function registerWebhookSourceRoutes(
     const rawBody = await c.req.text();
     const headers = headersToRecord(c.req.raw.headers);
 
-    let secret = env[auth.envKey as keyof typeof env] as string | undefined;
+    // Engine-declared secrets (presets) resolve from the validated env. A
+    // CONSUMER-defined webhook source may name an env var the engine schema
+    // doesn't declare (a BYO signature/match source), so fall back to the raw
+    // process.env value for it. Both auth branches below gate on truthiness, so
+    // an unset/blank secret stays fail-closed (signature → 401) and
+    // open-when-unconfigured (match) exactly as before.
+    let secret =
+      (env[auth.envKey as keyof typeof env] as string | undefined) ??
+      process.env[auth.envKey];
 
     // For the inbound PostHog source, fall back to the secret minted by
     // `hogsend connect` (kind="derived" store) when env has none — so an

package/src/worker.ts

@@ -3,6 +3,10 @@ import {
   selectBucketReactionTasks,
   selectBucketTasks,
 } from "./buckets/registry.js";
+import {
+  type ConnectorRuntimeFactory,
+  startConnectorRuntimes,
+} from "./connectors/runtime.js";
 import type { HogsendClient } from "./container.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
 import { parseEnabledFilter, selectJourneyTasks } from "./journeys/registry.js";
@@ -39,6 +43,14 @@ export interface CreateWorkerOptions {
   enabledBuckets?: string;
   /** Extra client tasks registered alongside the built-in workflows. */
   extraWorkflows?: unknown[];
+  /**
+   * Inbound connector-runtime factories keyed by connector id (e.g.
+   * `{ discord: createDiscordRuntime }`). When `CONNECTOR_RUNTIME_HOST=worker`
+   * (default) and `ENABLE_CONNECTOR_RUNTIMES` is on, the worker elects a single
+   * leader replica per gateway connector and holds its socket inline — no
+   * separate service, no ingress secret.
+   */
+  connectorRuntimes?: Record<string, ConnectorRuntimeFactory>;
 }
 
 export interface Worker {
@@ -99,11 +111,14 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
   // lifecycle. `_worker` is captured for stop().
   let _worker: Awaited<ReturnType<typeof hatchet.worker>> | undefined;
   let _stopHeartbeat: (() => Promise<void>) | undefined;
+  let _stopRuntimes: (() => Promise<void>) | undefined;
 
   async function stop(): Promise<void> {
-    // Delete the heartbeat first (an immediate "worker down" signal) before the
-    // Redis connection is torn down below.
+    // Delete the worker heartbeat first (an immediate "worker down" signal) and
+    // release any connector-runtime leases + their heartbeats BEFORE the Redis
+    // connection is torn down below.
     await _stopHeartbeat?.();
+    await _stopRuntimes?.();
     await Promise.allSettled([
       _worker?.stop(),
       // Shut down the injected analytics instance (same object the worker's
@@ -142,6 +157,26 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     // (read via GET /v1/health). Best-effort; never blocks the listener.
     _stopHeartbeat = startWorkerHeartbeat(container.logger);
 
+    // Inline connector runtimes (gateway sockets) — the worker is the default
+    // host. Each gateway connector with a supplied factory races a Redis leader
+    // lease so exactly one replica holds its socket; the in-process sink feeds
+    // transform→ingest with no HTTP hop. Auto-on; a factory that declines (e.g.
+    // no bot token) simply no-ops. Started AFTER the heartbeat and BEFORE the
+    // blocking `_worker.start()` below (anything after it is dead code at
+    // runtime until shutdown).
+    if (
+      container.env.ENABLE_CONNECTOR_RUNTIMES === "true" &&
+      container.env.CONNECTOR_RUNTIME_HOST === "worker" &&
+      opts.connectorRuntimes &&
+      Object.keys(opts.connectorRuntimes).length > 0
+    ) {
+      const runtimes = startConnectorRuntimes({
+        client: container,
+        factories: opts.connectorRuntimes,
+      });
+      _stopRuntimes = () => runtimes.stop();
+    }
+
     // Boot-time backfill / criteria-change re-eval (Section 6.6 B): diff each
     // enabled bucket's criteriaHash against bucket_configs and trigger a
     // backfill/re-eval run where it differs. Kicked off BEFORE the listener