pi-crew 0.9.50 → 0.9.52

package/src/runtime/handoff-manager.ts

@@ -1,598 +0,0 @@
-// HandoffManager defaults
-const DEFAULT_SUMMARIZE_THRESHOLD = 5000;
-const DEFAULT_HANDOVER_TIMEOUT_MS = 300000; // 5 minutes
-const DEFAULT_CLEANUP_INTERVAL_MS = 60000; // 1 minute
-const MAX_PENDING_HANDOFFS = 1000; // Prevent unbounded growth
-
-/**
- * Type guard for HandoffSummary structure validation.
- */
-export function isValidHandoffSummary(value: unknown): value is HandoffSummary {
-	if (!value || typeof value !== "object") {
-		return false;
-	}
-	const obj = value as Record<string, unknown>;
-
-	// Check required fields
-	if (typeof obj.taskId !== "string" || !obj.taskId) return false;
-	if (typeof obj.runId !== "string" || !obj.runId) return false;
-	if (typeof obj.timestamp !== "number") return false;
-	if (typeof obj.task !== "string" || !obj.task) return false;
-	if (typeof obj.outcome !== "string") return false;
-	if (!["success", "failure", "partial"].includes(obj.outcome)) return false;
-
-	// Check arrays
-	if (!Array.isArray(obj.filesCreated)) return false;
-	if (!Array.isArray(obj.filesModified)) return false;
-	if (!Array.isArray(obj.filesDeleted)) return false;
-	if (!Array.isArray(obj.decisions)) return false;
-	if (!Array.isArray(obj.blockers)) return false;
-	if (!Array.isArray(obj.nextSteps)) return false;
-
-	// Check metrics object
-	if (!obj.metrics || typeof obj.metrics !== "object") return false;
-	const metrics = obj.metrics as Record<string, unknown>;
-	if (typeof metrics.tokensUsed !== "number") return false;
-	if (typeof metrics.duration !== "number") return false;
-	if (typeof metrics.iterations !== "number") return false;
-	if (!Array.isArray(metrics.toolsUsed)) return false;
-
-	// Check contextSnapshot
-	if (typeof obj.contextSnapshot !== "string") return false;
-
-	return true;
-}
-
-/**
- * HandoffManager - Generates structured summaries for agent handoffs.
- *
- * Based on pi-boomerang's session_before_tree hook pattern:
- * - Detects task completion via agent_end hook
- * - Generates structured summaries with token metrics, artifacts, decisions
- * - Optionally collapses context to reduce token usage
- *
- * @see docs/pi-boomerang-integration-plan.md
- */
-
-/**
- * Represents a key decision made during task execution.
- */
-export interface Decision {
-	rationale: string;
-	outcome: string;
-	alternativesConsidered: string[];
-}
-
-/**
- * Structured handoff summary for passing context between agents.
- */
-export interface HandoffSummary {
-	taskId: string;
-	runId: string;
-	timestamp: number;
-
-	// Core summary
-	task: string;
-	outcome: "success" | "failure" | "partial";
-
-	// Structured artifacts
-	filesCreated: string[];
-	filesModified: string[];
-	filesDeleted: string[];
-
-	// Key decisions made
-	decisions: Decision[];
-
-	// Open issues / next steps
-	blockers: string[];
-	nextSteps: string[];
-
-	// Metrics
-	metrics: {
-		tokensUsed: number;
-		duration: number;
-		iterations: number;
-		toolsUsed: string[];
-	};
-
-	// Context snapshot
-	contextSnapshot: string;
-
-	/** Worker output text propagated through the chain (read from resultArtifact). */
-	outputText?: string;
-}
-
-/**
- * Task result interface (simplified for handoff generation).
- */
-export interface TaskResult {
-	outcome: "success" | "failure" | "partial";
-	usage?: {
-		inputTokens?: number;
-		outputTokens?: number;
-		totalTokens?: number;
-	};
-	duration?: number;
-	iterations?: number;
-	toolsUsed?: string[];
-	blockers?: string[];
-	nextSteps?: string[];
-	filesCreated?: string[];
-	filesModified?: string[];
-	filesDeleted?: string[];
-	decisions?: Decision[];
-	error?: string;
-
-	/** Worker's textual output (read from resultArtifact during chain execution). */
-	outputText?: string;
-}
-
-/**
- * Task packet interface (minimal for handoff generation).
- */
-export interface TaskPacket {
-	taskId: string;
-	runId: string;
-	goal: string;
-	sessionId?: string;
-	summarizeThreshold?: number;
-	collapseContext?: boolean;
-	forceSummarize?: boolean;
-	context?: Record<string, unknown>;
-}
-
-export interface HandoffManagerOptions {
-	/** Default token threshold for triggering summarization */
-	defaultSummarizeThreshold?: number;
-	/** Enable context collapse after handoff */
-	enableContextCollapse?: boolean;
-	/** Custom event emitter for handoff events */
-	eventEmitter?: HandoffEventEmitter;
-	/** Timeout for pending handoffs in ms (default: 300000 = 5 minutes) */
-	handoffTimeoutMs?: number;
-	/** Interval for cleanup of old pending handoffs in ms (default: 60000 = 1 minute) */
-	cleanupIntervalMs?: number;
-}
-
-export interface HandoffEventEmitter {
-	emit(event: string, data: unknown): void;
-}
-
-/**
- * Result of shouldSummarize check.
- */
-export interface SummarizeDecision {
-	shouldSummarize: boolean;
-	reason: string;
-	tokenCount: number;
-}
-
-/**
- * HandoffManager generates structured summaries when agents complete tasks,
- * enabling efficient context passing to subsequent agents.
- *
- * H1: Includes memory management to prevent unbounded growth of pendingHandoffs Map.
- */
-export class HandoffManager {
-	private pendingHandoffs = new Map<string, HandoffSummary>();
-	private options: HandoffManagerOptions;
-	private handoffTimestamps = new Map<string, number>(); // Track when handoffs were added
-	private cleanupTimer: ReturnType<typeof setInterval> | null = null;
-	private disposed = false;
-
-	constructor(options: HandoffManagerOptions = {}) {
-		this.options = {
-			defaultSummarizeThreshold: DEFAULT_SUMMARIZE_THRESHOLD,
-			handoffTimeoutMs: DEFAULT_HANDOVER_TIMEOUT_MS,
-			cleanupIntervalMs: DEFAULT_CLEANUP_INTERVAL_MS,
-			...options,
-		};
-
-		// Start cleanup timer
-		this.startCleanupTimer();
-	}
-
-	/**
-	 * Start the periodic cleanup timer for stale pending handoffs.
-	 * H1: Prevents memory leak by clearing old entries.
-	 */
-	private startCleanupTimer(): void {
-		if (this.disposed) {
-			return;
-		}
-		if (this.cleanupTimer) {
-			return;
-		}
-		this.cleanupTimer = setInterval(() => {
-			this.cleanupStaleHandoffs();
-		}, this.options.cleanupIntervalMs);
-		// FIX (BG2 hang): without .unref(), the cleanup interval keeps the Node
-		// event loop alive forever — tests that create HandoffManager without
-		// calling dispose() (e.g. chain-runner.test.ts mock helper that does
-		// `return new HandoffManager()`) leak an interval per test, and the
-		// file-level test never completes because Node waits for all handles
-		// to close. .unref() lets the process exit when nothing else is pending
-		// — this is the standard Node.js pattern for background timers.
-		if (typeof this.cleanupTimer.unref === "function") {
-			this.cleanupTimer.unref();
-		}
-	}
-
-	/**
-	 * Clean up stale pending handoffs that have exceeded the timeout.
-	 * H1: Prevents memory leak by removing old entries.
-	 * FIX: Iterate over entries() instead of mutating Map during iteration.
-	 */
-	private cleanupStaleHandoffs(): void {
-		if (this.disposed) return;
-
-		const now = Date.now();
-		const timeout = this.options.handoffTimeoutMs ?? DEFAULT_HANDOVER_TIMEOUT_MS;
-		const cutoff = now - timeout;
-
-		// Collect keys to delete to avoid mutation during iteration
-		const toDelete: string[] = [];
-		for (const [sessionId, timestamp] of this.handoffTimestamps.entries()) {
-			if (timestamp < cutoff) {
-				toDelete.push(sessionId);
-			}
-		}
-		for (const sessionId of toDelete) {
-			this.pendingHandoffs.delete(sessionId);
-			this.handoffTimestamps.delete(sessionId);
-		}
-
-		// Also enforce max handoffs limit
-		if (this.pendingHandoffs.size > MAX_PENDING_HANDOFFS) {
-			// Remove oldest entries
-			const sortedEntries = [...this.handoffTimestamps.entries()].sort((a, b) => a[1] - b[1]);
-			const removeCount = sortedEntries.length - MAX_PENDING_HANDOFFS;
-			for (let i = 0; i < removeCount; i++) {
-				const sessionId = sortedEntries[i][0];
-				this.pendingHandoffs.delete(sessionId);
-				this.handoffTimestamps.delete(sessionId);
-			}
-		}
-	}
-
-	/**
-	 * Hook: agent_end
-	 * Called when agent completes a task.
-	 *
-	 * @param packet - The task packet
-	 * @param result - The task result
-	 */
-	async onAgentEnd(packet: TaskPacket, result: TaskResult): Promise<HandoffSummary | null> {
-		if (this.disposed) {
-			return null;
-		}
-
-		// Check if summarization is needed
-		if (!this.shouldSummarize(packet, result).shouldSummarize) {
-			return null;
-		}
-
-		// Generate handoff summary
-		const summary = await this.generateSummary(packet, result);
-
-		// H7: Validate generated summary structure
-		if (!isValidHandoffSummary(summary)) {
-			this.options.eventEmitter?.emit("handoff:validation_failed", {
-				packet,
-				error: "Generated summary failed structure validation",
-			});
-			return null;
-		}
-
-		// Store pending handoff for tree navigation
-		if (packet.sessionId) {
-			this.pendingHandoffs.set(packet.sessionId, summary);
-			this.handoffTimestamps.set(packet.sessionId, Date.now());
-		}
-
-		// Emit handoff event
-		this.options.eventEmitter?.emit("handoff:generated", {
-			packet,
-			summary,
-		});
-
-		// Optionally collapse context
-		if (packet.collapseContext) {
-			await this.collapseContext(packet, summary);
-		}
-
-		return summary;
-	}
-
-	/**
-	 * Hook: session_before_tree
-	 * Called before navigating to tree view.
-	 * Injects pending handoff summaries into the tree.
-	 *
-	 * @param sessionId - The session ID
-	 * @param targetId - The target tree node ID
-	 */
-	async onBeforeTreeNavigation(sessionId: string, targetId: string): Promise<HandoffSummary | null> {
-		if (this.disposed) {
-			return null;
-		}
-
-		const pendingHandoff = this.pendingHandoffs.get(sessionId);
-
-		if (pendingHandoff) {
-			// Clear the pending handoff after injection
-			this.pendingHandoffs.delete(sessionId);
-			this.handoffTimestamps.delete(sessionId);
-			return pendingHandoff;
-		}
-
-		return null;
-	}
-
-	/**
-	 * Check if summarization should be performed.
-	 * H7: Validates input parameters before generating summary.
-	 */
-	shouldSummarize(packet: TaskPacket, result: TaskResult): SummarizeDecision {
-		// H7: Validate packet structure
-		if (!packet || typeof packet.taskId !== "string" || !packet.taskId) {
-			return {
-				shouldSummarize: false,
-				reason: "Invalid task packet structure",
-				tokenCount: 0,
-			};
-		}
-
-		// H7: Validate result structure
-		if (!result || typeof result.outcome !== "string") {
-			return {
-				shouldSummarize: false,
-				reason: "Invalid task result structure",
-				tokenCount: 0,
-			};
-		}
-
-		const threshold = packet.summarizeThreshold ?? this.options.defaultSummarizeThreshold ?? DEFAULT_SUMMARIZE_THRESHOLD;
-		const tokenCount = result.usage?.totalTokens ?? 0;
-
-		// Summarize if:
-		// 1. Task exceeded threshold tokens
-		if (tokenCount > threshold) {
-			return {
-				shouldSummarize: true,
-				reason: `Token count ${tokenCount} exceeds threshold ${threshold}`,
-				tokenCount,
-			};
-		}
-
-		// 2. Task completed with significant work (3 or more tools used)
-		if (result.outcome === "success" && (result.toolsUsed?.length ?? 0) >= 3) {
-			return {
-				shouldSummarize: true,
-				reason: `Task used ${result.toolsUsed?.length ?? 0} tools, exceeding minimum of 3`,
-				tokenCount,
-			};
-		}
-
-		// 3. Explicitly requested
-		if (packet.forceSummarize === true) {
-			return {
-				shouldSummarize: true,
-				reason: "Forced summarization requested",
-				tokenCount,
-			};
-		}
-
-		// 4. Task has significant artifacts or decisions
-		const hasArtifacts = (result.filesCreated?.length ?? 0) > 0 || (result.filesModified?.length ?? 0) > 0;
-		const hasDecisions = (result.decisions?.length ?? 0) > 0;
-
-		if (hasArtifacts || hasDecisions) {
-			return {
-				shouldSummarize: true,
-				reason: "Task produced significant artifacts or decisions",
-				tokenCount,
-			};
-		}
-
-		// 5. Task outcome is not success (failure or partial)
-		if (result.outcome !== "success") {
-			return {
-				shouldSummarize: true,
-				reason: `Task outcome is ${result.outcome}`,
-				tokenCount,
-			};
-		}
-
-		return {
-			shouldSummarize: false,
-			reason: "Task below summarization threshold",
-			tokenCount,
-		};
-	}
-
-	/**
-	 * Generate a structured handoff summary.
-	 */
-	async generateSummary(packet: TaskPacket, result: TaskResult): Promise<HandoffSummary> {
-		const artifacts = this.extractArtifacts(result);
-		// Use extractDecisionsFromResult to handle empty array and generate defaults
-		const decisions = this.extractDecisionsFromResult(result);
-		const contextSnapshot = await this.generateContextSnapshot(packet.runId, packet.taskId, result);
-
-		return {
-			taskId: packet.taskId,
-			runId: packet.runId,
-			timestamp: Date.now(),
-
-			task: packet.goal,
-			outcome: result.outcome,
-
-			filesCreated: artifacts.created,
-			filesModified: artifacts.modified,
-			filesDeleted: artifacts.deleted,
-
-			decisions,
-			blockers: result.blockers ?? [],
-			nextSteps: result.nextSteps ?? [],
-
-			metrics: {
-				tokensUsed: result.usage?.totalTokens ?? 0,
-				duration: result.duration ?? 0,
-				iterations: result.iterations ?? 1,
-				toolsUsed: result.toolsUsed ?? [],
-			},
-
-			contextSnapshot,
-			...(result.outputText ? { outputText: result.outputText } : {}),
-		};
-	}
-
-	/**
-	 * Collapse context after handoff.
-	 * Signals to other extensions not to prompt during collapse.
-	 */
-	async collapseContext(packet: TaskPacket, summary: HandoffSummary): Promise<void> {
-		// Set global flag to signal collapse in progress
-		(globalThis as Record<string, unknown>).__boomerangCollapseInProgress = true;
-
-		try {
-			// Emit event that context will be collapsed
-			this.options.eventEmitter?.emit("handoff:context_collapse", {
-				sessionId: packet.sessionId,
-				taskId: packet.taskId,
-				summary,
-			});
-		} finally {
-			// Clear the flag
-			(globalThis as Record<string, unknown>).__boomerangCollapseInProgress = false;
-		}
-	}
-
-	/**
-	 * Get pending handoff for a session.
-	 */
-	getPendingHandoff(sessionId: string): HandoffSummary | undefined {
-		return this.pendingHandoffs.get(sessionId);
-	}
-
-	/**
-	 * Clear pending handoff for a session.
-	 */
-	clearPendingHandoff(sessionId: string): void {
-		this.pendingHandoffs.delete(sessionId);
-		this.handoffTimestamps.delete(sessionId);
-	}
-
-	/**
-	 * Clear all pending handoffs.
-	 * H1: Manual cleanup method for memory management.
-	 */
-	clearAllPendingHandoffs(): void {
-		this.pendingHandoffs.clear();
-		this.handoffTimestamps.clear();
-	}
-
-	/**
-	 * Get the count of pending handoffs.
-	 * Useful for monitoring and debugging.
-	 */
-	getPendingCount(): number {
-		return this.pendingHandoffs.size;
-	}
-
-	/**
-	 * Extract file artifacts from task result.
-	 */
-	private extractArtifacts(result: TaskResult): {
-		created: string[];
-		modified: string[];
-		deleted: string[];
-	} {
-		return {
-			created: result.filesCreated ?? [],
-			modified: result.filesModified ?? [],
-			deleted: result.filesDeleted ?? [],
-		};
-	}
-
-	/**
-	 * Extract decisions from task result.
-	 */
-	private extractDecisionsFromResult(result: TaskResult): Decision[] {
-		if (result.decisions && result.decisions.length > 0) {
-			return result.decisions;
-		}
-
-		// Generate a default decision for failure outcomes
-		if (result.outcome === "failure") {
-			return [
-				{
-					rationale: "Task failed",
-					outcome: result.error ?? "Unknown error",
-					alternativesConsidered: [],
-				},
-			];
-		}
-
-		return [];
-	}
-
-	/**
-	 * Generate context snapshot for handoff.
-	 */
-	private async generateContextSnapshot(runId: string, taskId: string, result: TaskResult): Promise<string> {
-		const parts: string[] = [];
-
-		parts.push(`Task: ${taskId}`);
-		parts.push(`Outcome: ${result.outcome}`);
-
-		if (result.usage?.totalTokens) {
-			parts.push(`Tokens: ${result.usage.totalTokens}`);
-		}
-
-		if (result.toolsUsed?.length) {
-			parts.push(`Tools: ${result.toolsUsed.join(", ")}`);
-		}
-
-		if (result.blockers?.length) {
-			parts.push(`Blockers: ${result.blockers.join("; ")}`);
-		}
-
-		if (result.nextSteps?.length) {
-			parts.push(`Next Steps: ${result.nextSteps.join("; ")}`);
-		}
-
-		return parts.join("\n");
-	}
-
-	/**
-	 * H8: Dispose of resources. Call when manager is no longer needed.
-	 * Clears all pending handoffs and stops cleanup timer.
-	 */
-	dispose(): void {
-		this.disposed = true;
-
-		if (this.cleanupTimer) {
-			clearInterval(this.cleanupTimer);
-			this.cleanupTimer = null;
-		}
-
-		this.pendingHandoffs.clear();
-		this.handoffTimestamps.clear();
-	}
-
-	/**
-	 * Check if the manager has been disposed.
-	 */
-	isDisposed(): boolean {
-		return this.disposed;
-	}
-}
-
-/**
- * Create a HandoffManager with default options.
- */
-export function createHandoffManager(options?: HandoffManagerOptions): HandoffManager {
-	return new HandoffManager(options);
-}

