API reference
Every workflow-authoring primitive: imports, options, types, results, examples, and execution semantics.
Use this reference when you know what you want to build and need to know exactly what a function accepts. Start with Build a workflow for a guided introduction.
This reference describes Laufwerk 0.0.1-alpha.13, Effect 3.22.1,
@effect/workflow 0.19.1, Harness 1.0.68, and the Codex/Claude Code adapters
1.0.70. Adapter options are checked against those pinned types; a newer native
CLI or upstream documentation can expose options this version does not accept.
Examples are checked against an isolated, exact-version registry consumer. The framework checkout can contain changes outside this published version. See current status for release evidence.
Primitive directory
| Primitive | What it owns | Reference |
|---|---|---|
| Effect Schema | Runtime input/output validation and encoded types | Types and schemas |
Workflow.make | Input/output contract and execution identity | Workflow |
Activity.make | A named, recorded step | Activity |
execution.agent / HarnessAgent | Model adapter, instructions, tools and permissions | Agents |
Session.open, Session.run | Agent conversation and execution lifecycle | Session |
Workspace.open, Workspace.writeBack | Shared files and their relationship to the original source | Workspace |
Human, HumanView | Recorded questions, typed custom forms, decisions and notifications | Human |
Visual | Descriptive workflow nodes and scopes | Visual annotations |
createLocalExecution, createDockerExecution, createMicrosandbox | Where agents and commands execute | Execution |
DurableClock, DurableDeferred | Timers and durable completion signals | Timers and signals |
defineConfig | Consumer project identity and legacy sandbox definitions | Configuration |
defineHttpRoutes | HTTP entry points that can start runs | HTTP |
| Testing and benchmarks | Checks and comparisons built around recorded runs | Testing and benchmarks |
| CLI | Start, inspect, answer and control runs | CLI |
There is no exported Agent, Run, Task, or Benchmark constructor in the root
SDK. Use execution.agent, workflow execution, and Activity.make respectively;
benchmarking is currently a composition of tests and run measurements.
How to read the signatures
Effect.Effect<A, E, R> describes work that returns A, can fail with E, and
requires services R. It does not execute when constructed. Inside a registered
workflow's Effect.gen, use yield* to run it and obtain A.
Laufwerk supplies its session, workspace and human services and the Effect workflow
engine. Calling Effect.runPromise(Session.run(...)) in an arbitrary script does
not supply those services. Configuration and agent constructors, by contrast,
are ordinary functions. HTTP handlers use ordinary promises.
In tables, optional means the property can be omitted. It does not imply that
null is accepted. readonly properties are configuration values, not setters.
Examples whose code-block titles end in .ts or .tsx are complete modules;
workflow fragments are exported functions that you call from your workflow.
Multi-file examples preserve their relative imports; save each file at the stated
consumer path. All files on a reference page are compiled together.
Start with the complete session workflow to see workspace, agent, commands, structured output and cleanup wired together. The schema reference explains the types used in the tables.
Identity and replay
| Identity | Scope | Example |
|---|---|---|
projectId | Consumer project | "acme-tools" |
Workflow name and idempotencyKey(input) | Workflow execution | "review" and input.requestId |
Session key | Run | "implementer" |
ask / exec key | Operation within a continuous session | "revise-2", "test-2" |
Human key | Run, across all Human methods | "approve-release" |
Activity / clock / deferred name | Named operation within the workflow execution | "fetch-ticket" |
Keep identities stable on replay and distinct for genuinely different work. In a loop, derive them from a stable iteration index. A completed operation's key is not a request to run it again with new arguments. New inputs or a benchmark trial need a new workflow execution identity.
Durability records results and resumable state. It does not make arbitrary network requests or shell commands exactly-once transactions. See reliability.
Package boundaries
| Import | Contents |
|---|---|
@laufwerk/sdk | Session, Workspace, Human, their public types/errors, defineConfig, ExecutionTarget |
@laufwerk/execution | Local/Docker constructors, resource types, prepared Codex image helpers |
@laufwerk/sdk/harness | Re-exported Harness agent API |
@laufwerk/sdk/harness/codex | Codex adapter, including Laufwerk's bridge compatibility correction |
@laufwerk/sdk/harness/claude-code | Claude Code adapter |
@laufwerk/sdk/harness/v1 | Low-level Harness adapter/provider protocol |
@laufwerk/sdk/ai | Re-export of AI SDK; useful for tool, stepCountIs and related types |
@laufwerk/sdk/human-view | Typed display and response contracts |
@laufwerk/sdk/visual | Descriptive workflow annotations |
@laufwerk/studio/react | Custom view registration and React component props |
@laufwerk/sdk/http | HTTP route and workflow-start types |
@laufwerk/sandbox | Legacy Microsandbox integration and low-level volume helpers |
@effect/workflow / effect | Workflow, Activity, timers, signals, Effect and Schema |
The full upstream AI SDK and low-level provider protocols are not additional
Laufwerk primitives. Their exports retain upstream contracts. The pages here
document Laufwerk authoring options and the agent settings needed to use them.
/internal exports are runtime implementation contracts, not a stable authoring API.