pi-crew 0.5.5 → 0.5.7

package/src/runtime/retry-runner.ts

@@ -0,0 +1,354 @@
+/**
+ * RetryRunner - Execute tasks with retry support and summary accumulation.
+ * 
+ * Based on pi-boomerang's --rethrow pattern:
+ * - Retries failed tasks up to maxAttempts
+ * - Generates handoffs between attempts
+ * - Accumulates context from previous attempts
+ * - Supports exponential backoff
+ * - Limits handoff accumulation to prevent memory leaks
+ * 
+ * @see docs/pi-boomerang-integration-plan.md
+ */
+
+import type { HandoffSummary, HandoffManager, TaskPacket, TaskResult } from "./handoff-manager.ts";
+
+/**
+ * Retry configuration.
+ */
+export interface RetryConfig {
+	/** Maximum number of retry attempts */
+	maxAttempts: number;
+	/** Generate summary between attempts for context accumulation */
+	summaryBetweenAttempts?: boolean;
+	/** Stop retrying if task succeeds */
+	stopOnSuccess?: boolean;
+	/** Base backoff delay in milliseconds (multiplied by attempt number) */
+	backoffMs?: number;
+	/** Backoff multiplier (default: 1) */
+	backoffMultiplier?: number;
+	/** Maximum backoff delay cap in milliseconds */
+	maxBackoffMs?: number;
+	/** Custom retry condition (return true to retry) */
+	retryCondition?: (result: TaskResult, attempt: number) => boolean;
+	/** Maximum handoffs to retain (default: 100) - prevents memory leaks */
+	maxHandoffs?: number;
+}
+
+/**
+ * Result of a single attempt.
+ */
+export interface AttemptResult {
+	attempt: number;
+	result: TaskResult;
+	summary?: HandoffSummary;
+	duration: number;
+	error?: string;
+	timestamp: number;
+}
+
+/**
+ * Final retry result.
+ */
+export interface RetryResult {
+	success: boolean;
+	attempts: AttemptResult[];
+	finalResult?: TaskResult;
+	totalHandoffs: HandoffSummary[];
+	totalDuration: number;
+}
+
+/**
+ * Task runner interface (minimal for retry functionality).
+ */
+export interface TaskRunnerLike {
+	runTask(packet: TaskPacket): Promise<TaskResult>;
+}
+
+/**
+ * RetryRunner handles task execution with automatic retry and summary accumulation.
+ */
+export class RetryRunner {
+	private _disposed = false;
+	private _handoffs: HandoffSummary[] = [];
+
+	constructor(
+		private taskRunner: TaskRunnerLike,
+		private handoffManager: HandoffManager,
+	) {}
+
+	/**
+	 * Check if this runner has been disposed.
+	 */
+	get isDisposed(): boolean {
+		return this._disposed;
+	}
+
+	/**
+	 * Dispose of resources held by this runner.
+	 * Clears any accumulated state and prevents further operations.
+	 */
+	dispose(): void {
+		this._disposed = true;
+	}
+
+	/**
+	 * Clear accumulated handoffs to free memory.
+	 * Useful when you want to reset state without disposing.
+	 */
+	clearHandoffs(): void {
+		this._handoffs = [];
+	}
+
+	/**
+	 * Get the effective max handoffs limit from config or default.
+	 */
+	private getMaxHandoffs(config: RetryConfig): number {
+		return config.maxHandoffs ?? 100;
+	}
+
+	/**
+	 * Trim handoffs array to max size, keeping most recent.
+	 */
+	private trimHandoffs(handoffs: HandoffSummary[], maxSize: number): HandoffSummary[] {
+		if (handoffs.length <= maxSize) {
+			return handoffs;
+		}
+		// Keep the most recent handoffs (last maxSize items)
+		return handoffs.slice(-maxSize);
+	}
+
+	/**
+	 * Execute task with retry support.
+	 * Summaries accumulate between attempts for better context.
+	 * 
+	 * @param packet - Task packet to execute
+	 * @param config - Retry configuration (stopOnSuccess defaults to true)
+	 * @returns Final retry result with all attempts
+	 */
+	async runWithRetry(
+		packet: TaskPacket,
+		config: RetryConfig
+	): Promise<RetryResult> {
+		if (this._disposed) {
+			throw new Error("RetryRunner has been disposed");
+		}
+
+		const attempts: AttemptResult[] = [];
+		const handoffs: HandoffSummary[] = [];
+		const startTime = Date.now();
+		const maxHandoffs = this.getMaxHandoffs(config);
+
+		// Clear previous handoffs at start of each retry run
+		this._handoffs = [];
+
+
+		for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+			if (this._disposed) {
+				throw new Error("RetryRunner was disposed during retry");
+			}
+			const attemptStart = Date.now();
+
+			try {
+				// Inject accumulated handoffs into context
+				const enrichedPacket = this.enrichPacketWithHandoffs(
+					packet,
+					handoffs,
+					attempt
+				);
+
+				// Execute task
+				const result = await this.taskRunner.runTask(enrichedPacket);
+
+				const attemptResult: AttemptResult = {
+					attempt,
+					result,
+					duration: Date.now() - attemptStart,
+					timestamp: Date.now(),
+				};
+
+				// Generate summary between attempts
+				if (config.summaryBetweenAttempts !== false) {
+					const summary = await this.handoffManager.generateSummary(
+						packet,
+						result
+					);
+					attemptResult.summary = summary;
+					handoffs.push(summary);
+
+					// Trim handoffs to prevent memory leak
+					if (handoffs.length > maxHandoffs) {
+						handoffs.splice(0, handoffs.length - maxHandoffs);
+					}
+				}
+
+				attempts.push(attemptResult);
+
+				// Stop on success if configured (default to true when undefined)
+				if ((config.stopOnSuccess ?? true) && result.outcome === "success") {
+					return {
+						success: true,
+						attempts,
+						finalResult: result,
+						totalHandoffs: handoffs,
+						totalDuration: Date.now() - startTime,
+					};
+				}
+
+				// Check custom retry condition
+				if (config.retryCondition && !config.retryCondition(result, attempt)) {
+					break;
+				}
+
+				// Check default retry condition (retry on failure)
+				if (result.outcome !== "success" && attempt < config.maxAttempts) {
+					// Apply backoff before retry
+					const backoffDelay = this.calculateBackoff(
+						config.backoffMs ?? 1000,
+						attempt,
+						config.backoffMultiplier ?? 1,
+						config.maxBackoffMs
+					);
+					if (backoffDelay > 0) {
+						await this.sleep(backoffDelay);
+					}
+				}
+
+			} catch (error) {
+				attempts.push({
+					attempt,
+					result: {
+						outcome: "failure",
+						error: error instanceof Error ? error.message : String(error),
+					},
+					duration: Date.now() - attemptStart,
+					timestamp: Date.now(),
+					error: error instanceof Error ? error.message : String(error),
+				});
+
+				// Apply backoff before retry on error
+				if (config.backoffMs && attempt < config.maxAttempts) {
+					const backoffDelay = this.calculateBackoff(
+						config.backoffMs,
+						attempt,
+						config.backoffMultiplier ?? 1,
+						config.maxBackoffMs
+					);
+					if (backoffDelay > 0) {
+						await this.sleep(backoffDelay);
+					}
+				}
+			}
+		}
+
+		const finalAttempt = attempts[attempts.length - 1];
+		return {
+			success: finalAttempt?.result.outcome === "success",
+			attempts,
+			finalResult: finalAttempt?.result,
+			totalHandoffs: this.trimHandoffs(handoffs, maxHandoffs),
+			totalDuration: Date.now() - startTime,
+		};
+	}
+
+	/**
+	 * Enrich packet with accumulated handoffs from previous attempts.
+	 */
+	private enrichPacketWithHandoffs(
+		packet: TaskPacket,
+		handoffs: HandoffSummary[],
+		attempt: number
+	): TaskPacket {
+		if (handoffs.length === 0) {
+			return packet;
+		}
+
+		// Build accumulated context from previous attempts
+		const accumulatedContext = handoffs.map((h, index) =>
+			`## Attempt ${index + 1}: ${h.task}\n` +
+			`Outcome: ${h.outcome}\n` +
+			`Files: created=${h.filesCreated.join(", ")}, modified=${h.filesModified.join(", ")}\n` +
+			`Decisions: ${h.decisions.map(d => d.rationale).join("; ")}\n` +
+			`Blockers: ${h.blockers.join(", ")}\n` +
+			`Next Steps: ${h.nextSteps.join(", ")}\n`
+		).join("\n---\n");
+
+		return {
+			...packet,
+			context: {
+				...packet.context,
+				__boomerangAttempts: attempt,
+				__boomerangHandoffs: handoffs,
+				__boomerangContext: `Previous attempts summary:\n${accumulatedContext}`,
+			},
+		};
+	}
+
+	/**
+	 * Calculate backoff delay with optional capping.
+	 */
+	private calculateBackoff(
+		baseMs: number,
+		attempt: number,
+		multiplier: number,
+		maxBackoffMs?: number
+	): number {
+		let delay = baseMs * Math.pow(multiplier, attempt - 1);
+		if (maxBackoffMs !== undefined) {
+			delay = Math.min(delay, maxBackoffMs);
+		}
+		return delay;
+	}
+
+	/**
+	 * Sleep helper.
+	 */
+	private sleep(ms: number): Promise<void> {
+		return new Promise(resolve => setTimeout(resolve, ms));
+	}
+}
+
+/**
+ * Create a RetryRunner with default dependencies.
+ */
+export function createRetryRunner(
+	taskRunner: TaskRunnerLike,
+	handoffManager: HandoffManager
+): RetryRunner {
+	return new RetryRunner(taskRunner, handoffManager);
+}
+
+/**
+ * Default retry config for common scenarios.
+ */
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+	maxAttempts: 3,
+	summaryBetweenAttempts: true,
+	stopOnSuccess: true,
+	backoffMs: 1000,
+	backoffMultiplier: 2,
+	maxBackoffMs: 30000,
+};
+
+/**
+ * Retry config for transient failures (quick retries).
+ */
+export const TRANSIENT_FAILURE_RETRY_CONFIG: RetryConfig = {
+	maxAttempts: 2,
+	summaryBetweenAttempts: false,
+	stopOnSuccess: true,
+	backoffMs: 500,
+	backoffMultiplier: 1,
+};
+
+/**
+ * Retry config for persistent failures (exponential backoff).
+ */
+export const PERSISTENT_FAILURE_RETRY_CONFIG: RetryConfig = {
+	maxAttempts: 5,
+	summaryBetweenAttempts: true,
+	stopOnSuccess: true,
+	backoffMs: 2000,
+	backoffMultiplier: 2,
+	maxBackoffMs: 60000,
+};

