claude-taskflow 0.2.10 → 0.3.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +139 -377
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,460 +1,222 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<img src="https://raw.githubusercontent.com/heggria/taskflow/main/assets/hero.png" alt="taskflow:
|
|
3
|
+
<img src="https://raw.githubusercontent.com/heggria/taskflow/main/assets/hero.png" alt="taskflow 0.3: trusted effects for coding-agent workflows" width="100%">
|
|
4
4
|
|
|
5
5
|
<br />
|
|
6
6
|
|
|
7
|
-
[](https://www.npmjs.com/package/pi-taskflow)
|
|
8
7
|
[](https://github.com/heggria/taskflow/actions/workflows/ci.yml)
|
|
9
8
|
[](https://nodejs.org)
|
|
10
9
|
[](https://github.com/heggria/taskflow/blob/main/LICENSE)
|
|
11
|
-
[](#
|
|
12
|
-
[](#built-to-survive-real-work)
|
|
10
|
+
[](#host-adapters)
|
|
13
11
|
|
|
14
12
|
**English** · [简体中文](https://github.com/heggria/taskflow/blob/main/README.zh-CN.md)
|
|
15
13
|
|
|
16
|
-
[
|
|
14
|
+
[0.3 overview](#taskflow-03-trusted-effects) · [Quickstart](#quickstart) · [Docs](https://heggria.github.io/taskflow/en/docs) · [Examples](https://github.com/heggria/taskflow/blob/main/examples) · [Changelog](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md)
|
|
17
15
|
|
|
18
16
|
</div>
|
|
19
17
|
|
|
20
18
|
---
|
|
21
19
|
|
|
22
|
-
#
|
|
20
|
+
# taskflow 0.3: make agent side effects inspectable
|
|
23
21
|
|
|
24
|
-
**taskflow
|
|
22
|
+
**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 work out of the host conversation. In the 0.3 candidate, the contract also describes the effects a phase is allowed to propose.
|
|
25
23
|
|
|
26
|
-
|
|
24
|
+
> **Status: 0.3.0-beta.1 Trusted Effects beta — beta channel, not GA.** This release candidate is prepared for npm's `beta` channel; the beta ships the Trusted Effects MVP described below. The 0.3-C Control Plane remains a follow-on candidate track; it is not a shipped beta surface.
|
|
27
25
|
|
|
28
|
-
|
|
26
|
+
## The 0.3 idea
|
|
27
|
+
|
|
28
|
+
An agent can propose content. It should not become the mutation authority merely because it can run a command.
|
|
29
|
+
|
|
30
|
+
For admitted, declared filesystem-write targets, taskflow 0.3 makes the path explicit and routes the final mutation through the resources transaction:
|
|
29
31
|
|
|
30
32
|
```text
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
33
|
+
flow / .tf.ts
|
|
34
|
+
│
|
|
35
|
+
▼
|
|
36
|
+
validate + verify ──► EffectIR + FlowIR hash
|
|
37
|
+
│ │
|
|
38
|
+
│ ▼
|
|
39
|
+
│ admit declared targets
|
|
40
|
+
│ │
|
|
41
|
+
▼ ▼
|
|
42
|
+
isolated phase ───────► stage → commit | restore + reject
|
|
35
43
|
│
|
|
36
44
|
▼
|
|
37
|
-
|
|
38
|
-
│
|
|
39
|
-
┌────────────┼────────────┐
|
|
40
|
-
▼ ▼ ▼
|
|
41
|
-
resume replay recompute
|
|
45
|
+
ledger-backed why-effect
|
|
42
46
|
```
|
|
43
47
|
|
|
44
|
-
|
|
48
|
+
This is **not** an OS sandbox. Resolve-only hosts cannot prevent every write to an undeclared path. Secret and service references are typed and fail closed in this cut; they do not imply a vault or network backend.
|
|
45
49
|
|
|
46
|
-
##
|
|
50
|
+
## What is in the candidate
|
|
47
51
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
| | Ad-hoc agents / scripts | **taskflow** |
|
|
52
|
+
| Layer | What it does | Candidate status |
|
|
51
53
|
|---|---|---|
|
|
52
|
-
| **
|
|
53
|
-
| **
|
|
54
|
-
| **
|
|
55
|
-
| **
|
|
56
|
-
| **
|
|
57
|
-
| **
|
|
54
|
+
| **Taskflow runtime** | Declarative DAGs, 12 phase types, budgets, retries, approvals, isolation, resume, replay, trace, and recompute | Existing 0.2 foundation |
|
|
55
|
+
| **Trusted Effects** | Closed `EffectIR`, `PathRef` / `SecretRef` / `ServiceRef`, confidentiality/integrity labels, effect validation, overlap checks, and ledger-backed `why-*` explainers | 0.3 MVP implementation |
|
|
56
|
+
| **Resource transaction** | Snapshot → lease → durable intent/permit → stage → commit, or restore and reject | 0.3 MVP implementation |
|
|
57
|
+
| **Host adapters** | Pi, Codex, Claude Code, OpenCode, Grok Build, and Hermes Agent use the same flow contract | Existing host surface; support remains host-specific |
|
|
58
|
+
| **Control Plane** | ControlHost scaffold, proposed wire contracts, singleton/fencing, and hello negotiation; future stores, approvals, receipts, and coordination | Active 0.3-C track; not shipped and not the 0.3 MVP GA claim |
|
|
59
|
+
| **WebUI** | Runs, approvals, receipts, and evidence browsing | Planned in the 0.3-C sequence; not shipped in this candidate |
|
|
58
60
|
|
|
59
|
-
The
|
|
61
|
+
The normative MVP definition is [`docs/internal/0.3.0-trusted-effects-mvp.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3.0-trusted-effects-mvp.md). The 0.3-C Control Plane plan is [`docs/internal/0.3-c-control-plane-plan.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3-c-control-plane-plan.md).
|
|
60
62
|
|
|
61
|
-
##
|
|
63
|
+
## Quickstart
|
|
62
64
|
|
|
63
|
-
|
|
65
|
+
The 0.3 beta can be installed from npm, or exercised from a clean source checkout. Use Node.js **≥ 22.19.0**:
|
|
64
66
|
|
|
65
67
|
```bash
|
|
66
|
-
|
|
68
|
+
git clone https://github.com/heggria/taskflow.git
|
|
69
|
+
cd taskflow
|
|
70
|
+
git checkout rc/0.3.0-trusted-effects
|
|
71
|
+
pnpm install
|
|
72
|
+
pnpm run typecheck
|
|
73
|
+
pnpm test
|
|
67
74
|
```
|
|
68
75
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
The routing skill uses the same familiar `task` / `tasks` / `chain` shape:
|
|
74
|
-
|
|
75
|
-
```json
|
|
76
|
-
{
|
|
77
|
-
"chain": [
|
|
78
|
-
{ "agent": "scout", "task": "Map the public API under src/api." },
|
|
79
|
-
{
|
|
80
|
-
"agent": "security-reviewer",
|
|
81
|
-
"task": "Audit this surface for missing auth and unsafe input boundaries:\n{previous.output}"
|
|
82
|
-
},
|
|
83
|
-
{
|
|
84
|
-
"agent": "reviewer",
|
|
85
|
-
"task": "Turn these findings into one prioritized report:\n{previous.output}"
|
|
86
|
-
}
|
|
87
|
-
]
|
|
88
|
-
}
|
|
76
|
+
The beta commands below become usable after the tag workflow completes; until then they are release-target examples, not proof of registry availability.
|
|
77
|
+
```bash
|
|
78
|
+
npm install --global pi-taskflow@beta
|
|
79
|
+
npm install --global codex-taskflow@beta
|
|
89
80
|
```
|
|
90
81
|
|
|
91
|
-
|
|
82
|
+
The host-specific plugin and MCP commands remain in the [host guides](https://heggria.github.io/taskflow/en/docs/guides/). Stable 0.2.x installs remain available through exact stable pins.
|
|
92
83
|
|
|
93
|
-
|
|
94
|
-
{
|
|
95
|
-
"name": "audit-api",
|
|
96
|
-
"args": { "dir": { "default": "src/api" } },
|
|
97
|
-
"concurrency": 4,
|
|
98
|
-
"phases": [
|
|
99
|
-
{
|
|
100
|
-
"id": "discover",
|
|
101
|
-
"type": "agent",
|
|
102
|
-
"agent": "scout",
|
|
103
|
-
"task": "List source files under {args.dir}. Output ONLY a JSON array of {\"path\":\"...\"} objects.",
|
|
104
|
-
"output": "json"
|
|
105
|
-
},
|
|
106
|
-
{
|
|
107
|
-
"id": "audit-each",
|
|
108
|
-
"type": "map",
|
|
109
|
-
"over": "{steps.discover.json}",
|
|
110
|
-
"as": "file",
|
|
111
|
-
"agent": "security-reviewer",
|
|
112
|
-
"task": "Audit {file.path}. Cite evidence and assign severity.",
|
|
113
|
-
"dependsOn": ["discover"]
|
|
114
|
-
},
|
|
115
|
-
{
|
|
116
|
-
"id": "report",
|
|
117
|
-
"type": "reduce",
|
|
118
|
-
"from": ["audit-each"],
|
|
119
|
-
"agent": "reviewer",
|
|
120
|
-
"task": "Synthesize one prioritized report:\n{steps.audit-each.output}",
|
|
121
|
-
"dependsOn": ["audit-each"],
|
|
122
|
-
"final": true
|
|
123
|
-
}
|
|
124
|
-
]
|
|
125
|
-
}
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
Save it as `.pi/taskflows/audit-api.json`, then run:
|
|
84
|
+
Run the no-LLM Trusted Effects vertical-slice fixture:
|
|
129
85
|
|
|
130
|
-
```
|
|
131
|
-
|
|
86
|
+
```bash
|
|
87
|
+
pnpm exec node --conditions=development --experimental-strip-types --test \
|
|
88
|
+
packages/taskflow-core/test/effects-e2e-fixture.test.ts
|
|
132
89
|
```
|
|
133
90
|
|
|
134
|
-
|
|
91
|
+
This exercises the checked-in `examples/trusted-effects-write.json` path without a live LLM. For an interactive run, use the host guide for the adapter you already run. The stable 0.2 installation path remains documented separately in the [host guides](https://heggria.github.io/taskflow/en/docs/guides/).
|
|
135
92
|
|
|
136
|
-
|
|
93
|
+
## Declare an effect
|
|
137
94
|
|
|
138
|
-
|
|
95
|
+
Effects are part of the flow contract, not a free-form prompt promise:
|
|
139
96
|
|
|
140
97
|
```json
|
|
141
98
|
{
|
|
142
|
-
"name": "
|
|
143
|
-
"scriptCwd": "flow",
|
|
99
|
+
"name": "trusted-effects-write",
|
|
144
100
|
"phases": [
|
|
145
|
-
{
|
|
101
|
+
{
|
|
102
|
+
"id": "write-report",
|
|
103
|
+
"type": "script",
|
|
104
|
+
"run": ["node", "scripts/render-report.mjs"],
|
|
105
|
+
"effects": [
|
|
106
|
+
{
|
|
107
|
+
"id": "report",
|
|
108
|
+
"kind": "fs.write",
|
|
109
|
+
"purpose": "write final report",
|
|
110
|
+
"target": {
|
|
111
|
+
"kind": "path",
|
|
112
|
+
"path": {
|
|
113
|
+
"workspace": "project",
|
|
114
|
+
"subpath": { "literalPath": "out/report.md" },
|
|
115
|
+
"intent": "create-file"
|
|
116
|
+
}
|
|
117
|
+
},
|
|
118
|
+
"confidentiality": "internal",
|
|
119
|
+
"integrity": "project"
|
|
120
|
+
}
|
|
121
|
+
],
|
|
122
|
+
"final": true
|
|
123
|
+
}
|
|
146
124
|
]
|
|
147
125
|
}
|
|
148
126
|
```
|
|
149
127
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
[Follow the full quickstart →](https://heggria.github.io/taskflow/en/docs/getting-started)
|
|
128
|
+
The declaration is not authorization by itself. The runtime resolves the `PathRef`, checks labels and overlaps, records the resource intent, and only then permits the transaction to stage and finalize the declared target. `taskflow_why_effect` explains the resulting authorization and ledger state without model calls.
|
|
153
129
|
|
|
154
|
-
##
|
|
130
|
+
## The runtime contract
|
|
155
131
|
|
|
156
|
-
|
|
132
|
+
The 0.2 runtime remains the foundation. A flow can be authored as portable JSON or compiled from TypeScript DSL to FlowIR:
|
|
157
133
|
|
|
158
134
|
```text
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
## 0.2.10: organized, portable saved flows
|
|
172
|
-
|
|
173
|
-
Saved flows can now be organized below the bounded `.pi/taskflows/flows/**` convention while legacy top-level flows keep their existing precedence and behavior. A file-backed flow may opt into `scriptCwd: "flow"`, making adjacent scripts, templates, and fixtures portable as one reviewable directory bundle.
|
|
174
|
-
|
|
175
|
-
Discovery, provenance, and persistence remain fail-closed: recursion has shared file/entry/directory/byte/depth budgets, symlinked descendants are excluded, source identity survives foreground/background/resume/subflow paths, and nested definition/sidecar writes revalidate the physical parent through atomic promotion. [Full 0.2.10 notes →](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md#0210--2026-08-12)
|
|
176
|
-
|
|
177
|
-
## 0.2.9: Hermes Agent + verify parity
|
|
178
|
-
|
|
179
|
-
Taskflow now ships on **Hermes Agent** as `hermes-taskflow`, bringing the same MCP control plane to a sixth host. Hermes children run with an ephemeral home, explicit toolsets, cwd-confined local reads, provider-only credential material, and an explicit opt-in for mutating `--yolo` phases.
|
|
180
|
-
|
|
181
|
-
Pi's advertised `/tf verify <name>` command now matches the tool surface, including saved flow names containing spaces. Project discovery also stops at canonical home/temp boundaries, so ambient `/tmp/.pi` state cannot become a project by accident. [Full 0.2.9 notes →](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md#029--2026-08-11)
|
|
182
|
-
|
|
183
|
-
## 0.2.8: review, then confirm
|
|
184
|
-
|
|
185
|
-
Pi approvals now separate **selection** from **commit**. Choose Reject, Edit guidance, or Approve with `R` / `E` / `A`, arrows, or Tab; press Enter to confirm. The safe default is Reject, and Escape or Ctrl-C still rejects immediately.
|
|
186
|
-
|
|
187
|
-
Long proposals start collapsed. Press `V` to open an inline scrollable preview while the decision footer stays visible; short proposals remain open by default. Full notes: [CHANGELOG 0.2.8](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md#028--2026-08-10).
|
|
188
|
-
|
|
189
|
-
## 0.2.7: plan before spend · close the loop
|
|
190
|
-
|
|
191
|
-
The 0.2 line made graphs **compiled and inspectable**. **0.2.7** makes the day-to-day loop feel finished: you can see the plan *before* any model call, and you can hear about the run *after* it finishes — without stuffing transcripts into the host.
|
|
192
|
-
|
|
193
|
-
| Before spend | After spend |
|
|
194
|
-
|---|---|
|
|
195
|
-
| **`taskflow_plan` / `/tf plan`** — bind typed args, project phase order, mark dynamic refs, worst-case agent-call bound | **`hooks.onComplete` / `onFail` / `onBlocked`** — webhook, file, or argv-only command; summary payload only (`taskflow.hook.v1`) |
|
|
196
|
-
| **`verify` / `lint`** still free | **`approval.timeoutMs` + `onExpire`** — HITL no longer waits forever |
|
|
197
|
-
| **`recompute` savings line** — `reused N · rerun M · cutoff K · saved ~P%` | **`taskflow_analytics`** — last-N status, duration, fail/cache rates (read-only) |
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
# Zero tokens: see what would run and how expensive the worst case looks
|
|
201
|
-
# MCP: taskflow_plan · Pi: /tf plan my-flow '{"dir":"src"}'
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
```jsonc
|
|
205
|
-
// Optional: fire-and-forget when a background run finishes
|
|
206
|
-
{
|
|
207
|
-
"hooks": {
|
|
208
|
-
"onComplete": [{ "type": "file", "path": ".taskflow/hooks/last-complete.json" }]
|
|
209
|
-
}
|
|
210
|
-
}
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
MCP hosts now expose **19 tools** (added `taskflow_plan` and `taskflow_analytics`). Starter templates: [`examples/templates/`](https://github.com/heggria/taskflow/blob/main/examples/templates/). Full notes: [CHANGELOG 0.2.7](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md#027--2026-08-06).
|
|
214
|
-
|
|
215
|
-
## 0.2 is the compiler turn
|
|
216
|
-
|
|
217
|
-
Before 0.2, taskflow executed declarative graphs. Now the graph also has a compile-time frontend, a canonical intermediate representation, an append-only decision trace, offline replay, and incremental recompute.
|
|
218
|
-
|
|
219
|
-
### Author in JSON or TypeScript
|
|
220
|
-
|
|
221
|
-
JSON remains the portable runtime contract. For larger flows, `taskflow-dsl` adds a compile-time TypeScript authoring layer:
|
|
222
|
-
|
|
223
|
-
```ts
|
|
224
|
-
import { agent, flow, json, map, reduce } from "taskflow-dsl";
|
|
225
|
-
|
|
226
|
-
export default flow("audit", (ctx) => {
|
|
227
|
-
ctx.budget({ maxUSD: 2 });
|
|
228
|
-
|
|
229
|
-
const files = agent("List files under {args.dir}", {
|
|
230
|
-
agent: "scout",
|
|
231
|
-
output: json<{ path: string }[]>(),
|
|
232
|
-
});
|
|
233
|
-
|
|
234
|
-
const audits = map(files, (file) =>
|
|
235
|
-
agent(`Audit ${file.path}`, { agent: "security-reviewer" }),
|
|
236
|
-
);
|
|
237
|
-
|
|
238
|
-
return reduce(
|
|
239
|
-
[audits],
|
|
240
|
-
(parts) => agent(`Write one report:\n${parts.audits.output}`),
|
|
241
|
-
{ final: true },
|
|
242
|
-
);
|
|
243
|
-
});
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
```bash
|
|
247
|
-
pnpm add -D taskflow-dsl
|
|
248
|
-
taskflow-dsl check audit.tf.ts
|
|
249
|
-
taskflow-dsl build audit.tf.ts --emit both
|
|
250
|
-
# → audit.taskflow.json + audit.flowir.json
|
|
135
|
+
JSON / .tf.ts
|
|
136
|
+
│
|
|
137
|
+
▼
|
|
138
|
+
validate → Taskflow JSON → FlowIR + content hash
|
|
139
|
+
│
|
|
140
|
+
▼
|
|
141
|
+
isolated DAG runtime
|
|
142
|
+
│
|
|
143
|
+
resume · replay · recompute · trace
|
|
144
|
+
│
|
|
145
|
+
▼
|
|
146
|
+
finalOutput to the host
|
|
251
147
|
```
|
|
252
148
|
|
|
253
|
-
`.tf.ts` is **compile-time only**. Hosts execute the emitted Taskflow JSON; they never interpret TypeScript.
|
|
254
|
-
|
|
255
|
-
### Compile to a contract you can reason about
|
|
256
|
-
|
|
257
|
-
FlowIR canonicalizes the graph and gives it a content hash. That compiled identity makes provenance and stale analysis inspectable, while the runtime adds content-addressed caching and deterministic tools:
|
|
258
|
-
|
|
259
|
-
| Operation | What it answers | Model calls |
|
|
260
|
-
|---|---|---:|
|
|
261
|
-
| **`plan`** | What will run, which args bind, worst-case agent calls? | **0** |
|
|
262
|
-
| `verify` / `compile` / `lint` | Is the graph structurally safe / lint-clean? | **0** |
|
|
263
|
-
| `ir` | What is the canonical graph and content hash? | **0** |
|
|
264
|
-
| `resume` | What unfinished work remains? (forks a new run; original untouched) | Only unfinished phases |
|
|
265
|
-
| `trace` | What calls and runtime decisions actually happened? | **0** to inspect |
|
|
266
|
-
| `replay` | What if thresholds or budgets had been different? | **0** |
|
|
267
|
-
| `why-stale` | What changed, and what depends on it? | **0** |
|
|
268
|
-
| `recompute` | What is the smallest observable affected frontier? (+ savings line) | Only affected phases |
|
|
269
|
-
| `analytics` | How have recent runs of this flow behaved? | **0** |
|
|
270
|
-
|
|
271
|
-
[Explore the compiler and runtime →](https://heggria.github.io/taskflow/en/docs/compiler-runtime/)
|
|
272
|
-
|
|
273
149
|
## One runtime, 12 phase types
|
|
274
150
|
|
|
275
151
|
| Family | Phases | Use them for |
|
|
276
152
|
|---|---|---|
|
|
277
|
-
| **Work** | `agent` · `parallel` · `map` · `reduce` · `script` | Single tasks, static
|
|
278
|
-
| **Control** | `gate` · `approval` · `flow` · `loop` | Quality decisions, human checkpoints, composition, iterative refinement |
|
|
153
|
+
| **Work** | `agent` · `parallel` · `map` · `reduce` · `script` | Single tasks, static concurrency, dynamic fan-out, aggregation, and zero-token shell steps |
|
|
154
|
+
| **Control** | `gate` · `approval` · `flow` · `loop` | Quality decisions, human checkpoints, composition, and iterative refinement |
|
|
279
155
|
| **Selection** | `tournament` · `race` | Best-of-N quality or first-success latency |
|
|
280
|
-
| **Dynamic graph** | `expand` | Validate and execute a runtime-produced
|
|
281
|
-
|
|
282
|
-
Across those phase types, the DSL provides dependencies, conditions, retries, timeouts, output contracts, budgets, workspace isolation, and explicit final-output selection. Each kind accepts only the fields that are safe and meaningful for it; freshness-sensitive phases are excluded from cross-run caching.
|
|
283
|
-
|
|
284
|
-
[Read the phase reference →](https://heggria.github.io/taskflow/en/docs/syntax/phase-types)
|
|
285
|
-
|
|
286
|
-
## Runtime guarantees, not prompt conventions
|
|
287
|
-
|
|
288
|
-
### Verify before spend
|
|
289
|
-
|
|
290
|
-
Cycles, dangling dependencies, invalid references, impossible joins, unsafe dynamic fragments, and configuration hazards are rejected or surfaced before the expensive work starts.
|
|
291
|
-
|
|
292
|
-
### Keep intermediate work out of the host context
|
|
293
|
-
|
|
294
|
-
Agent-running phases execute in isolated subagent processes; control and script phases stay inside the runtime. Upstream outputs are wired into downstream inputs internally. Only `finalOutput` returns to the host unless you explicitly use `peek` or `trace`.
|
|
295
|
-
|
|
296
|
-
### Survive sessions and failures
|
|
297
|
-
|
|
298
|
-
Phase state is persisted atomically. Resume skips unchanged completed work; detached Pi runs can outlive the initiating session; an idle watchdog terminates stalled subagents.
|
|
299
|
-
|
|
300
|
-
### Reuse work honestly
|
|
301
|
-
|
|
302
|
-
Within-run resume is content-addressed. Cross-run caching is opt-in and can fingerprint Git commits, files, globs, environment variables, and TTLs. Change one declared input and only its dependents become stale.
|
|
303
|
-
|
|
304
|
-
### Bound the blast radius
|
|
305
|
-
|
|
306
|
-
Budgets, concurrency caps, retries, timeouts, nesting limits, dynamic-graph breadth caps, path containment, non-idempotent phase classification, and fail-closed approval behavior are runtime semantics—not suggestions in a prompt.
|
|
307
|
-
|
|
308
|
-
### 0.2.1: safe dynamic cwd and Pi terminal reaping
|
|
309
|
-
|
|
310
|
-
An invocation argument declared as `type: "relative-path"` may select a phase
|
|
311
|
-
working directory with the exact form `cwd: "{args.package}"`. The bridge is
|
|
312
|
-
default-off, requires host `resolve-only` authorization, and confines the
|
|
313
|
-
canonical directory to the invocation root. Absolute paths, concatenation, and
|
|
314
|
-
`{steps.*}` remain rejected; this compatibility bridge is not an OS sandbox.
|
|
315
|
-
Resolve-only writer phases within one invocation are serialized before durable
|
|
316
|
-
lease acquisition, so fan-out cannot self-timeout while separate processes
|
|
317
|
-
remain protected by cross-process leases.
|
|
156
|
+
| **Dynamic graph** | `expand` | Validate and execute a runtime-produced nested or grafted fragment |
|
|
318
157
|
|
|
319
|
-
|
|
320
|
-
settings can use an explicit extension allowlist or opt back into legacy
|
|
321
|
-
inheritance. If a Pi child produces a validated final answer and terminal event
|
|
322
|
-
but an extension keeps the process alive, Taskflow waits a bounded grace window,
|
|
323
|
-
reaps the process group, and records `completionSource: "terminal-reap"` instead
|
|
324
|
-
of reporting a false timeout.
|
|
158
|
+
Across those phase types, the runtime provides shared behavior: dependencies, conditions, retries, timeouts, output contracts, budgets, workspace isolation, explicit final-output selection, and persistence for resume. Each phase kind accepts only the fields that are safe and meaningful for it.
|
|
325
159
|
|
|
326
|
-
|
|
327
|
-
{
|
|
328
|
-
"taskflow": {
|
|
329
|
-
"piChild": {
|
|
330
|
-
"resourceProfile": "isolated",
|
|
331
|
-
"extensions": [],
|
|
332
|
-
"terminalGraceMs": 1500
|
|
333
|
-
}
|
|
334
|
-
}
|
|
335
|
-
}
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
`allowlist` accepts explicit trusted extension files; `inherit` restores ambient
|
|
339
|
-
Pi extension discovery as a compatibility mode. Flows cannot widen this host
|
|
340
|
-
authority.
|
|
341
|
-
|
|
342
|
-
[Read the core concepts →](https://heggria.github.io/taskflow/en/docs/concepts/)
|
|
343
|
-
|
|
344
|
-
## Install on your host
|
|
345
|
-
|
|
346
|
-
All packages require **Node.js ≥ 22.19.0**.
|
|
347
|
-
|
|
348
|
-
### Pi
|
|
349
|
-
|
|
350
|
-
```bash
|
|
351
|
-
pi install npm:pi-taskflow
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
Pi provides the richest local experience: the `taskflow` tool, `/tf` commands, live DAG rendering, interactive approvals, background runs, and model-role setup.
|
|
355
|
-
|
|
356
|
-
[Pi guide →](https://heggria.github.io/taskflow/en/docs/guides/pi)
|
|
357
|
-
|
|
358
|
-
### OpenAI Codex
|
|
359
|
-
|
|
360
|
-
```bash
|
|
361
|
-
codex plugin marketplace add heggria/taskflow
|
|
362
|
-
codex plugin add taskflow@taskflow
|
|
363
|
-
```
|
|
160
|
+
Useful zero-token operations include:
|
|
364
161
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
[Claude Code guide →](https://heggria.github.io/taskflow/en/docs/guides/claude-code)
|
|
375
|
-
|
|
376
|
-
### OpenCode
|
|
377
|
-
|
|
378
|
-
```bash
|
|
379
|
-
opencode mcp add taskflow -- \
|
|
380
|
-
npx -y -p opencode-taskflow@0.2.10 opencode-taskflow-mcp
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
[OpenCode guide →](https://heggria.github.io/taskflow/en/docs/guides/opencode)
|
|
384
|
-
|
|
385
|
-
### Grok Build
|
|
386
|
-
|
|
387
|
-
```bash
|
|
388
|
-
grok mcp add taskflow -- \
|
|
389
|
-
npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
Grok Build support is new in 0.2. Its CLI stream does not report token/cost usage, so budget-declaring flows are rejected rather than silently running without enforcement.
|
|
393
|
-
|
|
394
|
-
[Grok Build guide →](https://heggria.github.io/taskflow/en/docs/guides/grok-build)
|
|
395
|
-
|
|
396
|
-
### Hermes Agent
|
|
397
|
-
|
|
398
|
-
```bash
|
|
399
|
-
hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.10 hermes-taskflow-mcp
|
|
400
|
-
# Prefer env in config.yaml (not CLI --env after args — can be stuffed into argv):
|
|
401
|
-
# mcp_servers.taskflow.env.PI_TASKFLOW_HERMES_UNSAFE_YOLO: "1" # mutating only
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
Hermes quiet mode does not report token/cost usage, so budget-declaring flows are rejected rather than silently running without enforcement. Child agents use an ephemeral HERMES_HOME with only non-secret model/fallback routing, a routed-provider-only inference `auth.json`, and provider-allowlisted dotenv keys; parent MCP, skills, memory, sessions, and rules are not inherited. RO local-read → `taskflow_readonly_files`; else `taskflow_model_only` (never omit `-t`).
|
|
405
|
-
|
|
406
|
-
[Hermes guide →](https://github.com/heggria/taskflow/blob/main/docs/hermes-mcp.md)
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
## Built to survive real work
|
|
410
|
-
|
|
411
|
-
<div align="center">
|
|
412
|
-
|
|
413
|
-
**10 packages** · **6 hosts** · **12 phase types** · **18 built-in agents** · **1,500+ tests** · **MIT**
|
|
162
|
+
| Operation | Question it answers |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `taskflow_plan` | What will run, what arguments bind, and what is the worst-case agent-call bound? |
|
|
165
|
+
| `taskflow_verify` / `taskflow_compile` | Is the graph structurally valid and what is its canonical form? |
|
|
166
|
+
| `taskflow_trace` / `taskflow_replay` | What happened, or what would a zero-token what-if replay decide? |
|
|
167
|
+
| `taskflow_why_stale` / `taskflow_recompute` | What changed and what is the smallest affected frontier? |
|
|
168
|
+
| `taskflow_why_effect` | Why was a declared effect allowed, staged, committed, rejected, or left unknown? |
|
|
169
|
+
| `taskflow_analytics` | How have recent runs behaved? |
|
|
414
170
|
|
|
415
|
-
|
|
171
|
+
The MCP surface currently exposes **20 tools**. Intermediate transcripts remain inside the runtime unless you explicitly inspect them with `peek` or `trace`; the host normally receives only `finalOutput`.
|
|
416
172
|
|
|
417
|
-
|
|
418
|
-
taskflow-core
|
|
419
|
-
┌──────────────┼───────────────┐
|
|
420
|
-
│ │ │
|
|
421
|
-
taskflow-dsl pi-taskflow taskflow-mcp-core ─┐
|
|
422
|
-
taskflow-hosts ─────┼─ codex-taskflow
|
|
423
|
-
├─ claude-taskflow
|
|
424
|
-
├─ opencode-taskflow
|
|
425
|
-
└─ grok-taskflow / hermes-taskflow
|
|
426
|
-
```
|
|
173
|
+
## Host adapters
|
|
427
174
|
|
|
428
|
-
|
|
175
|
+
The same flow contract can be delivered through six coding-agent hosts:
|
|
429
176
|
|
|
430
|
-
|
|
177
|
+
- **Pi** — native extension, `/tf` commands, live run views, and interactive approvals.
|
|
178
|
+
- **Codex** — plugin and stdio MCP server.
|
|
179
|
+
- **Claude Code** — plugin and stdio MCP server.
|
|
180
|
+
- **OpenCode** — MCP configuration and generated skill.
|
|
181
|
+
- **Grok Build** — MCP configuration and generated skill.
|
|
182
|
+
- **Hermes Agent** — MCP delivery with explicit child toolsets and isolation policy.
|
|
431
183
|
|
|
432
|
-
|
|
184
|
+
Host support is not a blanket security guarantee. Read the [host support baseline](https://github.com/heggria/taskflow/blob/main/conformance/workspace/host-support-baseline.json) and the [Trusted Effects documentation](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3.0-trusted-effects-mvp.md) before enabling mutating phases.
|
|
433
185
|
|
|
434
|
-
|
|
435
|
-
|---|---|
|
|
436
|
-
| [Getting Started](https://heggria.github.io/taskflow/en/docs/getting-started) | Your first successful run |
|
|
437
|
-
| [Concepts](https://heggria.github.io/taskflow/en/docs/concepts/) | DAGs, isolation, verification, resume, shared context |
|
|
438
|
-
| [Syntax](https://heggria.github.io/taskflow/en/docs/syntax/) | Phase fields, control flow, budgets, caching, scorers |
|
|
439
|
-
| [Compiler & Runtime](https://heggria.github.io/taskflow/en/docs/compiler-runtime/) | TypeScript DSL, FlowIR, replay, recompute, background runs |
|
|
440
|
-
| [Host Guides](https://heggria.github.io/taskflow/en/docs/guides/) | Pi, Codex, Claude Code, OpenCode, Grok, and Hermes setup |
|
|
441
|
-
| [Reference](https://heggria.github.io/taskflow/en/docs/reference/) | Commands, shorthand, and exact tool surfaces |
|
|
442
|
-
| [Showcase](https://heggria.github.io/taskflow/en/docs/showcase/) | Real flows and case studies |
|
|
443
|
-
| [0.2.0 Frontier Assessment](https://github.com/heggria/taskflow/blob/main/docs/taskflow-0.2.0-frontier-assessment.zh-CN.md) | Independent, evidence-based technical assessment (Chinese) |
|
|
186
|
+
## Security boundaries we state plainly
|
|
444
187
|
|
|
445
|
-
|
|
188
|
+
- `effects[]` is a declaration and validation surface; it is not ambient authority.
|
|
189
|
+
- The resources layer is the only finalizer for admitted declared filesystem effects.
|
|
190
|
+
- Direct writes to declared targets are detected and restored by the MVP path.
|
|
191
|
+
- Writes to undeclared paths remain host-policy dependent under resolve-only execution.
|
|
192
|
+
- `SecretRef` and `ServiceRef` are typed handles only; no vault or live service adapter ships in this cut.
|
|
193
|
+
- There is no FileBroker or full OS sandbox claim in 0.3 MVP.
|
|
194
|
+
- Control Plane stores, approvals, receipts, and WebUI are future 0.3-C stages, not proof that 0.3 is released or GA.
|
|
446
195
|
|
|
447
|
-
##
|
|
196
|
+
## Development
|
|
448
197
|
|
|
449
198
|
```bash
|
|
450
199
|
pnpm install
|
|
451
200
|
pnpm run typecheck
|
|
452
201
|
pnpm test
|
|
453
202
|
pnpm run build
|
|
203
|
+
pnpm run build:website
|
|
454
204
|
pnpm run test:pack
|
|
455
205
|
```
|
|
456
206
|
|
|
457
|
-
|
|
207
|
+
The monorepo contains the host-neutral `taskflow-core`, Trusted Effects and resources code, the `taskflow-control` 0.3-C contract package, the TypeScript DSL, MCP/host adapters, examples, and the website. See [`AGENTS.md`](https://github.com/heggria/taskflow/blob/main/AGENTS.md) for architecture and coding conventions.
|
|
208
|
+
|
|
209
|
+
## Documentation
|
|
210
|
+
|
|
211
|
+
| Start here | Use it for |
|
|
212
|
+
|---|---|
|
|
213
|
+
| [0.3 overview](https://heggria.github.io/taskflow/en/docs) | Candidate scope, status, and the honest security boundary |
|
|
214
|
+
| [Getting Started](https://heggria.github.io/taskflow/en/docs/getting-started) | First flow and host setup |
|
|
215
|
+
| [Core Concepts](https://heggria.github.io/taskflow/en/docs/concepts/) | DAGs, isolation, verification, resume, and evidence |
|
|
216
|
+
| [Compiler & Runtime](https://heggria.github.io/taskflow/en/docs/compiler-runtime/) | JSON, TypeScript DSL, FlowIR, replay, and recompute |
|
|
217
|
+
| [Host Guides](https://heggria.github.io/taskflow/en/docs/guides/) | Pi, Codex, Claude Code, OpenCode, Grok, and Hermes |
|
|
218
|
+
| [Examples](https://github.com/heggria/taskflow/blob/main/examples) | Runnable flow definitions, including Trusted Effects |
|
|
219
|
+
| [Changelog](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md) | Release history and candidate notes |
|
|
458
220
|
|
|
459
221
|
## License
|
|
460
222
|
|
|
@@ -462,8 +224,8 @@ Contributions are welcome. Start with [`CONTRIBUTING.md`](https://github.com/heg
|
|
|
462
224
|
|
|
463
225
|
<div align="center">
|
|
464
226
|
|
|
465
|
-
**Declare
|
|
227
|
+
**Declare the effect. Verify the path. Commit through one authority.**
|
|
466
228
|
|
|
467
|
-
[Read the docs](https://heggria.github.io/taskflow/en/docs) · [Try
|
|
229
|
+
[Read the docs](https://heggria.github.io/taskflow/en/docs) · [Try the candidate](#quickstart) · [View releases](https://github.com/heggria/taskflow/releases)
|
|
468
230
|
|
|
469
231
|
</div>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-taskflow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0-beta.1",
|
|
4
4
|
"description": "Run taskflow on Claude Code: the npm tarball provides the Claude subagent runner and MCP server; the plugin is distributed through the repository marketplace.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
|
@@ -48,9 +48,9 @@
|
|
|
48
48
|
"access": "public"
|
|
49
49
|
},
|
|
50
50
|
"dependencies": {
|
|
51
|
-
"taskflow-core": "0.
|
|
52
|
-
"taskflow-hosts": "0.
|
|
53
|
-
"taskflow-mcp-core": "0.
|
|
51
|
+
"taskflow-core": "0.3.0-beta.1",
|
|
52
|
+
"taskflow-hosts": "0.3.0-beta.1",
|
|
53
|
+
"taskflow-mcp-core": "0.3.0-beta.1"
|
|
54
54
|
},
|
|
55
55
|
"scripts": {
|
|
56
56
|
"build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/copy-readme.mjs claude-taskflow"
|