pi-harness-runtime 0.10.43 → 1.1.1

package/packages/prompt-versioning/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pi/prompt-versioning",
+  "version": "0.10.30",
+  "type": "module",
+  "description": "Version control for prompts with rollback support (RFC-0019)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "bun-types": "^1.0.0"
+  }
+}

package/packages/prompt-versioning/test/versioning.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Prompt Versioning Tests (RFC-0019)
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { PromptVersioning } from "../src/index.js";
+
+describe("PromptVersioning", () => {
+  let pv: PromptVersioning;
+
+  beforeEach(() => { pv = new PromptVersioning(); });
+
+  it("creates a prompt with initial version", () => {
+    const record = pv.createPrompt("login-prompt", "Hello {{name}}");
+    expect(record.name).toBe("login-prompt");
+    expect(record.versions).toHaveLength(1);
+    expect(record.activeVersion).toBe(record.versions[0].version);
+  });
+
+  it("addVersion creates a new version", () => {
+    const record = pv.createPrompt("greet", "Hi {{name}}");
+    const v2 = pv.addVersion(record.id, "Hello {{name}}");
+    expect(v2.version).not.toBe(record.versions[0].version);
+    expect(record.versions).toHaveLength(2);
+    expect(record.activeVersion).toBe(v2.version);
+  });
+
+  it("getVersion returns correct version", () => {
+    const record = pv.createPrompt("test", "v1");
+    const v2 = pv.addVersion(record.id, "v2");
+    const found = pv.getVersion(record.id, v2.version);
+    expect(found?.prompt).toBe("v2");
+  });
+
+  it("getVersion returns active when no version specified", () => {
+    const record = pv.createPrompt("test", "v1");
+    pv.addVersion(record.id, "v2");
+    const found = pv.getVersion(record.id);
+    expect(found?.prompt).toBe("v2");
+  });
+
+  it("listVersions returns all versions", () => {
+    const record = pv.createPrompt("test", "v1");
+    pv.addVersion(record.id, "v2");
+    pv.addVersion(record.id, "v3");
+    const versions = pv.listVersions(record.id);
+    expect(versions).toHaveLength(3);
+  });
+
+  it("diff shows added and removed lines", () => {
+    const record = pv.createPrompt("test", "line1\nline2\nline3");
+    pv.addVersion(record.id, "line1\nnewLine\nline3");
+    const d = pv.diff(record.id, record.versions[0].version, record.versions[1].version);
+    expect(d).not.toBeNull();
+    expect(d!.added).toBe(1);
+    expect(d!.removed).toBe(1);
+  });
+
+  it("rollback reverts to previous version", () => {
+    const record = pv.createPrompt("test", "v1");
+    const v2 = pv.addVersion(record.id, "v2");
+    const result = pv.rollback(record.id, record.versions[0].version);
+    expect(result?.rolledBackTo).toBe(record.versions[0].version);
+    expect(result?.previousVersion).toBe(v2.version);
+  });
+
+  it("rollback returns null for unknown version", () => {
+    const record = pv.createPrompt("test", "v1");
+    const result = pv.rollback(record.id, "nonexistent");
+    expect(result).toBeNull();
+  });
+
+  it("delete removes prompt when allowed", () => {
+    pv = new PromptVersioning({ allowDelete: true });
+    const record = pv.createPrompt("test", "content");
+    expect(pv.delete(record.id)).toBe(true);
+    expect(pv.getVersion(record.id)).toBeNull();
+  });
+
+  it("delete returns false when not allowed", () => {
+    const record = pv.createPrompt("test", "content");
+    expect(pv.delete(record.id)).toBe(false);
+  });
+
+  it("enforces maxVersions", () => {
+    pv = new PromptVersioning({ maxVersions: 3 });
+    const record = pv.createPrompt("test", "v1");
+    for (let i = 2; i <= 10; i++) pv.addVersion(record.id, `v${i}`);
+    expect(record.versions).toHaveLength(3);
+  });
+
+  it("getStats returns correct stats", () => {
+    const record = pv.createPrompt("test", "v1");
+    pv.addVersion(record.id, "v2");
+    const stats = pv.getStats(record.id);
+    expect(stats?.versionCount).toBe(2);
+  });
+
+  it("getStats returns null for unknown prompt", () => {
+    expect(pv.getStats("nonexistent")).toBeNull();
+  });
+
+  it("listPrompts returns all prompts", () => {
+    pv.createPrompt("a", "content a");
+    pv.createPrompt("b", "content b");
+    expect(pv.listPrompts()).toHaveLength(2);
+  });
+
+  it("throws for unknown promptId on addVersion", () => {
+    expect(() => pv.addVersion("nonexistent", "content")).toThrow();
+  });
+});

