pi-crew 0.9.50 → 0.9.52

package/src/runtime/phase-progress.ts

@@ -1,217 +0,0 @@
-/**
- * Phase progress calculator for pi-crew runs.
- *
- * Groups tasks by their adaptive phase metadata and computes per-phase
- * and overall progress metrics including estimated remaining time.
- */
-import type { TeamTaskState } from "../state/types.ts";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface PhaseInfo {
-	/** Phase name, e.g. "explore", "plan", "execute", "verify" */
-	phase: string;
-	/** 0-based index among all phases */
-	index: number;
-	/** Total tasks in this phase */
-	total: number;
-	/** Completed tasks */
-	completed: number;
-	/** Failed tasks */
-	failed: number;
-	/** Currently running tasks */
-	running: number;
-	/** Still queued (not started) */
-	queued: number;
-	/** (completed + failed) / total * 100, rounded to 1 decimal */
-	percentage: number;
-}
-
-export interface RunProgress {
-	/** Breakdown per phase, in phase order */
-	phases: PhaseInfo[];
-	/** Overall (completed + failed) / total * 100 */
-	overallPercentage: number;
-	/** Phase that currently has running or queued tasks, or null */
-	currentPhase: string | null;
-	/** Estimated remaining ms based on avg task duration × remaining tasks */
-	estimatedRemainingMs: number;
-	/** Total task count */
-	totalTasks: number;
-	/** Completed task count */
-	completedTasks: number;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "skipped", "needs_attention"]);
-
-/**
- * Extract the phase label for a task.
- *
- * Priority:
- * 1. `task.adaptive.phase` (set by adaptive planner)
- * 2. Infer from stepId prefix: `adaptive-<phaseIndex>-...` → use the numeric phase index
- * 3. Fallback: `"default"`
- */
-function extractPhase(task: TeamTaskState): string {
-	if (task.adaptive?.phase) return task.adaptive.phase;
-	if (task.stepId?.startsWith("adaptive-")) {
-		const parts = task.stepId.split("-");
-		// adaptive-<phaseIndex>-<taskIndex>-<role> → parts[1] is the phase index
-		if (parts.length >= 3 && parts[1]) return parts[1];
-	}
-	return "default";
-}
-
-/**
- * Compute task duration in ms from startedAt → finishedAt.
- * Returns undefined if timestamps are missing or invalid.
- */
-function taskDurationMs(task: TeamTaskState): number | undefined {
-	if (!task.startedAt || !task.finishedAt) return undefined;
-	const start = new Date(task.startedAt).getTime();
-	const end = new Date(task.finishedAt).getTime();
-	const duration = end - start;
-	return Number.isFinite(duration) && duration > 0 ? duration : undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Main export
-// ---------------------------------------------------------------------------
-
-/**
- * Compute phase-aware progress for a set of tasks.
- *
- * Groups tasks by phase, calculates per-phase and overall percentages,
- * and estimates remaining time from the average duration of completed tasks.
- */
-export function computePhaseProgress(tasks: TeamTaskState[]): RunProgress {
-	if (tasks.length === 0) {
-		return {
-			phases: [],
-			overallPercentage: 0,
-			currentPhase: null,
-			estimatedRemainingMs: 0,
-			totalTasks: 0,
-			completedTasks: 0,
-		};
-	}
-
-	// Preserve insertion order of first-seen phase
-	const phaseOrder: string[] = [];
-	const phaseGroups = new Map<string, TeamTaskState[]>();
-
-	for (const task of tasks) {
-		const phase = extractPhase(task);
-		if (!phaseGroups.has(phase)) {
-			phaseGroups.set(phase, []);
-			phaseOrder.push(phase);
-		}
-		phaseGroups.get(phase)!.push(task);
-	}
-
-	let totalCompleted = 0;
-	let totalTerminal = 0;
-	let totalDurationSum = 0;
-	let totalDurationCount = 0;
-	let currentPhase: string | null = null;
-
-	const phases: PhaseInfo[] = phaseOrder.map((phase, index) => {
-		const group = phaseGroups.get(phase)!;
-		let completed = 0;
-		let failed = 0;
-		let running = 0;
-		let queued = 0;
-		let hasRunningOrQueued = false;
-
-		for (const task of group) {
-			const status = task.status;
-			if (status === "completed") {
-				completed++;
-				totalCompleted++;
-				totalTerminal++;
-				const dur = taskDurationMs(task);
-				if (dur !== undefined) {
-					totalDurationSum += dur;
-					totalDurationCount++;
-				}
-			} else if (status === "failed") {
-				failed++;
-				totalTerminal++;
-				const dur = taskDurationMs(task);
-				if (dur !== undefined) {
-					totalDurationSum += dur;
-					totalDurationCount++;
-				}
-			} else if (status === "running" || status === "waiting") {
-				running++;
-				hasRunningOrQueued = true;
-			} else if (status === "queued") {
-				queued++;
-				hasRunningOrQueued = true;
-			}
-			// cancelled, skipped → counted in total but not completed/failed
-		}
-
-		if (hasRunningOrQueued && currentPhase === null) {
-			currentPhase = phase;
-		}
-
-		const terminal = completed + failed;
-		const percentage = group.length > 0 ? Math.round((terminal / group.length) * 1000) / 10 : 0;
-
-		return {
-			phase,
-			index,
-			total: group.length,
-			completed,
-			failed,
-			running,
-			queued,
-			percentage,
-		};
-	});
-
-	const overallPercentage = tasks.length > 0 ? Math.round((totalTerminal / tasks.length) * 1000) / 10 : 0;
-
-	// Estimate remaining time: avg duration × remaining non-terminal tasks
-	const remainingTasks = tasks.length - totalTerminal;
-	let estimatedRemainingMs = 0;
-	if (totalDurationCount > 0 && remainingTasks > 0) {
-		const avgDuration = totalDurationSum / totalDurationCount;
-		estimatedRemainingMs = Math.round(avgDuration * remainingTasks);
-	}
-
-	return {
-		phases,
-		overallPercentage,
-		currentPhase,
-		estimatedRemainingMs,
-		totalTasks: tasks.length,
-		completedTasks: totalCompleted,
-	};
-}
-
-/**
- * Format a human-readable phase progress line.
- *
- * Example: "Phase 2/4 execute: 60.0% (3/5)"
- * Returns empty string when there are no phases.
- */
-export function formatPhaseProgressLine(runProgress: RunProgress): string {
-	if (runProgress.phases.length === 0) return "";
-	const current = runProgress.currentPhase;
-	if (!current) {
-		// All done — show summary
-		return `All ${runProgress.phases.length} phases done: ${runProgress.overallPercentage}% (${runProgress.completedTasks}/${runProgress.totalTasks})`;
-	}
-	const currentPhaseInfo = runProgress.phases.find((p) => p.phase === current);
-	if (!currentPhaseInfo) return `${runProgress.overallPercentage}% done`;
-	const done = currentPhaseInfo.completed + currentPhaseInfo.failed;
-	return `Phase ${currentPhaseInfo.index + 1}/${runProgress.phases.length} ${current}: ${currentPhaseInfo.percentage}% (${done}/${currentPhaseInfo.total})`;
-}

package/src/runtime/phase-tracker.ts

@@ -1,385 +0,0 @@
-/**
- * Phase Tracker — marks phase transitions with timestamps and metrics.
- *
- * Tracks workflow phases (assessment, implementation, verification, etc.)
- * with start/complete/skip lifecycle and phase-level metrics.
- *
- * @file src/runtime/phase-tracker.ts
- */
-
-import { EventEmitter } from "node:events";
-
-/** Phase status. */
-export type PhaseStatus = "active" | "completed" | "skipped" | "failed";
-
-/** Metrics collected for a phase. */
-export interface PhaseMetrics {
-	/** Number of tasks completed in this phase. */
-	tasksCompleted?: number;
-	/** Number of tasks failed in this phase. */
-	tasksFailed?: number;
-	/** Total tokens used in this phase. */
-	tokensUsed?: number;
-	/** Number of subagents spawned in this phase. */
-	subagentsSpawned?: number;
-	/** Custom metadata key-value pairs. */
-	custom?: Record<string, unknown>;
-}
-
-/** A tracked phase. */
-export interface Phase {
-	/** Unique phase name/identifier. */
-	name: string;
-	/** ISO timestamp when phase started. */
-	startTime: string;
-	/** ISO timestamp when phase ended (if ended). */
-	endTime?: string;
-	/** Duration in milliseconds (if ended). */
-	durationMs?: number;
-	/** Current phase status. */
-	status: PhaseStatus;
-	/** Collected metrics for this phase. */
-	metrics?: PhaseMetrics;
-	/** Order index (0-based). */
-	index: number;
-}
-
-/** Event emitted on phase lifecycle changes. */
-export interface PhaseLifecycleEvent {
-	type: "phase:started" | "phase:completed" | "phase:skipped" | "phase:failed";
-	phase: Phase;
-}
-
-/** Default empty metrics. */
-function emptyMetrics(): PhaseMetrics {
-	return {
-		tasksCompleted: 0,
-		tasksFailed: 0,
-		tokensUsed: 0,
-		subagentsSpawned: 0,
-	};
-}
-
-/**
- * PhaseTracker manages workflow phase lifecycle.
- *
- * @example
- * ```typescript
- * const tracker = new PhaseTracker();
- * tracker.start("assessment");
- * // ... do work ...
- * tracker.complete("assessment", { tasksCompleted: 5, tokensUsed: 12000 });
- * tracker.start("implementation");
- * ```
- */
-export class PhaseTracker extends EventEmitter {
-	private phases: Phase[] = [];
-	private currentPhaseName: string | null = null;
-	private phaseMetrics: Map<string, PhaseMetrics> = new Map();
-
-	/**
-	 * Start a new phase, completing the previous one if any.
-	 *
-	 * @param name - Phase name (e.g., "assessment", "implementation").
-	 * @param metrics - Optional initial metrics for the phase.
-	 * @returns The started Phase object.
-	 */
-	start(name: string, metrics?: PhaseMetrics): Phase {
-		// HIGH-8: Prevent duplicate phases - check if phase already exists
-		if (this.phases.some((p) => p.name === name)) {
-			throw new Error(`Phase "${name}" already exists. Duplicate phases are not allowed.`);
-		}
-
-		// Complete previous phase before starting new one (only if active)
-		if (this.currentPhaseName !== null) {
-			this.completeIfActive(this.currentPhaseName);
-		}
-
-		const phase: Phase = {
-			name,
-			startTime: new Date().toISOString(),
-			status: "active",
-			index: this.phases.length,
-			metrics: metrics ?? emptyMetrics(),
-		};
-
-		this.phases.push(phase);
-		this.currentPhaseName = name;
-		this.phaseMetrics.set(name, phase.metrics!);
-
-		const event: PhaseLifecycleEvent = { type: "phase:started", phase };
-		this.emit("phase:started", event);
-		return phase;
-	}
-
-	/**
-	 * Complete a phase with optional metrics update.
-	 *
-	 * @param name - Phase name to complete.
-	 * @param metrics - Optional metrics to merge/update.
-	 */
-	complete(name: string, metrics?: Partial<PhaseMetrics>): void {
-		const phase = this.phases.find((p) => p.name === name);
-		if (!phase) {
-			throw new Error(`Phase "${name}" not found`);
-		}
-		if (phase.status !== "active") {
-			throw new Error(`Phase "${name}" is not active (status: ${phase.status})`);
-		}
-
-		const now = new Date();
-		const startMs = new Date(phase.startTime).getTime();
-		const endMs = now.getTime();
-
-		phase.endTime = now.toISOString();
-		phase.durationMs = endMs - startMs;
-		phase.status = "completed";
-
-		// Merge provided metrics with existing
-		if (metrics) {
-			const existing = this.phaseMetrics.get(name) ?? emptyMetrics();
-			phase.metrics = {
-				tasksCompleted: metrics.tasksCompleted ?? existing.tasksCompleted,
-				tasksFailed: metrics.tasksFailed ?? existing.tasksFailed,
-				tokensUsed: metrics.tokensUsed ?? existing.tokensUsed,
-				subagentsSpawned: metrics.subagentsSpawned ?? existing.subagentsSpawned,
-				custom: { ...existing.custom, ...metrics.custom },
-			};
-			this.phaseMetrics.set(name, phase.metrics);
-		}
-
-		this.emit("phase:completed", {
-			type: "phase:completed",
-			phase,
-		} as PhaseLifecycleEvent);
-	}
-
-	/**
-	 * Skip the current active phase without metrics.
-	 *
-	 * @param name - Phase name to skip.
-	 * @param reason - Optional reason for skipping.
-	 */
-	skip(name: string, reason?: string): void {
-		const phase = this.phases.find((p) => p.name === name);
-		if (!phase) {
-			throw new Error(`Phase "${name}" not found`);
-		}
-		if (phase.status !== "active") {
-			throw new Error(`Phase "${name}" is not active (status: ${phase.status})`);
-		}
-
-		const now = new Date();
-		const startMs = new Date(phase.startTime).getTime();
-		const endMs = now.getTime();
-
-		phase.endTime = now.toISOString();
-		phase.durationMs = endMs - startMs;
-		phase.status = "skipped";
-
-		// Clear current phase since we're done with it
-		if (this.currentPhaseName === name) {
-			this.currentPhaseName = null;
-		}
-
-		this.emit("phase:skipped", {
-			type: "phase:skipped",
-			phase,
-		} as PhaseLifecycleEvent);
-	}
-
-	/**
-	 * Mark a phase as failed.
-	 *
-	 * @param name - Phase name to fail.
-	 * @param error - Optional error information.
-	 */
-	fail(name: string, error?: string): void {
-		const phase = this.phases.find((p) => p.name === name);
-		if (!phase) {
-			throw new Error(`Phase "${name}" not found`);
-		}
-		if (phase.status !== "active") {
-			throw new Error(`Phase "${name}" is not active (status: ${phase.status})`);
-		}
-
-		const now = new Date();
-		const startMs = new Date(phase.startTime).getTime();
-		const endMs = now.getTime();
-
-		phase.endTime = now.toISOString();
-		phase.durationMs = endMs - startMs;
-		phase.status = "failed";
-
-		if (error) {
-			const existing = this.phaseMetrics.get(name) ?? emptyMetrics();
-			phase.metrics = {
-				...existing,
-				custom: { ...existing.custom, error },
-			};
-			this.phaseMetrics.set(name, phase.metrics);
-		}
-
-		// Clear current phase since we're done with it
-		if (this.currentPhaseName === name) {
-			this.currentPhaseName = null;
-		}
-
-		this.emit("phase:failed", {
-			type: "phase:failed",
-			phase,
-		} as PhaseLifecycleEvent);
-	}
-
-	/**
-	 * Complete a phase only if it is currently active. Does not throw if the
-	 * phase is already completed, skipped, or failed.
-	 *
-	 * @param name - Phase name to complete.
-	 * @param metrics - Optional metrics to merge/update.
-	 */
-	completeIfActive(name: string, metrics?: Partial<PhaseMetrics>): void {
-		const phase = this.phases.find((p) => p.name === name);
-		if (phase && phase.status === "active") {
-			this.complete(name, metrics);
-		}
-	}
-
-	/**
-	 * Get all phases.
-	 * @returns Copy of phases array.
-	 */
-	getPhases(): Phase[] {
-		return [...this.phases];
-	}
-
-	/**
-	 * Get phases filtered by status.
-	 * @param status - Status to filter by.
-	 * @returns Filtered phases.
-	 */
-	getPhasesByStatus(status: PhaseStatus): Phase[] {
-		return this.phases.filter((p) => p.status === status);
-	}
-
-	/**
-	 * Get the current active phase.
-	 * @returns Current phase or null if none active.
-	 */
-	getCurrentPhase(): Phase | null {
-		return this.phases.find((p) => p.status === "active") ?? null;
-	}
-
-	/**
-	 * Get a specific phase by name.
-	 * @param name - Phase name.
-	 * @returns Phase or undefined.
-	 */
-	getPhase(name: string): Phase | undefined {
-		return this.phases.find((p) => p.name === name);
-	}
-
-	/**
-	 * Get metrics for a phase.
-	 * @param name - Phase name.
-	 * @returns Metrics or undefined.
-	 */
-	getMetrics(name: string): PhaseMetrics | undefined {
-		return this.phaseMetrics.get(name);
-	}
-
-	/**
-	 * Update metrics for the current phase.
-	 * @param updates - Partial metrics to merge.
-	 */
-	updateCurrentMetrics(updates: Partial<PhaseMetrics>): void {
-		if (!this.currentPhaseName) return;
-		const existing = this.phaseMetrics.get(this.currentPhaseName) ?? emptyMetrics();
-		const updated: PhaseMetrics = {
-			tasksCompleted: updates.tasksCompleted ?? existing.tasksCompleted,
-			tasksFailed: updates.tasksFailed ?? existing.tasksFailed,
-			tokensUsed: updates.tokensUsed ?? existing.tokensUsed,
-			subagentsSpawned: updates.subagentsSpawned ?? existing.subagentsSpawned,
-			custom: { ...existing.custom, ...updates.custom },
-		};
-		this.phaseMetrics.set(this.currentPhaseName, updated);
-		const phase = this.getPhase(this.currentPhaseName);
-		if (phase) {
-			phase.metrics = updated;
-		}
-	}
-
-	/**
-	 * Add tokens to the current phase's metrics.
-	 * @param tokens - Number of tokens to add.
-	 */
-	addTokensToCurrent(tokens: number): void {
-		if (!this.currentPhaseName) return;
-		const existing = this.phaseMetrics.get(this.currentPhaseName) ?? emptyMetrics();
-		existing.tokensUsed = (existing.tokensUsed ?? 0) + tokens;
-		this.phaseMetrics.set(this.currentPhaseName, existing);
-		const phase = this.getPhase(this.currentPhaseName);
-		if (phase) {
-			phase.metrics = existing;
-		}
-	}
-
-	/**
-	 * Get total duration across all completed phases.
-	 * @returns Total milliseconds or 0.
-	 */
-	totalDuration(): number {
-		return this.phases.reduce((sum, p) => sum + (p.durationMs ?? 0), 0);
-	}
-
-	/**
-	 * Get summary statistics for all phases.
-	 * @returns Summary object.
-	 */
-	summary(): {
-		totalPhases: number;
-		active: number;
-		completed: number;
-		skipped: number;
-		failed: number;
-		totalDurationMs: number;
-	} {
-		return {
-			totalPhases: this.phases.length,
-			active: this.phases.filter((p) => p.status === "active").length,
-			completed: this.phases.filter((p) => p.status === "completed").length,
-			skipped: this.phases.filter((p) => p.status === "skipped").length,
-			failed: this.phases.filter((p) => p.status === "failed").length,
-			totalDurationMs: this.totalDuration(),
-		};
-	}
-
-	/**
-	 * Check if a phase exists.
-	 * @param name - Phase name.
-	 * @returns True if phase exists.
-	 */
-	hasPhase(name: string): boolean {
-		return this.phases.some((p) => p.name === name);
-	}
-
-	/**
-	 * Reset all phases (for testing or recovery).
-	 */
-	reset(): void {
-		this.phases = [];
-		this.currentPhaseName = null;
-		this.phaseMetrics.clear();
-	}
-
-	/**
-	 * Dispose of resources (EventEmitter listeners).
-	 * Call this when the tracker is no longer needed.
-	 */
-	dispose(): void {
-		this.removeAllListeners();
-		this.phases = [];
-		this.currentPhaseName = null;
-		this.phaseMetrics.clear();
-	}
-}