@desplega.ai/agent-swarm 1.74.0 → 1.74.2

package/src/tools/workflows/create-workflow.ts

@@ -24,7 +24,12 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
         "Without 'inputs', only 'trigger' and workflow-level 'input' are available for interpolation.\n" +
         "- STRUCTURED OUTPUT: For agent-task nodes, put outputSchema inside 'config' to validate the agent's raw JSON output. " +
         "Node-level outputSchema validates the executor's return ({taskId, taskOutput}), which is different.\n" +
-        "- Agent-task config: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }.",
+        "- Agent-task config: { template, outputSchema?, agentId?, tags?, priority?, dir?, vcsRepo?, model? }.\n" +
+        "- TRIGGER SCHEMA: Optional 'triggerSchema' is a JSON-Schema object that validates incoming trigger payloads. " +
+        "Supported keywords: type, required, properties, enum, const, items (recursive into arrays). " +
+        "Other JSON-Schema keywords (oneOf/anyOf/$ref/pattern/format/additionalProperties) are silently ignored.\n" +
+        "- WAIT NODE: type 'wait' pauses a workflow for a duration or until a named workflowEventBus event arrives. " +
+        "See runbooks/workflows.md#wait-nodes for config shapes, ordering caveats, and built-in event names.",
       inputSchema: z.object({
         name: z.string().describe("Unique name for the workflow"),
         description: z.string().optional().describe("Description of what this workflow does"),
@@ -57,6 +62,14 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
           .min(1)
           .optional()
           .describe("Default VCS repo for all agent-task nodes (e.g. org/repo)"),
+        triggerSchema: z
+          .record(z.string(), z.unknown())
+          .optional()
+          .describe(
+            "Optional JSON-Schema object that validates incoming trigger payloads. " +
+              "Supported keywords: type, required, properties, enum, const, items. " +
+              "Other JSON-Schema keywords are silently ignored.",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().optional(),
@@ -66,7 +79,7 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
       }),
     },
     async (
-      { name, description, definition, triggers, cooldown, input, dir, vcsRepo },
+      { name, description, definition, triggers, cooldown, input, dir, vcsRepo, triggerSchema },
       requestInfo,
     ) => {
       if (!requestInfo.agentId) {
@@ -102,6 +115,7 @@ export const registerCreateWorkflowTool = (server: McpServer) => {
           input,
           dir,
           vcsRepo,
+          triggerSchema,
           createdByAgentId: requestInfo.agentId,
         });
         return {

package/src/tools/workflows/patch-workflow.ts

@@ -2,7 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { getWorkflow, updateWorkflow } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
-import type { WorkflowDefinitionPatch } from "@/types";
+import type { WorkflowPatch } from "@/types";
 import { WorkflowNodePatchSchema } from "@/types";
 import { applyDefinitionPatch, validateDefinition } from "@/workflows/definition";
 import { snapshotWorkflow } from "@/workflows/version";
@@ -14,8 +14,13 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
       title: "Patch Workflow Definition",
       annotations: { destructiveHint: false },
       description:
-        "Partially update a workflow definition by creating, updating, or deleting individual nodes. " +
-        "Operations are applied in order: delete → create → update. " +
+        "Partially update a workflow by creating, updating, or deleting individual nodes, " +
+        "and/or by setting/clearing the trigger payload schema. " +
+        "DAG operations are applied in order: delete → create → update. " +
+        "`triggerSchema` is independent of DAG ops: pass an object to set/replace, " +
+        "pass null to clear, or omit to leave unchanged. " +
+        "Validator subset for `triggerSchema`: type, required, properties, enum, const, items. " +
+        "Other JSON-Schema keywords are silently ignored. " +
         "Creates a version snapshot before applying changes.",
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow ID to patch"),
@@ -48,6 +53,15 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
           .enum(["fail", "continue"])
           .optional()
           .describe("Update onNodeFailure behavior"),
+        triggerSchema: z
+          .record(z.string(), z.unknown())
+          .optional()
+          .nullable()
+          .describe(
+            "Optional JSON-Schema describing the expected trigger payload. " +
+              "Pass an object to set/replace; pass null to clear; omit to leave unchanged. " +
+              "Validator subset: type, required, properties, enum, const, items.",
+          ),
       }),
       outputSchema: z.object({
         success: z.boolean(),
@@ -59,7 +73,7 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
         nodesDeleted: z.number().optional(),
       }),
     },
