pi-harness-runtime 0.10.11 → 0.10.12

package/packages/checkpoint/src/types.ts

@@ -0,0 +1,348 @@
+/**
+ * Checkpoint Engine - Types
+ *
+ * Core types for the enhanced checkpoint system.
+ */
+
+// --- SDK Version ------------------------------------------------------------
+
+/**
+ * SDK version for compatibility checks
+ */
+export const SDK_VERSION = "1.0.0";
+
+// --- Task Types ---------------------------------------------------------
+
+/**
+ * Task status
+ */
+export type TaskStatus = "pending" | "running" | "done" | "failed" | "blocked";
+
+/**
+ * Runtime task
+ */
+export interface RuntimeTask {
+	id: string;
+	title: string;
+	description: string;
+	status: TaskStatus;
+	assignedProvider?: string;
+	worktreePath?: string;
+	acceptanceCriteria?: string[];
+}
+
+// --- Job Types ----------------------------------------------------------
+
+/**
+ * Job status
+ */
+export type JobStatus =
+	| "pending"
+	| "running"
+	| "blocked"
+	| "completed"
+	| "failed"
+	| "cancelled"
+	| "archived";
+
+// --- State Types ---------------------------------------------------------
+
+/**
+ * Runtime state to be checkpointed
+ */
+export interface RuntimeState {
+	version: number;
+	jobId: string;
+	status: JobStatus;
+	requirement: string;
+	currentTaskId?: string;
+	provider?: string;
+	resumeAt?: string;
+	lastError?: string;
+	tasks: RuntimeTask[];
+	createdAt: string;
+	updatedAt: string;
+	metadata?: Record<string, unknown>;
+}
+
+// --- Checkpoint Types ----------------------------------------------------
+
+/**
+ * Checkpoint type
+ */
+export type CheckpointType = "full" | "incremental";
+
+/**
+ * Checkpoint metadata
+ */
+export interface CheckpointMetadata {
+	jobId: string;
+	version: number;
+	type: CheckpointType;
+	sizeBytes: number;
+	compressed: boolean;
+	checksum: string;
+	taskProgress: {
+		total: number;
+		completed: number;
+		failed: number;
+		running: number;
+	};
+	createdAt: string;
+	expiresAt?: string;
+	baseVersion?: number; // For incremental checkpoints
+}
+
+/**
+ * Full checkpoint data
+ */
+export interface FullCheckpoint {
+	jobId: string;
+	version: number;
+	type: "full";
+	state: RuntimeState;
+	metadata: CheckpointMetadata;
+}
+
+/**
+ * State delta for incremental checkpoints
+ */
+export interface StateDelta {
+	jobId: string;
+	baseVersion: number;
+	targetVersion: number;
+	changes: {
+		status?: JobStatus;
+		tasks?: TaskDelta[];
+		context?: ContextDiff;
+		errors?: ErrorEntry[];
+		metadata?: Record<string, unknown>;
+	};
+	timestamp: string;
+	checksum: string;
+}
+
+/**
+ * Task delta
+ */
+export interface TaskDelta {
+	taskId: string;
+	action: "added" | "updated" | "removed";
+	before?: Partial<RuntimeTask>;
+	after?: Partial<RuntimeTask>;
+}
+
+/**
+ * Context diff
+ */
+export interface ContextDiff {
+	added?: Record<string, unknown>;
+	removed?: string[];
+	updated?: Record<string, { before: unknown; after: unknown }>;
+}
+
+/**
+ * Error entry
+ */
+export interface ErrorEntry {
+	taskId?: string;
+	error: string;
+	timestamp: string;
+	recoverable: boolean;
+}
+
+/**
+ * Incremental checkpoint data
+ */
+export interface IncrementalCheckpoint {
+	jobId: string;
+	version: number;
+	type: "incremental";
+	delta: StateDelta;
+	metadata: CheckpointMetadata;
+}
+
+// --- Recovery Types ------------------------------------------------------
+
+/**
+ * Recovery strategy
+ */
+export type RecoveryStrategy =
+	| "latest" // Use most recent checkpoint
+	| "fullest" // Use checkpoint with most completed tasks
+	| `specific:${number}` // Use specific version number
+	| `timestamp:${string}` // Use checkpoint closest to timestamp
+	| "interactive"; // User selects from list
+
+/**
+ * Recovery result
+ */
+export interface RecoveryResult {
+	success: boolean;
+	recoveredVersion: number;
+	recoveredState?: RuntimeState;
+	lostEvents: number;
+	recoveryTimeMs: number;
+	errors?: string[];
+	warnings?: string[];
+}
+
+/**
+ * Verification result
+ */
+export interface VerificationResult {
+	valid: boolean;
+	checksumMatch: boolean;
+	corruptionDetails?: string[];
+}
+
+/**
+ * Prune result
+ */
+export interface PruneResult {
+	deletedCount: number;
+	freedBytes: number;
+	remainingCount: number;
+	errors?: string[];
+}
+
+// --- Storage Types -------------------------------------------------------
+
+/**
+ * Checkpoint file stored on disk
+ */
+export interface CheckpointFile {
+	jobId: string;
+	version: number;
+	type: CheckpointType;
+	data: string;
+	metadata: CheckpointMetadata;
+}
+
+/**
+ * Index entry for a checkpoint
+ */
+export interface IndexEntry {
+	jobId: string;
+	version: number;
+	type: CheckpointType;
+	path: string;
+	compressed: boolean;
+	checksum: string;
+	size: number;
+	createdAt: string;
+	baseVersion?: number;
+}
+
+/**
+ * Checkpoint index for a job
+ */
+export interface CheckpointIndex {
+	jobId: string;
+	entries: IndexEntry[];
+	currentVersion: number;
+	lastUpdated: string;
+}
+
+// --- Configuration --------------------------------------------------------
+
+/**
+ * Checkpoint engine configuration
+ */
+export interface CheckpointEngineConfig {
+	/**
+	 * Root directory for checkpoint storage
+	 */
+	rootDir?: string;
+
+	/**
+	 * Enable compression for checkpoints
+	 */
+	compression?: boolean;
+
+	/**
+	 * Enable incremental checkpoints
+	 */
+	incremental?: boolean;
+
+	/**
+	 * Maximum number of checkpoints to keep
+	 */
+	maxCheckpoints?: number;
+
+	/**
+	 * Automatically prune old checkpoints on save
+	 */
+	autoPrune?: boolean;
+
+	/**
+	 * Checksum algorithm
+	 */
+	checksumAlgorithm?: "md5" | "sha256";
+
+	/**
+	 * Enable parallel file writes
+	 */
+	parallelWrites?: boolean;
+
+	/**
+	 * Build metadata index
+	 */
+	metadataIndex?: boolean;
+}
+
+// --- Event Types ---------------------------------------------------------
+
+/**
+ * Checkpoint event
+ */
+export interface CheckpointEvent {
+	type: "checkpoint" | "recovery" | "prune" | "verify";
+	jobId: string;
+	version?: number;
+	timestamp: string;
+	data?: Record<string, unknown>;
+}
+
+/**
+ * Event log entry
+ */
+export interface EventLogEntry {
+	id: string;
+	event: CheckpointEvent;
+	correlationId?: string;
+}
+
+// --- Legacy Types --------------------------------------------------------
+
+/**
+ * Legacy checkpoint format
+ */
+export interface LegacyCheckpoint {
+	version: number;
+	jobId: string;
+	status: string;
+	state: Record<string, unknown>;
+	timestamp: string;
+}
+
+/**
+ * Check if a checkpoint is in legacy format
+ */
+export function isLegacyCheckpoint(
+	checkpoint: unknown,
+): checkpoint is LegacyCheckpoint {
+	if (typeof checkpoint !== "object" || checkpoint === null) {
+		return false;
+	}
+
+	const cp = checkpoint as Record<string, unknown>;
+
+	return (
+		typeof cp.version === "number" &&
+		typeof cp.jobId === "string" &&
+		typeof cp.status === "string" &&
+		cp.state !== undefined &&
+		typeof cp.timestamp === "string"
+	);
+}

