Workflow execution lifecycle
Construction inventory before convergence
This inventory comes from repository-wide searches for new WorkflowRunner,
WorkflowRunner(, connectPythonBridgeForGraph, hydrateGraphNodeFlags, and
withExplicitNodeFlags. Paths identify call sites without depending on line
numbers. Tests under tests/ and __tests__/ construct the kernel directly.
| Construction site | Classification | Responsibilities before migration |
|---|---|---|
packages/execution/src/session.ts |
Top-level server execution | Normalize, hydrate, preflight, resolve executors, construct context and runner, connect and close Python, timeout, cancel, live input and properties, message capture, cost ledger, worker boundaries, optional output naming and persistence, scratch cleanup |
packages/execution/src/service/workflow-run.ts |
Top-level server execution | Normalize, metadata hydration, preflight, registry or host resolver, start shared Python worker, workspace context, runner, interactive cancel, progress and terminal persistence, output naming, result presentation. No run timeout or scratch cleanup |
packages/dsl/src/core.ts |
Top-level server execution | Build graph with explicit flags, construct context, caller/global/builtin/Python resolution, connect and close Python, runner, throw on failed result or node error, select last output. No preflight, timeout, persistence, live inputs or property updates |
scripts/run-workflow.mjs |
Top-level server execution | Load file, prepare registry and context, select providers, start local Python worker, resolve executors, runner, print result, close Python on success. No cancellation, timeout or workspace cleanup |
packages/workflow-runner/src/run.ts |
Browser/portable execution | Registry hydration and validation, context and runner, AbortSignal cancellation, queue/wake message streaming, completion and result propagation, listener cleanup. No Python, persistence or output rewriting |
packages/workflow-runner/e2e/src/browser-entry.ts |
Specialized browser harness | Prepare context, registry and sandbox catalog, hydrate graph, runner, record messages and traces, browser test controls. No server lifecycle |
packages/core-nodes/src/nodes/run-inner-graph.ts |
Nested execution | Normalize child graph, inherited metadata and executor resolution, inherited context, runner, failure interpretation and parent output mapping. No independent Python, persistence, timeout or workspace cleanup |
examples/workflow_runner/js/main.js |
Browser execution, different class | Constructs the example’s HTTP/WebSocket client named WorkflowRunner, not the kernel runner. Owns transport and UI |
Electron’s createWorkflowRunner() constructs a client store, not the kernel
runner. README examples are documentation rather than execution entry points.
Boundary
Full Node/server execution uses ExecutionSession. The independently installed
lean server uses the actor lifecycle in
packages/nodes-core/src/index.ts, which
has no dependency on the full session’s Python, model or provider integrations.
These are the two canonical top-level server lifecycle owners. Public APIs keep
their own graph preparation and result presentation. Nested execution can
construct a child kernel runner. Browser execution uses the portable
runWorkflow API. npm run check:execution-boundary enumerates the
exact permitted source files, rejects multiple constructions in an owner, and
checks both kernel and execution-core imports, including aliases and namespaces.
The lean lifecycle validates and hydrates the graph before constructing a runner.
It passes the run’s owner and job IDs, workspace, message emitter and usage callback
to registered node definitions. Its AbortSignal listener calls runner.cancel()
and remains installed until the awaited runner returns a terminal result. The
listener is removed on completion or failure. The authenticated
server-core host owns job persistence,
message replay and terminal usage totals. The node adapter forwards provider
terminal token usage to that host without estimating a monetary cost. This lean
path does not connect Python, install packs or inherit the full session’s timeout
and scratch-cleanup policies.
Session responsibility audit
| Behavior | Ownership |
|---|---|
| Normalize, hydrate, construct runner, cancel, timeout, terminal result | Canonical lifecycle |
| Python connection, worker job boundaries and owned bridge close | Canonical lifecycle. A shared host bridge remains host-owned |
| Scratch cleanup, including setup failure | Canonical lifecycle |
buildWorkspaceExecutionContext |
Server default. An injected context overrides secrets, storage, workspace and generation durability |
| Headless permission gate | Server default, explicitly disabled by hosts preserving another permission policy |
| Cost ledger | Optional integration, enabled by default for existing server callers |
| Durable generation tracking | Context preparation, enabled by the default server context and saved-workflow service. Injected contexts choose their own hooks |
| Output name rewriting | Optional presentation policy, enabled with requireTerminalResult |
| Persistence | Optional host hooks. Job rows, progress, interactive sessions and receipt formatting remain in adapters |
| Buffered message iteration | Portable coordination shared with the browser runner |
The DSL keeps its explicit graph flags and output keys, secret resolver and registry precedence. Its preflight and cost recording remain disabled. Its result adapter throws on failed runs and node error messages.
Adapter changes
DSL run() and runGraph() retain their signatures and return records of the
last value for each nonempty output. Registry resolution stays caller registry,
global registry, builtin packs, then Python. The DSL no longer connects or closes
Python, constructs a runner, or invokes the kernel run method. Graph conversion,
context inputs, registry policy and result-to-exception conversion stay in the
adapter.
The saved-workflow service and scripts/run-workflow.mjs also use the session.
The file runner keeps its existing preflight, permission and cost-recording
policies through explicit options rather than inheriting server defaults.
The service retains ownership checks, preflight before lazy bootstrap, metadata
preparation, job progress, background receipts and interactive verdicts. Its
shared Python bridge now receives session job boundaries without being closed.
Actor failures now produce a canonical failed run. The legacy DSL check for node error messages remains separate from the session and is tested against a message-only result. A cancellation can also retain node errors while reporting a cancelled terminal status.
The session adds these options for known host requirements:
| Option | Requirement |
|---|---|
executorResolverFactory |
DSL registry precedence needs the bridge the session owns |
hasTsExecutor |
Python detection must consult every DSL TS registry |
bridgeOptions |
Preserve DSL remote worker configuration without wrapping bridge lifecycle |
preflight |
Preserve DSL behavior and avoid repeating the service’s pre-bootstrap preflight |
installHeadlessPermissionGate |
Preserve an injected DSL context’s permission policy |
context and recordCosts already existed. The DSL uses them to preserve its
secret resolver and avoid adding persistence.
Behavior verification
The DSL differential tests keep the previous kernel path as an oracle and compare outputs, status, errors and retained messages. Job IDs and durations are excluded. They found no differences. Observable lifecycle changes are scratch cleanup after setup failure, shared-worker job boundaries in service runs, and portable terminal delivery after cancellation. Closing the portable iterator early now cancels the run and waits for it.
Remaining duplication
The saved-workflow service and WebSocket host still prepare metadata before the session hydrates the graph. Moving that preparation requires preserving unknown nodes, list property types and each surface’s output keys. Server preflight is also performed before lazy service bootstrap, using the shared preflight helper. Shared bridge bootstrap stays with the host because its lifetime spans runs. Nested graph normalization and output mapping stay local to the child.