package/packages/provider-adapter-sdk/README.md

@@ -0,0 +1,221 @@
+# Provider Adapter SDK
+
+A comprehensive SDK for building, testing, and registering AI provider adapters.
+
+## Features
+
+- **Fluent Builder API**: Create adapters with a clean, chainable interface
+- **Lifecycle Management**: Initialize, activate, and teardown adapters
+- **Health Checks**: Automatic health monitoring for adapters
+- **Testing Utilities**: Built-in testing framework for adapters
+- **Registry**: Centralized management of multiple adapters
+- **Error Handling**: Comprehensive error parsing and quota detection
+
+## Installation
+
+```bash
+npm install @pi/provider-adapter-sdk
+```
+
+## Quick Start
+
+### Creating an Adapter
+
+```typescript
+import {
+  AdapterBuilder,
+  type ProviderRequest,
+  type ProviderResponse,
+} from "@pi/provider-adapter-sdk";
+
+const adapter = new AdapterBuilder("My Provider")
+  .id("my-provider")
+  .name("My Custom AI Provider")
+  .models("myai/model-x", "myai/model-y")
+  .capabilities("code", "review")
+  .rateLimits({
+    requestsPerMinute: 60,
+    tokensPerMinute: 100000,
+  })
+  .invoke(async (request: ProviderRequest): Promise<ProviderResponse> => {
+    // Your API call here
+    const response = await fetch("https://api.example.com/v1/completions", {
+      method: "POST",
+      body: JSON.stringify({
+        model: request.model,
+        messages: request.messages,
+      }),
+    });
+    return response.json();
+  })
+  .parseError((error) => ({
+    quotaExceeded: error.code === "QUOTA_EXCEEDED",
+    rateLimited: error.status === 429,
+    timeout: error.status === 408,
+    serverError: error.status >= 500,
+    clientError: error.status >= 400 && error.status < 500,
+  }))
+  .build();
+```
+
+### Using the Registry
+
+```typescript
+import { AdapterRegistry } from "@pi/provider-adapter-sdk";
+
+const registry = new AdapterRegistry();
+
+// Register adapter
+await registry.register(adapter, {
+  async onInit() {
+    console.log("Adapter initialized");
+  },
+});
+
+// Invoke adapter
+const result = await registry.invoke("my-provider", {
+  model: "myai/model-x",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+// List adapters
+const adapters = registry.listAdapters();
+console.log(`Registered ${adapters.length} adapters`);
+```
+
+### Testing Adapters
+
+```typescript
+import { AdapterTester } from "@pi/provider-adapter-sdk";
+
+const tester = new AdapterTester(adapter, {
+  mockResponses: true,
+  testInvocation: true,
+  testQuotaDetection: true,
+  testErrorParsing: true,
+  testHealthCheck: true,
+});
+
+const report = await tester.runAllTests();
+
+console.log(`Tests: ${report.summary.passed}/${report.summary.total} passed`);
+```
+
+## API Reference
+
+### AdapterBuilder
+
+Fluent API for creating provider adapters.
+
+```typescript
+new AdapterBuilder(name?: string)
+  .id(id: string)              // Required: unique adapter ID
+  .name(name: string)           // Required: display name
+  .models(...models: string[])  // Required: supported models
+  .defaultModel(model: string)  // Default model
+  .capabilities(...caps)        // Capabilities (code, review, etc.)
+  .rateLimits(limits)           // Rate limit configuration
+  .maxTokens(model, tokens)     // Max tokens per model
+  .invoke(fn)                   // Required: invocation function
+  .parseError(fn)               // Error parser function
+  .healthCheck(fn)              // Health check function
+  .build()                      // Build the adapter
+```
+
+### AdapterRegistry
+
+Central registry for managing adapters.
+
+```typescript
+const registry = new AdapterRegistry({
+  autoHealthCheck: true,
+  healthCheckInterval: 30000,
+});
+
+// Methods
+await registry.register(adapter, lifecycle?);
+await registry.unregister(id);
+registry.getAdapter(id);
+registry.listAdapters();
+registry.listByCapability(capability);
+await registry.invoke(id, request);
+await registry.healthCheck(id);
+await registry.healthCheckAll();
+registry.getStats();
+```
+
+### AdapterTester
+
+Testing utilities for adapters.
+
+```typescript
+const tester = new AdapterTester(adapter, config);
+
+await tester.runAllTests();
+await tester.testBasicInvocation(request);
+await tester.testQuotaDetection();
+await tester.testErrorParsing();
+await tester.testHealthCheck();
+tester.generateMockResponses();
+```
+
+## Capabilities
+
+Supported provider capabilities:
+
+- `code` - Code generation
+- `review` - Code review
+- `plan` - Planning
+- `test` - Test generation
+- `e2e` - End-to-end testing
+- `refactor` - Code refactoring
+- `analysis` - Code analysis
+- `debug` - Debugging assistance
+
+## Error Handling
+
+The SDK provides comprehensive error parsing:
+
+```typescript
+const analysis = adapter.parseError(error);
+// analysis.quotaExceeded - Quota exceeded
+// analysis.rateLimited - Rate limited
+// analysis.timeout - Request timed out
+// analysis.serverError - Server error
+// analysis.clientError - Client error
+```
+
+## Migration Guide
+
+### From Old Adapter Pattern
+
+If you're migrating from the old adapter pattern:
+
+```typescript
+// Old pattern
+class MyAdapter extends BaseProviderAdapter {
+  readonly id = "my-provider";
+  async invoke(request) { ... }
+}
+
+// New pattern (recommended)
+const adapter = new AdapterBuilder("My Provider")
+  .id("my-provider")
+  .models("my-model")
+  .invoke(async (request) => { ... })
+  .build();
+```
+
+## Examples
+
+See `examples/custom-adapter.ts` for complete examples:
+
+- Basic adapter creation
+- Registry usage
+- Adapter testing
+- Error handling
+- Migration from existing adapters
+
+## License
+
+MIT