package/packages/cli-plugin-sdk/src/index.ts

@@ -0,0 +1,169 @@
+/**
+ * CLI Plugin SDK — Main Entry (RFC-0067)
+ */
+
+import { execa } from "execa";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { searchPlugins } from "./registry.js";
+import {
+	isInstalled,
+	getInstalledPlugin,
+	listInstalledPlugins,
+} from "./plugin-fs.js";
+import type {
+	PluginCLIConfig,
+	InstalledPlugin,
+	PluginSearchResult,
+	InvokeResult,
+} from "./types.js";
+
+export type {
+	PluginCLIConfig,
+	InstalledPlugin,
+	PluginSearchResult,
+	InvokeResult,
+};
+
+/**
+ * CLI SDK for managing pi-harness plugins
+ */
+export class PluginCLI {
+	private readonly config: Required<PluginCLIConfig>;
+
+	constructor(config: PluginCLIConfig = {}) {
+		this.config = {
+			cwd: config.cwd ?? process.cwd(),
+			globalDir: config.globalDir ?? "",
+			registry: config.registry ?? "https://registry.npmjs.org",
+			npmBin: config.npmBin ?? "npm",
+		};
+	}
+
+	/** Install a plugin from npm */
+	async install(
+		name: string,
+		options: { version?: string; global?: boolean } = {},
+	): Promise<void> {
+		const { version, global = false } = options;
+
+		let normalizedName = name;
+		if (!name.startsWith("@") && !name.startsWith("pi-")) {
+			normalizedName = name.startsWith("plugin-")
+				? `@pi/${name}`
+				: `@pi/plugin-${name}`;
+			console.warn(`Normalizing "${name}" to "${normalizedName}"`);
+		}
+
+		const pkgSpec = version ? `${normalizedName}@${version}` : normalizedName;
+		const args = [
+			this.config.npmBin,
+			"install",
+			pkgSpec,
+			global ? "--global" : "--save",
+		];
+		if (this.config.registry) {
+			args.push("--registry", this.config.registry);
+		}
+
+		await execa(args[0], args.slice(1), {
+			cwd: this.config.cwd,
+			stdio: "inherit",
+		});
+	}
+
+	/** Remove an installed plugin */
+	async remove(name: string): Promise<void> {
+		if (!isInstalled(name, this.config)) {
+			throw new Error(`Plugin "${name}" is not installed`);
+		}
+
+		await execa(this.config.npmBin, ["uninstall", name, "--save"], {
+			cwd: this.config.cwd,
+			stdio: "inherit",
+		});
+	}
+
+	/** List all installed plugins */
+	async list(): Promise<InstalledPlugin[]> {
+		return listInstalledPlugins(this.config);
+	}
+
+	/** Update plugin(s) */
+	async update(name?: string): Promise<void> {
+		const args = [this.config.npmBin, "update"];
+		if (name) args.push(name);
+		else args.push("@pi/*");
+		if (this.config.registry) args.push("--registry", this.config.registry);
+
+		await execa(args[0], args.slice(1), {
+			cwd: this.config.cwd,
+			stdio: "inherit",
+		});
+	}
+
+	/** Search npm for plugins */
+	async search(query: string): Promise<PluginSearchResult[]> {
+		const results = await Promise.all([
+			searchPlugins(`@pi/plugin-${query}`, this.config.registry),
+			searchPlugins(`@pi/${query}-plugin`, this.config.registry),
+			searchPlugins(query, this.config.registry),
+		]);
+
+		const seen = new Set<string>();
+		const deduped: PluginSearchResult[] = [];
+		for (const r of results.flat()) {
+			if (!seen.has(r.name)) {
+				seen.add(r.name);
+				deduped.push(r);
+			}
+		}
+		return deduped.slice(0, 20);
+	}
+
+	/** Invoke a plugin exported function */
+	async invoke(
+		pluginName: string,
+		command: string,
+		args: Record<string, unknown> = {},
+	): Promise<InvokeResult> {
+		const plugin = getInstalledPlugin(pluginName, this.config);
+		if (!plugin) {
+			return { success: false, error: `Plugin "${pluginName}" not found` };
+		}
+
+		try {
+			const pluginPath = join(
+				plugin.path,
+				plugin.manifest?.entryPoint ?? "dist/index.js",
+			);
+			if (!existsSync(pluginPath)) {
+				return {
+					success: false,
+					error: `Plugin entry not found at ${pluginPath}`,
+				};
+			}
+
+			const mod = await import(pluginPath);
+			const fn = mod[command] ?? mod.default?.[command];
+			if (typeof fn !== "function") {
+				return {
+					success: false,
+					error: `Function "${command}" not found in plugin`,
+				};
+			}
+
+			const result = await fn(args);
+			return { success: true, result };
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return { success: false, error: message };
+		}
+	}
+
+	/** Get path to an installed plugin */
+	getPluginPath(name: string): string | null {
+		const plugin = getInstalledPlugin(name, this.config);
+		return plugin?.path ?? null;
+	}
+}

