Workflow SDK
The Workflow SDK is Dromio's beta TypeScript package for contracted, inspectable workflows. Application code owns domain behavior; the SDK owns the run lifecycle, composition, waits, events, traces, and executable projections.
If you want to run something now, follow the Quick start.
Install and import
bun add @dromio/workflow
import {
catalog,
defineSignal,
promptFile,
step,
workflow,
workflowApp,
} from "@dromio/workflow";
step() defines reusable work, workflow() compiles a document, catalog()
creates a searchable catalog when you need one outside compilation,
defineSignal() declares typed external occurrences, promptFile() loads a
model prompt, and workflowApp() registers executable surfaces.
The root export is the canonical authoring API. Advanced result helpers and
stores live under @dromio/workflow/core; model workers live under
@dromio/workflow/product. The package is ESM and the documented executable
runners are tested with Bun 1.3.
Mental model
| Concept | Meaning |
|---|---|
| Workflow document | Versioned trigger, nodes, edges, loops, and result topology |
| Catalog item | Reusable executable step definition referenced by a document node |
| Placement | A node in one document; its ID and config may differ from the reusable definition |
| Workflow | A compiled document, catalog, contracts, and executable session factory |
| Child workflow | An independently runnable workflow composed inside a parent step |
| Workflow App | A registry of workflows for CLI, TUI, GUI, SVG, and host adapters |
| Session | One run's status, state, events, checkpoints, waits, and control methods |
| Event | An immutable lifecycle fact emitted during execution |
| Artifact | A file registered by a step for renderers and callers |
Choose a primitive
| Need | API |
|---|---|
| Contracted application behavior | step() |
| One structured model operation | step.model() |
| Harness-owned inference or tools | step.delegate() |
| One assessment plus deterministic policy | workflow.judge() |
| Revise until the quality bar passes | workflow.judgeUntil() |
| Clarify until a typed contract is complete | workflow.clarifyUntil() |
| Human question or approval | step.ask() or step.approval() |
| External occurrence or timer | step.waitFor() or step.sleep() |
| One nested workflow | step.workflow() |
| One selected child | step.router() |
| Concurrent children | step.fork() |
| One child per item | step.forEach() |
Primitive steps describe one runtime behavior. Bundled workflow.* builders
compose real executable nodes and remain independently runnable. Compatibility
wrappers step.evaluate() and step.promptedContract() remain available while
applications migrate.
Start with the Authoring rules, then use the Authoring API reference for required options and behavior of every root primitive.
Ownership boundaries
Application code owns domain schemas, prompts, score policies, mappings, authorization, and the meaning of side effects. The SDK owns contract validation, step attempts, child execution, suspension, resumption, retries, events, trace ancestry, checkpoints, and projections.
Durability is explicit. A direct in-process session can be snapshotted and hydrated. A supplied store or Workflow App host persists it. The SDK cannot make an external side effect idempotent or durable unless its adapter participates.
Authoring path
- Define domain contracts and reusable steps.
- Write a workflow document with trigger, nodes, edges, and result.
- Compile it with
workflow()and the catalog definitions it references. - Call
workflow.start()directly, or register it withworkflowApp(). - Stream and retain events; add persistence before relying on waits in production.
- Test successful, invalid, waiting, resumed, failed, and retried behavior.
Package status
@dromio/workflow is 0.2.5 and beta. Pin the version, review the
API status, and treat lower-level subpaths as
faster-moving integration APIs. The package is Apache-2.0 licensed; source and
issues are available in the Dromio-Labs/workflow repository.