pi-agent-flow 1.5.0 → 1.7.0

package/package.json

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

package/src/flow.ts

@@ -25,10 +25,11 @@ import { DEFAULT_AGENT_SESSION_MODE, getAgentSessionTimeoutMs, type AgentSession
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
+const FINISH_KILL_GRACE_MS = 5_000; // wait 5s after finish() before force-killing the child process
 const AGENT_END_GRACE_MS = 2000;
 const FLOW_TIME_BUDGET_WARNING_MS = 2 * 60 * 1000; // warn 2 min before kill
-const FLOW_FINAL_URGE_MS = 30 * 1000; // final urge 30 s before kill
-const REPORTING_GRACE_MS = 10_000; // grace period after timeout for agent to report findings
+const FLOW_FINAL_URGE_MS = 135 * 1000; // final urge 135 s (2m15s) before kill (increased from 30s for wider summary window)
+const REPORTING_GRACE_MS = 90_000; // grace period after timeout for agent to report findings (increased from 10s to 90s)
 const FLOW_TOOL_SUMMARY_GRACE_MS = FLOW_FINAL_URGE_MS; // bash/tool abort lead time so the agent can summarize
 const FLOW_DEPTH_ENV = "PI_FLOW_DEPTH";
 const FLOW_MAX_DEPTH_ENV = "PI_FLOW_MAX_DEPTH";
@@ -38,6 +39,54 @@ const FLOW_DEADLINE_ENV = "PI_FLOW_DEADLINE_MS";
 const FLOW_TOOL_SUMMARY_GRACE_ENV = "PI_FLOW_TOOL_SUMMARY_GRACE_MS";
 export const FLOW_TOOL_OPTIMIZE_ENV = "PI_FLOW_TOOL_OPTIMIZE";
 const PI_OFFLINE_ENV = "PI_OFFLINE";
+const FLOW_REMINDER_FILE_ENV = "PI_FLOW_REMINDER_FILE";
+
+// ---------------------------------------------------------------------------
+// Global child process group tracking for signal propagation
+// ---------------------------------------------------------------------------
+
+/** Track child process groups so we can kill them on parent exit / signal. */
+const runningChildGroups = new Map<number, { groupPid: number; name: string }>();
+
+/** Register a child process group for cleanup on shutdown. */
+export function registerChildGroup(pid: number, name: string): void {
+	if (pid > 0 && !isWindows) {
+		runningChildGroups.set(pid, { groupPid: pid, name });
+	}
+}
+
+/** Unregister a completed/stopped child process group. */
+export function unregisterChildGroup(pid: number): void {
+	runningChildGroups.delete(pid);
+}
+
+/**
+ * Terminate all registered child process groups via SIGTERM (then SIGKILL after timeout).
+ * Called on parent exit, SIGINT, SIGTERM, or pi-agent-flow:shutdown.
+ */
+export function terminateAllChildGroups(): void {
+	if (runningChildGroups.size === 0) return;
+	const pids = Array.from(runningChildGroups.keys());
+	for (const pid of pids) {
+		try {
+			process.kill(-pid, "SIGTERM");
+		} catch {
+			try { process.kill(pid, "SIGTERM"); } catch { /* gone */ }
+		}
+	}
+	// Hard kill after timeout
+	const sigkillTimer = setTimeout(() => {
+		for (const pid of pids) {
+			try {
+				process.kill(-pid, "SIGKILL");
+			} catch {
+				try { process.kill(pid, "SIGKILL"); } catch { /* gone */ }
+			}
+		}
+		runningChildGroups.clear();
+	}, 5000);
+	sigkillTimer.unref();
+}
 
 type FlowUpdateCallback = (partial: AgentToolResult<FlowDetails>) => void;
 
@@ -109,6 +158,24 @@ function cleanupFlowTempDir(dir: string | null): void {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// Reminder file helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a reminder message to the reminder file so the child agent can see it
+ * via the timed-bash wrapper before its next tool call.
+ * Creates the file if it doesn't exist; appends the message.
+ */
+function writeReminderFile(reminderFilePath: string | null, message: string): void {
+	if (!reminderFilePath) return;
+	try {
+		fs.writeFileSync(reminderFilePath, message + "\n", { encoding: "utf-8", flag: "a" });
+	} catch {
+		/* best-effort */
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Build pi CLI arguments (fork-only)
 // ---------------------------------------------------------------------------
@@ -428,6 +495,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		forkSessionTmpPath = forkTmp.filePath;
 	}
 
+	// Create a temp dir for the reminder file so the child agent can read timeout warnings
+	// via the timed-bash wrapper before its next tool call.
+	let reminderTmpDir: string | null = null;
+	let reminderFilePath: string | null = null;
+	if (effectiveTimeout > 0) {
+		reminderTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-flow-reminder-"));
+		reminderFilePath = path.join(reminderTmpDir, "reminder.txt");
+	}
+
 	try {
 		const piArgs = buildFlowArgs(
 			flow,
@@ -472,13 +548,20 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 					...(effectiveTimeout > 0 ? {
 						[FLOW_DEADLINE_ENV]: String(deadlineAtMs),
 						[FLOW_TOOL_SUMMARY_GRACE_ENV]: String(toolSummaryGraceMs),
+						[FLOW_REMINDER_FILE_ENV]: reminderFilePath ?? "",
 					} : {
 						[FLOW_DEADLINE_ENV]: "",
 						[FLOW_TOOL_SUMMARY_GRACE_ENV]: "0",
+						[FLOW_REMINDER_FILE_ENV]: "",
 					}),
 				},
 			});
 
+			// Register the child process group for global cleanup on signal/exit
+			if (proc.pid !== undefined && !isWindows) {
+				registerChildGroup(proc.pid, normalizedFlowName);
+			}
+
 			let stdinEnded = false;
 			const endStdin = () => {
 				if (stdinEnded) return;
@@ -497,6 +580,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			let timeoutFired = false;
 			let semanticCompletionTimer: NodeJS.Timeout | undefined;
 			let countdownTimer: NodeJS.Timeout | undefined;
+			let finishKillTimer: NodeJS.Timeout | undefined;
 
 			const clearSemanticCompletionTimer = () => {
 				if (semanticCompletionTimer) {
@@ -534,6 +618,13 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				sigkillTimer.unref();
 			};
 
+			const clearFinishKillTimer = () => {
+				if (finishKillTimer) {
+					clearTimeout(finishKillTimer);
+					finishKillTimer = undefined;
+				}
+			};
+
 			const finish = (code: number) => {
 				if (settled) return;
 				settled = true;
@@ -543,6 +634,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 				if (signal && abortHandler) {
 					signal.removeEventListener("abort", abortHandler);
 				}
+				// Soft-kill: give the child a short grace to exit naturally after stdin close.
+				// If it hasn't closed by then, force-kill to prevent orphaned processes.
+				clearFinishKillTimer();
+				finishKillTimer = setTimeout(() => {
+					if (!didClose) {
+						terminateChild();
+					}
+				}, FINISH_KILL_GRACE_MS);
+				finishKillTimer.unref();
 				resolve(code);
 			};
 
@@ -596,6 +696,10 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 
 			proc.on("close", (code) => {
 				didClose = true;
+				clearFinishKillTimer();
+				if (proc.pid !== undefined) {
+					unregisterChildGroup(proc.pid);
+				}
 				if (buffer.trim()) flushBufferedLines(buffer);
 				finish(code ?? 0);
 			});
@@ -630,13 +734,15 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 						const remainingSec = Math.round(FLOW_TIME_BUDGET_WARNING_MS / 1000);
 						const warnMsg = `\n[Flow warning] ${remainingSec}s remaining before hard timeout. The agent should wrap up now.`;
 						result.stderr += warnMsg;
+						// Write to reminder file so the child agent sees it on its next bash call.
+						writeReminderFile(reminderFilePath, `[Flow warning] ${remainingSec}s remaining before hard timeout. Wrap up your work and output structured findings.`);
 						// Force an update so the parent UI shows the warning immediately.
 						emitUpdate();
 					}, warningMs);
 					warnTimer.unref();
 				}
 
-				// Final urge timer: stronger warning 30 s before hard timeout
+				// Final urge timer: stronger warning 45 s before hard timeout
 				const urgeMs = effectiveTimeout - FLOW_FINAL_URGE_MS;
 				if (urgeMs > 0) {
 					const urgeTimer = setTimeout(() => {
@@ -644,6 +750,8 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 						const remainingSec = Math.round(FLOW_FINAL_URGE_MS / 1000);
 						const urgeMsg = `\n[Flow warning] ${remainingSec}s remaining before hard timeout. Stop all work and output your structured findings.`;
 						result.stderr += urgeMsg;
+						// Write to reminder file so the child agent sees it on its next bash call.
+						writeReminderFile(reminderFilePath, `[Flow urge] ${remainingSec}s remaining before hard timeout. STOP all tool use and output your structured findings NOW.`);
 						emitUpdate();
 					}, urgeMs);
 					urgeTimer.unref();
@@ -692,6 +800,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		return normalized;
 	} finally {
 		cleanupFlowTempDir(forkSessionTmpDir);
+		cleanupFlowTempDir(reminderTmpDir);
 	}
 }
 

