pi-harness-runtime 0.10.43 → 1.1.1

package/packages/capability-registry/test/registry.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Capability Registry Tests (RFC-0051)
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+	createCapabilityRegistry,
+	type InMemoryCapabilityRegistry,
+	DEFAULT_CAPABILITIES,
+	queryCapabilities,
+	findBestModel,
+	filterByLatency,
+	LATENCY_RANK,
+} from "../src/index.js";
+import type { CapabilityProfile, Capability } from "../src/types.js";
+
+describe("CapabilityRegistry", () => {
+	let registry: InMemoryCapabilityRegistry;
+
+	beforeEach(() => {
+		registry = createCapabilityRegistry(true);
+	});
+
+	describe("initialization", () => {
+		it("should load default capabilities", () => {
+			const providers = registry.listProviders();
+			expect(providers.length).toBeGreaterThan(0);
+		});
+
+		it("should have OpenAI providers", () => {
+			const providers = registry.listProviders();
+			expect(providers).toContain("openai");
+		});
+
+		it("should have Anthropic providers", () => {
+			const providers = registry.listProviders();
+			expect(providers).toContain("anthropic");
+		});
+	});
+
+	describe("register and unregister", () => {
+		it("should register new capabilities", () => {
+			const newCaps: CapabilityProfile[] = [
+				{
+					capability: "code_generation",
+					score: 90,
+					latency: "fast",
+					contextWindow: 100000,
+					maxOutputTokens: 4096,
+				},
+			];
+
+			registry.register("test-provider", "test-model", newCaps);
+
+			const caps = registry.getCapabilities("test-provider", "test-model");
+			expect(caps).toHaveLength(1);
+			expect(caps[0].capability).toBe("code_generation");
+			expect(caps[0].score).toBe(90);
+		});
+
+		it("should unregister capabilities", () => {
+			registry.unregister("openai", "gpt-4o");
+
+			const caps = registry.getCapabilities("openai", "gpt-4o");
+			expect(caps).toHaveLength(0);
+		});
+
+		it("should track events", () => {
+			const events: any[] = [];
+			registry.onEvent((e) => events.push(e));
+
+			const caps: CapabilityProfile[] = [
+				{
+					capability: "planning",
+					score: 85,
+					latency: "fast",
+					contextWindow: 50000,
+					maxOutputTokens: 2048,
+				},
+			];
+
+			registry.register("event-test", "model-v1", caps);
+
+			expect(events).toContainEqual({
+				type: "capability.registered",
+				providerId: "event-test",
+				modelId: "model-v1",
+				count: 1,
+			});
+		});
+	});
+
+	describe("query", () => {
+		it("should query by capability", () => {
+			const results = registry.query("code_generation");
+			expect(results.length).toBeGreaterThan(0);
+		});
+
+		it("should filter by minimum score", () => {
+			const results = registry.query("code_generation", { minScore: 95 });
+			expect(results.every((r) => r.profile.score >= 95)).toBe(true);
+		});
+
+		it("should filter by latency", () => {
+			const results = registry.query("code_generation", { maxLatency: "fast" });
+			expect(
+				results.every(
+					(r) => LATENCY_RANK[r.profile.latency] <= LATENCY_RANK["fast"],
+				),
+			).toBe(true);
+		});
+
+		it("should filter by context window", () => {
+			const results = registry.query("code_generation", {
+				requiresContextWindow: 200000,
+			});
+			expect(results.every((r) => r.profile.contextWindow >= 200000)).toBe(
+				true,
+			);
+		});
+
+		it("should sort by score descending", () => {
+			const results = registry.query("code_generation");
+			for (let i = 1; i < results.length; i++) {
+				expect(results[i - 1].profile.score).toBeGreaterThanOrEqual(
+					results[i].profile.score,
+				);
+			}
+		});
+
+		it("should emit query event", () => {
+			const events: any[] = [];
+			registry.onEvent((e) => events.push(e));
+
+			registry.query("code_generation");
+
+			expect(events).toContainEqual(
+				expect.objectContaining({
+					type: "capability.queried",
+					capability: "code_generation",
+				}),
+			);
+		});
+	});
+
+	describe("listProviders and listModels", () => {
+		it("should list providers", () => {
+			const providers = registry.listProviders();
+			expect(Array.isArray(providers)).toBe(true);
+			expect(providers.length).toBeGreaterThan(0);
+		});
+
+		it("should list models for a provider", () => {
+			const models = registry.listModels("openai");
+			expect(models).toContain("gpt-4o");
+		});
+
+		it("should return empty array for unknown provider", () => {
+			const models = registry.listModels("unknown-provider");
+			expect(models).toHaveLength(0);
+		});
+	});
+
+	describe("findBestModel", () => {
+		it("should find the highest scoring model", () => {
+			const candidates = registry.query("code_generation");
+			const best = findBestModel(candidates);
+
+			expect(best).toBeDefined();
+			const maxScore = Math.max(...candidates.map((c) => c.profile.score));
+			expect(best!.profile.score).toBe(maxScore);
+		});
+
+		it("should return undefined for empty array", () => {
+			const result = findBestModel([]);
+			expect(result).toBeUndefined();
+		});
+	});
+
+	describe("filterByLatency", () => {
+		it("should filter to fast latency", () => {
+			const candidates = registry.query("code_generation");
+			const fast = filterByLatency(candidates, "fast");
+
+			expect(fast.every((c) => c.profile.latency === "fast")).toBe(true);
+		});
+
+		it("should sort by quality when preference is quality", () => {
+			const candidates = registry.query("code_generation");
+			const sorted = filterByLatency(candidates, "quality");
+
+			expect(sorted[0].profile.score).toBeGreaterThanOrEqual(
+				sorted[1].profile.score,
+			);
+		});
+	});
+});
+
+describe("LATENCY_RANK", () => {
+	it("should have correct ordering", () => {
+		expect(LATENCY_RANK["fast"]).toBeLessThan(LATENCY_RANK["medium"]);
+		expect(LATENCY_RANK["medium"]).toBeLessThan(LATENCY_RANK["slow"]);
+	});
+});

