pi-taskflow 0.0.2 → 0.0.3

package/DESIGN.md

@@ -288,12 +288,12 @@ export async function runTaskflow(def, args, ctx): Promise<TaskflowResult>
 
 ## 5. 路线图
 
-| 版本 | 范围 |
-|------|------|
-| **v0.1** | DSL + schema + runtime（agent/parallel/map/reduce）+ `taskflow` 工具 + `/tf run` + 内存隔离 + 流式进度 |
-| **v0.2** | 保存/动态命令注册 + 跨 session 恢复 + `gate` 阶段 + run 历史 TUI |
-| **v0.3** | examples + SKILL.md（教 LLM 写定义）+ YAML 支持 + 发布 npm |
-| **v0.4** | 真·后台执行（detached + 轮询）+ 成本预估/上限 + 内置 `deep-research` 工作流 |
+| 版本 | 范围 | 状态 |
+|------|------|------|
+| **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` 工作流 | ⏳ 待办 |
 
 ---
 

package/extensions/index.ts

@@ -17,6 +17,7 @@ import { Text } from "@earendil-works/pi-tui";
 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 } from "./schema.ts";
 import {
@@ -306,15 +307,30 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (sub === "runs") {
-				const runs = listRuns(ctx.cwd);
+				const runs = listRuns(ctx.cwd, 50);
 				if (runs.length === 0) {
 					ctx.ui.notify("No taskflow runs yet.", "info");
 					return;
 				}
-				ctx.ui.notify(
-					runs.map((r) => `${r.runId} [${r.status}] ${r.flowName} — ${summarizeRun(r)}`).join("\n"),
-					"info",
-				);
+				if (!ctx.hasUI) {
+					ctx.ui.notify(
+						runs.map((r) => `${r.runId} [${r.status}] ${r.flowName} — ${summarizeRun(r)}`).join("\n"),
+						"info",
+					);
+					return;
+				}
+				const result = await ctx.ui.custom<RunHistoryResult | undefined>((_tui, theme, _kb, done) => {
+					return new RunHistoryComponent(runs, theme, (r) => done(r));
+				});
+				if (result?.action === "resume") {
+					if (ctx.isIdle()) {
+						pi.sendUserMessage(
+							`Resume the taskflow run "${result.runId}" using the taskflow tool with action="resume", runId="${result.runId}".`,
+						);
+					} else {
+						ctx.ui.notify("Agent is busy; try /tf resume when idle.", "warning");
+					}
+				}
 				return;
 			}
 

package/extensions/render.ts

@@ -115,7 +115,11 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	const type = phase.type ?? "agent";
 	if (!ps || ps.status === "pending") return theme.fg("dim", "—");
 
-	if (ps.status === "skipped") return theme.fg("muted", "skipped · upstream failed");
+	if (ps.status === "skipped") {
+		const reason = (ps.error ?? "upstream failed").replace(/\s+/g, " ");
+		const snip = reason.length > 52 ? `${reason.slice(0, 52)}…` : reason;
+		return theme.fg("muted", `skipped · ${snip}`);
+	}
 
 	const isFanout = type === "map" || type === "parallel";
 
@@ -167,6 +171,18 @@ function phaseDetail(phase: Phase, ps: PhaseState | undefined, theme: Theme): st
 	// single-agent done
 	const model = shortModel(ps.model);
 	const u = compactUsage(ps.usage, theme);
+	if (ps.gate) {
+		const badge =
+			ps.gate.verdict === "block" ? theme.fg("error", theme.bold("BLOCK")) : theme.fg("success", "PASS");
+		let g = badge;
+		if (ps.gate.reason) {
+			const r = ps.gate.reason.replace(/\s+/g, " ");
+			g += theme.fg("dim", ` ${r.length > 44 ? `${r.slice(0, 44)}…` : r}`);
+		}
+		if (model) g += `  ${theme.fg("dim", model)}`;
+		if (time) g += `  ${time}`;
+		return g;
+	}
 	let s = "";
 	if (model) s += theme.fg("accent", model);
 	if (u) s += (s ? "  " : "") + u;
@@ -187,9 +203,11 @@ function headerLine(state: RunState, theme: Theme): string {
 			? theme.fg("success", "✓")
 			: state.status === "failed"
 				? theme.fg("error", "✗")
-				: state.status === "paused"
-					? theme.fg("warning", "‖")
-					: theme.fg("warning", spinnerFrame());
+				: state.status === "blocked"
+					? theme.fg("error", "⊗")
+					: state.status === "paused"
+						? theme.fg("warning", "‖")
+						: theme.fg("warning", spinnerFrame());
 
 	let line =
 		`${head} ${theme.fg("toolTitle", theme.bold("taskflow"))} ` +
@@ -197,6 +215,7 @@ function headerLine(state: RunState, theme: Theme): string {
 		theme.fg("muted", `  ${done}/${total}`);
 	if (running) line += theme.fg("warning", ` · ${running}▸`);
 	if (failed) line += theme.fg("error", ` · ${failed}✗`);
+	if (state.status === "blocked") line += theme.fg("error", " · blocked");
 	const cost = aggregateCost(state);
 	if (cost) line += theme.fg("muted", ` · $${cost.toFixed(3)}`);
 	const el = runElapsed(state);

package/extensions/runs-view.ts

@@ -0,0 +1,141 @@
+/**
+ * Interactive run-history view for `/tf runs` (ctx.ui.custom).
+ * List view: navigate runs; Enter → detail; r → resume; Esc/q → close.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { renderProgress, summarizeRun } from "./render.ts";
+import type { RunState } from "./store.ts";
+
+export interface RunHistoryResult {
+	action: "resume";
+	runId: string;
+}
+
+function statusBadge(status: RunState["status"], theme: Theme): string {
+	switch (status) {
+		case "completed":
+			return theme.fg("success", "✓ done");
+		case "failed":
+			return theme.fg("error", "✗ failed");
+		case "blocked":
+			return theme.fg("error", "⊗ blocked");
+		case "paused":
+			return theme.fg("warning", "‖ paused");
+		default:
+			return theme.fg("warning", "◐ running");
+	}
+}
+
+function timeAgo(ts: number): string {
+	const s = Math.floor((Date.now() - ts) / 1000);
+	if (s < 60) return `${s}s ago`;
+	if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+	if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+	return `${Math.floor(s / 86400)}d ago`;
+}
+
+function isResumable(r: RunState): boolean {
+	return r.status === "paused" || r.status === "failed" || r.status === "blocked";
+}
+
+export class RunHistoryComponent {
+	private runs: RunState[];
+	private theme: Theme;
+	private onDone: (result?: RunHistoryResult) => void;
+	private selected = 0;
+	private mode: "list" | "detail" = "list";
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(runs: RunState[], theme: Theme, onDone: (result?: RunHistoryResult) => void) {
+		this.runs = runs;
+		this.theme = theme;
+		this.onDone = onDone;
+	}
+
+	handleInput(data: string): void {
+		this.invalidate();
+		if (this.mode === "detail") {
+			if (matchesKey(data, "escape")) {
+				this.mode = "list";
+				return;
+			}
+			if (data === "r" && isResumable(this.runs[this.selected])) {
+				this.onDone({ action: "resume", runId: this.runs[this.selected].runId });
+			}
+			return;
+		}
+		// list mode
+		if (matchesKey(data, "escape") || data === "q" || matchesKey(data, "ctrl+c")) {
+			this.onDone();
+			return;
+		}
+		if (matchesKey(data, "up")) {
+			this.selected = (this.selected - 1 + this.runs.length) % this.runs.length;
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.selected = (this.selected + 1) % this.runs.length;
+			return;
+		}
+		if (matchesKey(data, "return")) {
+			this.mode = "detail";
+			return;
+		}
+		if (data === "r" && isResumable(this.runs[this.selected])) {
+			this.onDone({ action: "resume", runId: this.runs[this.selected].runId });
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const th = this.theme;
+		const lines: string[] = [""];
+
+		if (this.mode === "detail") {
+			const run = this.runs[this.selected];
+			lines.push(truncateToWidth(`  ${th.fg("accent", "Run ")}${th.fg("muted", run.runId)}`, width));
+			lines.push("");
+			for (const l of renderProgress(run, th).split("\n")) lines.push(truncateToWidth(l, width));
+			lines.push("");
+			const hint = isResumable(run) ? "Esc back · r resume" : "Esc back";
+			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}`, width));
+			lines.push("");
+			this.cachedWidth = width;
+			this.cachedLines = lines;
+			return lines;
+		}
+
+		// list mode
+		const header =
+			th.fg("borderMuted", "─".repeat(3)) +
+			th.fg("accent", " Taskflow runs ") +
+			th.fg("borderMuted", "─".repeat(Math.max(0, width - 18)));
+		lines.push(truncateToWidth(header, width));
+		lines.push("");
+
+		this.runs.forEach((run, i) => {
+			const sel = i === this.selected;
+			const marker = sel ? th.fg("accent", "❯ ") : "  ";
+			const badge = statusBadge(run.status, th);
+			const name = sel ? th.fg("text", run.flowName) : th.fg("muted", run.flowName);
+			const meta = th.fg("dim", `${summarizeRun(run)} · ${timeAgo(run.updatedAt)}`);
+			lines.push(truncateToWidth(`  ${marker}${badge}  ${name}  ${meta}`, width));
+		});
+
+		lines.push("");
+		lines.push(truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}`, width));
+		lines.push("");
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/extensions/runtime.ts

@@ -178,7 +178,9 @@ async function executePhase(
 			}
 			emitProgress();
 		});
-		return resultToPhaseState(phase.id, r, inputHash, parseJson);
+		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
+		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
+		return ps;
 	}
 
 	if (type === "parallel") {
@@ -285,6 +287,36 @@ function defaultAgent(deps: RuntimeDeps): string {
 	return deps.agents[0]?.name ?? "default";
 }
 
+/**
+ * Parse a gate phase's output into a verdict. Blocks the flow only on an
+ * explicit negative signal; ambiguous output passes (fail-open).
+ * Accepts JSON ({continue|pass: bool} or {verdict: "..."}) or a text marker
+ * `VERDICT: PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT` (last occurrence wins).
+ */
+export function parseGateVerdict(output: string): { verdict: "pass" | "block"; reason?: string } {
+	const json = safeParse(output);
+	if (json && typeof json === "object") {
+		const o = json as Record<string, unknown>;
+		if (typeof o.continue === "boolean") return { verdict: o.continue ? "pass" : "block", reason: asReason(o.reason) };
+		if (typeof o.pass === "boolean") return { verdict: o.pass ? "pass" : "block", reason: asReason(o.reason) };
+		if (typeof o.verdict === "string") {
+			const block = /block|fail|stop|reject|halt|\bno\b/i.test(o.verdict);
+			return { verdict: block ? "block" : "pass", reason: asReason(o.reason) };
+		}
+	}
+	const matches = [...output.matchAll(/VERDICT\s*[:=]\s*(PASS|BLOCK|FAIL|STOP|OK|REJECT|HALT)/gi)];
+	if (matches.length) {
+		const v = matches[matches.length - 1][1].toUpperCase();
+		const pass = v === "PASS" || v === "OK";
+		return { verdict: pass ? "pass" : "block" };
+	}
+	return { verdict: "pass" };
+}
+
+function asReason(v: unknown): string | undefined {
+	return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+
 /**
  * Execute a full taskflow. Mutates and persists `state` as it progresses.
  */
@@ -297,6 +329,9 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 	deps.onProgress?.(state);
 
 	let aborted = false;
+	let gateBlocked = false;
+	let gateReason = "";
+	let gateOutput = "";
 
 	for (const layer of layers) {
 		if (deps.signal?.aborted) {
@@ -308,13 +343,13 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 		await mapWithConcurrencyLimit(layer, layerConcurrency, async (phase) => {
 			// Snapshot prior state BEFORE marking running, so resume cache checks work.
 			const prior = state.phases[phase.id];
-			// Skip if a dependency failed (unless this phase is optional).
+			// Skip if a dependency failed, or an upstream gate blocked the flow.
 			const failedDep = dependenciesOf(phase).some((d) => state.phases[d]?.status === "failed");
-			if (failedDep) {
+			if (gateBlocked || failedDep) {
 				state.phases[phase.id] = {
 					id: phase.id,
 					status: "skipped",
-					error: "Upstream dependency failed",
+					error: gateBlocked ? `Gate blocked${gateReason ? `: ${gateReason}` : ""}` : "Upstream dependency failed",
 					endedAt: Date.now(),
 					usage: emptyUsage(),
 				};
@@ -333,6 +368,11 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 
 			const ps = await executePhase(phase, state, deps, prior, () => deps.onProgress?.(state));
 			state.phases[phase.id] = ps;
+			if ((phase.type ?? "agent") === "gate" && ps.gate?.verdict === "block") {
+				gateBlocked = true;
+				gateReason = ps.gate.reason ?? "";
+				gateOutput = ps.output ?? "";
+			}
 			deps.persist?.(state);
 			deps.onProgress?.(state);
 		});
@@ -342,14 +382,19 @@ export async function executeTaskflow(state: RunState, deps: RuntimeDeps): Promi
 	const finalState = state.phases[fp.id];
 	const anyFailed = Object.values(state.phases).some((p) => p.status === "failed");
 
-	state.status = aborted ? "paused" : anyFailed ? "failed" : "completed";
+	state.status = aborted ? "paused" : gateBlocked ? "blocked" : anyFailed ? "failed" : "completed";
 	deps.persist?.(state);
 	deps.onProgress?.(state);
 
+	let finalOutput = finalState?.output ?? "(no output)";
+	if (gateBlocked && (!finalState || finalState.status === "skipped")) {
+		finalOutput = `Gate blocked the workflow.${gateReason ? `\nReason: ${gateReason}` : ""}${gateOutput ? `\n\n${gateOutput}` : ""}`;
+	}
+
 	const totalUsage = aggregateUsage(Object.values(state.phases).map((p) => p.usage ?? emptyUsage()));
 	return {
 		state,
-		finalOutput: finalState?.output ?? "(no output)",
+		finalOutput,
 		ok: state.status === "completed",
 		totalUsage,
 	};

package/extensions/store.ts

@@ -37,6 +37,8 @@ export interface PhaseState {
 	subProgress?: { done: number; total: number; running: number; failed: number };
 	/** Latest activity line from the running subagent(s). */
 	liveText?: string;
+	/** Gate verdict (gate phases only). */
+	gate?: { verdict: "pass" | "block"; reason?: string };
 }
 
 export interface RunState {
@@ -44,7 +46,7 @@ export interface RunState {
 	flowName: string;
 	def: Taskflow;
 	args: Record<string, unknown>;
-	status: "running" | "completed" | "failed" | "paused";
+	status: "running" | "completed" | "failed" | "paused" | "blocked";
 	phases: Record<string, PhaseState>;
 	createdAt: number;
 	updatedAt: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Lightweight workflow orchestration for the Pi coding agent — declarative multi-phase taskflows with dynamic fan-out, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",

package/skills/taskflow/SKILL.md

@@ -55,9 +55,29 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 | `agent` | one subagent runs `task` |
 | `parallel` | run `branches[]` concurrently |
 | `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
-| `gate` | quality/review step (a focused agent pass) |
+| `gate` | quality/review step that can **halt the flow** (see below) |
 | `reduce` | aggregate `from[]` phases into one output |
 
+### Gate phases (quality control)
+
+A `gate` phase runs an agent to review upstream output and can **block the rest
+of the workflow**. End the gate task's instructions by asking the agent to emit a
+verdict the runtime can read:
+
+- a final line `VERDICT: PASS` or `VERDICT: BLOCK` (also accepts OK/FAIL/STOP/REJECT/HALT), or
+- JSON like `{"continue": false, "reason": "missing auth checks"}` / `{"verdict": "block", "reason": "..."}`
+
+On **BLOCK**, downstream phases are skipped and the run ends as `blocked` with the
+reason surfaced. Ambiguous output **fails open** (treated as PASS) so a gate never
+halts the flow by accident. Example gate task:
+
+```
+Review the audit results below. If any endpoint is missing auth, end with
+"VERDICT: BLOCK" and a one-line reason; otherwise end with "VERDICT: PASS".
+
+{steps.audit.output}
+```
+
 ### Interpolation
 
 - `{args.X}` — invocation argument