package/packages/cli-plugin-sdk/src/plugin-fs.ts

@@ -0,0 +1,91 @@
+/**
+ * CLI Plugin SDK — Filesystem Operations (RFC-0067)
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { InstalledPlugin, PluginCLIConfig } from "./types.js";
+
+/**
+ * Resolve plugin directory from config
+ */
+export function resolvePluginDir(config: PluginCLIConfig): string {
+	return config.globalDir ?? join(config.cwd ?? process.cwd(), "node_modules");
+}
+
+/**
+ * Check if a plugin is installed
+ */
+export function isInstalled(name: string, config: PluginCLIConfig): boolean {
+	const dir = join(resolvePluginDir(config), name);
+	return existsSync(dir);
+}
+
+/**
+ * Get installed plugin info
+ */
+export function getInstalledPlugin(
+	name: string,
+	config: PluginCLIConfig,
+): InstalledPlugin | null {
+	const dir = join(resolvePluginDir(config), name);
+	if (!existsSync(dir)) return null;
+
+	let manifest: InstalledPlugin["manifest"] = null;
+	const pkgPath = join(dir, "package.json");
+	if (existsSync(pkgPath)) {
+		try {
+			manifest = JSON.parse(
+				readFileSync(pkgPath, "utf-8"),
+			) as InstalledPlugin["manifest"];
+		} catch {
+			// ignore parse errors
+		}
+	}
+
+	return {
+		name,
+		version: manifest?.version ?? "unknown",
+		path: dir,
+		manifest,
+	};
+}
+
+/**
+ * List all installed pi-* plugins
+ */
+export function listInstalledPlugins(
+	config: PluginCLIConfig,
+): InstalledPlugin[] {
+	const pluginDir = resolvePluginDir(config);
+	if (!existsSync(pluginDir)) return [];
+
+	const plugins: InstalledPlugin[] = [];
+	try {
+		const entries = readdirSync(pluginDir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const name = entry.name;
+			const fullPath = join(pluginDir, name);
+			try {
+				const pkgPath = join(fullPath, "package.json");
+				if (!existsSync(pkgPath)) continue;
+				const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+					version?: string;
+					pi?: { sdkVersion?: string };
+					name?: string;
+				};
+				if (!pkg.pi && !pkg.name?.startsWith("@pi/")) continue;
+				plugins.push({
+					name: pkg.name ?? name,
+					version: pkg.version ?? "unknown",
+					path: fullPath,
+					manifest: pkg as InstalledPlugin["manifest"],
+				});
+			} catch {}
+		}
+	} catch {
+		// dir doesn't exist
+	}
+	return plugins;
+}

