pi-agent-flow 1.4.4 → 1.6.0

package/README.md

@@ -81,8 +81,8 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 | Flow | Purpose | Tools | Tier |
 |------|---------|-------|------|
 | `[scout]` | Discover files, trace code paths, map architecture | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
-| `[debug]` | Investigate logs, errors, stack traces, root causes | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
-| `[build]` | Implement features, fix bugs, write tests, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
+| `[debug]` | Investigate logs, errors, stack traces, root causes, and update relevant troubleshooting docs | `batch`, `bash`, `find`, `grep`, `ls` | `lite` |
+| `[build]` | Implement features, fix bugs, write tests, update relevant docs, ship | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[craft]` | Plan structure, break down requirements, design solutions | `batch`, `bash`, `find`, `grep`, `ls` | `full` |
 | `[audit]` | Audit security, quality, correctness; fix issues autonomously | `batch`, `bash`, `find`, `grep`, `ls` | `flash` |
 | `[ideas]` | Generate ideas and explore possibilities with inherited context | `batch`, `bash` | `full` |
@@ -91,6 +91,8 @@ The result is faster, cheaper, and cleaner delegation: the main agent remains un
 
 > **Clean slate:** Set `inheritContext: false` in a custom flow's front-matter so it receives only the intent, ideal for unbiased creative work.
 
+> **Docs hygiene:** Bundled `build` and `debug` flows are instructed to update relevant documentation after their work when the findings or implementation change developer or operational knowledge. If no docs apply, they should state why in the final report.
+
 ### Session modes
 
 Each flow call may set `sessionMode` to choose the child-agent time budget:

package/agents/build.md

@@ -17,8 +17,9 @@ During this build flow — your mission is to implement and verify changes. Be a
 4. Execute — implement changes following core principles.
 5. Refactor — clean up only if the change is working.
 6. Verify — run tests and relevant checks before considering the work done.
-7. Ship — commit, push, monitor CI/CD, and fix failures until green when shipping is in scope.
-8. Finalize — confirm implementation, tests, and CI/CD status.
+7. Document — update relevant docs after the implementation and verification are settled; if no docs apply, state why.
+8. Ship — commit, push, monitor CI/CD, and fix failures until green when shipping is in scope.
+9. Finalize — confirm implementation, docs, tests, and CI/CD status.
 
 ## Rules
 
@@ -28,6 +29,7 @@ During this build flow — your mission is to implement and verify changes. Be a
 - If already on a feature/fix branch, continue on it.
 - Commit with a clear conventional message such as `feat:`, `fix:`, or `refactor:` when committing is in scope.
 - Push only after local verification passes when shipping is in scope.
+- Update relevant documentation after finishing the work; if no docs changed, explain why in the final report.
 - If CI/CD fails, diagnose, fix, commit, push, and repeat until green.
 - If an unexpected error or trace is needed, recommend [debug] rather than guessing.
 

package/agents/debug.md

@@ -16,6 +16,8 @@ During this debug flow — your mission is to investigate root cause. Be forensi
 3. Check changes — inspect recent diffs, configuration, dependencies, and environment differences.
 4. Identify root cause — state exactly what is broken and why.
 5. Recommend fix — propose the smallest safe correction only after evidence confirms the cause.
+6. Document — update relevant docs, runbooks, or troubleshooting notes after finishing the investigation; if no docs apply, state why.
+7. Finalize — confirm root cause, evidence, documentation updates, and recommended next steps.
 
 ## Rules
 
@@ -23,7 +25,8 @@ During this debug flow — your mission is to investigate root cause. Be forensi
 - Read logs and symptoms before reading broad code areas.
 - Use `batch` with `o: "read"`, `s: <offset>`, and `l: <limit>` for targeted file reading instead of bash `sed`/`head`/`tail`.
 - Do not suggest fixes until root cause is confirmed.
-- Do not implement changes from this flow unless explicitly requested.
+- Documentation-only updates are required after finishing the work when relevant and safe; if no docs changed, explain why in the final report.
+- Do not implement product-code changes from this flow unless explicitly requested.
 
 ## Note
 Treat this as a clean-slate system rewrite, unless explicitly mentioned in the requirements. Perform a comprehensive migration with zero requirements for backwards compatibility. You must ensure that all residual code, variable names, test suites, and documentation are fully refactored and perfectly aligned with the new architecture.

package/package.json

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

package/src/agents.ts

@@ -56,6 +56,18 @@ export function getFlowTier(flowName: string): FlowTier {
 	}
 }
 
+/** Return the bundled flow names associated with a given tier. */
+export function getTierFlowNames(tier: FlowTier): string[] {
+	switch (tier) {
+		case "lite":
+			return ["scout", "debug"];
+		case "flash":
+			return ["build", "audit"];
+		case "full":
+			return ["ideas", "craft"];
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -9,8 +9,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseAgentSessionMode, type AgentSessionMode } from "./session-mode.js";
+import { type FlowTier } from "./agents.js";
 
-export type FlowTier = "lite" | "flash" | "full";
 
 export interface FlowModelTierConfig {
 	primary?: string;
@@ -369,3 +369,23 @@ export function resolveFlowModelCandidates(opts: {
 
 	return { primary: candidates[0], candidates };
 }
+
+export function formatFlowModelStrategy(modeName: string, strategy: FlowModelStrategy): string {
+	const tiers: FlowTier[] = ["lite", "flash", "full"];
+	const parts: string[] = [];
+	for (const tier of tiers) {
+		const config = strategy[tier];
+		const hasPrimary = Boolean(config?.primary);
+		const hasFailover = config?.failover && config.failover.length > 0;
+		let value: string;
+		if (hasPrimary) {
+			value = config!.primary!;
+		} else if (hasFailover) {
+			value = `failover: ${config!.failover!.join(", ")}`;
+		} else {
+			value = "(default)";
+		}
+		parts.push(`${tier}: ${value}`);
+	}
+	return `mode: ${modeName} | ${parts.join(" · ")}`;
+}

package/src/index.ts

@@ -17,6 +17,7 @@ import {
 	resolveFlowModelCandidates,
 	selectFlowModelStrategy,
 	writeGlobalFlowMode,
+	formatFlowModelStrategy,
 	type LoadedFlowModelConfigs,
 } from "./config.js";
 import { getInheritedCliArgs } from "./cli-args.js";
@@ -727,8 +728,10 @@ export default function (pi: ExtensionAPI) {
 				);
 			} else {
 				try {
-					const writeResult = writeGlobalFlowMode(requestedFlowMode);
-					console.warn(`[pi-agent-flow] Flow mode switched to "${requestedFlowMode}" in ${writeResult.path}.`);
+					writeGlobalFlowMode(requestedFlowMode);
+					const strategy = loadedFlowModelConfigs.configs[requestedFlowMode] ?? {};
+					const strategyDescription = formatFlowModelStrategy(requestedFlowMode, strategy);
+					console.warn(strategyDescription);
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
 					console.warn(`[pi-agent-flow] ${message}`);
@@ -1091,7 +1094,12 @@ flow [type] accomplished
 		pi.emit("pi-agent-flow:ready", pluginApi);
 	}
 
-	// Register cleanup on process exit (once)
+	// Register cleanup on process exit (once).
+	// We intentionally do NOT hook SIGINT/SIGTERM here. A plugin must not
+	// override the host process signal handling; doing so can cut off the
+	// host's terminal-cleanup logic and leave escape sequences or status
+	// lines visible on Ctrl+C. The 'exit' event fires for normal exits,
+	// including when the host handles the signal and calls process.exit().
 	if (!(globalThis as any).__pi_agent_flow_shutdown_registered) {
 		(globalThis as any).__pi_agent_flow_shutdown_registered = true;
 		const emitShutdown = () => {
@@ -1100,8 +1108,6 @@ flow [type] accomplished
 			}
 		};
 		process.on("exit", emitShutdown);
-		process.on("SIGINT", () => { emitShutdown(); process.exit(130); });
-		process.on("SIGTERM", () => { emitShutdown(); process.exit(143); });
 	}
 
 }

package/src/render-utils.ts

@@ -47,27 +47,30 @@ export function formatCompactTokenPair(usage: Partial<UsageStats>): string {
 	return `↑ ${formatFixedTokens(usage.input || 0)} · ↓ ${formatFixedTokens(usage.output || 0)}`;
 }
 
-export function formatCompactStats(usage: Partial<UsageStats>, model?: string, maxWidth?: number): string {
-	const parts: string[] = [];
-	parts.push(`↑ ${formatFixedTokens(usage.input || 0)}`);
-	parts.push(`↓ ${formatFixedTokens(usage.output || 0)}`);
-	parts.push(`tps: ${formatTps(usage.smoothedTps)}`);
-	parts.push(`ctx: ${formatFixedTokens(usage.contextTokens || 0)}`);
+export function formatCompactStats(
+	usage: Partial<UsageStats>,
+	model?: string,
+	maxWidth?: number,
+	options: { skipTokens?: boolean } = {},
+): string {
+	const tokenParts = [`↑ ${formatFixedTokens(usage.input || 0)}`, `↓ ${formatFixedTokens(usage.output || 0)}`];
+	const runtimeParts = [`tps: ${formatTps(usage.smoothedTps)}`, `ctx: ${formatFixedTokens(usage.contextTokens || 0)}`];
+	const parts = options.skipTokens ? runtimeParts : [...tokenParts, ...runtimeParts];
 
 	const displayModel = model ? model.replace(/^[^/]+\//, "") : undefined;
 	let result = parts.join(" · ") + (displayModel ? ` · ${displayModel}` : "");
 	if (maxWidth && visibleLength(result) > maxWidth) {
-		// Drop model first
+		// Drop model first.
 		let narrow = parts.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
-		// Drop context tokens
-		const narrowParts = parts.slice(0, 3); // up to tps
-		narrow = narrowParts.join(" · ");
+		// Drop context tokens next.
+		const withoutContext = parts.filter((part) => !part.startsWith("ctx:"));
+		narrow = withoutContext.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
-		// Bare minimum (just input/output)
-		narrow = `${parts[0]} · ${parts[1]}`;
+		// Bare minimum: token pair for normal stats, tps for token-free headers.
+		narrow = options.skipTokens ? runtimeParts[0] : tokenParts.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
 		return truncateChars(result, maxWidth);
@@ -105,12 +108,15 @@ export function getTruncationBudget(prefixLength: number): number {
 /** Fixed content budget for collapsed-line text (dir/act/log). */
 export const CONTENT_MAX = 60;
 
+/** Longer budget for detail lines (act/msg) to show more content. */
+export const DETAIL_CONTENT_MAX = 80;
+
 /**
  * Compute how many visible chars of content fit after a prefix,
- * using the fixed CONTENT_MAX budget. Floor of 8 to keep things readable.
+ * using the given budget (defaults to CONTENT_MAX). Floor of 8 to keep things readable.
  */
-export function contentBudget(prefixVisibleLen: number): number {
-	return Math.max(CONTENT_MAX - prefixVisibleLen, 8);
+export function contentBudget(prefixVisibleLen: number, max = CONTENT_MAX): number {
+	return Math.max(max - prefixVisibleLen, 8);
 }
 
 /**

package/src/render.ts

@@ -22,7 +22,7 @@ import {
 	isFlowError,
 	isFlowSuccess,
 } from "./types.js";
-import { formatCompactStats, formatCompactTokenPair, formatCountdown, formatFlowTypeName, truncateChars, tailText, contentBudget, visibleLength } from "./render-utils.js";
+import { formatCompactStats, formatCompactTokenPair, formatCountdown, formatFlowTypeName, truncateChars, tailText, contentBudget, visibleLength, DETAIL_CONTENT_MAX } from "./render-utils.js";
 
 function shortenPath(p: string): string {
 	const home = os.homedir();
@@ -33,6 +33,12 @@ type ThemeFg = (color: string, text: string) => string;
 type ThemeBg = (color: string, text: string) => string;
 type FlowTheme = { fg: ThemeFg; bold: (s: string) => string; bg: ThemeBg };
 
+const COLLAPSED_FLOW_HEADER_TYPE_WIDTH = 8;
+
+function formatCollapsedFlowHeaderTypeName(type: string): string {
+	return formatFlowTypeName(type).padEnd(COLLAPSED_FLOW_HEADER_TYPE_WIDTH, " ");
+}
+
 function formatFlowToolCall(toolName: string, args: Record<string, unknown>, fg: ThemeFg): string {
 	const pathArg = (args.file_path || args.path || "...") as string;
 
@@ -319,9 +325,9 @@ function renderFlowCollapsed(
 ): Container {
 	const container = new Container();
 	const maxWidth = process.stdout.columns ?? 80;
-	const stats = formatCompactStats(r.usage, r.model, maxWidth);
-	const typeName = formatFlowTypeName(r.type);
-	let header = `${theme.fg("accent", theme.bold(typeName))} ${theme.fg("dim", stats)}`;
+	const stats = formatCompactStats(r.usage, r.model, maxWidth, { skipTokens: true });
+	const typeName = formatCollapsedFlowHeaderTypeName(r.type);
+	let header = `${theme.fg("accent", theme.bold(typeName))}${theme.fg("dim", `· ${stats}`)}`;
 	if (error && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 	container.addChild(new TruncatedText(header, 0, 0));
 
@@ -337,13 +343,13 @@ function renderFlowCollapsed(
 	if (lastTool) {
 		const actStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
 		const actPrefix = `├─ act: [${r.usage.toolCalls}] - `;
-		const actContent = truncateChars(actStr, contentBudget(visibleLength(actPrefix)));
+		const actContent = truncateChars(actStr, contentBudget(visibleLength(actPrefix), DETAIL_CONTENT_MAX));
 		container.addChild(new TruncatedText(`${theme.fg("dim", actPrefix)}${actContent}`, 0, 0));
 	}
 
 	// msg: line (last assistant text or streaming)
 	const msgPrefix = formatMsgLinePrefix("└─", r);
-	const msgBudget = contentBudget(visibleLength(msgPrefix));
+	const msgBudget = contentBudget(visibleLength(msgPrefix), DETAIL_CONTENT_MAX);
 	if (r.exitCode === -1 && streamingText) {
 		const logContent = tailText(streamingText, msgBudget);
 		container.addChild(new TruncatedText(`${theme.fg("dim", msgPrefix)}${theme.fg("dim", logContent)}`, 0, 0));
@@ -451,13 +457,13 @@ function renderActivityPanel(
 	for (let i = 0; i < results.length; i++) {
 		const r = results[i];
 		const isLast = i === results.length - 1;
-		const stats = formatCompactStats(r.usage, r.model, maxWidth);
+		const stats = formatCompactStats(r.usage, r.model, maxWidth, { skipTokens: true });
 		const error = isFlowError(r);
-		const typeName = formatFlowTypeName(r.type);
+		const typeName = formatCollapsedFlowHeaderTypeName(r.type);
 
 		// Header line
 		const headerPrefix = isLast ? "└─" : "├─";
-		let headerLine = `${theme.fg("dim", headerPrefix)} ${theme.fg("accent", theme.bold(typeName))} ${theme.fg("dim", stats)}`;
+		let headerLine = `${theme.fg("dim", headerPrefix)} ${theme.fg("accent", theme.bold(typeName))}${theme.fg("dim", `· ${stats}`)}`;
 		if (error && r.stopReason) {
 			headerLine += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 		}
@@ -478,13 +484,13 @@ function renderActivityPanel(
 		if (lastTool) {
 			const actStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
 			const actPrefix = `${indent}├─ act: [${r.usage.toolCalls}] - `;
-			const actContent = truncateChars(actStr, contentBudget(visibleLength(actPrefix)));
+			const actContent = truncateChars(actStr, contentBudget(visibleLength(actPrefix), DETAIL_CONTENT_MAX));
 			container.addChild(new TruncatedText(`${theme.fg("dim", actPrefix)}${actContent}`, 0, 0));
 		}
 
 		// msg: line (live streaming text or last assistant text)
 		const msgPrefix = formatMsgLinePrefix(indent + "└─", r);
-		const msgBudget = contentBudget(visibleLength(msgPrefix));
+		const msgBudget = contentBudget(visibleLength(msgPrefix), DETAIL_CONTENT_MAX);
 		const liveText = r.exitCode === -1 ? r.streamingText : undefined;
 		const lastText = liveText || getLastAssistantText(r.messages);
 		if (lastText) {