package/packages/provider-adapter-sdk/examples/custom-adapter.ts

@@ -0,0 +1,353 @@
+/**
+ * Provider Adapter SDK - Examples
+ *
+ * This file demonstrates how to use the Provider Adapter SDK
+ * to create, test, and register custom AI provider adapters.
+ */
+
+import {
+	AdapterBuilder,
+	AdapterRegistry,
+	AdapterTester,
+	type ProviderRequest,
+	type ProviderResponse,
+} from "../src/index.js";
+
+// ─── Example 1: Creating a Simple Custom Adapter ─────────────────────────────
+
+/**
+ * Example of creating a custom provider adapter
+ */
+async function createCustomAdapter() {
+	// Create an adapter using the fluent builder API
+	const myAdapter = new AdapterBuilder("My Custom AI")
+		.id("my-custom-ai")
+		.name("My Custom AI Provider")
+		.models("myai/model-x", "myai/model-y", "myai/model-z")
+		.capabilities("code", "review", "analysis")
+		.rateLimits({
+			requestsPerMinute: 60,
+			tokensPerMinute: 100000,
+		})
+		.defaultModel("myai/model-x")
+		.maxTokens("myai/model-x", 32768)
+		.maxTokens("myai/model-y", 65536)
+		.invoke(async (request: ProviderRequest): Promise<ProviderResponse> => {
+			// In production, this would call your actual API
+			console.log(`Calling API with model: ${request.model}`);
+
+			// Simulate API call
+			const response = await fetch(
+				"https://api.myai.example.com/v1/completions",
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						// "Authorization": `Bearer ${process.env.MYAI_API_KEY}`
+					},
+					body: JSON.stringify({
+						model: request.model,
+						messages: request.messages,
+						temperature: request.temperature,
+						max_tokens: request.maxTokens,
+					}),
+				},
+			);
+
+			if (!response.ok) {
+				const error = await response.text();
+				throw new Error(`API Error: ${response.status} - ${error}`);
+			}
+
+			const data = await response.json();
+			return {
+				content: data.choices[0]?.message?.content || "",
+				model: request.model,
+				finishReason: data.choices[0]?.finish_reason || "stop",
+				usage: {
+					input: data.usage?.prompt_tokens || 0,
+					output: data.usage?.completion_tokens || 0,
+					cost: data.usage?.total_tokens
+						? data.usage.total_tokens * 0.00001
+						: 0,
+				},
+			};
+		})
+		.parseError((error: unknown) => {
+			const e = error as Record<string, unknown>;
+			const msg = String(e.message ?? "");
+			const status = Number(e.status ?? e.statusCode ?? 0);
+
+			return {
+				quotaExceeded: status === 429 || msg.includes("quota"),
+				rateLimited: status === 429,
+				timeout: status === 408 || msg.includes("timeout"),
+				serverError: status >= 500 && status < 600,
+				clientError: status >= 400 && status < 500,
+				message: msg,
+			};
+		})
+		.healthCheck(async () => {
+			try {
+				const start = Date.now();
+				const response = await fetch("https://api.myai.example.com/health", {
+					method: "GET",
+					signal: AbortSignal.timeout(5000),
+				});
+				return {
+					healthy: response.ok,
+					latencyMs: Date.now() - start,
+					message: response.ok ? "OK" : "Service unavailable",
+					timestamp: new Date().toISOString(),
+				};
+			} catch {
+				return {
+					healthy: false,
+					message: "Health check failed",
+					timestamp: new Date().toISOString(),
+				};
+			}
+		})
+		.build();
+
+	return myAdapter;
+}
+
+// ─── Example 2: Using the Registry ───────────────────────────────────────────
+
+/**
+ * Example of using the adapter registry
+ */
+async function useRegistry() {
+	// Create registry
+	const registry = new AdapterRegistry({
+		autoHealthCheck: true,
+		healthCheckInterval: 30000,
+		healthCheckTimeout: 5000,
+	});
+
+	// Create an adapter
+	const adapter = await createCustomAdapter();
+
+	// Register with lifecycle hooks
+	await registry.register(adapter, {
+		async onInit() {
+			console.log(`Initializing adapter: ${adapter.id}`);
+			// Setup connections, load config, etc.
+		},
+		async onTeardown() {
+			console.log(`Tearing down adapter: ${adapter.id}`);
+			// Cleanup resources, close connections, etc.
+		},
+	});
+
+	// List all adapters
+	const allAdapters = registry.listAdapters();
+	console.log(`Registered adapters: ${allAdapters.length}`);
+
+	// List by capability
+	const codeAdapters = registry.listByCapability("code");
+	console.log(`Code-capable adapters: ${codeAdapters.length}`);
+
+	// Invoke adapter
+	const result = await registry.invoke(adapter.id, {
+		model: "myai/model-x",
+		messages: [
+			{ role: "system", content: "You are a helpful assistant." },
+			{ role: "user", content: "Hello!" },
+		],
+		temperature: 0.7,
+		maxTokens: 500,
+	});
+
+	console.log(`Response: ${result.response.content}`);
+
+	// Health check
+	const health = await registry.healthCheck(adapter.id);
+	console.log(`Health: ${health.healthy ? "OK" : "FAIL"}`);
+
+	// Get stats
+	const stats = registry.getStats();
+	console.log(`Total adapters: ${stats.total}`);
+	console.log(`Ready adapters: ${stats.byState.ready}`);
+
+	// Cleanup
+	await registry.unregister(adapter.id);
+}
+
+// ─── Example 3: Testing Adapters ────────────────────────────────────────────
+
+/**
+ * Example of testing an adapter
+ */
+async function testAdapter() {
+	// Create adapter
+	const adapter = await createCustomAdapter();
+
+	// Create tester
+	const tester = new AdapterTester(adapter, {
+		testInvocation: true,
+		testQuotaDetection: true,
+		testErrorParsing: true,
+		testHealthCheck: true,
+		testRateLimiting: false,
+		mockResponses: true, // Use mock mode for testing
+		timeout: 10000,
+	});
+
+	// Add custom mock responses
+	tester.addMockResponse({
+		request: {
+			model: "myai/model-x",
+			messages: [{ role: "user", content: "Test" }],
+		},
+		response: {
+			content: "This is a mock response",
+			model: "myai/model-x",
+			finishReason: "stop",
+			usage: {
+				input: 10,
+				output: 20,
+				cost: 0.001,
+			},
+		},
+	});
+
+	// Generate default mock responses
+	tester.generateMockResponses();
+
+	// Run all tests
+	const report = await tester.runAllTests();
+
+	console.log("Test Report:");
+	console.log(`  Adapter: ${report.adapterId}`);
+	console.log(`  Overall: ${report.overall}`);
+	console.log(
+		`  Results: ${report.summary.passed}/${report.summary.total} passed`,
+	);
+	console.log(`  Duration: ${report.summary.duration}ms`);
+
+	for (const result of report.results) {
+		const status = result.passed ? "✓" : "✗";
+		console.log(
+			`    ${status} ${result.name}: ${result.message || result.error}`,
+		);
+	}
+
+	// Run individual tests
+	const invocationResult = await tester.testBasicInvocation({
+		model: "myai/model-x",
+		messages: [{ role: "user", content: "Hello" }],
+	});
+	console.log(`Invocation test: ${invocationResult.passed ? "PASS" : "FAIL"}`);
+
+	const errorResult = await tester.testErrorParsing();
+	console.log(`Error parsing test: ${errorResult.passed ? "PASS" : "FAIL"}`);
+
+	return report;
+}
+
+// ─── Example 4: Error Handling ────────────────────────────────────────────────
+
+/**
+ * Example of error handling
+ */
+async function errorHandling() {
+	const adapter = await createCustomAdapter();
+
+	try {
+		// Try to invoke with unsupported model
+		const result = await adapter.invoke({
+			model: "unsupported-model",
+			messages: [{ role: "user", content: "Test" }],
+		});
+
+		if (result.response.error) {
+			console.log(`API Error: ${result.response.error}`);
+		}
+
+		if (result.retryable) {
+			console.log("Request is retryable");
+		}
+	} catch (error) {
+		const analysis = adapter.parseError(error);
+		console.log("Error Analysis:");
+		console.log(`  Quota Exceeded: ${analysis.quotaExceeded}`);
+		console.log(`  Rate Limited: ${analysis.rateLimited}`);
+		console.log(`  Timeout: ${analysis.timeout}`);
+		console.log(`  Server Error: ${analysis.serverError}`);
+		console.log(`  Client Error: ${analysis.clientError}`);
+	}
+}
+
+// ─── Example 5: Migration from Existing Adapters ─────────────────────────────
+
+/**
+ * Example of migrating an existing adapter
+ */
+async function migrateExistingAdapter() {
+	// This shows how to migrate from the old adapter pattern
+	// to the new SDK pattern
+
+	const migratedAdapter = new AdapterBuilder("Legacy Provider")
+		.id("legacy-provider")
+		.name("Legacy Provider (Migrated)")
+		.models("legacy/model-v1", "legacy/model-v2")
+		.capabilities("code", "review")
+		.rateLimits({
+			requestsPerMinute: 30,
+			tokensPerDay: 1000000,
+		})
+		.invoke(async (request: ProviderRequest) => {
+			// Your existing invocation logic here
+			return {
+				content: "Legacy response",
+				model: request.model,
+				finishReason: "stop",
+			};
+		})
+		// Keep existing error parsing logic
+		.parseError((error: unknown) => {
+			// Your existing error parsing logic
+			return {
+				quotaExceeded: false,
+				rateLimited: false,
+				timeout: false,
+				serverError: false,
+				clientError: false,
+			};
+		})
+		.build();
+
+	console.log(`Migrated adapter: ${migratedAdapter.id}`);
+	return migratedAdapter;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+	console.log("Provider Adapter SDK Examples\n");
+
+	console.log("1. Creating a custom adapter...");
+	const adapter = await createCustomAdapter();
+	console.log(
+		`   Created: ${adapter.id} with ${adapter.getModels().length} models`,
+	);
+
+	console.log("\n2. Testing the adapter...");
+	await testAdapter();
+
+	console.log("\n3. Testing error handling...");
+	await errorHandling();
+
+	console.log("\n4. Using the registry...");
+	// await useRegistry(); // Uncomment to run full registry example
+
+	console.log("\n5. Migration example...");
+	await migrateExistingAdapter();
+
+	console.log("\n✓ All examples completed!");
+}
+
+// Run examples
+main().catch(console.error);