pi-agent-flow 1.8.1 → 1.8.3

package/src/hooks.ts

@@ -1,294 +0,0 @@
-/**
- * Post-flow hook registry.
- *
- * Hooks inject advisory messages into flow tool results after execution.
- * Built-in hooks fire automatically; user hooks can be registered via `registerHook()`.
- */
-
-import {
-	type PostFlowHook,
-	type AutoTransition,
-	type SingleResult,
-	isFlowSuccess,
-} from "./types.js";
-
-// ---------------------------------------------------------------------------
-// Module-scoped hook registry
-// ---------------------------------------------------------------------------
-
-const hooks: PostFlowHook[] = [];
-
-/**
- * Register or replace a hook by name.
- * If a hook with the same name already exists, it is replaced.
- */
-export function registerHook(hook: PostFlowHook): void {
-	const idx = hooks.findIndex((h) => h.name === hook.name);
-	if (idx >= 0) hooks[idx] = hook;
-	else hooks.push(hook);
-}
-
-/**
- * Unregister a hook by name.
- * Returns true if a hook was removed, false if no hook with that name existed.
- */
-export function unregisterHook(name: string): boolean {
-	const idx = hooks.findIndex((h) => h.name === name);
-	if (idx < 0) return false;
-	hooks.splice(idx, 1);
-	return true;
-}
-
-export interface RunHooksResult {
-	/** Advisory messages sorted by priority. */
-	advisors: string[];
-	/** Auto-transitions collected from hooks. */
-	autoTransitions: AutoTransition[];
-}
-
-/**
- * Run all registered hooks against the given flow results.
- * 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.
- *
- * Each hook action is wrapped in try/catch so one bad hook cannot crash
- * the pipeline. Failures are reported as advisory warnings.
- */
-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(
-			hook.trigger.flowTypes.map((t) => t.toLowerCase()),
-		);
-		const onlyOnSuccess = hook.trigger.onlyOnSuccess !== false;
-
-		const matching = results.filter((r) => triggerTypes.has(r.type));
-		if (matching.length === 0) continue;
-		if (onlyOnSuccess && !matching.every((r) => isFlowSuccess(r))) continue;
-
-		try {
-			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);
-				}
-			}
-		} catch (err) {
-			const errorMessage = err instanceof Error ? err.message : String(err);
-			messages.push({
-				priority: 999,
-				content: `Hook "${hook.name}" failed: ${errorMessage}`,
-			});
-		}
-	}
-
-	messages.sort((a, b) => a.priority - b.priority);
-	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];
-}
-
-/**
- * Clear all registered hooks. For testing only.
- */
-export function clearHooks(): void {
-	hooks.length = 0;
-}
-
-// ---------------------------------------------------------------------------
-// Built-in hooks — success transitions
-// ---------------------------------------------------------------------------
-
-/** Suggest audit flow after a successful build flow. */
-registerHook({
-	name: "pi-agent-flow/build-to-audit",
-	trigger: { flowTypes: ["build"], onlyOnSuccess: true },
-	action: (ctx) => {
-		const auditWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "audit",
-		);
-		if (auditWasRequested) return null;
-
-		return {
-			content:
-				"Consider running a [audit] flow to audit the changes for security, correctness, and code quality.",
-			priority: 10,
-		};
-	},
-});
-
-/** Suggest build flow after a successful debug flow. */
-registerHook({
-	name: "pi-agent-flow/debug-to-build",
-	trigger: { flowTypes: ["debug"], onlyOnSuccess: true },
-	action: (ctx) => {
-		const buildWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "build",
-		);
-		if (buildWasRequested) return null;
-
-		return {
-			content:
-				"The root cause has been identified. Consider running a [build] flow to implement the fix.",
-			priority: 10,
-		};
-	},
-});
-
-/** Suggest scout flow after a successful audit flow. */
-registerHook({
-	name: "pi-agent-flow/audit-to-scout",
-	trigger: { flowTypes: ["audit"], onlyOnSuccess: true },
-	action: (ctx) => {
-		const scoutWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "scout",
-		);
-		if (scoutWasRequested) return null;
-
-		return {
-			content:
-				"Audit complete. Consider running a [scout] flow to trace the audit findings across the codebase.",
-			priority: 15,
-		};
-	},
-});
-
-/** 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,
-		};
-	},
-});
-
-// ---------------------------------------------------------------------------
-// Built-in hooks — failure transitions
-// ---------------------------------------------------------------------------
-
-/** Suggest debug flow after a failed build flow. */
-registerHook({
-	name: "pi-agent-flow/build-to-debug-on-failure",
-	trigger: { flowTypes: ["build"], onlyOnSuccess: false },
-	action: (ctx) => {
-		const allSucceeded = ctx.results.every((r) => isFlowSuccess(r));
-		if (allSucceeded) return null;
-		const debugWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "debug",
-		);
-		if (debugWasRequested) return null;
-
-		return {
-			content:
-				"Build failed. Consider running a [debug] flow to investigate the root cause.",
-			priority: 10,
-		};
-	},
-});
-
-/** Suggest build flow after a failed audit flow (found issues). */
-registerHook({
-	name: "pi-agent-flow/audit-to-build-on-failure",
-	trigger: { flowTypes: ["audit"], onlyOnSuccess: false },
-	action: (ctx) => {
-		const allSucceeded = ctx.results.every((r) => isFlowSuccess(r));
-		if (allSucceeded) return null;
-		const buildWasRequested = ctx.params.some(
-			(p) => p.type.toLowerCase() === "build",
-		);
-		if (buildWasRequested) return null;
-
-		return {
-			content:
-				"Audit found issues. Consider running a [build] flow to fix them.",
-			priority: 10,
-		};
-	},
-});