pi-crew 0.5.24 → 0.6.0

package/src/runtime/drift-detectors.ts

@@ -0,0 +1,220 @@
+/**
+ * Runtime drift detectors — detect state anomalies in pi-crew runs.
+ *
+ * Pattern origin: GSD-2 ADR-017 drift detection & state reconciliation.
+ * Each detector checks for a specific anomaly and returns a report.
+ * Repair handlers are idempotent — safe to run multiple times.
+ */
+
+import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type DriftKind =
+	| "stale-process"         // Heartbeat timeout (existing)
+	| "orphaned-claim"        // Task claim without task
+	| "orphaned-worktree"     // Worktree dir without active run
+	| "missing-timestamps"    // State files without timestamps
+	| "status-divergence"     // Manifest status ≠ status file
+	| "unregistered-run";     // State dir but no manifest
+
+export interface DriftReport {
+	kind: DriftKind;
+	runId: string;
+	details: string;
+	repaired: boolean;
+	repairResult?: string;
+}
+
+export interface DriftContext {
+	/** Root directory for crew state (.crew/) */
+	crewRoot: string;
+	/** Active run IDs (from registry) */
+	activeRunIds: Set<string>;
+	/** Manifest content if available */
+	manifest?: { runId: string; status: string; cwd: string; [k: string]: unknown };
+}
+
+// ── Detectors ────────────────────────────────────────────────────────────
+
+/**
+ * Detect task claims that reference tasks not in the manifest.
+ */
+export function detectOrphanedClaim(ctx: DriftContext): DriftReport | null {
+	if (!ctx.manifest) return null;
+	const claimsDir = path.join(ctx.crewRoot, "state", "task-claims");
+	if (!existsSync(claimsDir)) return null;
+
+	const claimFiles = readdirSync(claimsDir).filter((f) => f.endsWith(".json"));
+	for (const file of claimFiles) {
+		try {
+			const claim = JSON.parse(readFileSync(path.join(claimsDir, file), "utf-8"));
+			if (claim.runId === ctx.manifest.runId && claim.taskId) {
+				// Check if task exists in manifest tasks array
+				const tasks = (ctx.manifest as Record<string, unknown>).tasks;
+				if (Array.isArray(tasks) && !tasks.some((t: Record<string, unknown>) => t.id === claim.taskId)) {
+					return {
+						kind: "orphaned-claim",
+						runId: ctx.manifest.runId,
+						details: `Task claim '${claim.taskId}' references non-existent task`,
+						repaired: false,
+					};
+				}
+			}
+		} catch {
+			// Malformed claim file — skip
+		}
+	}
+	return null;
+}
+
+/**
+ * Detect worktree directories that don't belong to any active run.
+ */
+export function detectOrphanedWorktree(ctx: DriftContext): DriftReport | null {
+	const worktreesDir = path.join(ctx.crewRoot, "worktrees");
+	if (!existsSync(worktreesDir)) return null;
+
+	const dirs = readdirSync(worktreesDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory())
+		.map((d) => d.name);
+
+	for (const dir of dirs) {
+		// Extract run ID from worktree dir name (format: <runId>-<taskId> or <runId>)
+		const runId = dir.split("-").slice(0, 5).join("-"); // heuristic: run IDs are timestamp-based
+		if (!ctx.activeRunIds.has(runId) && !ctx.activeRunIds.has(dir)) {
+			return {
+				kind: "orphaned-worktree",
+				runId: dir,
+				details: `Worktree '${dir}' has no active run`,
+				repaired: false,
+			};
+		}
+	}
+	return null;
+}
+
+/**
+ * Detect state files missing required timestamps.
+ */
+export function detectMissingTimestamps(ctx: DriftContext): DriftReport | null {
+	if (!ctx.manifest) return null;
+	const stateDir = path.join(ctx.crewRoot, "state");
+	if (!existsSync(stateDir)) return null;
+
+	// Check manifest has createdAt/updatedAt
+	const m = ctx.manifest as Record<string, unknown>;
+	if (!m.createdAt && !m.updatedAt) {
+		return {
+			kind: "missing-timestamps",
+			runId: ctx.manifest.runId,
+			details: "Manifest missing createdAt/updatedAt timestamps",
+			repaired: false,
+		};
+	}
+	return null;
+}
+
+/**
+ * Detect divergence between manifest status and individual task status files.
+ */
+export function detectStatusDivergence(ctx: DriftContext): DriftReport | null {
+	if (!ctx.manifest) return null;
+	const statusPath = path.join(ctx.crewRoot, "state", `${ctx.manifest.runId}.status`);
+	if (!existsSync(statusPath)) return null;
+
+	try {
+		const status = readFileSync(statusPath, "utf-8").trim();
+		if (status !== ctx.manifest.status) {
+			return {
+				kind: "status-divergence",
+				runId: ctx.manifest.runId,
+				details: `Manifest says '${ctx.manifest.status}' but status file says '${status}'`,
+				repaired: false,
+			};
+		}
+	} catch {
+		// Can't read status file — not drift, might be permissions
+	}
+	return null;
+}
+
+/**
+ * Detect state directories that have no corresponding manifest.
+ */
+export function detectUnregisteredRun(ctx: DriftContext): DriftReport | null {
+	const runsDir = path.join(ctx.crewRoot, "runs");
+	if (!existsSync(runsDir)) return null;
+
+	const runDirs = readdirSync(runsDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory())
+		.map((d) => d.name);
+
+	for (const runId of runDirs) {
+		if (!ctx.activeRunIds.has(runId)) {
+			// Check if it has state files (manifest exists)
+			const manifestPath = path.join(runsDir, runId, "manifest.json");
+			if (existsSync(manifestPath)) {
+				try {
+					const stat = statSync(manifestPath);
+					const ageMs = Date.now() - stat.mtimeMs;
+					// Only flag if older than 1 hour (might be in-progress)
+					if (ageMs > 60 * 60 * 1000) {
+						return {
+							kind: "unregistered-run",
+							runId,
+							details: `Run '${runId}' has manifest but is not in active registry (age: ${Math.round(ageMs / 60000)}m)`,
+							repaired: false,
+						};
+					}
+				} catch {
+					// Can't stat — skip
+				}
+			}
+		}
+	}
+	return null;
+}
+
+// ── Reconciliation Loop ─────────────────────────────────────────────────
+
+const ALL_DETECTORS = [
+	detectOrphanedClaim,
+	detectOrphanedWorktree,
+	detectMissingTimestamps,
+	detectStatusDivergence,
+	detectUnregisteredRun,
+];
+
+/**
+ * Run all drift detectors and collect reports.
+ * Capped at maxPasses repair attempts.
+ *
+ * Pattern origin: GSD-2 ADR-017 — capped at 2 retry passes.
+ */
+export function runDriftDetection(ctx: DriftContext, maxPasses = 2): DriftReport[] {
+	const reports: DriftReport[] = [];
+
+	for (let pass = 0; pass < maxPasses; pass++) {
+		let newFindings = 0;
+
+		for (const detector of ALL_DETECTORS) {
+			try {
+				const report = detector(ctx);
+				if (report) {
+					reports.push(report);
+					newFindings++;
+				}
+			} catch (error) {
+				logInternalError("drift-detectors", error, `detector=${detector.name} runId=${ctx.manifest?.runId}`);
+			}
+		}
+
+		// If no new findings, stop early
+		if (newFindings === 0) break;
+	}
+
+	return reports;
+}

