pi-agent-flow 1.1.0 → 1.2.2

package/{flow.ts → src/flow.ts}

@@ -10,8 +10,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import { type FlowConfig, getFlowTier } from "./agents.js";
-import { parseFlowCliArgs } from "./runner-cli.js";
+import { type FlowConfig } from "./agents.js";
+import { parseFlowCliArgs } from "./cli-args.js";
 import { processFlowJsonLine, drainStreamingText, drainStreamingEstimate, drainCtxEstimate, updateSmoothedTps, drainSmoothedTps } from "./runner-events.js";
 import {
 	type SingleResult,
@@ -20,6 +20,7 @@ import {
 	getFlowOutput,
 	normalizeFlowResult,
 } from "./types.js";
+import { extractStructuredOutput } from "./structured-output.js";
 
 const isWindows = process.platform === "win32";
 const SIGKILL_TIMEOUT_MS = 5000;
@@ -52,8 +53,8 @@ function mergeStreamingUsage(
 		...actual,
 		...(estimatedOutputTokens > 0 ? { output: Math.max(actual.output, estimatedOutputTokens) } : {}),
 		...(ctxEstimate > 0 ? { contextTokens: Math.max(actual.contextTokens, ctxEstimate) } : {}),
-		// Preserve the peak smoothedTPS seen during the stream rather than the live EMA value.
-		...(smoothedTps > 0 ? { smoothedTps: Math.max(actual.smoothedTps || 0, smoothedTps) } : {}),
+		// Show the live EMA value so the dashboard can rise and fall smoothly.
+		...(smoothedTps > 0 ? { smoothedTps } : {}),
 	};
 }
 
@@ -117,7 +118,7 @@ export function getOptimizedTools(
 	);
 	if (!hasLegacyTools) return flowTools;
 	const filtered = flowTools.filter(
-		(t) => t !== "read" && t !== "write" && t !== "edit" && t !== "batch",
+		(t) => t !== "read" && t !== "write" && t !== "edit" && t !== "batch" && t !== "batch_read",
 	);
 	return filtered.includes("batch")
 		? filtered
