@flowwright/runtime

@flowwright/runtime executes FlowWright’s validated execution-plan IR. It owns pipeline loading, DAG scheduling, host and Docker execution, caching, artifacts, durable events, and the repositories used by local history and the team control plane.

FlowWright · CLI · Core

Use it

import { validateExecutionPlan } from "@flowwright/core";
import { loadPlan, runPlan } from "@flowwright/runtime";

const plan = await loadPlan("pipeline.ts");
const checked = validateExecutionPlan(plan);

if (!checked.ok) throw new Error(checked.errors[0]?.message);

const result = await runPlan(checked.plan, {
  cwd: process.cwd(),
  env: process.env as Record<string, string>,
  concurrency: 2,
  emit: (event) => console.log(event),
});

Most users interact with this package through the flow CLI. It is public for custom hosts, executors, stores, and integrations.

Public surface

| Area | Main exports | |---|---| | Loading | loadPlan and child-process pipeline loading | | Execution | runPlan, LocalShellExecutor, DockerExecutor, executor interfaces | | Scheduling | Topological stage ordering, bounded concurrency, conditions, retries, and timeouts | | Cache and artifacts | FileCacheStore, cache interfaces, artifact collection and metadata | | Persistence | openRunStore, repository contracts, migrations, run history, worker queue and leases | | Events | Durable run-event recording and replay helpers |

Design boundary

validated plan ──schedule──▶ executor ──emit──▶ typed events
       │                                      │
       └──────── cache · state · artifacts ───┘

• Runtime executes plans; it does not define the authoring DSL or IR contract.
• StepExecutor isolates scheduling from process or container execution.
• Every lifecycle change is emitted as a typed event that reporters and persistence can consume independently.
• Storage interfaces separate execution from the current local persistence implementation.
• HTTP, authentication, projects, users, webhooks, and worker orchestration belong to @flowwright/control-plane.

Development

$ pnpm --filter @flowwright/runtime typecheck
$ pnpm --filter @flowwright/runtime test
$ pnpm --filter @flowwright/runtime build

Tests cover scheduling, cancellation, retries, timeouts, caching, Docker integration, artifacts, migrations, repositories, history, queue claims, and durable events.

Requires Node.js 24+. Licensed under MIT.