pi-crew 0.5.5 → 0.5.6

package/src/runtime/hidden-handoff.ts

@@ -0,0 +1,424 @@
+/**
+ * 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 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);
+		let 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
+			console.error("Hidden handoff failed:", error);
+		}
+	}
+
+	/**
+	 * 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/live-agent-manager.ts

@@ -3,6 +3,8 @@ import type { IrcMessage } from "./live-irc.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import type { appendEvent } from "../state/event-log.ts";
 
+const MAX_PENDING_MESSAGES = 1000;
+
 type LiveSessionHandle = {
 	steer?: (text: string) => Promise<void>;
 	prompt?: (text: string, options?: Record<string, unknown>) => Promise<void>;
@@ -103,12 +105,12 @@ export function registerLiveAgent(input: Omit<LiveAgentHandle, "createdAt" | "up
 	if (handle.pendingSteers.length && typeof handle.session.steer === "function") {
 		const pending = [...handle.pendingSteers];
 		handle.pendingSteers.length = 0;
-		for (const message of pending) void handle.session.steer(message).catch(() => {});
+		for (const message of pending) void handle.session.steer(message).catch((error) => logInternalError("live-agent-manager.steer", error, `agentId=${handle.agentId}`));
 	}
 	if (handle.pendingFollowUps.length && typeof handle.session.prompt === "function") {
 		const pending = [...handle.pendingFollowUps];
 		handle.pendingFollowUps.length = 0;
-		for (const message of pending) void handle.session.prompt(message, { source: "api", expandPromptTemplates: false }).catch(() => {});
+		for (const message of pending) void handle.session.prompt(message, { source: "api", expandPromptTemplates: false }).catch((error) => logInternalError("live-agent-manager.prompt", error, `agentId=${handle.agentId}`));
 	}
 	return handle;
 }
@@ -262,6 +264,14 @@ export async function resumeLiveAgent(agentIdOrTaskId: string, prompt: string):
 export function trackLiveAgentToolStart(agentIdOrTaskId: string, toolName: string): void {
 	const handle = getLiveAgent(agentIdOrTaskId);
 	if (!handle) return;
+	// Evict oldest entries if at capacity
+	const MAX_TRACKED_TOOLS = 1000;
+	if (handle.activity.activeTools.size >= MAX_TRACKED_TOOLS) {
+		const firstKey = handle.activity.activeTools.keys().next().value;
+		if (firstKey !== undefined) {
+			handle.activity.activeTools.delete(firstKey);
+		}
+	}
 	handle.activity.activeTools.set(toolName, toolName);
 	handle.activity.toolUses++;
 	handle.updatedAt = new Date().toISOString();
@@ -310,6 +320,9 @@ export function clearLiveAgentsForTest(): void {
 export function sendIrcMessage(targetAgentId: string, message: IrcMessage): void {
 	const handle = getLiveAgent(targetAgentId);
 	if (!handle) return;
+	if (handle.pendingMessages.length >= MAX_PENDING_MESSAGES) {
+		handle.pendingMessages.shift();
+	}
 	handle.pendingMessages.push(message);
 	handle.updatedAt = new Date().toISOString();
 	// G4: Try non-blocking delivery via sendCustomMessage
@@ -328,7 +341,7 @@ export function sendIrcMessage(targetAgentId: string, message: IrcMessage): void
 	// Fallback: inject as prompt (blocking)
 	if (typeof handle.session.prompt === "function") {
 		const ircPrompt = `[Message from ${message.from}] ${message.content}`;
-		void handle.session.prompt(ircPrompt, { source: "api", expandPromptTemplates: false }).catch(() => {});
+		void handle.session.prompt(ircPrompt, { source: "api", expandPromptTemplates: false }).catch((error) => logInternalError("live-agent-manager.irc-deliver", error, `agentId=${handle.agentId}`));
 	}
 }
 
@@ -341,6 +354,9 @@ export function broadcastIrcMessage(fromAgentId: string, message: IrcMessage): s
 	for (const handle of liveAgents.values()) {
 		if (handle.agentId === fromAgentId) continue;
 		if (handle.status !== "running" && handle.status !== "queued") continue;
+		if (handle.pendingMessages.length >= MAX_PENDING_MESSAGES) {
+			handle.pendingMessages.shift();
+		}
 		handle.pendingMessages.push(message);
 		handle.updatedAt = new Date().toISOString();
 		// G4: Try non-blocking delivery
@@ -360,7 +376,7 @@ export function broadcastIrcMessage(fromAgentId: string, message: IrcMessage): s
 		// Fallback: inject as prompt
 		if (typeof handle.session.prompt === "function") {
 			const ircPrompt = `[Broadcast from ${message.from}] ${message.content}`;
-			void handle.session.prompt(ircPrompt, { source: "api", expandPromptTemplates: false }).catch(() => {});
+			void handle.session.prompt(ircPrompt, { source: "api", expandPromptTemplates: false }).catch((error) => logInternalError("live-agent-manager.irc-broadcast", error, `agentId=${handle.agentId}`));
 		}
 		recipients.push(handle.agentId);
 	}

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

@@ -105,6 +105,41 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 }
 
+function isString(value: unknown): value is string {
+	return typeof value === "string";
+}
+
+/**
+ * Type-safe extractor for message role from streaming events.
+ * Handles the case where message may be a Record with a role field.
+ */
+function extractMessageRole(obj: Record<string, unknown> | undefined): string | undefined {
+	const message = obj?.message ? asRecord(obj.message) : undefined;
+	return isString(message?.role) ? message.role : undefined;
+}
+
+/**
+ * Type-safe extractor for message usage from streaming events.
+ * Handles the case where message may be a Record with usage data.
+ */
+function extractMessageUsage(obj: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+	const message = obj?.message ? asRecord(obj.message) : undefined;
+	return message?.usage && typeof message.usage === "object" ? message.usage as Record<string, unknown> : undefined;
+}
+
+/**
+ * Type-safe extractor for tool name from streaming events.
+ * Handles various event structures: { tool: { name } }, { toolName }, { name }.
+ */
+function extractToolName(obj: Record<string, unknown> | undefined): string | undefined {
+	if (!obj) return undefined;
+	const tool = asRecord(obj.tool);
+	if (isString(tool?.name)) return tool.name;
+	if (isString(obj.toolName)) return obj.toolName;
+	if (isString(obj.name)) return obj.name;
+	return undefined;
+}
+
 function textFromContent(content: unknown): string[] {
 	if (typeof content === "string") return [content];
 	if (!Array.isArray(content)) return [];
@@ -477,8 +512,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 					}
 				}
 				// Accumulate lifetime usage that survives compaction
