pi-harness-runtime 0.2.0 → 0.3.1

package/harness/job-state-machine.ts

@@ -0,0 +1,363 @@
+/**
+ * Job State Machine — RFC-0015
+ *
+ * Manages job lifecycle states with:
+ * - Defined state transitions
+ * - Event emission on every transition
+ * - Automatic checkpointing
+ * - Transition guards (validity checks)
+ *
+ * States:
+ * created -> planning -> queued -> running -> testing -> e2e_testing ->
+ * reviewing -> repairing -> paused_quota -> waiting_human -> ready_for_client -> archived
+ */
+
+import type {
+	JobStatus,
+	RuntimeEvent,
+	RuntimeCheckpoint,
+} from "../packages/types/src/runtime-types.ts";
+
+export interface StateTransition {
+	from: JobStatus;
+	to: JobStatus;
+	event: string;
+	message: string;
+}
+
+export interface TransitionResult {
+	success: boolean;
+	checkpoint?: RuntimeCheckpoint;
+	error?: string;
+}
+
+// Valid transitions map
+const VALID_TRANSITIONS: Record<JobStatus, JobStatus[]> = {
+	created: ["planning"],
+	planning: ["queued", "cancelled"],
+	queued: ["running", "cancelled", "waiting_human"],
+	running: [
+		"testing",
+		"reviewing",
+		"repairing",
+		"paused_quota",
+		"blocked",
+		"waiting_human",
+		"cancelled",
+	],
+	testing: [
+		"reviewing",
+		"running",
+		"repairing",
+		"paused_quota",
+		"waiting_human",
+		"cancelled",
+	],
+	e2e_testing: [
+		"reviewing",
+		"repairing",
+		"paused_quota",
+		"waiting_human",
+		"cancelled",
+	],
+	reviewing: [
+		"repairing",
+		"running",
+		"ready_for_client",
+		"paused_quota",
+		"waiting_human",
+		"cancelled",
+	],
+	repairing: [
+		"running",
+		"testing",
+		"reviewing",
+		"paused_quota",
+		"waiting_human",
+		"cancelled",
+	],
+	paused_quota: ["running", "waiting_human", "cancelled"],
+	waiting_human: ["running", "planning", "cancelled"],
+	blocked: ["running", "waiting_human", "cancelled"],
+	ready_for_client: ["archived", "repairing"],
+	cancelled: [],
+	archived: [],
+};
+
+export interface JobStateMachineOptions {
+	checkpointManager: CheckpointManager;
+	eventEmitter?: (event: RuntimeEvent) => void;
+}
+
+export interface CheckpointManager {
+	save(checkpoint: RuntimeCheckpoint): Promise<void>;
+	load(jobId: string): Promise<RuntimeCheckpoint | null>;
+	appendEvent(jobId: string, event: RuntimeEvent): Promise<void>;
+}
+
+export class JobStateMachine {
+	private currentCheckpoint: RuntimeCheckpoint | null = null;
+	private readonly eventLog: RuntimeEvent[] = [];
+
+	constructor(private readonly options: JobStateMachineOptions) {}
+
+	/**
+	 * Initialize a new job with a requirement
+	 */
+	async createJob(
+		jobId: string,
+		requirement: string,
+	): Promise<TransitionResult> {
+		const now = new Date().toISOString();
+		const checkpoint: RuntimeCheckpoint = {
+			version: 1,
+			jobId,
+			status: "created",
+			requirement,
+			createdAt: now,
+			updatedAt: now,
+		};
+
+		const event = this.createEvent(
+			jobId,
+			"JobCreated",
+			`Job ${jobId} created with requirement`,
+			{ requirement },
+		);
+
+		try {
+			await this.options.checkpointManager.save(checkpoint);
+			await this.options.checkpointManager.appendEvent(jobId, event);
+			this.currentCheckpoint = checkpoint;
+			this.eventLog.push(event);
+			return { success: true, checkpoint };
+		} catch (error) {
+			return { success: false, error: String(error) };
+		}
+	}
+
+	/**
+	 * Resume a job from checkpoint
+	 */
+	async resumeJob(jobId: string): Promise<TransitionResult> {
+		const checkpoint = await this.options.checkpointManager.load(jobId);
+		if (!checkpoint) {
+			return { success: false, error: `No checkpoint found for job ${jobId}` };
+		}
+		this.currentCheckpoint = checkpoint;
+		return { success: true, checkpoint };
+	}
+
+	/**
+	 * Transition to a new state
+	 */
+	async transition(
+		to: JobStatus,
+		data?: Partial<RuntimeCheckpoint>,
+	): Promise<TransitionResult> {
+		if (!this.currentCheckpoint) {
+			return {
+				success: false,
+				error: "No active job. Call createJob() or resumeJob() first.",
+			};
+		}
+
+		const from = this.currentCheckpoint.status;
+
+		// Validate transition
+		if (!this.isValidTransition(from, to)) {
+			return {
+				success: false,
+				error: `Invalid transition: ${from} -> ${to}. Valid transitions: ${VALID_TRANSITIONS[from].join(", ") || "none"}`,
+			};
+		}
+
+		// Create updated checkpoint
+		const updated: RuntimeCheckpoint = {
+			...this.currentCheckpoint,
+			status: to,
+			updatedAt: new Date().toISOString(),
+			...data,
+		};
+
+		// Create event
+		const event = this.createEvent(
+			this.currentCheckpoint.jobId,
+			`StateTransition:${from}->${to}`,
+			`Transitioned from ${from} to ${to}`,
+			{ from, to, ...data },
+		);
+
+		try {
+			await this.options.checkpointManager.save(updated);
+			await this.options.checkpointManager.appendEvent(
+				this.currentCheckpoint.jobId,
+				event,
+			);
+			this.currentCheckpoint = updated;
+			this.eventLog.push(event);
+			return { success: true, checkpoint: updated };
+		} catch (error) {
+			return { success: false, error: String(error) };
+		}
+	}
+
+	/**
+	 * Check if a transition is valid
+	 */
+	isValidTransition(from: JobStatus, to: JobStatus): boolean {
+		return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+	}
+
+	/**
+	 * Get available next states from current state
+	 */
+	getAvailableTransitions(): JobStatus[] {
+		if (!this.currentCheckpoint) return [];
+		return VALID_TRANSITIONS[this.currentCheckpoint.status] ?? [];
+	}
+
+	/**
+	 * Get current checkpoint
+	 */
+	getCheckpoint(): RuntimeCheckpoint | null {
+		return this.currentCheckpoint;
+	}
+
+	/**
+	 * Get event log
+	 */
+	getEventLog(): RuntimeEvent[] {
+		return [...this.eventLog];
+	}
+
+	/**
+	 * Set current task
+	 */
+	async setCurrentTask(taskId: string): Promise<TransitionResult> {
+		return this.transition(this.currentCheckpoint!.status, {
+			currentTaskId: taskId,
+		});
+	}
+
+	/**
+	 * Set provider
+	 */
+	async setProvider(provider: string): Promise<TransitionResult> {
+		return this.transition(this.currentCheckpoint!.status, { provider });
+	}
+
+	/**
+	 * Set resume time (for quota pause)
+	 */
+	async setResumeTime(resumeAt: string): Promise<TransitionResult> {
+		if (!this.currentCheckpoint) {
+			return { success: false, error: "No active job" };
+		}
+		this.currentCheckpoint.resumeAt = resumeAt;
+		this.currentCheckpoint.updatedAt = new Date().toISOString();
+		try {
+			await this.options.checkpointManager.save(this.currentCheckpoint);
+			return { success: true, checkpoint: this.currentCheckpoint };
+		} catch (error) {
+			return { success: false, error: String(error) };
+		}
+	}
+
+	/**
+	 * Record an error
+	 */
+	async recordError(error: string): Promise<TransitionResult> {
+		if (!this.currentCheckpoint) {
+			return { success: false, error: "No active job" };
+		}
+		this.currentCheckpoint.lastError = error;
+		this.currentCheckpoint.updatedAt = new Date().toISOString();
+		try {
+			await this.options.checkpointManager.save(this.currentCheckpoint);
+			return { success: true, checkpoint: this.currentCheckpoint };
+		} catch (error) {
+			return { success: false, error: String(error) };
+		}
+	}
+
+	/**
+	 * Check if job is in a terminal state
+	 */
+	isTerminal(): boolean {
+		if (!this.currentCheckpoint) return false;
+		return ["ready_for_client", "cancelled", "archived"].includes(
+			this.currentCheckpoint.status,
+		);
+	}
+
+	/**
+	 * Check if job can be resumed
+	 */
+	canResume(): boolean {
+		if (!this.currentCheckpoint) return false;
+		return (
+			this.currentCheckpoint.status === "paused_quota" ||
+			this.currentCheckpoint.status === "blocked"
+		);
+	}
+
+	/**
+	 * Get job status summary
+	 */
+	getStatusSummary(): {
+		jobId: string;
+		status: JobStatus;
+		isTerminal: boolean;
+		canResume: boolean;
+	} | null {
+		if (!this.currentCheckpoint) return null;
+		return {
+			jobId: this.currentCheckpoint.jobId,
+			status: this.currentCheckpoint.status,
+			isTerminal: this.isTerminal(),
+			canResume: this.canResume(),
+		};
+	}
+
+	private createEvent(
+		jobId: string,
+		type: string,
+		message: string,
+		data?: Record<string, unknown>,
+	): RuntimeEvent {
+		return {
+			ts: new Date().toISOString(),
+			jobId,
+			type,
+			message,
+			data,
+		};
+	}
+}
+
+/**
+ * Factory to create a state machine with a JsonCheckpointManager
+ */
+export async function createJobStateMachine(
+	rootDir: string,
+	jobId?: string,
+): Promise<{ machine: JobStateMachine; checkpoint: RuntimeCheckpoint | null }> {
+	const { JsonCheckpointManager } = await import(
+		"../packages/checkpoint/src/checkpoint-manager.ts"
+	);
+
+	const manager = new JsonCheckpointManager(rootDir);
+
+	if (jobId) {
+		const checkpoint = await manager.load(jobId);
+		const machine = new JobStateMachine({ checkpointManager: manager });
+		if (checkpoint) {
+			machine.resumeJob(jobId);
+		}
+		return { machine, checkpoint };
+	}
+
+	const machine = new JobStateMachine({ checkpointManager: manager });
+	return { machine, checkpoint: null };
+}

