Graph Workflow Engine

FSM-based workflow engine with Claude Agent SDK integration

Graph Workflow Engine

A stateful, FSM-based workflow engine for building AI-driven software development pipelines with checkpoint/resume capabilities.

What is it?

The Graph Engine enables multi-step AI workflows that:

Installation

import { defineNodes, defineWorkflow, StdlibTool, AgentModel, GraphEngine } from '@sys/graph';

Quick Start

The API provides compile-time type safety for transitions. TypeScript validates that all then values point to valid nodes.

1. Define a Workflow

import { defineNodes, defineWorkflow, StdlibTool, AgentModel } from '@sys/graph';

interface MyContext extends Record<string, unknown> {
  allTasksDone: boolean;
  testsPassed: boolean;
}

// Define schema with all node names
const schema = defineNodes<MyContext>()([
  'PLAN', 'IMPLEMENT', 'TEST', 'FIX', 'COMMIT'
] as const);

export default defineWorkflow({
  id: 'feature-development',
  schema,
  initialContext: { allTasksDone: false, testsPassed: false },

  nodes: [
    // First node is the entry point
    schema.agent('PLAN', {
      role: 'architect',
      prompt: 'Analyze the request and output a JSON plan.',
      capabilities: [StdlibTool.Glob, StdlibTool.Read],
      then: 'IMPLEMENT',  // TypeScript validates this!
    }),

    schema.agent('IMPLEMENT', {
      role: 'builder',
      prompt: 'Implement the planned tasks.',
      capabilities: [StdlibTool.Write, StdlibTool.Read, StdlibTool.Bash],
      then: (state) => state.context.allTasksDone ? 'TEST' : 'IMPLEMENT',
    }),

    schema.command('TEST', {
      command: 'bun test',
      then: (state) => state.context.testsPassed ? 'COMMIT' : 'FIX',
    }),

    schema.agent('FIX', {
      role: 'debugger',
      prompt: 'Fix the failing tests.',
      capabilities: [StdlibTool.Read, StdlibTool.Write],
      then: 'TEST',
    }),

    schema.slashCommand('COMMIT', {
      command: 'commit',
      args: 'Implement feature with passing tests',
      then: 'END',
    }),
  ],
});

2. Execute the Workflow

import { GraphEngine } from '@sys/graph';

const engine = new GraphEngine();

const result = await engine.run('feature-development', {
  context: {
    request: 'Add user authentication to the API',
    allTasksDone: false,
  },
});

console.log('Final state:', result.status);

Node Types

Node Type Purpose Key Features
AgentNode AI-powered execution Claude SDK, tools, multi-turn
CommandNode Shell commands stdout/stderr capture, exit codes
SlashCommandNode Claude Code operations /commit, /test, /edit
GitHubProjectNode Project status updates GitHub Projects V2 API

Primitive Nodes

Low-level building blocks for dynamic, composable workflows:

Node Type Purpose Key Features
EvalNode Context transformation No LLM, pure functions
DynamicAgentNode Runtime AI config Dynamic model/prompt
DynamicCommandNode Runtime shell config Dynamic command/env
HttpNode HTTP requests JSON I/O, all HTTP methods
LLMNode Direct LLM calls Schema validation, structured output

Documentation

Document Description
Architecture Core concepts and design
Nodes Built-in node types
Primitives Dynamic, composable building blocks
State State management and persistence
Transitions Routing between nodes
Custom Nodes Creating your own nodes
API Reference Type-safe schema-based API
Examples Full workflow examples

Comparison with Dispatch

Feature Dispatch Graph Engine
Purpose GitHub CI/CD automation AI workflow orchestration
Graph Type DAG (issue dependencies) FSM (node transitions)
AI Integration None Claude Agent SDK
Parallelization Matrix jobs Sequential nodes
Persistence Ephemeral Full checkpoint/resume
Use Case Manage issue queues Build multi-step AI workflows

Testing

bun test src/lib/graph/__tests__