chore: import upstream snapshot with attribution

apps/sim/executor/handlers/wait/wait-handler.test.ts

@@ -0,0 +1,331 @@
+/**
+ * @vitest-environment node
+ */
+import '@sim/testing/mocks/executor'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { BlockType } from '@/executor/constants'
+import { WaitBlockHandler } from '@/executor/handlers/wait/wait-handler'
+import type { ExecutionContext } from '@/executor/types'
+import type { SerializedBlock } from '@/serializer/types'
+
+describe('WaitBlockHandler', () => {
+  let handler: WaitBlockHandler
+  let mockBlock: SerializedBlock
+  let mockContext: ExecutionContext
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+
+    handler = new WaitBlockHandler()
+
+    mockBlock = {
+      id: 'wait-block-1',
+      metadata: { id: BlockType.WAIT, name: 'Test Wait' },
+      position: { x: 50, y: 50 },
+      config: { tool: BlockType.WAIT, params: {} },
+      inputs: { timeValue: 'string', timeUnit: 'string' },
+      outputs: {},
+      enabled: true,
+    }
+
+    mockContext = {
+      workflowId: 'test-workflow-id',
+      blockStates: new Map(),
+      blockLogs: [],
+      metadata: { duration: 0 },
+      environmentVariables: {},
+      decisions: { router: new Map(), condition: new Map() },
+      loopExecutions: new Map(),
+      completedLoops: new Set(),
+      executedBlocks: new Set(),
+      activeExecutionPath: new Set(),
+    }
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('should handle wait blocks', () => {
+    expect(handler.canHandle(mockBlock)).toBe(true)
+    const nonWaitBlock: SerializedBlock = { ...mockBlock, metadata: { id: 'other' } }
+    expect(handler.canHandle(nonWaitBlock)).toBe(false)
+  })
+
+  it('should wait in-process for short waits in seconds', async () => {
+    const inputs = { timeValue: '5', timeUnit: 'seconds' }
+
+    const executePromise = handler.execute(mockContext, mockBlock, inputs)
+
+    await vi.advanceTimersByTimeAsync(5000)
+
+    const result = await executePromise
+
+    expect(result).toEqual({
+      waitDuration: 5000,
+      status: 'completed',
+    })
+  })
+
+  it('should wait in-process for short waits in minutes', async () => {
+    const inputs = { timeValue: '2', timeUnit: 'minutes' }
+
+    const executePromise = handler.execute(mockContext, mockBlock, inputs)
+
+    await vi.advanceTimersByTimeAsync(120_000)
+
+    const result = await executePromise
+
+    expect(result).toEqual({
+      waitDuration: 120_000,
+      status: 'completed',
+    })
+  })
+
+  it('should default to 10 seconds when inputs are not provided', async () => {
+    const executePromise = handler.execute(mockContext, mockBlock, {})
+
+    await vi.advanceTimersByTimeAsync(10_000)
+
+    const result = await executePromise
+
+    expect(result).toEqual({
+      waitDuration: 10_000,
+      status: 'completed',
+    })
+  })
+
+  it('should reject negative wait amounts', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, { timeValue: '-5', timeUnit: 'seconds' })
+    ).rejects.toThrow('Wait amount must be a positive number')
+  })
+
+  it('should reject zero wait amounts', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, { timeValue: '0', timeUnit: 'seconds' })
+    ).rejects.toThrow('Wait amount must be a positive number')
+  })
+
+  it('should reject non-numeric wait amounts', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, { timeValue: 'abc', timeUnit: 'seconds' })
+    ).rejects.toThrow('Wait amount must be a positive number')
+  })
+
+  it('should reject unknown wait units', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, { timeValue: '5', timeUnit: 'fortnights' })
+    ).rejects.toThrow('Unknown wait unit: fortnights')
+  })
+
+  it('should reject async waits longer than the 30-day ceiling', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, {
+        async: true,
+        timeValue: '31',
+        timeUnitLong: 'days',
+      })
+    ).rejects.toThrow('Wait time exceeds maximum of 30 days')
+  })
+
+  it('should reject synchronous waits longer than 5 minutes', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, { timeValue: '10', timeUnit: 'minutes' })
+    ).rejects.toThrow('Wait time exceeds maximum of 5 minutes')
+  })
+
+  it('should default the async unit to minutes when timeUnitLong is missing', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+
+    const result = (await handler.execute(mockContext, mockBlock, {
+      async: true,
+      timeValue: '3',
+    })) as Record<string, any>
+
+    const waitMs = 3 * 60 * 1000
+    expect(result.waitDuration).toBe(waitMs)
+    expect(result.status).toBe('waiting')
+  })
+
+  it('should reject seconds as a unit in async mode', async () => {
+    await expect(
+      handler.execute(mockContext, mockBlock, {
+        async: true,
+        timeValue: '30',
+        timeUnitLong: 'seconds',
+      })
+    ).rejects.toThrow('Seconds are not allowed in async mode')
+  })
+
+  it('should still execute in-process at the 5-minute boundary', async () => {
+    const inputs = { timeValue: '5', timeUnit: 'minutes' }
+
+    const executePromise = handler.execute(mockContext, mockBlock, inputs)
+
+    await vi.advanceTimersByTimeAsync(5 * 60 * 1000)
+
+    const result = await executePromise
+
+    expect(result).toEqual({
+      waitDuration: 5 * 60 * 1000,
+      status: 'completed',
+    })
+  })
+
+  it('should suspend the workflow when wait exceeds the in-process threshold', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+
+    const inputs = { async: true, timeValue: '10', timeUnitLong: 'minutes' }
+
+    const result = (await handler.execute(mockContext, mockBlock, inputs)) as Record<string, any>
+
+    const waitMs = 10 * 60 * 1000
+    const expectedResumeAt = new Date(Date.now() + waitMs).toISOString()
+
+    expect(result.status).toBe('waiting')
+    expect(result.waitDuration).toBe(waitMs)
+    expect(result.resumeAt).toBe(expectedResumeAt)
+
+    const pauseMetadata = result._pauseMetadata
+    expect(pauseMetadata).toBeDefined()
+    expect(pauseMetadata.pauseKind).toBe('time')
+    expect(pauseMetadata.resumeAt).toBe(expectedResumeAt)
+    expect(pauseMetadata.contextId).toBe('wait-block-1')
+    expect(pauseMetadata.blockId).toBe('wait-block-1')
+    expect(pauseMetadata.response).toEqual({ waitDuration: waitMs, resumeAt: expectedResumeAt })
+  })
+
+  it('should suspend the workflow for multi-day waits', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+
+    const inputs = { async: true, timeValue: '2', timeUnitLong: 'days' }
+
+    const result = (await handler.execute(mockContext, mockBlock, inputs)) as Record<string, any>
+
+    const waitMs = 2 * 24 * 60 * 60 * 1000
+    const expectedResumeAt = new Date(Date.now() + waitMs).toISOString()
+
+    expect(result.status).toBe('waiting')
+    expect(result.waitDuration).toBe(waitMs)
+    expect(result.resumeAt).toBe(expectedResumeAt)
+    expect(result._pauseMetadata.pauseKind).toBe('time')
+    expect(result._pauseMetadata.resumeAt).toBe(expectedResumeAt)
+  })
+
+  it('should accept hours and convert to milliseconds', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+
+    const result = (await handler.execute(mockContext, mockBlock, {
+      async: true,
+      timeValue: '3',
+      timeUnitLong: 'hours',
+    })) as Record<string, any>
+
+    const waitMs = 3 * 60 * 60 * 1000
+    expect(result.waitDuration).toBe(waitMs)
+    expect(result.status).toBe('waiting')
+    expect(result._pauseMetadata.pauseKind).toBe('time')
+  })
+
+  it('should handle cancellation via AbortSignal', async () => {
+    const abortController = new AbortController()
+    mockContext.abortSignal = abortController.signal
+
+    const inputs = { timeValue: '30', timeUnit: 'seconds' }
+
+    const executePromise = handler.execute(mockContext, mockBlock, inputs)
+
+    await vi.advanceTimersByTimeAsync(10000)
+    abortController.abort()
+    await vi.advanceTimersByTimeAsync(1)
+
+    const result = await executePromise
+
+    expect(result).toEqual({
+      waitDuration: 30000,
+      status: 'cancelled',
+    })
+  })
+
+  it('should return cancelled immediately if signal is already aborted', async () => {
+    const abortController = new AbortController()
+    abortController.abort()
+    mockContext.abortSignal = abortController.signal
+
+    const inputs = { timeValue: '10', timeUnit: 'seconds' }
+
+    const result = await handler.execute(mockContext, mockBlock, inputs)
+
+    expect(result).toEqual({
+      waitDuration: 10000,
+      status: 'cancelled',
+    })
+  })
+
+  it('should not invoke the in-process sleep when suspending; AbortSignal is irrelevant for long waits', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+    const abortController = new AbortController()
+    abortController.abort()
+    mockContext.abortSignal = abortController.signal
+
+    const result = (await handler.execute(mockContext, mockBlock, {
+      async: true,
+      timeValue: '1',
+      timeUnitLong: 'hours',
+    })) as Record<string, any>
+
+    expect(result.status).toBe('waiting')
+    expect(result._pauseMetadata.pauseKind).toBe('time')
+  })
+
+  it('should preserve fractional time values for larger units', async () => {
+    const inputs = { timeValue: '5.5', timeUnit: 'seconds' }
+
+    const executePromise = handler.execute(mockContext, mockBlock, inputs)
+
+    await vi.advanceTimersByTimeAsync(5500)
+
+    const result = await executePromise
+
+    expect(result).toEqual({
+      waitDuration: 5500,
+      status: 'completed',
+    })
+  })
+
+  it('should suspend a 1.5-day wait without truncating', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+
+    const result = (await handler.execute(mockContext, mockBlock, {
+      async: true,
+      timeValue: '1.5',
+      timeUnitLong: 'days',
+    })) as Record<string, any>
+
+    const waitMs = 1.5 * 24 * 60 * 60 * 1000
+    expect(result.waitDuration).toBe(waitMs)
+    expect(result.status).toBe('waiting')
+    expect(result._pauseMetadata.pauseKind).toBe('time')
+  })
+
+  it('should always suspend when async is enabled, even for short waits', async () => {
+    vi.setSystemTime(new Date('2026-04-28T00:00:00.000Z'))
+
+    const result = (await handler.execute(mockContext, mockBlock, {
+      async: true,
+      timeValue: '2',
+      timeUnitLong: 'minutes',
+    })) as Record<string, any>
+
+    const waitMs = 2 * 60 * 1000
+    const expectedResumeAt = new Date(Date.now() + waitMs).toISOString()
+
+    expect(result.status).toBe('waiting')
+    expect(result.waitDuration).toBe(waitMs)
+    expect(result.resumeAt).toBe(expectedResumeAt)
+    expect(result._pauseMetadata.pauseKind).toBe('time')
+    expect(result._pauseMetadata.resumeAt).toBe(expectedResumeAt)
+  })
+})

