Engine methods

Methods on the Engine returned by createEngine.

engine.start(pollIntervalMs?)

Initializes storage and starts the polling loop, running tick() every pollIntervalMs (default 1000). Call once at startup. Returns Promise<void>.

engine.stop()

Stops the polling loop, clears all schedules, ends all open streams, aborts in-flight steps, and waits for any in-flight tick to finish. In-flight runs are left running so they can be reclaimed. Returns Promise<void>.

engine.tick()

Claims up to concurrency pending or stale runs and executes them in parallel. Useful for CLI tools and tests. If you use tick() without start(), call storage.initialize() first. Returns Promise<void>.

engine.enqueue(name, input, options?)

Submits a run. Type-safe — only accepts registered workflow names with matching input. Returns the created WorkflowRun (use run.id to track it).

Option	Type	Description
idempotencyKey	string	Same key + same input returns the existing run; same key + different input throws IdempotencyConflictError

Throws WorkflowNotFoundError for an unknown name and ValidationError if input fails the schema.

engine.stream(options?)

Returns a pull-based ResultStream — an AsyncIterableIterator<EngineEvent> (and AsyncDisposable) of execution events. Each call returns an independent stream.

Option	Type	Default	Description
bufferSize	number	Infinity	Max events buffered before the engine pauses (backpressure). 0 = strict rendezvous; any non-negative integer allows that many buffered events.

Invalid bufferSize (negative, or a non-integer that isn't Infinity) throws ConfigError. Breaking out of the loop, await using, or engine.stop() unsubscribes automatically. See Streaming Results.

engine.cancel(runId)

Cancels a pending or running workflow. Returns true if cancelled, false if it already completed / failed / cancelled. Aborts the current step's AbortSignal immediately. See Cancellation.

engine.schedule(name, input, intervalMs)

Enqueues a run on a recurring interval. Returns a scheduleId string. Validates name and input immediately. See Scheduled Workflows.

engine.unschedule(scheduleId)

Cancels a recurring schedule by id. Returns true if a schedule was removed, false otherwise.

engine.getRunStatus(runId)

Returns { run, steps } — the run's current status and all its step results — or null if the run is not found.

const info = await engine.getRunStatus(run.id)
info?.run.status // 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
info?.steps      // StepResult[]