taskflow 0.3 Documentation

Trusted Effects for coding-agent workflows: declare effects, verify typed paths, and commit admitted filesystem changes through one resource authority.

0.3.0-beta.1.2 — beta channel candidate, not GA. This page describes the Trusted Effects MVP prepared for the beta release. The 0.3-C Control Plane remains a follow-on candidate track.

taskflow is a declarative runtime for coding-agent workflows. It turns a graph into a verifiable execution contract, runs phases in isolation, and keeps intermediate transcripts out of the host conversation. The 0.3 candidate adds Trusted Effects: a typed declaration and resource-controlled commit path for admitted filesystem effects.

Start with the right path

Trusted Effects overview

Learn what effects[], PathRef, labels, resource transactions, and why-* evidence mean — including the limits of resolve-only execution.

Run the no-LLM fixture

Exercise the checked-in filesystem-write vertical slice without a live model.

Run a normal flow

Install a host and run a declarative DAG with agent phases, gates, approvals, and resume.

Understand the 0.2 foundation

TypeScript authoring, FlowIR, trace, replay, background runs, and incremental recompute.

Trusted Effects is not an OS sandbox. The 0.3 MVP protects admitted declared filesystem targets through the resources path. Under resolve-only execution, writes to undeclared paths remain host-policy dependent; SecretRef and ServiceRef have no live vault or network backend in this cut.

The 0.3 contract

Declare. Attach a closed effects[] list to a phase. Each effect names its kind, typed target, purpose, and optional confidentiality/integrity labels.

Verify and admit. Validate the EffectIR, resolve PathRef, check information-flow labels and mutating-path overlap, then bind the declared target to a resource intent.

Stage and commit. The resources layer snapshots, leases, journals, stages, and atomically commits the declared filesystem target — or restores and rejects when the transaction cannot complete.

Explain. Query taskflow_why_effect or the core why-* APIs for structured, ledger-backed reasons. Declaration alone is never presented as authorization.

Install on your host

The 0.3 beta is available from npm's beta channel, or from this repository for source-level work. Stable host guides continue to use the published 0.2.x line unless you explicitly select the beta channel.

Every taskflow package requires Node.js 22.19.0 or newer. The candidate's source and fixture checks use pnpm from the repository checkout.

Pi

Native extension, /tf commands, run views, and interactive approvals.

Codex

Plugin and stdio MCP delivery.

Claude Code

Plugin and stdio MCP delivery.

OpenCode

MCP configuration and generated skill.

Grok Build

MCP configuration with explicit host profiles.

Hermes Agent

MCP delivery with explicit child toolsets and isolation policy.

Learn the foundation

Core concepts

DAGs, phase types, interpolation, verification, isolation, and resume.

Syntax reference

Flow fields, control flow, budgets, caching, and approvals.

Compiler & runtime

JSON, TypeScript DSL, FlowIR, trace, replay, and recompute.

Commands & MCP tools

Host commands and the current 20-tool MCP surface, including taskflow_why_effect.

Release boundary

The current 0.3 line has two related tracks:

Trusted Effects MVP: the release-bound product definition. It covers EffectIR, typed refs, labels, resource-controlled filesystem transactions, overlap admission, host-baseline honesty, and ledger-backed why-* explainers.
0.3-C Control Plane: a follow-on track whose current code is a ControlHost/proposed-contract scaffold. Project stores, coordination, approvals, receipts, and evidence UI are later stages; none is the 0.3 MVP GA definition, and the WebUI is not shipped in this candidate.

Read the MVP freeze in the repository and the 0.3-C plan for the normative scope.