pi-crew 0.5.5 → 0.5.6

package/src/runtime/auto-summarize.ts

@@ -0,0 +1,350 @@
+/**
+ * AutoSummarizeService - Enables auto-summarization with token/tool thresholds.
+ * 
+ * Based on pi-boomerang's autoBoomerang pattern:
+ * - toggle() enables/disables auto-summarization
+ * - shouldAutoSummarize() checks if task should auto-summarize
+ * - Token and tool thresholds control when summarization triggers
+ * 
+ * @see docs/pi-boomerang-integration-plan.md
+ */
+
+import type { TaskPacket, TaskResult } from "./handoff-manager.ts";
+
+/**
+ * Configuration for AutoSummarizeService.
+ */
+export interface AutoSummarizeConfig {
+	/** Whether auto-summarize is enabled */
+	enabled: boolean;
+	/** Token threshold to trigger summarization */
+	threshold: number;
+	/** Minimum tools used to trigger summarization (default: 5) */
+	minToolsUsed?: number;
+	/** Whether to collapse context after summarization */
+	collapseContext?: boolean;
+}
+
+/**
+ * Default configuration values.
+ */
+export const DEFAULT_AUTO_SUMMARIZE_CONFIG: Required<Omit<AutoSummarizeConfig, "enabled">> = {
+	threshold: 5000,
+	minToolsUsed: 5,
+	collapseContext: true,
+};
+
+/**
+ * Options for AutoSummarizeService.
+ */
+export interface AutoSummarizeServiceOptions {
+	/** Initial configuration */
+	config?: Partial<AutoSummarizeConfig>;
+	/** Custom event emitter */
+	eventEmitter?: AutoSummarizeEventEmitter;
+}
+
+/**
+ * Event emitter for auto-summarize events.
+ */
+export interface AutoSummarizeEventEmitter {
+	emit(event: string, data: unknown): void;
+}
+
+/**
+ * Event data for auto-summarize toggle event.
+ */
+export interface AutoSummarizeToggledEventData {
+	enabled: boolean;
+	previousEnabled: boolean;
+}
+
+/**
+ * Event data for auto-summarize triggered event.
+ */
+export interface AutoSummarizeTriggeredEventData {
+	packet: TaskPacket;
+	result: TaskResult;
+	trigger: AutoSummarizeTrigger;
+	tokenCount: number;
+}
+
+/**
+ * What triggered the auto-summarize.
+ */
+export type AutoSummarizeTrigger =
+	| "token_threshold"
+	| "tools_threshold"
+	| "manual"
+	| "high_usage";
+
+/**
+ * AutoSummarizeService enables automatic summarization based on configurable thresholds.
+ * When enabled, it monitors task completion and triggers summarization for tasks
+ * that exceed token or tool usage thresholds.
+ */
+export class AutoSummarizeService {
+	private config: AutoSummarizeConfig & Required<Omit<AutoSummarizeConfig, "enabled">>;
+	private eventEmitter: AutoSummarizeEventEmitter | null = null;
+
+	constructor(options: AutoSummarizeServiceOptions = {}) {
+		this.config = {
+			enabled: options.config?.enabled ?? false,
+			threshold: options.config?.threshold ?? DEFAULT_AUTO_SUMMARIZE_CONFIG.threshold,
+			minToolsUsed: options.config?.minToolsUsed ?? DEFAULT_AUTO_SUMMARIZE_CONFIG.minToolsUsed,
+			collapseContext: options.config?.collapseContext ?? DEFAULT_AUTO_SUMMARIZE_CONFIG.collapseContext,
+		};
+
+		if (options.eventEmitter) {
+			this.eventEmitter = options.eventEmitter;
+		}
+	}
+
+	/**
+	 * Check if auto-summarization is currently enabled.
+	 */
+	isEnabled(): boolean {
+		return this.config.enabled;
+	}
+
+	/**
+	 * Toggle auto-summarize mode.
+	 * Returns the new enabled state.
+	 */
+	toggle(): boolean {
+		const previousEnabled = this.config.enabled;
+		this.config.enabled = !this.config.enabled;
+
+		this.eventEmitter?.emit("auto-summarize:toggled", {
+			enabled: this.config.enabled,
+			previousEnabled,
+		} as AutoSummarizeToggledEventData);
+
+		return this.config.enabled;
+	}
+
+	/**
+	 * Enable auto-summarize.
+	 */
+	enable(): void {
+		if (!this.config.enabled) {
+			this.toggle();
+		}
+	}
+
+	/**
+	 * Disable auto-summarize.
+	 */
+	disable(): void {
+		if (this.config.enabled) {
+			this.toggle();
+		}
+	}
+
+	/**
+	 * Check if a task should auto-summarize.
+	 * 
+	 * @param packet - The task packet
+	 * @param result - The task result
+	 * @returns True if the task should auto-summarize
+	 */
+	shouldAutoSummarize(packet: TaskPacket, result: TaskResult): boolean {
+		if (!this.config.enabled) {
+			return false;
+		}
+
+		const tokenCount = result.usage?.totalTokens ?? 0;
+
+		// Check token threshold
+		if (tokenCount >= this.config.threshold) {
+			return true;
+		}
+
+		// Check tools threshold
+		const toolsUsed = result.toolsUsed?.length ?? 0;
+		if (toolsUsed >= (this.config.minToolsUsed ?? 5)) {
+			return true;
+		}
+
+		// High usage check: high token count relative to tools
+		// More tokens per tool suggests complex work that should be summarized
+		if (tokenCount > 2000 && toolsUsed >= 3) {
+			const tokensPerTool = tokenCount / toolsUsed;
+			if (tokensPerTool > 1000) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Get the reason why a task should (or should not) auto-summarize.
+	 * 
+	 * @param packet - The task packet
+	 * @param result - The task result
+	 * @returns Object with shouldSummarize flag and reason
+	 */
+	getAutoSummarizeDecision(packet: TaskPacket, result: TaskResult): AutoSummarizeDecision {
+		if (!this.config.enabled) {
+			return {
+				shouldSummarize: false,
+				reason: "auto-summarize is disabled",
+				trigger: undefined,
+				tokenCount: result.usage?.totalTokens ?? 0,
+				toolsUsed: result.toolsUsed?.length ?? 0,
+			};
+		}
+
+		const tokenCount = result.usage?.totalTokens ?? 0;
+		const toolsUsed = result.toolsUsed?.length ?? 0;
+
+		// Check token threshold
+		if (tokenCount >= this.config.threshold) {
+			return {
+				shouldSummarize: true,
+				reason: `Token count ${tokenCount} exceeds threshold ${this.config.threshold}`,
+				trigger: "token_threshold",
+				tokenCount,
+				toolsUsed,
+			};
+		}
+
+		// Check tools threshold
+		const minTools = this.config.minToolsUsed ?? 5;
+		if (toolsUsed >= minTools) {
+			return {
+				shouldSummarize: true,
+				reason: `Tool count ${toolsUsed} meets minimum ${minTools}`,
+				trigger: "tools_threshold",
+				tokenCount,
+				toolsUsed,
+			};
+		}
+
+		// High usage check
+		if (tokenCount > 2000 && toolsUsed >= 3) {
+			const tokensPerTool = tokenCount / toolsUsed;
+			if (tokensPerTool > 1000) {
+				return {
+					shouldSummarize: true,
+					reason: `High token-to-tool ratio: ${Math.round(tokensPerTool)} tokens/tool`,
+					trigger: "high_usage",
+					tokenCount,
+					toolsUsed,
+				};
+			}
+		}
+
+		return {
+			shouldSummarize: false,
+			reason: `Below thresholds (tokens: ${tokenCount}/${this.config.threshold}, tools: ${toolsUsed}/${minTools})`,
+			trigger: undefined,
+			tokenCount,
+			toolsUsed,
+		};
+	}
+
+	/**
+	 * Get the current configuration.
+	 */
+	getConfig(): AutoSummarizeConfig & Required<Omit<AutoSummarizeConfig, "enabled">> {
+		return { ...this.config };
+	}
+
+	/**
+	 * Update configuration.
+	 */
+	updateConfig(config: Partial<AutoSummarizeConfig>): void {
+		const previousEnabled = this.config.enabled;
+
+		if (config.enabled !== undefined) {
+			this.config.enabled = config.enabled;
+		}
+		if (config.threshold !== undefined) {
+			this.config.threshold = config.threshold;
+		}
+		if (config.minToolsUsed !== undefined) {
+			this.config.minToolsUsed = config.minToolsUsed;
+		}
+		if (config.collapseContext !== undefined) {
+			this.config.collapseContext = config.collapseContext;
+		}
+
+		// Emit event if enabled state changed
+		if (config.enabled !== undefined && config.enabled !== previousEnabled) {
+			this.eventEmitter?.emit("auto-summarize:toggled", {
+				enabled: this.config.enabled,
+				previousEnabled,
+			} as AutoSummarizeToggledEventData);
+		}
+	}
+
+	/**
+	 * Get current threshold value.
+	 */
+	getThreshold(): number {
+		return this.config.threshold;
+	}
+
+	/**
+	 * Set token threshold.
+	 */
+	setThreshold(threshold: number): void {
+		if (threshold < 0) {
+			throw new Error("Threshold must be non-negative");
+		}
+		this.config.threshold = threshold;
+	}
+
+	/**
+	 * Get current minToolsUsed value.
+	 */
+	getMinToolsUsed(): number {
+		return this.config.minToolsUsed ?? 5;
+	}
+
+	/**
+	 * Set minimum tools threshold.
+	 */
+	setMinToolsUsed(minTools: number): void {
+		if (minTools < 0) {
+			throw new Error("minToolsUsed must be non-negative");
+		}
+		this.config.minToolsUsed = minTools;
+	}
+
+	/**
+	 * Check if context should be collapsed after summarization.
+	 */
+	shouldCollapseContext(): boolean {
+		return this.config.collapseContext ?? true;
+	}
+
+	/**
+	 * Set event emitter.
+	 */
+	setEventEmitter(eventEmitter: AutoSummarizeEventEmitter): void {
+		this.eventEmitter = eventEmitter;
+	}
+}
+
+/**
+ * Decision result from shouldAutoSummarize check.
+ */
+export interface AutoSummarizeDecision {
+	shouldSummarize: boolean;
+	reason: string;
+	trigger: AutoSummarizeTrigger | undefined;
+	tokenCount: number;
+	toolsUsed: number;
+}
+
+/**
+ * Create an AutoSummarizeService with default options.
+ */
+export function createAutoSummarizeService(
+	options?: AutoSummarizeServiceOptions,
+): AutoSummarizeService {
+	return new AutoSummarizeService(options);
+}

package/src/runtime/background-runner.ts

@@ -24,6 +24,7 @@ import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
 import { expandParallelResearchWorkflow } from "./parallel-research.ts";
 import { writeAsyncStartMarker } from "./async-marker.ts";
 import { startParentGuard, stopParentGuard } from "./parent-guard.ts";
+import { logInternalError } from "../utils/internal-error.ts";
 
 /**
  * Heartbeat mechanism: periodically write a heartbeat file so the stale reconciler
@@ -323,7 +324,7 @@ async function main(): Promise<void> {
 			if (loaded) {
 				// LAZY: live-agent-manager only needed on failure cleanup path; avoid module load at hot path.
 				const { terminateLiveAgentsForRun } = await import("./live-agent-manager.ts");
-				void terminateLiveAgentsForRun(loaded.manifest.runId, "failed", appendEvent, loaded.manifest.eventsPath).catch(() => {});
+				void terminateLiveAgentsForRun(loaded.manifest.runId, "failed", appendEvent, loaded.manifest.eventsPath).catch((error) => logInternalError("background-runner.terminate", error, `runId=${loaded.manifest.runId}`));
 			}
 		} catch { /* best-effort */ }
 		const message = error instanceof Error ? error.message : String(error);

package/src/runtime/budget-tracker.ts

@@ -0,0 +1,354 @@
+/**
+ * Budget Tracker — token budget tracking for team/subagent execution.
+ *
+ * Tracks token usage with configurable warning (default 80%) and abort
+ * (default 95%) thresholds. Provides spent(), remaining(), warning(),
+ * exhausted(), and createAbortSignal() for integration with team-runner.
+ *
+ * @file src/runtime/budget-tracker.ts
+ */
+
+import { EventEmitter } from "node:events";
+
+/** Budget configuration passed to TeamBudgetTracker constructor. */
+export interface BudgetConfig {
+  /** Total token budget for the run. */
+  total: number;
+  /** Warning threshold as fraction of total (default: 0.8 = 80%). */
+  warningThreshold?: number;
+  /** Abort threshold as fraction of total (default: 0.95 = 95%). */
+  abortThreshold?: number;
+}
+
+/** Internal phase-level accounting for trackUsage breakdown. */
+interface PhaseUsage {
+  phaseName: string;
+  tokens: number;
+  startTime: number;
+}
+
+/** Public usage record returned by trackUsage. */
+export interface BudgetUsageRecord {
+  /** Total tokens spent after this update. */
+  totalSpent: number;
+  /** Tokens added in this update. */
+  delta: number;
+  /** Warning state after this update. */
+  isWarning: boolean;
+  /** Exhausted state after this update. */
+  isExhausted: boolean;
+}
+
+/** Event emitted when budget crosses thresholds. */
+export interface BudgetEvent {
+  type: "budget:warning" | "budget:exhausted";
+  budget: BudgetSnapshot;
+}
+
+/** Snapshot of budget state for event payloads. */
+export interface BudgetSnapshot {
+  total: number;
+  spent: number;
+  remaining: number;
+  percentUsed: number;
+}
+
+/**
+ * TeamBudgetTracker tracks token usage against a configurable budget.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new TeamBudgetTracker({ total: 100000 });
+ * tracker.trackUsage(5000);
+ * console.log(tracker.spent()); // 5000
+ * console.log(tracker.warning()); // false (50% of 100k)
+ * ```
+ */
+export class TeamBudgetTracker extends EventEmitter {
+  private used = 0;
+  private readonly total: number;
+  private readonly warningThreshold: number;
+  private readonly abortThreshold: number;
+  private phaseUsage: PhaseUsage[] = [];
+  private warningEmitted = false;
+  private exhaustedEmitted = false;
+  private abortController: AbortController | null = null;
+  private abortInterval: NodeJS.Timeout | null = null;
+
+  /**
+   * Create a new budget tracker.
+   * @param config - Budget configuration with total and optional thresholds.
+   */
+  constructor(config: BudgetConfig) {
+    super();
+    this.total = config.total;
+    this.warningThreshold = config.warningThreshold ?? 0.8;
+    this.abortThreshold = config.abortThreshold ?? 0.95;
+  }
+
+  /**
+   * Total budget tokens.
+   */
+  get totalBudget(): number {
+    return this.total;
+  }
+
+  /**
+   * Get total tokens spent.
+   */
+  spent(): number {
+    return this.used;
+  }
+
+  /**
+   * Get remaining tokens.
+   */
+  remaining(): number {
+    return this.total - this.used;
+  }
+
+  /**
+   * Percentage used as decimal (0-1).
+   */
+  percentUsed(): number {
+    return this.total > 0 ? this.used / this.total : 0;
+  }
+
+  /**
+   * Check if usage has crossed the warning threshold.
+   */
+  warning(): boolean {
+    return this.percentUsed() >= this.warningThreshold;
+  }
+
+  /**
+   * Check if usage has crossed the abort threshold.
+   */
+  exhausted(): boolean {
+    return this.percentUsed() >= this.abortThreshold;
+  }
+
+  /**
+   * Check if both warning and exhausted events have been emitted for current usage.
+   */
+  isWarningEmitted(): boolean {
+    return this.warningEmitted;
+  }
+
+  /**
+   * Check if exhausted event has been emitted.
+   */
+  isExhaustedEmitted(): boolean {
+    return this.exhaustedEmitted;
+  }
+
+  /**
+   * Track token usage and emit threshold-crossed events.
+   *
+   * @param tokens - Number of tokens to add to usage.
+   * @param phaseName - Optional phase name for breakdown tracking.
+   * @returns BudgetUsageRecord with updated totals and thresholds.
+   */
+  trackUsage(tokens: number, phaseName?: string): BudgetUsageRecord {
+    if (tokens < 0) {
+      throw new Error("trackUsage: tokens must be non-negative");
+    }
+
+    const prevSpent = this.used;
+    this.used += tokens;
+
+    // Phase-level tracking for breakdown reporting
+    if (phaseName) {
+      const existing = this.phaseUsage.find((p) => p.phaseName === phaseName);
+      if (existing) {
+        existing.tokens += tokens;
+      } else {
+        this.phaseUsage.push({ phaseName, tokens, startTime: Date.now() });
+      }
+    }
+
+    const snapshot: BudgetSnapshot = {
+      total: this.total,
+      spent: this.used,
+      remaining: this.remaining(),
+      percentUsed: this.percentUsed(),
+    };
+
+    // Emit warning event on threshold crossing
+    if (this.warning() && !this.warningEmitted) {
+      this.warningEmitted = true;
+      this.emit("warning", { type: "budget:warning", budget: snapshot } as BudgetEvent);
+    }
+
+    // Emit exhausted event on threshold crossing
+    if (this.exhausted() && !this.exhaustedEmitted) {
+      this.exhaustedEmitted = true;
+      this.emit("exhausted", { type: "budget:exhausted", budget: snapshot } as BudgetEvent);
+    }
+
+    return {
+      totalSpent: this.used,
+      delta: tokens,
+      isWarning: this.warning(),
+      isExhausted: this.exhausted(),
+    };
+  }
+
+  /**
+   * Create an AbortSignal that fires when the budget is exhausted.
+   *
+   * The signal will be aborted automatically once the abort threshold
+   * is crossed. If already exhausted when called, the signal is
+   * immediately aborted.
+   *
+   * @returns AbortSignal that can be passed to subagent execution.
+   */
+  createAbortSignal(): AbortSignal {
+    // If already exhausted, return immediately aborted signal
+    if (this.exhausted()) {
+      const controller = new AbortController();
+      controller.abort(new Error("Budget exhausted before signal creation"));
+      return controller.signal;
+    }
+
+    // Clear any existing interval before creating new one
+    if (this.abortInterval) {
+      clearInterval(this.abortInterval);
+      this.abortInterval = null;
+    }
+
+    // Create controller and set up threshold check
+    this.abortController = new AbortController();
+
+    // Store reference for potential external abort
+    const tracker = this;
+
+    // Return a signal that checks threshold on each access
+    // The actual abort happens once exhausted() first returns true
+    const signal = this.abortController.signal;
+
+    // Set up interval check and store the ID for cleanup
+    this.abortInterval = setInterval(() => {
+      if (tracker.exhausted() && !signal.aborted) {
+        tracker.abortController!.abort(
+          new Error(`Budget exhausted: ${tracker.spent()}/${tracker.total}`),
+        );
+        if (tracker.abortInterval) {
+          clearInterval(tracker.abortInterval);
+          tracker.abortInterval = null;
+        }
+      }
+    }, 1000);
+
+    // Clean up interval when signal is aborted
+    const cleanup = (): void => {
+      if (tracker.abortInterval) {
+        clearInterval(tracker.abortInterval);
+        tracker.abortInterval = null;
+      }
+    };
+    signal.addEventListener("abort", cleanup, { once: true });
+
+    return signal;
+  }
+
+  /**
+   * Get phase-level usage breakdown.
+   * @returns Array of phase usage records.
+   */
+  getPhaseBreakdown(): { phaseName: string; tokens: number }[] {
+    return this.phaseUsage.map((p) => ({
+      phaseName: p.phaseName,
+      tokens: p.tokens,
+    }));
+  }
+
+  /**
+   * Reset usage for re-use (e.g., in testing or recovery scenarios).
+   * Does not reset emitted flags — use resetAll() for full reset.
+   */
+  resetUsage(): void {
+    this.used = 0;
+    this.phaseUsage = [];
+  }
+
+  /**
+   * Full reset including emitted flags.
+   */
+  resetAll(): void {
+    this.used = 0;
+    this.phaseUsage = [];
+    this.warningEmitted = false;
+    this.exhaustedEmitted = false;
+    this.abortController = null;
+    if (this.abortInterval) {
+      clearInterval(this.abortInterval);
+      this.abortInterval = null;
+    }
+  }
+
+  /**
+   * Get current snapshot of budget state.
+   */
+  snapshot(): BudgetSnapshot {
+    return {
+      total: this.total,
+      spent: this.used,
+      remaining: this.remaining(),
+      percentUsed: this.percentUsed(),
+    };
+  }
+
+  /**
+   * Dispose of resources (EventEmitter listeners, timers).
+   * Call this when the tracker is no longer needed.
+   */
+  dispose(): void {
+    this.removeAllListeners();
+    if (this.abortInterval) {
+      clearInterval(this.abortInterval);
+      this.abortInterval = null;
+    }
+    this.abortController = null;
+    this.used = 0;
+    this.phaseUsage = [];
+    this.warningEmitted = false;
+    this.exhaustedEmitted = false;
+  }
+}
+
+/**
+ * Create a BudgetConfig with reasonable defaults.
+ * @param total - Total token budget.
+ * @param warningThreshold - Warning threshold (default 0.8).
+ * @param abortThreshold - Abort threshold (default 0.95).
+ */
+export function createBudgetConfig(
+  total: number,
+  warningThreshold = 0.8,
+  abortThreshold = 0.95,
+): BudgetConfig {
+  return { total, warningThreshold, abortThreshold };
+}
+
+/**
+ * Check if a budget config is valid.
+ * @param config - Budget configuration to validate.
+ */
+export function validateBudgetConfig(config: BudgetConfig): { valid: boolean; error?: string } {
+  if (typeof config.total !== "number" || config.total <= 0) {
+    return { valid: false, error: "total must be a positive number" };
+  }
+  const warning = config.warningThreshold ?? 0.8;
+  const abort = config.abortThreshold ?? 0.95;
+  if (warning < 0 || warning > 1) {
+    return { valid: false, error: "warningThreshold must be between 0 and 1" };
+  }
+  if (abort < 0 || abort > 1) {
+    return { valid: false, error: "abortThreshold must be between 0 and 1" };
+  }
+  if (warning >= abort) {
+    return { valid: false, error: "warningThreshold must be less than abortThreshold" };
+  }
+  return { valid: true };
+}