pi-agent-flow 0.1.0-alpha.7 → 0.1.0-alpha.8

package/README.md

@@ -1,28 +1,27 @@
-# pi-agent-flow
+<p align="center"><code>pi install /path/to/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%" />
+</p>
+<br/>
 
-Flow-state delegation extension for [Pi coding agent](https://pi.dev).
-
-Delegates tasks to specialized flow states running as isolated pi processes. Each flow receives a snapshot of the current session context and returns a structured report.
+---
 
-## Features
+## Quickstart
 
-- Isolated context — flows always receive your current session snapshot
-- Parallel execution — batch independent flows into one call
-- Structured reports — every flow returns [Summary], [Done], [Not Done], [Next Steps]
-- Depth guards — configurable max delegation depth (default: 3)
-- Cycle prevention — blocks recursive delegation chains
-- Flow discovery — reads definitions from ~/.pi/agent/agents/ and .pi/agents/
-- TUI rendering — rich collapsed/expanded display in interactive mode
+### Installing Pi Agent Flow
 
-## Installation
+Install via the Pi CLI with your local path:
 
-```bash
+```shell
+# Install from a local path
 pi install /path/to/pi-agent-flow
 ```
 
-Or add to ~/.pi/agent/settings.json:
+Or add it to your Pi settings:
 
-```json
+```shell
+# ~/.pi/agent/settings.json
 {
   "packages": [
     "./path/to/pi-agent-flow"
@@ -30,9 +29,36 @@ Or add to ~/.pi/agent/settings.json:
 }
 ```
 
+Then start Pi and delegate tasks using flow states.
+
+<details>
+<summary>You can also clone this repository and use it directly.</summary>
+
+```shell
+git clone https://github.com/your-org/pi-agent-flow.git
+cd pi-agent-flow
+pi install .
+```
+
+</details>
+
+---
+
+## Features
+
+- **Isolated context** — flows always receive your current session snapshot (or start clean when configured)
+- **Parallel execution** — batch independent flows into one call
+- **Structured reports** — every flow returns `[Summary]`, `[Done]`, `[Not Done]`, `[Next Steps]`
+- **Depth guards** — configurable max delegation depth (default: `3`)
+- **Cycle prevention** — blocks recursive delegation chains
+- **Flow discovery** — reads definitions from `~/.pi/agent/agents/` and `.pi/agents/`
+- **TUI rendering** — rich collapsed/expanded display in interactive mode
+
+---
+
 ## Flow Definitions
 
-Create .md files in ~/.pi/agent/agents/ or .pi/agents/:
+Create `.md` files in `~/.pi/agent/agents/` or `.pi/agents/`:
 
 ```markdown
 ---
@@ -59,21 +85,32 @@ flow [explore] accomplished
 - recommended follow-up
 ```
 
+---
+
 ## Bundled Flows
 
-- [explore] — discover files, trace code paths, map architecture
-- [debug] — investigate logs, errors, stack traces, root causes
-- [code] — implement features, fix bugs, write tests
-- [architect] — plan structure, break down requirements, design solutions
-- [review] — audit security, quality, correctness
+| Flow | Purpose |
+|------|---------|
+| `[explore]` | Discover files, trace code paths, map architecture |
+| `[debug]` | Investigate logs, errors, stack traces, root causes |
+| `[code]` | Implement features, fix bugs, write tests |
+| `[architect]` | Plan structure, break down requirements, design solutions |
+| `[review]` | Audit security, quality, correctness |
+| `[brainstorm]` | Generate ideas and explore possibilities with a clean slate |
+
+> **Note:** Some flows — like `[brainstorm]` — start with a **clean slate** and do not inherit the current session context. They receive only the intent, making them ideal for unbiased, creative thinking.
+
+---
 
 ## Usage
 
+### Single flow
+
 ```json
 { "flow": [{ "type": "explore", "intent": "Find all authentication-related code" }] }
 ```
 
-Batch multiple flows:
+### Batch multiple flows
 
 ```json
 {
@@ -84,21 +121,33 @@ Batch multiple flows:
 }
 ```
 
+---
+
 ## Configuration
 
-Flags (passed to parent pi process):
+### Flags (passed to parent pi process)
 
-- --flow-max-depth [n] — Maximum delegation depth (default: 3)
-- --flow-prevent-cycles — Block cyclic delegation (default: true)
-- --no-flow-prevent-cycles — Disable cycle prevention
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--flow-max-depth [n]` | Maximum delegation depth | `3` |
+| `--flow-prevent-cycles` | Block cyclic delegation | `true` |
+| `--no-flow-prevent-cycles` | Disable cycle prevention | — |
 
-Environment variables (propagated to child processes):
+### Environment variables (propagated to child processes)
+
+| Variable | Description |
+|----------|-------------|
+| `PI_FLOW_DEPTH` | Current depth |
+| `PI_FLOW_MAX_DEPTH` | Max allowed depth |
+| `PI_FLOW_STACK` | JSON array of ancestor flow names |
+| `PI_FLOW_PREVENT_CYCLES` | `"1"` or `"0"` |
+
+---
 
-- PI_FLOW_DEPTH — Current depth
-- PI_FLOW_MAX_DEPTH — Max allowed depth
-- PI_FLOW_STACK — JSON array of ancestor flow names
-- PI_FLOW_PREVENT_CYCLES — "1" or "0"
+## Docs
 
-## License
+- [**Pi Documentation**](https://pi.dev)
+- [**Contributing**](./docs/contributing.md) *(if available)*
+- [**License**](./LICENSE)
 
-MIT
+This repository is licensed under the [MIT License](LICENSE).

package/agents/brainstorm.md

@@ -0,0 +1,24 @@
+---
+name: brainstorm
+description: Generate ideas, explore possibilities, and think creatively without context bias
+tools: read, bash
+inheritContext: false
+maxDepth: 0
+---
+
+You are the brainstorm flow — your mission is to generate ideas and think creatively. You start with a clean slate and only have the intent to guide you. Stay focused on your intent at all times.
+
+When your mission is accomplished, end your response with:
+
+flow [brainstorm] accomplished
+
+[Summary] what was brainstormed
+
+[Done]
+- ideas generated
+
+[Not Done]
+- incomplete items and reasons
+
+[Next Steps]
+- recommended follow-up

package/agents.ts

@@ -24,6 +24,7 @@ export interface FlowConfig {
 	model?: string;
 	thinking?: string;
 	maxDepth?: number;
+	inheritContext?: boolean;
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -140,6 +141,26 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 		if (Number.isFinite(parsed) && parsed >= 0) maxDepth = parsed;
 	}
 
+	let inheritContext: boolean | undefined;
+	if (typeof frontmatter.inheritContext === "boolean") {
+		inheritContext = frontmatter.inheritContext;
+	} else if (typeof frontmatter.inheritContext === "string") {
+		const normalized = frontmatter.inheritContext.trim().toLowerCase();
+		if (normalized === "true" || normalized === "yes" || normalized === "1") {
+			inheritContext = true;
+		} else if (normalized === "false" || normalized === "no" || normalized === "0") {
+			inheritContext = false;
+		} else {
+			console.warn(
+				`[pi-agent-flow] Ignoring invalid inheritContext value "${frontmatter.inheritContext}" in "${filePath}". Expected true/false.`,
+			);
+		}
+	} else if (frontmatter.inheritContext !== undefined) {
+		console.warn(
+			`[pi-agent-flow] Ignoring invalid inheritContext field in "${filePath}". Expected boolean or string.`,
+		);
+	}
+
 	return {
 		name,
 		description,
@@ -147,6 +168,7 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 		model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 		thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
 		maxDepth,
+		inheritContext,
 		systemPrompt: body,
 		source,
 		filePath,

package/flow.ts

@@ -143,8 +143,8 @@ export interface RunFlowOptions {
 	intent: string;
 	/** Optional override working directory. */
 	taskCwd?: string;
-	/** Serialized parent session snapshot for fork mode. */
-	forkSessionSnapshotJsonl: string;
+	/** Serialized parent session snapshot for fork mode. Null when the flow starts with a clean slate. */
+	forkSessionSnapshotJsonl: string | null;
 	/** Current delegation depth of the caller process. */
 	parentDepth: number;
 	/** Delegation stack from the caller process (ancestor flow names). */
@@ -197,21 +197,6 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		};
 	}
 
-	if (!forkSessionSnapshotJsonl || !forkSessionSnapshotJsonl.trim()) {
-		return {
-			type: flowName,
-			agentSource: flow.source,
-			intent,
-			exitCode: 1,
-			messages: [],
-			stderr: "Cannot run in fork mode: missing parent session snapshot context.",
-			usage: emptyFlowUsage(),
-			model: flow.model,
-			stopReason: "error",
-			errorMessage: "Cannot run in fork mode: missing parent session snapshot context.",
-		};
-	}
-
 	const result: SingleResult = {
 		type: flowName,
 		agentSource: flow.source,
@@ -236,10 +221,14 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		});
 	};
 
-	// Write forked session snapshot to temp file
-	const forkTmp = writeFlowSessionToTempFile(flow.name, forkSessionSnapshotJsonl);
-	const forkSessionTmpDir = forkTmp.dir;
-	const forkSessionTmpPath = forkTmp.filePath;
+	// Write forked session snapshot to temp file only when provided
+	let forkSessionTmpDir: string | null = null;
+	let forkSessionTmpPath: string | null = null;
+	if (forkSessionSnapshotJsonl) {
+		const forkTmp = writeFlowSessionToTempFile(flow.name, forkSessionSnapshotJsonl);
+		forkSessionTmpDir = forkTmp.dir;
+		forkSessionTmpPath = forkTmp.filePath;
+	}
 
 	try {
 		const piArgs = buildFlowArgs(

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.",
+		description: "Flow type. Must match an available flow name exactly: explore, debug, code, architect, review, brainstorm.",
 	}),
 	intent: Type.String({
 		description: "Clear, specific mission for this flow.",
@@ -371,6 +371,7 @@ Before acting, reason about whether to dive into a flow:
 - [code] — when you are ready to build. Implement features, fix bugs, write tests.
 - [architect] — when you need a plan. Design structure, break down requirements before building.
 - [review] — when you need to verify. Audit security, quality, correctness.
+- [brainstorm] — when you need fresh ideas. Start from a clean slate with only the intent.
 
 Multiple independent flows? Batch them into one call:
 
@@ -416,17 +417,10 @@ flow [type] accomplished
 				const { flows } = discovery;
 				const makeDetails = makeFlowDetailsFactory(discovery.projectFlowsDir);
 
-				// Build fork session snapshot (shared across all flows)
+				// Build fork session snapshot (shared across all flows that inherit context)
 				const forkSessionSnapshotJsonl = buildForkSessionSnapshotJsonl(
 					ctx.sessionManager,
 				);
-				if (!forkSessionSnapshotJsonl) {
-					return {
-						content: [{ type: "text", text: "Cannot use fork mode: failed to snapshot current session context." }],
-						details: makeDetails([]),
-						isError: true,
-					};
-				}
 
 				// Collect all requested flow names
 				const requested = new Set(params.flow.map((f) => f.type));
@@ -513,13 +507,14 @@ flow [type] accomplished
 						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,
+							forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
 							parentDepth: currentDepth,
 							parentFlowStack: ancestorFlowStack,
 							maxDepth: effectiveMaxDepth,

package/package.json

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

package/render-utils.ts

@@ -21,7 +21,7 @@ export function formatFlowUsage(usage: Partial<UsageStats>, model?: string): str
 	if (usage.cacheWrite) parts.push(`CW:${formatTokens(usage.cacheWrite)}`);
 	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
 	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	if (model) parts.push(model);
+	if (model) parts.push(`model:${model}`);
 	return parts.join(" ");
 }
 
@@ -31,7 +31,7 @@ export function formatCompactStats(usage: Partial<UsageStats>, model?: string):
 	parts.push(`↓${formatTokens(usage.output || 0)}`);
 	if (usage.cacheRead) parts.push(`cr:${formatTokens(usage.cacheRead)}`);
 	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	if (model) parts.push(model);
+	if (model) parts.push(`model:${model}`);
 	return parts.join(" ");
 }
 

package/render.ts

@@ -109,19 +109,11 @@ function flowStatusIcon(r: SingleResult, theme: { fg: ThemeFg }): string {
 // renderFlowCall — shown while the flow is being invoked
 // ---------------------------------------------------------------------------
 
-function truncateText(text: string): string {
-	const words = text.split(/\s+/);
-	if (words.length <= 12) return text;
-	return `${words.slice(0, 3).join(" ")} ... ${words.slice(-8).join(" ")}`;
-}
-
 export function renderFlowCall(args: Record<string, any>, theme: FlowTheme): Text {
 	const flows = args.flow as Array<{ type: string; intent: string }> | undefined;
 
 	// Minimal — renderFlowResult owns the full display
 	return new Text("", 0, 0);
-
-	return new Text(theme.fg("muted", "(empty flow call)"), 0, 0);
 }
 
 // ---------------------------------------------------------------------------
@@ -352,7 +344,7 @@ function renderMultiFlowCollapsed(
 
 		// Intent line
 		if (r.intent) {
-			const intentPrefix = hasMsg ? "├─" : "└─";
+			const intentPrefix = "├─";
 			text += `\n${theme.fg("dim", indent + intentPrefix + " int:")} ${theme.fg("dim", truncateChars(r.intent, 40))}`;
 		}
 

package/types.ts

@@ -140,7 +140,9 @@ export function getFlowDisplayItems(messages: Message[]): DisplayItem[] {
 				if (part.type === "text") {
 					items.push({ type: "text", text: part.text });
 				} else if (part.type === "toolCall") {
-					items.push({ type: "toolCall", name: part.name, args: part.arguments });
+					const name = part.name ?? part.toolName ?? "unknown";
+					const args = (part.arguments ?? part.input ?? {}) as Record<string, unknown>;
+					items.push({ type: "toolCall", name, args });
 				}
 			}
 		}