Node Executor

@module automation/node-executor

Node Executor Plugin Protocol — Wait Node Pause/Resume

Defines the specification for node executor plugins, with a focus on

the wait node executor that supports flow pause and external-event

resume (signal, manual, webhook, condition).

The protocol covers:

WaitResumePayload: The payload delivered when a paused flow is resumed
WaitExecutorConfig: Configuration for the wait executor plugin
NodeExecutorDescriptor: Generic node executor plugin descriptor

Source: packages/spec/src/automation/node-executor.zod.ts

TypeScript Usage

import { ActionCategory, ActionDescriptor, ActionParadigm, NodeExecutorDescriptor, WaitEventType, WaitExecutorConfig, WaitResumePayload, WaitTimeoutBehavior } from '@objectstack/spec/automation';
import type { ActionCategory, ActionDescriptor, ActionParadigm, NodeExecutorDescriptor, WaitEventType, WaitExecutorConfig, WaitResumePayload, WaitTimeoutBehavior } from '@objectstack/spec/automation';

// Validate data
const result = ActionCategory.parse(data);

ActionCategory

Action palette category

Allowed Values

logic
data
io
human
control
custom

ActionDescriptor

Canonical cross-paradigm action/node descriptor (ADR-0018)

Properties

Property	Type	Required	Description
type	`string`	✅	Registry action/node type (matches the executor type)
version	`string`	✅	Executor version (semver)
name	`string`	✅	Display label (or i18n key)
description	`string`	optional	Action description
icon	`string`	optional	Icon id resolved by the designer
category	`Enum<'logic' \| 'data' \| 'io' \| 'human' \| 'control' \| 'custom'>`	✅	Palette category
paradigms	`Enum<'flow' \| 'workflow_rule' \| 'approval'>[]`	✅	Authoring surfaces that may offer this action
configSchema	`any`	optional	JSON Schema for the node config (drives form + parse validation)
supportsPause	`boolean`	✅	Supports async pause/resume
supportsCancellation	`boolean`	✅	Supports cancellation
supportsRetry	`boolean`	✅	Supports retry on failure
needsOutbox	`boolean`	✅	Dispatch via service-messaging outbox (retry/idempotency/dead-letter)
isAsync	`boolean`	✅	Suspends the flow awaiting an external reply
source	`Enum<'builtin' \| 'plugin'>`	✅	builtin = platform baseline; plugin = third-party contributed
deprecated	`boolean`	✅	Deprecated alias kept for back-compat
aliasOf	`string`	optional	Canonical type this alias forwards to

ActionParadigm

Authoring paradigm that may offer this action

Allowed Values

flow
workflow_rule
approval

NodeExecutorDescriptor

Node executor plugin descriptor

Properties

Property	Type	Required	Description
id	`string`	✅	Unique executor plugin identifier
name	`string`	✅	Display name
nodeTypes	`string[]`	✅	FlowNodeAction types this executor handles
version	`string`	✅	Plugin version (semver)
description	`string`	optional	Executor description
supportsPause	`boolean`	✅	Whether the executor supports async pause/resume
supportsCancellation	`boolean`	✅	Whether the executor supports mid-execution cancellation
supportsRetry	`boolean`	✅	Whether the executor supports retry on failure
configSchemaRef	`string`	optional	JSON Schema $ref for executor-specific config

WaitEventType

Wait event type determining how a paused flow is resumed

Allowed Values

timer
signal
webhook
manual
condition

WaitExecutorConfig

Wait node executor plugin configuration

Properties

Property	Type	Required	Description
defaultTimeoutMs	`integer`	✅	Default timeout in ms (default: 24 hours)
defaultTimeoutBehavior	`Enum<'fail' \| 'continue' \| 'fallback'>`	✅	Default behavior when wait timeout is exceeded
conditionPollIntervalMs	`integer`	✅	Polling interval for condition waits in ms (default: 30s)
conditionMaxPolls	`integer`	✅	Max polling attempts for condition waits (0 = unlimited)
webhookUrlPattern	`string`	✅	URL pattern for webhook resume endpoints
persistCheckpoints	`boolean`	✅	Persist wait checkpoints to durable storage
maxPausedExecutions	`integer`	✅	Max concurrent paused executions (0 = unlimited)

WaitResumePayload

Payload for resuming a paused wait node

Properties

Property	Type	Required	Description
executionId	`string`	✅	Execution ID of the paused flow
checkpointId	`string`	✅	Checkpoint ID to resume from
nodeId	`string`	✅	Wait node ID being resumed
eventType	`Enum<'timer' \| 'signal' \| 'webhook' \| 'manual' \| 'condition'>`	✅	Event type that triggered resume
signalName	`string`	optional	Signal name (when eventType is signal)
webhookPayload	`Record<string, any>`	optional	Webhook request payload (when eventType is webhook)
resumedBy	`string`	optional	User ID or system identifier that triggered resume
resumedAt	`string`	✅	ISO 8601 timestamp of the resume event
variables	`Record<string, any>`	optional	Variables to merge into flow context upon resume

WaitTimeoutBehavior

Behavior when a wait node exceeds its timeout

Allowed Values

fail
continue
fallback

On this page