pi-agent-flow 1.2.7 → 1.4.0

package/package.json

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

package/src/batch/constants.ts

@@ -11,6 +11,7 @@ export const MAX_BYTES = 50 * 1024; // 50KB
 export const SAFE_FULL_READ_LIMIT = 300;
 export const TARGETED_READ_LINE_LIMIT = 1000;
 export const MAX_CONTEXT_MAP_ENTRIES = 100;
+export const MAX_TOTAL_RESULT_LINES = 1500;
 
 // ---------------------------------------------------------------------------
 // Types

package/src/batch/execute.ts

@@ -16,6 +16,7 @@ import {
 	MAX_BYTES,
 	SAFE_FULL_READ_LIMIT,
 	TARGETED_READ_LINE_LIMIT,
+	MAX_TOTAL_RESULT_LINES,
 } from "./constants.js";
 import {
 	normalizeToLF,
@@ -212,6 +213,8 @@ export async function executeOperations(
 	const counts = { read: 0, write: 0, edit: 0, delete: 0, error: 0, skipped: 0 };
 	const errors: { path: string; op: string; message: string; hint?: string }[] = [];
 	const truncatedFiles: { path: string; shown: number; total: number; nextOffset?: number }[] = [];
+	const aggregateLimitSkipped: { path: string }[] = [];
+	let aggregateLinesRead = 0;
 	const includeLimitWarnings = options.includeLimitWarnings ?? true;
 
 	for (const op of operations) {
@@ -232,6 +235,18 @@ export async function executeOperations(
 
 			switch (op.o) {
 				case "read": {
+					if (aggregateLinesRead >= MAX_TOTAL_RESULT_LINES) {
+						results.push({
+							op: "read",
+							path: op.p,
+							status: "skipped",
+							error: `Skipped: aggregate line limit of ${MAX_TOTAL_RESULT_LINES} already reached. Use separate batch/batch_read calls.`,
+						});
+						counts.skipped++;
+						aggregateLimitSkipped.push({ path: op.p });
+						break;
+					}
+
 					// Access check before reading
 					try {
 						await fs.access(resolvedPath);
@@ -293,6 +308,8 @@ export async function executeOperations(
 						});
 					}
 
+					aggregateLinesRead += linesRead;
+
 					results.push({
 						op: "read",
 						path: op.p,
@@ -404,7 +421,7 @@ export async function executeOperations(
 		}
 	}
 	// Build the enhanced summary and content text
-	const summary = buildSummary(counts, errors, truncatedFiles);
+	const summary = buildSummary(counts, errors, truncatedFiles, aggregateLimitSkipped);
 	const contentText = buildContentText(summary, results);
 
 	return { summary, contentText, results };
@@ -418,6 +435,7 @@ function buildSummary(
 	counts: { read: number; write: number; edit: number; delete: number; error: number; skipped: number },
 	errors: { path: string; op: string; message: string; hint?: string }[],
 	truncatedFiles: { path: string; shown: number; total: number; nextOffset?: number }[],
+	aggregateLimitSkipped: { path: string }[] = [],
 ): string {
 	const totalSuccess =
 		counts.read + counts.write + counts.edit + counts.delete;
@@ -471,6 +489,13 @@ function buildSummary(
 		}
 	}
 
+	// Aggregate line limit warnings
+	if (aggregateLimitSkipped.length > 0) {
+		parts.push(
+			`  ⚠ Aggregate line limit (${MAX_TOTAL_RESULT_LINES}) reached — skipped ${aggregateLimitSkipped.length} read${aggregateLimitSkipped.length > 1 ? "s" : ""}: ${aggregateLimitSkipped.map((s) => s.path).join(", ")}`,
+		);
+	}
+
 	return parts.join("\n");
 }
 

package/src/flow.ts

@@ -20,17 +20,19 @@ import {
 	getFlowOutput,
 	normalizeFlowResult,
 } from "./types.js";
-import { extractStructuredOutput } from "./structured-output.js";
+import { extractStructuredOutput, enrichStructuredOutputCommands } from "./structured-output.js";
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
 const AGENT_END_GRACE_MS = 2000;
 const DEFAULT_FLOW_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+const FLOW_TIME_BUDGET_WARNING_MS = 2 * 60 * 1000; // warn 2 min before kill
 const FLOW_DEPTH_ENV = "PI_FLOW_DEPTH";
 const FLOW_MAX_DEPTH_ENV = "PI_FLOW_MAX_DEPTH";
 const FLOW_STACK_ENV = "PI_FLOW_STACK";
 const FLOW_PREVENT_CYCLES_ENV = "PI_FLOW_PREVENT_CYCLES";
 const FLOW_TIMEOUT_ENV = "PI_FLOW_TIMEOUT_MS";
+const FLOW_DEADLINE_ENV = "PI_FLOW_DEADLINE_MS";
 export const FLOW_TOOL_OPTIMIZE_ENV = "PI_FLOW_TOOL_OPTIMIZE";
 const PI_OFFLINE_ENV = "PI_OFFLINE";
 
@@ -140,6 +142,7 @@ function buildFlowArgs(
 	maxDepth: number = 0,
 	toolOptimize: boolean = false,
 	structuredOutput: boolean = true,
+	timeoutMs?: number,
 ): string[] {
 	const args: string[] = [
 		"--mode",
@@ -210,11 +213,17 @@ function buildFlowArgs(
 		? `You may delegate to sub-flows (depth ${currentDepth}/${effectiveMaxDepth}).`
 		: `You may NOT delegate to sub-flows (depth limit reached).`;
 
+	const timeBudgetHint =
+		timeoutMs && timeoutMs > 0
+			? `Time budget: ${Math.round(timeoutMs / 1000)}s total. You will be hard-killed when time expires — plan and prioritize accordingly.\n`
+			: "";
+
 	const activation =
 		`\n\n<activation flow="${flow.name}" depth="${currentDepth}" tools="${availableTools}">\n` +
 		`You are a [${flow.name}] agent operating at depth ${currentDepth}.\n` +
 		`Available tools: ${availableTools}.\n` +
 		`${delegationRule}\n` +
+		`${timeBudgetHint}` +
 		`Do not attempt to use any tool outside the available set — it will fail.\n` +
 		`</activation>`;
 
@@ -227,6 +236,8 @@ function buildFlowArgs(
 			`\n\n## Structured Output\n\n` +
 			`End your response with a JSON code block containing:\n` +
 			`\n` +
+			`For every command you ran, include the exact verbatim command string in the \\"command\\" field (not a paraphrase or summary).\n` +
+			`\n` +
 			`\`\`\`json\n` +
 			`{\n` +
 			`  "version": "1.0",\n` +
@@ -239,7 +250,7 @@ function buildFlowArgs(
 			`    { "type": "read", "description": "what was done", "target": "file.ts", "result": "success", "evidence": "output or proof" }\n` +
 			`  ],\n` +
 			`  "commands": [\n` +
-			`    { "command": "npm test", "tool": "bash", "target": ".", "result": "success", "output": "12 passing, 2 failing", "purpose": "Run test suite to verify fix" }\n` +
+			`    { "command": "curl -s -X POST https://api.example.com/v1/data -H 'Authorization: Bearer token'", "tool": "bash" }\n` +
 			`  ],\n` +
 			`  "notDone": [\n` +
 			`    { "item": "unfinished work", "reason": "why it was not completed", "blocker": "blocking issue if any", "nextStep": "specific follow-up" }\n` +
@@ -404,6 +415,14 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		forkSessionTmpPath = forkTmp.filePath;
 	}
 
+	// Resolve timeout: explicit option > env var > default (10 min)
+	const envTimeoutRaw = process.env[FLOW_TIMEOUT_ENV];
+	const envTimeout = envTimeoutRaw !== undefined ? (() => {
+		const n = Number(envTimeoutRaw);
+		return Number.isSafeInteger(n) && n >= 0 ? n : null;
+	})() : null;
+	const effectiveTimeout = opts.timeoutMs ?? envTimeout ?? DEFAULT_FLOW_TIMEOUT_MS;
+
 	try {
 		const piArgs = buildFlowArgs(
 			flow,
@@ -414,17 +433,10 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			maxDepth,
 			toolOptimize,
 			structuredOutput,
+			effectiveTimeout,
 		);
 		let wasAborted = false;
 
-		// Resolve timeout: explicit option > env var > default (10 min)
-		const envTimeoutRaw = process.env[FLOW_TIMEOUT_ENV];
-		const envTimeout = envTimeoutRaw !== undefined ? (() => {
-			const n = Number(envTimeoutRaw);
-			return Number.isSafeInteger(n) && n >= 0 ? n : null;
-		})() : null;
-		const effectiveTimeout = opts.timeoutMs ?? envTimeout ?? DEFAULT_FLOW_TIMEOUT_MS;
-
 		const exitCode = await new Promise<number>((resolve) => {
 			const nextDepth = Math.max(0, Math.floor(parentDepth)) + 1;
 			const propagatedMaxDepth = Math.max(0, Math.floor(maxDepth));
@@ -444,6 +456,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 					[FLOW_PREVENT_CYCLES_ENV]: preventCycles ? "1" : "0",
 					[FLOW_TOOL_OPTIMIZE_ENV]: toolOptimize ? "1" : "0",
 					[PI_OFFLINE_ENV]: "1",
+					[FLOW_DEADLINE_ENV]: String(Date.now() + effectiveTimeout),
 				},
 			});
 
@@ -560,6 +573,23 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 
 			// Execution timeout — kill child if it runs too long
 			if (effectiveTimeout > 0) {
+				// Warning timer: notify the parent UI that the child is about to be killed.
+				// NOTE: True mid-flight injection into the child's context requires pi-core
+				// support for out-of-band messages. Until then, the agent only knows its
+				// budget from the initial prompt; this warning is parent-side only.
+				const warningMs = effectiveTimeout - FLOW_TIME_BUDGET_WARNING_MS;
+				if (warningMs > 0) {
+					const warnTimer = setTimeout(() => {
+						if (didClose || settled) return;
+						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;
+						// Force an update so the parent UI shows the warning immediately.
+						emitUpdate();
+					}, warningMs);
+					warnTimer.unref();
+				}
+
 				const timeoutTimer = setTimeout(() => {
 					if (didClose || settled) return;
 					result.stderr += `\nFlow timed out after ${Math.round(effectiveTimeout / 1000)}s.`;
@@ -586,7 +616,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			const flowText = getFlowOutput(normalized.messages);
 			const extracted = extractStructuredOutput(flowText);
 			if (extracted) {
-				normalized.structuredOutput = extracted;
+				normalized.structuredOutput = enrichStructuredOutputCommands(extracted, normalized.messages);
 			}
 		}
 

package/src/index.ts

@@ -448,11 +448,7 @@ function renderCompressedFlowResult(r: CompressedFlowResult): string {
 		parts.push(`Files:\n${fileLines.join("\n")}`);
 	}
 	if (r.commands?.length) {
-		const cmdLines = r.commands.map((c) => {
-			const result = c.result ? ` (${c.result})` : "";
-			const purpose = c.purpose ? ` — ${c.purpose}` : "";
-			return `  ${c.tool ?? "cmd"}: ${c.command}${result}${purpose}`;
-		});
+		const cmdLines = r.commands.map((c) => `  ${c.tool ?? "cmd"}: ${c.command}`);
 		parts.push(`Commands:\n${cmdLines.join("\n")}`);
 	}
 	if (r.error) parts.push(`Error: ${r.error}`);

package/src/structured-output.ts

@@ -5,6 +5,7 @@
  * and validates it against the FlowStructuredOutput schema.
  */
 
+import type { Message } from "@mariozechner/pi-ai";
 import type { Action, CommandEntry, FileEntry, FlowStructuredOutput, NotDoneItem } from "./types.js";
 
 type FlowStatus = FlowStructuredOutput["status"];
@@ -95,3 +96,64 @@ export function extractStructuredOutput(text: string): FlowStructuredOutput | un
 		...(parsed.extensions !== undefined ? { extensions: parsed.extensions } : {}),
 	};
 }
+
+/**
+ * Walk the message history and mechanically replace paraphrased bash commands
+ * in a structured-output `commands` array with the exact verbatim strings from
+ * the actual tool calls. This fixes the common LLM behaviour of summarising
+ * `curl -s -X POST …` as `"curl GAWA baseline"`.
+ *
+ * Batch operations are flattened so that bash commands nested inside a batch
+ * call are included in the same chronological order they were executed.
+ */
+export function enrichStructuredOutputCommands(
+	structuredOutput: FlowStructuredOutput,
+	messages: Message[],
+): FlowStructuredOutput {
+	// Collect actual verbatim bash commands (including those inside batch ops)
+	const actualBashCommands: string[] = [];
+	for (const msg of messages) {
+		if (msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
+		for (const part of msg.content) {
+			if (part.type !== "toolCall") continue;
+			const name =
+				part.name ||
+				(part as unknown as { toolName?: string }).toolName ||
+				"";
+			const args = part.arguments || part.input || {};
+
+			if (name === "bash") {
+				const cmd = (args.command as string) || "";
+				if (cmd) actualBashCommands.push(cmd);
+			} else if (name === "batch") {
+				const ops = Array.isArray(args.o)
+					? args.o
+					: Array.isArray(args.op)
+						? args.op
+						: Array.isArray(args.operations)
+							? args.operations
+							: [];
+				for (const op of ops) {
+					if (!op) continue;
+					const opType = (op.o ?? op.op) as string;
+					if (opType === "bash" && op.command) {
+						actualBashCommands.push(op.command as string);
+					}
+				}
+			}
+		}
+	}
+
+	if (actualBashCommands.length === 0) return structuredOutput;
+
+	// Replace paraphrased bash commands with actual verbatim ones, in order.
+	let bashIdx = 0;
+	const enrichedCommands = structuredOutput.commands.map((cmd) => {
+		if (cmd.tool === "bash" && bashIdx < actualBashCommands.length) {
+			return { command: actualBashCommands[bashIdx++], tool: "bash" };
+		}
+		return { command: cmd.command, tool: cmd.tool };
+	});
+
+	return { ...structuredOutput, commands: enrichedCommands };
+}

package/src/types.ts

@@ -39,18 +39,10 @@ export interface FileEntry {
 
 /** Structured command/tool invocation entry in a flow's output. */
 export interface CommandEntry {
-	/** The command string or tool call representation. */
+	/** The exact verbatim command string or tool call that was executed. */
 	command: string;
 	/** Tool used: bash, grep, find, ls, batch, read, write, edit, flow, web. */
 	tool?: string;
-	/** Working directory or target scope (file path, URL, etc.). */
-	target?: string;
-	/** Whether it succeeded, failed, or was aborted. */
-	result?: "success" | "failure" | "partial" | "aborted";
-	/** High-level output or error excerpt (not full stdout). */
-	output?: string;
-	/** Why this command was run (1 sentence). */
-	purpose?: string;
 }
 
 /** Compressed representation of a flow result for child context inheritance. */