pi-taskflow 0.0.3 → 0.0.4

package/extensions/index.ts

@@ -19,7 +19,7 @@ import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.
 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 { finalPhase, type Taskflow, validateTaskflow, desugar, isShorthand } from "./schema.ts";
 import {
 	getFlow,
 	listFlows,
@@ -41,6 +41,14 @@ interface TaskflowDetails {
 /** pi reads `isError` at runtime to mark tool failures; it is not in the public type. */
 type ToolResult = AgentToolResult<TaskflowDetails> & { isError?: boolean };
 
+const ShorthandStep = Type.Object(
+	{
+		agent: Type.Optional(Type.String({ description: "Agent for this step (defaults to the first available agent)" })),
+		task: Type.String({ description: "Task prompt for this step (supports {previous.output} in chains)" }),
+	},
+	{ additionalProperties: false },
+);
+
 const TaskflowParams = Type.Object({
 	action: StringEnum(["run", "save", "resume", "list"] as const, {
 		description: "What to do: run a flow, save a definition, resume a paused run, or list saved flows",
@@ -53,6 +61,24 @@ const TaskflowParams = Type.Object({
 				"Inline taskflow definition (JSON object matching the taskflow DSL). Use to run or save a new flow.",
 		}),
 	),
+	// --- Shorthand (non-DAG) modes, like the subagent tool. No DSL required. ---
+	agent: Type.Optional(
+		Type.String({ description: "Shorthand single mode: agent to run with `task` (like subagent single mode)" }),
+	),
+	task: Type.Optional(
+		Type.String({ description: "Shorthand single mode: the task prompt (like subagent single mode)" }),
+	),
+	tasks: Type.Optional(
+		Type.Array(ShorthandStep, {
+			description: "Shorthand parallel mode: run these tasks concurrently and merge results (like subagent parallel)",
+		}),
+	),
+	chain: Type.Optional(
+		Type.Array(ShorthandStep, {
+			description:
+				"Shorthand chain mode: run sequentially; reference the prior step with {previous.output} (like subagent chain)",
+		}),
+	),
 	args: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Invocation arguments for the flow" })),
 	runId: Type.Optional(Type.String({ description: "Run id to resume (for action=resume)" })),
 	scope: Type.Optional(
@@ -175,6 +201,7 @@ export default function (pi: ExtensionAPI) {
 			"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.",
 			"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?}]}.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
@@ -183,7 +210,7 @@ export default function (pi: ExtensionAPI) {
 		promptSnippet: "Orchestrate many subagents over a whole codebase/many items (declarative DAG with map fan-out)",
 		promptGuidelines: [
 			"Prefer taskflow whenever a request spans a whole project/codebase or many items — e.g. 'explore / 探索 / 审计 / analyze the project', auditing endpoints, reviewing or migrating many files/modules, or cross-checked research. It fans out to many subagents across phases and aggregates the result, keeping intermediate work out of your context.",
-			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. Use the plain subagent tool only for a single delegated task.",
+			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. For simple single/parallel/chain delegations use the shorthand `task`/`tasks`/`chain` (no DSL) when you want the run tracked, resumable, or saveable; otherwise the plain subagent tool is fine.",
 			"For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 		],
 
@@ -209,18 +236,39 @@ export default function (pi: ExtensionAPI) {
 				return finalResult(action, result);
 			}
 
-			// resolve the definition (inline define wins, else saved name)
+			// resolve the definition: inline `define` / shorthand (single|parallel|chain), else saved `name`.
 			let def: Taskflow | undefined;
-			if (params.define) {
-				const v = validateTaskflow(params.define);
+
+			// A shorthand spec can come from `define` (no phases) or top-level params.
+			const shorthandSpec: unknown =
+				params.define ??
+				(params.chain
+					? { chain: params.chain, name: params.name }
+					: params.tasks
+						? { tasks: params.tasks, name: params.name }
+						: params.task
+							? { task: params.task, agent: params.agent, name: params.name }
+							: undefined);
+
+			if (shorthandSpec !== undefined) {
+				let candidate: unknown = shorthandSpec;
+				if (isShorthand(candidate)) {
+					try {
+						candidate = desugar(candidate);
+					} catch (e) {
+						return errorResult(action, `Invalid shorthand: ${e instanceof Error ? e.message : String(e)}`);
+					}
+				}
+				const v = validateTaskflow(candidate);
 				if (!v.ok) return errorResult(action, `Invalid taskflow:\n- ${v.errors.join("\n- ")}`);
-				def = params.define as Taskflow;
+				def = candidate as Taskflow;
 			} else if (params.name) {
 				const saved = getFlow(ctx.cwd, params.name);
 				if (!saved) return errorResult(action, `Saved flow not found: ${params.name}`);
 				def = saved.def;
 			}
-			if (!def) return errorResult(action, "Provide 'define' (inline) or 'name' (saved).");
+			if (!def)
+				return errorResult(action, "Provide 'define' (DSL), shorthand 'task'/'tasks'/'chain', or 'name' (saved).");
 
 			// save
 			if (action === "save") {
@@ -256,10 +304,23 @@ export default function (pi: ExtensionAPI) {
 
 		renderCall(args, theme) {
 			const action = args.action ?? "run";
-			const name = args.name || (args.define as any)?.name || "(inline)";
-			let text = theme.fg("toolTitle", theme.bold("taskflow ")) + theme.fg("accent", `${action} `) + theme.fg("muted", name);
+			let label = args.name || (args.define as { name?: string } | undefined)?.name;
+			let suffix = "";
 			const phases = (args.define as Taskflow | undefined)?.phases;
-			if (phases) text += theme.fg("dim", ` (${phases.length} phases)`);
+			if (phases) suffix = ` (${phases.length} phases)`;
+			else if (args.chain) {
+				label ||= "chain";
+				suffix = ` (${(args.chain as unknown[]).length} steps)`;
+			} else if (args.tasks) {
+				label ||= "parallel";
+				suffix = ` (${(args.tasks as unknown[]).length} tasks)`;
+			} else if (args.task) {
+				label ||= "task";
+			}
+			label ||= "(inline)";
+			let text =
+				theme.fg("toolTitle", theme.bold("taskflow ")) + theme.fg("accent", `${action} `) + theme.fg("muted", label);
+			if (suffix) text += theme.fg("dim", suffix);
 			return new Text(text, 0, 0);
 		},
 

package/extensions/render.ts

@@ -9,7 +9,7 @@ import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { formatTokens, type UsageStats } from "./runner.ts";
 import type { PhaseState, RunState } from "./store.ts";
-import type { Phase } from "./schema.ts";
+import { dependenciesOf, type Phase, topoLayers } from "./schema.ts";
 
 // Single-width glyphs (Geometric Shapes / check marks) — keep columns aligned.
 const ICON: Record<PhaseState["status"], { ch: string; color: string }> = {
@@ -223,35 +223,81 @@ function headerLine(state: RunState, theme: Theme): string {
 	return line;
 }
 
-/** The full dense progress block (header + aligned phase rows). */
+/**
+ * Left-gutter rail glyph for a phase at `i` within a parallel group of `size`.
+ * A group is a topological layer with >1 phase (they run concurrently); the
+ * bracket (┌ ├ └) visually fans them out from the preceding layer. Single-phase
+ * layers get a blank gutter so the column stays quiet.
+ */
+function railGlyph(i: number, size: number): string {
+	if (size <= 1) return " ";
+	if (i === 0) return "┌";
+	if (i === size - 1) return "└";
+	return "├";
+}
+
+/** The full dense progress block (header + DAG-ordered phase rows). */
 export function renderProgress(state: RunState, theme: Theme): string {
 	const phases = state.def.phases;
 	const idW = Math.max(...phases.map((p) => p.id.length), 2);
 	const typeW = Math.max(...phases.map((p) => (p.type ?? "agent").length), 4);
+	const defIndex = new Map(phases.map((p, i) => [p.id, i]));
+
+	// Render in topological order: each layer is a set of phases that can run
+	// concurrently; later layers depend on earlier ones. This makes the DAG's
+	// flow legible top-to-bottom without drawing a full graph.
+	const layers = topoLayers(phases);
+	const rendered = new Set<string>();
 
 	let text = headerLine(state, theme);
-	for (const phase of phases) {
+
+	const renderRow = (phase: Phase, rail: string, prevLayerIds: Set<string>) => {
 		const ps = state.phases[phase.id];
 		const status = ps?.status ?? "pending";
 		const id = phase.id.padEnd(idW);
 		const type = (phase.type ?? "agent").padEnd(typeW);
 		const detail = phaseDetail(phase, ps, theme);
+
+		// Annotate only "long" edges — dependencies that skip past the adjacent
+		// layer. Edges into the immediately-preceding layer are implied by position
+		// (and the rail), so showing them would just add noise.
+		const longEdges = dependenciesOf(phase).filter((d) => !prevLayerIds.has(d));
+		const dep = longEdges.length
+			? theme.fg("dim", `  ↳ ${longEdges.join(", ")}`)
+			: "";
+
+		const gutter = rail === " " ? " " : theme.fg("borderMuted", rail);
 		text +=
-			`\n  ${icon(status, theme)} ` +
+			`\n  ${gutter} ${icon(status, theme)} ` +
 			theme.fg(status === "pending" ? "dim" : "text", id) +
 			"  " +
 			theme.fg("dim", type) +
 			"  " +
-			detail;
+			detail +
+			dep;
 
 		// Live activity sub-line (only while running, only if we have a message).
 		if (status === "running" && ps?.liveText) {
-			const indent = " ".repeat(2 + 2 + idW + 2);
+			const indent = " ".repeat(2 + 2 + 2 + idW + 2);
 			const msg = ps.liveText.replace(/\s+/g, " ").trim();
 			const snip = msg.length > 88 ? `${msg.slice(0, 88)}…` : msg;
 			text += `\n${indent}${theme.fg("dim", "› ")}${theme.fg("muted", snip)}`;
 		}
+		rendered.add(phase.id);
+	};
+
+	let prevLayerIds = new Set<string>();
+	for (const layer of layers) {
+		const ordered = [...layer].sort((a, b) => (defIndex.get(a.id) ?? 0) - (defIndex.get(b.id) ?? 0));
+		ordered.forEach((phase, i) => renderRow(phase, railGlyph(i, ordered.length), prevLayerIds));
+		prevLayerIds = new Set(ordered.map((p) => p.id));
 	}
+
+	// Safety net: render any phase a malformed DAG left out of the layering.
+	for (const phase of phases) {
+		if (!rendered.has(phase.id)) renderRow(phase, " ", prevLayerIds);
+	}
+
 	return text;
 }
 

package/extensions/runner.ts

@@ -289,7 +289,7 @@ export async function runAgentTask(
 		}
 		if (tmpPromptDir) {
 			try {
-				fs.rmdirSync(tmpPromptDir);
+				fs.rmSync(tmpPromptDir, { recursive: true, force: true });
 			} catch {
 				/* ignore */
 			}

package/extensions/runtime.ts

@@ -259,12 +259,20 @@ async function executePhase(
 
 /** Resolve a `{steps.x.json}`-style ref directly to its parsed value (bypassing stringify). */
 function directRef(over: string, state: RunState): unknown {
-	const m = over.match(/^\{steps\.([a-zA-Z0-9_]+)\.(output|json)\}$/);
+	const m = over.match(/^\{steps\.([a-zA-Z0-9_]+)\.(output|json)(?:\.([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*))?\}$/);
 	if (!m) return undefined;
 	const step = state.phases[m[1]];
 	if (!step || step.status !== "done") return undefined;
-	if (m[2] === "json") return step.json ?? safeParse(step.output ?? "");
-	return safeParse(step.output ?? "");
+	let value: unknown;
+	if (m[2] === "json") value = step.json ?? safeParse(step.output ?? "");
+	else value = safeParse(step.output ?? "");
+	if (m[3]) {
+		for (const key of m[3].split(".")) {
+			if (value == null || typeof value !== "object") return undefined;
+			value = (value as Record<string, unknown>)[key];
+		}
+	}
+	return value;
 }
 
 function lastCompletedOutput(state: RunState, phase: Phase): string | undefined {

package/extensions/schema.ts

@@ -90,6 +90,88 @@ export type Phase = Static<typeof PhaseSchema>;
 export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
 
+// ---------------------------------------------------------------------------
+// Shorthand (non-DAG) specs — subagent-style ergonomics
+// ---------------------------------------------------------------------------
+//
+// For simple delegations you should not have to author a phases DAG. A
+// shorthand spec mirrors the subagent tool's modes and is desugared into a
+// full Taskflow before validation/execution:
+//
+//   { task, agent? }                  → one `agent` phase           (single)
+//   { tasks: [{task, agent?}, ...] }  → one `parallel` phase        (parallel)
+//   { chain: [{task, agent?}, ...] }  → sequential `agent` phases   (chain)
+//
+// Chain steps reference the prior step's output with {previous.output}, exactly
+// like the subagent tool's {previous} placeholder.
+
+export interface ShorthandStep {
+	agent?: string;
+	task: string;
+}
+
+/** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
+export function isShorthand(def: unknown): boolean {
+	if (typeof def !== "object" || def === null) return false;
+	const d = def as Record<string, unknown>;
+	if (Array.isArray(d.phases)) return false;
+	return Array.isArray(d.chain) || Array.isArray(d.tasks) || typeof d.task === "string";
+}
+
+function readStep(s: unknown): ShorthandStep {
+	if (typeof s === "string") return { task: s };
+	if (s && typeof s === "object") {
+		const o = s as Record<string, unknown>;
+		return { agent: typeof o.agent === "string" ? o.agent : undefined, task: String(o.task ?? "") };
+	}
+	return { task: "" };
+}
+
+/**
+ * Desugar a shorthand spec into a full Taskflow DAG. Throws if no recognizable
+ * shorthand field is present. Carries through optional name/description/
+ * concurrency/agentScope/args.
+ */
+export function desugar(def: unknown): Taskflow {
+	if (typeof def !== "object" || def === null) throw new Error("Shorthand spec must be an object");
+	const d = def as Record<string, unknown>;
+
+	const meta: Partial<Taskflow> = {};
+	if (typeof d.description === "string") meta.description = d.description;
+	if (typeof d.concurrency === "number") meta.concurrency = d.concurrency;
+	if (d.agentScope === "user" || d.agentScope === "project" || d.agentScope === "both") meta.agentScope = d.agentScope;
+	if (d.args && typeof d.args === "object") meta.args = d.args as Taskflow["args"];
+	const nameOf = (fallback: string) => (typeof d.name === "string" && d.name.trim() ? d.name.trim() : fallback);
+
+	// chain → sequential agent phases
+	if (Array.isArray(d.chain) && d.chain.length > 0) {
+		const steps = d.chain.map(readStep);
+		const phases: Phase[] = steps.map((s, i) => {
+			const phase: Phase = { id: `step${i + 1}`, type: "agent", task: s.task };
+			if (s.agent) phase.agent = s.agent;
+			if (i > 0) phase.dependsOn = [`step${i}`];
+			if (i === steps.length - 1) phase.final = true;
+			return phase;
+		});
+		return { name: nameOf("chain"), ...meta, phases };
+	}
+
+	// tasks → one parallel phase (fan-out + merge), no extra aggregation agent
+	if (Array.isArray(d.tasks) && d.tasks.length > 0) {
+		const branches: ParallelTask[] = d.tasks.map(readStep).map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
+		return { name: nameOf("parallel"), ...meta, phases: [{ id: "parallel", type: "parallel", branches, final: true }] };
+	}
+
+	// single task → one agent phase
+	if (typeof d.task === "string") {
+		const phase: Phase = { id: "main", type: "agent", task: d.task, final: true };
+		if (typeof d.agent === "string") phase.agent = d.agent;
+		return { name: nameOf("task"), ...meta, phases: [phase] };
+	}
+
+	throw new Error("Shorthand spec needs one of: 'task' (single), 'tasks' (parallel), or 'chain' (sequential)");
+}
+
 // ---------------------------------------------------------------------------
 // Validation (beyond schema: DAG integrity, phase-type requirements)
 // ---------------------------------------------------------------------------

package/extensions/store.ts

@@ -114,7 +114,7 @@ export function saveFlow(
 	def: Taskflow,
 	scope: "user" | "project" = "project",
 ): { filePath: string } {
-	const dir = scope === "user" ? userFlowsDir() : findProjectFlowsDir(cwd, true)!;
+	const dir = scope === "user" ? userFlowsDir() : (findProjectFlowsDir(cwd, true) ?? path.join(cwd, ".pi", "taskflows"));
 	fs.mkdirSync(dir, { recursive: true });
 	const safe = def.name.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(dir, `${safe}.json`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "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": "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:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts"
   },
   "pi": {

package/skills/taskflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskflow
-description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use whenever a request spans a whole project or many items — deeply exploring / 探索 / auditing / 审计 / analyzing a codebase, reviewing or migrating many files or modules in parallel, cross-checked/adversarial review, codebase-wide research, or any repeatable orchestration you want to save and rerun. Prefer this over ad-hoc parallel subagents when the work has multiple phases or dynamic fan-out over a discovered list. Not for a single delegated task — use the subagent tool for that.
+description: Orchestrate multi-phase subagent workflows with pi-taskflow. Use whenever a request spans a whole project or many items — deeply exploring / 探索 / auditing / 审计 / analyzing a codebase, reviewing or migrating many files or modules in parallel, cross-checked/adversarial review, codebase-wide research, or any repeatable orchestration you want to save and rerun. Prefer this over ad-hoc parallel subagents when the work has multiple phases or dynamic fan-out over a discovered list. Also supports subagent-style shorthand (single / parallel / chain) for simple non-DAG delegations you want tracked, resumable, or saveable.
 ---
 
 # Taskflow
@@ -16,7 +16,36 @@ the final answer — not every step's transcript.
 - 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.
+For a single quick delegation you can use the **shorthand modes** below (no DSL),
+or the plain `subagent` tool. Use the shorthand when you want the run tracked,
+resumable, or saveable as a `/tf` command.
+
+## Shorthand (non-DAG) — like the subagent tool
+
+Skip the DSL entirely for simple delegations. The runtime desugars these into a
+proper flow, so you still get progress, persistence, resume, and `save`.
+
+```jsonc
+// single  — one agent, one task
+{ "task": "Summarize the architecture of src/", "agent": "explorer" }
+
+// parallel — run several tasks at once, outputs merged
+{ "tasks": [
+  { "task": "Audit auth in src/api", "agent": "analyst" },
+  { "task": "Audit input validation in src/api", "agent": "analyst" }
+] }
+
+// chain — run sequentially; reference the prior step with {previous.output}
+{ "chain": [
+  { "task": "List the public API of src/lib", "agent": "scout" },
+  { "task": "Write docs for:\n{previous.output}", "agent": "writer" }
+] }
+```
+
+- `agent` is optional (defaults to the first available agent).
+- Add `name` to label the run (and to `save` it as a `/tf:<name>` command).
+- Precedence if several are given: `chain` > `tasks` > `task`.
+- You can pass these as top-level tool params **or** inside `define`.
 
 ## How to author a taskflow