@persistent-ai/fireflow-executor / server / ExecutionWorkflows

Class: ExecutionWorkflows

Defined in: packages/fireflow-executor/server/dbos/workflows/ExecutionWorkflows.ts:119

Class-based DBOS workflow for executing fireflow flows

This class provides the main entry point for executing fireflow flows using DBOS. Uses the @DBOS.workflow() decorator for durable execution guarantees.

Signal Pattern:

• Workflow starts immediately but waits for START_SIGNAL before executing
• This allows clients to subscribe to the event stream before execution begins

Command Loop Pattern (Debug Mode Only):

• Command polling (PAUSE/RESUME/STEP/STOP) is ONLY enabled when task.debug=true
• In production mode (debug=false): Zero overhead - no polling, no recv() calls
• In debug mode: Command loop runs in background, awaited after execution completes
• No overlapping recv() calls - single sequential loop

DBOS Durability Guarantees:

• Each step is checkpointed in PostgreSQL
• If the worker crashes, DBOS automatically resumes from the last completed step
• The workflow is guaranteed to run to completion (at-least-once semantics)
• Idempotency is ensured through workflow ID (executionId)

Extends

• ConfiguredInstance

Constructors

Constructor

new ExecutionWorkflows(name?): ExecutionWorkflows

Defined in: packages/fireflow-executor/server/dbos/workflows/ExecutionWorkflows.ts:120

Parameters

name?

string = 'ExecutionWorkflows'

Returns

ExecutionWorkflows

Overrides

ConfiguredInstance.constructor

Properties

name

readonly name: string

Defined in: node_modules/.pnpm/@[email protected][email protected][email protected][email protected]/node_modules/@dbos-inc/dbos-sdk/dist/src/decorators.d.ts:137

Inherited from

ConfiguredInstance.name

Methods

initialize()

initialize(): Promise<void>

Defined in: packages/fireflow-executor/server/dbos/workflows/ExecutionWorkflows.ts:124

Override this method to perform async initialization between construction and DBOS.launch().

Returns

Promise<void>

Overrides

ConfiguredInstance.initialize

---

executeFireFlow()

static executeFireFlow(task): Promise<ExecutionResult>

Defined in: packages/fireflow-executor/server/dbos/workflows/ExecutionWorkflows.ts:149

Execute a fireflow flow with durable workflow orchestration.

Public DBOS workflow entry point. Used by:

• tRPC executionRouter.create path (after the executions row has been provisioned by the router).
• Internal child-execution spawning (line ~530, where each emitted event becomes a fresh workflow with its own ID).

External callers that do NOT pre-provision the executions row (e.g. Flame Chorus enqueueing from Go via cross-language DBOS) should target provisionAndExecuteFireFlow instead — it inserts the row, then delegates to the same underlying pipeline inside the same workflow context (so the caller-supplied workflowID remains the one that owns the agui:events / events streams).

Parameters

task

ExecutionTask

Execution task containing executionId and flowId

Returns

Promise<ExecutionResult>

Execution result with status and duration

---

provisionAndExecuteAgentFlow()

static provisionAndExecuteAgentFlow(input): Promise<ExecutionResult>

Defined in: packages/fireflow-executor/server/dbos/workflows/ExecutionWorkflows.ts:202

Dedicated cross-language entrypoint for launching AGENT flows from external services (Flame Chorus / PersistentAI chat).

Difference from the generic provisionAndExecuteFireFlow: the human who triggered the run is an EXTERNAL identity (e.g. a PersistentAI user id), not a FireFlow USR. This entrypoint maps input.caller to a real FireFlow user via getOrCreateUserByExternalAccount (idempotent, race-safe, replay-safe inside a DBOS step) and overwrites integration.createdBy with that USR before running the shared pipeline.

The result: the execution's callerId is always a real FireFlow user, so dual-identity resolution (caller-scoped VFS / secrets, personal workspace) works honestly instead of silently failing on a foreign id. Using provider 'persistentai' unifies this with the editor's PersistentAI-session login — the same person resolves to one USR across chat and editor.

Personal-workspace creation stays LAZY (on first caller-VFS access); this entrypoint only guarantees the user record exists.

Parameters

input

ProvisionAndExecuteFireFlowInput

Returns

Promise<ExecutionResult>

---

provisionAndExecuteFireFlow()

static provisionAndExecuteFireFlow(input): Promise<ExecutionResult>

Defined in: packages/fireflow-executor/server/dbos/workflows/ExecutionWorkflows.ts:172

DBOS workflow that provisions an executions row and then runs the standard FireFlow execution pipeline INSIDE THE SAME WORKFLOW (same workflowID).

This is the entry point used by Flame Chorus (or any external service) when enqueueing via cross-language DBOS without going through the tRPC router. The caller-supplied executionId is also the DBOS workflowID, which is what the caller will read the events / agui:events stream by.

Implementation detail: the underlying pipeline lives in the non-decorated private helper runFireFlowExecution. Calling it directly (not via DBOS.startWorkflow) keeps the entire pipeline — including all DBOS.runStep and DBOS.writeStream calls — inside this wrapper's workflow context, so the streams are keyed by the wrapper's workflowID (== input.executionId).

Parameters

input

ProvisionAndExecuteFireFlowInput

Returns

Promise<ExecutionResult>