pi-taskflow 0.0.5 → 0.0.7

package/DESIGN.md

@@ -204,6 +204,19 @@ pi-taskflow/
 | `map` | 对上游数组**动态 fan-out**，每项一个 agent | ≤concurrency |
 | `gate` | 质量门 / 对抗 review（可决定是否继续） | 1+ |
 | `reduce` | 把多结果聚合为一（synthesize） | 1 |
+| `approval` | **人在环**：暂停等待 approve / reject / edit | 1 |
+| `flow` | 把一个**已保存的 taskflow** 当作单个 phase 运行（组合复用） | 子流程并发 |
+
+### 3.3b 控制流 / 可靠性字段（任意 phase）
+
+| 字段 | 语义 |
+|------|------|
+| `when` | 条件守卫：表达式为假则 skip 该 phase。支持 `{refs}`、`== != < > <= >=`、`&& \|\| !`、括号、字符串/数字字面量。解析失败 fail-open（仍运行） |
+| `join` | 依赖 join：`all`（默认，等全部 dep）/ `any`（OR-join，任一 dep 完成即运行） |
+| `retry` | `{max, backoffMs, factor}`：失败重试，延迟 = `backoffMs * factor^attempt` |
+| `use` / `with` | `flow` 子流程的名字与入参（入参字符串值会插值） |
+
+顶层 `budget: {maxUSD, maxTokens}`：累计成本/token 超限即停（剩余 phase skip，运行态 `blocked`）。
 
 ### 3.4 模板插值
 
@@ -293,7 +306,8 @@ export async function runTaskflow(def, args, ctx): Promise<TaskflowResult>
 | **v0.1** | DSL + schema + runtime（agent/parallel/map/reduce）+ `taskflow` 工具 + `/tf run` + 内存隔离 + 流式进度 | ✅ 已发布 (npm 0.0.1) |
 | **v0.2** | 保存/动态命令注册 + 跨 session 恢复 + `gate` 真门控 + run 历史交互 TUI | ✅ 已完成 (npm 0.0.3) |
 | **v0.3** | examples + SKILL.md（教 LLM 写定义）+ YAML 支持 + 发布 npm | 🚧 examples/SKILL/npm 已做；YAML 待办 |
-| **v0.4** | 真·后台执行（detached + 轮询）+ 成本预估/上限 + 内置 `deep-research` 工作流 | ⏳ 待办 |
+| **v0.6** | 控制流 & 可靠性：`when` 条件分支 + `join:any` OR-join + 声明式 `retry` + `approval` 人在环 + `flow` 子流程组合 + `budget` 成本上限 | ✅ 已完成 |
+| **v0.7+** | 真·后台执行（detached + 轮询）+ 事件/cron 触发 + 成本**预估** + mermaid DAG 导出 + 内置 `deep-research` 工作流 | ⏳ 待办 |
 
 ---
 

package/README.md

@@ -1,8 +1,14 @@
-# pi-taskflow
+<div align="center">
 