package/harness/loop-runtime.ts

@@ -0,0 +1,337 @@
+/**
+ * Loop Runtime — RFC-0001
+ *
+ * Core execution loop for the harness runtime.
+ * Runs the repeated cycle:
+ *   pick task -> assign model -> code -> run tests -> review diff
+ *   -> if failed: repair
+ *   -> if quota_limit: pause and resume later
+ *   -> if blocked: escalate to human
+ */
+
+import type {
+	LoopConfig,
+	LoopState,
+	JobStatus,
+	RuntimeCheckpoint,
+	RuntimeTask,
+} from "../packages/types/src/runtime-types.ts";
+import { JobStateMachine } from "./job-state-machine.ts";
+import { TaskGraphManager } from "./task-graph.ts";
+import { RepairEngine } from "./repair-engine.ts";
+import type { CheckpointManager } from "./job-state-machine.ts";
+
+export interface LoopResult {
+	success: boolean;
+	completed: boolean;
+	iterations: number;
+	error?: string;
+}
+
+export interface LoopCallbacks {
+	onTaskStart?: (taskId: string) => Promise<void>;
+	onTaskComplete?: (taskId: string, report: unknown) => Promise<void>;
+	onTaskFailure?: (taskId: string, error: string) => Promise<void>;
+	onQuotaExceeded?: (provider: string) => Promise<void>;
+	onHumanEscalation?: (taskId: string, reason: string) => Promise<void>;
+	onIteration?: (iteration: number, status: string) => Promise<void>;
+	invokeAgent?: (
+		task: RuntimeTask,
+		context: unknown,
+	) => Promise<{ success: boolean; output?: string; error?: string }>;
+	runTests?: (
+		taskId: string,
+		worktreePath?: string,
+	) => Promise<{ passed: boolean; output?: string }>;
+	runReview?: (
+		taskId: string,
+		diffPath: string,
+	) => Promise<{ approved: boolean; comments?: string }>;
+}
+
+export class LoopRuntime {
+	private state: LoopState;
+	private machine: JobStateMachine;
+	private graph: TaskGraphManager;
+	private repairEngine: RepairEngine;
+	private callbacks: LoopCallbacks;
+	private running = false;
+	private paused = false;
+
+	constructor(
+		config: LoopConfig,
+		checkpointManager: CheckpointManager,
+		callbacks: LoopCallbacks,
+	) {
+		this.state = {
+			jobId: config.jobId,
+			iteration: 0,
+			status: "running",
+		};
+
+		this.machine = new JobStateMachine({ checkpointManager });
+		this.graph = new TaskGraphManager({ jobId: config.jobId });
+		this.repairEngine = new RepairEngine(config.jobId);
+		this.callbacks = callbacks;
+	}
+
+	/**
+	 * Initialize the loop with a job
+	 */
+	async init(requirement: string): Promise<void> {
+		await this.machine.createJob(this.state.jobId, requirement);
+		await this.machine.transition("planning");
+	}
+
+	/**
+	 * Resume from checkpoint
+	 */
+	async resume(checkpoint: RuntimeCheckpoint): Promise<void> {
+		this.state.iteration = 0;
+		await this.machine.resumeJob(checkpoint.jobId);
+	}
+
+	/**
+	 * Run the main loop
+	 */
+	async run(): Promise<LoopResult> {
+		this.running = true;
+
+		try {
+			while (this.running) {
+				// Check for pause
+				if (this.paused) {
+					await this.saveCheckpoint();
+					break;
+				}
+
+				this.state.iteration++;
+
+				// Check iteration limit
+				if (this.state.iteration > 1000) {
+					return {
+						success: false,
+						completed: false,
+						iterations: this.state.iteration,
+						error: "Max iterations exceeded",
+					};
+				}
+
+				await this.callbacks.onIteration?.(
+					this.state.iteration,
+					this.state.status,
+				);
+
+				// Check job status
+				if (this.machine.isTerminal()) {
+					return {
+						success: true,
+						completed: true,
+						iterations: this.state.iteration,
+					};
+				}
+
+				// Pick next task
+				const nextTask = await this.pickNextTask();
+				if (!nextTask) {
+					// No more tasks, job is complete
+					await this.machine.transition("ready_for_client");
+					return {
+						success: true,
+						completed: true,
+						iterations: this.state.iteration,
+					};
+				}
+
+				this.state.currentTaskId = nextTask.id;
+				this.state.status = "running";
+
+				// Execute task
+				const result = await this.executeTask(nextTask);
+
+				if (!result.success) {
+					// Handle failure
+					const { repairTask } = this.repairEngine.analyzeAndRepair(
+						nextTask.id,
+						result.error ?? "Unknown error",
+					);
+
+					if (this.repairEngine.shouldEscalate(repairTask.id)) {
+						await this.machine.transition("waiting_human");
+						await this.callbacks.onHumanEscalation?.(
+							nextTask.id,
+							result.error ?? "Unknown error",
+						);
+					} else {
+						await this.machine.transition("repairing");
+						// Continue loop to attempt repair
+					}
+				} else {
+					// Task succeeded
+					this.graph.updateTaskStatus(nextTask.id, "done");
+					await this.machine.transition("testing");
+
+					// Run tests
+					const testResult = await this.callbacks.runTests?.(
+						nextTask.id,
+						nextTask.worktreePath,
+					);
+					if (!testResult?.passed) {
+						await this.machine.transition("repairing");
+						this.graph.updateTaskStatus(nextTask.id, "failed");
+					} else {
+						await this.machine.transition("reviewing");
+
+						// Run review
+						const reviewResult = await this.callbacks.runReview?.(
+							nextTask.id,
+							nextTask.worktreePath ?? "",
+						);
+						if (!reviewResult?.approved) {
+							await this.machine.transition("repairing");
+						}
+					}
+				}
+
+				await this.saveCheckpoint();
+			}
+
+			return {
+				success: true,
+				completed: false,
+				iterations: this.state.iteration,
+			};
+		} catch (error) {
+			return {
+				success: false,
+				completed: false,
+				iterations: this.state.iteration,
+				error: String(error),
+			};
+		} finally {
+			this.running = false;
+		}
+	}
+
+	/**
+	 * Pick the next task to execute
+	 */
+	private async pickNextTask(): Promise<RuntimeTask | null> {
+		const readyTasks = this.graph.getReadyTasks();
+
+		// Pick the first ready task that's not assigned
+		for (const task of readyTasks) {
+			if (!task.assignedAgent) {
+				this.graph.assignAgent(task.id, "loop-runtime");
+				return task as unknown as RuntimeTask;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Execute a single task
+	 */
+	private async executeTask(task: RuntimeTask): Promise<{
+		success: boolean;
+		output?: string;
+		error?: string;
+	}> {
+		try {
+			await this.callbacks.onTaskStart?.(task.id);
+
+			const result = await this.callbacks.invokeAgent?.(task, {
+				jobId: this.state.jobId,
+				requirement: this.machine.getCheckpoint()?.requirement,
+			});
+
+			if (result?.success) {
+				await this.callbacks.onTaskComplete?.(task.id, {
+					output: result.output,
+				});
+				return { success: true, output: result.output };
+			} else {
+				const error = result?.error ?? "Agent returned failure";
+				await this.callbacks.onTaskFailure?.(task.id, error);
+				return { success: false, error };
+			}
+		} catch (error) {
+			return { success: false, error: String(error) };
+		}
+	}
+
+	/**
+	 * Pause the loop
+	 */
+	pause(): void {
+		this.paused = true;
+		this.state.status = "paused";
+	}
+
+	/**
+	 * Resume the loop
+	 */
+	async resumeLoop(): Promise<void> {
+		this.paused = false;
+		this.state.status = "running";
+	}
+
+	/**
+	 * Stop the loop
+	 */
+	stop(): void {
+		this.running = false;
+		this.state.status = "failed";
+	}
+
+	/**
+	 * Save checkpoint
+	 */
+	private async saveCheckpoint(): Promise<void> {
+		const checkpoint = this.machine.getCheckpoint();
+		if (checkpoint) {
+			await this.machine.transition(checkpoint.status, {
+				currentTaskId: this.state.currentTaskId,
+			});
+		}
+	}
+
+	/**
+	 * Get current state
+	 */
+	getState(): LoopState {
+		return this.state;
+	}
+
+	/**
+	 * Get job status
+	 */
+	getStatus(): {
+		status: JobStatus;
+		canResume: boolean;
+		isTerminal: boolean;
+	} | null {
+		const summary = this.machine.getStatusSummary();
+		if (!summary) return null;
+		return {
+			status: summary.status,
+			canResume: summary.canResume,
+			isTerminal: summary.isTerminal,
+		};
+	}
+
+	/**
+	 * Check if loop is running
+	 */
+	isRunning(): boolean {
+		return this.running && !this.paused;
+	}
+
+	/**
+	 * Check if loop is paused
+	 */
+	isPaused(): boolean {
+		return this.paused;
+	}
+}