package/src/runtime/sandbox.ts

@@ -0,0 +1,252 @@
+import * as vm from "node:vm";
+
+/**
+ * Forbidden patterns for sandbox security (C4).
+ * These are checked during script compilation/validation.
+ */
+const FORBIDDEN_PATTERNS = [
+	// ESM patterns
+	/import\s*\(/,                    // Dynamic import()
+	/import\s+.*from\s+/,            // Static import
+	/export\s+(default\s+)?/,         // Export statements
+	/import\.meta/,                   // import.meta
+	// Module patterns
+	/require\s*\(/,                   // CommonJS require
+	/module\./,                        // module.exports, module.id, etc.
+	/__dirname/,                       // __dirname reference
+	/__filename/,                      // __filename reference
+	/\bdefine\s*\(/,                  // AMD define
+] as const;
+
+/**
+ * Whitelist of allowed identifiers for strict mode.
+ * Only these identifiers can be used in sandboxed code.
+ */
+const ALLOWED_IDENTIFIERS = new Set([
+	// Built-in constructors
+	"Array", "Boolean", "Date", "Error", "Function", "JSON", "Map", "Number", "Object", "Promise", "RegExp", "Set", "String", "Symbol",
+	// Static methods
+	"ArrayBuffer", "Uint8Array", "parseInt", "parseFloat", "isNaN", "isFinite",
+	// URI encoding
+	"encodeURI", "decodeURI", "encodeURIComponent", "decodeURIComponent",
+	// Math (read-only)
+	"Math",
+	// Console (safe methods only)
+	"console",
+	// Process (limited)
+	"process",
+]);
+
+Object.freeze(FORBIDDEN_PATTERNS);
+
+export interface SandboxOptions {
+	timeout?: number;
+	globals?: Record<string, unknown>;
+	onLog?: (message: string) => void;
+	onError?: (message: string) => void;
+	onWarn?: (message: string) => void;
+}
+
+/**
+ * WorkflowSandbox provides a safe execution context for dynamic JavaScript
+ * in pi-crew workflows. It creates a VM context with restricted globals
+ * and provides safe console and process objects.
+ */
+export class WorkflowSandbox {
+	private context: vm.Context;
+	private timeout: number;
+
+	constructor(options: SandboxOptions = {}) {
+		this.timeout = options.timeout ?? 30000;
+		this.context = this.createSafeContext(options.globals ?? {}, options);
+	}
+
+	private createSafeContext(globals: Record<string, unknown>, options: SandboxOptions): vm.Context {
+		// C4: Frozen process object - limited access to process internals
+		const frozenProcess = {
+			cwd: () => process.cwd(),
+			platform: process.platform,
+			arch: process.arch,
+			version: process.version,
+			env: { ...process.env }, // Copy, not reference
+			// Explicitly excluded: exit, kill, hrtime, memoryUsage, cpuUsage, binding, dlopen, _tickCallback
+		};
+		Object.freeze(frozenProcess);
+
+		// Safe console implementation
+		const safeConsole = {
+			log: (...args: unknown[]) => (options.onLog ?? console.log)(args.map(formatArg).join(" ")),
+			error: (...args: unknown[]) => (options.onError ?? console.error)(args.map(formatArg).join(" ")),
+			warn: (...args: unknown[]) => (options.onWarn ?? console.warn)(args.map(formatArg).join(" ")),
+			info: (...args: unknown[]) => (options.onLog ?? console.log)(args.map(formatArg).join(" ")),
+			debug: (...args: unknown[]) => (options.onLog ?? console.log)(args.map(formatArg).join(" ")),
+			table: (data: unknown) => (options.onLog ?? console.log)(JSON.stringify(data, null, 2)),
+			dir: (data: unknown) => (options.onLog ?? console.log)(JSON.stringify(data, null, 2)),
+		};
+
+		// C4: Ensure globals don't include process, global, or globalThis references
+		const safeGlobals: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(globals)) {
+			// Filter out dangerous global references
+			if (key === "process" || key === "global" || key === "globalThis" || key === "GLOBAL") {
+				continue; // Skip - these are handled by frozenProcess or intentionally omitted
+			}
+			safeGlobals[key] = value;
+		}
+
+		// Context isolation - explicitly list allowed globals
+		const contextGlobals: Record<string, unknown> = {
+			...safeGlobals,
+			process: frozenProcess,
+			console: safeConsole,
+			// Safe Math (static methods only)
+			Math: Math,
+			// Safe JSON
+			JSON: JSON,
+			// Safe Number
+			Number: Number,
+			// Safe String
+			String: String,
+			// Safe Boolean
+			Boolean: Boolean,
+			// Safe Array
+			Array: Array,
+			// Safe Object
+			Object: Object,
+			// Safe RegExp
+			RegExp: RegExp,
+			// Safe Error
+			Error: Error,
+			// Safe Map
+			Map: Map,
+			// Safe Set
+			Set: Set,
+			// Safe Promise
+			Promise: Promise,
+			// Safe Symbol
+			Symbol: Symbol,
+			// Safe parseInt/parseFloat
+			parseInt: parseInt,
+			parseFloat: parseFloat,
+			isNaN: isNaN,
+			isFinite: isFinite,
+			// Safe encodeURI/decodeURI
+			encodeURI: encodeURI,
+			decodeURI: decodeURI,
+			encodeURIComponent: encodeURIComponent,
+			decodeURIComponent: decodeURIComponent,
+			// Safe typed arrays (read-only buffer views)
+			ArrayBuffer: ArrayBuffer,
+			Uint8Array: Uint8Array,
+		};
+
+		return vm.createContext(contextGlobals);
+	}
+
+	/**
+	 * C4: Validate code before execution - check for forbidden patterns and
+	 * ensure compilation is safe.
+	 */
+	private validateScript(code: string): void {
+		// Check for ESM/module patterns
+		for (const pattern of FORBIDDEN_PATTERNS) {
+			if (pattern.test(code)) {
+				throw new Error(`Forbidden pattern detected: ${pattern.source}`);
+			}
+		}
+
+		// Check for import.meta specifically (C4)
+		if (/import\.meta/.test(code)) {
+			throw new Error("import.meta is not allowed in sandboxed code");
+		}
+
+		// Verify compilation succeeds (C4)
+		const wrappedCode = `(function(){ ${code} })()`;
+		new vm.Script(wrappedCode, {
+			filename: "sandbox-validate.js",
+		});
+	}
+
+	/**
+	 * Execute JavaScript code in the sandboxed context.
+	 * @param code - The JavaScript code to execute
+	 * @param timeout - Optional timeout override in milliseconds
+	 * @returns The result of the script execution
+	 * @throws Error if code contains forbidden patterns or fails compilation
+	 */
+	execute(code: string, timeout?: number): unknown {
+		// C4: Validate script before execution
+		this.validateScript(code);
+
+		const effectiveTimeout = timeout ?? this.timeout;
+		// Wrap code in an IIFE to allow return statements
+		const wrappedCode = `(function(){ ${code} })()`;
+		const script = new vm.Script(wrappedCode, {
+			filename: "workflow.js",
+		});
+
+		return script.runInContext(this.context, {
+			timeout: effectiveTimeout,
+			displayErrors: true,
+		});
+	}
+
+	/**
+	 * Execute an async function in the sandboxed context.
+	 * @param fn - Async function to execute
+	 * @param timeout - Optional timeout override in milliseconds
+	 * @returns Promise resolving to the function result
+	 */
+	async executeAsync<T>(fn: () => Promise<T>, timeout?: number): Promise<T> {
+		const effectiveTimeout = timeout ?? this.timeout;
+		const script = new vm.Script(`(${fn.toString()})()`, {
+			filename: "workflow.js",
+		});
+
+		const result = script.runInContext(this.context, {
+			timeout: effectiveTimeout,
+			displayErrors: true,
+		});
+
+		return result as Promise<T>;
+	}
+
+	/**
+	 * Create a new sandbox with additional globals merged in.
+	 */
+	extend(additionalGlobals: Record<string, unknown>): WorkflowSandbox {
+		const newSandbox = new WorkflowSandbox({
+			timeout: this.timeout,
+			globals: { ...additionalGlobals },
+		});
+		return newSandbox;
+	}
+
+	/**
+	 * Get the VM context for advanced use cases.
+	 */
+	getContext(): vm.Context {
+		return this.context;
+	}
+}
+
+function formatArg(arg: unknown): string {
+	if (typeof arg === "string") return arg;
+	if (arg === null) return "null";
+	if (arg === undefined) return "undefined";
+	if (typeof arg === "object") {
+		try {
+			return JSON.stringify(arg);
+		} catch {
+			return String(arg);
+		}
+	}
+	return String(arg);
+}
+
+/**
+ * Create a pre-configured sandbox for workflow execution.
+ */
+export function createWorkflowSandbox(options?: SandboxOptions): WorkflowSandbox {
+	return new WorkflowSandbox(options);
+}

package/src/runtime/scheduler.ts

@@ -106,8 +106,13 @@ export class CrewScheduler {
 	private disarm(id: string): void {
 		const t = this.timers.get(id);
 		if (t) {
-			clearInterval(t as ReturnType<typeof setInterval>);
-			clearTimeout(t as ReturnType<typeof setTimeout>);
+			// Branch on timer type to use correct clear function
+			const job = this.jobs.get(id);
+			if (job?.scheduleType === "once") {
+				clearTimeout(t as ReturnType<typeof setTimeout>);
+			} else {
+				clearInterval(t as ReturnType<typeof setInterval>);
+			}
 			this.timers.delete(id);
 		}
 	}

package/src/runtime/subagent-manager.ts

@@ -220,7 +220,7 @@ export class SubagentManager {
 			const record = this.records.get(id);
 			if (!record) return undefined;
 			if (record.status !== "running" && record.status !== "queued") return record;
-			if (record.promise) await record.promise.catch(() => { /* status already set to error */ });
+			if (record.promise) await record.promise.catch((error) => { logInternalError("subagent-manager.waitForRecord", error, `id=${id}`); });
 			else await new Promise((resolve) => setTimeout(resolve, 100));
 		}
 	}

package/src/runtime/task-graph.ts

@@ -34,12 +34,21 @@ export interface ExecutionPlan {
  * - Each subsequent wave contains tasks whose dependencies are all in earlier waves.
  * - If all tasks have empty `dependsOn`, they all go into wave 0 (backward compatible).
  * - If a cycle is detected, `hasCycle` is true and `cycleNodes` lists the involved IDs.
+ * 
+ * @throws Error if a task depends on itself (self-dependency).
  */
 export function buildExecutionPlan(tasks: TaskNode[]): ExecutionPlan {
 	if (tasks.length === 0) {
 		return { waves: [], hasCycle: false };
 	}
 
+	// HIGH-9: Detect self-dependency
+	for (const task of tasks) {
+		if (task.dependsOn.includes(task.id)) {
+			throw new Error(`Task "${task.id}" has self-dependency (depends on itself)`);
+		}
+	}
+
 	const idSet = new Set<string>(tasks.map((t) => t.id));
 	const adjacency = new Map<string, Set<string>>();       // id -> ids that depend on it
 	const inDegree = new Map<string, number>();
@@ -108,7 +117,8 @@ export function buildExecutionPlan(tasks: TaskNode[]): ExecutionPlan {
  */
 function buildWave(tasks: TaskNode[], ids: string[], index: number): ExecutionWave {
 	const taskMap = new Map(tasks.map((t) => [t.id, t]));
-	const waveTasks = ids.map((id) => taskMap.get(id)!).filter(Boolean);
+	// MEDIUM-12: Filter out undefined values instead of using non-null assertion
+	const waveTasks = ids.map((id) => taskMap.get(id)).filter(Boolean) as TaskNode[];
 
 	let label: string | undefined;
 	if (waveTasks.length > 0 && waveTasks.every((t) => t.phase !== undefined)) {

package/src/runtime/task-runner.ts

@@ -205,6 +205,20 @@ export async function runTeamTask(
 			input.taskRuntimeOverride ??
 			input.runtimeKind ??
 			(input.executeWorkers ? "child-process" : "scaffold");
+		// FIX: Check signal before persisting state — if cancelled, skip the write.
+		if (input.signal?.aborted) {
+			const cancelReason = cancellationReasonFromSignal(input.signal);
+			const cancelledTask: TeamTaskState = {
+				...task,
+				status: "cancelled",
+				error: `${cancelReason.code}: ${cancelReason.message}`,
+				finishedAt: new Date().toISOString(),
+			};
+			return {
+				manifest: input.manifest,
+				tasks: updateTask(tasks, cancelledTask),
+			};
+		}
 		tasks = persistSingleTaskUpdate(manifest, tasks, task);
 		if (runtimeKind === "child-process")
 			({ task, tasks } = checkpointTask(
@@ -458,7 +472,7 @@ export async function runTeamTask(
 							taskId: task.id,
 							message: `Worker lifecycle: ${event.type}${event.error ? ` error=${event.error}` : ""}${event.exitCode != null ? ` exit=${event.exitCode}` : ""}`,
 							data: { ...event },
-						});
+						}).catch((error) => logInternalError("task-runner.lifecycle-event", error, `taskId=${task.id}, type=${event.type}`));
 					},
 					onStdoutLine: (line) => {
 						appendCrewAgentOutput(manifest, task.id, line);