@pilotoo/workflow

Introduction

@pilotoo/workflow is the engine behind Workflows. It holds the definition schema, the validator, the expression language, the built-in node kinds and a runtime that compiles a definition to a LangGraph graph. Everything the environment provides, such as fetch, a sandbox, a command runner or connection tools, enters through ports, so the same engine runs in @pilotoo/server, in the local backend and in Pilotoo Brain.

Installation

@pilotoo/workflow is at version 0.1.0, is marked private and is not published to a registry. It is also not part of the tarballs that pnpm release:check packs, so today it is used from the kit workspace:

pnpm install
pnpm --filter @pilotoo/workflow build

Inside the workspace, depend on it with "@pilotoo/workflow": "workspace:^". Its build first builds the kit packages it depends on.

Basic usage

Create a runtime from node kinds and a checkpointer, then start a run:

src/run.ts

import { coreNodeKinds, createWorkflowRuntime } from '@pilotoo/workflow';

const runtime = createWorkflowRuntime({
  kinds: coreNodeKinds,
  checkpointer,
  ports: { fetch },
  onEvent: (event) => console.log(event.type),
});

const outcome = await runtime.start({
  workflow,
  runId: 'run-1',
  threadId: 'thread-1',
  input: { userId: 7 },
});

runtime.resume({ interruptId, answer, ... }) continues a run paused by an approve node, and runtime.pendingInterrupts(threadId) lists what a paused run waits for. Validate a definition without running it:

import { validateWorkflow } from '@pilotoo/workflow/definition';

const issues = validateWorkflow(workflow, kinds);

See Building workflows for the format and every node kind.

Entry points

Import	Provides
@pilotoo/workflow	createWorkflowRuntime, coreNodeKinds and each core kind, defineNodeKind, resolveExpressions, the HostPorts, Sandbox, CommandRunner and ConnectionsPort types, connectionNodeKind, cron helpers (nextFires, assertSchedulable), catalog helpers (describeNodeKind, nodeOutputPorts, kindsFromToolList) and the agent-facing workflow tools (workflowToolDefinitions).
@pilotoo/workflow/definition	Only the definition: workflowDefinitionSchema, validateWorkflow, layoutWorkflow and the descriptor types. Safe to import in a browser, as the visual builder does.
@pilotoo/workflow/agents	agentNodeKinds: the tool, llm and agent kinds, which bring in @pilotoo/agent-runtime.
@pilotoo/workflow/quickjs	createQuickJsSandbox: the code node’s sandbox, QuickJS compiled to WebAssembly in a worker thread.

Ports

A node kind that needs something the host did not lend fails its node with a clear message. All four are optional.

Port	Used by
fetch	The http kind.
sandbox	The code kind. createQuickJsSandbox() is the one to lend on a shared server.
exec	The command kind: a program with its arguments, no shell.
connections	The connection.<tool> kinds, which run a tool of the caller’s connected accounts.

Dependencies

@pilotoo/agent-runtime, @pilotoo/chat-protocol, @langchain/core, @langchain/langgraph, @langchain/langgraph-checkpoint, croner, quickjs-emscripten, @cfworker/json-schema and zod. It has no peer dependencies.

Learn more

• Workflows, Triggers and Server integration.
• @pilotoo/server, which mounts the runtime and the REST routes.