@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/builtin-triggers.ts

@@ -1,16 +1,17 @@
 /**
  * Built-in triggers shipped by automation-backend itself.
  *
- * Three triggers, all setup-backed (no plugin hook to subscribe to):
+ * Two setup-backed triggers (no plugin hook to subscribe to):
  *
  *   - `time.cron` — recurring queue job on a cron pattern.
  *   - `time.interval` — recurring queue job on a fixed interval.
- *   - `template` — interval-based polling; evaluates a template on each
- *     tick and fires on the false → true edge (so an automation
- *     subscribing on "value template is truthy" doesn't re-fire while
- *     the value stays truthy).
  *
- * All three share the same two-stage runtime structure:
+ * (The polling `template` trigger was removed in the reactive engine —
+ * §7. Its real cases are covered reactively by the `numeric_state` /
+ * `state` triggers + conditions, which wake on `ENTITY_CHANGED` instead of
+ * re-evaluating on a timer.)
+ *
+ * Both share the same two-stage runtime structure:
  *
  *   1. A single shared queue (`automation-builtin-triggers`) accepts
  *      every recurring tick. A consumer registered at plugin init reads
@@ -33,15 +34,12 @@
  * back in place by the time the consumer would dispatch.
  */
 import { z } from "zod";
-import type { Logger } from "@checkstack/backend-api";
+import { createHook, type Logger } from "@checkstack/backend-api";
 import type { QueueManager } from "@checkstack/queue-api";
 import type { PluginMetadata } from "@checkstack/common";
-import {
-  evaluateBoolean,
-  parseCondition,
-} from "@checkstack/template-engine";
 
 import type { TriggerDefinition } from "./action-types";
+import { extractNumericField, matchesThreshold } from "./dispatch/numeric";
 
 // ─── Shared queue plumbing ─────────────────────────────────────────────
 
