@open-mercato/core 0.6.3-develop.3876.1.d40fe4ec2d → 0.6.3-develop.3894.1.352abf4240

package/src/modules/workflows/components/nodes/WaitForTimerNode.tsx

@@ -0,0 +1,70 @@
+'use client'
+
+import { Handle, Position, NodeProps } from '@xyflow/react'
+import { WorkflowNodeCard } from '../WorkflowNodeCard'
+import { WorkflowStatus } from '../../lib/status-colors'
+
+export interface WaitForTimerNodeData {
+  label: string
+  description?: string
+  duration?: string
+  until?: string
+  config?: { duration?: string; until?: string }
+  version?: number
+  status?: 'pending' | 'running' | 'completed' | 'error' | 'not_started' | 'in_progress'
+  stepNumber?: number
+  badge?: string
+  tooltip?: string
+  executionStatus?: 'completed' | 'active' | 'pending' | 'failed' | 'skipped'
+}
+
+/**
+ * WaitForTimerNode - Pauses workflow for a duration or until a specific datetime
+ * Uses WorkflowNodeCard for consistent styling
+ */
+export function WaitForTimerNode({ data, isConnectable, selected }: NodeProps) {
+  const nodeData = data as unknown as WaitForTimerNodeData
+
+  const mapStatus = (status?: string): WorkflowStatus => {
+    if (!status || status === 'pending') return 'not_started'
+    if (status === 'running' || status === 'in_progress') return 'in_progress'
+    if (status === 'completed') return 'completed'
+    if (status === 'error') return 'not_started'
+    return 'not_started'
+  }
+
+  const workflowStatus = mapStatus(nodeData.status)
+
+  const duration = nodeData.duration || nodeData.config?.duration
+  const until = nodeData.until || nodeData.config?.until
+  const description = nodeData.description ||
+    (duration ? `Wait for ${duration}` : until ? `Wait until ${until}` : 'Timer-based pause')
+
+  return (
+    <div className="wait-for-timer-node" title={nodeData.tooltip}>
+      <Handle
+        type="target"
+        position={Position.Top}
+        id="target"
+        isConnectable={isConnectable}
+        className="!w-3 !h-3 !bg-[#0080FE] !border-2 !border-white"
+      />
+
+      <WorkflowNodeCard
+        title={nodeData.label}
+        description={description}
+        status={workflowStatus}
+        nodeType="waitForTimer"
+        selected={selected}
+      />
+
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        id="source"
+        isConnectable={isConnectable}
+        className="!w-3 !h-3 !bg-[#0080FE] !border-2 !border-white"
+      />
+    </div>
+  )
+}

package/src/modules/workflows/components/nodes/index.ts

@@ -15,3 +15,6 @@ export type { SubWorkflowNodeData } from './SubWorkflowNode'
 
 export { WaitForSignalNode } from './WaitForSignalNode'
 export type { WaitForSignalNodeData } from './WaitForSignalNode'
+
+export { WaitForTimerNode } from './WaitForTimerNode'
+export type { WaitForTimerNodeData } from './WaitForTimerNode'