-[![npm](https://img.shields.io/npm/v/pi-taskflow.svg)](https://www.npmjs.com/package/pi-taskflow)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
-[![Pi coding agent](https://img.shields.io/badge/for-Pi%20coding%20agent-7c3aed.svg)](https://pi.dev)
+<img src="./assets/hero.png" alt="pi-taskflow — declarative, multi-phase subagent workflows" width="880">
+
+<p>
+  <a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/v/pi-taskflow?style=flat-square&color=B692FF&label=npm" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-43D9AD?style=flat-square" alt="MIT license"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-6E8BFF?style=flat-square" alt="for the Pi coding agent"></a>
+</p>
+
+</div>
 
 > Lightweight workflow orchestration for the [Pi coding agent](https://pi.dev).
 
@@ -16,9 +22,10 @@ saveable as a one-word `/tf:<name>` command.
 pi install npm:pi-taskflow
 ```
 
-Fan out one subagent per item, gate the results with an adversarial review, and
-get back only the final report — none of the intermediate transcripts ever touch
-your conversation.
+Fan out one subagent per item, route on results, retry the flaky ones, pause for
+human approval, cap the spend, and gate the output with an adversarial review —
+all from one declarative definition. Only the final report reaches your
+conversation; every intermediate transcript stays in the runtime.
 
 ## Why
 
@@ -39,6 +46,11 @@ only the final phase's output.
 | Scale | a few tasks | dynamic `map` fan-out |
 | Resumable | no | yes (cross-session, cached phases skip) |
 | Quality gates | no | `gate` phases with `VERDICT: BLOCK / PASS` |
+| Conditional routing | no | `when` guards + `join: any` OR-joins |
+| Fault tolerance | no | per-phase `retry` with backoff |
+| Human-in-the-loop | no | `approval` phases (approve / reject / edit) |
+| Cost control | no | run-wide `budget` (USD / token caps) |
+| Composition | no | `flow` phases run saved sub-flows |
 | Progress visibility | opaque while running | live DAG render with timing + cost |
 | Ergonomics | inline JSON each time | shorthand (`task`/`tasks`/`chain`) or DSL |
 
@@ -131,6 +143,36 @@ only the final report back.
 
 Save it once → `/tf:summarize-files` forever.
 
+### Route, gate, and guard
+
+Phases also **branch, retry, pause for a human, and respect a budget** — still
+declaratively, no scripting:
+
+```jsonc
+{
+  "name": "triage-and-fix",
+  "budget": { "maxUSD": 1.5 },
+  "phases": [
+    { "id": "triage", "type": "agent", "agent": "analyst", "output": "json",
+      "task": "Classify the bug. Output ONLY {\"severity\":\"high\"} or {\"severity\":\"low\"}." },
+    { "id": "deep",  "when": "{steps.triage.json.severity} == high", "dependsOn": ["triage"],
+      "agent": "executor_code", "task": "Root-cause and patch it.",
+      "retry": { "max": 2, "backoffMs": 500 } },
+    { "id": "quick", "when": "{steps.triage.json.severity} == low",  "dependsOn": ["triage"],
+      "agent": "executor_fast", "task": "Apply the quick fix." },
+    { "id": "approve", "type": "approval", "join": "any", "dependsOn": ["deep", "quick"],
+      "task": "Review the fix before it ships." },
+    { "id": "ship", "type": "agent", "dependsOn": ["approve"],
+      "task": "Open a PR with the change.", "final": true }
+  ]
+}
+```
+
+- **`when`** routes to `deep` *or* `quick` from the triage JSON; the other branch is skipped.
+- **`join: "any"`** lets `approve` run as soon as whichever branch fired completes.
+- **`retry`** re-runs a flaky patch with backoff; **`budget`** halts the whole run if it gets too expensive.
+- **`approval`** pauses for a human (approve / reject / edit) before the final `ship`.
+
 ## Watch it run
 
 This is the live progress render for a real run — the `self-improve` flow that
@@ -172,9 +214,51 @@ writes and verifies its own test suites, caught here mid-block by a quality gate
 | `map` | fan out over an array — one subagent per item, `{item}` bound | `over`, `task` |
 | `gate` | quality/review step that can **halt the flow** | `task` |
 | `reduce` | aggregate `from[]` phase outputs into one | `from`, `task` |
+| `approval` | **human-in-the-loop** pause — approve / reject / edit before continuing | — |
+| `flow` | run a **saved sub-flow** as one phase (composition/reuse) | `use` |
+
+### Common phase fields
 
-Every phase needs `id`. Optional fields: `agent`, `dependsOn`, `output`,
-`model`, `thinking`, `tools`, `cwd`, `concurrency`, `final`, `optional`.
+Every phase needs a unique `id` and a `type` (defaults to `agent`). On top of the
+per-type fields above:
+
+| Field | Meaning |
+|---|---|
+| `agent` | Agent to run (defaults to the first discovered agent) |
+| `dependsOn` | Phase ids this phase waits for — builds the DAG |
+| `join` | `"all"` (default) waits for every dep; `"any"` is an OR-join |
+| `when` | Conditional guard — skip unless the expression is truthy |
+| `retry` | `{ max, backoffMs?, factor? }` — retry a failing subagent |
+| `output` | `"text"` (default) or `"json"` (exposes `{steps.ID.json}`) |
+| `model` / `thinking` / `tools` | Per-phase overrides for the subagent |
+| `cwd` | Working directory for the subagent |
+| `concurrency` | Fan-out cap for `map` / `parallel` (overrides the flow default) |
+| `final` | Marks the result-bearing phase (else the last phase wins) |
+| `optional` | A failure here does **not** abort the run |
+| `use` / `with` | (`flow`) saved sub-flow name + its args |
+
+Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8),
+`agentScope`, and `budget: { maxUSD?, maxTokens? }`.
+
+### Control flow & reliability
+
+- **`when`** — skip a phase unless an expression is truthy. Supports `{refs}`,
+  `== != < > <= >=`, `&& || !`, parentheses, and quoted strings/numbers, e.g.
+  `"when": "{steps.triage.json.route} == deep"`. Pair with `join: "any"` on the
+  merge phase to build real if/else routing. Parse errors **fail open**.
+- **`join: "any"`** — an OR-join: the phase runs as soon as *one* dependency
+  completes (default `"all"` waits for every dep).
+- **`retry`** — `{ "max": 2, "backoffMs": 500, "factor": 2 }` retries a failing
+  subagent with fixed (`factor:1`) or exponential backoff; usage is summed and
+  the attempt count shows as `↻N` in the TUI.
+- **`approval`** — pause for a human (`select`: Approve / Reject / Edit). Reject
+  halts the flow; Edit injects the typed note as the phase output for downstream
+  steps. Non-interactive runs auto-approve.
+- **`flow`** — `{ "type": "flow", "use": "deep-research", "with": { "topic": "{item}" } }`
+  runs a saved flow as a phase (recursion is detected and rejected).
+- **`budget`** — a run-wide `{maxUSD, maxTokens}` ceiling; once exceeded, pending
+  phases are skipped (and in-flight fan-out stops spawning) and the run is
+  `blocked`.
 
 ### `output` format
 
@@ -263,9 +347,26 @@ file). Phase-level overrides for `model`, `thinking`, and `tools` are passed as
 Settings from `~/.pi/agent/settings.json` (the `subagents.agentOverrides` map)
 are honored, letting you tweak model, thinking, or tools per agent across all flows.
 
+## Examples
+
+Ready-to-read definitions live in [`examples/`](./examples):
+
+| File | Demonstrates |
+|---|---|
+| [`summarize-files.json`](./examples/summarize-files.json) | discover → `map` fan-out → `reduce` |
+| [`conditional-research.json`](./examples/conditional-research.json) | `when` routing + `join: any` + `gate` + `budget` |
+| [`guarded-refactor.json`](./examples/guarded-refactor.json) | `approval` (human-in-the-loop) + `retry` + `gate` |
+
+To use one, copy it into `.pi/taskflows/<name>.json` (or
+`~/.pi/agent/taskflows/`) and it registers as `/tf:<name>` — or just point the
+model at the definition.
+
 ## Status & limits
 
-- **v0.0.4** — DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`),
+- **v0.0.6** — control flow & reliability: conditional `when` guards, `join: any`
+  OR-joins, declarative `retry`/backoff, `approval` (human-in-the-loop) phases,
+  `flow` (saved sub-flow composition), and run-wide `budget` caps — on top of the
+  DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`),
   inline + saved flows, cross-session resume, live progress, isolated context.
   Default `concurrency` is 8 (set on the flow; per-phase `concurrency` overrides
   for that phase).
@@ -279,7 +380,8 @@ are honored, letting you tweak model, thinking, or tools per agent across all fl
 ### What it doesn't do (yet)
 
 - **No detached background execution.** A run needs the pi session to stay open.
-  True background execution is on the roadmap.
+  True background execution (and event/cron triggers on top of it) is on the
+  roadmap.
 - **No `output: "file"`.** Outputs are text/JSON only. Write files via agent
   tool calls if needed.
 - **`map` requires a JSON array.** The `over` field must resolve to
@@ -292,13 +394,10 @@ are honored, letting you tweak model, thinking, or tools per agent across all fl
 ```bash
 npm install
 npm run typecheck
-node --experimental-strip-types --test test/interpolate.test.ts \
-  test/schema.test.ts test/runtime.test.ts test/runner.test.ts \
-  test/store.test.ts test/agents.test.ts test/render.test.ts \
-  test/desugar.test.ts
+npm test            # unit tests — no network, no process spawning
 
 # real end-to-end (spawns live subagents; needs model access)
-PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts
+npm run test:e2e
 ```
 
 ## Contributing

package/examples/conditional-research.json

@@ -0,0 +1,56 @@
+{
+  "name": "conditional-research",
+  "description": "Triage a topic, route to a deep or quick research branch (conditional `when` + OR-join), gate the result, and report.",
+  "version": 1,
+  "args": {
+    "topic": { "description": "The subject to research" }
+  },
+  "concurrency": 4,
+  "agentScope": "user",
+  "budget": { "maxUSD": 1.0 },
+  "phases": [
+    {
+      "id": "triage",
+      "type": "agent",
+      "agent": "analyst",
+      "task": "Decide how much research the topic \"{args.topic}\" needs. Output ONLY JSON: {\"route\": \"deep\"} for broad/ambiguous topics, or {\"route\": \"quick\"} for narrow/well-defined ones.",
+      "output": "json"
+    },
+    {
+      "id": "deep",
+      "type": "agent",
+      "agent": "explorer",
+      "when": "{steps.triage.json.route} == deep",
+      "dependsOn": ["triage"],
+      "task": "Do a thorough, multi-angle investigation of \"{args.topic}\". Cover background, key players, trade-offs, and open questions.",
+      "retry": { "max": 2, "backoffMs": 500, "factor": 2 }
+    },
+    {
+      "id": "quick",
+      "type": "agent",
+      "agent": "explorer",
+      "when": "{steps.triage.json.route} == quick",
+      "dependsOn": ["triage"],
+      "task": "Give a concise, focused answer on \"{args.topic}\" with the 3 most important points.",
+      "retry": { "max": 2, "backoffMs": 500, "factor": 2 }
+    },
+    {
+      "id": "review",
+      "type": "gate",
+      "agent": "critic",
+      "join": "any",
+      "from": ["deep", "quick"],
+      "dependsOn": ["deep", "quick"],
+      "task": "Review the research below for unsupported claims. If it is solid, end with 'VERDICT: PASS'; if it is too thin, end with 'VERDICT: BLOCK' and one reason.\n\n{steps.deep.output}{steps.quick.output}"
+    },
+    {
+      "id": "report",
+      "type": "reduce",
+      "from": ["review"],
+      "dependsOn": ["review"],
+      "agent": "doc-writer",
+      "task": "Write a clean markdown brief on \"{args.topic}\" from the validated research:\n\n{steps.deep.output}{steps.quick.output}",
+      "final": true
+    }
+  ]
+}

package/examples/guarded-refactor.json

@@ -0,0 +1,50 @@
+{
+  "name": "guarded-refactor",
+  "description": "Plan a change, pause for human approval before touching code (HITL), then implement with retries and a final review gate. Budget-capped.",
+  "version": 1,
+  "args": {
+    "target": { "default": "src", "description": "Directory or module to refactor" },
+    "goal": { "description": "What the refactor should achieve" }
+  },
+  "concurrency": 4,
+  "agentScope": "user",
+  "budget": { "maxUSD": 2.0 },
+  "phases": [
+    {
+      "id": "plan",
+      "type": "agent",
+      "agent": "planner",
+      "task": "Produce a concrete, step-by-step refactor plan for {args.target} to achieve: {args.goal}. List the files you would change and the risks."
+    },
+    {
+      "id": "approve",
+      "type": "approval",
+      "dependsOn": ["plan"],
+      "task": "Review the refactor plan above. Approve to proceed, reject to abort, or edit to add constraints the implementer must follow."
+    },
+    {
+      "id": "implement",
+      "type": "agent",
+      "agent": "executor_code",
+      "dependsOn": ["approve"],
+      "task": "Implement the approved plan for {args.target}.\nPlan:\n{steps.plan.output}\nExtra human guidance (if any):\n{steps.approve.output}",
+      "retry": { "max": 1, "backoffMs": 1000 }
+    },
+    {
+      "id": "review",
+      "type": "gate",
+      "agent": "reviewer",
+      "dependsOn": ["implement"],
+      "task": "Review the implementation report below. If it is correct and complete, end with 'VERDICT: PASS'; otherwise 'VERDICT: BLOCK' with reasons.\n\n{steps.implement.output}"
+    },
+    {
+      "id": "summary",
+      "type": "reduce",
+      "from": ["review"],
+      "dependsOn": ["review"],
+      "agent": "doc-writer",
+      "task": "Write a short changelog entry summarizing what was done:\n\n{steps.implement.output}",
+      "final": true
+    }
+  ]
+}

package/extensions/agents.ts

@@ -55,7 +55,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = (() => {
+			try {
+				return parseFrontmatter<Record<string, string>>(content);
+			} catch {
+				// A single malformed agent file must not break discovery for every flow.
+				return { frontmatter: {} as Record<string, string>, body: "" };
+			}
+		})();
 		if (!frontmatter.name || !frontmatter.description) continue;
 
 		const tools = frontmatter.tools

package/extensions/index.ts

@@ -18,8 +18,8 @@ import { Type } from "typebox";
 import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
 import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
-import { executeTaskflow, type RuntimeResult } from "./runtime.ts";
-import { finalPhase, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
+import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
+import { finalPhase, resolveArgs, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
 import {
 	getFlow,
 	listFlows,
@@ -86,17 +86,6 @@ const TaskflowParams = Type.Object({
 	),
 });
 
-function resolveArgs(def: Taskflow, provided: Record<string, unknown> | undefined): Record<string, unknown> {
-	const args: Record<string, unknown> = {};
-	for (const [key, spec] of Object.entries(def.args ?? {})) {
-		if (provided && key in provided) args[key] = provided[key];
-		else if (spec.default !== undefined) args[key] = spec.default;
-	}
-	// also pass through any extra provided args
-	if (provided) for (const [k, v] of Object.entries(provided)) if (!(k in args)) args[k] = v;
-	return args;
-}
-
 function makeRunState(def: Taskflow, args: Record<string, unknown>, cwd: string): RunState {
 	return {
 		runId: newRunId(def.name),
@@ -153,6 +142,29 @@ async function runFlow(
 		(heartbeat as { unref?: () => void }).unref?.();
 	}
 
+	// Human-in-the-loop approver — only when an interactive UI is available.
+	const requestApproval = ctx.hasUI
+		? async (req: ApprovalRequest): Promise<ApprovalDecision> => {
+				if (req.upstream?.trim()) {
+					const snip = req.upstream.replace(/\s+/g, " ").trim();
+					ctx.ui.notify(`[${def.name}/${req.phaseId}] ${snip.length > 280 ? `${snip.slice(0, 280)}…` : snip}`, "info");
+				}
+				const choice = await ctx.ui.select(
+					`Taskflow approval — ${req.phaseId}: ${req.message}`,
+					["Approve", "Reject", "Edit / add guidance"],
+					{ signal },
+				);
+				if (!choice || choice === "Reject") return { decision: "reject" };
+				if (choice.startsWith("Edit")) {
+					const note = await ctx.ui.input("Guidance passed downstream as this phase's output", "type guidance…", {
+						signal,
+					});
+					return { decision: "edit", note: note ?? "" };
+				}
+				return { decision: "approve" };
+			}
+		: undefined;
+
 	try {
 		const result = await executeTaskflow(state, {
 			cwd: ctx.cwd,
@@ -160,6 +172,8 @@ async function runFlow(
 			globalThinking: settings.globalThinking,
 			signal,
 			persist: persistThrottled,
+			requestApproval,
+			loadFlow: (name: string) => getFlow(ctx.cwd, name)?.def,
 		});
 		return result;
 	} finally {
@@ -199,11 +213,12 @@ export default function (pi: ExtensionAPI) {
 		label: "Taskflow",
 		description: [
 			"Orchestrate a multi-phase workflow of subagents from a declarative definition.",
-			"Phases (agent, parallel, map, gate, reduce) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
+			"Phases (agent, parallel, map, gate, reduce, approval, flow) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
 			"Use action=run with an inline `define` (you write the DSL) or a saved `name`.",
 			"For simple non-DAG delegations (like the subagent tool) skip the DSL: pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` to run in parallel, or `chain:[{task,agent?}]` to run sequentially (reference the prior step with {previous.output}).",
 			"Use action=save to persist a definition as a reusable /tf:<name> command. action=resume continues a paused run. action=list shows saved flows.",
-			"DSL: {name, args?, concurrency?, phases:[{id, type, agent, task, dependsOn?, over?(map), as?(map), branches?(parallel), from?(reduce), output?:'json', final?}]}.",
+			"DSL: {name, args?, concurrency?, budget?:{maxUSD,maxTokens}, phases:[{id, type, agent, task, dependsOn?, join?:'all'|'any', when?, retry?:{max,backoffMs,factor}, over?(map), as?(map), branches?(parallel), from?(reduce), use?(flow), with?(flow), output?:'json', final?}]}.",
+			"Phase types: agent (one subagent), parallel (static branches), map (dynamic fan-out over an array), gate (VERDICT: PASS/BLOCK quality gate), reduce (aggregate from N phases), approval (human-in-the-loop pause), flow (run a saved sub-flow). join:'any' is an OR-join; when is a conditional guard; retry adds backoff; budget caps run cost.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
@@ -286,19 +301,28 @@ export default function (pi: ExtensionAPI) {
 							);
 					},
 				});
+				const warningText = v.warnings.length ? `\n\nWarnings:\n- ${v.warnings.join("\n- ")}` : "";
 				return {
 					content: [
-						{ type: "text", text: `Saved taskflow '${def.name}' → ${filePath}\nRun it with /tf:${def.name} or action=run.` },
+						{ type: "text", text: `Saved taskflow '${def.name}' → ${filePath}\nRun it with /tf:${def.name} or action=run.${warningText}` },
 					],
 					details: { action, message: filePath } satisfies TaskflowDetails,
 				};
 			}
 
 			// run
-			const v = validateTaskflow(def);
-			if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
 			const args = resolveArgs(def, params.args);
+			const v = validateTaskflow(def, { args, cwd: ctx.cwd });
+			if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
+			for (const w of v.warnings) {
+				console.warn(`[taskflow:${def.name}] ${w}`);
+			}
 			const result = await runFlow(def, args, ctx, signal, onUpdate as any);
+			// Surface the validation warnings in the tool result so the model
+			// can acknowledge or fix them, and the user sees them in the chat.
+			if (v.warnings.length) {
+				result.finalOutput = `${result.finalOutput}\n\nWarnings:\n- ${v.warnings.join("\n- ")}`;
+			}
 			return finalResult(action, result);
 		},