-				if (obj?.type === "message_end" && (obj as any).message?.role === "assistant") {
-					const u = (obj as any).message?.usage;
+				if (obj?.type === "message_end" && extractMessageRole(obj) === "assistant") {
+					const u = extractMessageUsage(obj);
 					if (u) {
 						trackTaskUsage(input.task.id, {
 							input: typeof u.input === "number" ? u.input : 0,
@@ -497,11 +532,11 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 				}
 				// G2: Track tool start/end for activity display
 				if (obj?.type === "tool_use" || obj?.type === "tool_execution_start") {
-					const toolName = (obj as any).tool?.name ?? (obj as any).toolName ?? (obj as any).name ?? "unknown";
+					const toolName = extractToolName(obj) ?? "unknown";
 					trackLiveAgentToolStart(agentId, toolName);
 				}
 				if (obj?.type === "tool_result" || obj?.type === "tool_execution_end") {
-					const toolName = (obj as any).tool?.name ?? (obj as any).toolName ?? (obj as any).name ?? "unknown";
+					const toolName = extractToolName(obj) ?? "unknown";
 					trackLiveAgentToolEnd(agentId, toolName);
 				}
 				// Phase 1: collect events for yield detection

package/src/runtime/manifest-cache.ts

@@ -152,10 +152,11 @@ export function createManifestCache(cwd: string, options: ManifestCacheOptions =
 			clearTimeout(listTimer);
 		}
 		listTimer = setTimeout(() => {
+			const timer = listTimer;
 			listTimer = undefined;
 			listCache.clear();
+			timer?.unref();
 		}, ttlMs);
-		listTimer.unref();
 	}
 
 	function loadManifest(runId: string, rootsToCheck: string[]): CachedManifest | undefined {

package/src/runtime/model-resolver.ts

@@ -4,10 +4,22 @@ export interface ModelEntry {
 	provider: string;
 }
 
+/**
+ * Core Model interface representing a resolved model instance.
+ * Used by resolveModel return type to ensure proper typing.
+ */
+export interface Model {
+	id: string;
+	name?: string;
+	provider?: string;
+	// Allow additional properties from the registry
+	[key: string]: unknown;
+}
+
 export interface ModelRegistry {
-	find(provider: string, modelId: string): any;
-	getAll(): any[];
-	getAvailable?(): any[];
+	find(provider: string, modelId: string): Model | undefined;
+	getAll(): Model[];
+	getAvailable?(): Model[];
 }
 
 /**
@@ -15,7 +27,7 @@ export interface ModelRegistry {
  * Exact match first ("provider/modelId"), then fuzzy match.
  * Returns Model on success, error message string on failure.
  */
-export function resolveModel(input: string, registry: ModelRegistry): any | string {
+export function resolveModel(input: string, registry: ModelRegistry): Model | string {
 	const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
 	const availableSet = new Set(all.map((m) => `${m.provider}/${m.id}`.toLowerCase()));