pi-taskflow 0.0.5 → 0.0.6

package/extensions/schema.ts

@@ -12,10 +12,11 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce"] as const;
+export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow"] as const;
 export type PhaseType = (typeof PHASE_TYPES)[number];
 
 export const OUTPUT_FORMATS = ["text", "json"] as const;
+export const JOIN_MODES = ["all", "any"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -25,6 +26,29 @@ const ParallelTaskSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/** Declarative retry policy for a phase's subagent call(s). */
+const RetrySchema = Type.Object(
+	{
+		max: Type.Number({ description: "Max retry attempts after the first try (>= 0)" }),
+		backoffMs: Type.Optional(Type.Number({ description: "Base delay between attempts, in ms", default: 0 })),
+		factor: Type.Optional(
+			Type.Number({ description: "Backoff multiplier per attempt (1 = fixed, 2 = exponential)", default: 1 }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+/** Run-wide cost / token ceiling. Exceeding it halts the run (remaining phases skipped). */
+const BudgetSchema = Type.Object(
+	{
+		maxUSD: Type.Optional(Type.Number({ description: "Halt the run once accumulated cost exceeds this many USD" })),
+		maxTokens: Type.Optional(
+			Type.Number({ description: "Halt the run once accumulated input+output tokens exceed this" }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 const PhaseSchema = Type.Object(
 	{
 		id: Type.String({ description: "Unique phase identifier (referenced via {steps.<id>.output})" }),
@@ -46,7 +70,28 @@ const PhaseSchema = Type.Object(
 			Type.Array(Type.String(), { description: "[reduce] Phase ids whose outputs are aggregated" }),
 		),
 
+		// sub-workflow (flow)
+		use: Type.Optional(Type.String({ description: "[flow] Name of a saved taskflow to run as this phase" })),
+		with: Type.Optional(
+			Type.Record(Type.String(), Type.Unknown(), {
+				description: "[flow] Args passed to the sub-flow (string values support interpolation)",
+			}),
+		),
+
 		dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Phase ids this phase depends on" })),
+		join: Type.Optional(
+			StringEnum(JOIN_MODES, {
+				description: "Dependency join: 'all' (default) waits for every dep; 'any' runs as soon as one dep completes",
+				default: "all",
+			}),
+		),
+		when: Type.Optional(
+			Type.String({
+				description:
+					"Conditional guard: skip this phase unless the expression is truthy. Supports {refs} and == != < > <= >= && || ! ()",
+			}),
+		),
+		retry: Type.Optional(RetrySchema),
 		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" })),
@@ -77,6 +122,7 @@ export const TaskflowSchema = Type.Object(
 		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 })),
+		budget: Type.Optional(BudgetSchema),
 		agentScope: Type.Optional(
 			StringEnum(["user", "project", "both"] as const, { description: "Agent discovery scope", default: "user" }),
 		),
@@ -89,6 +135,9 @@ export type ParallelTask = Static<typeof ParallelTaskSchema>;
 export type Phase = Static<typeof PhaseSchema>;
 export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
+export type RetryPolicy = Static<typeof RetrySchema>;
+export type Budget = Static<typeof BudgetSchema>;
+export type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
 // Shorthand (non-DAG) specs — subagent-style ergonomics
@@ -227,6 +276,25 @@ export function validateTaskflow(def: unknown): ValidationResult {
 			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'`);
 		}
+		if (type === "flow") {
+			if (!p.use) errors.push(`Phase '${p.id}' (flow) requires 'use' (a saved flow name)`);
+		}
+		if (p.retry) {
+			if (typeof p.retry.max !== "number" || p.retry.max < 0) {
+				errors.push(`Phase '${p.id}': retry.max must be a number >= 0`);
+			} else if (p.retry.max > 20) {
+				errors.push(`Phase '${p.id}': retry.max must be <= 20`);
+			}
+			if (p.retry.backoffMs !== undefined && (p.retry.backoffMs < 0 || p.retry.backoffMs > 60000)) {
+				errors.push(`Phase '${p.id}': retry.backoffMs must be between 0 and 60000`);
+			}
+			if (p.retry.factor !== undefined && (p.retry.factor < 1 || p.retry.factor > 10)) {
+				errors.push(`Phase '${p.id}': retry.factor must be between 1 and 10`);
+			}
+		}
+		if (p.join && !JOIN_MODES.includes(p.join as JoinMode)) {
+			errors.push(`Phase '${p.id}': unknown join mode '${p.join}'`);
+		}
 	}
 
 	// dependsOn / from references must exist
@@ -247,7 +315,7 @@ export function validateTaskflow(def: unknown): ValidationResult {
 	}
 
 	// Exactly handle final-phase resolution lazily (0 finals => last phase is final)
-	const finals = (flow.phases as Phase[]).filter((p) => p.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 };
@@ -341,3 +409,18 @@ export function topoLayers(phases: Phase[]): Phase[][] {
 export function finalPhase(phases: Phase[]): Phase {
 	return phases.find((p) => p.final) ?? phases[phases.length - 1];
 }
+
+/**
+ * Apply a flow's declared arg defaults over the provided values, then pass
+ * through any extra provided keys. Shared by the tool entrypoint (index) and the
+ * sub-flow (`flow`) phase (runtime).
+ */
+export function resolveArgs(def: Taskflow, provided?: Record<string, unknown>): 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;
+	}
+	if (provided) for (const [k, v] of Object.entries(provided)) if (!(k in args)) args[k] = v;
+	return args;
+}

package/extensions/store.ts

@@ -11,7 +11,7 @@ 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";
+import type { UsageStats } from "./usage.ts";
 
 export interface SavedFlow {
 	name: string;
@@ -39,6 +39,12 @@ export interface PhaseState {
 	liveText?: string;
 	/** Gate verdict (gate phases only). */
 	gate?: { verdict: "pass" | "block"; reason?: string };
+	/** Total subagent attempts incl. retries (when > calls, a retry happened). */
+	attempts?: number;
+	/** True when a map/parallel fan-out was cut short by the budget cap. */
+	budgetTruncated?: boolean;
+	/** Human-in-the-loop outcome (approval phases only). */
+	approval?: { decision: "approve" | "reject" | "edit"; note?: string; auto?: boolean };
 }
 
 export interface RunState {
@@ -118,7 +124,7 @@ export function saveFlow(
 	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");
+	writeFileAtomic(filePath, `${JSON.stringify(def, null, 2)}\n`);
 	return { filePath };
 }
 
@@ -138,7 +144,7 @@ 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");
+	writeFileAtomic(path.join(dir, `${state.runId}.json`), JSON.stringify(state, null, 2));
 }
 
 export function loadRun(cwd: string, runId: string): RunState | null {
@@ -174,3 +180,23 @@ export function listRuns(cwd: string, limit = 20): RunState[] {
 export function hashInput(...parts: string[]): string {
 	return crypto.createHash("sha256").update(parts.join("\u0000")).digest("hex").slice(0, 16);
 }
+
+/**
+ * Write a file atomically: write to a unique temp file in the same directory,
+ * then rename over the target (rename is atomic on the same filesystem). Prevents
+ * a crash or concurrent write from leaving a half-written, corrupt JSON file.
+ */
+function writeFileAtomic(filePath: string, data: string): void {
+	const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+	try {
+		fs.writeFileSync(tmp, data, "utf-8");
+		fs.renameSync(tmp, filePath);
+	} catch (e) {
+		try {
+			if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+		} catch {
+			/* ignore cleanup failure */
+		}
+		throw e;
+	}
+}

package/extensions/usage.ts

@@ -0,0 +1,42 @@
+/**
+ * Usage accounting — token/cost stats shared across the runner (producer),
+ * runtime (aggregation), store (persistence), and render (display).
+ *
+ * Kept in its own leaf module so persistence and TUI don't have to depend on
+ * the process-spawning layer (`runner.ts`) just for these types/helpers.
+ */
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+/** Sum numeric usage fields across runs. `contextTokens` is intentionally excluded (it is a point-in-time gauge, not additive). */
+export function aggregateUsage(usages: UsageStats[]): UsageStats {
+	const total = emptyUsage();
+	for (const u of usages) {
+		total.input += u.input;
+		total.output += u.output;
+		total.cacheRead += u.cacheRead;
+		total.cacheWrite += u.cacheWrite;
+		total.cost += u.cost;
+		total.turns += u.turns;
+	}
+	return total;
+}
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "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",
@@ -36,7 +36,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "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",
+    "test": "node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/render.test.ts test/desugar.test.ts",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts"
   },
   "pi": {

package/skills/taskflow/SKILL.md

@@ -86,6 +86,71 @@ Call the `taskflow` tool. To run a brand-new flow you write inline, pass
 | `map` | fan out over `over` (an array) — one subagent per item, `{item}` bound |
 | `gate` | quality/review step that can **halt the flow** (see below) |
 | `reduce` | aggregate `from[]` phases into one output |
+| `approval` | **human-in-the-loop** pause: ask a person to approve / reject / edit before continuing |
+| `flow` | run a **saved sub-flow** (by `use`) as a single phase — composition/reuse |
+
+### Control-flow fields (any phase)
+
+| field | meaning |
+|-------|---------|
+| `when` | conditional guard — skip the phase unless the expression is truthy. Supports `{refs}`, `== != < > <= >=`, `&& \|\| !`, parentheses, quoted strings/numbers. Parse errors fail **open** (phase runs). |
+| `join` | dependency join: `"all"` (default — wait for every dep) or `"any"` (OR-join — run as soon as one dep completes). |
+| `retry` | `{ "max": N, "backoffMs": ms, "factor": k }` — retry a failing subagent up to N times; delay is `backoffMs * factor^attempt` (`factor:1`=fixed, `2`=exponential). |
+
+### Conditional routing (when + gate/branches)
+
+Pair `when` with an upstream phase that emits a decision to build real if/else
+routing. Use `join: "any"` on the merge phase so it runs whichever branch fired:
+
+```jsonc
+{ "id": "triage", "type": "agent", "agent": "analyst", "output": "json",
+  "task": "Classify the task. Output ONLY {\"route\":\"deep\"} or {\"route\":\"quick\"}." },
+{ "id": "deep",  "when": "{steps.triage.json.route} == deep",  "dependsOn": ["triage"], "agent": "analyst", "task": "..." },
+{ "id": "quick", "when": "{steps.triage.json.route} == quick", "dependsOn": ["triage"], "agent": "executor_fast", "task": "..." },
+{ "id": "report", "type": "reduce", "from": ["deep","quick"], "join": "any",
+  "dependsOn": ["deep","quick"], "agent": "writer", "task": "...", "final": true }
+```
+
+> `when` should reference **upstream** (`dependsOn`) phases — a ref to a phase
+> that hasn't completed resolves empty and the guard is treated as false.
+
+### Approval phases (human-in-the-loop)
+
+An `approval` phase pauses the run and asks the operator to **Approve / Reject /
+Edit**. Distinct from `gate` (which is an *agent* reviewing): this is a *human*
+deciding. The (interpolated) `task` is the prompt shown.
+
+- **Approve** → continue; the phase output is `(approve)`.
+- **Reject** → halt the flow (same mechanism as a blocking gate).
+- **Edit** → the typed note becomes this phase's `output`, so you can inject
+  guidance mid-run: reference it downstream with `{steps.<id>.output}`.
+- **Non-interactive** runs (headless/CI/print mode) **auto-approve** and record it.
+
+```jsonc
+{ "id": "checkpoint", "type": "approval", "dependsOn": ["plan"],
+  "task": "Review the plan above before the expensive fan-out. Approve, reject, or add guidance." }
+```
+
+### Sub-flows (composition)
+
+A `flow` phase runs another **saved** taskflow by name and bubbles up its final
+output. Pass args via `with` (string values interpolate). Recursion is detected
+and rejected.
+
+```jsonc
+{ "id": "research", "type": "flow", "use": "deep-research",
+  "with": { "topic": "{item}" }, "dependsOn": ["plan"] }
+```
+
+### Budget (cost / token caps)
+
+Add a run-wide ceiling at the top level. When accumulated cost/tokens exceed it,
+remaining phases are skipped (and an in-flight `map`/`parallel` stops spawning
+new items); the run ends as `blocked`.
+
+```jsonc
+{ "name": "...", "budget": { "maxUSD": 1.50, "maxTokens": 2000000 }, "phases": [ ... ] }
+```
 
 ### Gate phases (quality control)
 
@@ -132,8 +197,8 @@ variables, and storage paths — read `configuration.md` (next to this file).
 
 Quick reference:
 
-- **Flow:** `name`, `description`, `concurrency` (default 8), `agentScope` (user|project|both), `args`.
-- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `final`.
+- **Flow:** `name`, `description`, `concurrency` (default 8), `budget` (`maxUSD`/`maxTokens`), `agentScope` (user|project|both), `args`.
+- **Phase:** `model`, `thinking`, `tools` (whitelist), `cwd`, `output:"json"`, `concurrency` (map/parallel fan-out), `when`, `join` (all|any), `retry`, `use`/`with` (flow), `final`.
 - **Precedence (model/thinking/tools):** phase value → `settings.subagents.agentOverrides[agent]` → agent frontmatter → global/default.
 - **Concurrency:** same-layer phases use `flow.concurrency`; a `map`/`parallel` phase uses `phase.concurrency ?? flow.concurrency ?? 8`.