package/src/runtime/intercom-bridge.ts

@@ -0,0 +1,178 @@
+/**
+ * Intercom bridge — workers can escalate questions to the orchestrator.
+ *
+ * Pattern origin: pi-subagents/src/intercom-bridge.ts — contact_supervisor tool
+ * for child agents to escalate decisions, report progress, or ask questions.
+ *
+ * This module provides the message queue and correlation logic.
+ * The actual tool registration happens in task-runner.ts.
+ */
+
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type IntercomUrgency = "low" | "medium" | "high" | "critical";
+export type IntercomType = "question" | "escalation" | "progress" | "block";
+
+export interface IntercomMessage {
+	type: IntercomType;
+	taskStepId: string;
+	content: string;
+	urgency: IntercomUrgency;
+	timestamp: number;
+	timeout?: number; // ms to wait for response
+}
+
+export interface IntercomResponse {
+	answer: string;
+	source: "orchestrator" | "human" | "timeout";
+	timestamp: number;
+	messageId: string;
+}
+
+// ── Message Queue ────────────────────────────────────────────────────────
+
+interface PendingMessage {
+	message: IntercomMessage;
+	id: string;
+	resolve: (response: IntercomResponse) => void;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+const MAX_QUEUE_SIZE = 100;
+
+/**
+ * In-process intercom queue for worker→orchestrator communication.
+ *
+ * Each message gets a unique ID. Callers await a response via a Promise.
+ * If no response arrives within the timeout, resolves with source="timeout".
+ */
+export class IntercomQueue {
+	private pending = new Map<string, PendingMessage>();
+	private queue: IntercomMessage[] = [];
+
+	/**
+	 * Enqueue a message and return a promise that resolves when the
+	 * orchestrator responds (or times out).
+	 */
+	enqueue(message: IntercomMessage): Promise<IntercomResponse> {
+		if (this.pending.size >= MAX_QUEUE_SIZE) {
+			// Evict oldest
+			const firstKey = this.pending.keys().next().value;
+			if (firstKey) this.evict(firstKey, "queue_full");
+		}
+
+		const id = `icm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+		return new Promise<IntercomResponse>((resolve) => {
+			const entry: PendingMessage = { message, id, resolve };
+
+			// Set timeout if specified
+			if (message.timeout && message.timeout > 0) {
+				entry.timer = setTimeout(() => {
+					resolve({
+						answer: "No response received within timeout",
+						source: "timeout",
+						timestamp: Date.now(),
+						messageId: id,
+					});
+					this.pending.delete(id);
+				}, message.timeout);
+			}
+
+			this.pending.set(id, entry);
+			this.queue.push({ ...message });
+		});
+	}
+
+	/**
+	 * Respond to a pending message by ID.
+	 */
+	respond(messageId: string, answer: string, source: "orchestrator" | "human" = "orchestrator"): boolean {
+		const entry = this.pending.get(messageId);
+		if (!entry) return false;
+
+		if (entry.timer) clearTimeout(entry.timer);
+
+		entry.resolve({
+			answer,
+			source,
+			timestamp: Date.now(),
+			messageId,
+		});
+
+		this.pending.delete(messageId);
+		return true;
+	}
+
+	/**
+	 * Get all pending messages (for orchestrator to process).
+	 */
+	getPending(): Array<IntercomMessage & { id: string }> {
+		return [...this.pending.entries()].map(([id, entry]) => ({
+			...entry.message,
+			id,
+		}));
+	}
+
+	/**
+	 * Number of pending messages awaiting response.
+	 */
+	get pendingCount(): number {
+		return this.pending.size;
+	}
+
+	/**
+	 * Clean up all pending messages (e.g., on run completion).
+	 */
+	clear(): void {
+		for (const [id, entry] of this.pending) {
+			this.evict(id, "run_complete");
+		}
+		this.queue = [];
+	}
+
+	private evict(id: string, reason: string): void {
+		const entry = this.pending.get(id);
+		if (!entry) return;
+
+		if (entry.timer) clearTimeout(entry.timer);
+
+		entry.resolve({
+			answer: `Message evicted: ${reason}`,
+			source: "timeout",
+			timestamp: Date.now(),
+			messageId: id,
+		});
+
+		this.pending.delete(id);
+	}
+}
+
+// ── Singleton per run ────────────────────────────────────────────────────
+
+const queues = new Map<string, IntercomQueue>();
+
+/**
+ * Get or create an intercom queue for a run.
+ */
+export function getIntercomQueue(runId: string): IntercomQueue {
+	let queue = queues.get(runId);
+	if (!queue) {
+		queue = new IntercomQueue();
+		queues.set(runId, queue);
+	}
+	return queue;
+}
+
+/**
+ * Clean up intercom queue for a completed run.
+ */
+export function cleanupIntercomQueue(runId: string): void {
+	const queue = queues.get(runId);
+	if (queue) {
+		queue.clear();
+		queues.delete(runId);
+	}
+}

package/src/runtime/plan-templates.ts

@@ -0,0 +1,200 @@
+/**
+ * Structured planning engine — template-based plan generation with verification.
+ *
+ * Pattern origin: plannotator/ — plan templates with task decomposition,
+ * verification constraints, and pre-execution plan verification.
+ *
+ * Templates provide reusable plan structures that can be specialized
+ * for different project types, replacing pure LLM-generated plans with
+ * deterministic scaffolding + LLM refinement.
+ */
+
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface PlanTemplate {
+	/** Template name (e.g., "standard-review", "full-implementation") */
+	name: string;
+	/** One-line description */
+	description: string;
+	/** Template phases */
+	phases: PlanPhase[];
+	/** Verification commands per phase (phaseName → command) */
+	verificationCommands: Record<string, string>;
+}
+
+export interface PlanPhase {
+	/** Phase name (e.g., "explore", "plan", "execute", "verify") */
+	name: string;
+	/** Agent role for this phase */
+	role: string;
+	/** Task description template — {{variables}} are substituted */
+	taskTemplate: string;
+	/** Maximum number of tasks in this phase */
+	maxTasks: number;
+	/** Dependencies on other phases */
+	dependsOn: string[];
+	/** Optional verification command */
+	verificationCommand?: string;
+}
+
+export interface RenderedPlan {
+	templateName: string;
+	phases: RenderedPhase[];
+	variables: Record<string, string>;
+}
+
+export interface RenderedPhase {
+	name: string;
+	role: string;
+	task: string;
+	dependsOn: string[];
+	verificationCommand?: string;
+}
+
+// ── Template Registry ────────────────────────────────────────────────────
+
+const templates = new Map<string, PlanTemplate>();
+
+/**
+ * Register a plan template.
+ */
+export function registerPlanTemplate(template: PlanTemplate): void {
+	templates.set(template.name, template);
+}
+
+/**
+ * Get a registered template by name.
+ */
+export function getPlanTemplate(name: string): PlanTemplate | undefined {
+	return templates.get(name);
+}
+
+/**
+ * List all registered template names.
+ */
+export function listPlanTemplates(): string[] {
+	return [...templates.keys()];
+}
+
+// ── Rendering ────────────────────────────────────────────────────────────
+
+/**
+ * Render a plan template with variable substitution.
+ *
+ * Variables in task templates use {{variableName}} syntax.
+ *
+ * @param templateName - Name of the registered template
+ * @param variables - Key-value pairs for substitution
+ * @returns Rendered plan, or undefined if template not found
+ */
+export function renderPlanTemplate(
+	templateName: string,
+	variables: Record<string, string>,
+): RenderedPlan | undefined {
+	const template = templates.get(templateName);
+	if (!template) {
+		logInternalError("plan-templates", new Error(`Template not found: ${templateName}`));
+		return undefined;
+	}
+
+	const phases: RenderedPhase[] = template.phases.map((phase) => ({
+		name: phase.name,
+		role: phase.role,
+		task: substituteVariables(phase.taskTemplate, variables),
+		dependsOn: phase.dependsOn,
+		verificationCommand: phase.verificationCommand ?? template.verificationCommands[phase.name],
+	}));
+
+	return { templateName, phases, variables };
+}
+
+/**
+ * Substitute {{variable}} placeholders in a template string.
+ */
+function substituteVariables(template: string, variables: Record<string, string>): string {
+	return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+		return variables[key] ?? match;
+	});
+}
+
+// ── Built-in Templates ───────────────────────────────────────────────────
+
+registerPlanTemplate({
+	name: "standard-review",
+	description: "Standard code review workflow: explore → review → verify",
+	phases: [
+		{
+			name: "explore",
+			role: "explorer",
+			taskTemplate: "Map the codebase and identify the key files related to: {{goal}}. Focus on: {{focusAreas}}.",
+			maxTasks: 1,
+			dependsOn: [],
+		},
+		{
+			name: "review",
+			role: "reviewer",
+			taskTemplate: "Review the code identified in the explore phase for: {{goal}}. Check correctness, maintainability, and security.",
+			maxTasks: 1,
+			dependsOn: ["explore"],
+		},
+		{
+			name: "verify",
+			role: "verifier",
+			taskTemplate: "Verify that all review findings are addressed. Run tests if applicable. Confirm: {{goal}} is achieved.",
+			maxTasks: 1,
+			dependsOn: ["review"],
+			verificationCommand: "npm test",
+		},
+	],
+	verificationCommands: {
+		verify: "npm test",
+	},
+});
+
+registerPlanTemplate({
+	name: "full-implementation",
+	description: "Full implementation workflow: explore → plan → execute → review → verify",
+	phases: [
+		{
+			name: "explore",
+			role: "explorer",
+			taskTemplate: "Explore the codebase to understand the current state relevant to: {{goal}}. Identify affected files and patterns.",
+			maxTasks: 1,
+			dependsOn: [],
+		},
+		{
+			name: "plan",
+			role: "planner",
+			taskTemplate: "Create a detailed implementation plan for: {{goal}}. Break down into concrete steps with file-level changes.",
+			maxTasks: 1,
+			dependsOn: ["explore"],
+		},
+		{
+			name: "execute",
+			role: "executor",
+			taskTemplate: "Implement the plan for: {{goal}}. Make all planned changes, write tests, and ensure TypeScript compiles.",
+			maxTasks: 3,
+			dependsOn: ["plan"],
+		},
+		{
+			name: "review",
+			role: "reviewer",
+			taskTemplate: "Review the implementation of: {{goal}}. Check for correctness, security, performance, and code quality.",
+			maxTasks: 1,
+			dependsOn: ["execute"],
+		},
+		{
+			name: "verify",
+			role: "verifier",
+			taskTemplate: "Verify the complete implementation of: {{goal}}. Run tests, check types, validate all acceptance criteria.",
+			maxTasks: 1,
+			dependsOn: ["review"],
+			verificationCommand: "npm test && npx tsc --noEmit",
+		},
+	],
+	verificationCommands: {
+		verify: "npm test && npx tsc --noEmit",
+	},
+});

package/src/runtime/task-graph.ts

@@ -215,3 +215,82 @@ export function detectCycles(tasks: TaskNode[]): string[][] {
 
 	return cycles;
 }
+
+/**
+ * Find tasks that are blocked (not completed, have incomplete dependencies).
+ *
+ * Pattern origin: pi-blueprint dependency-graph.ts findBlockedTasks()
+ *
+ * @param tasks - All task nodes
+ * @param completedIds - Set of completed task IDs
+ * @returns Array of blocked task IDs
+ */
+export function findBlockedTasks(tasks: TaskNode[], completedIds: Set<string>): string[] {
+	return tasks
+		.filter((t) => !completedIds.has(t.id))
+		.filter((t) => t.dependsOn.some((dep) => !completedIds.has(dep)))
+		.map((t) => t.id);
+}
+
+/**
+ * Get specific incomplete dependencies blocking a task.
+ *
+ * Pattern origin: pi-blueprint dependency-graph.ts getBlockingTasks()
+ *
+ * @param tasks - All task nodes
+ * @param taskId - The task to check
+ * @param completedIds - Set of completed task IDs
+ * @returns Array of blocking task IDs
+ */
+export function getBlockingTasks(tasks: TaskNode[], taskId: string, completedIds: Set<string>): string[] {
+	const task = tasks.find((t) => t.id === taskId);
+	if (!task) return [];
+	return task.dependsOn.filter((dep) => !completedIds.has(dep));
+}
+
+/**
+ * Topological sort using Kahn's BFS algorithm.
+ *
+ * Pattern origin: pi-blueprint dependency-graph.ts topologicalSort()
+ *
+ * @param tasks - All task nodes
+ * @returns Ordered array of task IDs (dependencies first)
+ */
+export function topologicalSort(tasks: TaskNode[]): string[] {
+	if (tasks.length === 0) return [];
+
+	const idSet = new Set(tasks.map((t) => t.id));
+	const inDegree = new Map<string, number>();
+	const adjacency = new Map<string, string[]>();
+
+	for (const task of tasks) {
+		inDegree.set(task.id, 0);
+		adjacency.set(task.id, []);
+	}
+
+	for (const task of tasks) {
+		for (const dep of task.dependsOn) {
+			if (!idSet.has(dep)) continue;
+			adjacency.get(dep)!.push(task.id);
+			inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1);
+		}
+	}
+
+	const queue: string[] = [];
+	for (const [id, deg] of inDegree) {
+		if (deg === 0) queue.push(id);
+	}
+
+	const result: string[] = [];
+	while (queue.length > 0) {
+		const id = queue.shift()!;
+		result.push(id);
+		for (const dependent of adjacency.get(id) ?? []) {
+			const deg = inDegree.get(dependent)! - 1;
+			inDegree.set(dependent, deg);
+			if (deg === 0) queue.push(dependent);
+		}
+	}
+
+	return result;
+}