pi-agent-flow 0.2.7 → 0.2.11

package/README.md

@@ -1,4 +1,4 @@
-<p align="center"><code>pi install /path/to/pi-agent-flow</code></p>
+<p align="center"><code>pi install npm:pi-agent-flow</code></p>
 <p align="center"><strong>Pi Agent Flow</strong> is a flow-state delegation extension for the <a href="https://pi.dev">Pi coding agent</a> that runs locally in your terminal.</p>
 <p align="center">
   <img src="https://github.com/user-attachments/assets/pi-agent-flow-demo.png" alt="Pi Agent Flow demo" width="80%" />
@@ -11,11 +11,10 @@
 
 ### Installing Pi Agent Flow
 
-Install via the Pi CLI with your local path:
+Install via the Pi CLI from npm:
 
 ```shell
-# Install from a local path
-pi install /path/to/pi-agent-flow
+pi install npm:pi-agent-flow
 ```
 
 Or add it to your Pi settings:
@@ -24,7 +23,7 @@ Or add it to your Pi settings:
 # ~/.pi/agent/settings.json
 {
   "packages": [
-    "./path/to/pi-agent-flow"
+    "npm:pi-agent-flow"
   ]
 }
 ```
@@ -32,9 +31,10 @@ Or add it to your Pi settings:
 Then start Pi and delegate tasks using flow states.
 
 <details>
-<summary>You can also clone this repository and use it directly.</summary>
+<summary>You can also install from a local path.</summary>
 
 ```shell
+# Install from a local clone
 git clone https://github.com/your-org/pi-agent-flow.git
 cd pi-agent-flow
 pi install .
@@ -56,6 +56,21 @@ pi install .
 
 ---
 
+## Why Flow Style?
+
+Flow-style delegation is designed for **context efficiency**. Instead of launching every sub-agent with the full, ever-growing conversation history, each flow receives only what it needs: your intent and (when appropriate) a session snapshot.
+
+This approach delivers four concrete benefits:
+
+1. **Avoid duplicate tool calls** — every sub-agent launch no longer re-runs the same `read`, `grep`, or `bash` probes that the parent already performed.
+2. **Prevent context bloat** — long transcripts with repeated file listings and command outputs are kept out of the main conversation thread.
+3. **Eliminate unnecessary noise** — the parent agent sees only structured results (`[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`) instead of pages of intermediate reasoning.
+4. **Preserve focus** — each flow stays locked on its intent because it isn't distracted by unrelated earlier messages.
+
+The result is faster, cheaper, and cleaner delegation: the main agent remains uncluttered while specialized flows do the heavy lifting in isolated contexts.
+
+---
+
 ## Flow Definitions
 
 Create `.md` files in `~/.pi/agent/agents/` or `.pi/agents/`:

package/agents.ts

@@ -110,7 +110,7 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 	const frontmatter = parsed.frontmatter ?? {};
 	const body = parsed.body ?? "";
 
-	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim() : "";
+	const name = typeof frontmatter.name === "string" ? frontmatter.name.trim().toLowerCase() : "";
 	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
 	if (!name || !description) return null;
 
@@ -197,7 +197,7 @@ function loadFlowsFromDir(dir: string, source: "user" | "project" | "bundled"):
 function mergeFlows(...groups: FlowConfig[][]): FlowConfig[] {
 	const flowMap = new Map<string, FlowConfig>();
 	for (const group of groups) {
-		for (const flow of group) flowMap.set(flow.name, flow);
+		for (const flow of group) flowMap.set(flow.name.toLowerCase(), flow);
 	}
 	return Array.from(flowMap.values());
 }
@@ -227,7 +227,7 @@ export function discoverFlows(cwd: string, scope: FlowScope): FlowDiscoveryResul
 		return { flows: mergeFlows(bundledFlows, userFlows), projectFlowsDir };
 	}
 	if (scope === "project") {
-		return { flows: projectFlows, projectFlowsDir };
+		return { flows: mergeFlows(projectFlows), projectFlowsDir };
 	}
 	return {
 		flows: mergeFlows(bundledFlows, userFlows, projectFlows),

package/flow.ts

@@ -195,11 +195,12 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		makeDetails,
 	} = opts;
 