@@ -128,10 +129,11 @@ function buildFlowArgs(
 	flow: FlowConfig,
 	intent: string,
 	forkSessionPath: string | null,
-	tieredModels?: { lite?: string; flash?: string; full?: string },
+	model?: string,
 	parentDepth: number = 0,
 	maxDepth: number = 0,
 	toolOptimize: boolean = false,
+	structuredOutput: boolean = true,
 ): string[] {
 	const args: string[] = [
 		"--mode",
@@ -145,10 +147,21 @@ function buildFlowArgs(
 		args.push("--session", forkSessionPath);
 	}
 
-	const tier = getFlowTier(flow.name);
-	const tierModel = tieredModels?.[tier] ?? inheritedCliArgs.tieredModels?.[tier];
-	const model = flow.model ?? tierModel ?? inheritedCliArgs.fallbackModel;
-	if (model) args.push("--model", model);
+	if (inheritedCliArgs.flowModelConfig) {
+		args.push("--flow-model-config", inheritedCliArgs.flowModelConfig);
+	}
+	if (inheritedCliArgs.tieredModels?.lite) {
+		args.push("--flow-lite-model", inheritedCliArgs.tieredModels.lite);
+	}
+	if (inheritedCliArgs.tieredModels?.flash) {
+		args.push("--flow-flash-model", inheritedCliArgs.tieredModels.flash);
+	}
+	if (inheritedCliArgs.tieredModels?.full) {
+		args.push("--flow-full-model", inheritedCliArgs.tieredModels.full);
+	}
+
+	const resolvedModel = model ?? flow.model ?? inheritedCliArgs.fallbackModel;
+	if (resolvedModel) args.push("--model", resolvedModel);
 
 	const thinking = flow.thinking ?? inheritedCliArgs.fallbackThinking;
 	if (thinking) args.push("--thinking", thinking);
@@ -199,8 +212,42 @@ function buildFlowArgs(
 		`</activation>`;
 
 	// Phase 3: Directive — the flow's system prompt (renamed from <system-directive>)
-	const directive = flow.systemPrompt.trim()
-		? `\n\n<directive>\n${flow.systemPrompt.trim()}\n</directive>`
+	let directiveBody = flow.systemPrompt.trim();
+
+	// Append structured output instructions when enabled
+	if (structuredOutput && directiveBody) {
+		directiveBody +=
+			`\n\n## Structured Output\n\n` +
+			`End your response with a JSON code block containing:\n` +
+			`\n` +
+			`\`\`\`json\n` +
+			`{\n` +
+			`  "version": "1.0",\n` +
+			`  "status": "complete",\n` +
+			`  "summary": "2-3 sentence summary of what was accomplished",\n` +
+			`  "files": [\n` +
+			`    { "path": "relative/path", "role": "read", "description": "why it matters", "snippet": "short excerpt", "ranges": [{ "start": 10, "end": 25, "label": "bug" }] }\n` +
+			`  ],\n` +
+			`  "actions": [\n` +
+			`    { "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` +
+			`  ],\n` +
+			`  "notDone": [\n` +
+			`    { "item": "unfinished work", "reason": "why it was not completed", "blocker": "blocking issue if any", "nextStep": "specific follow-up" }\n` +
+			`  ],\n` +
+			`  "nextSteps": ["recommended follow-up action"],\n` +
+			`  "reasoning": ["key hypothesis or inference"],\n` +
+			`  "notes": ["observation or warning"]\n` +
+			`}\n` +
+			`\`\`\`\n` +
+			`\n` +
+			`Only include fields that have data. Omit empty arrays; missing array fields are acceptable. Keep snippets under 300 characters. List at most 10 files, 10 actions, 10 commands, and 10 notDone items. If you cannot produce valid structured output, omit the JSON block entirely.`;
+	}
+
+	const directive = directiveBody
+		? `\n\n<directive>\n${directiveBody}\n</directive>`
 		: "";
 
 	// Phase 4: Mission — the intent wrapped with execution contract
@@ -245,8 +292,10 @@ export interface RunFlowOptions {
 	preventCycles: boolean;
 	/** Whether to transform tool lists to use batch. */
 	toolOptimize?: boolean;
-	/** Tiered model overrides (lite/flash/full). */
-	tieredModels?: { lite?: string; flash?: string; full?: string };
+	/** Whether to inject structured JSON output instructions. Default: true. */
+	structuredOutput?: boolean;
+	/** Explicit model to use for this flow execution. */
+	model?: string;
 	/** Abort signal for cancellation. */
 	signal?: AbortSignal;
 	/** Streaming update callback. */
@@ -276,6 +325,8 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		maxDepth,
 		preventCycles,
 		toolOptimize = false,
+		structuredOutput = true,
+		model,
 		signal,
 		onUpdate,
 		makeDetails,
@@ -297,7 +348,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		};
 	}
 
-	const resolvedModel = flow.model ?? inheritedCliArgs.fallbackModel;
+	const resolvedModel = model ?? flow.model ?? inheritedCliArgs.fallbackModel;
 	const result: SingleResult = {
 		type: normalizedFlowName,
 		agentSource: flow.source,
@@ -310,21 +361,30 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		model: resolvedModel,
 	};
 
+	let liveStreamingText = "";
+	let liveEstimatedOutputTokens = 0;
+	let lastActualOutputTokens = result.usage.output;
 	const emitUpdate = () => {
-		const streaming = drainStreamingText(result);
+		const streamingDelta = drainStreamingText(result);
+		if (streamingDelta) liveStreamingText += streamingDelta;
 		const estimatedTokens = drainStreamingEstimate(result);
+		if (result.usage.output !== lastActualOutputTokens) {
+			lastActualOutputTokens = result.usage.output;
+			liveEstimatedOutputTokens = result.usage.output;
+		}
+		liveEstimatedOutputTokens += estimatedTokens;
 		const ctxEst = drainCtxEstimate(result);
 		updateSmoothedTps(result, estimatedTokens);
 		const smoothedTps = drainSmoothedTps(result);
-		const mergedUsage = mergeStreamingUsage(result.usage, estimatedTokens, ctxEst, smoothedTps);
+		const mergedUsage = mergeStreamingUsage(result.usage, liveEstimatedOutputTokens, ctxEst, smoothedTps);
 		onUpdate?.({
 			content: [
 				{
 					type: "text",
-					text: streaming || getFlowOutput(result.messages) || "(running...)",
+					text: liveStreamingText || getFlowOutput(result.messages) || "(running...)",
 				},
 			],
-			details: makeDetails([{ ...result, usage: mergedUsage }]),
+			details: makeDetails([{ ...result, usage: mergedUsage, streamingText: liveStreamingText || undefined }]),
 		});
 	};
 
@@ -342,10 +402,11 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			flow,
 			intent,
 			forkSessionTmpPath,
-			opts.tieredModels,
+			model,
 			parentDepth,
 			maxDepth,
 			toolOptimize,
+			structuredOutput,
 		);
 		let wasAborted = false;
 
@@ -511,7 +572,18 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			result.usage.smoothedTps = finalSmoothedTps;
 		}
 
-		return normalizeFlowResult(result, wasAborted);
+		const normalized = normalizeFlowResult(result, wasAborted);
+
+		// Extract structured JSON output from the final assistant text
+		if (structuredOutput) {
+			const flowText = getFlowOutput(normalized.messages);
+			const extracted = extractStructuredOutput(flowText);
+			if (extracted) {
+				normalized.structuredOutput = extracted;
+			}
+		}
+
+		return normalized;
 	} finally {
 		cleanupFlowTempDir(forkSessionTmpDir);
 	}

package/{hooks.ts → src/hooks.ts}

@@ -104,19 +104,19 @@ registerHook({
 	},
 });
 
-/** Suggest explore flow after a successful audit flow. */
+/** Suggest scout flow after a successful audit flow. */
 registerHook({
-	name: "pi-agent-flow/audit-to-explore",
+	name: "pi-agent-flow/audit-to-scout",
 	trigger: { flowTypes: ["audit"], onlyOnSuccess: true },
 	action: (ctx) => {
-		const exploreWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "explore",
+		const scoutWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "scout",
 		);
-		if (exploreWasRequested) return null;
+		if (scoutWasRequested) return null;
 
 		return {
 			content:
-				"Audit complete. Consider running an [explore] flow to review the audit findings.",
+				"Audit complete. Consider running a [scout] flow to trace the audit findings across the codebase.",
 			priority: 15,
 		};
 	},