package/packages/checkpoint/README.md

@@ -0,0 +1,206 @@
+# @pi/checkpoint
+
+Enhanced checkpoint system with incremental snapshots, diff-based storage, compression, and intelligent recovery strategies.
+
+## Features
+
+- **Incremental Checkpoints** - Only store changes, reducing storage by 60%+
+- **Compression** - Optional gzip compression for large checkpoints
+- **Checksum Verification** - Detect corruption with SHA-256 checksums
+- **Multiple Recovery Strategies** - Latest, fullest, specific version, or by timestamp
+- **Auto-Pruning** - Automatically clean up old checkpoints
+- **State Diffing** - Efficient incremental updates
+
+## Installation
+
+```bash
+npm install @pi/checkpoint
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { createCheckpointEngine } from "@pi/checkpoint";
+
+const engine = createCheckpointEngine({
+  rootDir: "./checkpoints",
+  compression: true,
+  incremental: true,
+  maxCheckpoints: 10,
+});
+
+// Save a checkpoint
+const state = {
+  version: 1,
+  jobId: "job-123",
+  status: "running",
+  requirement: "Build a web app",
+  tasks: [],
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+};
+
+await engine.save("job-123", state);
+
+// Load the latest checkpoint
+const recovered = await engine.load("job-123");
+console.log(recovered?.status); // "running"
+```
+
+### Recovery Strategies
+
+```typescript
+import { createCheckpointEngine, RecoveryStrategy } from "@pi/checkpoint";
+
+// Recover using latest checkpoint
+const result1 = await engine.recover("job-123", "latest");
+
+// Recover using checkpoint with most completed tasks
+const result2 = await engine.recover("job-123", "fullest");
+
+// Recover specific version
+const result3 = await engine.recover("job-123", "specific:5");
+
+// Recover closest to a timestamp
+const result4 = await engine.recover("job-123", "timestamp:2024-01-15T10:00:00Z");
+
+if (result.success) {
+  console.log(`Recovered state at version ${result.recoveredVersion}`);
+  console.log(`Recovery took ${result.recoveryTimeMs}ms`);
+}
+```
+
+### Incremental Checkpoints
+
+```typescript
+const engine = createCheckpointEngine({
+  rootDir: "./checkpoints",
+  incremental: true, // Enable incremental snapshots
+  compression: true,
+});
+
+// Save creates incremental or full checkpoint automatically
+await engine.save("job-123", updatedState);
+
+// Check metadata
+const metadata = await engine.getMetadata("job-123");
+console.log(metadata.map((m) => ({
+  version: m.version,
+  type: m.type, // "full" or "incremental"
+  sizeBytes: m.sizeBytes,
+  taskProgress: m.taskProgress,
+})));
+```
+
+### Verification & Pruning
+
+```typescript
+// Verify a checkpoint
+const verified = await engine.verify("job-123", 5);
+console.log(`Valid: ${verified.valid}, Checksum: ${verified.checksumMatch}`);
+
+// Prune old checkpoints (keep last 5)
+const pruneResult = await engine.prune("job-123", 5);
+console.log(`Deleted ${pruneResult.deletedCount} checkpoints`);
+console.log(`Freed ${pruneResult.freedBytes} bytes`);
+```
+
+## API Reference
+
+### CheckpointEngine
+
+```typescript
+const engine = createCheckpointEngine({
+  rootDir: string;           // Checkpoint storage directory
+  compression?: boolean;     // Enable gzip compression (default: true)
+  incremental?: boolean;     // Enable incremental snapshots (default: true)
+  maxCheckpoints?: number;  // Max checkpoints to keep (default: 10)
+  autoPrune?: boolean;       // Auto-prune on save (default: true)
+  checksumAlgorithm?: "md5" | "sha256"; // Checksum algorithm (default: "sha256")
+  parallelWrites?: boolean; // Parallel file I/O (default: true)
+});
+```
+
+### Methods
+
+```typescript
+// Save checkpoint (auto-selects full or incremental)
+await engine.save(jobId, state): Promise<CheckpointMetadata>;
+
+// Load latest checkpoint
+await engine.load(jobId): Promise<RuntimeState | null>;
+
+// Load specific version
+await engine.loadState(jobId, version): Promise<RuntimeState | null>;
+
+// Recover using strategy
+await engine.recover(jobId, strategy): Promise<RecoveryResult>;
+
+// Verify checkpoint integrity
+await engine.verify(jobId, version): Promise<VerificationResult>;
+
+// Prune old checkpoints
+await engine.prune(jobId, keepCount): Promise<PruneResult>;
+
+// Get metadata for all checkpoints
+await engine.getMetadata(jobId): Promise<CheckpointMetadata[]>;
+
+// Delete all checkpoints
+await engine.deleteAll(jobId): Promise<void>;
+```
+
+### Recovery Strategies
+
+```typescript
+type RecoveryStrategy =
+  | "latest"              // Most recent checkpoint
+  | "fullest"             // Checkpoint with most completed tasks
+  | "specific:number"     // Specific version number
+  | "timestamp:ISO"       // Checkpoint closest to timestamp
+  | "interactive";        // User selection (returns latest for now)
+```
+
+### Checkpoint Metadata
+
+```typescript
+interface CheckpointMetadata {
+  jobId: string;
+  version: number;
+  type: "full" | "incremental";
+  sizeBytes: number;
+  compressed: boolean;
+  checksum: string;
+  taskProgress: {
+    total: number;
+    completed: number;
+    failed: number;
+    running: number;
+  };
+  createdAt: string;
+  baseVersion?: number; // For incremental checkpoints
+}
+```
+
+## Storage Format
+
+Checkpoints are stored as JSON files:
+
+```
+checkpoints/
++-- jobs/
+    +-- job-123/
+        +-- index.json              # Checkpoint index
+        +-- checkpoint-1.json      # Full checkpoint
+        +-- checkpoint-2.delta.json # Incremental checkpoint
+        +-- checkpoint-3.json      # Full checkpoint
+```
+
+## Performance
+
+| Metric | Full Checkpoint | Incremental |
+| -------- | ---------------- | ------------- |
+| Storage | Baseline | 60-80% reduction |
+| Write Speed | Baseline | 30-50% faster |
+| Read Speed | Baseline |

