PersistentAI API Documentation / @persistentai/fireflow-types / ExecutionContext

Class: ExecutionContext

Defined in: packages/fireflow-types/src/execution/execution-context.ts:55

Constructors

Constructor

new ExecutionContext(flowId, abortController, metadata?, executionId?, integrations?, rootExecutionId?, parentExecutionId?, eventData?, isChildExecution?, executionDepth?, getNodeById?, findNodes?, userId?, onPortResolved?, runnerId?, runnerType?, services?, options?): ExecutionContext

Defined in: packages/fireflow-types/src/execution/execution-context.ts:131

Parameters

flowId

string

abortController

AbortController

metadata?

Record<string, unknown>

executionId?

string

integrations?

objectOutputType<{ external: ZodOptional<ZodRecord<ZodString, ZodAny>>; persistentai: ZodOptional<ZodObject<{ agentID: ZodOptional<ZodString>; agentSession: ZodOptional<ZodString>; chatID: ZodOptional<ZodString>; messageID: ZodOptional<ZodNumber>; }, "strip", ZodTypeAny, { agentID?: string; agentSession?: string; chatID?: string; messageID?: number; }, { agentID?: string; agentSession?: string; chatID?: string; messageID?: number; }>>; wallet: ZodOptional<ZodObject<{ address: ZodOptional<ZodString>; capabilities: ZodOptional<ZodObject<{ supportsBatchTransactions: ZodOptional<ZodBoolean>; supportsEIP1559: ZodOptional<ZodBoolean>; supportsEIP712: ZodOptional<ZodBoolean>; }, "strip", ZodTypeAny, { supportsBatchTransactions?: boolean; supportsEIP1559?: boolean; supportsEIP712?: boolean; }, { supportsBatchTransactions?: boolean; supportsEIP1559?: boolean; supportsEIP712?: boolean; }>>; chainId: ZodOptional<ZodNumber>; ensName: ZodOptional<ZodString>; isConnected: ZodBoolean; lastUpdated: ZodOptional<ZodNumber>; providerType: ZodOptional<ZodString>; rpcUrl: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { address?: string; capabilities?: { supportsBatchTransactions?: boolean; supportsEIP1559?: boolean; supportsEIP712?: boolean; }; chainId?: number; ensName?: string; isConnected: boolean; lastUpdated?: number; providerType?: string; rpcUrl?: string; }, { address?: string; capabilities?: { supportsBatchTransactions?: boolean; supportsEIP1559?: boolean; supportsEIP712?: boolean; }; chainId?: number; ensName?: string; isConnected: boolean; lastUpdated?: number; providerType?: string; rpcUrl?: string; }>>; }, ZodAny, "strip">

rootExecutionId?

string

parentExecutionId?

string

eventData?

eventName

string = ...

payload?

any = ...

isChildExecution?

boolean

executionDepth?

number

getNodeById?

(nodeId) => INode | undefined

findNodes?

(predicate) => INode[] | undefined

userId?

string

onPortResolved?

OnPortResolvedCallback

runnerId?

string

runnerType?

RunnerType

services?

IExecutionServices

options?

breakpoints?

string[] = ...

debug?

boolean = ...

execution?

{ flowTimeoutMs?: number; maxConcurrency?: number; nodeTimeoutMs?: number; } = ...

execution.flowTimeoutMs?

number = ...

execution.maxConcurrency?

number = ...

execution.nodeTimeoutMs?

number = ...

Returns

ExecutionContext

Properties

abortController

readonly abortController: AbortController

Defined in: packages/fireflow-types/src/execution/execution-context.ts:81

currentNodeId?

optional currentNodeId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:95

emittedEvents?

optional emittedEvents: EmittedEvent[]

Defined in: packages/fireflow-types/src/execution/execution-context.ts:92

eventData?

readonly optional eventData: object

Defined in: packages/fireflow-types/src/execution/execution-context.ts:93

eventName

eventName: string

payload?

optional payload: any

executionDepth

readonly executionDepth: number

Defined in: packages/fireflow-types/src/execution/execution-context.ts:96

executionId

readonly executionId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:56

findNodes()

findNodes: (predicate) => INode[] | undefined

Defined in: packages/fireflow-types/src/execution/execution-context.ts:100

Parameters

predicate

(node) => boolean

Returns

INode[] | undefined

flowId?

readonly optional flowId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:79

getNodeById()

getNodeById: (nodeId) => INode | undefined

Defined in: packages/fireflow-types/src/execution/execution-context.ts:98

Parameters

nodeId

string

Returns

INode | undefined

integrations

readonly integrations: objectOutputType

Defined in: packages/fireflow-types/src/execution/execution-context.ts:89

isChildExecution?

readonly optional isChildExecution: boolean

Defined in: packages/fireflow-types/src/execution/execution-context.ts:94

metadata

readonly metadata: Record<string, unknown>

Defined in: packages/fireflow-types/src/execution/execution-context.ts:80

options?

readonly optional options: object

Defined in: packages/fireflow-types/src/execution/execution-context.ts:123

Execution options (timeouts, concurrency, debug settings). Inherited from parent execution for subflows.

breakpoints?

optional breakpoints: string[]

debug?

optional debug: boolean

execution?

optional execution: object

execution.flowTimeoutMs?

optional flowTimeoutMs: number

execution.maxConcurrency?

optional maxConcurrency: number

execution.nodeTimeoutMs?

optional nodeTimeoutMs: number

parentExecutionId?

readonly optional parentExecutionId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:58

rootExecutionId?

readonly optional rootExecutionId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:57

runnerId?

readonly optional runnerId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:66

The ID of the entity that initiated this execution

For 'user' runner type: the userId
For 'flow' runner type: the parent executionId
For 'vfs_trigger' runner type: resolved based on context_mode

runnerType?

readonly optional runnerType: RunnerType

Defined in: packages/fireflow-types/src/execution/execution-context.ts:71

Type of runner that initiated this execution

services?

readonly optional services: IExecutionServices

Defined in: packages/fireflow-types/src/execution/execution-context.ts:117

Services available to nodes for DBOS and VFS operations. Optional for backward compatibility - nodes should check if services exist.

startTime

readonly startTime: Date

Defined in: packages/fireflow-types/src/execution/execution-context.ts:78

userId?

readonly optional userId: string

Defined in: packages/fireflow-types/src/execution/execution-context.ts:76

Deprecated

Use runnerId instead. This field will be removed in a future version.

Accessors

abortSignal

Get Signature

get abortSignal(): AbortSignal

Defined in: packages/fireflow-types/src/execution/execution-context.ts:187

Returns

AbortSignal

Methods

clearWorkHandle()

clearWorkHandle(nodeId): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:483

Clear a work handle after execute() completes.

This is called by the execution engine after a node's execute() phase to free memory. Nodes should not call this directly.

Parameters

nodeId

string

The node ID whose work handle should be cleared

Returns

void

cloneForChildExecution()

cloneForChildExecution(eventData, childExecutionId): ExecutionContext

Defined in: packages/fireflow-types/src/execution/execution-context.ts:247

Clone this context for a child execution

Parameters

eventData

The event data for the child execution

eventName

string = ...

payload?

any = ...

childExecutionId

string

The ID for the child execution

Returns

ExecutionContext

emitEvent()

emitEvent(eventType, data, nodeId): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:228

Emit an event that can trigger listener nodes

Parameters

eventType

string

The type of event to emit

data

any

The event data

nodeId

string

The ID of the node emitting the event (for tracking)

Returns

void

getECDHKeyPair()

getECDHKeyPair(): Promise<CryptoKeyPair>

Defined in: packages/fireflow-types/src/execution/execution-context.ts:191

Returns

Promise<CryptoKeyPair>

getEventsQueue()

getEventsQueue(): EventQueue<ExecutionEvent<ExecutionEventEnum>>

Defined in: packages/fireflow-types/src/execution/execution-context.ts:206

Returns

EventQueue<ExecutionEvent<ExecutionEventEnum>>

getIntegration()

getIntegration<T>(type): T | undefined

Defined in: packages/fireflow-types/src/execution/execution-context.ts:215

Helper method to get a specific integration by type

Type Parameters

T

T = unknown

Parameters

type

string

The integration type to retrieve

Returns

T | undefined

The integration data or undefined if not found

getWorkHandle()

getWorkHandle<T>(nodeId): T | undefined

Defined in: packages/fireflow-types/src/execution/execution-context.ts:471

Retrieve a work handle stored by preExecute().

Type Parameters

T

T = unknown

Parameters

nodeId

string

The node ID that owns the work handle

Returns

T | undefined

The work handle cast to type T, or undefined if not found

Example

// In execute():
const handle = context.getWorkHandle<SubflowHandle>(this.id)
const result = await handle.getResult()

See

docs/design/022-unified-execution-model.md

hasWorkHandle()

hasWorkHandle(nodeId): boolean

Defined in: packages/fireflow-types/src/execution/execution-context.ts:493

Check if a node has a stored work handle.

Parameters

nodeId

string

The node ID to check

Returns

boolean

true if the node has a stored work handle

isPortResolved()

isPortResolved(nodeIdOrPortId, portId?): boolean

Defined in: packages/fireflow-types/src/execution/execution-context.ts:374

Check if a port is resolved.

Parameters

nodeIdOrPortId

string

Node ID (new signature) or Port ID (deprecated signature)

portId?

string

Port ID (new signature only)

Returns

boolean

true if the port is resolved

Example

// New signature (recommended, thread-safe):
context.isPortResolved(this.id, 'outputStream')

// Old signature (deprecated):
context.isPortResolved('outputStream')

publishPortStream()

publishPortStream(nodeId, portId, streamKey): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:432

Announce that a port's stream data is being published to a DBOS stream. The execution engine translates this into a STREAM_PUBLISHED event that the frontend uses to dynamically subscribe to the stream data.

Parameters

nodeId

string

The node publishing the stream

portId

string

The port being streamed

streamKey

string

The DBOS stream key to subscribe to

Returns

void

resolvePort()

resolvePort(nodeIdOrPortId, portId?): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:295

Mark a port as resolved, allowing downstream nodes to begin execution.

Parameters

nodeIdOrPortId

string

Node ID (new signature) or Port ID (deprecated signature)

portId?

string

Port ID (new signature only)

Returns

void

Throws

Error if port not found or called outside execution context

Example

// New signature (recommended, thread-safe):
context.resolvePort(this.id, 'outputStream')

// Old signature (deprecated, not thread-safe in parallel execution):
context.resolvePort('outputStream')

resolvePortWithChildren()

resolvePortWithChildren(nodeId, portId): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:345

Resolve a port and all its nested sub-ports (for object/array ports). Sub-ports have IDs like "parentPort.childField" and are stored in the node's ports Map. Resolving the parent does NOT cascade to children in the PortResolver — each is independent.

Parameters

nodeId

string

portId

string

Returns

void

sendEvent()

sendEvent(event): Promise<void>

Defined in: packages/fireflow-types/src/execution/execution-context.ts:202

Parameters

event

ExecutionEvent

Returns

Promise<void>

setOnPortResolved()

setOnPortResolved(callback): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:411

Set the port resolution callback. This is called by the execution engine to receive port resolution events.

Parameters

callback

OnPortResolvedCallback

The callback to invoke when a port is resolved

Returns

void

setOnStreamPublished()

setOnStreamPublished(callback): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:419

Set the stream publication callback. Called by the execution engine to receive stream publication events.

Parameters

callback

OnStreamPublishedCallback

Returns

void

setWorkHandle()

setWorkHandle(nodeId, handle): void

Defined in: packages/fireflow-types/src/execution/execution-context.ts:454

Store a work handle from preExecute() for later retrieval in execute().

Work handles are typically opaque objects returned by async DBOS operations (e.g., workflow handles from dbos.startSubflow()). The preExecute phase stores the handle, and the execute phase retrieves it to await completion.

Parameters

nodeId

string

The node ID that owns this work handle

handle

unknown

The opaque work handle to store

Returns

void

Example

// In preExecute():
const handle = await dbos.startSubflow(...)
context.setWorkHandle(this.id, handle)
return { resolvedPorts: ['childExecutionId'] }

See

docs/design/022-unified-execution-model.md

types.gen

Type Aliases

Class: ExecutionContext ​

Constructors ​

Constructor ​

Parameters ​

flowId ​

abortController ​

metadata? ​

executionId? ​

integrations? ​

rootExecutionId? ​

parentExecutionId? ​

eventData? ​

eventName ​

payload? ​

isChildExecution? ​

executionDepth? ​

getNodeById? ​

findNodes? ​

userId? ​

onPortResolved? ​

runnerId? ​

runnerType? ​

services? ​

options? ​

breakpoints? ​

debug? ​

execution? ​

execution.flowTimeoutMs? ​

execution.maxConcurrency? ​

execution.nodeTimeoutMs? ​

Returns ​

Properties ​

abortController ​

currentNodeId? ​

emittedEvents? ​

eventData? ​

eventName ​

payload? ​

executionDepth ​

executionId ​

findNodes() ​

Parameters ​

predicate ​

Returns ​

flowId? ​

getNodeById() ​

Parameters ​

nodeId ​

Returns ​

integrations ​

isChildExecution? ​

metadata ​

options? ​

breakpoints? ​

debug? ​

execution? ​

execution.flowTimeoutMs? ​

execution.maxConcurrency? ​

execution.nodeTimeoutMs? ​

parentExecutionId? ​

rootExecutionId? ​

runnerId? ​

runnerType? ​

services? ​

startTime ​

userId? ​

Deprecated ​

Accessors ​

abortSignal ​

Get Signature ​

Returns ​

Methods ​

clearWorkHandle() ​

Parameters ​

nodeId ​

Returns ​

cloneForChildExecution() ​

Parameters ​

Class: ExecutionContext

Constructors

Constructor

Parameters

flowId

abortController

metadata?

executionId?

integrations?

rootExecutionId?

parentExecutionId?

eventData?

eventName

payload?

isChildExecution?

executionDepth?

getNodeById?

findNodes?

userId?

onPortResolved?

runnerId?

runnerType?

services?

options?

breakpoints?

debug?

execution?

execution.flowTimeoutMs?

execution.maxConcurrency?

execution.nodeTimeoutMs?

Returns

Properties

abortController

currentNodeId?

emittedEvents?

eventData?

eventName

payload?

executionDepth

executionId

findNodes()

Parameters

predicate

Returns

flowId?

getNodeById()

Parameters

nodeId

Returns

integrations

isChildExecution?

metadata

options?

breakpoints?

debug?

execution?

execution.flowTimeoutMs?

execution.maxConcurrency?

execution.nodeTimeoutMs?

parentExecutionId?

rootExecutionId?

runnerId?

runnerType?

services?

startTime

userId?

Deprecated

Accessors

abortSignal

Get Signature

Returns

Methods

clearWorkHandle()

Parameters

nodeId

Returns

cloneForChildExecution()

Parameters

eventData

eventName