pi-agent-flow 1.0.8 → 1.2.0

package/index.ts

@@ -1,645 +0,0 @@
-/**
- * Pi Flow Extension (fork-only)
- *
- * Delegates tasks to specialized flow states running as isolated pi processes.
- * Each flow receives a forked snapshot of the current session context.
- */
-
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
-import { type FlowConfig, discoverFlows } from "./agents.js";
-import { loadFlowModels, type FlowModelConfig } from "./config.js";
-import { renderFlowCall, renderFlowResult } from "./render.js";
-import { getFlowSummaryText } from "./runner-events.js";
-import { runHooks } from "./hooks.js";
-import { mapFlowConcurrent, runFlow } from "./flow.js";
-import {
-	type SingleResult,
-	type FlowDetails,
-	emptyFlowUsage,
-	isFlowError,
-	isFlowSuccess,
-} from "./types.js";
-
-// ---------------------------------------------------------------------------
-// Limits
-// ---------------------------------------------------------------------------
-
-const DEFAULT_MAX_DELEGATION_DEPTH = 3;
-const DEFAULT_PREVENT_CYCLE_DELEGATION = true;
-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";
-
-// ---------------------------------------------------------------------------
-// Tool parameter schema
-// ---------------------------------------------------------------------------
-
-const FlowItem = Type.Object({
-	type: Type.String({
-		description: "Flow type. Matching is case-insensitive. Must correspond to an available flow name such as explore, debug, code, architect, review, or brainstorm.",
-	}),
-	intent: Type.String({
-		description: "Clear, specific mission for this flow.",
-	}),
-	cwd: Type.Optional(
-		Type.String({ description: "Working directory override for this flow." }),
-	),
-});
-
-const FlowParams = Type.Object({
-	flow: Type.Array(FlowItem, {
-		description:
-			"Array of flow tasks to execute. Each runs in its own forked process. " +
-			'Example: { flow: [{ type: "explore", "intent": "Find auth code" }, { type: "code", "intent": "Fix bug" }] }',
-		minItems: 1,
-	}),
-	confirmProjectFlows: Type.Optional(
-		Type.Boolean({
-			description: "Whether to prompt the user before running project-local flows. Default: true.",
-			default: true,
-		}),
-	),
-});
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-interface FlowDepthConfig {
-	currentDepth: number;
-	maxDepth: number;
-	canDelegate: boolean;
-	ancestorFlowStack: string[];
-	preventCycles: boolean;
-}
-
-interface SessionSnapshotSource {
-	getHeader: () => unknown;
-	getBranch: () => unknown[];
-}
-
-function buildForkSessionSnapshotJsonl(
-	sessionManager: SessionSnapshotSource,
-): string | null {
-	const header = sessionManager.getHeader();
-	if (!header || typeof header !== "object") return null;
-
-	const branchEntries = sessionManager.getBranch();
-
-	// Trim the current conversation turn from the fork.
-	let trimFrom = branchEntries.length;
-	for (let i = branchEntries.length - 1; i >= 0; i--) {
-		const entry = branchEntries[i] as Record<string, unknown>;
-		if (entry?.type === "message") {
-			const msg = entry.message as Record<string, unknown> | undefined;
-			if (msg?.role === "user") {
-				trimFrom = i;
-				break;
-			}
-		}
-	}
-
-	const trimmedEntries = branchEntries.slice(0, trimFrom);
-	const lines = [JSON.stringify(header)];
-	for (const entry of trimmedEntries) lines.push(JSON.stringify(entry));
-	return `${lines.join("\n")}\n`;
-}
-
-function parseNonNegativeInt(raw: unknown): number | null {
-	if (typeof raw !== "string") return null;
-	const trimmed = raw.trim();
-	if (!/^\d+$/.test(trimmed)) return null;
-	const parsed = Number(trimmed);
-	return Number.isSafeInteger(parsed) ? parsed : null;
-}
-
-function parseBoolean(raw: unknown): boolean | null {
-	if (typeof raw === "boolean") return raw;
-	if (typeof raw !== "string") return null;
-	const normalized = raw.trim().toLowerCase();
-	if (["1", "true", "yes", "on"].includes(normalized)) return true;
-	if (["0", "false", "no", "off"].includes(normalized)) return false;
-	return null;
-}
-
-function parseFlowStack(raw: unknown): string[] | null {
-	if (raw === undefined) return [];
-	if (typeof raw !== "string") return null;
-	if (!raw.trim()) return [];
-
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-
-	if (!Array.isArray(parsed)) return null;
-	if (!parsed.every((value) => typeof value === "string")) return null;
-	return parsed
-		.map((value) => value.trim().toLowerCase())
-		.filter((value) => value.length > 0);
-}
-
-function getMaxDepthFlagFromArgv(argv: string[]): string | null {
-	for (let i = 2; i < argv.length; i++) {
-		const arg = argv[i];
-		if (arg === "--flow-max-depth") {
-			return argv[i + 1] ?? "";
-		}
-		if (arg.startsWith("--flow-max-depth=")) {
-			return arg.slice("--flow-max-depth=".length);
-		}
-	}
-	return null;
-}
-
-function getPreventCyclesFlagFromArgv(
-	argv: string[],
-): string | boolean | null {
-	for (let i = 2; i < argv.length; i++) {
-		const arg = argv[i];
-		if (arg === "--flow-prevent-cycles") {
-			const maybeValue = argv[i + 1];
-			if (maybeValue !== undefined && !maybeValue.startsWith("--")) {
-				return maybeValue;
-			}
-			return true;
-		}
-		if (arg === "--no-flow-prevent-cycles") return false;
-		if (arg.startsWith("--flow-prevent-cycles=")) {
-			return arg.slice("--flow-prevent-cycles=".length);
-		}
-	}
-	return null;
-}
-
-function resolveFlowDepthConfig(pi: ExtensionAPI): FlowDepthConfig {
-	const depthRaw = process.env[FLOW_DEPTH_ENV];
-	const parsedDepth = parseNonNegativeInt(depthRaw);
-	if (depthRaw !== undefined && parsedDepth === null) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid ${FLOW_DEPTH_ENV}="${depthRaw}". Expected a non-negative integer.`,
-		);
-	}
-	const currentDepth = parsedDepth ?? 0;
-
-	const stackRaw = process.env[FLOW_STACK_ENV];
-	const ancestorFlowStack = parseFlowStack(stackRaw);
-	if (stackRaw !== undefined && ancestorFlowStack === null) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid ${FLOW_STACK_ENV} value. Expected a JSON array of flow names.`,
-		);
-	}
-
-	const envMaxDepthRaw = process.env[FLOW_MAX_DEPTH_ENV];
-	const envMaxDepth = parseNonNegativeInt(envMaxDepthRaw);
-	if (envMaxDepthRaw !== undefined && envMaxDepth === null) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid ${FLOW_MAX_DEPTH_ENV}="${envMaxDepthRaw}". Expected a non-negative integer.`,
-		);
-	}
-
-	const argvFlagRaw = getMaxDepthFlagFromArgv(process.argv);
-	const argvFlagMaxDepth =
-		argvFlagRaw !== null ? parseNonNegativeInt(argvFlagRaw) : null;
-	if (argvFlagRaw !== null && argvFlagMaxDepth === null) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid --flow-max-depth value "${argvFlagRaw}". Expected a non-negative integer.`,
-		);
-	}
-
-	const runtimeFlagValue = pi.getFlag("flow-max-depth");
-	const runtimeFlagMaxDepth =
-		typeof runtimeFlagValue === "string"
-			? parseNonNegativeInt(runtimeFlagValue)
-			: null;
-	if (
-		argvFlagRaw === null &&
-		typeof runtimeFlagValue === "string" &&
-		runtimeFlagMaxDepth === null
-	) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid --flow-max-depth value "${runtimeFlagValue}". Expected a non-negative integer.`,
-		);
-	}
-
-	const envPreventCyclesRaw = process.env[FLOW_PREVENT_CYCLES_ENV];
-	const envPreventCycles = parseBoolean(envPreventCyclesRaw);
-	if (envPreventCyclesRaw !== undefined && envPreventCycles === null) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid ${FLOW_PREVENT_CYCLES_ENV}="${envPreventCyclesRaw}". Expected true/false.`,
-		);
-	}
-
-	const argvPreventCyclesRaw = getPreventCyclesFlagFromArgv(process.argv);
-	const argvPreventCycles =
-		typeof argvPreventCyclesRaw === "boolean"
-			? argvPreventCyclesRaw
-			: parseBoolean(argvPreventCyclesRaw);
-	if (
-		typeof argvPreventCyclesRaw === "string" &&
-		argvPreventCycles === null
-	) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid --flow-prevent-cycles value "${argvPreventCyclesRaw}". Expected true/false.`,
-		);
-	}
-
-	const runtimePreventCyclesRaw = pi.getFlag("flow-prevent-cycles");
-	const runtimePreventCycles = parseBoolean(runtimePreventCyclesRaw);
-	if (
-		argvPreventCyclesRaw === null &&
-		runtimePreventCyclesRaw !== undefined &&
-		runtimePreventCycles === null
-	) {
-		console.warn(
-			`[pi-agent-flow] Ignoring invalid --flow-prevent-cycles value "${String(runtimePreventCyclesRaw)}". Expected true/false.`,
-		);
-	}
-
-	const flagMaxDepth = argvFlagMaxDepth ?? runtimeFlagMaxDepth;
-	const maxDepth = flagMaxDepth ?? envMaxDepth ?? DEFAULT_MAX_DELEGATION_DEPTH;
-	const preventCycles =
-		argvPreventCycles ??
-		runtimePreventCycles ??
-		envPreventCycles ??
-		DEFAULT_PREVENT_CYCLE_DELEGATION;
-
-	return {
-		currentDepth,
-		maxDepth,
-		canDelegate: currentDepth < maxDepth,
-		ancestorFlowStack: ancestorFlowStack ?? [],
-		preventCycles,
-	};
-}
-
-function makeFlowDetailsFactory(projectFlowsDir: string | null) {
-	return (results: SingleResult[]): FlowDetails => ({
-		mode: "flow",
-		delegationMode: "fork",
-		projectAgentsDir: projectFlowsDir,
-		results,
-	});
-}
-
-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));
-}
-
-/** Get project-local flows referenced by the current request. */
-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");
-}
-
-/**
- * Prompt the user to confirm project-local flows if needed.
- * Returns false if the user declines.
- */
-async function confirmProjectFlowsIfNeeded(
-	projectFlows: FlowConfig[],
-	projectFlowsDir: string | null,
-	ctx: { ui: { confirm: (title: string, body: string) => Promise<boolean> } },
-): Promise<boolean> {
-	if (projectFlows.length === 0) return true;
-
-	const names = projectFlows.map((f) => f.name).join(", ");
-	const dir = projectFlowsDir ?? "(unknown)";
-	return ctx.ui.confirm(
-		"Run project-local flows?",
-		`Flows: ${names}\nSource: ${dir}\n\nProject flows are repo-controlled. Only continue for trusted repositories.`,
-	);
-}
-
-// ---------------------------------------------------------------------------
-// Reminder flow injection (sliding — always on latest user message)
-// ---------------------------------------------------------------------------
-
-const REMINDER_TEXT =
-	"\n\n[reminder_flow: If the answer is in context, reply; otherwise, delegate to the appropriate flow.]";
-
-function stripReminder(
-	content: string | { type: string; text?: string }[],
-): string | { type: string; text?: string }[] {
-	if (typeof content === "string") {
-		return content.replace(REMINDER_TEXT, "");
-	}
-	return content.map((c) => {
-		if (c.type === "text" && typeof c.text === "string") {
-			return { ...c, text: c.text.replace(REMINDER_TEXT, "") };
-		}
-		return c;
-	});
-}
-
-function appendReminder(
-	content: string | { type: string; text?: string }[],
-): string | { type: string; text?: string }[] {
-	if (typeof content === "string") {
-		return content + REMINDER_TEXT;
-	}
-	const copy = [...content];
-	const lastTextIdx = copy.map((c, i) => (c.type === "text" ? i : -1)).filter((i) => i !== -1).pop();
-	if (lastTextIdx === undefined) {
-		copy.push({ type: "text", text: REMINDER_TEXT });
-	} else {
-		const block = copy[lastTextIdx] as { type: "text"; text: string };
-		copy[lastTextIdx] = { ...block, text: block.text + REMINDER_TEXT };
-	}
-	return copy;
-}
-
-// ---------------------------------------------------------------------------
-// Extension entry point
-// ---------------------------------------------------------------------------
-
-export default function (pi: ExtensionAPI) {
-	pi.registerFlag("flow-max-depth", {
-		description: "Maximum allowed flow delegation depth (default: 3).",
-		type: "string",
-	});
-	pi.registerFlag("flow-prevent-cycles", {
-		description: "Block delegating to flows already in the current delegation stack (default: true).",
-		type: "boolean",
-	});
-	pi.registerFlag("flow-lite-model", {
-		description: "Model for lite-tier flows (explore, debug).",
-		type: "string",
-	});
-	pi.registerFlag("flow-flash-model", {
-		description: "Model for flash-tier flows (code, review).",
-		type: "string",
-	});
-	pi.registerFlag("flow-full-model", {
-		description: "Model for full-tier flows (brainstorm, architect).",
-		type: "string",
-	});
-
-	const depthConfig = resolveFlowDepthConfig(pi);
-	const { currentDepth, maxDepth, canDelegate, ancestorFlowStack, preventCycles } =
-		depthConfig;
-
-	let discoveredFlows: FlowConfig[] = [];
-	let flowModelConfig: FlowModelConfig = {};
-
-	// Auto-discover flows on session start
-	pi.on("session_start", async (_event, ctx) => {
-		if (!canDelegate) return;
-
-		const discovery = discoverFlows(ctx.cwd, "all");
-		discoveredFlows = discovery.flows;
-		flowModelConfig = loadFlowModels(ctx.cwd);
-	});
-
-	// Inject available flows into the system prompt
-	pi.on("before_agent_start", async (event) => {
-		if (!canDelegate) return;
-		if (discoveredFlows.length === 0) return;
-
-		return {
-			systemPrompt:
-				event.systemPrompt +
-				`\n\n## Flows
-
-Before acting, reason about whether to dive into a flow:
-
-- [explore] — when you need to understand first. Find files, trace code paths, map architecture.
-- [debug] — when something is broken. Investigate logs, errors, stack traces to find root cause.
-- [code] — when you are ready to build. Implement features, fix bugs, write tests.
-- [architect] — when you need a plan. Design structure, break down requirements before building.
-- [review] — when you need to verify. Audit security, quality, correctness.
-- [brainstorm] — when you need fresh ideas. Start from a clean slate with only the intent.
-
-Multiple independent flows? Batch them into one call:
-
-✅ { "flow": [{ "type": "explore", "intent": "..." }, { "type": "review", "intent": "..." }] }
-❌ Two separate calls — wastes time
-
-Each call renders as:
-
-• flow [explore] — Map the full directory structure...
-• flow [review] — Audit security and quality...
-
-Each flow returns:
-
-flow [type] accomplished
-
-[Summary] — what happened
-[Done] — completed with file:line references
-[Not Done] — incomplete items and reasons
-[Next Steps] — recommended follow-up
-
-### Guards
-- Depth: ${currentDepth}/${maxDepth} | Cycles: ${preventCycles ? "blocked" : "off"} | Stack: ${ancestorFlowStack.length > 0 ? ancestorFlowStack.join(" -> ") : "(root)"}
-`,
-		};
-	});
-
-	// Sliding reminder: strip from all earlier user messages, append to latest
-	pi.on("context", async (event) => {
-		const messages = event.messages;
-		const userIndices = messages
-			.map((m, i) => (m.role === "user" ? i : -1))
-			.filter((i) => i !== -1);
-
-		if (userIndices.length === 0) return undefined;
-
-		const lastUserIndex = userIndices[userIndices.length - 1];
-
-		const modified = messages.map((msg, idx) => {
-			if (msg.role !== "user") return msg;
-
-			const content = stripReminder(msg.content);
-			if (idx === lastUserIndex) {
-				return { ...msg, content: appendReminder(content) };
-			}
-			return { ...msg, content };
-		});
-
-		return { messages: modified };
-	});
-
-	// Register the flow tool
-	if (canDelegate) {
-		pi.registerTool({
-			name: "flow",
-			label: "Flow",
-			description: [
-				"If you cannot answer from your current context, you are forbidden from guessing.",
-				"You MUST enter to the following flow states, with tool call method.",
-				"",
-				"Flow states are isolated \u03c0 processes with forked session snapshots. They run in parallel.",
-				'Invoke: { "flow": [{ "type": "explore", "intent": "..." }, ...] }',
-				"States: explore (tanken), debug (kensh\u014d), code (shokunin), architect (keikaku), review (kanshi), brainstorm (mushin).",
-				"Custom states configs in (create if not exists): .md files in .pi/agents/ or ~/.pi/agent/agents/.",
-			].join("\n"),
-			parameters: FlowParams,
-
-			async execute(_toolCallId, params, signal, onUpdate, ctx) {
-				const discovery = discoverFlows(ctx.cwd, "all");
-				const { flows } = discovery;
-				const makeDetails = makeFlowDetailsFactory(discovery.projectFlowsDir);
-
-				// Resolve tiered models: CLI flags override settings.json overrides parent --model
-				const tieredModels = {
-					lite: (pi.getFlag("flow-lite-model") as string | undefined) ?? flowModelConfig.lite,
-					flash: (pi.getFlag("flow-flash-model") as string | undefined) ?? flowModelConfig.flash,
-					full: (pi.getFlag("flow-full-model") as string | undefined) ?? flowModelConfig.full,
-				};
-
-				// Build fork session snapshot (shared across all flows that inherit context)
-				const forkSessionSnapshotJsonl = buildForkSessionSnapshotJsonl(
-					ctx.sessionManager,
-				);
-
-				// Collect all requested flow names
-				const requested = new Set(params.flow.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 shouldConfirm = params.confirmProjectFlows ?? true;
-				if (shouldConfirm) {
-					const projectFlows = getRequestedProjectFlows(flows, requested);
-					if (projectFlows.length > 0) {
-						if (ctx.hasUI) {
-							const ok = await confirmProjectFlowsIfNeeded(projectFlows, discovery.projectFlowsDir, ctx);
-							if (!ok) {
-								return {
-									content: [{ type: "text", text: "Canceled: project-local flows not approved." }],
-									details: makeDetails([]),
-								};
-							}
-						} else {
-							const names = projectFlows.map((f) => f.name).join(", ");
-							return {
-								content: [{
-									type: "text",
-									text: `Blocked: project-local flow confirmation required in non-UI mode.\nFlows: ${names}\nRe-run with confirmProjectFlows: false if trusted.`,
-								}],
-								details: makeDetails([]),
-								isError: true,
-							};
-						}
-					}
-				}
-
-				// Run all flows in parallel
-				const allResults: SingleResult[] = new Array(params.flow.length);
-				for (let i = 0; i < params.flow.length; i++) {
-					allResults[i] = {
-						type: params.flow[i].type,
-						agentSource: "unknown",
-						intent: params.flow[i].intent,
-						exitCode: -1,
-						messages: [],
-						stderr: "",
-						usage: emptyFlowUsage(),
-					};
-				}
-
-				let lastStreamingText = "";
-				let lastEmittedText: string | undefined;
-				const emitProgress = (streamingText?: string) => {
-					if (!onUpdate) return;
-					if (streamingText !== undefined) lastStreamingText = streamingText;
-					const text = lastStreamingText || "";
-					if (text === lastEmittedText) return;
-					lastEmittedText = text;
-					onUpdate({
-						content: [{ type: "text", text }],
-						details: makeDetails([...allResults]),
-					});
-				};
-
-				if (onUpdate) emitProgress();
-
-				const results = await mapFlowConcurrent(params.flow, 4, 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 result = await runFlow({
-						cwd: ctx.cwd,
-						flows,
-						flowName: normalizedType,
-						intent: item.intent,
-						taskCwd: item.cwd,
-						forkSessionSnapshotJsonl: shouldInheritContext ? forkSessionSnapshotJsonl : null,
-						parentDepth: currentDepth,
-						parentFlowStack: ancestorFlowStack,
-						maxDepth: effectiveMaxDepth,
-						preventCycles,
-						tieredModels,
-						signal,
-						onUpdate: (partial) => {
-							if (partial.details?.results[0]) {
-								allResults[index] = partial.details.results[0];
-								emitProgress(partial.content?.[0]?.text);
-							}
-						},
-						makeDetails,
-					});
-					allResults[index] = result;
-					emitProgress();
-					return result;
-				});
-
-				// Build tool result with FULL flow output — no truncation
-				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 — inject advisory messages
-				const advisors = runHooks(params.flow, results);
-				const advisorBlock = advisors.length > 0
-					? "\n\n---\n\n💡 " + advisors.join("\n💡 ")
-					: "";
-
-				return {
-					content: [{
-						type: "text" as const,
-						text: `Flow: ${successCount}/${results.length} completed\n\n${flowReports.join("\n\n---\n\n")}${advisorBlock}`,
-					}],
-					details: makeDetails(results),
-				};
-			},
-
-			renderCall: (args, theme) => renderFlowCall(args, theme),
-			renderResult: (result, { expanded }, theme, args) =>
-				renderFlowResult(result, expanded, theme, args),
-		});
-	}
-}