package/src/modules/workflows/data/validators.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { parseDuration } from '../lib/duration'
 
 /**
  * Workflows Module - Zod Validators
@@ -8,6 +9,40 @@ import { z } from 'zod'
 
 const uuid = z.uuid()
 
+// Variable interpolation tokens (e.g., {{context.timeout}}) are resolved at
+// run time, so we must skip strict syntax checks on them at save time.
+const containsTemplate = (value: string) => value.includes('{{')
+
+export function isValidDurationString(value: unknown): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+  if (containsTemplate(value)) return true
+  try {
+    const ms = parseDuration(value)
+    return Number.isFinite(ms) && ms > 0
+  } catch {
+    return false
+  }
+}
+
+export function isValidIsoDateString(value: unknown): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+  if (containsTemplate(value)) return true
+  const d = new Date(value)
+  return !Number.isNaN(d.getTime())
+}
+
+export function isFutureIsoDateString(value: unknown): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+  if (containsTemplate(value)) return true
+  const d = new Date(value)
+  if (Number.isNaN(d.getTime())) return false
+  return d.getTime() > Date.now()
+}
+
+const DURATION_ERROR = 'Invalid duration. Use ISO 8601 (e.g., PT5M, PT1H, P1D) or simple format (5m, 1h, 3d)'
+const UNTIL_ERROR = 'Invalid "until". Provide an ISO 8601 datetime string'
+const UNTIL_PAST_ERROR = '"until" must be a future datetime'
+
 // ============================================================================
 // Enum Schemas - Workflow Types and Statuses
 // ============================================================================
@@ -169,6 +204,49 @@ export const activityDefinitionSchema = z.object({
     activityId: z.string().min(1), // ID of compensation activity
     automatic: z.boolean().default(true).optional() // Auto-trigger on failure
   }).optional(), // Compensation configuration (Phase 8.2)
+}).superRefine((activity, ctx) => {
+  if (activity.activityType !== 'WAIT') return
+  const config = activity.config || {}
+  const hasDuration = config.duration != null && config.duration !== ''
+  const hasUntil = config.until != null && config.until !== ''
+  if (!hasDuration && !hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT activity requires "duration" or "until"',
+    })
+    return
+  }
+  if (hasDuration && hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT activity accepts "duration" OR "until", not both',
+    })
+    return
+  }
+  if (hasDuration && !isValidDurationString(config.duration)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config', 'duration'],
+      message: DURATION_ERROR,
+    })
+  }
+  if (hasUntil) {
+    if (!isValidIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_ERROR,
+      })
+    } else if (!isFutureIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_PAST_ERROR,
+      })
+    }
+  }
 })
 
 // Localized validation message schema (for START step pre-conditions)
@@ -201,6 +279,49 @@ export const workflowStepSchema = z.object({
   retryPolicy: retryPolicySchema.optional(),
   // Pre-conditions for START step (business rules to validate before workflow can be started)
   preConditions: z.array(startPreConditionSchema).optional(),
+}).superRefine((step, ctx) => {
+  if (step.stepType !== 'WAIT_FOR_TIMER') return
+  const config = step.config || {}
+  const hasDuration = config.duration != null && config.duration !== ''
+  const hasUntil = config.until != null && config.until !== ''
+  if (!hasDuration && !hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT_FOR_TIMER step requires "duration" or "until"',
+    })
+    return
+  }
+  if (hasDuration && hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT_FOR_TIMER step accepts "duration" OR "until", not both',
+    })
+    return
+  }
+  if (hasDuration && !isValidDurationString(config.duration)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config', 'duration'],
+      message: DURATION_ERROR,
+    })
+  }
+  if (hasUntil) {
+    if (!isValidIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_ERROR,
+      })
+    } else if (!isFutureIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_PAST_ERROR,
+      })
+    }
+  }
 })
 
 // Transition condition (reference to business rule)

package/src/modules/workflows/di.ts

@@ -11,6 +11,8 @@ import * as stepHandler from './lib/step-handler'
 import * as transitionHandler from './lib/transition-handler'
 import * as activityExecutor from './lib/activity-executor'
 import * as eventLogger from './lib/event-logger'
+import * as signalHandler from './lib/signal-handler'
+import * as timerHandler from './lib/timer-handler'
 
 export function register(container: AwilixContainer): void {
   container.register({
@@ -19,5 +21,7 @@ export function register(container: AwilixContainer): void {
     transitionHandler: asFunction(() => transitionHandler).scoped(),
     activityExecutor: asFunction(() => activityExecutor).scoped(),
     eventLogger: asFunction(() => eventLogger).scoped(),
+    signalHandler: asFunction(() => signalHandler).scoped(),
+    timerHandler: asFunction(() => timerHandler).scoped(),
   })
 }

package/src/modules/workflows/i18n/de.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Funktion ausführen",
   "workflows.activities.types.SEND_EMAIL": "E-Mail senden",
   "workflows.activities.types.UPDATE_ENTITY": "Entität aktualisieren",
-  "workflows.activities.types.WAIT": "Warten",
+  "workflows.activities.types.WAIT": "Warten / Verzögerung",
+  "workflows.activities.waitDuration": "Dauer",
+  "workflows.activities.waitDurationDescription": "ISO 8601 Dauer (z.B. PT5M für 5 Minuten, PT1H für 1 Stunde, P1D für 1 Tag) oder einfaches Format (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "oder",
+  "workflows.activities.waitUntil": "Warten bis",
+  "workflows.activities.waitUntilDescription": "Bestimmtes Datum und Uhrzeit, bis zu dem gewartet werden soll",
   "workflows.backToList": "Zurück zu Workflows",
   "workflows.backend.definitions.visual_editor.title": "Visueller Workflow-Editor",
   "workflows.checkoutDemo.cart.empty.hint": "Füge Produkte aus dem Dropdown oben hinzu",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "SUB-WORKFLOW",
   "workflows.nodeTypes.userTask": "BENUTZERAUFGABE",
   "workflows.nodeTypes.waitForSignal": "AUF SIGNAL WARTEN",
+  "workflows.nodeTypes.waitForTimer": "AUF TIMER WARTEN",
   "workflows.notifications.task.assigned.body": "Ihnen wurde die Aufgabe \"{taskName}\" im Workflow \"{workflowName}\" zugewiesen{dueDate, select, other { (fällig: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Aufgabe zugewiesen",
   "workflows.orderApproval.approveButton": "Genehmigen",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Deaktiviert",
   "workflows.triggers.title": "Ereignis-Trigger",
   "workflows.validation.descriptionMaxLength": "Beschreibung darf maximal 5000 Zeichen lang sein",
+  "workflows.validation.invalidDuration": "Ungültige Dauer. Verwenden Sie ISO 8601 (z. B. PT5M, PT1H, P1D) oder ein einfaches Format (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Ungültiges Format",
   "workflows.validation.invalidTransition": "Ungültige Übergangskonfiguration",
   "workflows.validation.invalidWorkflowId": "Workflow-ID darf nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche enthalten",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "Alle Schritte müssen verbunden sein",
   "workflows.validation.required": "Dieses Feld ist erforderlich",
   "workflows.validation.uniqueId": "ID muss eindeutig sein",
+  "workflows.validation.untilMustBeFuture": "„Warten bis“ muss ein Datum und eine Uhrzeit in der Zukunft sein.",
   "workflows.validation.workflowIdFormat": "Workflow-ID darf nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche enthalten",
   "workflows.validation.workflowIdMaxLength": "Workflow-ID darf maximal 50 Zeichen lang sein",
   "workflows.validation.workflowIdRequired": "Workflow-ID ist erforderlich",

package/src/modules/workflows/i18n/en.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Execute Function",
   "workflows.activities.types.SEND_EMAIL": "Send Email",
   "workflows.activities.types.UPDATE_ENTITY": "Update Entity",
-  "workflows.activities.types.WAIT": "Wait",
+  "workflows.activities.types.WAIT": "Wait / Delay",
+  "workflows.activities.waitDuration": "Duration",
+  "workflows.activities.waitDurationDescription": "ISO 8601 duration (e.g., PT5M for 5 minutes, PT1H for 1 hour, P1D for 1 day) or simple format (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "or",
+  "workflows.activities.waitUntil": "Wait Until",
+  "workflows.activities.waitUntilDescription": "Specific date and time to wait until",
   "workflows.backToList": "Back to workflows",
   "workflows.backend.definitions.visual_editor.title": "Visual Workflow Editor",
   "workflows.checkoutDemo.cart.empty.hint": "Add products from the dropdown above",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "SUB-WORKFLOW",
   "workflows.nodeTypes.userTask": "USER TASK",
   "workflows.nodeTypes.waitForSignal": "WAIT FOR SIGNAL",
+  "workflows.nodeTypes.waitForTimer": "WAIT FOR TIMER",
   "workflows.notifications.task.assigned.body": "You have been assigned to task \"{taskName}\" in workflow \"{workflowName}\"{dueDate, select, other { (due: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Task Assigned",
   "workflows.orderApproval.approveButton": "Approve",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Disabled",
   "workflows.triggers.title": "Event Triggers",
   "workflows.validation.descriptionMaxLength": "Description must be 5000 characters or less",
+  "workflows.validation.invalidDuration": "Invalid duration. Use ISO 8601 (e.g., PT5M, PT1H, P1D) or simple format (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Invalid format",
   "workflows.validation.invalidTransition": "Invalid transition configuration",
   "workflows.validation.invalidWorkflowId": "Workflow ID can only contain lowercase letters, numbers, hyphens, and underscores",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "All steps must be connected",
   "workflows.validation.required": "This field is required",
   "workflows.validation.uniqueId": "ID must be unique",
+  "workflows.validation.untilMustBeFuture": "Wait Until must be a date and time in the future.",
   "workflows.validation.workflowIdFormat": "Workflow ID must contain only lowercase letters, numbers, hyphens, and underscores",
   "workflows.validation.workflowIdMaxLength": "Workflow ID must be 50 characters or less",
   "workflows.validation.workflowIdRequired": "Workflow ID is required",

package/src/modules/workflows/i18n/es.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Ejecutar funcion",
   "workflows.activities.types.SEND_EMAIL": "Enviar correo electronico",
   "workflows.activities.types.UPDATE_ENTITY": "Actualizar entidad",
-  "workflows.activities.types.WAIT": "Esperar",
+  "workflows.activities.types.WAIT": "Esperar / Retraso",
+  "workflows.activities.waitDuration": "Duración",
+  "workflows.activities.waitDurationDescription": "Duración ISO 8601 (ej. PT5M para 5 minutos, PT1H para 1 hora, P1D para 1 día) o formato simple (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "o",
+  "workflows.activities.waitUntil": "Esperar hasta",
+  "workflows.activities.waitUntilDescription": "Fecha y hora específica hasta la cual esperar",
   "workflows.backToList": "Volver a flujos de trabajo",
   "workflows.backend.definitions.visual_editor.title": "Editor visual de flujos de trabajo",
   "workflows.checkoutDemo.cart.empty.hint": "Añade productos desde el menú desplegable de arriba",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "SUBFLUJO DE TRABAJO",
   "workflows.nodeTypes.userTask": "TAREA DE USUARIO",
   "workflows.nodeTypes.waitForSignal": "ESPERAR SENAL",
+  "workflows.nodeTypes.waitForTimer": "ESPERAR TEMPORIZADOR",
   "workflows.notifications.task.assigned.body": "Se te ha asignado la tarea \"{taskName}\" en el flujo de trabajo \"{workflowName}\"{dueDate, select, other { (vence: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Tarea asignada",
   "workflows.orderApproval.approveButton": "Aprobar",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Deshabilitado",
   "workflows.triggers.title": "Disparadores de eventos",
   "workflows.validation.descriptionMaxLength": "La descripcion debe tener 5000 caracteres o menos",
+  "workflows.validation.invalidDuration": "Duracion no valida. Use ISO 8601 (p. ej. PT5M, PT1H, P1D) o formato simple (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Formato no valido",
   "workflows.validation.invalidTransition": "Configuracion de transicion no valida",
   "workflows.validation.invalidWorkflowId": "El ID del flujo de trabajo solo puede contener letras minusculas, numeros, guiones y guiones bajos",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "Todos los pasos deben estar conectados",
   "workflows.validation.required": "Este campo es obligatorio",
   "workflows.validation.uniqueId": "El ID debe ser unico",
+  "workflows.validation.untilMustBeFuture": "Esperar hasta debe ser una fecha y hora futura.",
   "workflows.validation.workflowIdFormat": "El ID del flujo de trabajo solo puede contener letras minusculas, numeros, guiones y guiones bajos",
   "workflows.validation.workflowIdMaxLength": "El ID del flujo de trabajo debe tener 50 caracteres o menos",
   "workflows.validation.workflowIdRequired": "El ID del flujo de trabajo es obligatorio",

package/src/modules/workflows/i18n/pl.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Wykonaj Funkcję",
   "workflows.activities.types.SEND_EMAIL": "Wyślij Email",
   "workflows.activities.types.UPDATE_ENTITY": "Zaktualizuj Encję",
-  "workflows.activities.types.WAIT": "Czekaj",
+  "workflows.activities.types.WAIT": "Czekaj / Opóźnienie",
+  "workflows.activities.waitDuration": "Czas trwania",
+  "workflows.activities.waitDurationDescription": "Format ISO 8601 (np. PT5M dla 5 minut, PT1H dla 1 godziny, P1D dla 1 dnia) lub prosty format (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "lub",
+  "workflows.activities.waitUntil": "Czekaj do",
+  "workflows.activities.waitUntilDescription": "Konkretna data i godzina, do której czekać",
   "workflows.backToList": "Powrót do przepływów",
   "workflows.backend.definitions.visual_editor.title": "Wizualny Edytor Przepływów Pracy",
   "workflows.checkoutDemo.cart.empty.hint": "Dodaj produkty z listy powyżej",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "PODPRZEPŁYW",
   "workflows.nodeTypes.userTask": "ZADANIE UŻYTKOWNIKA",
   "workflows.nodeTypes.waitForSignal": "CZEKAJ NA SYGNAŁ",
+  "workflows.nodeTypes.waitForTimer": "CZEKAJ NA TIMER",
   "workflows.notifications.task.assigned.body": "Przypisano Ci zadanie \"{taskName}\" w przepływie \"{workflowName}\"{dueDate, select, other { (termin: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Przypisano Zadanie",
   "workflows.orderApproval.approveButton": "Zatwierdź",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Wyłączony",
   "workflows.triggers.title": "Wyzwalacze Zdarzeń",
   "workflows.validation.descriptionMaxLength": "Opis musi mieć 5000 znaków lub mniej",
+  "workflows.validation.invalidDuration": "Nieprawidłowy czas trwania. Użyj formatu ISO 8601 (np. PT5M, PT1H, P1D) lub uproszczonego (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Nieprawidłowy format",
   "workflows.validation.invalidTransition": "Nieprawidłowa konfiguracja przejścia",
   "workflows.validation.invalidWorkflowId": "ID przepływu może zawierać tylko małe litery, cyfry, myślniki i podkreślenia",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "Wszystkie kroki muszą być połączone",
   "workflows.validation.required": "To pole jest wymagane",
   "workflows.validation.uniqueId": "ID musi być unikalne",
+  "workflows.validation.untilMustBeFuture": "„Czekaj do” musi być datą i godziną w przyszłości.",
   "workflows.validation.workflowIdFormat": "ID przepływu może zawierać tylko małe litery, cyfry, myślniki i podkreślenia",
   "workflows.validation.workflowIdMaxLength": "ID przepływu musi mieć 50 znaków lub mniej",
   "workflows.validation.workflowIdRequired": "ID przepływu jest wymagane",

package/src/modules/workflows/lib/activity-executor.ts

@@ -25,6 +25,7 @@ import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { callWebhookConfigSchema } from '../data/validators'
 import { WorkflowActivityJob, WORKFLOW_ACTIVITIES_QUEUE_NAME } from './activity-queue-types'
 import { logWorkflowEvent } from './event-logger'
+import { parseDuration } from './duration'
 
 export { isPrivateUrl } from '@open-mercato/shared/lib/network'
 
@@ -54,6 +55,7 @@ export type ActivityType =
   | 'UPDATE_ENTITY'
   | 'CALL_WEBHOOK'
   | 'EXECUTE_FUNCTION'
+  | 'WAIT'
 
 export interface ActivityDefinition {
   activityId: string // Unique identifier for activity
@@ -164,9 +166,12 @@ export async function enqueueActivity(
     userId: context.userId,
   }
 
-  // Enqueue to queue
+  // Enqueue to queue (WAIT activities use delayMs for the actual delay)
   const queue = getActivityQueue()
-  const jobId = await queue.enqueue(job)
+  const enqueueOptions = activity.activityType === 'WAIT' && (interpolatedConfig.duration || interpolatedConfig.until)
+    ? { delayMs: calculateWaitDelayMs(interpolatedConfig) }
+    : undefined
+  const jobId = await queue.enqueue(job, enqueueOptions)
 
   // Log event
   await logWorkflowEvent(em, {
@@ -187,6 +192,41 @@ export async function enqueueActivity(
   return jobId
 }
 
+/**
+ * Enqueue a delayed timer job for a WAIT_FOR_TIMER step.
+ *
+ * The activity worker handles `kind: 'timer'` jobs by calling
+ * `timerHandler.fireTimer`, which resumes the paused workflow instance.
+ */
+export async function enqueueTimerJob(params: {
+  workflowInstanceId: string
+  stepInstanceId: string
+  tenantId: string
+  organizationId: string
+  userId?: string
+  fireAt: string
+  delayMs: number
+}): Promise<string> {
+  const { workflowInstanceId, stepInstanceId, tenantId, organizationId, userId, fireAt, delayMs } =
+    params
+
+  const queue = getActivityQueue()
+  const jobId = await queue.enqueue(
+    {
+      kind: 'timer',
+      workflowInstanceId,
+      stepInstanceId,
+      tenantId,
+      organizationId,
+      userId,
+      fireAt,
+    },
+    { delayMs: delayMs > 0 ? delayMs : undefined }
+  )
+
+  return jobId
+}
+
 // ============================================================================
 // Main Activity Execution Functions
 // ============================================================================