@@ -99,7 +97,7 @@ export async function registerBuiltinTriggerConsumer(args: {
 }
 
 function buildJobId(args: {
-  kind: "cron" | "interval" | "template";
+  kind: "cron" | "interval";
   automationId: string;
   triggerId: string;
 }): string {
@@ -222,106 +220,102 @@ export function createTimeIntervalTrigger(
   };
 }
 
-// ─── template ──────────────────────────────────────────────────────────
+// ─── numeric_state ───────────────────────────────────────────────────────
 
-const templateConfigSchema = z.object({
-  /**
-   * Boolean expression evaluated every tick — uses the template
-   * engine's condition grammar.
-   *
-   * The trigger context exposes `{ now }` (ISO string). Anything more
-   * elaborate should be reached via the standard automation `variables`
-   * block / action pipeline, not from the trigger itself — the
-   * tick frequency makes anything I/O-heavy in here costly.
-   */
-  value_template: z
-    .string()
-    .min(1)
-    .describe(
-      "Boolean template — fires on the false → true edge. Has access to `{ now }`.",
-    ),
-  intervalSeconds: z
-    .number()
-    .int()
-    .min(1)
-    .max(86_400)
-    .describe("How often to re-evaluate the template (1s – 24h)."),
-});
+/**
+ * The `healthcheck.check.completed` hook this trigger rides. Referenced
+ * by id only (a `Hook` is just `{ id }`), so automation-backend needs no
+ * compile-time dependency on healthcheck-backend — the id must match what
+ * healthcheck emits.
+ */
+const HEALTHCHECK_CHECK_COMPLETED = "healthcheck.check.completed";
 
-const templateFiredPayloadSchema = z.object({
-  firedAt: z.string(),
+interface CheckCompletedPayload {
+  systemId: string;
+  configurationId: string;
+  status: string;
+  latencyMs?: number;
+  result?: Record<string, unknown>;
+  timestamp?: string;
+}
+
+const numericStateConfigSchema = z
+  .object({
+    field: z
+      .string()
+      .min(1)
+      .describe(
+        "Numeric field to watch: `latencyMs`, `p95LatencyMs`, or a collector path like `collectors.http.responseTimeMs`.",
+      ),
+    above: z
+      .number()
+      .optional()
+      .describe("Fire when the field is strictly greater than this."),
+    below: z
+      .number()
+      .optional()
+      .describe("Fire when the field is strictly less than this."),
+  })
+  .refine((c) => c.above !== undefined || c.below !== undefined, {
+    message: "numeric_state trigger requires at least one of `above` / `below`",
+  });
+
+export type NumericStateConfig = z.infer<typeof numericStateConfigSchema>;
+
+const numericStatePayloadSchema = z.object({
+  systemId: z.string(),
+  configurationId: z.string(),
+  status: z.string(),
+  field: z.string().describe("The watched field path."),
+  value: z.number().describe("The numeric value that crossed the threshold."),
+  timestamp: z.string().optional(),
 });
 
-export type TemplateConfig = z.infer<typeof templateConfigSchema>;
-export type TemplateFiredPayload = z.infer<typeof templateFiredPayloadSchema>;
+export type NumericStatePayload = z.infer<typeof numericStatePayloadSchema>;
 
-export function createTemplateTrigger(
-  deps: BuiltinTriggerDeps,
-): TriggerDefinition<TemplateFiredPayload, TemplateConfig> {
+/**
+ * `numeric_state` — fires off `healthcheck.check.completed` when a numeric
+ * field crosses an `above` / `below` threshold. Hook-backed; the per-
+ * automation threshold is enforced via `evaluateConfig` (a structured gate
+ * the trigger fan-in calls before starting a run). Combine with a
+ * trigger-level `for:` (Phase 15) for "above X for Y minutes".
+ *
+ * v1 is LEVEL-triggered: it fires on every completed check whose field is
+ * past the threshold. Edge (false → true) de-duplication is deferred;
+ * `mode: single` + `for:` already prevent alert storms in practice.
+ */
+export function createNumericStateTrigger(): TriggerDefinition<
+  NumericStatePayload,
+  NumericStateConfig
+> {
   return {
-    id: "template",
-    displayName: "Template Condition",
+    id: "numeric_state",
+    displayName: "Numeric Threshold",
     description:
-      "Polls a boolean template on a fixed interval. Fires on the false → true edge so the automation runs once per truthy window, not on every tick.",
-    category: "Time",
-    icon: "FileCode",
-    payloadSchema: templateFiredPayloadSchema,
-    configSchema: templateConfigSchema,
-    setup: async ({ config, identity, fire, logger }) => {
-      const jobId = buildJobId({
-        kind: "template",
-        automationId: identity.automationId,
-        triggerId: identity.triggerId,
-      });
-      // Each tick lives in this closure — `previousTruthy` survives
-      // across ticks for the lifetime of the setup() return. Tearing
-      // down resets it via the map-removal.
-      let previousTruthy = false;
-      let parsed;
-      try {
-        parsed = parseCondition(config.value_template);
-      } catch (error) {
-        // A malformed expression should fail fast at setup so the
-        // operator sees the error in the editor rather than as
-        // silently-never-firing.
-        throw new Error(
-          `template trigger: invalid value_template — ${(error as Error).message}`,
-        );
-      }
-      tickHandlers.set(jobId, async (tickLogger) => {
-        const truthy = (() => {
-          try {
-            return evaluateBoolean(parsed!, { now: new Date().toISOString() });
-          } catch (error) {
-            tickLogger.warn(
-              `template trigger ${jobId} threw on evaluation — treating as false: ${(error as Error).message}`,
-            );
-            return false;
-          }
-        })();
-        if (truthy && !previousTruthy) {
-          await fire({ firedAt: new Date().toISOString() });
-        }
-        previousTruthy = truthy;
-      });
-      const queue = deps.queueManager.getQueue<BuiltinTriggerTickPayload>(
-        BUILTIN_TRIGGER_QUEUE,
+      "Fires when a health-check numeric field (latency, p95, a collector metric) crosses an above/below threshold. Pair with `for:` for sustained thresholds.",
+    category: "Health",
+    icon: "Gauge",
+    payloadSchema: numericStatePayloadSchema,
+    configSchema: numericStateConfigSchema,
+    // Rides the healthcheck check-completed hook; the threshold gate below
+    // decides whether a given completion fires this automation.
+    hook: createHook<NumericStatePayload>(HEALTHCHECK_CHECK_COMPLETED),
+    contextKey: (payload) => payload.systemId,
+    contextKeyLabel: "system",
+    evaluateConfig: (payload, config) => {
+      // The hook delivers the raw `healthcheck.check.completed` payload
+      // (latencyMs top-level, `result` = collectors map). extractNumericField
+      // knows that shape.
+      const raw = payload as unknown as CheckCompletedPayload;
+      const value = extractNumericField(
+        raw as unknown as Record<string, unknown>,
+        config.field,
       );
-      await queue.scheduleRecurring(
-        { jobId },
-        {
-          jobId,
-          intervalSeconds: config.intervalSeconds,
-          startDelay: config.intervalSeconds,
-        },
-      );
-      logger.debug(
-        `Scheduled template trigger for automation ${identity.automationId}: every ${config.intervalSeconds}s`,
-      );
-      return async () => {
-        tickHandlers.delete(jobId);
-        await queue.cancelRecurring(jobId);
-      };
+      return matchesThreshold({
+        value,
+        above: config.above,
+        below: config.below,
+      });
     },
   };
 }
@@ -329,9 +323,9 @@ export function createTemplateTrigger(
 // ─── Public registry helper ────────────────────────────────────────────
 
 /**
- * Construct all three built-in triggers and register them through the
- * provided callback (which the automation-backend init phase passes
- * straight into the trigger registry).
+ * Construct the built-in triggers and register them through the provided
+ * callback (which the automation-backend init phase passes straight into
+ * the trigger registry).
  */
 export function registerBuiltinTriggers(args: {
   queueManager: QueueManager;
@@ -351,7 +345,10 @@ export function registerBuiltinTriggers(args: {
     args.pluginMetadata,
   );
   args.registerTrigger(
-    createTemplateTrigger(deps) as unknown as TriggerDefinition<unknown, unknown>,
+    createNumericStateTrigger() as unknown as TriggerDefinition<
+      unknown,
+      unknown
+    >,
     args.pluginMetadata,
   );
 }

package/src/dispatch/action-kind.ts

@@ -17,6 +17,7 @@ export type ActionKind =
   | "condition"
   | "stop"
   | "wait_for_trigger"
+  | "wait_until"
   | "sequence";
 
 /**
@@ -35,6 +36,7 @@ export function detectActionKind(action: Action): ActionKind {
   if ("condition" in a) return "condition";
   if ("stop" in a) return "stop";
   if ("wait_for_trigger" in a) return "wait_for_trigger";
+  if ("wait_until" in a) return "wait_until";
   if ("sequence" in a) return "sequence";
   throw new Error(
     `Unknown action shape — none of the discriminator keys are present: ${JSON.stringify(

package/src/dispatch/assemble-get-service.ts

@@ -0,0 +1,31 @@
+import type { ServiceRef } from "@checkstack/backend-api";
+
+/**
+ * Assemble the dispatch engine's `getService` from the plugin `env`.
+ *
+ * The automation dispatch path is the only context that resolves ARBITRARY
+ * cross-plugin service refs (the integration connection store, the secret
+ * resolver) OUTSIDE an RPC handler — at action execute time. It does so
+ * through the plugin `env.getService`, which resolves via the real
+ * `ServiceRegistry` using this plugin's identity.
+ *
+ * This used to be a throwing stub in `index.ts`, which meant every provider
+ * action (Jira / Teams / Webex) and every `secretEnv` script action threw in
+ * production. The whole dispatch test suite stubs `getService`, so the break
+ * was invisible. Extracting the assembly here lets a unit test assert the
+ * production wiring resolves a registered ref (and is NOT a throwing stub),
+ * guarding that exact regression.
+ *
+ * Safe to call from `init` / `afterPluginsReady` onward — dispatch never
+ * runs before then, by which point every service is registered. A missing
+ * ref propagates a CLEAR error from `env.getService` (fail loud), never a
+ * silent `undefined`.
+ */
+export function assembleDispatchGetService({
+  envGetService,
+}: {
+  /** The plugin `env.getService` — registry-backed resolution. */
+  envGetService: <T>(ref: ServiceRef<T>) => Promise<T>;
+}): <T>(ref: ServiceRef<T>) => Promise<T> {
+  return envGetService;
+}

package/src/dispatch/cancel-resurrect.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import { AutomationDefinitionSchema } from "@checkstack/automation-common";
+import type { AutomationStore } from "../automation-store";
+import { createActionRegistry } from "../action-registry";
+import { dispatchTrigger, resumeRun } from "./engine";
+import { handleTriggerFiring } from "./trigger-subscriber";
+import {
+  makeDispatchDeps,
+  makeRecordingAction,
+  testPlugin,
+} from "./test-fixtures";
+import type { LoadedAutomation } from "./types";
+
+const EVENT = "test.event";
+
+function automation(actions: unknown[], mode = "single"): LoadedAutomation {
+  const definition = AutomationDefinitionSchema.parse({
+    name: "Cancel test",
+    triggers: [{ event: EVENT }],
+    conditions: [],
+    actions,
+    mode,
+    max_runs: 10,
+  });
+  return { id: "auto-1", name: "Cancel test", status: "enabled", definition };
+}
+
+function storeFor(auto: LoadedAutomation): AutomationStore {
+  return {
+    create: async () => {
+      throw new Error("nope");
+    },
+    update: async () => {
+      throw new Error("nope");
+    },
+    delete: async () => {},
+    toggle: async () => {
+      throw new Error("nope");
+    },
+    getById: async (id) =>
+      id === auto.id
+        ? {
+            id: auto.id,
+            name: auto.name,
+            description: undefined,
+            status: auto.status,
+            definition: auto.definition,
+            managedBy: undefined,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          }
+        : undefined,
+    list: async () => ({ items: [], total: 0 }),
+    listGroups: async () => [],
+    findEnabledByTriggerEvent: async () => [auto],
+    listEnabled: async () => [auto],
+  };
+}
+
+describe("H1 — cancelled runs must not resurrect", () => {
+  it("a cancelled (restart) run does not resume when its awaited trigger fires", async () => {
+    const actionsReg = createActionRegistry();
+    const rec = makeRecordingAction();
+    actionsReg.register(rec.definition, testPlugin);
+    const { deps, runs, state } = makeDispatchDeps({ actions: actionsReg });
+
+    // A run that opens, waits for a resolve event, then closes.
+    const auto = automation([
+      { action: "test.record", config: { value: "open" } },
+      { wait_for_trigger: { event: "incident.resolved" } },
+      { action: "test.record", config: { value: "close" } },
+    ]);
+
+    const result = await dispatchTrigger(deps, {
+      automation: auto,
+      triggerId: "test_event",
+      triggerEventId: EVENT,
+      payload: {},
+      contextKey: "incident-1",
+    });
+    expect(result.status).toBe("waiting");
+    expect(rec.calls.map((c) => c.value)).toEqual(["open"]);
+    expect(runs.waitLocks.size).toBe(1);
+
+    // Cancel it (restart mode / operator cancel both flip status to
+    // "cancelled" and should tear down the wait lock + run-state).
+    const cancelled = await deps.runStore.cancelActiveRuns(
+      auto.id,
+      "cancelled by test",
+    );
+    expect(cancelled).toContain(result.runId);
+    // The cancel must have removed the wait lock + durable state.
+    expect(runs.waitLocks.size).toBe(0);
+    expect(state.states.has(result.runId)).toBe(false);
+
+    // Now the awaited trigger fires. wakeWaitingRuns must NOT resume the
+    // cancelled run, and the post-wait "close" action must NOT fire.
+    await handleTriggerFiring({
+      deps,
+      automationStore: storeFor(auto),
+      qualifiedEventId: "incident.resolved",
+      triggerPayload: { resolved: true },
+      actor: SYSTEM_ACTOR,
+      contextKey: "incident-1",
+    });
+
+    expect(rec.calls.map((c) => c.value)).toEqual(["open"]);
+    expect(runs.runs.get(result.runId)?.status).toBe("cancelled");
+  });
+
+  it("resumeRun directly refuses a cancelled run and drops any stale lock", async () => {
+    const actionsReg = createActionRegistry();
+    const rec = makeRecordingAction();
+    actionsReg.register(rec.definition, testPlugin);
+    const { deps, runs } = makeDispatchDeps({ actions: actionsReg });
+
+    const auto = automation([
+      { action: "test.record", config: { value: "open" } },
+      { wait_for_trigger: { event: "go" } },
+      { action: "test.record", config: { value: "close" } },
+    ]);
+
+    const result = await dispatchTrigger(deps, {
+      automation: auto,
+      triggerId: "test_event",
+      triggerEventId: EVENT,
+      payload: {},
+      contextKey: null,
+    });
+    expect(result.status).toBe("waiting");
+
+    // Cancel the run but leave a stale wait lock behind (simulating a path
+    // that flipped status without cleanup) — resumeRun must refuse AND drop
+    // the orphaned lock.
+    runs.runs.get(result.runId)!.status = "cancelled";
+
+    const resumed = await resumeRun(deps, {
+      runId: result.runId,
+      automation: auto,
+      waitedAtPath: "actions[1]",
+    });
+    expect(resumed.status).toBe("cancelled");
+    expect(rec.calls.map((c) => c.value)).toEqual(["open"]);
+    expect(runs.waitLocks.size).toBe(0);
+  });
+});