pi-taskflow 0.0.1

package/extensions/schema.ts

@@ -0,0 +1,261 @@
+/**
+ * Taskflow DSL — schema, types, and validation.
+ *
+ * A taskflow is a declarative, multi-phase workflow. Each phase delegates work
+ * to a subagent (an isolated `pi` process). Phases form a DAG via `dependsOn`.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Phase types
+// ---------------------------------------------------------------------------
+
+export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce"] as const;
+export type PhaseType = (typeof PHASE_TYPES)[number];
+
+export const OUTPUT_FORMATS = ["text", "json"] as const;
+
+const ParallelTaskSchema = Type.Object(
+	{
+		task: Type.String({ description: "Task for this parallel branch (supports interpolation)" }),
+		agent: Type.Optional(Type.String({ description: "Override the phase agent for this branch" })),
+	},
+	{ additionalProperties: false },
+);
+
+const PhaseSchema = Type.Object(
+	{
+		id: Type.String({ description: "Unique phase identifier (referenced via {steps.<id>.output})" }),
+		type: Type.Optional(StringEnum(PHASE_TYPES, { description: "Phase kind", default: "agent" })),
+		agent: Type.Optional(Type.String({ description: "Agent name to run this phase" })),
+		task: Type.Optional(Type.String({ description: "Task prompt (supports interpolation placeholders)" })),
+
+		// map fan-out
+		over: Type.Optional(
+			Type.String({ description: "[map] Interpolation ref resolving to an array to fan out over" }),
+		),
+		as: Type.Optional(Type.String({ description: "[map] Loop variable name (default: item)", default: "item" })),
+
+		// parallel static branches
+		branches: Type.Optional(Type.Array(ParallelTaskSchema, { description: "[parallel] Static task branches" })),
+
+		// reduce
+		from: Type.Optional(
+			Type.Array(Type.String(), { description: "[reduce] Phase ids whose outputs are aggregated" }),
+		),
+
+		dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Phase ids this phase depends on" })),
+		output: Type.Optional(StringEnum(OUTPUT_FORMATS, { description: "Parse output as text or json", default: "text" })),
+		model: Type.Optional(Type.String({ description: "Model override for this phase" })),
+		thinking: Type.Optional(Type.String({ description: "Thinking level override for this phase" })),
+		tools: Type.Optional(Type.Array(Type.String(), { description: "Restrict tools for this phase's agent" })),
+		cwd: Type.Optional(Type.String({ description: "Working directory for this phase's subagent" })),
+		final: Type.Optional(Type.Boolean({ description: "Mark this phase's output as the workflow result" })),
+		optional: Type.Optional(
+			Type.Boolean({ description: "If true, a failure does not abort the run", default: false }),
+		),
+		concurrency: Type.Optional(Type.Number({ description: "Override max concurrency for map/parallel" })),
+	},
+	{ additionalProperties: false },
+);
+
+const ArgSpecSchema = Type.Object(
+	{
+		default: Type.Optional(Type.Unknown()),
+		description: Type.Optional(Type.String()),
+		required: Type.Optional(Type.Boolean()),
+	},
+	{ additionalProperties: false },
+);
+
+export const TaskflowSchema = Type.Object(
+	{
+		name: Type.String({ description: "Workflow name (becomes /tf:<name> command when saved)" }),
+		description: Type.Optional(Type.String()),
+		version: Type.Optional(Type.Number({ default: 1 })),
+		args: Type.Optional(Type.Record(Type.String(), ArgSpecSchema, { description: "Declared invocation arguments" })),
+		concurrency: Type.Optional(Type.Number({ description: "Default max concurrent subagents", default: 8 })),
+		agentScope: Type.Optional(
+			StringEnum(["user", "project", "both"] as const, { description: "Agent discovery scope", default: "user" }),
+		),
+		phases: Type.Array(PhaseSchema, { minItems: 1, description: "Ordered phase definitions (DAG via dependsOn)" }),
+	},
+	{ additionalProperties: false },
+);
+
+export type ParallelTask = Static<typeof ParallelTaskSchema>;
+export type Phase = Static<typeof PhaseSchema>;
+export type Taskflow = Static<typeof TaskflowSchema>;
+export type ArgSpec = Static<typeof ArgSpecSchema>;
+
+// ---------------------------------------------------------------------------
+// Validation (beyond schema: DAG integrity, phase-type requirements)
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+	ok: boolean;
+	errors: string[];
+}
+
+export function validateTaskflow(def: unknown): ValidationResult {
+	const errors: string[] = [];
+
+	if (typeof def !== "object" || def === null) {
+		return { ok: false, errors: ["Taskflow must be an object"] };
+	}
+	const flow = def as Partial<Taskflow>;
+
+	if (!flow.name || typeof flow.name !== "string") errors.push("Missing or invalid 'name'");
+	if (!Array.isArray(flow.phases) || flow.phases.length === 0) {
+		errors.push("Taskflow must have at least one phase");
+		return { ok: false, errors };
+	}
+
+	const ids = new Set<string>();
+	for (const p of flow.phases) {
+		if (!p || typeof p !== "object") {
+			errors.push("Each phase must be an object");
+			continue;
+		}
+		if (!p.id) {
+			errors.push("Each phase requires an 'id'");
+			continue;
+		}
+		if (ids.has(p.id)) errors.push(`Duplicate phase id: ${p.id}`);
+		ids.add(p.id);
+
+		const type = (p.type ?? "agent") as PhaseType;
+		if (!PHASE_TYPES.includes(type)) errors.push(`Phase '${p.id}': unknown type '${type}'`);
+
+		// Per-type requirements
+		if (type === "agent" || type === "gate") {
+			if (!p.task) errors.push(`Phase '${p.id}' (${type}) requires 'task'`);
+		}
+		if (type === "map") {
+			if (!p.over) errors.push(`Phase '${p.id}' (map) requires 'over'`);
+			if (!p.task) errors.push(`Phase '${p.id}' (map) requires 'task'`);
+		}
+		if (type === "parallel") {
+			if (!p.branches || p.branches.length === 0)
+				errors.push(`Phase '${p.id}' (parallel) requires non-empty 'branches'`);
+		}
+		if (type === "reduce") {
+			if (!p.from || p.from.length === 0) errors.push(`Phase '${p.id}' (reduce) requires 'from'`);
+			if (!p.task) errors.push(`Phase '${p.id}' (reduce) requires 'task'`);
+		}
+	}
+
+	// dependsOn / from references must exist
+	for (const p of flow.phases) {
+		if (!p?.id) continue;
+		for (const dep of p.dependsOn ?? []) {
+			if (!ids.has(dep)) errors.push(`Phase '${p.id}': dependsOn unknown phase '${dep}'`);
+		}
+		for (const f of p.from ?? []) {
+			if (!ids.has(f)) errors.push(`Phase '${p.id}': from unknown phase '${f}'`);
+		}
+	}
+
+	// Cycle detection (Kahn)
+	if (errors.length === 0) {
+		const cycle = detectCycle(flow.phases as Phase[]);
+		if (cycle) errors.push(`Dependency cycle detected: ${cycle.join(" -> ")}`);
+	}
+
+	// Exactly handle final-phase resolution lazily (0 finals => last phase is final)
+	const finals = (flow.phases as Phase[]).filter((p) => p.final);
+	if (finals.length > 1) errors.push(`Only one phase may be marked 'final' (found ${finals.length})`);
+
+	return { ok: errors.length === 0, errors };
+}
+
+/** Returns a cycle path if the DAG has one, else null. */
+function detectCycle(phases: Phase[]): string[] | null {
+	const deps = new Map<string, string[]>();
+	for (const p of phases) deps.set(p.id, dependenciesOf(p));
+
+	const WHITE = 0;
+	const GRAY = 1;
+	const BLACK = 2;
+	const color = new Map<string, number>();
+	for (const p of phases) color.set(p.id, WHITE);
+	const stack: string[] = [];
+
+	const visit = (id: string): string[] | null => {
+		color.set(id, GRAY);
+		stack.push(id);
+		for (const d of deps.get(id) ?? []) {
+			if (!deps.has(d)) continue;
+			const c = color.get(d);
+			if (c === GRAY) {
+				const start = stack.indexOf(d);
+				return [...stack.slice(start), d];
+			}
+			if (c === WHITE) {
+				const found = visit(d);
+				if (found) return found;
+			}
+		}
+		color.set(id, BLACK);
+		stack.pop();
+		return null;
+	};
+
+	for (const p of phases) {
+		if (color.get(p.id) === WHITE) {
+			const found = visit(p.id);
+			if (found) return found;
+		}
+	}
+	return null;
+}
+
+/** Effective dependency ids of a phase (dependsOn ∪ from). */
+export function dependenciesOf(phase: Phase): string[] {
+	const set = new Set<string>([...(phase.dependsOn ?? []), ...(phase.from ?? [])]);
+	return Array.from(set);
+}
+
+/** Topologically ordered layers; phases in the same layer can run concurrently. */
+export function topoLayers(phases: Phase[]): Phase[][] {
+	const byId = new Map(phases.map((p) => [p.id, p]));
+	const indeg = new Map<string, number>();
+	const dependents = new Map<string, string[]>();
+
+	for (const p of phases) {
+		indeg.set(p.id, 0);
+		dependents.set(p.id, []);
+	}
+	for (const p of phases) {
+		for (const d of dependenciesOf(p)) {
+			if (!byId.has(d)) continue;
+			indeg.set(p.id, (indeg.get(p.id) ?? 0) + 1);
+			dependents.get(d)!.push(p.id);
+		}
+	}
+
+	const layers: Phase[][] = [];
+	let frontier = phases.filter((p) => (indeg.get(p.id) ?? 0) === 0);
+	const seen = new Set<string>();
+
+	while (frontier.length > 0) {
+		layers.push(frontier);
+		const next: Phase[] = [];
+		for (const p of frontier) {
+			seen.add(p.id);
+			for (const dep of dependents.get(p.id) ?? []) {
+				indeg.set(dep, (indeg.get(dep) ?? 0) - 1);
+				if ((indeg.get(dep) ?? 0) === 0 && !seen.has(dep)) next.push(byId.get(dep)!);
+			}
+		}
+		frontier = next;
+	}
+	return layers;
+}
+
+/** Resolve which phase is the result-bearing phase. */
+export function finalPhase(phases: Phase[]): Phase {
+	return phases.find((p) => p.final) ?? phases[phases.length - 1];
+}

