pi-harness-runtime 0.2.0 → 0.3.0

package/index.ts

@@ -19,16 +19,60 @@ import type {
 	ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
 import { UsageTracker } from "./tracker.ts";
-import { MirrorStore, type MirrorRecord } from "./mirror.ts";
+import { MirrorStore } from "./mirror.ts";
 import { aggregateWindows } from "./windows.ts";
 import { renderStatus } from "./renderer.ts";
 import { buildMirrorRecord, parseSyncValues } from "./sync-form.ts";
+import {
+	JobStateMachine,
+	type CheckpointManager,
+} from "./harness/job-state-machine.ts";
+import { TaskGraphManager } from "./harness/task-graph.ts";
+import { MasterPlanner } from "./harness/master-planner.ts";
+import { RepairEngine } from "./harness/repair-engine.ts";
+import {
+	type SharedBlackboard,
+	createBlackboard,
+} from "./harness/blackboard.ts";
+import { homedir } from "node:os";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 
 const PROVIDER_DEFAULT = "minimax"; // can be changed via /usage sync form
 
+// ─── Harness Runtime State ────────────────────────────────────────────
+const HARNESS_ROOT_DIR = join(homedir(), ".pi", "harness");
+
+interface HarnessSession {
+	jobId: string;
+	machine: JobStateMachine;
+	graph: TaskGraphManager;
+	blackboard: SharedBlackboard;
+	repairEngine: RepairEngine;
+	createdAt: string;
+}
+
+let currentSession: HarnessSession | null = null;
+
+function ensureHarnessDir() {
+	if (!existsSync(HARNESS_ROOT_DIR)) {
+		mkdirSync(HARNESS_ROOT_DIR, { recursive: true });
+	}
+}
+
+async function getCheckpointManager(): Promise<CheckpointManager> {
+	const { JsonCheckpointManager } = await import(
+		"./packages/checkpoint/src/checkpoint-manager.ts"
+	);
+	return new JsonCheckpointManager(
+		HARNESS_ROOT_DIR,
+	) as unknown as CheckpointManager;
+}
+
 export default function (pi: ExtensionAPI) {
 	const tracker = new UsageTracker();
 	const mirrorStore = new MirrorStore();
+	ensureHarnessDir();
 
 	// ─── Auto-track every assistant message ──────────────────────────────
 	pi.on("message_end", async (event, ctx) => {
@@ -165,6 +209,255 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// ─── /harness start — Start a new harness job ──────────────────────
+	pi.registerCommand("harness-start", {
+		description: "Start a new harness job: /harness start <requirement>",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			if (!args.trim()) {
+				ctx.ui.notify("Usage: /harness start <requirement>", "error");
+				return;
+			}
+
+			const jobId = `job-${Date.now()}`;
+			const requirement = args.trim();
+
+			ctx.ui.notify(`Starting harness job ${jobId}...`, "info");
+
+			try {
+				const cm = await getCheckpointManager();
+				const machine = new JobStateMachine({ checkpointManager: cm });
+				const result = await machine.createJob(jobId, requirement);
+
+				if (!result.success) {
+					ctx.ui.notify(`Failed to create job: ${result.error}`, "error");
+					return;
+				}
+
+				// Create task graph using heuristic planner
+				const planner = new MasterPlanner();
+				const planResult = await planner.createPlan(
+					requirement,
+					jobId,
+					HARNESS_ROOT_DIR,
+				);
+
+				if (!planResult.success) {
+					ctx.ui.notify(`Failed to create plan: ${planResult.error}`, "error");
+					return;
+				}
+
+				// Create blackboard
+				const blackboard = createBlackboard(
+					jobId,
+					HARNESS_ROOT_DIR,
+					planResult.graph!,
+				);
+
+				// Create repair engine
+				const repairEngine = new RepairEngine(HARNESS_ROOT_DIR);
+
+				// Store session
+				currentSession = {
+					jobId,
+					machine,
+					graph: new TaskGraphManager({ jobId }),
+					blackboard,
+					repairEngine,
+					createdAt: new Date().toISOString(),
+				};
+
+				const taskCount = planResult.graph?.nodes
+					? Object.keys(planResult.graph.nodes).length
+					: 0;
+				ctx.ui.notify(
+					`Job ${jobId} created with ${taskCount} tasks.\n` +
+						`Requirement: ${requirement}\n\n` +
+						`Run /harness status to see tasks, or /harness tasks to list them.`,
+					"info",
+				);
+			} catch (e) {
+				ctx.ui.notify(`Error starting harness: ${e}`, "error");
+			}
+		},
+	});
+
+	// ─── /harness status — Show harness job status ─────────────────────
+	pi.registerCommand("harness-status", {
+		description: "Show current harness job status",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			if (!currentSession) {
+				ctx.ui.notify(
+					"No active harness job. Run /harness start <requirement> to begin.",
+					"info",
+				);
+				return;
+			}
+
+			const summary = currentSession.machine.getStatusSummary();
+			if (!summary) {
+				ctx.ui.notify("Failed to get job status.", "error");
+				return;
+			}
+
+			const progress = currentSession.graph.getProgressSummary();
+			const lines = [
+				`Harness Job Status`,
+				`${"─".repeat(40)}`,
+				`Job ID:     ${currentSession.jobId}`,
+				`Status:     ${summary.status}`,
+				`Terminal:   ${summary.isTerminal ? "Yes" : "No"}`,
+				`Can Resume: ${summary.canResume ? "Yes" : "No"}`,
+				`${"─".repeat(40)}`,
+				`Tasks:      ${progress.done}/${progress.total} done, ${progress.running} running, ${progress.failed} failed`,
+				`Created:    ${currentSession.createdAt}`,
+				`${"─".repeat(40)}`,
+				`Run /harness tasks for task list`,
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	// ─── /harness tasks — List all tasks ───────────────────────────────
+	pi.registerCommand("harness-tasks", {
+		description: "List all tasks in the current harness job",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			if (!currentSession) {
+				ctx.ui.notify(
+					"No active harness job. Run /harness start <requirement> to begin.",
+					"info",
+				);
+				return;
+			}
+
+			const tasks = currentSession.graph.getAllTasks();
+			if (tasks.length === 0) {
+				ctx.ui.notify(
+					"No tasks found. The job may not have been planned yet.",
+					"info",
+				);
+				return;
+			}
+
+			const lines = [
+				`Tasks for Job ${currentSession.jobId}`,
+				`${"─".repeat(50)}`,
+			];
+
+			for (const task of tasks) {
+				const status = task.status.padEnd(10);
+				const retry = task.retryCount ? ` (${task.retryCount} retries)` : "";
+				lines.push(`[${task.id}] ${status} ${task.title}${retry}`);
+				if (task.dependencies.length > 0) {
+					lines.push(`  deps: ${task.dependencies.join(", ")}`);
+				}
+			}
+
+			lines.push(`${"─".repeat(50)}`);
+			const ready = currentSession.graph.getReadyTasks();
+			lines.push(`${ready.length} tasks ready to execute.`);
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	// ─── /harness pause — Pause the harness job ───────────────────────
+	pi.registerCommand("harness-pause", {
+		description: "Pause the current harness job",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			if (!currentSession) {
+				ctx.ui.notify("No active harness job to pause.", "info");
+				return;
+			}
+
+			const checkpoint = currentSession.machine.getCheckpoint();
+			if (!checkpoint) {
+				ctx.ui.notify("Failed to get checkpoint.", "error");
+				return;
+			}
+
+			const result = await currentSession.machine.transition("paused_quota");
+			if (!result.success) {
+				ctx.ui.notify(`Failed to pause: ${result.error}`, "error");
+				return;
+			}
+
+			ctx.ui.notify(
+				`Job ${currentSession.jobId} paused.\n` +
+					`Current status: paused_quota\n` +
+					`Run /harness resume to continue.`,
+				"info",
+			);
+		},
+	});
+
+	// ─── /harness resume — Resume the harness job ───────────────────────
+	pi.registerCommand("harness-resume", {
+		description: "Resume a paused harness job",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			if (!currentSession) {
+				ctx.ui.notify("No active harness job to resume.", "info");
+				return;
+			}
+
+			const checkpoint = currentSession.machine.getCheckpoint();
+			if (!checkpoint || checkpoint.status !== "paused_quota") {
+				ctx.ui.notify(
+					"Job is not paused. Run /harness start to begin a new job.",
+					"info",
+				);
+				return;
+			}
+
+			const result = await currentSession.machine.transition("running");
+			if (!result.success) {
+				ctx.ui.notify(`Failed to resume: ${result.error}`, "error");
+				return;
+			}
+
+			ctx.ui.notify(
+				`Job ${currentSession.jobId} resumed.\n` +
+					`Current status: running\n` +
+					`Run /harness status to monitor progress.`,
+				"info",
+			);
+		},
+	});
+
+	// ─── /harness cancel — Cancel the harness job ──────────────────────
+	pi.registerCommand("harness-cancel", {
+		description: "Cancel the current harness job",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			if (!currentSession) {
+				ctx.ui.notify("No active harness job to cancel.", "info");
+				return;
+			}
+
+			const ok = await ctx.ui.confirm(
+				`Cancel job ${currentSession.jobId}?`,
+				"This will mark the job as cancelled. Task state is preserved but work stops.",
+			);
+
+			if (!ok) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			const result = await currentSession.machine.transition("cancelled");
+			if (!result.success) {
+				ctx.ui.notify(`Failed to cancel: ${result.error}`, "error");
+				return;
+			}
+
+			const sessionJobId = currentSession.jobId;
+			currentSession = null;
+
+			ctx.ui.notify(
+				`Job ${sessionJobId} cancelled.\n` +
+					`Run /harness start to begin a new job.`,
+				"info",
+			);
+		},
+	});
+
 	// ─── Footer status (persistent badge) ────────────────────────────────
 	pi.on("session_start", async (_event, ctx) => {
 		await refreshFooterStatus(ctx, mirrorStore, tracker);
@@ -185,7 +478,6 @@ async function refreshFooterStatus(
 ) {
 	const local = aggregateWindows(tracker.all());
 	const mirror = mirrorStore.read();
-	const now = Date.now();
 
 	const todayStr = `${(local.today.tokens / 1000).toFixed(1)}k tok · $${local.today.cost.toFixed(3)}`;
 	let summary = `today: ${todayStr}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-runtime",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Codex-style /usage status for pi: local token tracking + provider mirror",
   "type": "module",
   "scripts": {
@@ -19,6 +19,8 @@
     "renderer.ts",
     "sync-form.ts",
     "cli.ts",
+    "harness",
+    "packages",
     "skills",
     "package.json",
     "README.md",
@@ -60,6 +62,7 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@types/node": "^20.14.0",
     "standard-version": "^9.5.0"
   }
-}
+}

package/packages/checkpoint/README.md

@@ -0,0 +1,3 @@
+# packages/checkpoint
+
+Checkpoint persistence and restore logic will live here.

package/packages/checkpoint/src/checkpoint-manager.ts

@@ -0,0 +1,38 @@
+import { mkdir, readFile, rename, writeFile, appendFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { RuntimeCheckpoint, RuntimeEvent } from "../../types/src/runtime-types";
+
+export class JsonCheckpointManager {
+  constructor(private readonly rootDir: string) {}
+
+  private jobDir(jobId: string): string {
+    return join(this.rootDir, "jobs", jobId);
+  }
+
+  private checkpointPath(jobId: string): string {
+    return join(this.jobDir(jobId), "checkpoint.json");
+  }
+
+  async save(checkpoint: RuntimeCheckpoint): Promise<void> {
+    const path = this.checkpointPath(checkpoint.jobId);
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(checkpoint, null, 2) + "\n", "utf-8");
+    await rename(tmp, path);
+  }
+
+  async load(jobId: string): Promise<RuntimeCheckpoint | null> {
+    try {
+      const text = await readFile(this.checkpointPath(jobId), "utf-8");
+      return JSON.parse(text) as RuntimeCheckpoint;
+    } catch {
+      return null;
+    }
+  }
+
+  async appendEvent(jobId: string, event: RuntimeEvent): Promise<void> {
+    const path = join(this.jobDir(jobId), "events.jsonl");
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, JSON.stringify(event) + "\n", "utf-8");
+  }
+}

package/packages/provider-router/src/provider-router.ts

@@ -0,0 +1,42 @@
+import type { ProviderSelection, RuntimeContext, RuntimeTask } from "../../types/src/runtime-types";
+
+export interface RoutingPolicy {
+  plannerProvider: string;
+  codeProviders: string[];
+  reviewProvider: string;
+  fallbackProviders: string[];
+}
+
+export class SimpleProviderRouter {
+  constructor(private readonly policy: RoutingPolicy) {}
+
+  async selectProvider(task: RuntimeTask, context: RuntimeContext): Promise<ProviderSelection> {
+    const candidates = this.candidatesForTask(task);
+
+    for (const providerId of candidates) {
+      const state = context.providerStates[providerId] ?? "unknown";
+      if (state === "available" || state === "unknown") {
+        return {
+          providerId,
+          reason: `selected ${providerId} for task ${task.id}; state=${state}`,
+        };
+      }
+    }
+
+    throw new Error(`No available provider for task ${task.id}`);
+  }
+
+  private candidatesForTask(task: RuntimeTask): string[] {
+    const title = task.title.toLowerCase();
+
+    if (title.includes("plan") || title.includes("architecture")) {
+      return [this.policy.plannerProvider, ...this.policy.fallbackProviders];
+    }
+
+    if (title.includes("review") || title.includes("diff")) {
+      return [this.policy.reviewProvider, ...this.policy.fallbackProviders];
+    }
+
+    return [...this.policy.codeProviders, ...this.policy.fallbackProviders];
+  }
+}

package/packages/providers/README.md

@@ -0,0 +1,3 @@
+# packages/providers
+
+Provider adapter interfaces and provider-specific implementations will live here.

package/packages/providers/adapters.ts

@@ -0,0 +1,261 @@
+/**
+ * Provider Adapter — RFC-0002
+ *
+ * Normalizes provider-specific behavior for:
+ * - model invocation
+ * - error detection
+ * - quota detection
+ * - reset time discovery
+ * - retry policy
+ * - model capability metadata
+ */
+
+import type {
+	ProviderConfig,
+	ProviderCapability,
+	ProviderRequest,
+	ProviderResponse,
+} from "../../packages/types/src/runtime-types.ts";
+
+export interface AdapterConfig {
+	provider: ProviderConfig;
+	quotaSignalExtractor?: (error: unknown) => QuotaSignal | null;
+}
+
+export interface QuotaSignal {
+	exhausted: boolean;
+	resetsAt?: string;
+	retryAfterMs?: number;
+}
+
+export interface AdapterResult {
+	response: ProviderResponse;
+	quotaSignal?: QuotaSignal;
+	retryable: boolean;
+}
+
+export interface ProviderAdapter {
+	readonly id: string;
+	readonly name: string;
+
+	invoke(request: ProviderRequest): Promise<AdapterResult>;
+
+	parseError(error: unknown): {
+		quotaExceeded: boolean;
+		rateLimited: boolean;
+		timeout: boolean;
+		serverError: boolean;
+		clientError: boolean;
+		quotaSignal?: QuotaSignal;
+	};
+
+	getCapabilities(): ProviderCapability[];
+
+	supportsModel(model: string): boolean;
+
+	getDefaultModel(): string;
+
+	getMaxTokens(model?: string): number;
+}
+
+/**
+ * Base adapter with common functionality
+ */
+export abstract class BaseProviderAdapter implements ProviderAdapter {
+	abstract readonly id: string;
+	abstract readonly name: string;
+
+	constructor(protected config: ProviderConfig) {}
+
+	abstract invoke(request: ProviderRequest): Promise<AdapterResult>;
+
+	abstract parseError(error: unknown): {
+		quotaExceeded: boolean;
+		rateLimited: boolean;
+		timeout: boolean;
+		serverError: boolean;
+		clientError: boolean;
+		quotaSignal?: QuotaSignal;
+	};
+
+	getCapabilities(): ProviderCapability[] {
+		return this.config.capabilities;
+	}
+
+	supportsModel(model: string): boolean {
+		return this.config.models.includes(model);
+	}
+
+	getDefaultModel(): string {
+		return this.config.models[0] ?? "default";
+	}
+
+	getMaxTokens(model?: string): number {
+		// Default token limits per model family
+		const limits: Record<string, number> = {
+			"minimax/MiniMax-M3": 32768,
+			"minimax/MiniMax-Text-01": 1000000,
+			"anthropic/claude-3-5-sonnet": 200000,
+			"openai/gpt-4o": 128000,
+			"openai/gpt-4-turbo": 128000,
+		};
+		return limits[model ?? this.getDefaultModel()] ?? 4096;
+	}
+
+	/**
+	 * Parse usage from response
+	 */
+	protected parseUsage(response: unknown): ProviderResponse["usage"] {
+		const r = response as Record<string, unknown>;
+		return {
+			input: (r.input_tokens as number) ?? (r.prompt_tokens as number) ?? 0,
+			output:
+				(r.output_tokens as number) ?? (r.completion_tokens as number) ?? 0,
+			cacheRead: (r.cache_read_tokens as number) ?? 0,
+			cacheWrite: (r.cache_write_tokens as number) ?? 0,
+			cost: (r.cost as number) ?? 0,
+		};
+	}
+}
+
+/**
+ * MiniMax adapter
+ */
+export class MiniMaxAdapter extends BaseProviderAdapter {
+	readonly id = "minimax";
+	readonly name = "MiniMax";
+
+	async invoke(request: ProviderRequest): Promise<AdapterResult> {
+		// In practice, this would call the MiniMax API
+		// For now, return a mock response
+		return {
+			response: {
+				content: "Mock response",
+				usage: { input: 100, output: 200, cost: 0.001 },
+				model: request.model,
+				finishReason: "stop",
+			},
+			retryable: false,
+		};
+	}
+
+	parseError(error: unknown): {
+		quotaExceeded: boolean;
+		rateLimited: boolean;
+		timeout: boolean;
+		serverError: boolean;
+		clientError: boolean;
+		quotaSignal?: QuotaSignal;
+	} {
+		const e = error as Record<string, unknown>;
+		const msg = String(e.message ?? e.error ?? "").toLowerCase();
+
+		return {
+			quotaExceeded: msg.includes("2056") || msg.includes("quota"),
+			rateLimited: msg.includes("rate limit") || msg.includes("429"),
+			timeout: msg.includes("timeout") || msg.includes("timed out"),
+			serverError:
+				msg.includes("500") || msg.includes("502") || msg.includes("503"),
+			clientError:
+				msg.includes("400") || msg.includes("401") || msg.includes("403"),
+			quotaSignal:
+				msg.includes("quota") || msg.includes("2056")
+					? { exhausted: true, resetsAt: undefined }
+					: undefined,
+		};
+	}
+}
+
+/**
+ * OpenAI adapter
+ */
+export class OpenAIAdapter extends BaseProviderAdapter {
+	readonly id = "openai";
+	readonly name = "OpenAI";
+
+	async invoke(request: ProviderRequest): Promise<AdapterResult> {
+		return {
+			response: {
+				content: "Mock response",
+				usage: { input: 100, output: 200, cost: 0.002 },
+				model: request.model,
+				finishReason: "stop",
+			},
+			retryable: false,
+		};
+	}
+
+	parseError(error: unknown): {
+		quotaExceeded: boolean;
+		rateLimited: boolean;
+		timeout: boolean;
+		serverError: boolean;
+		clientError: boolean;
+		quotaSignal?: QuotaSignal;
+	} {
+		const e = error as Record<string, unknown>;
+		const msg = String(e.message ?? e.error ?? "").toLowerCase();
+		const code = String(e.code ?? "");
+
+		return {
+			quotaExceeded:
+				code === "insufficient_quota" || code === "context_length_exceeded",
+			rateLimited: code === "rate_limit_exceeded" || msg.includes("429"),
+			timeout: msg.includes("timeout"),
+			serverError: code.startsWith("5"),
+			clientError: code.startsWith("4"),
+			quotaSignal:
+				code === "insufficient_quota"
+					? { exhausted: true, resetsAt: undefined }
+					: undefined,
+		};
+	}
+}
+
+/**
+ * Adapter registry
+ */
+export class AdapterRegistry {
+	private adapters: Map<string, ProviderAdapter> = new Map();
+
+	register(adapter: ProviderAdapter): void {
+		this.adapters.set(adapter.id, adapter);
+	}
+
+	get(id: string): ProviderAdapter | undefined {
+		return this.adapters.get(id);
+	}
+
+	list(): ProviderAdapter[] {
+		return Array.from(this.adapters.values());
+	}
+
+	/**
+	 * Create default registry with standard adapters
+	 */
+	static createDefault(): AdapterRegistry {
+		const registry = new AdapterRegistry();
+
+		registry.register(
+			new MiniMaxAdapter({
+				id: "minimax",
+				name: "MiniMax",
+				models: ["minimax/MiniMax-M3", "minimax/MiniMax-Text-01"],
+				capabilities: ["code", "review", "plan", "test"],
+				rateLimits: {},
+			}),
+		);
+
+		registry.register(
+			new OpenAIAdapter({
+				id: "openai",
+				name: "OpenAI",
+				models: ["openai/gpt-4o", "openai/gpt-4-turbo"],
+				capabilities: ["code", "review", "plan", "test", "refactor"],
+				rateLimits: {},
+			}),
+		);
+
+		return registry;
+	}
+}

package/packages/quota-manager/README.md

@@ -0,0 +1,3 @@
+# packages/quota-manager
+
+Quota detection, reset-time handling, and pause/resume logic will live here.