apps/sim/executor/handlers/wait/wait-handler.ts

@@ -0,0 +1,197 @@
+import { isExecutionCancelled, isRedisCancellationEnabled } from '@/lib/execution/cancellation'
+import type { BlockOutput } from '@/blocks/types'
+import { BlockType } from '@/executor/constants'
+import {
+  generatePauseContextId,
+  mapNodeMetadataToPauseScopes,
+} from '@/executor/human-in-the-loop/utils'
+import type { BlockHandler, ExecutionContext, PauseMetadata } from '@/executor/types'
+import type { SerializedBlock } from '@/serializer/types'
+
+const CANCELLATION_CHECK_INTERVAL_MS = 500
+
+/** Hard ceiling for in-process (synchronous) waits. */
+const MAX_INPROCESS_WAIT_MS = 5 * 60 * 1000
+
+/** Hard ceiling for async waits. */
+const MAX_ASYNC_WAIT_MS = 30 * 24 * 60 * 60 * 1000
+
+interface SleepOptions {
+  signal?: AbortSignal
+  executionId?: string
+}
+
+const sleep = async (ms: number, options: SleepOptions = {}): Promise<boolean> => {
+  const { signal, executionId } = options
+  const useRedis = isRedisCancellationEnabled() && !!executionId
+
+  if (signal?.aborted) {
+    return false
+  }
+
+  return new Promise((resolve) => {
+    // biome-ignore lint/style/useConst: needs to be declared before cleanup() but assigned later
+    let mainTimeoutId: NodeJS.Timeout | undefined
+    let checkIntervalId: NodeJS.Timeout | undefined
+    let resolved = false
+
+    const cleanup = () => {
+      if (mainTimeoutId) clearTimeout(mainTimeoutId)
+      if (checkIntervalId) clearInterval(checkIntervalId)
+      if (signal) signal.removeEventListener('abort', onAbort)
+    }
+
+    const onAbort = () => {
+      if (resolved) return
+      resolved = true
+      cleanup()
+      resolve(false)
+    }
+
+    if (signal) {
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    if (useRedis) {
+      checkIntervalId = setInterval(async () => {
+        if (resolved) return
+        try {
+          const cancelled = await isExecutionCancelled(executionId!)
+          if (cancelled) {
+            resolved = true
+            cleanup()
+            resolve(false)
+          }
+        } catch {}
+      }, CANCELLATION_CHECK_INTERVAL_MS)
+    }
+
+    mainTimeoutId = setTimeout(() => {
+      if (resolved) return
+      resolved = true
+      cleanup()
+      resolve(true)
+    }, ms)
+  })
+}
+
+const UNIT_TO_MS = {
+  seconds: 1000,
+  minutes: 60 * 1000,
+  hours: 60 * 60 * 1000,
+  days: 24 * 60 * 60 * 1000,
+} as const satisfies Record<string, number>
+
+type WaitUnit = keyof typeof UNIT_TO_MS
+
+function isWaitUnit(value: string): value is WaitUnit {
+  return value in UNIT_TO_MS
+}
+
+/**
+ * Handler for Wait blocks that pause workflow execution for a time delay.
+ *
+ * Default (async=false) waits are held in-process via an interruptible sleep and capped at 5 minutes.
+ * When async=true is set, the workflow is always suspended by returning {@link PauseMetadata} with
+ * `pauseKind: 'time'`; the cron-driven resume poller (see `/api/resume/poll`) picks the execution back
+ * up once `resumeAt` is reached. Async caps at 30 days.
+ */
+export class WaitBlockHandler implements BlockHandler {
+  canHandle(block: SerializedBlock): boolean {
+    return block.metadata?.id === BlockType.WAIT
+  }
+
+  async execute(
+    ctx: ExecutionContext,
+    block: SerializedBlock,
+    inputs: Record<string, any>
+  ): Promise<BlockOutput> {
+    return this.executeWithNode(ctx, block, inputs, { nodeId: block.id })
+  }
+
+  async executeWithNode(
+    ctx: ExecutionContext,
+    block: SerializedBlock,
+    inputs: Record<string, any>,
+    nodeMetadata: {
+      nodeId: string
+      loopId?: string
+      parallelId?: string
+      branchIndex?: number
+      branchTotal?: number
+      originalBlockId?: string
+      isLoopNode?: boolean
+      executionOrder?: number
+    }
+  ): Promise<BlockOutput> {
+    const isAsync = inputs.async === true || inputs.async === 'true'
+    const timeValue = Number.parseFloat(inputs.timeValue || '10')
+    const timeUnit = isAsync ? inputs.timeUnitLong || 'minutes' : inputs.timeUnit || 'seconds'
+
+    if (!Number.isFinite(timeValue) || timeValue <= 0) {
+      throw new Error('Wait amount must be a positive number')
+    }
+
+    if (!isWaitUnit(timeUnit)) {
+      throw new Error(`Unknown wait unit: ${timeUnit}`)
+    }
+
+    if (isAsync && timeUnit === 'seconds') {
+      throw new Error('Seconds are not allowed in async mode')
+    }
+
+    const waitMs = Math.round(timeValue * UNIT_TO_MS[timeUnit])
+
+    if (isAsync) {
+      if (waitMs > MAX_ASYNC_WAIT_MS) {
+        throw new Error('Wait time exceeds maximum of 30 days')
+      }
+    } else if (waitMs > MAX_INPROCESS_WAIT_MS) {
+      throw new Error(
+        'Wait time exceeds maximum of 5 minutes; enable async mode to wait up to 30 days'
+      )
+    }
+
+    if (!isAsync) {
+      const completed = await sleep(waitMs, {
+        signal: ctx.abortSignal,
+        executionId: ctx.executionId,
+      })
+
+      if (!completed) {
+        return {
+          waitDuration: waitMs,
+          status: 'cancelled',
+        }
+      }
+
+      return {
+        waitDuration: waitMs,
+        status: 'completed',
+      }
+    }
+
+    const { parallelScope, loopScope } = mapNodeMetadataToPauseScopes(ctx, nodeMetadata)
+    const contextId = generatePauseContextId(block.id, nodeMetadata, loopScope)
+    const now = new Date()
+    const resumeAt = new Date(now.getTime() + waitMs).toISOString()
+
+    const pauseMetadata: PauseMetadata = {
+      contextId,
+      blockId: nodeMetadata.nodeId,
+      response: { waitDuration: waitMs, resumeAt },
+      timestamp: now.toISOString(),
+      parallelScope,
+      loopScope,
+      pauseKind: 'time',
+      resumeAt,
+    }
+
+    return {
+      waitDuration: waitMs,
+      status: 'waiting',
+      resumeAt,
+      _pauseMetadata: pauseMetadata,
+    }
+  }
+}