package/packages/cli-plugin-sdk/src/registry.ts

@@ -0,0 +1,55 @@
+/**
+ * CLI Plugin SDK — NPM Registry Client (RFC-0067)
+ */
+
+import { execa } from "execa";
+import type { PluginSearchResult } from "./types.js";
+
+/**
+ * Query npm registry for plugins matching query
+ */
+export async function searchPlugins(
+	query: string,
+	registry?: string,
+): Promise<PluginSearchResult[]> {
+	try {
+		const args = ["search", query, "--json", "--prefer-online"];
+		if (registry) args.push("--registry", registry);
+		const { stdout } = await execa("npm", args);
+		const results = JSON.parse(stdout) as Array<{
+			name: string;
+			version: string;
+			description: string;
+			downloads?: number;
+		}>;
+		return results.slice(0, 20).map((r) => ({
+			name: r.name,
+			version: r.version,
+			description: r.description || "",
+			downloads: r.downloads ?? 0,
+		}));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Get package info from npm
+ */
+export async function getPackageInfo(
+	name: string,
+	registry?: string,
+): Promise<{ version: string; description: string } | null> {
+	try {
+		const args = ["view", name, "version", "description", "--json"];
+		if (registry) args.push("--registry", registry);
+		const { stdout } = await execa("npm", args);
+		const info = JSON.parse(stdout);
+		return {
+			version: info.version ?? "0.0.0",
+			description: info.description ?? "",
+		};
+	} catch {
+		return null;
+	}
+}

package/packages/cli-plugin-sdk/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI Plugin SDK — Types (RFC-0067)
+ */
+
+import type { PluginManifest } from "../../framework-plugin-sdk/src/types.js";
+
+export interface PluginCLIConfig {
+	cwd?: string;
+	globalDir?: string;
+	registry?: string;
+	npmBin?: string;
+}
+
+export interface InstalledPlugin {
+	name: string;
+	version: string;
+	path: string;
+	manifest: PluginManifest | null;
+}
+
+export interface PluginSearchResult {
+	name: string;
+	version: string;
+	description: string;
+	downloads: number;
+}
+
+export interface InvokeResult {
+	success: boolean;
+	result?: unknown;
+	error?: string;
+}

package/packages/clipboard/dist/src/clipboard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Clipboard — System clipboard integration
+ */
+import type { ClipboardOptions } from "./types.js";
+/** Write text to system clipboard. */
+export declare function copy(text: string, _options?: ClipboardOptions): Promise<void>;
+/** Read text from system clipboard. */
+export declare function read(): Promise<string>;
+/** Copy the last assistant message from session service. */
+export declare function copyLastResponse(_sessionApi: unknown, _options?: ClipboardOptions): Promise<void>;
+//# sourceMappingURL=clipboard.d.ts.map