Workflow SDK API status
@dromio/workflow is beta. Pin the package version and review exported
TypeScript types when upgrading. The public npm release is currently 0.2.5.
Root authoring APIs
| API | Status | Notes |
|---|---|---|
step() | Available | Contracted app-owned behavior and side effects |
step.model() | Available | One structured model operation |
step.delegate() | Available | Durable work owned by an external harness |
step.gate() | Available | Deterministic score-policy decision |
step.ask() | Available | Validated human question |
step.approval() | Available | Typed durable approval hook |
step.waitFor() | Available | Typed external-signal hook |
step.sleep() | Available | Duration or absolute-time timer hook |
step.workflow() | Available | One child workflow as a step |
step.router() | Available | Exactly one compatible child route |
step.fork() | Available | Concurrent children with all join |
step.forEach() | Available | Simple and advanced child iteration |
catalog() | Available | Searchable executable step catalog |
workflow() | Available | Document compilation and direct execution |
workflow.judge() | Available | One assessor step or child workflow plus deterministic gate |
workflow.judgeUntil() | Available | Bounded produce, judge, revise loop |
workflow.clarifyUntil() | Available | Typed, durable human clarification loop |
workflowApp() | Available | Executable workflow registry |
defineSignal() | Available | Typed correlation and payload definition |
promptFile() | Available | File-backed prompt source |
Compatibility APIs
| API | Status | Replacement |
|---|---|---|
step.evaluate() | Deprecated, supported | workflow.judge() plus step.workflow() when placement is needed |
step.promptedContract() | Deprecated, supported | workflow.clarifyUntil() |
codexCliWorker() | Deprecated, supported | step.delegate() with a Codex harness |
opencodeWorker() | Deprecated, supported | step.delegate() with an OpenCode harness |
createModelRouter() remains supported while current products move provider
selection to the application runtime boundary. It is not the canonical example
for new workflows. Generic file-write helpers are not root APIs.
Root execution and surface APIs
| API | Status | Runtime note |
|---|---|---|
workflow.start() / workflow.hydrate() | Available | In-process execution and recovery |
createWorkflowAppHost() | Available | Store-backed runtime and Fetch adapter |
runWorkflowCli() | Available | Workflow Apps with one prompt input key |
runWorkflowTui() | Available | Bun interactive terminal surface |
runWorkflowGui() | Available | Bun browser canvas server |
runWorkflowSvg() | Available | Bun lightweight graph server |
runWorkflowServer() | Available | Bun durable host and signal control plane |
createWorkflowControlPlaneMcpProvider() | Available in 0.2.5 | MCP discovery, triggers, run inspection, and resume_hook |
Important current limits
- The prompt-based Workflow App adapters require exactly one trigger input key.
step.delegate()requires a harness or operator to resume itshandoff_requestedhook; Dromio does not run a nested agent on its behalf.step.router()requires compatible routes and cannot change its choice while resuming a durable child.step.fork()currently joins all branches; branch output keys cannot collide.- The core runtime retries explicit
retry()results, not arbitrary exceptions. - There is no generic per-step timeout. Timer waits use
step.sleep(); provider request limits belong to their adapters. - In-memory storage is not durable. Use snapshots, a
LoopStore, SQLite host storage, or a custom runtime store appropriate to the deployment. - Events may gain new types during beta; consumers must tolerate unknown types.
Stability and compatibility
The root namespace is the preferred authoring surface. @dromio/workflow/core,
@dromio/workflow/product, and workflow-control-plane subpaths are public
package exports but expose lower-level integration machinery that may change
more quickly before 1.0.
The package is Apache-2.0 licensed. Report SDK issues and follow releases in the source repository.
For signatures and primitive behavior, continue to the Authoring API reference. For runtime limits and persistence, use Execution and durability.
Source of truth
Published exports and declarations are authoritative. In the source tree, the main references are:
packages/sdk/src/sdk/index.ts
packages/sdk/src/sdk/authoring/
packages/sdk/src/sdk/core/loop/
packages/sdk/src/sdk/client/interactions/workflow-app/
If prose and TypeScript disagree, follow the shipped types and open a docs issue with the package version and the conflicting page.