@checkstack/automation-backend 0.2.0

package/src/dispatch/trigger-subscriber.ts

@@ -0,0 +1,397 @@
+/**
+ * Trigger fan-in for the automation dispatch engine.
+ *
+ * Subscribes to every registered hook-backed trigger in `afterPluginsReady`,
+ * routes each emission to the matching enabled automations, and respects
+ * each automation's concurrency mode (single / parallel / queued / restart).
+ *
+ * Also handles `wait_for_trigger` resumption: every incoming event is
+ * cross-referenced against `automation_wait_locks` and matching waits
+ * are woken up.
+ */
+import type {
+  AutomationMode,
+  Trigger,
+} from "@checkstack/automation-common";
+import type {
+  HookEventMeta,
+  HookSubscribeOptions,
+  Logger,
+} from "@checkstack/backend-api";
+import { SYSTEM_ACTOR, type Actor } from "@checkstack/common";
+
+import type { AutomationStore } from "../automation-store";
+import { dispatchTrigger, resumeRun } from "./engine";
+import { evaluateCondition } from "./condition";
+import { renderString } from "./render";
+import { buildInitialScope } from "./scope";
+import type {
+  DispatchDeps,
+  LoadedAutomation,
+} from "./types";
+
+/**
+ * Subscription handle returned by `setupTriggerSubscriptions`. Calling
+ * `dispose()` unsubscribes every hook and tears down every setup-backed
+ * trigger. Used at shutdown.
+ */
+export interface TriggerSubscriptions {
+  dispose: () => Promise<void>;
+}
+
+/**
+ * Type of `onHook` injected by the plugin runtime in afterPluginsReady.
+ * Mirrors the shape from `@checkstack/backend-api` — note that the
+ * call returns a sync `HookUnsubscribe` (an async function), not a
+ * Promise<HookUnsubscribe>.
+ */
+export type OnHookFn = <T>(
+  hook: { id: string; _type?: T },
+  listener: (payload: T, meta?: HookEventMeta) => Promise<void>,
+  options?: HookSubscribeOptions,
+) => () => Promise<void>;
+
+export interface SetupTriggerSubscriptionsArgs {
+  deps: DispatchDeps;
+  onHook: OnHookFn;
+  automationStore: AutomationStore;
+  logger: Logger;
+}
+
+export async function setupTriggerSubscriptions(
+  args: SetupTriggerSubscriptionsArgs,
+): Promise<TriggerSubscriptions> {
+  const teardowns: Array<() => Promise<void>> = [];
+
+  const triggers = args.deps.registries.triggers.getTriggers();
+  args.logger.debug(
+    `⚙️  Setting up ${triggers.length} automation trigger subscriptions`,
+  );
+
+  for (const trigger of triggers) {
+    if (trigger.hook) {
+      const teardown = args.onHook(
+        trigger.hook,
+        async (payload, meta) => {
+          await handleTriggerFiring({
+            deps: args.deps,
+            automationStore: args.automationStore,
+            qualifiedEventId: trigger.qualifiedId,
+            triggerPayload: payload as Record<string, unknown>,
+            actor: meta?.actor ?? SYSTEM_ACTOR,
+            contextKey:
+              (trigger.contextKey?.(payload) ?? null),
+          });
+        },
+        {
+          mode: "work-queue",
+          workerGroup: `automation-trigger-${trigger.qualifiedId}`,
+        },
+      );
+      teardowns.push(teardown);
+      continue;
+    }
+
+    // Setup-backed triggers (cron, interval, template) — instantiate one
+    // setup per (automation, triggerConfig) pair across enabled
+    // automations referencing this trigger.
+    if (trigger.setup) {
+      const automations = await args.automationStore.listEnabled();
+      const referencing = automations.filter((a) =>
+        a.definition.triggers.some((t) => t.event === trigger.qualifiedId),
+      );
+      for (const automation of referencing) {
+        for (const t of automation.definition.triggers.filter(
+          (t) => t.event === trigger.qualifiedId,
+        )) {
+          const triggerId = t.id ?? deriveTriggerId(t);
+          const teardown = await trigger.setup({
+            config: t.config as never,
+            identity: {
+              automationId: automation.id,
+              triggerId,
+            },
+            fire: async (payload) => {
+              await handleTriggerFiring({
+                deps: args.deps,
+                automationStore: args.automationStore,
+                qualifiedEventId: trigger.qualifiedId,
+                triggerPayload: payload as Record<string, unknown>,
+                // Setup-backed triggers (cron / interval / template) fire on a
+                // schedule with no acting caller — the system is the actor.
+                actor: SYSTEM_ACTOR,
+                contextKey:
+                  trigger.contextKey?.(payload) ?? null,
+              });
+            },
+            logger: args.logger,
+          });
+          teardowns.push(teardown);
+        }
+      }
+    }
+  }
+
+  return {
+    dispose: async () => {
+      for (const teardown of teardowns.toReversed()) {
+        try {
+          await teardown();
+        } catch (error) {
+          args.logger.warn(
+            `Failed to tear down trigger subscription: ${(error as Error).message}`,
+          );
+        }
+      }
+    },
+  };
+}
+
+interface HandleTriggerFiringArgs {
+  deps: DispatchDeps;
+  automationStore: AutomationStore;
+  qualifiedEventId: string;
+  triggerPayload: Record<string, unknown>;
+  actor: Actor;
+  contextKey: string | null;
+}
+
+async function handleTriggerFiring(
+  args: HandleTriggerFiringArgs,
+): Promise<void> {
+  // ── Step 1: resume any waiting runs ──
+  await wakeWaitingRuns(args);
+
+  // ── Step 2: route to fresh runs for automations referencing this event ──
+  const matches = await args.automationStore.findEnabledByTriggerEvent(
+    args.qualifiedEventId,
+  );
+
+  for (const automation of matches) {
+    for (const trigger of automation.definition.triggers.filter(
+      (t) => t.event === args.qualifiedEventId,
+    )) {
+      await maybeStartRun({
+        deps: args.deps,
+        automation,
+        trigger,
+        triggerPayload: args.triggerPayload,
+        actor: args.actor,
+        contextKey: args.contextKey,
+        eventId: args.qualifiedEventId,
+      });
+    }
+  }
+}
+
+async function wakeWaitingRuns(args: HandleTriggerFiringArgs): Promise<void> {
+  const matches = await args.deps.runStore.findWaitLocksFor(
+    args.qualifiedEventId,
+    args.contextKey,
+  );
+  if (matches.length === 0) return;
+
+  for (const lock of matches) {
+    // Evaluate filter template if present.
+    if (lock.filterTemplate) {
+      try {
+        const ctx = buildInitialScope({
+          triggerId: "wait",
+          triggerEventId: args.qualifiedEventId,
+          payload: args.triggerPayload,
+          actor: args.actor,
+          startedAt: new Date(),
+        });
+        const pass = evaluateCondition(
+          lock.filterTemplate,
+          ctx,
+          args.deps.filters,
+        );
+        if (!pass) continue;
+      } catch (error) {
+        args.deps.logger.warn(
+          `wait_for_trigger filter failed to evaluate; skipping resume: ${(error as Error).message}`,
+        );
+        continue;
+      }
+    }
+
+    // Load the automation so we have the definition to resume against.
+    const run = await args.deps.runStore.loadRun(lock.runId);
+    if (!run) continue;
+    const automation = await args.automationStore.getById(run.automationId);
+    if (!automation) continue;
+
+    await args.deps.runStore.deleteWaitLock(lock.id);
+    await resumeRun(args.deps, {
+      runId: lock.runId,
+      automation: {
+        id: automation.id,
+        name: automation.name,
+        status: automation.status,
+        definition: automation.definition,
+      },
+      waitedAtPath: lock.actionPath,
+      payload: args.triggerPayload,
+    });
+  }
+}
+
+interface MaybeStartRunArgs {
+  deps: DispatchDeps;
+  automation: LoadedAutomation;
+  trigger: Trigger;
+  triggerPayload: Record<string, unknown>;
+  actor: Actor;
+  contextKey: string | null;
+  eventId: string;
+}
+
+async function maybeStartRun(args: MaybeStartRunArgs): Promise<void> {
+  // Trigger-level filter check.
+  if (args.trigger.filter) {
+    const ctx = buildInitialScope({
+      triggerId: args.trigger.id ?? deriveTriggerId(args.trigger),
+      triggerEventId: args.eventId,
+      payload: args.triggerPayload,
+      actor: args.actor,
+      startedAt: new Date(),
+    });
+    let pass: boolean;
+    try {
+      pass = evaluateCondition(
+        args.trigger.filter,
+        ctx,
+        args.deps.filters,
+      );
+    } catch (error) {
+      args.deps.logger.warn(
+        `Trigger filter failed to evaluate; skipping firing: ${(error as Error).message}`,
+      );
+      return;
+    }
+    if (!pass) return;
+  }
+
+  // Top-level conditions gate the run.
+  if (args.automation.definition.conditions.length > 0) {
+    const ctx = buildInitialScope({
+      triggerId: args.trigger.id ?? deriveTriggerId(args.trigger),
+      triggerEventId: args.eventId,
+      payload: args.triggerPayload,
+      actor: args.actor,
+      startedAt: new Date(),
+    });
+    for (const condition of args.automation.definition.conditions) {
+      try {
+        const pass = evaluateCondition(
+          condition,
+          ctx,
+          args.deps.filters,
+        );
+        if (!pass) return;
+      } catch {
+        return;
+      }
+    }
+  }
+
+  await respectConcurrencyMode({
+    deps: args.deps,
+    automationId: args.automation.id,
+    mode: args.automation.definition.mode,
+    maxRuns: args.automation.definition.max_runs,
+    triggerId: args.trigger.id ?? deriveTriggerId(args.trigger),
+    triggerEventId: args.eventId,
+    triggerPayload: args.triggerPayload,
+    actor: args.actor,
+    contextKey: args.contextKey,
+    automation: args.automation,
+  });
+}
+
+interface RespectConcurrencyArgs {
+  deps: DispatchDeps;
+  automationId: string;
+  automation: LoadedAutomation;
+  mode: AutomationMode;
+  maxRuns: number;
+  triggerId: string;
+  triggerEventId: string;
+  triggerPayload: Record<string, unknown>;
+  actor: Actor;
+  contextKey: string | null;
+}
+
+async function respectConcurrencyMode(
+  args: RespectConcurrencyArgs,
+): Promise<void> {
+  switch (args.mode) {
+    case "single": {
+      const active = await args.deps.runStore.hasActiveRun(args.automationId);
+      if (active) {
+        args.deps.logger.debug(
+          `Skipping trigger for ${args.automationId} — single mode and a run is active`,
+        );
+        return;
+      }
+      break;
+    }
+    case "parallel": {
+      const count = await args.deps.runStore.countActiveRuns(args.automationId);
+      if (count >= args.maxRuns) {
+        args.deps.logger.debug(
+          `Skipping trigger for ${args.automationId} — parallel limit reached (${count}/${args.maxRuns})`,
+        );
+        return;
+      }
+      break;
+    }
+    case "queued": {
+      // v1: queued behaves like parallel within max_runs. Real FIFO
+      // queueing requires its own coordination queue, which we add in a
+      // follow-up. Behaviour stays correct (no double-fire) under the
+      // existing work-queue mode.
+      const count = await args.deps.runStore.countActiveRuns(args.automationId);
+      if (count >= args.maxRuns) return;
+      break;
+    }
+    case "restart": {
+      const cancelled = await args.deps.runStore.cancelActiveRuns(
+        args.automationId,
+        "restart — superseded by newer trigger",
+      );
+      if (cancelled.length > 0) {
+        args.deps.logger.debug(
+          `Restart mode: cancelled ${cancelled.length} prior run(s) for ${args.automationId}`,
+        );
+      }
+      break;
+    }
+  }
+
+  await dispatchTrigger(args.deps, {
+    automation: args.automation,
+    triggerId: args.triggerId,
+    triggerEventId: args.triggerEventId,
+    payload: args.triggerPayload,
+    actor: args.actor,
+    contextKey: args.contextKey,
+  });
+}
+
+// Suppress unused warning for renderString — the helper is exported via
+// scope.ts and used by the engine's primitives; trigger-subscriber
+// doesn't currently render templates beyond conditions, but the import
+// is convenient for future filter expressions.
+void renderString;
+
+/**
+ * Derive a stable trigger id from the trigger declaration when the
+ * operator hasn't assigned one. Slugifies the event id; collisions
+ * within a single automation are the operator's responsibility (the
+ * editor surfaces the `id` field as soon as a duplicate appears).
+ */
+function deriveTriggerId(trigger: Trigger): string {
+  return trigger.event.replaceAll(/[^a-z0-9]+/gi, "_").toLowerCase();
+}

