pi-crew 0.9.55 → 0.9.57

package/src/runtime/hidden-handoff.ts

@@ -1,407 +0,0 @@
-/**
- * HiddenHandoffService - Sends hidden boomerang-handoff messages to parent agents.
- *
- * Based on pi-boomerang's triggerHiddenOrchestratorHandoff() pattern:
- * - Sends customType: "boomerang-handoff" messages
- * - Full handoff details in hidden message to parent
- * - Orchestrator immediately reads summary
- *
- * @see docs/pi-boomerang-integration-plan.md
- */
-
-import { logInternalError } from "../utils/internal-error.ts";
-import type { HandoffSummary } from "./handoff-manager.ts";
-
-/**
- * Type of hidden handoff message.
- */
-export type HiddenHandoffType = "boomerang-handoff" | "task-complete" | "context-ready";
-
-/**
- * Hidden handoff message sent to parent agent.
- */
-export interface HiddenHandoff {
-	type: HiddenHandoffType;
-	hidden: true;
-	content: HandoffContent;
-	metadata: HiddenHandoffMetadata;
-}
-
-/**
- * Metadata for hidden handoff message.
- */
-export interface HiddenHandoffMetadata {
-	taskId: string;
-	runId: string;
-	timestamp: number;
-	priority: HandoffPriority;
-}
-
-/**
- * Priority level for hidden handoffs.
- */
-export type HandoffPriority = "low" | "normal" | "high";
-
-/**
- * Content of a hidden handoff message.
- */
-export interface HandoffContent {
-	summary: string;
-	files: {
-		created: string[];
-		modified: string[];
-		deleted: string[];
-	};
-	decisions: {
-		rationale: string;
-		outcome: string;
-	}[];
-	nextSteps: string[];
-	metrics: {
-		tokens: number;
-		duration: number;
-	};
-}
-
-/**
- * Options for HiddenHandoffService.
- */
-export interface HiddenHandoffServiceOptions {
-	/** Custom mailbox service for sending messages */
-	mailbox?: HiddenHandoffMailbox;
-	/** Event emitter for handoff events */
-	eventEmitter?: HiddenHandoffEventEmitter;
-	/** Get parent agent ID callback */
-	getParentAgentId?: () => string;
-}
-
-/**
- * Mailbox interface for sending hidden handoffs.
- */
-export interface HiddenHandoffMailbox {
-	send(recipient: string, message: HiddenHandoff): void;
-}
-
-/**
- * Event emitter for hidden handoff events.
- */
-export interface HiddenHandoffEventEmitter {
-	emit(event: string, data: unknown): void;
-}
-
-/**
- * Event data for hidden handoff sent event.
- */
-export interface HiddenHandoffSentEventData {
-	summary: HandoffSummary;
-	recipient: string;
-	priority: HandoffPriority;
-}
-
-/**
- * HiddenHandoffService sends hidden boomerang-handoff messages to parent agents.
- * This enables agents to communicate progress and context without explicit user-visible output.
- */
-export class HiddenHandoffService {
-	private mailbox: HiddenHandoffMailbox | null = null;
-	private eventEmitter: HiddenHandoffEventEmitter | null = null;
-	private getParentAgentIdFn: (() => string) | null = null;
-	private enabled = true;
-	// C7: Track rate limiting per recipient
-	private sendTimestamps = new Map<string, number[]>();
-	private readonly RATE_LIMIT_WINDOW_MS = 60000; // 1 minute
-	private readonly RATE_LIMIT_MAX_SENDS = 10; // Max handoffs per window
-
-	constructor(options: HiddenHandoffServiceOptions = {}) {
-		if (options.mailbox) {
-			this.mailbox = options.mailbox;
-		}
-		if (options.eventEmitter) {
-			this.eventEmitter = options.eventEmitter;
-		}
-		if (options.getParentAgentId) {
-			this.getParentAgentIdFn = options.getParentAgentId;
-		}
-	}
-
-	/**
-	 * Check if hidden handoff service is enabled.
-	 */
-	isEnabled(): boolean {
-		return this.enabled;
-	}
-
-	/**
-	 * Enable or disable hidden handoff service.
-	 */
-	setEnabled(enabled: boolean): void {
-		this.enabled = enabled;
-	}
-
-	/**
-	 * Set the mailbox service for sending messages.
-	 */
-	setMailbox(mailbox: HiddenHandoffMailbox): void {
-		this.mailbox = mailbox;
-	}
-
-	/**
-	 * Set the event emitter for events.
-	 */
-	setEventEmitter(eventEmitter: HiddenHandoffEventEmitter): void {
-		this.eventEmitter = eventEmitter;
-	}
-
-	/**
-	 * Set the function to get parent agent ID.
-	 */
-	setGetParentAgentId(fn: () => string): void {
-		this.getParentAgentIdFn = fn;
-	}
-
-	/**
-	 * Send a hidden handoff to the parent agent or specified recipient.
-	 *
-	 * @param summary - The handoff summary to send
-	 * @param options - Send options
-	 */
-	sendHandoff(summary: HandoffSummary, options: SendHandoffOptions = {}): void {
-		if (!this.enabled) {
-			return;
-		}
-
-		const priority = options.priority ?? this.inferPriority(summary);
-		const content = this.buildContent(summary);
-		const recipient = options.to ?? this.getParentAgentId();
-
-		if (!recipient) {
-			// No parent to send to, but we still emit the event
-			this.eventEmitter?.emit("handoff:sent_no_recipient", {
-				summary,
-				priority,
-			});
-			return;
-		}
-
-		// C7: Validate recipient is a reasonable agent ID
-		if (!this.isValidRecipient(recipient)) {
-			this.eventEmitter?.emit("handoff:invalid_recipient", {
-				recipient,
-				summary,
-			});
-			return;
-		}
-
-		// C7: Check rate limit
-		if (this.isRateLimited(recipient)) {
-			this.eventEmitter?.emit("handoff:rate_limited", {
-				recipient,
-				summary,
-			});
-			return;
-		}
-
-		const message: HiddenHandoff = {
-			type: options.customType ?? "boomerang-handoff",
-			hidden: true,
-			content,
-			metadata: {
-				taskId: summary.taskId,
-				runId: summary.runId,
-				timestamp: Date.now(),
-				priority,
-			},
-		};
-
-		if (this.mailbox) {
-			this.mailbox.send(recipient, message);
-		}
-
-		// C7: Record send for rate limiting
-		this.recordSend(recipient);
-
-		this.eventEmitter?.emit("handoff:sent", {
-			summary,
-			recipient,
-			priority,
-		});
-	}
-
-	/**
-	 * Send a hidden handoff immediately (fire and forget).
-	 */
-	sendHandoffAsync(summary: HandoffSummary, options?: SendHandoffOptions): void {
-		// Fire and forget - no await
-		try {
-			this.sendHandoff(summary, options);
-		} catch (error) {
-			// Log but don't throw
-			logInternalError("hidden-handoff.async", error, `taskId=${summary.taskId} runId=${summary.runId}`);
-		}
-	}
-
-	/**
-	 * Infer priority based on summary outcome.
-	 */
-	private inferPriority(summary: HandoffSummary): HandoffPriority {
-		if (summary.outcome === "failure") {
-			return "high";
-		}
-		if (summary.blockers.length > 0) {
-			return "normal";
-		}
-		if (summary.metrics.tokensUsed > 10000) {
-			return "normal";
-		}
-		return "low";
-	}
-
-	/**
-	 * Build handoff content from summary.
-	 */
-	private buildContent(summary: HandoffSummary): HandoffContent {
-		return {
-			summary: this.buildSummaryText(summary),
-			files: {
-				created: summary.filesCreated,
-				modified: summary.filesModified,
-				deleted: summary.filesDeleted,
-			},
-			decisions: summary.decisions.map((d) => ({
-				rationale: d.rationale,
-				outcome: d.outcome,
-			})),
-			nextSteps: summary.nextSteps,
-			metrics: {
-				tokens: summary.metrics.tokensUsed,
-				duration: summary.metrics.duration,
-			},
-		};
-	}
-
-	/**
-	 * Build summary text from summary.
-	 */
-	private buildSummaryText(summary: HandoffSummary): string {
-		const parts: string[] = [`Completed: ${summary.task}`, `Outcome: ${summary.outcome}`];
-
-		if (summary.filesCreated.length > 0) {
-			parts.push(`Files created: ${summary.filesCreated.join(", ")}`);
-		}
-		if (summary.filesModified.length > 0) {
-			parts.push(`Files modified: ${summary.filesModified.join(", ")}`);
-		}
-		if (summary.decisions.length > 0) {
-			parts.push(`Decisions: ${summary.decisions.length}`);
-		}
-		if (summary.blockers.length > 0) {
-			parts.push(`Blockers: ${summary.blockers.join("; ")}`);
-		}
-		if (summary.nextSteps.length > 0) {
-			parts.push(`Next steps: ${summary.nextSteps.join("; ")}`);
-		}
-
-		parts.push(`Tokens: ${summary.metrics.tokensUsed}`, `Duration: ${Math.round(summary.metrics.duration / 1000)}s`);
-
-		return parts.join("\n");
-	}
-
-	/**
-	 * Get parent agent ID from callback or context.
-	 */
-	private getParentAgentId(): string | undefined {
-		if (this.getParentAgentIdFn) {
-			return this.getParentAgentIdFn();
-		}
-		// Fallback: try to get from global context
-		const ctx = (globalThis as Record<string, unknown>).__piCrewContext;
-		if (ctx && typeof ctx === "object") {
-			return (ctx as Record<string, unknown>).parentAgentId as string | undefined;
-		}
-		return undefined;
-	}
-
-	/**
-	 * C7: Validate recipient is a reasonable agent ID.
-	 */
-	private isValidRecipient(recipient: string): boolean {
-		if (!recipient || typeof recipient !== "string") {
-			return false;
-		}
-		// Reasonable length for an agent ID
-		if (recipient.length < 1 || recipient.length > 256) {
-			return false;
-		}
-		// Only allow alphanumeric, hyphen, underscore, colon, and period
-		// This prevents injection in mailbox routing
-		if (!/^[a-zA-Z0-9_:.-]+$/.test(recipient)) {
-			return false;
-		}
-		return true;
-	}
-
-	/**
-	 * C7: Check if recipient is rate limited.
-	 * Also cleans up empty recipient entries to prevent unbounded Map growth.
-	 */
-	private isRateLimited(recipient: string): boolean {
-		const now = Date.now();
-		const timestamps = this.sendTimestamps.get(recipient) ?? [];
-
-		// Filter out old timestamps outside the window
-		const recentTimestamps = timestamps.filter((t) => now - t < this.RATE_LIMIT_WINDOW_MS);
-
-		// HIGH-11: If no recent timestamps, remove the empty key to prevent unbounded growth
-		if (recentTimestamps.length === 0) {
-			this.sendTimestamps.delete(recipient);
-		} else {
-			this.sendTimestamps.set(recipient, recentTimestamps);
-		}
-
-		return recentTimestamps.length >= this.RATE_LIMIT_MAX_SENDS;
-	}
-
-	/**
-	 * C7: Record a send for rate limiting.
-	 */
-	private recordSend(recipient: string): void {
-		const now = Date.now();
-		const timestamps = this.sendTimestamps.get(recipient) ?? [];
-		timestamps.push(now);
-
-		// MEDIUM-14: Use RATE_LIMIT_WINDOW_MS consistently for both filter and record
-		const recentTimestamps = timestamps.filter((t) => now - t < this.RATE_LIMIT_WINDOW_MS);
-
-		this.sendTimestamps.set(recipient, recentTimestamps);
-	}
-
-	/**
-	 * Dispose of resources.
-	 * Call this when the service is no longer needed.
-	 */
-	dispose(): void {
-		this.mailbox = null;
-		this.eventEmitter = null;
-		this.getParentAgentIdFn = null;
-		this.sendTimestamps.clear();
-	}
-}
-
-/**
- * Options for sending hidden handoffs.
- */
-export interface SendHandoffOptions {
-	/** Recipient agent ID (defaults to parent) */
-	to?: string;
-	/** Priority level */
-	priority?: HandoffPriority;
-	/** Custom handoff type */
-	customType?: HiddenHandoffType;
-}
-
-/**
- * Create a HiddenHandoffService with default options.
- */
-export function createHiddenHandoffService(options?: HiddenHandoffServiceOptions): HiddenHandoffService {
-	return new HiddenHandoffService(options);
-}