package/extensions/store.ts

@@ -0,0 +1,170 @@
+/**
+ * Persistence for taskflow definitions and run state.
+ *
+ *   Definitions:  .pi/taskflows/<name>.json          (project)
+ *                 ~/.pi/agent/taskflows/<name>.json   (user)
+ *   Run state:    .pi/taskflows/runs/<runId>.json     (resume support)
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { Taskflow } from "./schema.ts";
+import type { UsageStats } from "./runner.ts";
+
+export interface SavedFlow {
+	name: string;
+	scope: "user" | "project";
+	filePath: string;
+	def: Taskflow;
+}
+
+export type PhaseStatus = "pending" | "running" | "done" | "failed" | "skipped";
+
+export interface PhaseState {
+	id: string;
+	status: PhaseStatus;
+	output?: string;
+	json?: unknown;
+	usage?: UsageStats;
+	model?: string;
+	error?: string;
+	inputHash?: string;
+	startedAt?: number;
+	endedAt?: number;
+}
+
+export interface RunState {
+	runId: string;
+	flowName: string;
+	def: Taskflow;
+	args: Record<string, unknown>;
+	status: "running" | "completed" | "failed" | "paused";
+	phases: Record<string, PhaseState>;
+	createdAt: number;
+	updatedAt: number;
+	cwd: string;
+}
+
+function userFlowsDir(): string {
+	return path.join(getAgentDir(), "taskflows");
+}
+
+function findProjectFlowsDir(cwd: string, create = false): string | null {
+	// Prefer an existing .pi dir up the tree; else use cwd/.pi when creating.
+	let dir = cwd;
+	while (true) {
+		const candidate = path.join(dir, ".pi");
+		if (fs.existsSync(candidate)) return path.join(candidate, "taskflows");
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return create ? path.join(cwd, ".pi", "taskflows") : null;
+}
+
+function readFlowFile(filePath: string, scope: "user" | "project"): SavedFlow | null {
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const def = JSON.parse(raw) as Taskflow;
+		if (!def?.name) return null;
+		return { name: def.name, scope, filePath, def };
+	} catch {
+		return null;
+	}
+}
+
+/** List all saved flows (project overrides user on name collision). */
+export function listFlows(cwd: string): SavedFlow[] {
+	const map = new Map<string, SavedFlow>();
+	const dirs: Array<{ dir: string; scope: "user" | "project" }> = [{ dir: userFlowsDir(), scope: "user" }];
+	const projDir = findProjectFlowsDir(cwd);
+	if (projDir) dirs.push({ dir: projDir, scope: "project" });
+
+	for (const { dir, scope } of dirs) {
+		if (!fs.existsSync(dir)) continue;
+		let entries: string[];
+		try {
+			entries = fs.readdirSync(dir);
+		} catch {
+			continue;
+		}
+		for (const name of entries) {
+			if (!name.endsWith(".json")) continue;
+			const flow = readFlowFile(path.join(dir, name), scope);
+			if (flow) map.set(flow.name, flow); // project after user → overrides
+		}
+	}
+	return Array.from(map.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getFlow(cwd: string, name: string): SavedFlow | null {
+	return listFlows(cwd).find((f) => f.name === name) ?? null;
+}
+
+export function saveFlow(
+	cwd: string,
+	def: Taskflow,
+	scope: "user" | "project" = "project",
+): { filePath: string } {
+	const dir = scope === "user" ? userFlowsDir() : findProjectFlowsDir(cwd, true)!;
+	fs.mkdirSync(dir, { recursive: true });
+	const safe = def.name.replace(/[^\w.-]+/g, "_");
+	const filePath = path.join(dir, `${safe}.json`);
+	fs.writeFileSync(filePath, `${JSON.stringify(def, null, 2)}\n`, "utf-8");
+	return { filePath };
+}
+
+// --- Run state ---
+
+function runsDir(cwd: string): string {
+	const projDir = findProjectFlowsDir(cwd, true)!;
+	return path.join(projDir, "runs");
+}
+
+export function newRunId(flowName: string): string {
+	const safe = flowName.replace(/[^\w.-]+/g, "_").slice(0, 24);
+	return `${safe}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+export function saveRun(state: RunState): void {
+	const dir = runsDir(state.cwd);
+	fs.mkdirSync(dir, { recursive: true });
+	state.updatedAt = Date.now();
+	fs.writeFileSync(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2), "utf-8");
+}
+
+export function loadRun(cwd: string, runId: string): RunState | null {
+	try {
+		const raw = fs.readFileSync(path.join(runsDir(cwd), `${runId}.json`), "utf-8");
+		return JSON.parse(raw) as RunState;
+	} catch {
+		return null;
+	}
+}
+
+export function listRuns(cwd: string, limit = 20): RunState[] {
+	const dir = runsDir(cwd);
+	if (!fs.existsSync(dir)) return [];
+	let files: string[];
+	try {
+		files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+	} catch {
+		return [];
+	}
+	const runs: RunState[] = [];
+	for (const f of files) {
+		try {
+			runs.push(JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8")));
+		} catch {
+			/* ignore */
+		}
+	}
+	return runs.sort((a, b) => b.updatedAt - a.updatedAt).slice(0, limit);
+}
+
+/** Stable hash of a phase's resolved task + inputs, for resume caching. */
+export function hashInput(...parts: string[]): string {
+	return crypto.createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pi-taskflow",
+  "version": "0.0.1",
+  "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",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "workflow",
+    "orchestration",
+    "subagents",
+    "agents",
+    "taskflow",
+    "ai",
+    "automation"
+  ],
+  "license": "MIT",
+  "author": "heggria <bshengtao@gmail.com>",
+  "homepage": "https://github.com/heggria/pi-taskflow#readme",
+  "bugs": {
+    "url": "https://github.com/heggria/pi-taskflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heggria/pi-taskflow.git"
+  },
+  "type": "module",
+  "files": [
+    "extensions",
+    "skills",
+    "examples",
+    "README.md",
+    "DESIGN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/interpolate.test.ts test/schema.test.ts test/runtime.test.ts",
+    "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
+    "typebox": "^1.1.38",
+    "typescript": "^5.6.0"
+  }
+}

package/skills/taskflow/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: taskflow
+description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use when a task needs several coordinated subagent steps, fan-out over many items (files, endpoints, modules), cross-checked/adversarial review, or a repeatable orchestration you want to save and rerun. Not for a single delegated task — use the subagent tool for that.
+---
+
+# Taskflow
+
+Build and run **declarative, multi-phase workflows** of subagents. The runtime
+holds intermediate results and the phase DAG, so your main context only receives
+the final answer — not every step's transcript.
+
+## When to use
+
+- A task needs **several coordinated steps** (discover → work → review → report).
+- You need to **fan out over many items** (audit every endpoint, summarize every file).
+- You want **cross-checked / adversarial review** before reporting.
+- You want a **repeatable** orchestration saved as a `/tf:<name>` command.
+
+For a single delegated task, use the `subagent` tool instead.
+
+## How to author a taskflow
+
+Call the `taskflow` tool. To run a brand-new flow you write inline, pass
+`action: "run"` with a `define` object. To run a saved flow, pass `name`.
+
+### DSL shape
+
+```jsonc
+{
+  "name": "audit-endpoints",
+  "description": "Audit API endpoints for missing auth",
+  "args": { "dir": { "default": "src/routes" } },
+  "concurrency": 8,
+  "agentScope": "user",            // user | project | both
+  "phases": [
+    { "id": "discover", "type": "agent", "agent": "scout",
+      "task": "List endpoints under {args.dir}. Output ONLY a JSON array [{\"route\":\"\",\"file\":\"\"}].",
+      "output": "json" },
+    { "id": "audit", "type": "map", "over": "{steps.discover.json}", "as": "item",
+      "agent": "analyst", "task": "Audit {item.route} ({item.file}) for missing auth.",
+      "dependsOn": ["discover"] },
+    { "id": "review", "type": "gate", "agent": "reviewer",
+      "task": "Remove false positives from:\n{steps.audit.output}", "dependsOn": ["audit"] },
+    { "id": "report", "type": "reduce", "from": ["review"], "agent": "writer",
+      "task": "Write a final report:\n{steps.review.output}", "dependsOn": ["review"],
+      "final": true }
+  ]
+}
+```
+
+### Phase types
+
+| type | meaning |
+|------|---------|
+| `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) |
+| `reduce` | aggregate `from[]` phases into one output |
+
+### Interpolation
+
+- `{args.X}` — invocation argument
+- `{steps.ID.output}` — a prior phase's text output
+- `{steps.ID.json}` / `{steps.ID.json.field}` — prior output parsed as JSON
+- `{item}` / `{item.field}` — current item inside a `map` phase
+- `{previous.output}` — the immediately-upstream phase output
+
+## Rules that make flows work
+
+1. For a `map` phase, make the upstream phase **emit a JSON array** and set
+   `output: "json"` on it. Tell that agent to output **only** JSON.
+2. Give each phase a clear, single responsibility.
+3. Reference upstream results explicitly with `{steps.ID...}` and set `dependsOn`.
+4. Mark the result-bearing phase with `"final": true` (else the last phase wins).
+
+## Actions
+
+- `action: "run"` — run inline `define` or a saved `name` (with optional `args`).
+- `action: "save"` — persist `define` (scope `project` or `user`); becomes `/tf:<name>`.
+- `action: "resume"` — continue a paused/failed run by `runId` (completed phases are cached).
+- `action: "list"` — list saved flows.
+
+## User commands
+
+- `/tf list` · `/tf run <name> [args]` · `/tf show <name>` · `/tf runs` · `/tf resume <runId>`
+- `/tf:<name> [args]` — shortcut for each saved flow