-    async ({ id, update, delete: del, create, onNodeFailure }, requestInfo) => {
+    async ({ id, update, delete: del, create, onNodeFailure, triggerSchema }, requestInfo) => {
       try {
         const existing = getWorkflow(id);
         if (!existing) {
@@ -72,7 +86,7 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
         const patchResult = applyDefinitionPatch(existing.definition, {
           update,
           delete: del,
-          create: create as WorkflowDefinitionPatch["create"],
+          create: create as WorkflowPatch["create"],
           onNodeFailure,
         });
         if (patchResult.errors.length > 0) {
@@ -94,7 +108,13 @@ export const registerPatchWorkflowTool = (server: McpServer) => {
 
         const version = snapshotWorkflow(id, requestInfo.agentId);
 
-        const workflow = updateWorkflow(id, { definition: patchResult.definition });
+        const updateArgs: Parameters<typeof updateWorkflow>[1] = {
+          definition: patchResult.definition,
+        };
+        if (triggerSchema !== undefined) {
+          updateArgs.triggerSchema = triggerSchema;
+        }
+        const workflow = updateWorkflow(id, updateArgs);
         if (!workflow) {
           return {
             content: [{ type: "text" as const, text: `Workflow not found: ${id}` }],

package/src/tools/workflows/trigger-workflow.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { getWorkflow, getWorkflowRun } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
 import { getExecutorRegistry, startWorkflowExecution } from "@/workflows";
+import { TriggerSchemaError } from "@/workflows/engine";
 
 export const registerTriggerWorkflowTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -11,7 +12,8 @@ export const registerTriggerWorkflowTool = (server: McpServer) => {
       title: "Trigger Workflow",
       annotations: { destructiveHint: false },
       description:
-        "Manually trigger a workflow execution, optionally passing trigger data as context. Respects cooldown configuration.",
+        "Manually trigger a workflow execution, optionally passing trigger data as context. Respects cooldown configuration. " +
+        "If the workflow has a triggerSchema, the payload is validated first; on failure, the response includes structured validationErrors plus the workflow's triggerSchema for self-correction.",
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow ID to trigger"),
         triggerData: z
@@ -24,6 +26,8 @@ export const registerTriggerWorkflowTool = (server: McpServer) => {
         message: z.string(),
         runId: z.string().optional(),
         skipped: z.boolean().optional(),
+        validationErrors: z.array(z.string()).optional(),
+        triggerSchema: z.record(z.string(), z.unknown()).optional(),
       }),
     },
     async ({ id, triggerData }) => {
@@ -86,6 +90,27 @@ export const registerTriggerWorkflowTool = (server: McpServer) => {
           },
         };
       } catch (err) {
+        if (err instanceof TriggerSchemaError) {
+          // Re-fetch workflow so we can echo its triggerSchema for self-correction.
+          // (Workflow existence was already proven above; this is best-effort.)
+          const workflow = getWorkflow(id);
+          const bulleted = err.validationErrors.map((e) => `- ${e}`).join("\n");
+          const schemaBlock = workflow?.triggerSchema
+            ? `\n\nExpected triggerSchema:\n\`\`\`json\n${JSON.stringify(workflow.triggerSchema, null, 2)}\n\`\`\``
+            : "";
+          const text =
+            `Trigger payload did not match the workflow's triggerSchema:\n${bulleted}` +
+            schemaBlock;
+          return {
+            content: [{ type: "text" as const, text }],
+            structuredContent: {
+              success: false,
+              message: `Trigger payload did not match the workflow's triggerSchema (${err.validationErrors.length} error${err.validationErrors.length === 1 ? "" : "s"}).`,
+              validationErrors: err.validationErrors,
+              triggerSchema: workflow?.triggerSchema,
+            },
+          };
+        }
         return {
           content: [{ type: "text" as const, text: `Failed: ${err}` }],
           structuredContent: { success: false, message: String(err) },

package/src/tools/workflows/update-workflow.ts

@@ -18,7 +18,11 @@ export const registerUpdateWorkflowTool = (server: McpServer) => {
       title: "Update Workflow",
       annotations: { destructiveHint: false },
       description:
-        "Update an existing workflow's name, description, definition, triggers, cooldown, input, or enabled state. Creates a version snapshot before applying changes.",
+        "Update an existing workflow's name, description, definition, triggers, cooldown, input, triggerSchema, or enabled state. " +
+        "Creates a version snapshot before applying changes. " +
+        "TRIGGER SCHEMA: pass 'triggerSchema' as a JSON-Schema object to set/replace, or 'null' to clear. " +
+        "Supported JSON-Schema keywords: type, required, properties, enum, const, items (recursive into arrays). " +
+        "Other JSON-Schema keywords (oneOf/anyOf/$ref/pattern/format/additionalProperties) are silently ignored.",
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow ID to update"),
         name: z.string().optional().describe("New name for the workflow"),
@@ -47,6 +51,15 @@ export const registerUpdateWorkflowTool = (server: McpServer) => {
           .nullable()
           .describe("Default VCS repo for all agent-task nodes (null to remove)"),
         enabled: z.boolean().optional().describe("Enable or disable the workflow"),
+        triggerSchema: z
+          .record(z.string(), z.unknown())
+          .optional()
+          .nullable()
+          .describe(
+            "New trigger payload JSON-Schema (null to clear). " +
+              "Supported keywords: type, required, properties, enum, const, items. " +
+              "Other JSON-Schema keywords are silently ignored.",
+          ),
       }),
       outputSchema: z.object({
         success: z.boolean(),
@@ -56,7 +69,19 @@ export const registerUpdateWorkflowTool = (server: McpServer) => {
       }),
     },
     async (
-      { id, name, description, definition, triggers, cooldown, input, dir, vcsRepo, enabled },
+      {
+        id,
+        name,
+        description,
+        definition,
+        triggers,
+        cooldown,
+        input,
+        dir,
+        vcsRepo,
+        enabled,
+        triggerSchema,
+      },
       requestInfo,
     ) => {
       try {
@@ -101,6 +126,7 @@ export const registerUpdateWorkflowTool = (server: McpServer) => {
           dir: dir === null ? null : dir,
           vcsRepo: vcsRepo === null ? null : vcsRepo,
           enabled,
+          triggerSchema: triggerSchema === null ? null : triggerSchema,
         });
         if (!workflow) {
           return {

package/src/types.ts

@@ -811,8 +811,8 @@ export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
 export const WorkflowNodePatchSchema = WorkflowNodeSchema.partial().omit({ id: true });
 export type WorkflowNodePatch = z.infer<typeof WorkflowNodePatchSchema>;
 
-/** Bulk workflow definition patch */
-export const WorkflowDefinitionPatchSchema = z.object({
+/** Bulk workflow patch — DAG operations plus optional metadata fields like triggerSchema */
+export const WorkflowPatchSchema = z.object({
   update: z
     .array(
       z.object({
@@ -828,8 +828,18 @@ export const WorkflowDefinitionPatchSchema = z.object({
     .enum(["fail", "continue"])
     .optional()
     .describe("Update the definition-level onNodeFailure behavior"),
+  triggerSchema: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .nullable()
+    .describe(
+      "Optional JSON-Schema describing the expected trigger payload shape. " +
+        "Pass an object to set/replace; pass null to clear; omit to leave unchanged. " +
+        "Validator subset: type, required, properties, enum, const, items. " +
+        "Other JSON-Schema keywords are silently ignored.",
+    ),
 });
-export type WorkflowDefinitionPatch = z.infer<typeof WorkflowDefinitionPatchSchema>;
+export type WorkflowPatch = z.infer<typeof WorkflowPatchSchema>;
 
 /** Result of applying a patch — collects all errors instead of throwing on the first */
 export interface PatchResult {
@@ -1004,6 +1014,41 @@ export const WorkflowRunStepSchema = z.object({
 });
 export type WorkflowRunStep = z.infer<typeof WorkflowRunStepSchema>;
 
+// --- Wait State (workflow `wait` node side table) ---
+
+export const WaitModeSchema = z.enum(["time", "event"]);
+export type WaitMode = z.infer<typeof WaitModeSchema>;
+
+export const WaitStateStatusSchema = z.enum(["pending", "fired", "timeout"]);
+export type WaitStateStatus = z.infer<typeof WaitStateStatusSchema>;
+
+/**
+ * Row shape for `wait_states` table — keep in sync with
+ * `src/be/migrations/049_wait_states.sql`.
+ *
+ * - `mode='time'`: `wakeUpAt` is set; `eventName`/`eventFilter`/`expiresAt` are null.
+ * - `mode='event'`: `eventName` is set; `eventFilter` is optional (flat
+ *   key/dot-path object OR arrow-fn body string); `expiresAt` is set when the
+ *   wait carries a timeout.
+ */
+export const WaitStateRowSchema = z.object({
+  id: z.string(),
+  workflowRunId: z.string(),
+  workflowRunStepId: z.string(),
+  mode: WaitModeSchema,
+  wakeUpAt: z.string().nullable(),
+  eventName: z.string().nullable(),
+  eventFilter: z.union([z.record(z.string(), z.unknown()), z.string()]).nullable(),
+  expiresAt: z.string().nullable(),
+  status: WaitStateStatusSchema,
+  firedPayload: z.unknown().nullable(),
+  resolvedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  eventScope: z.enum(["run", "global"]),
+});
+export type WaitStateRow = z.infer<typeof WaitStateRowSchema>;
+
 // ============================================================================
 // Prompt Template Types
 // ============================================================================

package/src/workflows/definition.ts

@@ -1,9 +1,9 @@
 import type {
   PatchResult,
   WorkflowDefinition,
-  WorkflowDefinitionPatch,
   WorkflowEdge,
   WorkflowNode,
+  WorkflowPatch,
 } from "../types";
 import type { ExecutorRegistry } from "./executors/registry";
 
@@ -249,10 +249,7 @@ export function validateDefinition(
  * even if earlier ones have errors. Validation of the resulting definition
  * (next refs, entry nodes, etc.) is the caller's responsibility.
  */
-export function applyDefinitionPatch(
-  def: WorkflowDefinition,
-  patch: WorkflowDefinitionPatch,
-): PatchResult {
+export function applyDefinitionPatch(def: WorkflowDefinition, patch: WorkflowPatch): PatchResult {
   const errors: string[] = [];
   let nodes = [...def.nodes];
 

package/src/workflows/executors/index.ts

@@ -14,3 +14,4 @@ export { createExecutorRegistry, ExecutorRegistry } from "./registry";
 export { ScriptExecutor } from "./script";
 export { ValidateExecutor } from "./validate";
 export { VcsExecutor } from "./vcs";
+export { WaitExecutor } from "./wait";

package/src/workflows/executors/registry.ts

@@ -9,6 +9,7 @@ import { RawLlmExecutor } from "./raw-llm";
 import { ScriptExecutor } from "./script";
 import { ValidateExecutor } from "./validate";
 import { VcsExecutor } from "./vcs";
+import { WaitExecutor } from "./wait";
 
 export interface ExecutorTypeInfo {
   type: string;
@@ -73,6 +74,7 @@ export function createExecutorRegistry(deps: ExecutorDependencies): ExecutorRegi
   // Async executors (Phase 4)
   registry.register(new AgentTaskExecutor(deps));
   registry.register(new HumanInTheLoopExecutor(deps));
+  registry.register(new WaitExecutor(deps));
 
   return registry;
 }

package/src/workflows/executors/wait.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import type { ExecutorMeta } from "../../types";
+import { subscribeWaitToBus } from "../resume";
+import { compileStringFilter } from "../wait-filter";
+import type { ExecutorResult } from "./base";
+import { BaseExecutor } from "./base";
+
+// ─── Config / Output Schemas ────────────────────────────────
+
+/**
+ * `wait` node config — discriminated union on `mode`.
+ *
+ * - `mode: "time"`: pause for `durationMs` (1ms..1y; effective resolution ~5s
+ *   from the wait-poller cadence).
+ * - `mode: "event"`: pause until a `workflowEventBus` event named `eventName`
+ *   arrives whose payload satisfies `filter`. The string-form filter is
+ *   capped at 2KB at the Zod boundary as defense-in-depth against pathologically
+ *   large filter sources.
+ */
+const WaitConfigSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("time"),
+    durationMs: z
+      .number()
+      .int()
+      .min(1)
+      .max(31_536_000_000) // 1 year ceiling
+      .describe("Wait duration in milliseconds (effective resolution ~5s)"),
+  }),
+  z.object({
+    mode: z.literal("event"),
+    eventName: z.string().min(1),
+    filter: z.union([z.record(z.string(), z.unknown()), z.string().max(2048)]).optional(),
+    scope: z.enum(["run", "global"]).default("run"),
+    timeoutMs: z
+      .number()
+      .int()
+      .min(1)
+      .max(31_536_000_000)
+      .optional()
+      .describe(
+        "Timeout in milliseconds (effective resolution ~5s) — when reached, routes via 'timeout' port",
+      ),
+  }),
+]);
+
+const WaitOutputSchema = z.object({
+  waitId: z.string().uuid(),
+  mode: z.enum(["time", "event"]),
+  firedAt: z.string().nullable(),
+  payload: z.unknown().optional(),
+});
+
+type WaitOutput = z.infer<typeof WaitOutputSchema>;
+type WaitConfig = z.infer<typeof WaitConfigSchema>;
+
+// ─── Executor ───────────────────────────────────────────────
+
+export class WaitExecutor extends BaseExecutor<typeof WaitConfigSchema, typeof WaitOutputSchema> {
+  readonly type = "wait";
+  readonly mode = "async" as const;
+  readonly configSchema = WaitConfigSchema;
+  readonly outputSchema = WaitOutputSchema;
+
+  protected async execute(
+    config: WaitConfig,
+    _context: Readonly<Record<string, unknown>>,
+    meta: ExecutorMeta,
+  ): Promise<ExecutorResult<WaitOutput>> {
+    const { db } = this.deps;
+
+    // 1. Idempotency check — if a wait_state already exists for this step,
+    // either return the resolved port (resolution happened during retry/recovery)
+    // or return the async marker to keep waiting.
+    const existing = db.getWaitStateByStepId(meta.stepId);
+    if (existing) {
+      if (existing.status !== "pending") {
+        const nextPort = computeNextPort(existing.mode, existing.status);
+        return {
+          status: "success",
+          output: {
+            waitId: existing.id,
+            mode: existing.mode,
+            firedAt: existing.resolvedAt,
+            payload: existing.firedPayload ?? undefined,
+          },
+          nextPort,
+        };
+      }
+      // Still pending — return async marker
+      return {
+        status: "success",
+        async: true,
+        waitFor: "wait.fired",
+        correlationId: existing.id,
+      } as unknown as ExecutorResult<WaitOutput>;
+    }
+
+    // 2. Mode-specific creation.
+    if (config.mode === "time") {
+      const waitId = crypto.randomUUID();
+      const wakeUpAt = new Date(Date.now() + config.durationMs).toISOString();
+      db.createWaitState({
+        id: waitId,
+        workflowRunId: meta.runId,
+        workflowRunStepId: meta.stepId,
+        mode: "time",
+        wakeUpAt,
+      });
+
+      return {
+        status: "success",
+        async: true,
+        waitFor: "wait.fired",
+        correlationId: waitId,
+      } as unknown as ExecutorResult<WaitOutput>;
+    }
+
+    // Event mode: validate the filter at executor-init time (so a bad workflow
+    // surfaces here, not at first event), insert the wait_state row, and
+    // subscribe to the bus so signals route to this wait.
+    if (typeof config.filter === "string") {
+      // Throws on parse error — caught by BaseExecutor.run wrapper and surfaced
+      // as a `failed` ExecutorResult.
+      compileStringFilter(config.filter);
+    }
+
+    const waitId = crypto.randomUUID();
+    const expiresAt = config.timeoutMs
+      ? new Date(Date.now() + config.timeoutMs).toISOString()
+      : null;
+
+    db.createWaitState({
+      id: waitId,
+      workflowRunId: meta.runId,
+      workflowRunStepId: meta.stepId,
+      mode: "event",
+      eventName: config.eventName,
+      eventFilter: config.filter ?? null,
+      expiresAt,
+      scope: config.scope,
+    });
+
+    // Register the bus listener for this event name (idempotent).
+    subscribeWaitToBus(waitId, config.eventName);
+
+    return {
+      status: "success",
+      async: true,
+      waitFor: "wait.fired",
+      correlationId: waitId,
+    } as unknown as ExecutorResult<WaitOutput>;
+  }
+}
+
+/**
+ * Map (mode, status) to the `next` port name.
+ *
+ * - time + fired       → "default" (single happy port)
+ * - event + fired      → "event"
+ * - event + timeout    → "timeout"
+ *
+ * Time mode never produces "timeout" in practice — wait_states for time-mode
+ * waits never set `expiresAt` so the poller will never resolve them as
+ * timeout. We default to "default" anyway as a safe fallback.
+ */
+export function computeNextPort(mode: "time" | "event", status: "fired" | "timeout"): string {
+  if (mode === "time") return "default";
+  return status === "timeout" ? "timeout" : "event";
+}

package/src/workflows/index.ts

@@ -2,21 +2,30 @@ export { findEntryNodes, getSuccessors } from "./definition";
 export { startWorkflowExecution } from "./engine";
 export { workflowEventBus } from "./event-bus";
 export { recoverIncompleteRuns } from "./recovery";
-export { cancelWorkflowRun, retryFailedRun, setupWorkflowResumeListener } from "./resume";
+export {
+  cancelWorkflowRun,
+  initWaitBusSubscriptions,
+  resumeWaitState,
+  retryFailedRun,
+  setupWorkflowResumeListener,
+  subscribeWaitToBus,
+} from "./resume";
 export { startRetryPoller, stopRetryPoller } from "./retry-poller";
 export { interpolate } from "./template";
 export { instantiateTemplate, validateTemplateVariables } from "./templates";
 export { handleScheduleTrigger, handleWebhookTrigger } from "./triggers";
 export { snapshotWorkflow } from "./version";
+export { startWaitPoller, stopWaitPoller } from "./wait-poller";
 
 import * as db from "../be/db";
 import { workflowEventBus } from "./event-bus";
 import type { ExecutorRegistry } from "./executors/registry";
 import { createExecutorRegistry } from "./executors/registry";
 import { recoverIncompleteRuns } from "./recovery";
-import { setupWorkflowResumeListener } from "./resume";
+import { initWaitBusSubscriptions, setupWorkflowResumeListener } from "./resume";
 import { startRetryPoller } from "./retry-poller";
 import { interpolate } from "./template";
+import { startWaitPoller } from "./wait-poller";
 
 // ─── Module-level singleton ────────────────────────────────
 
@@ -58,4 +67,11 @@ export function initWorkflows(): void {
 
   // 4. Start retry poller for failed steps with nextRetryAt
   startRetryPoller(_registry);
+
+  // 5. Start wait poller for time-mode waits + event-mode timeouts
+  startWaitPoller(_registry);
+
+  // 6. Initialize wait-bus subscriptions for event-mode waits (Phase 3).
+  // Re-attaches one bus listener per distinct pending eventName from the DB.
+  initWaitBusSubscriptions(_registry);
 }

package/src/workflows/json-schema-validator.ts

@@ -1,10 +1,17 @@
 /**
  * Minimal hand-rolled JSON Schema validator.
  *
- * Supports the subset needed for workflow I/O schemas:
+ * Supports the subset needed for workflow I/O schemas and `triggerSchema`:
  * - `type`: "object", "string", "number", "boolean", "array"
  * - `required`: array of required property names
  * - `properties`: map of property name → schema (recursive)
+ * - `enum`: array of allowed primitive values (strict equality)
+ * - `const`: a single allowed value (strict equality)
+ * - `items`: schema applied to every element of an array (recursive)
+ *
+ * Other JSON-Schema keywords (`oneOf`, `anyOf`, `$ref`, `pattern`, `format`,
+ * `additionalProperties`, etc.) are silently ignored. Document any new
+ * authoring surface for `triggerSchema` accordingly.
  *
  * Returns an array of validation error strings (empty = valid).
  */

package/src/workflows/recovery.ts

@@ -2,6 +2,7 @@ import {
   getCompletedStepNodeIds,
   getDb,
   getStuckApprovalRuns,
+  getStuckWaitRuns,
   getStuckWorkflowRuns,
   getWorkflow,
   getWorkflowRun,
@@ -13,7 +14,7 @@ import { checkpointStep } from "./checkpoint";
 import { getSuccessors } from "./definition";
 import { findReadyNodes, walkGraph } from "./engine";
 import type { ExecutorRegistry } from "./executors/registry";
-import { finalizeOrWait } from "./resume";
+import { finalizeOrWait, resumeWaitState } from "./resume";
 
 /**
  * Recover incomplete workflow runs on server startup.
@@ -36,6 +37,9 @@ export async function recoverIncompleteRuns(registry: ExecutorRegistry): Promise
   // --- Case 3: Waiting runs whose approval requests may have resolved ---
   recovered += await recoverApprovalWaitingRuns(registry);
 
+  // --- Case 4: Waiting runs whose wait_states are overdue or already resolved ---
+  recovered += await recoverWaitStates(registry);
+
   if (recovered > 0) {
     console.log(`[workflows] Recovered ${recovered} incomplete run(s) on startup`);
   }
@@ -200,6 +204,56 @@ async function recoverApprovalWaitingRuns(registry: ExecutorRegistry): Promise<n
   return recovered;
 }
 
+/**
+ * Recover waiting runs whose `wait_states` rows are either already resolved
+ * (case a — signal arrived / timeout fired while the API was down and the
+ * in-memory bus event was lost) or pending-but-overdue (case b — `wakeUpAt`
+ * or `expiresAt` already past; the wait poller would catch these on its first
+ * tick, but explicit recovery avoids the up-to-5s startup latency window).
+ *
+ * Mirrors `recoverApprovalWaitingRuns`. Time-mode overdue rows resume as
+ * `fired`. Event-mode overdue-but-pending rows resume as `timeout`. Already-
+ * resolved rows resume with their stored status (and stored `firedPayload`
+ * for fired event waits).
+ */
+async function recoverWaitStates(registry: ExecutorRegistry): Promise<number> {
+  const stuckRuns = getStuckWaitRuns();
+  let recovered = 0;
+
+  for (const stuck of stuckRuns) {
+    try {
+      // Decide what status to (re)apply.
+      let resumeStatus: "fired" | "timeout";
+      let payload: unknown;
+
+      if (stuck.waitStatus === "fired") {
+        resumeStatus = "fired";
+        payload = stuck.firedPayload != null ? safeJsonParse(stuck.firedPayload) : undefined;
+      } else if (stuck.waitStatus === "timeout") {
+        resumeStatus = "timeout";
+      } else {
+        // pending + overdue
+        resumeStatus = stuck.waitMode === "time" ? "fired" : "timeout";
+      }
+
+      await resumeWaitState(stuck.waitId, resumeStatus, payload, registry);
+      recovered++;
+    } catch (err) {
+      console.error(`[workflows] Failed to recover wait-state ${stuck.waitId}:`, err);
+    }
+  }
+
+  return recovered;
+}
+
+function safeJsonParse(s: string): unknown {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+
 /**
  * Get run IDs by status. Simple query since there's no dedicated function for this.
  */