package/src/runtime/prose-compressor.ts

@@ -1,162 +0,0 @@
-/**
- * Pure TypeScript prose compression module.
- *
- * Inspired by caveman's compress.js — reduces tool descriptions and other
- * prose by removing filler words, pleasantries, hedging, and articles while
- * preserving code, URLs, paths, identifiers, and other protected segments
- * byte-for-byte.
- *
- * No external dependencies. No `any` types. Regex-only pattern matching.
- */
-
-// ---------------------------------------------------------------------------
-// Protected segment patterns (order matters — earlier patterns take priority)
-// ---------------------------------------------------------------------------
-
-const PROTECTED_PATTERNS: readonly RegExp[] = [
-	/```[\s\S]*?```/g, // fenced code blocks
-	/`[^`\n]+`/g, // inline code
-	/\bhttps?:\/\/\S+/gi, // URLs
-	/\b[\w.-]*[/\\][\w./\\-]+/g, // paths with / or \
-	/\b[A-Z][A-Z0-9]*(?:_[A-Z][A-Z0-9]*)+\b/g, // CONSTANT_CASE
-	/\b\w+(?:\.\w+)+\(\)/g, // dotted.method() calls
-	/[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)/g, // function calls: name(args)
-	/\b\d+\.\d+\.\d+\b/g, // version numbers x.y.z
-];
-
-// ---------------------------------------------------------------------------
-// Compression patterns (applied to unprotected prose only)
-// ---------------------------------------------------------------------------
-
-const FILLERS = /\b(?:just|really|basically|actually|simply|quite|very|essentially|literally)\b/gi;
-
-const PLEASANTRIES = /\b(?:please|kindly|thank you|thanks|sure|certainly|of course|happy to)\b[,.]?\s*/gi;
-
-const HEDGES = /\b(?:perhaps|maybe|might|could potentially|would like to|i think|in my opinion)\b\s*/gi;
-
-const LEADERS = /^(?:i'?\s*ll|i will|i can|you can|we will|we can|let me|let'?\s*s)\s+/gim;
-
-const ARTICLES = /\b(?:a|an|the)\s+(?=[a-z])/gi;
-
-// ---------------------------------------------------------------------------
-// Sentinel helpers
-// ---------------------------------------------------------------------------
-
-const SENTINEL_OPEN = "\x00";
-const SENTINEL_CLOSE = "\x00";
-const SENTINEL_RE = /\x00(\d+)\x00/g;
-
-interface SegmentStore {
-	segments: string[];
-}
-
-function extractProtected(text: string, store: SegmentStore): string {
-	let working = text;
-	for (const re of PROTECTED_PATTERNS) {
-		// Reset lastIndex for reused RegExp objects
-		re.lastIndex = 0;
-		working = working.replace(re, (match: string): string => {
-			const index = store.segments.length;
-			store.segments.push(match);
-			return `${SENTINEL_OPEN}${index}${SENTINEL_CLOSE}`;
-		});
-	}
-	return working;
-}
-
-function restoreProtected(text: string, store: SegmentStore): string {
-	return text.replace(SENTINEL_RE, (_match: string, indexStr: string): string => {
-		const index = Number(indexStr);
-		return store.segments[index] ?? "";
-	});
-}
-
-// ---------------------------------------------------------------------------
-// Core prose compression
-// ---------------------------------------------------------------------------
-
-function compressProseText(text: string): string {
-	let s = text;
-
-	// Remove leading "I'll / I will / you can / ..." sentence openers
-	s = s.replace(LEADERS, "");
-
-	// Remove pleasantries
-	s = s.replace(PLEASANTRIES, "");
-
-	// Remove hedging phrases
-	s = s.replace(HEDGES, "");
-
-	// Remove filler adverbs
-	s = s.replace(FILLERS, "");
-
-	// Remove articles before lowercase words
-	s = s.replace(ARTICLES, "");
-
-	// Collapse whitespace introduced by removals
-	s = s.replace(/[ \t]{2,}/g, " ");
-
-	// Fix punctuation spacing (e.g. "word ," → "word,")
-	s = s.replace(/\s+([,.;:!?])/g, "$1");
-
-	// Collapse excessive newlines
-	s = s.replace(/\n{3,}/g, "\n\n");
-
-	// Re-capitalize first letter of each sentence after removals
-	s = s.replace(/(^|[.!?]\s+)([a-z])/g, (_match: string, pre: string, ch: string): string => {
-		return pre + ch.toUpperCase();
-	});
-
-	return s.trim();
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export interface CompressResult {
-	compressed: string;
-	originalLength: number;
-	compressedLength: number;
-	savingsPercent: number;
-}
-
-/**
- * Compress prose text by removing filler, pleasantries, hedging, and articles
- * while preserving code blocks, URLs, paths, identifiers, and other protected
- * segments byte-for-byte.
- */
-export function compressProse(text: string): CompressResult {
-	if (typeof text !== "string" || text.length === 0) {
-		return {
-			compressed: "",
-			originalLength: 0,
-			compressedLength: 0,
-			savingsPercent: 0,
-		};
-	}
-
-	const store: SegmentStore = { segments: [] };
-	const extracted = extractProtected(text, store);
-	const compressed = compressProseText(extracted);
-	const restored = restoreProtected(compressed, store);
-
-	const originalLength = text.length;
-	const compressedLength = restored.length;
-	const savingsPercent = originalLength > 0 ? Math.round(((originalLength - compressedLength) / originalLength) * 100 * 100) / 100 : 0;
-
-	return {
-		compressed: restored,
-		originalLength,
-		compressedLength,
-		savingsPercent,
-	};
-}
-
-/**
- * Convenience wrapper — returns just the compressed string for tool
- * descriptions and other single-field use cases.
- */
-export function compressToolDescription(description: string): string {
-	return compressProse(description).compressed;
-}

package/src/subagents/async-entry.ts

@@ -1 +0,0 @@
-export * from "../runtime/async-runner.ts";

package/src/subagents/index.ts

@@ -1,3 +0,0 @@
-export * from "./async-entry.ts";
-export * from "./manager.ts";
-export * from "./spawn.ts";

package/src/subagents/live/control.ts

@@ -1 +0,0 @@
-export * from "../../runtime/live-agent-control.ts";

package/src/subagents/live/manager.ts

@@ -1 +0,0 @@
-export * from "../../runtime/live-agent-manager.ts";

package/src/subagents/live/realtime.ts

@@ -1 +0,0 @@
-export * from "../../runtime/live-control-realtime.ts";

package/src/subagents/live/session-runtime.ts

@@ -1 +0,0 @@
-export * from "../../runtime/live-session-runtime.ts";

package/src/subagents/manager.ts

@@ -1 +0,0 @@
-export * from "../runtime/subagent-manager.ts";

package/src/subagents/spawn.ts

@@ -1 +0,0 @@
-export * from "../runtime/child-pi.ts";