-	const flow = flows.find((f) => f.name === flowName);
+	const normalizedFlowName = flowName.toLowerCase();
+	const flow = flows.find((f) => f.name === normalizedFlowName);
 	if (!flow) {
 		const available = flows.map((f) => `"${f.name}"`).join(", ") || "none";
 		return {
-			type: flowName,
+			type: normalizedFlowName,
 			agentSource: "unknown",
 			intent,
 			exitCode: 1,
@@ -210,7 +211,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 	}
 
 	const result: SingleResult = {
-		type: flowName,
+		type: normalizedFlowName,
 		agentSource: flow.source,
 		intent,
 		exitCode: -1,
@@ -255,7 +256,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		const exitCode = await new Promise<number>((resolve) => {
 			const nextDepth = Math.max(0, Math.floor(parentDepth)) + 1;
 			const propagatedMaxDepth = Math.max(0, Math.floor(maxDepth));
-			const propagatedStack = [...parentFlowStack, flowName];
+			const propagatedStack = [...parentFlowStack, normalizedFlowName];
 			const { command, prefixArgs } = resolveFlowSpawn();
 			const proc = spawn(command, [...prefixArgs, ...piArgs], {
 				cwd: taskCwd ?? cwd,

package/index.ts

@@ -36,7 +36,7 @@ const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
 
 const FlowItem = Type.Object({
 	type: Type.String({
-		description: "Flow type. Must match an available flow name exactly: explore, debug, code, architect, review, brainstorm.",
+		description: "Flow type. Matching is case-insensitive. Must correspond to an available flow name such as explore, debug, code, architect, review, or brainstorm.",
 	}),
 	intent: Type.String({
 		description: "Clear, specific mission for this flow.",
@@ -137,7 +137,7 @@ function parseFlowStack(raw: unknown): string[] | null {
 	if (!Array.isArray(parsed)) return null;
 	if (!parsed.every((value) => typeof value === "string")) return null;
 	return parsed
-		.map((value) => value.trim())
+		.map((value) => value.trim().toLowerCase())
 		.filter((value) => value.length > 0);
 }
 
@@ -303,7 +303,7 @@ function getRequestedProjectFlows(
 	requestedNames: Set<string>,
 ): FlowConfig[] {
 	return Array.from(requestedNames)
-		.map((name) => flows.find((f) => f.name === name))
+		.map((name) => flows.find((f) => f.name === name.toLowerCase()))
 		.filter((f): f is FlowConfig => f?.source === "project");
 }
 
@@ -423,7 +423,7 @@ flow [type] accomplished
 				);
 
 				// Collect all requested flow names
-				const requested = new Set(params.flow.map((f) => f.type));
+				const requested = new Set(params.flow.map((f) => f.type.toLowerCase()));
 
 				// Cycle check
 				if (preventCycles) {
@@ -483,58 +483,52 @@ flow [type] accomplished
 				}
 
 				let lastStreamingText = "";
+				let lastEmittedText: string | undefined;
 				const emitProgress = (streamingText?: string) => {
 					if (!onUpdate) return;
-					if (streamingText) lastStreamingText = streamingText;
+					if (streamingText !== undefined) lastStreamingText = streamingText;
+					const text = lastStreamingText || "";
+					if (text === lastEmittedText) return;
+					lastEmittedText = text;
 					onUpdate({
-						content: [{ type: "text", text: lastStreamingText || "" }],
+						content: [{ type: "text", text }],
 						details: makeDetails([...allResults]),
 					});
 				};
 
-				let heartbeat: NodeJS.Timeout | undefined;
-				if (onUpdate) {
-					emitProgress();
-					heartbeat = setInterval(() => {
-						if (allResults.some((r) => r.exitCode === -1)) emitProgress();
-					}, 1000);
-				}
-
-				let results: SingleResult[];
-				try {
-					results = await mapFlowConcurrent(params.flow, 4, async (item, index) => {
-						const targetFlow = flows.find((f) => f.name === item.type);
-						const effectiveMaxDepth =
-							targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
-
-						const shouldInheritContext = targetFlow?.inheritContext !== false;
-						const result = await runFlow({
-							cwd: ctx.cwd,
-							flows,
-							flowName: item.type,
-							intent: item.intent,
-							taskCwd: item.cwd,
-							forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
-							parentDepth: currentDepth,
-							parentFlowStack: ancestorFlowStack,
-							maxDepth: effectiveMaxDepth,
-							preventCycles,
-							signal,
-							onUpdate: (partial) => {
-								if (partial.details?.results[0]) {
-									allResults[index] = partial.details.results[0];
-									emitProgress(partial.content?.[0]?.text);
-								}
-							},
-							makeDetails,
-						});
-						allResults[index] = result;
-						emitProgress();
-						return result;
+				if (onUpdate) emitProgress();
+
+				const results = await mapFlowConcurrent(params.flow, 4, async (item, index) => {
+					const normalizedType = item.type.toLowerCase();
+					const targetFlow = flows.find((f) => f.name === normalizedType);
+					const effectiveMaxDepth =
+						targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
+
+					const shouldInheritContext = targetFlow?.inheritContext !== false;
+					const result = await runFlow({
+						cwd: ctx.cwd,
+						flows,
+						flowName: normalizedType,
+						intent: item.intent,
+						taskCwd: item.cwd,
+						forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
+						parentDepth: currentDepth,
+						parentFlowStack: ancestorFlowStack,
+						maxDepth: effectiveMaxDepth,
+						preventCycles,
+						signal,
+						onUpdate: (partial) => {
+							if (partial.details?.results[0]) {
+								allResults[index] = partial.details.results[0];
+								emitProgress(partial.content?.[0]?.text);
+							}
+						},
+						makeDetails,
 					});
-				} finally {
-					if (heartbeat) clearInterval(heartbeat);
-				}
+					allResults[index] = result;
+					emitProgress();
+					return result;
+				});
 
 				// Build tool result with FULL flow output — no truncation
 				const successCount = results.filter((r) => isFlowSuccess(r)).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "0.2.7",
+  "version": "0.2.11",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "index.ts",

package/render-utils.ts

@@ -48,14 +48,14 @@ export function formatFixedTokens(count: number): string {
 }
 
 /**
- * Format flow type name to fixed width (10 chars) in uppercase with dot padding.
- * Examples: "debug" → "DEBUG.....", "architect" → "ARCHITECT.", "brainstorm" → "BRAINSTORM"
+ * Format flow type name to fixed width (10 chars) in lowercase with dot padding.
+ * Examples: "debug" → "debug.....", "architect" → "architect.", "brainstorm" → "brainstorm"
  */
 export function formatFlowTypeName(type: string): string {
-	const upper = type.toUpperCase();
+	const lower = type.toLowerCase();
 	const targetWidth = 10;
-	if (upper.length >= targetWidth) return upper.slice(0, targetWidth);
-	return upper + ".".repeat(targetWidth - upper.length);
+	if (lower.length >= targetWidth) return lower.slice(0, targetWidth);
+	return lower + ".".repeat(targetWidth - lower.length);
 }
 
 export function formatCompactStats(usage: Partial<UsageStats>, model?: string): string {
@@ -153,10 +153,11 @@ function truncateAnsi(text: string, max: number): string {
 
 	const tailRaw = takeVisibleFromEnd(text, tail);
 
-	return headResult.raw + "\x1b[39m ... " + tailRaw;
+	return headResult.raw + " ... " + tailRaw;
 }
 
 export function truncateChars(text: string, max: number): string {
+	text = text.replace(/[\n\r\t]+/g, " ").replace(/ +/g, " ").trim();
 	if (visibleLength(text) <= max) return text;
 	return truncateAnsi(text, max);
 }

package/render.ts

@@ -193,12 +193,12 @@ function renderFlowExpanded(
 
 	// Intent
 	container.addChild(new Spacer(1));
-	container.addChild(new Text(theme.fg("muted", "─── Intent ───"), 0, 0));
+	container.addChild(new Text(theme.fg("muted", "─── intent ───"), 0, 0));
 	container.addChild(new Text(theme.fg("dim", r.intent), 0, 0));
 
 	// Flow report (structured output)
 	container.addChild(new Spacer(1));
-	container.addChild(new Text(theme.fg("muted", "─── Report ───"), 0, 0));
+	container.addChild(new Text(theme.fg("muted", "─── report ───"), 0, 0));
 	if (flowOutput) {
 		container.addChild(new Markdown(flowOutput.trim(), 0, 0, mdTheme));
 	} else {
@@ -210,7 +210,7 @@ function renderFlowExpanded(
 	const toolTraces = renderToolTraces(displayItems, theme);
 	if (toolTraces) {
 		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("muted", "─── Tool Calls ───"), 0, 0));
+		container.addChild(new Text(theme.fg("muted", "─── tool calls ───"), 0, 0));
 		container.addChild(new Text(toolTraces, 0, 0));
 	}
 
@@ -232,27 +232,27 @@ function renderFlowCollapsed(
 	let text = `${theme.fg("accent", theme.bold(typeName))} ${theme.fg("dim", "─")} ${theme.fg("dim", stats)}`;
 	if (error && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 
-	// DIR: line (intent/objective)
+	// dir: line (intent/objective)
 	if (r.intent) {
-		text += `\n${theme.fg("dim", "├─ DIR:")} ${theme.fg("dim", truncateChars(r.intent, 50))}`;
+		text += `\n${theme.fg("dim", "├─ dir:")} ${theme.fg("dim", truncateChars(r.intent, 50))}`;
 	}
 
-	// EXE: line (last tool call)
+	// exe: line (last tool call)
 	const lastTool = getLastToolCall(r.messages);
 	if (lastTool) {
 		const exeStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
-		text += `\n${theme.fg("dim", "├─ EXE:")} ${truncateChars(exeStr, 50)}`;
+		text += `\n${theme.fg("dim", "├─ exe:")} ${truncateChars(exeStr, 50)}`;
 	}
 
-	// LOG: line (last assistant text or streaming)
+	// log: line (last assistant text or streaming)
 	if (flowOutput) {
-		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("dim", truncateChars(flowOutput, 50))}`;
+		text += `\n${theme.fg("dim", "└─ log:")} ${theme.fg("dim", truncateChars(flowOutput, 50))}`;
 	} else if (streamingText) {
-		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("dim", tailText(streamingText, 50))}`;
+		text += `\n${theme.fg("dim", "└─ log:")} ${theme.fg("dim", tailText(streamingText, 50))}`;
 	} else if (error && r.errorMessage) {
-		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("error", truncateChars(r.errorMessage, 50))}`;
+		text += `\n${theme.fg("dim", "└─ log:")} ${theme.fg("error", truncateChars(r.errorMessage, 50))}`;
 	} else {
-		text += `\n${theme.fg("dim", "└─ LOG:")} ${theme.fg("dim", "[n/a]")}`;
+		text += `\n${theme.fg("dim", "└─ log:")} ${theme.fg("dim", "[n/a]")}`;
 	}
 
 	return new Text(text, 0, 0);
@@ -323,7 +323,7 @@ function renderMultiFlowExpanded(
 		const toolTraces = renderToolTraces(displayItems, theme);
 		if (toolTraces) {
 			container.addChild(new Spacer(1));
-			container.addChild(new Text(theme.fg("muted", "─── Tool Calls ───"), 0, 0));
+			container.addChild(new Text(theme.fg("muted", "─── tool calls ───"), 0, 0));
 			container.addChild(new Text(toolTraces, 0, 0));
 		}
 	}
@@ -367,26 +367,26 @@ function renderActivityPanel(
 		// Continuation indent for sub-lines
 		const indent = isLast ? "   " : "│  ";
 
-		// DIR: line (intent/objective)
+		// dir: line (intent/objective)
 		if (r.intent) {
-			container.addChild(new Text(`${theme.fg("dim", indent + "├─ DIR:")} ${theme.fg("dim", truncateChars(r.intent, 50))}`, 0, 0));
+			container.addChild(new Text(`${theme.fg("dim", indent + "├─ dir:")} ${theme.fg("dim", truncateChars(r.intent, 50))}`, 0, 0));
 		}
 
-		// EXE: line (last tool call)
+		// exe: line (last tool call)
 		const lastTool = getLastToolCall(r.messages);
 		if (lastTool) {
 			const exeStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
-			container.addChild(new Text(`${theme.fg("dim", indent + "├─ EXE:")} ${truncateChars(exeStr, 50)}`, 0, 0));
+			container.addChild(new Text(`${theme.fg("dim", indent + "├─ exe:")} ${truncateChars(exeStr, 50)}`, 0, 0));
 		}
 
-		// LOG: line (last assistant text)
+		// log: line (last assistant text)
 		const lastText = getLastAssistantText(r.messages);
 		if (lastText) {
-			container.addChild(new Text(`${theme.fg("dim", indent + "└─ LOG:")} ${theme.fg("dim", truncateChars(lastText, 50))}`, 0, 0));
+			container.addChild(new Text(`${theme.fg("dim", indent + "└─ log:")} ${theme.fg("dim", truncateChars(lastText, 50))}`, 0, 0));
 		} else if (error && r.errorMessage) {
-			container.addChild(new Text(`${theme.fg("dim", indent + "└─ LOG:")} ${theme.fg("error", truncateChars(r.errorMessage, 50))}`, 0, 0));
+			container.addChild(new Text(`${theme.fg("dim", indent + "└─ log:")} ${theme.fg("error", truncateChars(r.errorMessage, 50))}`, 0, 0));
 		} else {
-			container.addChild(new Text(`${theme.fg("dim", indent + "└─ LOG:")} ${theme.fg("dim", "[n/a]")}`, 0, 0));
+			container.addChild(new Text(`${theme.fg("dim", indent + "└─ log:")} ${theme.fg("dim", "[n/a]")}`, 0, 0));
 		}
 
 		// Add blank line separator between flows (with continuation pipe)