package/src/dispatch/types.ts

@@ -0,0 +1,259 @@
+/**
+ * Internal types for the automation dispatch engine.
+ *
+ * These are kept private to `automation-backend` — public API lives in
+ * `@checkstack/automation-common` and the package's index re-exports.
+ */
+import type { Logger, ServiceRef } from "@checkstack/backend-api";
+import type { AutomationDefinition } from "@checkstack/automation-common";
+import type { QueueManager } from "@checkstack/queue-api";
+import type { FilterRegistry } from "@checkstack/template-engine";
+
+import type { ActionRegistry } from "../action-registry";
+import type { ArtifactTypeRegistry } from "../artifact-type-registry";
+import type { TriggerRegistry } from "../trigger-registry";
+import type { ArtifactStore } from "../artifact-store";
+
+import type { RunStateStore } from "./run-state-store";
+
+/**
+ * Persistent dependency bundle threaded through the dispatch engine.
+ * Provided once by the plugin entry; reused for every run / step.
+ */
+export interface DispatchDeps {
+  logger: Logger;
+  filters: FilterRegistry;
+  registries: {
+    triggers: TriggerRegistry;
+    actions: ActionRegistry;
+    artifactTypes: ArtifactTypeRegistry;
+  };
+  artifactStore: ArtifactStore;
+  /** Resolve a platform service ref — passed through to action `execute`. */
+  getService: <T>(ref: ServiceRef<T>) => Promise<T>;
+  /** Persistence backend for runs / steps / wait locks. */
+  runStore: RunStore;
+  /** Per-run scope snapshot + heartbeat + advisory-lock helpers. */
+  runStateStore: RunStateStore;
+  /**
+   * Queue manager for crash-safe time-based suspension (`delay` action)
+   * and any future queue-backed continuations.
+   */
+  queueManager: QueueManager;
+}
+
+/**
+ * A node-style action path. Strings index into "actions", "sequence",
+ * etc.; numbers index array positions.
+ *
+ *   ["actions", 0]                                 // first top-level action
+ *   ["actions", 1, "choose", 0, "sequence", 2]     // 3rd action in first choose branch of 2nd action
+ *   ["actions", 3, "parallel", 1]                  // 2nd parallel branch of 4th action
+ *   ["actions", 4, "repeat", "sequence", 0]        // 1st action in repeat sequence of 5th action
+ */
+export type ActionPath = ReadonlyArray<string | number>;
+
+/**
+ * Serialize an action path for persistence / display. We keep it
+ * URL-ish for readability in the run-detail UI.
+ *
+ *   ["actions", 0]  →  "actions[0]"
+ *   ["actions", 1, "choose", 0, "sequence", 2]  →  "actions[1].choose[0].sequence[2]"
+ */
+export function formatActionPath(path: ActionPath): string {
+  let out = "";
+  for (const segment of path) {
+    if (typeof segment === "number") {
+      out += `[${segment}]`;
+    } else {
+      out += out.length === 0 ? segment : `.${segment}`;
+    }
+  }
+  return out;
+}
+
+/**
+ * The terminal outcomes of executing a single action.
+ */
+export type StepOutcome =
+  | { kind: "ok" }
+  | { kind: "skipped"; reason: string }
+  | { kind: "failed"; error: string }
+  | { kind: "stopped"; reason?: string; error?: boolean }
+  | { kind: "suspended"; stepId: string };
+
+/**
+ * The outcomes of walking a sequence (top-level `actions:`, a `choose`
+ * branch, a `parallel` branch, a `repeat` iteration body, etc.).
+ */
+export type SequenceOutcome =
+  | { kind: "completed" }
+  | { kind: "stopped"; reason?: string; error?: boolean }
+  | { kind: "suspended"; suspendingStepId: string };
+
+/**
+ * Loaded automation row + parsed definition. Convenience wrapper to keep
+ * call sites tidy.
+ */
+export interface LoadedAutomation {
+  id: string;
+  name: string;
+  status: "enabled" | "disabled";
+  definition: AutomationDefinition;
+}
+
+/**
+ * Top-level run identity carried through the walker.
+ */
+export interface RunIdentity {
+  runId: string;
+  automation: LoadedAutomation;
+  /** Operator-assigned trigger id or auto-derived (`event` slug). */
+  triggerId: string;
+  /** Fully qualified event id that fired. */
+  triggerEventId: string;
+  contextKey: string | null;
+  startedAt: Date;
+}
+
+/**
+ * Execution context handed to each primitive handler.
+ *
+ * - `scope` is the template-engine variable bag for the current position
+ *   in the tree. The walker rebuilds this when entering / exiting
+ *   nested blocks (variables, repeat iterations, etc.).
+ * - `payload` is the original trigger payload — convenient for actions
+ *   that want to reach it directly.
+ * - `consumedArtifacts` is a lazy view — the dispatcher resolves it
+ *   when an action declares `consumes` rather than scanning every step.
+ */
+export interface DispatchContext {
+  deps: DispatchDeps;
+  run: RunIdentity;
+  payload: Record<string, unknown>;
+  /** Mutable variable scope. Modified by `variables` / `repeat`. */
+  scope: Record<string, unknown>;
+  /** When inside `wait_for_trigger`'s resume path, set to true. */
+  resuming: boolean;
+}
+
+// ─── Run-store interface ─────────────────────────────────────────────────
+
+/**
+ * Persistence operations the dispatch engine needs. Implemented in
+ * `run-state.ts` against the Drizzle schema.
+ */
+export interface RunStore {
+  // Runs
+  createRun(input: CreateRunInput): Promise<string>;
+  updateRunStatus(
+    runId: string,
+    status: "running" | "waiting" | "success" | "failed" | "cancelled" | "skipped",
+    errorMessage?: string,
+  ): Promise<void>;
+  loadRun(runId: string): Promise<LoadedRun | undefined>;
+  countActiveRuns(automationId: string): Promise<number>;
+  /** Used by `mode: "single"` to detect a pre-existing run. */
+  hasActiveRun(automationId: string): Promise<boolean>;
+  /** Used by `mode: "restart"` to abort prior runs. */
+  cancelActiveRuns(automationId: string, reason: string): Promise<string[]>;
+
+  // Steps
+  createStep(input: CreateStepInput): Promise<string>;
+  updateStep(
+    stepId: string,
+    patch: {
+      status: "running" | "success" | "failed" | "skipped" | "waiting";
+      errorMessage?: string;
+      resultPayload?: Record<string, unknown>;
+      incrementAttempts?: boolean;
+    },
+  ): Promise<void>;
+  /**
+   * Find the most recent step row for a given `(runId, actionPath)`.
+   * Used by container resumes (parallel / repeat) to look up the
+   * step they wrote at suspension so they can read accumulated state
+   * (branch outcomes, iteration list) from its `result_payload`.
+   */
+  findStepByPath(
+    runId: string,
+    actionPath: string,
+  ): Promise<LoadedStep | undefined>;
+
+  // Wait locks (for wait_for_trigger + delay durability)
+  createWaitLock(input: CreateWaitLockInput): Promise<string>;
+  loadWaitLock(id: string): Promise<LoadedWaitLock | undefined>;
+  findWaitLocksFor(
+    eventId: string,
+    contextKey: string | null,
+  ): Promise<LoadedWaitLock[]>;
+  deleteWaitLock(id: string): Promise<void>;
+  sweepExpiredWaitLocks(now: Date): Promise<LoadedWaitLock[]>;
+}
+
+export interface CreateRunInput {
+  automationId: string;
+  triggerId: string;
+  triggerEventId: string;
+  triggerPayload: Record<string, unknown>;
+  contextKey: string | null;
+}
+
+export interface LoadedRun {
+  id: string;
+  automationId: string;
+  triggerId: string;
+  triggerEventId: string;
+  triggerPayload: Record<string, unknown>;
+  contextKey: string | null;
+  status: string;
+  errorMessage: string | null;
+  startedAt: Date;
+  finishedAt: Date | null;
+}
+
+export interface CreateStepInput {
+  runId: string;
+  actionPath: string;
+  actionId: string | null;
+  actionKind: string;
+  providerActionId: string | null;
+}
+
+export interface LoadedStep {
+  id: string;
+  runId: string;
+  actionPath: string;
+  actionId: string | null;
+  actionKind: string;
+  status: string;
+  attempts: number;
+  errorMessage: string | null;
+  resultPayload: Record<string, unknown> | null;
+  startedAt: Date;
+  finishedAt: Date | null;
+}
+
+export type WaitLockKind = "trigger" | "delay";
+
+export interface CreateWaitLockInput {
+  runId: string;
+  actionPath: string;
+  kind: WaitLockKind;
+  eventId: string;
+  contextKey: string | null;
+  filterTemplate: string | null;
+  timeoutAt: Date | null;
+}
+
+export interface LoadedWaitLock {
+  id: string;
+  runId: string;
+  actionPath: string;
+  kind: WaitLockKind;
+  eventId: string;
+  contextKey: string | null;
+  filterTemplate: string | null;
+  timeoutAt: Date | null;
+  createdAt: Date;
+}