@runflow-ai/flow-compiler

Bidirectional compiler between visual FlowGraph JSON and Runflow SDK TypeScript code.

The visual flow editor (Flows / Agent Builder) is a projection of the canonical agent code. This package is the bridge: it compiles a graph into runnable SDK code and (in the beta roadmap) parses code back into a graph.

Install

npm install @runflow-ai/flow-compiler

Inside the Runflow monorepo it is consumed via npm workspaces by apps/api-portal and apps/portal (the latter only imports types).

Usage

import { compile, validate, FlowGraph } from '@runflow-ai/flow-compiler';

const graph: FlowGraph = {
  id: 'support_agent',
  name: 'Support Agent',
  nodes: [
    { id: 'start_1', kind: 'start', config: {} },
    { id: 'classify', kind: 'agent', config: {
      agentName: 'classifier',
      model: { provider: 'openai', modelId: 'gpt-4o-mini' },
      instructions: 'Classify support tickets…',
    } },
    { id: 'end_1', kind: 'end', config: {} },
  ],
  edges: [
    { id: 'e1', source: 'start_1', target: 'classify' },
    { id: 'e2', source: 'classify', target: 'end_1' },
  ],
};

const issues = validate(graph);              // cycle/orphan/required-field checks
const { source, sourceHash, warnings } = compile(graph);

The emitted source is plain Runflow SDK TypeScript using flow().agent().branch().build() — deployable via rf deploy like any other agent.

Supported nodes

| Kind | SDK primitive | Runflow-exclusive | |---|---|---| | start | flow() entry | — | | trigger | bound to trigger-engine (webhook / cron / manual) | ✓ | | agent | Agent + .agent(id, instance, { prompt }) | — | | branch | .branch(id, { condition, onTrue, onFalse }) | — | | transform | .step(id, async (input, ctx) => …) | — | | knowledge | Knowledge.search(query, { k, threshold }) | ✓ | | mcp | .connector(id, slug, tool, 'invoke', params) against mcp-gateway | ✓ | | guardrails | PIISanitizer({ locale, strategy }) | ✓ | | credentials | Credentials.get(id) injected into context | ✓ | | end | terminal step | — |

Each emitted step is annotated with // @flow-node:<uuid> so future round-trip (decompile) preserves IDs without losing canvas-authored structure.

Validation

validate(graph) returns ValidationIssue[] with errors (block save) and warnings (allowed). Built-in checks: single start node, no orphan edges, branch must have an onTrue edge, Knowledge requires vectorStore, MCP requires instanceSlug + toolSlug, Credentials require credentialId.

Tests

npm test --workspace=packages/flow-compiler

8 tests covering: validation, deterministic hashing, the 6 base nodes, and each of the 4 Runflow-exclusive nodes.

Round-trip (decompile)

compile() embeds the full FlowGraph as a base64 JSON comment (// @flow-graph-json:<…>) at the top of the emitted source. decompile(source) reads that line back and returns the graph — survives hand-editing of function bodies as long as the marker line is preserved.

import { compile, decompile } from '@runflow-ai/flow-compiler';
const { source } = compile(graph);
const { graph: recovered } = decompile(source); // === graph

This is "best-effort" Phase-2 round-trip. For agents whose TS was authored entirely outside the canvas (no marker), decompile returns null. Full AST-level round-trip via ts-morph is the Phase-3 roadmap.

Roadmap

• AST-level decompile (ts-morph) for code authored outside the canvas
• Additional nodes: While, User approval, Sandbox, Deploy
• Trace replay attribute (flow.nodeId) on startSpan for live debugging