package/src/index.ts

@@ -24,7 +24,7 @@ import { getInheritedCliArgs } from "./cli-args.js";
 import { renderFlowCall, renderFlowResult } from "./render.js";
 import { getFlowSummaryText } from "./runner-events.js";
 import { runHooks, runHooksDetailed, getRegisteredHooks, registerHook, unregisterHook } from "./hooks.js";
-import { mapFlowConcurrent, runFlow } from "./flow.js";
+import { mapFlowConcurrent, runFlow, terminateAllChildGroups } from "./flow.js";
 import { executeFlows } from "./executor.js";
 import {
 	type SingleResult,
@@ -1095,14 +1095,20 @@ flow [type] accomplished
 	}
 
 	// 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().
+	// We use prependListener on SIGINT/SIGTERM to propagate to child processes
+	// before the host's own signal handler runs. This avoids orphaned sub-agents.
+	// The host handler still runs afterward and handles terminal cleanup.
 	if (!(globalThis as any).__pi_agent_flow_shutdown_registered) {
 		(globalThis as any).__pi_agent_flow_shutdown_registered = true;
+
+		// Propagate signals to child process groups so sub-agents don't become orphans.
+		// We use prependListener so our handler runs first, before the host's cleanup.
+		process.prependListener("SIGINT", terminateAllChildGroups);
+		process.prependListener("SIGTERM", terminateAllChildGroups);
+
+		// Also handle the 'exit' event, which fires when the host calls process.exit().
 		const emitShutdown = () => {
+			terminateAllChildGroups();
 			if (typeof pi.emit === "function") {
 				pi.emit("pi-agent-flow:shutdown", { reason: "process-exit" });
 			}

package/src/render-utils.ts

@@ -108,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;
 
@@ -320,8 +326,8 @@ function renderFlowCollapsed(
 	const container = new Container();
 	const maxWidth = process.stdout.columns ?? 80;
 	const stats = formatCompactStats(r.usage, r.model, maxWidth, { skipTokens: true });
-	const typeName = formatFlowTypeName(r.type);
-	let header = `${theme.fg("accent", theme.bold(typeName))} ${theme.fg("dim", stats)}`;
+	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));
@@ -453,11 +459,11 @@ function renderActivityPanel(
 		const isLast = i === results.length - 1;
 		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) {

package/src/session-mode.ts

@@ -1,15 +1,16 @@
-export const AGENT_SESSION_MODES = ["fast", "default", "long"] as const;
+export const AGENT_SESSION_MODES = ["fast", "default", "long", "extreme_long"] as const;
 
 export type AgentSessionMode = typeof AGENT_SESSION_MODES[number];
 
 export const DEFAULT_AGENT_SESSION_MODE: AgentSessionMode = "default";
-export const MAX_AGENT_SESSION_TIMEOUT_MS = 900_000;
+export const MAX_AGENT_SESSION_TIMEOUT_MS = 1_200_000;
 export const PI_FLOW_SESSION_MODE_ENV = "PI_FLOW_SESSION_MODE";
 
 export const AGENT_SESSION_TIMEOUTS_MS: Record<AgentSessionMode, number> = {
 	fast: 300_000,
 	default: 600_000,
-	long: MAX_AGENT_SESSION_TIMEOUT_MS,
+	long: 900_000,
+	extreme_long: MAX_AGENT_SESSION_TIMEOUT_MS,
 };
 
 export function parseAgentSessionMode(value: unknown): AgentSessionMode | undefined {

package/src/timed-bash.ts

@@ -13,6 +13,7 @@
  * still active.
  */
 
+import * as fs from "node:fs";
 import { createBashToolDefinition } from "@mariozechner/pi-coding-agent";
 
 export type TimingTier =
@@ -30,6 +31,7 @@ export interface TimingReport {
 
 const FLOW_DEADLINE_ENV = "PI_FLOW_DEADLINE_MS";
 const FLOW_TOOL_SUMMARY_GRACE_ENV = "PI_FLOW_TOOL_SUMMARY_GRACE_MS";
+const FLOW_REMINDER_FILE_ENV = "PI_FLOW_REMINDER_FILE";
 const DEFAULT_FLOW_TOOL_SUMMARY_GRACE_MS = 30_000;
 
 /** Classify duration into user-defined tiers with actionable feedback. */
@@ -87,6 +89,30 @@ function getFlowToolSummaryGraceMs(): number {
 	return parseNonNegativeSafeInteger(process.env[FLOW_TOOL_SUMMARY_GRACE_ENV]) ?? DEFAULT_FLOW_TOOL_SUMMARY_GRACE_MS;
 }
 
+function getFlowReminderFilePath(): string | null {
+	const raw = process.env[FLOW_REMINDER_FILE_ENV];
+	return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+
+/**
+ * Read any pending reminder from the reminder file set by the parent runner.
+ * Returns the reminder text (without trailing newline), or null if no reminder exists.
+ * Clears the file after reading so the agent only sees each reminder once.
+ */
+export function readAndClearReminderFile(): string | null {
+	const filePath = getFlowReminderFilePath();
+	if (!filePath) return null;
+	try {
+		if (!fs.existsSync(filePath)) return null;
+		const content = fs.readFileSync(filePath, { encoding: "utf-8" }).trim();
+		// Clear the file after reading so each reminder is only injected once.
+		try { fs.writeFileSync(filePath, "", { encoding: "utf-8" }); } catch { /* best-effort */ }
+		return content || null;
+	} catch {
+		return null;
+	}
+}
+
 function formatDeadlineAppendix(): string {
 	return "\n\n[Flow timeout] Bash command was interrupted to preserve time for the final flow summary. Stop running tools and return structured findings now.";
 }
@@ -189,6 +215,12 @@ export function createTimedBashToolDefinition(
 		) {
 			const start = Date.now();
 			const deadlineSignal = createDeadlineSignal(signal);
+
+			// Check for pending reminder from parent runner before executing bash.
+			// This allows the parent to inject timeout warnings into the agent's context
+			// via the tool result, since stdin is closed after spawn.
+			const reminderPreamble = readAndClearReminderFile();
+
 			try {
 				const result = await original.execute(
 					toolCallId,
@@ -201,6 +233,10 @@ export function createTimedBashToolDefinition(
 				const report = classifyDuration(duration);
 				const appendix = formatTimingAppendix(report);
 
+				// Inject reminder preamble before timing info so it's the first thing the agent sees.
+				if (reminderPreamble) {
+					appendTextToToolResult(result, `\n\n[REMINDER FROM PARENT] ${reminderPreamble}`);
+				}
 				appendTextToToolResult(result, appendix);
 				if (deadlineSignal.wasDeadlineAbort()) {
 					appendTextToToolResult(result, formatDeadlineAppendix());