pi-crew 0.9.53 → 0.9.55

package/src/runtime/progress-tracker.ts

@@ -0,0 +1,124 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { crewEventBus } from "../observability/event-bus.ts";
+
+export interface AgentProgress {
+	toolCalls: number;
+	currentTool: string | null;
+	toolStartTime: number | null;
+	errors: string[];
+	turns: number;
+	tokens: { input: number; output: number };
+	status: "idle" | "running" | "completed" | "error";
+}
+
+export class ProgressTracker {
+	private sessions = new Map<
+		string,
+		{
+			unsubscribe: () => void;
+			progress: AgentProgress;
+		}
+	>();
+
+	track(
+		session: {
+			subscribe: (listener: (event: AgentSessionEvent) => void) => () => void;
+		},
+		agentId: string,
+		runId: string,
+	): AgentProgress {
+		if (this.sessions.has(agentId)) {
+			return this.sessions.get(agentId)!.progress;
+		}
+
+		const progress: AgentProgress = {
+			toolCalls: 0,
+			currentTool: null,
+			toolStartTime: null,
+			errors: [],
+			turns: 0,
+			tokens: { input: 0, output: 0 },
+			status: "running",
+		};
+
+		const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+			this.handleEvent(event, progress, agentId, runId);
+		});
+
+		this.sessions.set(agentId, { unsubscribe, progress });
+		return progress;
+	}
+
+	private handleEvent(event: AgentSessionEvent, progress: AgentProgress, agentId: string, runId: string): void {
+		switch (event.type) {
+			case "tool_execution_start":
+				progress.toolCalls++;
+				progress.currentTool = event.toolName;
+				progress.toolStartTime = Date.now();
+				crewEventBus.emit({
+					type: "agent:progress",
+					runId,
+					agentId,
+					payload: { ...progress },
+					timestamp: Date.now(),
+				});
+				break;
+
+			case "tool_execution_end":
+				progress.currentTool = null;
+				progress.toolStartTime = null;
+				if (event.isError) {
+					progress.errors.push(String(event.result ?? "Unknown error"));
+					crewEventBus.emit({
+						type: "agent:error",
+						runId,
+						agentId,
+						payload: String(event.result ?? "Unknown error"),
+						timestamp: Date.now(),
+					});
+				}
+				crewEventBus.emit({
+					type: "agent:progress",
+					runId,
+					agentId,
+					payload: { ...progress },
+					timestamp: Date.now(),
+				});
+				break;
+
+			case "turn_start":
+				progress.turns++;
+				break;
+
+			case "agent_end":
+				progress.status = "completed";
+				crewEventBus.emit({
+					type: "agent:complete",
+					runId,
+					agentId,
+					payload: { ...progress },
+					timestamp: Date.now(),
+				});
+				break;
+
+			case "agent_start":
+				progress.status = "running";
+				break;
+		}
+	}
+
+	untrack(agentId: string): void {
+		const tracked = this.sessions.get(agentId);
+		if (tracked) {
+			tracked.unsubscribe();
+			this.sessions.delete(agentId);
+		}
+	}
+
+	getProgress(agentId: string): AgentProgress | undefined {
+		return this.sessions.get(agentId)?.progress;
+	}
+}
+
+// Export singleton instance
+export const globalProgressTracker = new ProgressTracker();

package/src/runtime/prose-compressor.ts

