pi-taskflow 0.0.16 → 0.0.18

package/extensions/agents.ts

@@ -21,7 +21,7 @@ export interface TaskflowSettings {
 	maxRunAgeDays: number;
 }
 
-import { DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS } from "./store.ts";
+import { DEFAULT_KEPT_RUNS, DEFAULT_RUN_AGE_DAYS, writeFileAtomic } from "./store.ts";
 
 export const DEFAULT_TASKFLOW_SETTINGS: TaskflowSettings = {
 	builtInAgents: true,
@@ -63,12 +63,6 @@ export function shouldSyncBuiltinAgentsToProject(settings: TaskflowSettings = DE
 	return settings.builtInAgents && settings.syncBuiltinAgentsToProject;
 }
 
-export interface AgentOverride {
-	model?: string;
-	thinking?: string;
-	tools?: string[];
-}
-
 export interface AgentConfig {
 	name: string;
 	description: string;
@@ -120,16 +114,18 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "built-in")
 			if (!frontmatter.name || !frontmatter.description) continue;
 
 			// frontmatter is YAML-parsed: tools may be a comma-separated string ("a, b")
-			// OR a YAML sequence ([a, b]). Handle both forms.
+			// OR a YAML sequence ([a, b]). Handle both forms; reject other types to
+			// prevent garbage output from malformed YAML (e.g. boolean, number).
 			const rawTools = frontmatter.tools;
-			const tools: string[] | undefined = Array.isArray(rawTools)
-				? rawTools.map((t) => String(t).trim()).filter(Boolean)
-				: rawTools !== undefined && rawTools !== null
-					? String(rawTools)
-							.split(",")
-							.map((t) => t.trim())
-							.filter(Boolean)
-					: undefined;
+			let tools: string[] | undefined;
+			if (Array.isArray(rawTools)) {
+				tools = rawTools.map((t) => String(t).trim()).filter(Boolean);
+			} else if (typeof rawTools === "string") {
+				tools = rawTools.split(",").map((t) => t.trim()).filter(Boolean);
+			} else if (rawTools !== undefined && rawTools !== null) {
+				console.warn(`[taskflow] Agent '${String(frontmatter.name)}': 'tools' must be a string or array, got ${typeof rawTools}. Ignoring.`);
+				tools = undefined;
+			}
 
 			agents.push({
 				name: String(frontmatter.name),
@@ -173,7 +169,6 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 export function discoverAgents(
 	cwd: string,
 	scope: AgentScope,
-	overrides?: Record<string, AgentOverride>,
 	modelRoles?: Record<string, string>,
 	taskflowSettings: TaskflowSettings = DEFAULT_TASKFLOW_SETTINGS,
 ): AgentDiscoveryResult {
@@ -202,23 +197,6 @@ export function discoverAgents(
 		for (const a of projectAgents) agentMap.set(a.name, a);
 	}
 
-	if (overrides) {
-		for (const [name, override] of Object.entries(overrides)) {
-			const agent = agentMap.get(name);
-			if (agent) {
-				// Clone before mutating: agentMap owns the original AgentConfig
-				// (loaded from disk in loadAgentsFromDir). Mutating it in place
-				// would cause cross-contamination for any caller that retains a
-				// reference and invokes discoverAgents again with different overrides.
-				const mutated: AgentConfig = { ...agent };
-				if (override.model !== undefined) mutated.model = override.model;
-				if (override.thinking !== undefined) mutated.thinking = override.thinking;
-				if (override.tools !== undefined) mutated.tools = override.tools;
-				agentMap.set(name, mutated);
-			}
-		}
-	}
-
 	// Resolve {{role}} model references (e.g. {{fast}} → openrouter/deepseek/v4-flash)
 	// Clone before mutating, consistent with the overrides block above.
 	if (modelRoles) {
@@ -236,7 +214,6 @@ export function discoverAgents(
 }
 
 export interface SubagentSettings {
-	agentOverrides?: Record<string, AgentOverride>;
 	globalThinking?: string;
 	modelRoles?: Record<string, string>;
 	taskflow: TaskflowSettings;
@@ -261,7 +238,6 @@ export function readSubagentSettings(): SubagentSettings {
 		if (!fs.existsSync(settingsPath)) return { taskflow: { ...DEFAULT_TASKFLOW_SETTINGS } };
 		const raw = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
 		return {
-			agentOverrides: raw.subagents?.agentOverrides,
 			globalThinking: raw.subagents?.globalThinking ?? raw.defaultThinkingLevel,
 			modelRoles: raw.modelRoles,
 			taskflow: normalizeTaskflowSettings(raw.taskflow),
@@ -311,7 +287,7 @@ export function syncBuiltinAgentsToProject(cwd: string): void {
 
 		try {
 			const content = fs.readFileSync(src, "utf-8");
-			fs.writeFileSync(dst, content, "utf-8");
+			writeFileAtomic(dst, content);
 		} catch {
 			// Best-effort: a locked file must not block the sync.
 		}

package/extensions/cache.ts

@@ -47,9 +47,13 @@ function resolveOne(entry: string, cwd: string): string {
 					cwd,
 					encoding: "utf-8",
 					stdio: ["ignore", "pipe", "ignore"],
+					timeout: 30_000,
 				}).trim();
 				return `git:${ref}=${sha}`;
-			} catch {
+			} catch (e: unknown) {
+				if ((e as NodeJS.ErrnoException).code === "ETIMEDOUT") {
+					return `git:${ref}=<timeout>`;
+				}
 				return `git:${ref}=<no-git>`;
 			}
 		}

package/extensions/index.ts

@@ -1,5 +1,5 @@
 /**
- * pi-taskflow — lightweight workflow orchestration for the Pi coding agent.
+ * pi-taskflow — a declarative, verifiable graph of task nodes for the Pi coding agent.
  *
  * Registers:
  *   - tool `taskflow`        : run inline / saved flows, save, resume (LLM-callable)
@@ -42,6 +42,7 @@ import {
 	DEFAULT_RUN_AGE_DAYS,
 } from "./store.ts";
 import { CacheStore } from "./cache.ts";
+import { safeParse } from "./interpolate.ts";
 
 interface TaskflowDetails {
 	state?: RunState;
@@ -195,7 +196,7 @@ async function runFlow(
 		cleanupConfig.maxKeep = settings.taskflow.maxKeptRuns;
 		cleanupConfig.maxAgeDays = settings.taskflow.maxRunAgeDays;
 		const scope: AgentScope = def.agentScope ?? "user";
-		const { agents } = discoverAgents(ctx.cwd, scope, settings.agentOverrides, settings.modelRoles, settings.taskflow);
+		const { agents } = discoverAgents(ctx.cwd, scope, settings.modelRoles, settings.taskflow);
 
 		// Hint: if any agent still has unresolved {{role}} references, suggest configuring modelRoles
 		const unresolvedRoles = agents
@@ -324,7 +325,7 @@ export default function (pi: ExtensionAPI) {
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
-		promptSnippet: "Orchestrate subagents — single, parallel, chain, or DAG — with tracking, resume, and context isolation. Replaces the subagent tool.",
+		promptSnippet: "Declare a verifiable graph of subagent tasks (single, parallel, chain, or full DAG) — tracked, resumable, context-isolated. The runtime validates the graph before running. Replaces the subagent tool.",
 		promptGuidelines: [
 			"BEFORE FIRST USE: invoke skill_load('taskflow') to read the full skill documentation (DSL syntax, phase types, examples, best practices). This tool description is a condensed reference only — the skill is the authoritative guide.\n\nUse taskflow for ALL delegation — single tasks, parallel, chain, or full DAG orchestration. It fully replaces the subagent tool: every delegation is tracked with a runId, resumable across sessions, context-isolated (only final output returns), and saveable as /tf:<name>. Do NOT call the subagent tool directly; use taskflow shorthand (task/tasks/chain) for simple cases instead.",
 			"For complex multi-phase work (explore / 审计 / analyze the project, auditing endpoints, reviewing or migrating many files/modules, cross-checked research), use the full DSL with phases. For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
@@ -416,7 +417,7 @@ export default function (pi: ExtensionAPI) {
 			if (action === "agents") {
 				const scope = params.scope ?? "both";
 				const settings2 = readSubagentSettings();
-				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, undefined, settings2.modelRoles, settings2.taskflow);
+				const { agents } = discoverAgents(ctx.cwd, scope as AgentScope, settings2.modelRoles, settings2.taskflow);
 				const text = agents.length
 					? agents
 							.map(
@@ -441,13 +442,18 @@ export default function (pi: ExtensionAPI) {
 				const { verifyTaskflow } = await import("./verify.ts");
 				// Load definition: inline define takes priority, then saved name
 				let def: Taskflow | undefined;
-				if (params.define) {
-					const d = params.define as Record<string, unknown>;
+				let resolvedDefine: unknown = params.define;
+				if (typeof resolvedDefine === "string") {
+					const parsed = safeParse(resolvedDefine);
+					if (parsed && typeof parsed === "object") resolvedDefine = parsed;
+				}
+				if (resolvedDefine) {
+					const d = resolvedDefine as Record<string, unknown>;
 					if (typeof d === "object" && d !== null && Array.isArray(d.phases)) {
 						def = d as unknown as Taskflow;
-					} else if (isShorthand(params.define)) {
-						const r = validateTaskflow(params.define);
-						if (r.ok) def = params.define as unknown as Taskflow;
+					} else if (isShorthand(resolvedDefine)) {
+						const r = validateTaskflow(resolvedDefine);
+						if (r.ok) def = resolvedDefine as unknown as Taskflow;
 					}
 				} else if (params.name) {
 					const saved = getFlow(ctx.cwd, params.name);
@@ -505,9 +511,25 @@ export default function (pi: ExtensionAPI) {
 			// resolve the definition: inline `define` / shorthand (single|parallel|chain), else saved `name`.
 			let def: Taskflow | undefined;
 
+			// Auto-parse string `define` — LLMs sometimes pass a JSON string
+			// instead of a parsed object. safeParse handles markdown fences too.
+			let resolvedDefine: unknown = params.define;
+			if (typeof resolvedDefine === "string") {
+				const parsed = safeParse(resolvedDefine);
+				if (parsed && typeof parsed === "object") {
+					resolvedDefine = parsed;
+				} else {
+					return errorResult(
+						action,
+						`'define' was passed as a string, not a JSON object. Pass it as a proper object, e.g.:\n` +
+							`define: {"name":"my-flow","phases":[{"id":"step1","task":"do something"}]}`,
+					);
+				}
+			}
+
 			// A shorthand spec can come from `define` (no phases) or top-level params.
 			const shorthandSpec: unknown =
-				params.define ??
+				resolvedDefine ??
 				(params.chain
 					? { chain: params.chain, name: params.name }
 					: params.tasks
@@ -530,11 +552,25 @@ export default function (pi: ExtensionAPI) {
 				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}`);
+				if (!saved) {
+					const available = listFlows(ctx.cwd);
+					const hint = available.length
+						? ` Available flows: ${available.map((f) => f.name).join(", ")}.`
+						: " No saved flows found. Use action=save to create one, or pass 'define' for an inline flow.";
+					return errorResult(action, `Saved flow '${params.name}' not found.${hint}`);
+				}
 				def = saved.def;
 			}
 			if (!def)
-				return errorResult(action, "Provide 'define' (DSL), shorthand 'task'/'tasks'/'chain', or 'name' (saved).");
+				return errorResult(
+					action,
+					`No taskflow definition provided. Use one of:\n` +
+						`- define: {"name":"...","phases":[...]} (inline DSL object)\n` +
+						`- task: "..." (shorthand single agent)\n` +
+						`- tasks: [{"task":"..."},...] (shorthand parallel)\n` +
+						`- chain: [{"task":"..."},...] (shorthand sequential)\n` +
+						`- name: "saved-flow-name" (run a previously saved flow)`,
+				);
 
 			// save
 			if (action === "save") {
@@ -562,7 +598,17 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// run
-			const args = resolveArgs(def, params.args);
+			// Auto-parse string args — LLMs sometimes pass a JSON string.
+			let resolvedArgs: Record<string, unknown> | undefined;
+			if (typeof params.args === "string") {
+				const parsed = safeParse(params.args);
+				if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+					resolvedArgs = parsed as Record<string, unknown>;
+				}
+			} else if (params.args && typeof params.args === "object") {
+				resolvedArgs = params.args as Record<string, unknown>;
+			}
+			const args = resolveArgs(def, resolvedArgs);
 			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) {
@@ -579,7 +625,14 @@ export default function (pi: ExtensionAPI) {
 
 		renderCall(args, theme) {
 			const action = args.action ?? "run";
-			let label = args.name || (args.define as { name?: string } | undefined)?.name;
+			let label = args.name;
+		if (!label) {
+			let define = args.define;
+			if (typeof define === "string") {
+				try { define = JSON.parse(define); } catch { /* not JSON */ }
+			}
+			label = (define as { name?: string } | undefined)?.name;
+		}
 			let suffix = "";
 			const phases = (args.define as Taskflow | undefined)?.phases;
 			if (phases) suffix = ` (${phases.length} phases)`;
@@ -613,7 +666,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerCommand("tf", {
 		description: "Taskflow: list | run <name> | show <name> | runs | init",
 		getArgumentCompletions: (prefix) => {
-			const subs = ["list", "run", "show", "runs", "resume", "init"];
+			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify"];
 			const items = subs.map((s) => ({ value: s, label: s }));
 			const filtered = items.filter((i) => i.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -797,13 +850,13 @@ function parseArgsString(input: string, def: Taskflow): Record<string, unknown>
 	}
 	// key=value pairs
 	const out: Record<string, unknown> = {};
-	const pairs = trimmed.match(/(\w+)=("[^"]*"|\S+)/g);
+	const pairs = trimmed.match(/(\w+)=("(?:[^"\\]|\\.)*"|\S+)/g);
 	if (pairs) {
 		for (const p of pairs) {
 			const idx = p.indexOf("=");
 			const k = p.slice(0, idx);
 			let v: string = p.slice(idx + 1);
-			if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+			if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1).replace(/\\"/g, '"');
 			out[k] = v;
 		}
 		return out;

package/extensions/interpolate.ts

@@ -66,7 +66,13 @@ function resolvePath(path: string, ctx: InterpolationContext): unknown {
 		const step = stepId ? ctx.steps[stepId] : undefined;
 		if (!step) return undefined;
 		const field = parts[2];
-		if (field === "output") return step.output;
+		if (field === "output") {
+			// Guard: {steps.X.output.trailing} — trailing segments after output are
+			// likely author errors (output is a string, not an object). Return
+			// undefined so the placeholder is left intact with a missing warning.
+			if (parts.length > 3) return undefined;
+			return step.output;
+		}
 		if (field === "json") {
 			const json = step.json ?? safeParse(step.output);
 			return dig(json, parts.slice(3));
@@ -82,6 +88,12 @@ function resolvePath(path: string, ctx: InterpolationContext): unknown {
 	return undefined;
 }
 
+/**
+ * Traverse an object by a sequence of property keys. Returns `undefined`
+ * when any segment is missing or the current value is not an object —
+ * never throws, so extra path segments like {steps.X.json.a.b} where the
+ * data is shallower resolve gracefully to undefined (M-8).
+ */
 function dig(obj: unknown, parts: string[]): unknown {
 	let cur: unknown = obj;
 	for (const part of parts) {
@@ -219,10 +231,25 @@ function tokenize(input: string): Tok[] {
 		}
 		// quoted string
 		if (c === '"' || c === "'") {
-			const end = input.indexOf(c, i + 1);
-			if (end === -1) throw new Error("unterminated string");
-			toks.push({ t: "str", v: input.slice(i + 1, end) });
-			i = end + 1;
+			// Handle escaped quotes. Note: ALL \X sequences are interpreted as literal X
+			// (including \n → n, \t → t). This differs from JSON/JS escaping but is
+			// correct for condition strings which only need quote escaping.
+			let j = i + 1;
+			let val = "";
+			while (j < n) {
+				if (input[j] === "\\" && j + 1 < n) {
+					val += input[j + 1];
+					j += 2;
+				} else if (input[j] === c) {
+					break;
+				} else {
+					val += input[j];
+					j++;
+				}
+			}
+			if (j >= n) throw new Error("unterminated string");
+			toks.push({ t: "str", v: val });
+			i = j + 1;
 			continue;
 		}
 		// multi/single char operators

package/extensions/render.ts

@@ -104,7 +104,7 @@ export function summarizeRun(state: RunState): string {
 	const done = phases.filter((p) => p.status === "done").length;
 	const failed = phases.filter((p) => p.status === "failed").length;
 	const running = phases.filter((p) => p.status === "running").length;
-	const total = state.def.phases.length;
+	const total = Object.keys(state.phases).length;
 	const bits = [`${done}/${total} done`];
 	if (running) bits.push(`${running} running`);
 	if (failed) bits.push(`${failed} failed`);
@@ -254,7 +254,7 @@ function headerLine(state: RunState, theme: Theme): string {
 	const done = phases.filter((p) => p.status === "done").length;
 	const failed = phases.filter((p) => p.status === "failed").length;
 	const running = phases.filter((p) => p.status === "running").length;
-	const total = state.def.phases.length;
+	const total = Object.keys(state.phases).length;
 
 	const head =
 		state.status === "completed"

package/extensions/runner.ts

@@ -25,6 +25,8 @@ export interface RunResult {
 	errorMessage?: string;
 	/** Total subagent attempts incl. retries (set by the runtime's retry wrapper). */
 	attempts?: number;
+	/** Set when the subagent was killed by the idle watchdog (not a user abort). */
+	idleTimeout?: boolean;
 }
 
 export interface LiveUpdate {
@@ -74,6 +76,8 @@ const TRANSIENT_ERROR_RE =
 	/rate[_\s-]?limit|too\s+many\s+requests|overloaded|\b429\b|\b503\b|\b502\b|\b504\b|service\s+unavailable|temporarily\s+unavailable|timeout|timed?\s+out|econnreset|etimedout|socket\s+hang\s*up/i;
 export function isTransientError(r: RunResult): boolean {
 	if (r.stopReason === "aborted") return false;
+	// Idle timeout is a deterministic stall — retrying won't help.
+	if (r.stopReason === "error" && r.idleTimeout) return false;
 	const hay = `${r.errorMessage ?? ""} ${r.stderr ?? ""} ${r.output ?? ""}`;
 	return TRANSIENT_ERROR_RE.test(hay);
 }
@@ -153,6 +157,8 @@ export interface EventAccumulator {
 	stopReason?: string;
 	errorMessage?: string;
 	lastActivity: string;
+	/** Set when message cap was hit — output gets a truncation notice. */
+	truncated?: boolean;
 }
 
 export function newAccumulator(model?: string): EventAccumulator {
@@ -175,7 +181,15 @@ export function foldEventLine(acc: EventAccumulator, line: string): LiveUpdate |
 	}
 	if (event.type !== "message_end" || !event.message) return null;
 	const msg = event.message as Message;
-	acc.messages.push(msg);
+	// Cap prevents OOM from misconfigured loops. 500 messages is generous for
+	// normal subagent tasks (50 turns × 10 messages each). Messages beyond the
+	// cap are still parsed for usage/model/stopReason extraction.
+	const MAX_MESSAGES = 500;
+	if (acc.messages.length < MAX_MESSAGES) {
+		acc.messages.push(msg);
+	} else {
+		acc.truncated = true;
+	}
 	if (msg.role !== "assistant") return null;
 	acc.usage.turns++;
 	const u = (msg as any).usage;
@@ -323,6 +337,7 @@ export async function runAgentTask(
 
 		let wasAborted = false;
 		let idleTimedOut = false;
+		let killedBySignal: string | undefined;
 		const exitCode = await new Promise<number>((resolve) => {
 			const invocation = getPiInvocation(args);
 			const proc = spawn(invocation.command, invocation.args, {
@@ -371,12 +386,19 @@ export async function runAgentTask(
 				buffer = lines.pop() || "";
 				for (const line of lines) processLine(line);
 			});
+			// Cap prevents OOM from verbose tool output (e.g., npm install). 64 KB is
+			// generous for error diagnosis while preventing memory exhaustion.
+			const STDERR_MAX_LEN = 64 * 1024;
 			proc.stderr.on("data", (data) => {
 				result.stderr += data.toString();
+				if (result.stderr.length >= STDERR_MAX_LEN) {
+					result.stderr = result.stderr.slice(0, STDERR_MAX_LEN) + "\n[...stderr truncated at 64KB]";
+				}
 			});
-			proc.on("close", (code) => {
+			proc.on("close", (code, signal) => {
 				clearTimers();
 				if (buffer.trim()) processLine(buffer);
+				if (code === null && signal) killedBySignal = signal;
 				resolve(code ?? 0);
 			});
 			proc.on("error", (err) => {
@@ -411,11 +433,25 @@ export async function runAgentTask(
 		result.stopReason = acc.stopReason;
 		result.errorMessage = acc.errorMessage;
 		result.output = getFinalOutput(acc.messages);
+		// M-6: surface truncation when the message cap was hit so downstream
+		// phases and the user know output was cut short.
+		if (acc.truncated) {
+			result.output += "\n\n[...output truncated after 500 messages]";
+		}
+		// Signal kill detection: process exited 0 but was killed by a signal
+		// (e.g. OOM killer, cgroup limit). Treat as failure so the runtime's
+		// retry/fail handling doesn't silently accept a truncated result.
+		if (exitCode === 0 && killedBySignal && !idleTimedOut && !wasAborted) {
+			result.exitCode = 1;
+			result.stopReason = "error";
+			result.errorMessage = `Subagent killed by signal ${killedBySignal}`;
+		}
 		if (idleTimedOut) {
 			// Distinct, actionable signal: the child was killed for being idle, not
 			// a user abort. stopReason "error" keeps it in the failed bucket so the
 			// runtime's retry/fail handling treats it as a real failure.
 			result.stopReason = "error";
+			result.idleTimeout = true;
 			result.errorMessage = `Subagent stalled: no output for ${Math.round((opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS) / 1000)}s (idle timeout) — killed`;
 		} else if (wasAborted) {
 			result.stopReason = "aborted";

package/extensions/runs-view.ts

@@ -29,7 +29,7 @@ function statusBadge(status: RunState["status"], theme: Theme): string {
 }
 
 function timeAgo(ts: number): string {
-	const s = Math.floor((Date.now() - ts) / 1000);
+	const s = Math.max(0, 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`;
@@ -37,7 +37,7 @@ function timeAgo(ts: number): string {
 }
 
 function isResumable(r: RunState): boolean {
-	return r.status === "paused" || r.status === "failed" || r.status === "blocked";
+	return r.status === "paused" || r.status === "failed";
 }
 
 export class RunHistoryComponent {