package/src/runtime/heartbeat-gradient.ts

@@ -1,36 +0,0 @@
-import type { WorkerHeartbeatState } from "./worker-heartbeat.ts";
-
-export type HeartbeatLevel = "healthy" | "warn" | "stale" | "dead";
-
-export interface GradientThresholds {
-	warnMs: number;
-	staleMs: number;
-	deadMs: number;
-}
-
-export const DEFAULT_GRADIENT_THRESHOLDS: GradientThresholds = {
-	warnMs: 30_000,
-	staleMs: 60_000,
-	deadMs: 300_000,
-};
-
-export function heartbeatAgeMs(heartbeat: WorkerHeartbeatState | undefined, now = Date.now()): number {
-	if (!heartbeat) return Number.POSITIVE_INFINITY;
-	const lastSeen = Date.parse(heartbeat.lastSeenAt);
-	return Number.isFinite(lastSeen) ? Math.max(0, now - lastSeen) : Number.POSITIVE_INFINITY;
-}
-
-export function classifyHeartbeat(
-	heartbeat: WorkerHeartbeatState | undefined,
-	thresholds: GradientThresholds = DEFAULT_GRADIENT_THRESHOLDS,
-	now = Date.now(),
-): HeartbeatLevel {
-	if (!heartbeat) return "dead";
-	if (heartbeat.alive === false) return "dead";
-	const elapsed = heartbeatAgeMs(heartbeat, now);
-	if (!Number.isFinite(elapsed)) return "dead";
-	if (elapsed > thresholds.deadMs) return "dead";
-	if (elapsed > thresholds.staleMs) return "stale";
-	if (elapsed > thresholds.warnMs) return "warn";
-	return "healthy";
-}