@@ -377,6 +417,9 @@ async function executeActivityByType(
     case 'EXECUTE_FUNCTION':
       return await executeFunction(interpolatedConfig, context, container)
 
+    case 'WAIT':
+      return await executeWait(interpolatedConfig)
+
     default:
       throw new ActivityExecutionError(
         `Unknown activity type: ${activity.activityType}`,
@@ -750,6 +793,47 @@ export async function executeFunction(
   }
 }
 
+/**
+ * Calculate delay in milliseconds from a WAIT activity config.
+ * Supports either `duration` (relative, e.g. "PT5M") or `until` (absolute ISO 8601 datetime).
+ */
+function calculateWaitDelayMs(config: { duration?: string; until?: string }): number {
+  if (config.until) {
+    const targetDate = new Date(config.until)
+    if (isNaN(targetDate.getTime())) {
+      throw new Error(`WAIT activity: invalid "until" datetime: ${config.until}`)
+    }
+    const delayMs = targetDate.getTime() - Date.now()
+    return Math.max(0, delayMs)
+  }
+
+  if (config.duration) {
+    return parseDuration(config.duration)
+  }
+
+  throw new Error('WAIT activity requires "duration" (e.g., "PT5M", "1h") or "until" (ISO 8601 datetime)')
+}
+
+/**
+ * WAIT activity handler
+ *
+ * Delays workflow execution for a configured duration or until a specific datetime.
+ * - `duration`: relative delay (e.g. "PT5M", "1h", "30s")
+ * - `until`: absolute datetime (e.g. "2026-04-15T10:00:00Z")
+ * - Sync mode: blocks via sleep (suitable for short delays)
+ * - Async mode: delay is handled by the queue's delayMs option;
+ *   this handler returns immediately when called from the worker
+ */
+async function executeWait(config: any): Promise<any> {
+  const durationMs = calculateWaitDelayMs(config)
+
+  // In sync mode, actually sleep for the duration
+  // In async mode (called from worker), the delay already happened via queue scheduling
+  await sleep(durationMs)
+
+  return { waited: true, durationMs }
+}
+
 /**
  * CALL_API activity handler
  *

package/src/modules/workflows/lib/activity-queue-types.ts

@@ -2,25 +2,31 @@
  * Workflow Activity Queue Types
  *
  * Type definitions for async activity execution via queue system.
+ * Jobs are discriminated by the optional `kind` field:
+ *   - `'activity'` (default, back-compat): background execution of a workflow activity
+ *   - `'timer'`: delayed fire-timer job for a WAIT_FOR_TIMER step
  */
 
-export interface WorkflowActivityJob {
-  // Execution context
+export interface WorkflowActivityJobBase {
   workflowInstanceId: string
   stepInstanceId?: string
+  tenantId: string
+  organizationId: string
+  userId?: string
+}
+
+export interface WorkflowActivityJobActivity extends WorkflowActivityJobBase {
+  kind?: 'activity'
   transitionId?: string
 
-  // Activity definition
   activityId: string
   activityName: string
   activityType: string
   activityConfig: any
 
-  // Workflow context (for execution)
   workflowContext: Record<string, any>
   stepContext?: Record<string, any>
 
-  // Retry & timeout config
   retryPolicy?: {
     maxAttempts: number
     initialIntervalMs: number
@@ -28,13 +34,14 @@ export interface WorkflowActivityJob {
     maxIntervalMs: number
   }
   timeoutMs?: number
+}
 
-  // Multi-tenant
-  tenantId: string
-  organizationId: string
-
-  // Metadata
-  userId?: string
+export interface WorkflowActivityJobTimer extends WorkflowActivityJobBase {
+  kind: 'timer'
+  stepInstanceId: string
+  fireAt: string // ISO 8601 timestamp for when the timer should fire
 }
 
+export type WorkflowActivityJob = WorkflowActivityJobActivity | WorkflowActivityJobTimer
+
 export const WORKFLOW_ACTIVITIES_QUEUE_NAME = 'workflow-activities'

package/src/modules/workflows/lib/activity-worker-handler.ts

@@ -34,6 +34,31 @@ export function createActivityWorkerHandler(
     const { payload } = job
     const startTime = Date.now()
 
+    // Timer jobs (kind: 'timer') are a distinct flow — they resume a paused
+    // workflow instance rather than executing an activity. Handle them first.
+    if (payload.kind === 'timer') {
+      console.log(
+        `[ActivityWorker] Firing timer for instance ${payload.workflowInstanceId} (job ${ctx.jobId})`
+      )
+      try {
+        const { fireTimer } = await import('./timer-handler')
+        await fireTimer(em, container, {
+          instanceId: payload.workflowInstanceId,
+          stepInstanceId: payload.stepInstanceId,
+          tenantId: payload.tenantId,
+          organizationId: payload.organizationId,
+          userId: payload.userId,
+        })
+      } catch (error: any) {
+        console.error(
+          `[ActivityWorker] Failed to fire timer for instance ${payload.workflowInstanceId}:`,
+          error.message
+        )
+        throw error
+      }
+      return
+    }
+
     console.log(
       `[ActivityWorker] Processing activity ${payload.activityId} (job ${ctx.jobId})`
     )
@@ -79,6 +104,10 @@ export function createActivityWorkerHandler(
             return await executeCallWebhook(payload.activityConfig, activityContext)
           case 'EXECUTE_FUNCTION':
             return await executeFunction(payload.activityConfig, activityContext, container)
+          case 'WAIT':
+            // Delay already applied by the queue via delayMs; the worker
+            // only needs to record completion so the workflow can resume.
+            return { waited: true, async: true }
           default:
             throw new Error(`Unsupported activity type: ${payload.activityType}`)
         }