package/packages/checkpoint/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pi/checkpoint",
+  "version": "0.10.30",
+  "description": "Enhanced checkpoint system with incremental snapshots, diff-based storage, and recovery strategies",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "checkpoint",
+    "snapshot",
+    "recovery",
+    "state"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^7.0.2"
+  }
+}

package/packages/checkpoint/test/engine.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Checkpoint Engine - Tests
+ */
+
+import { describe, it, expect, beforeEach, afterAll } from "bun:test";
+import { createCheckpointEngine, SDK_VERSION } from "../src/index.js";
+import type { RuntimeState } from "../src/types.js";
+
+describe("CheckpointEngine", () => {
+	describe("SDK_VERSION", () => {
+		it("should export SDK_VERSION", () => {
+			expect(SDK_VERSION).toBeDefined();
+			expect(typeof SDK_VERSION).toBe("string");
+		});
+	});
+
+	describe("createCheckpointEngine", () => {
+		it("should create a checkpoint engine instance", () => {
+			const engine = createCheckpointEngine({
+				rootDir: "/tmp/test-checkpoints",
+			});
+			expect(engine).toBeDefined();
+		});
+
+		it("should create with default config", () => {
+			const engine = createCheckpointEngine();
+			expect(engine).toBeDefined();
+		});
+	});
+
+	describe("save and load", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-test",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		const testState: RuntimeState = {
+			version: 1,
+			jobId: "test-job-1",
+			status: "running",
+			requirement: "Test requirement",
+			tasks: [
+				{
+					id: "task-1",
+					title: "Task 1",
+					description: "First task",
+					status: "done",
+				},
+				{
+					id: "task-2",
+					title: "Task 2",
+					description: "Second task",
+					status: "pending",
+				},
+			],
+			createdAt: new Date().toISOString(),
+			updatedAt: new Date().toISOString(),
+		};
+
+		it("should save a checkpoint", async () => {
+			const metadata = await engine.save("test-job-1", testState);
+
+			expect(metadata).toBeDefined();
+			expect(metadata.jobId).toBe("test-job-1");
+			expect(metadata.version).toBe(1);
+			expect(metadata.type).toBe("full");
+		});
+
+		it("should increment version on save", async () => {
+			const state2 = {
+				...testState,
+				version: 2,
+				updatedAt: new Date().toISOString(),
+			};
+			const metadata = await engine.save("test-job-1", state2);
+
+			expect(metadata.version).toBe(2);
+		});
+
+		it("should load the latest checkpoint", async () => {
+			const loaded = await engine.load("test-job-1");
+
+			expect(loaded).toBeDefined();
+			expect(loaded?.jobId).toBe("test-job-1");
+			expect(loaded?.status).toBe("running");
+		});
+
+		it("should return null for non-existent job", async () => {
+			const loaded = await engine.load("non-existent-job");
+
+			expect(loaded).toBeNull();
+		});
+
+		it("should get metadata for all checkpoints", async () => {
+			const metadata = await engine.getMetadata("test-job-1");
+
+			expect(metadata.length).toBeGreaterThan(0);
+			expect(metadata[0].jobId).toBe("test-job-1");
+		});
+
+		it("should delete all checkpoints", async () => {
+			await engine.deleteAll("test-job-1");
+
+			const loaded = await engine.load("test-job-1");
+			expect(loaded).toBeNull();
+		});
+	});
+
+	describe("incremental checkpoints", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-incremental",
+			compression: false,
+			incremental: true,
+			autoPrune: false,
+		});
+
+		it("should save incremental checkpoint", async () => {
+			const state1: RuntimeState = {
+				version: 1,
+				jobId: "incremental-test",
+				status: "running",
+				requirement: "Test",
+				tasks: [],
+				createdAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+			};
+
+			await engine.save("incremental-test", state1);
+
+			const state2: RuntimeState = {
+				...state1,
+				version: 2,
+				status: "completed",
+				updatedAt: new Date().toISOString(),
+			};
+
+			const metadata = await engine.save("incremental-test", state2);
+
+			// Should be incremental after first full checkpoint
+			expect(["full", "incremental"]).toContain(metadata.type);
+		});
+
+		afterAll(async () => {
+			await engine.deleteAll("incremental-test");
+		});
+	});
+
+	describe("recovery", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-recovery",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		beforeEach(async () => {
+			// Clear any stale checkpoints from previous runs so version starts at 1
+			await engine.deleteAll("recovery-test");
+
+			const state: RuntimeState = {
+				version: 1,
+				jobId: "recovery-test",
+				status: "running",
+				requirement: "Recovery test",
+				tasks: [],
+				createdAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+			};
+			await engine.save("recovery-test", state);
+		});
+
+		it("should recover with latest strategy", async () => {
+			const result = await engine.recover("recovery-test", "latest");
+
+			expect(result.success).toBe(true);
+			expect(result.recoveredVersion).toBe(1);
+			expect(result.recoveredState?.jobId).toBe("recovery-test");
+		});
+
+		it("should recover with specific version", async () => {
+			const result = await engine.recover("recovery-test", "specific:1");
+
+			expect(result.success).toBe(true);
+			expect(result.recoveredVersion).toBe(1);
+		});
+
+		it("should fail for non-existent job", async () => {
+			const result = await engine.recover("non-existent", "latest");
+
+			expect(result.success).toBe(false);
+		});
+	});
+
+	describe("pruning", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-prune",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		it("should prune old checkpoints", async () => {
+			// Create multiple checkpoints
+			for (let i = 1; i <= 5; i++) {
+				const state: RuntimeState = {
+					version: i,
+					jobId: "prune-test",
+					status: "running",
+					requirement: `Version ${i}`,
+					tasks: [],
+					createdAt: new Date().toISOString(),
+					updatedAt: new Date().toISOString(),
+				};
+				await engine.save("prune-test", state);
+			}
+
+			// Prune to keep only 2
+			const result = await engine.prune("prune-test", 2);
+
+			expect(result.deletedCount).toBeGreaterThan(0);
+			expect(result.remainingCount).toBe(2);
+		});
+
+		afterAll(async () => {
+			await engine.deleteAll("prune-test");
+		});
+	});
+
+	describe("verification", () => {
+		const engine = createCheckpointEngine({
+			rootDir: "/tmp/checkpoint-verify",
+			compression: false,
+			incremental: false,
+			autoPrune: false,
+		});
+
+		beforeEach(async () => {
+			const state: RuntimeState = {
+				version: 1,
+				jobId: "verify-test",
+				status: "running",
+				requirement: "Verify test",
+				tasks: [],
+				createdAt: new Date().toISOString(),
+				updatedAt: new Date().toISOString(),
+			};
+			await engine.save("verify-test", state);
+		});
+
+		it("should verify checkpoint", async () => {
+			const result = await engine.verify("verify-test", 1);
+
+			expect(result.valid).toBe(true);
+			expect(result.checksumMatch).toBe(true);
+		});
+
+		it("should fail verification for non-existent checkpoint", async () => {
+			const result = await engine.verify("verify-test", 999);
+
+			expect(result.valid).toBe(false);
+		});
+	});
+});