@@ -0,0 +1,162 @@
+/**
+ * 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/runtime/recovery-recipes.ts

@@ -0,0 +1,203 @@
+import type { PolicyDecision, PolicyDecisionReason } from "../state/types.ts";
+
+export type FailureScenario =
+	| "trust_prompt_unresolved"
+	| "prompt_misdelivery"
+	| "stale_branch"
+	| "compile_red_cross_crate"
+	| "mcp_handshake_failure"
+	| "partial_plugin_startup"
+	| "provider_failure"
+	| "task_failed"
+	| "worker_stale"
+	| "green_unsatisfied";
+export type RecoveryStep =
+	| "accept_trust_prompt"
+	| "redirect_prompt_to_agent"
+	| "rebase_branch"
+	| "clean_build"
+	| "retry_mcp_handshake"
+	| "restart_plugin"
+	| "restart_worker"
+	| "rerun_task"
+	| "collect_verification_evidence"
+	| "escalate_to_human";
+export type RecoveryResultState = "planned" | "skipped" | "escalation_required";
+
+export interface RecoveryRecipe {
+	scenario: FailureScenario;
+	steps: RecoveryStep[];
+	maxAttempts: number;
+	escalationPolicy: "alert_human" | "log_and_continue" | "abort";
+}
+
+export interface RecoveryLedgerEntry {
+	scenario: FailureScenario;
+	taskId?: string;
+	decisionReason: PolicyDecisionReason;
+	attempt: number;
+	state: RecoveryResultState;
+	steps: RecoveryStep[];
+	message: string;
+	createdAt: string;
+}
+
+export interface RecoveryLedger {
+	entries: RecoveryLedgerEntry[];
+}
+
+export function scenarioForPolicyReason(reason: PolicyDecisionReason): FailureScenario {
+	switch (reason) {
+		case "branch_stale":
+			return "stale_branch";
+		case "worker_stale":
+			return "worker_stale";
+		case "green_unsatisfied":
+			return "green_unsatisfied";
+		case "task_failed":
+			return "task_failed";
+		default:
+			return "provider_failure";
+	}
+}
+
+export function recipeFor(scenario: FailureScenario): RecoveryRecipe {
+	switch (scenario) {
+		case "trust_prompt_unresolved":
+			return {
+				scenario,
+				steps: ["accept_trust_prompt"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "prompt_misdelivery":
+			return {
+				scenario,
+				steps: ["redirect_prompt_to_agent"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "stale_branch":
+			return {
+				scenario,
+				steps: ["rebase_branch", "clean_build"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "compile_red_cross_crate":
+			return {
+				scenario,
+				steps: ["clean_build"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "mcp_handshake_failure":
+			return {
+				scenario,
+				steps: ["retry_mcp_handshake"],
+				maxAttempts: 1,
+				escalationPolicy: "abort",
+			};
+		case "partial_plugin_startup":
+			return {
+				scenario,
+				steps: ["restart_plugin", "retry_mcp_handshake"],
+				maxAttempts: 1,
+				escalationPolicy: "log_and_continue",
+			};
+		case "worker_stale":
+			return {
+				scenario,
+				steps: ["restart_worker"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "green_unsatisfied":
+			return {
+				scenario,
+				steps: ["collect_verification_evidence"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "task_failed":
+			return {
+				scenario,
+				steps: ["rerun_task"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+		case "provider_failure":
+			return {
+				scenario,
+				steps: ["restart_worker"],
+				maxAttempts: 1,
+				escalationPolicy: "alert_human",
+			};
+	}
+}
+
+export function buildRecoveryLedger(decisions: PolicyDecision[], previous: RecoveryLedger = { entries: [] }): RecoveryLedger {
+	const entries = [...previous.entries];
+	for (const item of decisions) {
+		if (!["retry", "escalate", "block"].includes(item.action)) continue;
+		const scenario = scenarioForPolicyReason(item.reason);
+		const recipe = recipeFor(scenario);
+		const priorAttempts = entries.filter((entry) => entry.scenario === scenario && entry.taskId === item.taskId).length;
+		const attempt = priorAttempts + 1;
+		entries.push({
+			scenario,
+			taskId: item.taskId,
+			decisionReason: item.reason,
+			attempt,
+			state: attempt <= recipe.maxAttempts && item.action !== "block" ? "planned" : "escalation_required",
+			steps: attempt <= recipe.maxAttempts ? recipe.steps : ["escalate_to_human"],
+			message: item.message,
+			createdAt: new Date().toISOString(),
+		});
+	}
+	return { entries };
+}
+
+/**
+ * #4 (assessment): decide whether a FAILED task should be re-queued for a
+ * whole-task rerun, honoring limits.maxRetriesPerTask.
+ *
+ * Before #4, buildRecoveryLedger recorded `rerun_task` entries with
+ * state:"planned" but NOTHING ever executed them — the recovery ledger was
+ * decorative. This pure function drives the actual re-queue decision used in
+ * the run loop: when a task returns a failed STATUS (not a retryable throw,
+ * which #1's autoRetry/executeWithRetry already handles), re-queue it for a
+ * bounded whole-task rerun instead of immediately aborting the run.
+ *
+ * Default-off: maxRetriesPerTask defaults to 0 → never rerun (preserves prior
+ * behavior unless explicitly opted in). Bounded by retryCount < maxRetries.
+ */
+export interface RerunDecision {
+	rerun: boolean;
+	newRetryCount: number;
+	reason: string;
+}
+
+export function shouldRerunFailedTask(task: { policy?: { retryCount?: number } }, limits?: { maxRetriesPerTask?: number }): RerunDecision {
+	const maxRetries = limits?.maxRetriesPerTask ?? 0;
+	const retryCount = task.policy?.retryCount ?? 0;
+	if (maxRetries <= 0) {
+		return {
+			rerun: false,
+			newRetryCount: retryCount,
+			reason: "maxRetriesPerTask not set (opt-in) — no whole-task rerun",
+		};
+	}
+	if (retryCount >= maxRetries) {
+		return {
+			rerun: false,
+			newRetryCount: retryCount,
+			reason: `retryCount ${retryCount} >= maxRetriesPerTask ${maxRetries} — rerun budget exhausted`,
+		};
+	}
+	return {
+		rerun: true,
+		newRetryCount: retryCount + 1,
+		reason: `whole-task rerun ${retryCount + 1}/${maxRetries}`,
+	};
+}