pi-crew 0.5.2 → 0.5.6

package/src/runtime/chain-runner.ts

@@ -0,0 +1,507 @@
+/**
+ * ChainRunner - Execute sequential chains with `->` syntax support.
+ * 
+ * Based on pi-boomerang's parseChain pattern:
+ * - Parses "teamA -> teamB -> teamC" syntax
+ * - Supports per-step overrides for model, skill, thinking
+ * - Accumulates handoffs between steps
+ * - Executes steps sequentially with context passing
+ * 
+ * @see docs/pi-boomerang-integration-plan.md
+ */
+
+import type { HandoffSummary, HandoffManager, TaskPacket, TaskResult } from "./handoff-manager.ts";
+
+/**
+ * Single step in a chain.
+ */
+export interface ChainStep {
+	/** Step name/identifier */
+	name: string;
+	/** Team to execute (if using team reference) */
+	team?: string;
+	/** Workflow to execute (if using workflow reference) */
+	workflow?: string;
+	/** Template to execute (if using template reference) */
+	template?: string;
+	/** Inline goal text (for literal goals) */
+	inlineGoal?: string;
+
+	/** Per-step model override */
+	model?: string;
+	/** Per-step skill override */
+	skill?: string;
+	/** Thinking mode */
+	thinking?: "fast" | "standard" | "deep";
+
+	/** Step-specific context */
+	context?: Record<string, unknown>;
+	/** Step timeout in milliseconds */
+	timeout?: number;
+
+	/** Whether to continue chain on failure */
+	continueOnError?: boolean;
+}
+
+/**
+ * Parsed chain specification.
+ */
+export interface ChainSpec {
+	/** Ordered steps in the chain */
+	steps: ChainStep[];
+	/** Global arguments applied to all steps */
+	globalArgs?: Record<string, unknown>;
+	/** Global model override */
+	globalModel?: string;
+	/** Global skill override */
+	globalSkill?: string;
+	/** Global thinking mode */
+	globalThinking?: "fast" | "standard" | "deep";
+	/** Continue chain on step failure */
+	continueOnError?: boolean;
+}
+
+/**
+ * Result of a single chain step execution.
+ */
+export interface ChainStepResult {
+	step: number;
+	name: string;
+	outcome: "success" | "failure" | "skipped" | "partial";
+	result?: TaskResult;
+	handoff?: HandoffSummary;
+	duration: number;
+	error?: string;
+}
+
+/**
+ * Final chain execution result.
+ */
+export interface ChainResult {
+	steps: ChainStepResult[];
+	totalDuration: number;
+	success: boolean;
+	/** Total tokens used across all steps */
+	totalTokens?: number;
+	/** All handoffs generated during chain */
+	totalHandoffs: HandoffSummary[];
+}
+
+/**
+ * Task runner interface for chain execution.
+ */
+export interface ChainTaskRunner {
+	runTask(packet: TaskPacket): Promise<TaskResult>;
+}
+
+/**
+ * ChainRunner executes sequential chains with context passing.
+ */
+export class ChainRunner {
+	/** Maximum number of chain history entries to prevent memory leaks */
+	private static readonly MAX_CHAIN_HISTORY_SIZE = 100;
+
+	/** Maximum size per handoff entry to prevent memory issues from large artifacts */
+	private static readonly MAX_HANDOFF_ENTRY_SIZE = 5000; // bytes per entry
+
+	constructor(
+		private taskRunner: ChainTaskRunner,
+		private handoffManager: HandoffManager,
+	) {}
+
+	/**
+	 * Parse chain syntax: step1 -> step2 -> step3
+	 * 
+	 * Supports multiple syntaxes:
+	 * - Team reference: @teamName
+	 * - Workflow reference: workflow:name
+	 * - Template reference: template:name
+	 * - Inline goal: "goal description"
+	 * 
+	 * @example
+	 * parseChain("@research -> @implement -> @review")
+	 * parseChain('"Research AI trends" -> "Analyze findings"')
+	 * parseChain("@step1 --model claude-opus-3 -> @step2")
+	 * 
+	 * @param chainString - The chain string to parse
+	 * @returns Parsed chain specification
+	 */
+	parseChain(chainString: string): ChainSpec {
+		const stepStrings = chainString.split("->").map(s => s.trim());
+
+		const steps: ChainStep[] = stepStrings.map((step, index) => {
+			return this.parseStep(step, index);
+		});
+
+		// Extract global overrides
+		const globalModel = this.extractGlobalFlag(chainString, "global-model");
+		const globalSkill = this.extractGlobalFlag(chainString, "global-skill");
+		const globalThinking = this.extractGlobalFlag(chainString, "global-thinking") as "fast" | "standard" | "deep" | undefined;
+		const continueOnError = this.extractGlobalFlag(chainString, "continue-on-error") === "true";
+
+		return {
+			steps,
+			globalModel,
+			globalSkill,
+			globalThinking,
+			continueOnError,
+		};
+	}
+
+	/**
+	 * Execute chain sequentially.
+	 * Each step receives handoff from previous step.
+	 * 
+	 * @param spec - Parsed chain specification
+	 * @param initialContext - Initial context for the chain
+	 * @param eventsPath - Optional event log path for events
+	 * @returns Final chain result
+	 */
+	async runChain(
+		spec: ChainSpec,
+		initialContext: Record<string, unknown> = {},
+		eventsPath?: string
+	): Promise<ChainResult> {
+		const stepResults: ChainStepResult[] = [];
+		let accumulatedContext = { ...initialContext };
+		const startTime = Date.now();
+		let totalTokens = 0;
+		const allHandoffs: HandoffSummary[] = [];
+
+		for (let i = 0; i < spec.steps.length; i++) {
+			const step = spec.steps[i];
+			const stepStart = Date.now();
+
+			try {
+				// Resolve effective config (step overrides global)
+				const effectiveConfig = this.getEffectiveConfig(step, spec);
+
+				// Enrich context with previous handoffs
+				const stepContext = this.enrichContextFromHandoffs(
+					accumulatedContext,
+					stepResults
+				);
+
+				// Execute step
+				const result = await this.executeStep(effectiveConfig, stepContext);
+
+				// Track tokens
+				if (result.usage?.totalTokens) {
+					totalTokens += result.usage.totalTokens;
+				}
+
+				// Generate handoff for next step
+				const handoff = await this.handoffManager.generateSummary(
+					this.createMinimalPacket(step, i),
+					result
+				);
+
+				stepResults.push({
+					step: i + 1,
+					name: step.name,
+					outcome: result.outcome,
+					result,
+					handoff,
+					duration: Date.now() - stepStart,
+				});
+
+				if (handoff !== null) { allHandoffs.push(handoff); }
+
+				// Update accumulated context on success
+				if (result.outcome === "success") {
+					accumulatedContext = {
+						...accumulatedContext,
+						[`step_${i}_result`]: result,
+						[`step_${i}_handoff`]: handoff,
+					};
+				} else {
+					// Stop chain on step failure unless configured to continue
+					if (!spec.continueOnError && !step.continueOnError) {
+						break;
+					}
+				}
+
+				// Emit progress event if eventsPath provided
+				if (eventsPath) {
+					const { appendEventAsync } = await import("../state/event-log.ts");
+					await appendEventAsync(eventsPath, {
+						type: "chain.step_completed",
+						runId: "chain",
+						taskId: `step-${i + 1}`,
+						data: {
+							step: i + 1,
+							name: step.name,
+							outcome: result.outcome,
+							duration: Date.now() - stepStart,
+						},
+					});
+				}
+
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : String(error);
+
+				stepResults.push({
+					step: i + 1,
+					name: step.name,
+					outcome: "failure",
+					duration: Date.now() - stepStart,
+					error: errorMessage,
+				});
+
+				// Stop chain on failure unless configured to continue
+				if (!spec.continueOnError && !step.continueOnError) {
+					break;
+				}
+			}
+		}
+
+		return {
+			steps: stepResults,
+			totalDuration: Date.now() - startTime,
+			success: stepResults.every(s => s.outcome !== "failure"),
+			totalTokens: totalTokens > 0 ? totalTokens : undefined,
+			totalHandoffs: allHandoffs,
+		};
+	}
+
+	/**
+	 * Parse a single step from the chain string.
+	 * Includes type safety checks for ChainStep parsing (H3).
+	 */
+	private parseStep(step: string, index: number): ChainStep {
+		// Parse team reference: @teamName
+		const teamMatch = step.match(/^@([a-zA-Z][a-zA-Z0-9_]*)/);
+
+		// Parse workflow reference: workflow:name
+		const workflowMatch = step.match(/^workflow:([a-zA-Z][a-zA-Z0-9_]*)/);
+
+		// Parse template reference: template:name
+		const templateMatch = step.match(/^template:([a-zA-Z][a-zA-Z0-9_]*)/);
+
+		// Parse inline goal: "goal description" (can follow other patterns)
+		const inlineMatch = step.match(/"([^"]{1,10000})"/);
+
+		const nameParts = step.split(/\s+/);
+		const name = (nameParts[0] && nameParts[0].length > 0 && nameParts[0].length <= 100)
+			? nameParts[0]
+			: `step-${index}`;
+
+		const parsed: ChainStep = {
+			name,
+		};
+
+		// Set step type based on matching pattern with type safety
+		if (teamMatch && teamMatch[1]) {
+			parsed.team = this.sanitizeIdentifier(teamMatch[1]);
+		}
+		if (workflowMatch && workflowMatch[1]) {
+			parsed.workflow = this.sanitizeIdentifier(workflowMatch[1]);
+		}
+		if (templateMatch && templateMatch[1]) {
+			parsed.template = this.sanitizeIdentifier(templateMatch[1]);
+		}
+		if (inlineMatch && inlineMatch[1]) {
+			parsed.inlineGoal = this.sanitizeInlineGoal(inlineMatch[1]);
+		}
+
+		// Parse per-step overrides with type safety
+		const modelVal = this.extractFlag(step, "model");
+		if (modelVal && this.isValidModelName(modelVal)) {
+			parsed.model = modelVal;
+		}
+
+		const skillVal = this.extractFlag(step, "skill");
+		if (skillVal && this.isValidIdentifier(skillVal)) {
+			parsed.skill = skillVal;
+		}
+
+		const thinkingVal = this.extractFlag(step, "thinking");
+		if (thinkingVal && this.isValidThinkingMode(thinkingVal)) {
+			parsed.thinking = thinkingVal;
+		}
+
+		// Parse step timeout
+		const timeoutStr = this.extractFlag(step, "timeout");
+		if (timeoutStr) {
+			const timeoutMs = parseInt(timeoutStr, 10);
+			if (!isNaN(timeoutMs) && timeoutMs > 0 && timeoutMs <= 86400000) {
+				parsed.timeout = timeoutMs * 1000; // Convert seconds to ms
+			}
+		}
+
+		// Parse continueOnError for step
+		if (this.extractFlag(step, "continue-on-error") === "true") {
+			parsed.continueOnError = true;
+		}
+
+		return parsed;
+	}
+
+	/**
+	 * Sanitize identifier to prevent injection.
+	 */
+	private sanitizeIdentifier(value: string): string {
+		return value.replace(/[^a-zA-Z0-9_]/g, '_').substring(0, 100);
+	}
+
+	/**
+	 * Sanitize inline goal to prevent injection.
+	 */
+	private sanitizeInlineGoal(value: string): string {
+		// Remove control characters and limit length
+		return value.replace(/[\x00-\x1F\x7F]/g, '').substring(0, 10000);
+	}
+
+	/**
+	 * Validate model name format.
+	 */
+	private isValidModelName(value: string): boolean {
+		return /^[a-zA-Z][a-zA-Z0-9_-]{0,50}$/.test(value);
+	}
+
+	/**
+	 * Validate identifier format.
+	 */
+	private isValidIdentifier(value: string): boolean {
+		return /^[a-zA-Z][a-zA-Z0-9_]{0,50}$/.test(value);
+	}
+
+	/**
+	 * Validate thinking mode value.
+	 */
+	private isValidThinkingMode(value: string): value is "fast" | "standard" | "deep" {
+		return ["fast", "standard", "deep"].includes(value);
+	}
+
+	/**
+	 * Extract a flag from step string.
+	 * Uses escaped flag name to prevent regex injection.
+	 */
+	private extractFlag(input: string, flag: string): string | undefined {
+		// Escape regex special characters in flag name to prevent injection
+		const escapedFlag = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		const match = input.match(new RegExp(`--${escapedFlag}\\s+(\\S+)`));
+		return match?.[1];
+	}
+
+	/**
+	 * Extract a global flag from the chain string.
+	 * Global flags can appear anywhere in the chain string.
+	 * Uses escaped flag name to prevent regex injection.
+	 */
+	private extractGlobalFlag(input: string, flag: string): string | undefined {
+		// Escape regex special characters in flag name to prevent injection
+		const escapedFlag = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		const patternEq = '--' + escapedFlag + '=\\s*(\\S+)';
+		const match = input.match(new RegExp(patternEq, 'i'));
+		if (match) return match[1];
+
+		const patternNoEq = '--' + escapedFlag + '\\s+(\\S+)';
+		const matchNoEq = input.match(new RegExp(patternNoEq, 'i'));
+		if (matchNoEq) return matchNoEq[1];
+
+		return undefined;
+	}
+
+	/**
+	 * Get effective config with step overrides global.
+	 */
+	private getEffectiveConfig(step: ChainStep, spec: ChainSpec): ChainStep {
+		return {
+			...step,
+			model: step.model ?? spec.globalModel,
+			skill: step.skill ?? spec.globalSkill,
+			thinking: step.thinking ?? spec.globalThinking,
+		};
+	}
+
+	/**
+	 * Enrich context with previous handoffs.
+	 * Limits history size to prevent memory leaks.
+	 */
+	private enrichContextFromHandoffs(
+		context: Record<string, unknown>,
+		previousResults: ChainStepResult[]
+	): Record<string, unknown> {
+		const handoffs = previousResults
+			.filter(r => r.handoff)
+			.map(r => r.handoff!);
+
+		if (handoffs.length === 0) {
+			return context;
+		}
+
+		// Limit history size to prevent memory leak (H2)
+		const limitedHandoffs = handoffs.slice(-ChainRunner.MAX_CHAIN_HISTORY_SIZE);
+
+		// Limit per-entry size to prevent memory issues from large artifacts
+		const filteredHandoffs = limitedHandoffs.filter(h => {
+			const size = JSON.stringify(h).length;
+			return size <= ChainRunner.MAX_HANDOFF_ENTRY_SIZE;
+		});
+
+		return {
+			...context,
+			__chainHistory: filteredHandoffs.map(h => ({
+				step: h.taskId,
+				outcome: h.outcome,
+				filesCreated: h.filesCreated?.slice(0, 50), // Limit array size
+				filesModified: h.filesModified?.slice(0, 50), // Limit array size
+				decisions: h.decisions?.slice(0, 20), // Limit array size
+				nextSteps: h.nextSteps?.slice(0, 20), // Limit array size
+			})),
+		};
+	}
+
+	/**
+	 * Execute a single step.
+	 */
+	private async executeStep(
+		config: ChainStep,
+		context: Record<string, unknown>
+	): Promise<TaskResult> {
+		const packet: TaskPacket = {
+			taskId: `chain-${Date.now()}-${config.name}`,
+			runId: "chain",
+			goal: config.inlineGoal ?? config.name,
+			summarizeThreshold: 3000,
+			collapseContext: true,
+			context,
+		};
+
+		return this.taskRunner.runTask(packet);
+	}
+
+	/**
+	 * Create minimal packet for handoff generation.
+	 */
+	private createMinimalPacket(step: ChainStep, index: number): TaskPacket {
+		return {
+			taskId: `chain-step-${index}`,
+			runId: "chain",
+			sessionId: "chain",
+			goal: step.inlineGoal ?? step.name,
+		};
+	}
+}
+
+/**
+ * Create a ChainRunner with default dependencies.
+ */
+export function createChainRunner(
+	taskRunner: ChainTaskRunner,
+	handoffManager: HandoffManager
+): ChainRunner {
+	return new ChainRunner(taskRunner, handoffManager);
+}
+
+/**
+ * Parse chain from string shorthand.
+ */
+export function parseChainString(chainString: string): ChainSpec {
+	const runner = new ChainRunner(
+		{ runTask: () => Promise.reject(new Error("Not initialized")) } as ChainTaskRunner,
+		{} as HandoffManager
+	);
+	return runner.parseChain(chainString);
+}