pi-agent-flow 1.2.4 → 1.2.6

package/src/cli-args.ts

@@ -61,6 +61,17 @@ export interface ParsedFlowCliArgs {
  * - alwaysProxy: forwarded verbatim to every child
  * - fallbackModel/thinking/tools: used only when the flow file does not set them
  */
+let _cachedArgs: ParsedFlowCliArgs | undefined;
+
+/**
+ * Lazily parse process.argv once and cache the result.
+ * Avoids module-level side effects at import time.
+ */
+export function getInheritedCliArgs(): ParsedFlowCliArgs {
+	if (!_cachedArgs) _cachedArgs = parseFlowCliArgs(process.argv);
+	return _cachedArgs;
+}
+
 export function parseFlowCliArgs(argv: string[]): ParsedFlowCliArgs {
 	const extensionArgs: string[] = [];
 	const alwaysProxy: string[] = [];

package/src/config.ts

@@ -29,6 +29,10 @@ export interface FlowSettings {
 	toolOptimize?: boolean;
 	/** Whether to inject structured JSON output instructions into flow prompts. Default: true. */
 	structuredOutput?: boolean;
+	/** Maximum number of flows to execute concurrently. Default: 4. */
+	maxConcurrency?: number;
+	/** Whether to automatically queue follow-up flows based on hook transitions. Default: false. */
+	autoTransition?: boolean;
 }
 
 const BUILTIN_FLOW_MODEL_CONFIGS: FlowModelConfigs = {
@@ -176,6 +180,12 @@ function extractFlowSettings(settings: Record<string, unknown> | null): FlowSett
 	if (typeof obj.structuredOutput === "boolean") {
 		result.structuredOutput = obj.structuredOutput;
 	}
+	if (typeof obj.maxConcurrency === "number" && Number.isSafeInteger(obj.maxConcurrency) && obj.maxConcurrency >= 1) {
+		result.maxConcurrency = obj.maxConcurrency;
+	}
+	if (typeof obj.autoTransition === "boolean") {
+		result.autoTransition = obj.autoTransition;
+	}
 	return result;
 }
 

package/src/executor.ts

@@ -0,0 +1,399 @@
+/**
+ * FlowExecutor — extracted from index.ts for testability.
+ *
+ * Encapsulates the orchestration logic for running flows: cycle detection,
+ * project-flow confirmation, parallel execution with failover, caching,
+ * hook invocation, auto-transition, and telemetry.
+ */
+
+import type { FlowConfig } from "./agents.js";
+import type {
+	SingleResult,
+	FlowDetails,
+	CompressedFlowResult,
+	FlowMetrics,
+} from "./types.js";
+import { isFlowSuccess, isFlowError, getFlowOutput, emptyFlowUsage } from "./types.js";
+import { extractStructuredOutput } from "./structured-output.js";
+import { runHooksDetailed, type RunHooksResult } from "./hooks.js";
+import { mapFlowConcurrent, runFlow } from "./flow.js";
+import { getFlowSummaryText } from "./runner-events.js";
+import { resolveFlowModelCandidates, selectFlowModelStrategy, type LoadedFlowModelConfigs, type FlowModelStrategy } from "./config.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FlowExecutorDeps {
+	/** All discovered flow configs. */
+	flows: FlowConfig[];
+	/** Current delegation depth. */
+	currentDepth: number;
+	/** Maximum delegation depth. */
+	maxDepth: number;
+	/** Ancestor flow stack (names). */
+	ancestorFlowStack: string[];
+	/** Whether cycle prevention is enabled. */
+	preventCycles: boolean;
+	/** Whether to use optimized tool list. */
+	toolOptimize: boolean;
+	/** Whether to inject structured output instructions. */
+	structuredOutput: boolean;
+	/** Working directory. */
+	cwd: string;
+	/** Loaded flow model configs. */
+	loadedFlowModelConfigs: LoadedFlowModelConfigs;
+	/** Max concurrency for parallel flow execution. */
+	maxConcurrency: number;
+	/** Whether auto-transition is enabled. */
+	autoTransition: boolean;
+	/** Abort signal. */
+	signal?: AbortSignal;
+	/** Streaming update callback. */
+	onUpdate?: (result: import("@mariozechner/pi-agent-core").AgentToolResult<FlowDetails>) => void;
+	/** Factory to wrap results into FlowDetails. */
+	makeDetails: (results: SingleResult[]) => FlowDetails;
+	/** Get a CLI flag value. */
+	getFlag: (name: string) => unknown;
+	/** Inherited CLI args for tier overrides. */
+	tierOverrideResolver: (tier: "lite" | "flash" | "full") => string | undefined;
+	/** Inherited fallback model. */
+	fallbackModel?: string;
+	/** Fork session snapshot JSONL. */
+	forkSessionSnapshotJsonl: string | null;
+	/** Flow result cache for compression. */
+	flowResultCache: Map<string, CompressedFlowResult[]>;
+	/** Project flows directory. */
+	projectFlowsDir: string | null;
+	/** Session manager for fork snapshot. */
+	sessionManager: { getHeader: () => unknown; getBranch: () => unknown[] };
+	/** Whether UI is available for confirmation. */
+	hasUI: boolean;
+	/** UI confirmation callback. */
+	uiConfirm: (title: string, body: string) => Promise<boolean>;
+	/** Telemetry callback. */
+	onFlowMetrics?: (metrics: FlowMetrics) => void;
+	/** Whether to prompt the user before running project-local flows. Default: true. */
+	confirmProjectFlows?: boolean;
+}
+
+export interface ExecuteFlowParams {
+	type: string;
+	intent: string;
+	aim: string;
+	cwd?: string;
+}
+
+export interface ExecuteFlowResult {
+	content: Array<{ type: string; text: string }>;
+	details: FlowDetails;
+	isError?: boolean;
+	/** Auto-queued transitions for the caller to execute. */
+	autoTransitions?: Array<{ type: string; intent: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getFlowCycleViolations(
+	requestedNames: Set<string>,
+	ancestorFlowStack: string[],
+): string[] {
+	if (requestedNames.size === 0 || ancestorFlowStack.length === 0) return [];
+	const stackSet = new Set(ancestorFlowStack);
+	return Array.from(requestedNames).filter((name) => stackSet.has(name));
+}
+
+function getRequestedProjectFlows(
+	flows: FlowConfig[],
+	requestedNames: Set<string>,
+): FlowConfig[] {
+	return Array.from(requestedNames)
+		.map((name) => flows.find((f) => f.name === name.toLowerCase()))
+		.filter((f): f is FlowConfig => f?.source === "project");
+}
+
+async function confirmProjectFlowsIfNeeded(
+	projectFlows: FlowConfig[],
+	projectFlowsDir: string | null,
+	hasUI: boolean,
+	uiConfirm: (title: string, body: string) => Promise<boolean>,
+): Promise<{ ok: boolean; blocked?: string }> {
+	if (projectFlows.length === 0) return { ok: true };
+
+	const names = projectFlows.map((f) => f.name).join(", ");
+	const dir = projectFlowsDir ?? "(unknown)";
+
+	if (hasUI) {
+		const ok = await uiConfirm(
+			"Run project-local flows?",
+			`Flows: ${names}\nSource: ${dir}\n\nProject flows are repo-controlled. Only continue for trusted repositories.`,
+		);
+		return { ok };
+	}
+
+	return {
+		ok: false,
+		blocked: `Blocked: project-local flow confirmation required in non-UI mode.\nFlows: ${names}\nRe-run with confirmProjectFlows: false if trusted.`,
+	};
+}
+
+function shouldFailover(result: SingleResult): boolean {
+	if (result.stopReason === "aborted") return false;
+	const text = `${result.errorMessage ?? ""}\n${result.stderr ?? ""}`.toLowerCase();
+	if (!text.trim()) return false;
+	if (text.includes("permission") || text.includes("invalid tool") || text.includes("bad settings")) {
+		return false;
+	}
+	return result.exitCode > 0;
+}
+
+// ---------------------------------------------------------------------------
+// FlowExecutor
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a set of flow tasks with full orchestration: cycle detection,
+ * project confirmation, parallel execution with model failover, hook
+ * invocation, auto-transition, and telemetry.
+ */
+export async function executeFlows(
+	deps: FlowExecutorDeps,
+	params: ExecuteFlowParams[],
+	toolCallId: string,
+): Promise<ExecuteFlowResult> {
+	const {
+		flows, currentDepth, maxDepth, ancestorFlowStack, preventCycles,
+		toolOptimize, structuredOutput, cwd, loadedFlowModelConfigs,
+		maxConcurrency, autoTransition, signal, onUpdate, makeDetails,
+		getFlag, tierOverrideResolver, fallbackModel, forkSessionSnapshotJsonl,
+		flowResultCache, projectFlowsDir, hasUI, uiConfirm, onFlowMetrics,
+		confirmProjectFlows,
+	} = deps;
+
+	const requested = new Set<string>(params.map((f) => f.type.toLowerCase()));
+
+	// Cycle check
+	if (preventCycles) {
+		const violations = getFlowCycleViolations(requested, ancestorFlowStack);
+		if (violations.length > 0) {
+			const stack = ancestorFlowStack.join(" -> ") || "(root)";
+			return {
+				content: [{
+					type: "text",
+					text: `Blocked: cycle detected. Flow(s) in stack: ${violations.join(", ")}\nStack: ${stack}`,
+				}],
+				details: makeDetails([]),
+				isError: true,
+			};
+		}
+	}
+
+	// Project flow confirmation
+	const projectFlows = getRequestedProjectFlows(flows, requested);
+	if (projectFlows.length > 0 && confirmProjectFlows !== false) {
+		const { ok, blocked } = await confirmProjectFlowsIfNeeded(projectFlows, projectFlowsDir, hasUI, uiConfirm);
+		if (!ok) {
+			return {
+				content: [{ type: "text", text: blocked ?? "Canceled: project-local flows not approved." }],
+				details: makeDetails([]),
+				isError: !blocked,
+			};
+		}
+	}
+
+	// Resolve model strategy
+	const cliFlowModelConfig =
+		typeof getFlag("flow-model-config") === "string"
+			? (getFlag("flow-model-config") as string)
+			: undefined;
+	const selectedFlowModelConfig = selectFlowModelStrategy(
+		loadedFlowModelConfigs.configs,
+		cliFlowModelConfig ?? loadedFlowModelConfigs.selectedName,
+	);
+
+	// Pre-allocate results array
+	const allResults: SingleResult[] = new Array(params.length);
+	for (let i = 0; i < params.length; i++) {
+		allResults[i] = {
+			type: params[i].type,
+			agentSource: "unknown",
+			intent: params[i].intent,
+			aim: params[i].aim,
+			exitCode: -1,
+			messages: [],
+			stderr: "",
+			usage: emptyFlowUsage(),
+		};
+	}
+
+	// Streaming progress
+	let lastStreamingText = "";
+	let lastEmittedSignature: string | undefined;
+	const emitProgress = (streamingText?: string) => {
+		if (!onUpdate) return;
+		if (streamingText !== undefined) lastStreamingText = streamingText;
+		const text = lastStreamingText || "";
+		const signature =
+			text +
+			"|" +
+			allResults
+				.map(
+					(r) =>
+						`${r.messages.length}:${r.usage.toolCalls}:${r.usage.input}:${r.usage.output}:${r.usage.contextTokens}:${r.usage.smoothedTps ?? 0}:${r.errorMessage ?? ""}`,
+				)
+				.join(";");
+		if (signature === lastEmittedSignature) return;
+		lastEmittedSignature = signature;
+		onUpdate({
+			content: [{ type: "text", text }],
+			details: makeDetails([...allResults]),
+		});
+	};
+
+	if (onUpdate) emitProgress();
+
+	// Execute all flows in parallel
+	const executionStart = Date.now();
+	const results = await mapFlowConcurrent(params, maxConcurrency, async (item, index) => {
+		const normalizedType = item.type.toLowerCase();
+		const targetFlow = flows.find((f) => f.name === normalizedType);
+		const effectiveMaxDepth =
+			targetFlow?.maxDepth !== undefined ? targetFlow.maxDepth : maxDepth;
+
+		const shouldInheritContext = targetFlow?.inheritContext !== false;
+		const tier = targetFlow?.tier ?? "flash";
+		const { candidates } = resolveFlowModelCandidates({
+			tier,
+			flowModel: targetFlow?.model,
+			cliTierOverride: tierOverrideResolver(tier),
+			strategy: selectedFlowModelConfig.strategy,
+			fallbackModel,
+		});
+		const attemptModels = candidates.length > 0 ? candidates : [undefined];
+		const attemptedModels: string[] = [];
+		let result = allResults[index];
+		const flowStart = Date.now();
+
+		for (let attempt = 0; attempt < attemptModels.length; attempt++) {
+			const candidateModel = attemptModels[attempt];
+			if (candidateModel) attemptedModels.push(candidateModel);
+			result = await runFlow({
+				cwd,
+				flows,
+				flowName: normalizedType,
+				intent: item.intent,
+				aim: item.aim,
+				taskCwd: item.cwd,
+				forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
+				parentDepth: currentDepth,
+				parentFlowStack: ancestorFlowStack,
+				maxDepth: effectiveMaxDepth,
+				preventCycles,
+				toolOptimize,
+				structuredOutput,
+				model: candidateModel,
+				signal,
+				onUpdate: (partial) => {
+					if (partial.details?.results[0]) {
+						allResults[index] = partial.details.results[0];
+						emitProgress(partial.content?.[0]?.text);
+					}
+				},
+				makeDetails,
+			});
+			allResults[index] = result;
+			emitProgress();
+			if (isFlowSuccess(result) || signal?.aborted) break;
+			if (attempt < attemptModels.length - 1 && shouldFailover(result)) {
+				continue;
+			}
+			break;
+		}
+
+		if (result && !isFlowSuccess(result) && attemptedModels.length > 1) {
+			const summary = `Model failover attempts: ${attemptedModels.join(" -> ")}`;
+			const baseStderr = result.stderr.trim();
+			result.stderr = baseStderr ? `${baseStderr}\n\n${summary}` : summary;
+			allResults[index] = result;
+			emitProgress();
+		}
+
+		// Telemetry for individual flow
+		if (onFlowMetrics) {
+			const flowDuration = Date.now() - flowStart;
+			onFlowMetrics({
+				type: normalizedType,
+				durationMs: flowDuration,
+				exitCode: result.exitCode,
+				success: isFlowSuccess(result),
+				model: result.model,
+				failoverCount: Math.max(0, attemptedModels.length - 1),
+				usage: result.usage,
+				source: result.agentSource,
+				depth: currentDepth + 1,
+			});
+		}
+
+		return result;
+	});
+
+	// Cache flow results
+	for (const result of results) {
+		const so = result.structuredOutput;
+		if (!so) continue;
+		const compressed: CompressedFlowResult = {
+			type: result.type,
+			status: isFlowError(result) ? "failed" : "accomplished",
+		};
+		if (so.files.length > 0) compressed.files = so.files;
+		if (so.commands.length > 0) compressed.commands = so.commands;
+		if (result.errorMessage) compressed.error = result.errorMessage;
+		const existing = flowResultCache.get(toolCallId) ?? [];
+		existing.push(compressed);
+		flowResultCache.set(toolCallId, existing);
+	}
+
+	// Build tool result
+	const successCount = results.filter((r) => isFlowSuccess(r)).length;
+	const flowReports = results.map((r) => {
+		const output = getFlowSummaryText(r);
+		const status = isFlowError(r) ? "failed" : "accomplished";
+		return `flow [${r.type}] ${status}\n\n${output}`;
+	});
+
+	// Post-flow hooks
+	const hookResult: RunHooksResult = runHooksDetailed(params, results);
+	const advisorBlock = hookResult.advisors.length > 0
+		? "\n\n---\n\n💡 " + hookResult.advisors.join("\n💡 ")
+		: "";
+
+	// Auto-transition: collect qualifying transitions
+	const queuedTransitions: Array<{ type: string; intent: string }> = [];
+	if (autoTransition && hookResult.autoTransitions.length > 0) {
+		for (const transition of hookResult.autoTransitions) {
+			if (transition.confidence >= 0.7) {
+				const normalizedType = transition.type.toLowerCase();
+				const flowExists = flows.some((f) => f.name === normalizedType);
+				const notAlreadyRequested = !requested.has(normalizedType);
+				const noCycles = !preventCycles || !ancestorFlowStack.includes(normalizedType);
+				if (flowExists && notAlreadyRequested && noCycles) {
+					queuedTransitions.push({
+						type: transition.type,
+						intent: transition.intent,
+					});
+				}
+			}
+		}
+	}
+
+	return {
+		content: [{
+			type: "text" as const,
+			text: `Flow: ${successCount}/${results.length} completed\n\n${flowReports.join("\n\n---\n\n")}${advisorBlock}`,
+		}],
+		details: makeDetails(results),
+		autoTransitions: queuedTransitions.length > 0 ? queuedTransitions : undefined,
+	};
+}

package/src/flow.ts

@@ -11,7 +11,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import { type FlowConfig } from "./agents.js";
-import { parseFlowCliArgs } from "./cli-args.js";
+import { getInheritedCliArgs } from "./cli-args.js";
 import { processFlowJsonLine, drainStreamingText, drainStreamingEstimate, drainCtxEstimate, updateSmoothedTps, drainSmoothedTps } from "./runner-events.js";
 import {
 	type SingleResult,
@@ -102,7 +102,7 @@ function cleanupFlowTempDir(dir: string | null): void {
 // Build pi CLI arguments (fork-only)
 // ---------------------------------------------------------------------------
 
-const inheritedCliArgs = parseFlowCliArgs(process.argv);
+const inheritedCliArgs = getInheritedCliArgs();
 
 /**
  * Transform a flow's tool list when toolOptimize is enabled.
@@ -167,19 +167,20 @@ function buildFlowArgs(
 	if (thinking) args.push("--thinking", thinking);
 
 	// Child flows get their configured tools from flow.tools, optimized by
-	// getOptimizedTools, with web explicitly filtered out.
-	// When flow.tools is undefined and toolOptimize=true, default to batch+bash+web
-	// (flow is unnecessary since the child is already inside a flow).
-	// When toolOptimize=false, include batch and web alongside legacy tools.
+	// Child flows cannot browse or search the web — they work with whatever
+	// context the parent provides in the intent. `web` is always stripped.
 	const defaultTools = toolOptimize
-		? ["batch", "bash", "web"]
-		: ["read", "write", "edit", "batch", "bash", "flow", "web"];
+		? ["batch", "bash"]
+		: ["read", "write", "edit", "batch", "bash", "flow"];
+	// getOptimizedTools replaces legacy read/write/edit with batch when
+	// toolOptimize is on. The result may still include `web` if the flow's
+	// frontmatter explicitly lists it, so we filter here.
 	const optimizedTools = getOptimizedTools(flow.tools, toolOptimize) ?? defaultTools;
 	let harnessTools = optimizedTools.filter((t) => t !== "web");
-	// If the flow explicitly listed only "web" (or nothing after filtering),
-	// fall back to defaultTools so the child isn't orphaned with zero tools.
+	// If the flow explicitly listed only tools that got filtered (e.g. just
+	// "web"), fall back to defaultTools so the child isn't orphaned.
 	if (harnessTools.length === 0) {
-		harnessTools = defaultTools.filter((t) => t !== "web");
+		harnessTools = [...defaultTools];
 	}
 	args.push("--tools", harnessTools.join(","));
 

package/src/hooks.ts

@@ -7,6 +7,7 @@
 
 import {
 	type PostFlowHook,
+	type AutoTransition,
 	type SingleResult,
 	isFlowSuccess,
 } from "./types.js";
@@ -27,15 +28,34 @@ export function registerHook(hook: PostFlowHook): void {
 	else hooks.push(hook);
 }
 
+export interface RunHooksResult {
+	/** Advisory messages sorted by priority. */
+	advisors: string[];
+	/** Auto-transitions collected from hooks, sorted by confidence descending. */
+	autoTransitions: AutoTransition[];
+}
+
 /**
  * Run all registered hooks against the given flow results.
- * Returns an array of advisory strings sorted by priority.
+ * Returns advisory strings sorted by priority and auto-transitions.
  */
 export function runHooks(
 	params: Array<{ type: string; intent: string }>,
 	results: SingleResult[],
 ): string[] {
+	const raw = runHooksDetailed(params, results);
+	return raw.advisors;
+}
+
+/**
+ * Run all hooks and return both advisors and auto-transitions.
+ */
+export function runHooksDetailed(
+	params: Array<{ type: string; intent: string }>,
+	results: SingleResult[],
+): RunHooksResult {
 	const messages: Array<{ priority: number; content: string }> = [];
+	const transitions: AutoTransition[] = [];
 
 	for (const hook of hooks) {
 		const triggerTypes = new Set(
@@ -50,11 +70,25 @@ export function runHooks(
 		const result = hook.action({ results: matching, params });
 		if (result) {
 			messages.push({ priority: result.priority ?? 0, content: result.content });
+			if (result.autoTransition) {
+				transitions.push(result.autoTransition);
+			}
 		}
 	}
 
 	messages.sort((a, b) => a.priority - b.priority);
-	return messages.map((m) => m.content);
+	transitions.sort((a, b) => b.confidence - a.confidence);
+	return {
+		advisors: messages.map((m) => m.content),
+		autoTransitions: transitions,
+	};
+}
+
+/**
+ * Get a snapshot of all registered hooks. For introspection and plugin API.
+ */
+export function getRegisteredHooks(): PostFlowHook[] {
+	return [...hooks];
 }
 
 /**
@@ -121,3 +155,79 @@ registerHook({
 		};
 	},
 });
+
+// ---------------------------------------------------------------------------
+// Extended transition hooks
+// ---------------------------------------------------------------------------
+
+/** Suggest build or debug flow after a successful scout flow. */
+registerHook({
+	name: "pi-agent-flow/scout-to-build",
+	trigger: { flowTypes: ["scout"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const alreadyRequested = ctx.params.some(
+			(p) => ["build", "debug"].includes(p.type.toLowerCase()),
+		);
+		if (alreadyRequested) return null;
+
+		return {
+			content:
+				"Context mapped. Consider running a [build] flow to implement changes, or [debug] if investigating an issue.",
+			priority: 20,
+		};
+	},
+});
+
+/** Suggest build flow after a successful craft flow. */
+registerHook({
+	name: "pi-agent-flow/craft-to-build",
+	trigger: { flowTypes: ["craft"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const buildWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "build",
+		);
+		if (buildWasRequested) return null;
+
+		return {
+			content:
+				"Plan ready. Consider running a [build] flow to implement the design.",
+			priority: 10,
+		};
+	},
+});
+
+/** Suggest craft or build flow after a successful ideas flow. */
+registerHook({
+	name: "pi-agent-flow/ideas-to-craft",
+	trigger: { flowTypes: ["ideas"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const alreadyRequested = ctx.params.some(
+			(p) => ["craft", "build"].includes(p.type.toLowerCase()),
+		);
+		if (alreadyRequested) return null;
+
+		return {
+			content:
+				"Ideas explored. Consider running a [craft] flow to design the approach, or [build] to implement directly.",
+			priority: 15,
+		};
+	},
+});
+
+/** Suggest audit flow after a successful debug flow. */
+registerHook({
+	name: "pi-agent-flow/debug-to-audit",
+	trigger: { flowTypes: ["debug"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const auditWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "audit",
+		);
+		if (auditWasRequested) return null;
+
+		return {
+			content:
+				"Root cause identified. Consider running an [audit] flow to verify the fix area for related issues.",
+			priority: 20,
+		};
+	},
+});