pi-harness-runtime 0.10.11 → 0.10.12

package/packages/provider-adapter-sdk/src/types.ts

@@ -0,0 +1,293 @@
+/**
+ * Provider Adapter SDK - Types
+ *
+ * Core types for building provider adapters.
+ */
+
+// --- SDK Version ------------------------------------------------------------
+
+/**
+ * SDK version for compatibility checks
+ */
+export const SDK_VERSION = "1.0.0";
+
+// --- Provider Types (from @pi/types) ----------------------------------------
+
+/**
+ * Provider capability
+ */
+export type ProviderCapability =
+	| "code"
+	| "review"
+	| "plan"
+	| "test"
+	| "e2e"
+	| "refactor"
+	| "analysis"
+	| "debug";
+
+/**
+ * Provider request
+ */
+export interface ProviderRequest {
+	model: string;
+	messages: ProviderMessage[];
+	temperature?: number;
+	maxTokens?: number;
+	stop?: string[];
+}
+
+/**
+ * Provider message
+ */
+export interface ProviderMessage {
+	role: "system" | "user" | "assistant";
+	content: string;
+}
+
+/**
+ * Provider response
+ */
+export interface ProviderResponse {
+	content: string;
+	usage?: {
+		input: number;
+		output: number;
+		cacheRead?: number;
+		cacheWrite?: number;
+		cost?: number;
+	};
+	model?: string;
+	finishReason?: "stop" | "length" | "content_filter" | "error";
+	error?: string;
+}
+
+// --- Rate Limit Config ------------------------------------------------------
+
+/**
+ * Rate limit configuration for providers
+ */
+export interface RateLimitConfig {
+	requestsPerMinute?: number;
+	tokensPerMinute?: number;
+	tokensPerDay?: number;
+	concurrentRequests?: number;
+}
+
+// --- SDK Types --------------------------------------------------------------
+
+/**
+ * Adapter version information
+ */
+export interface AdapterVersion {
+	sdk: string;
+	minRuntime?: string;
+	capabilities: ProviderCapability[];
+}
+
+/**
+ * Quota signal extracted from error responses
+ */
+export interface QuotaSignal {
+	exhausted: boolean;
+	resetsAt?: string;
+	retryAfterMs?: number;
+	usedPercentage?: number;
+	remainingTokens?: number;
+}
+
+/**
+ * Error analysis result from adapter
+ */
+export interface ErrorAnalysis {
+	quotaExceeded: boolean;
+	rateLimited: boolean;
+	timeout: boolean;
+	serverError: boolean;
+	clientError: boolean;
+	quotaSignal?: QuotaSignal;
+	message?: string;
+	code?: string;
+}
+
+/**
+ * Adapter invocation result with quota signals
+ */
+export interface AdapterResult {
+	response: ProviderResponse;
+	quotaSignal?: QuotaSignal;
+	retryable: boolean;
+	latencyMs?: number;
+}
+
+/**
+ * Configuration for creating an adapter via Builder
+ */
+export interface AdapterBuilderConfig {
+	id: string;
+	name: string;
+	models?: string[];
+	capabilities?: ProviderCapability[];
+	rateLimits?: RateLimitConfig;
+	defaultModel?: string;
+	maxTokens?: Record<string, number>;
+}
+
+/**
+ * Invoke function signature for custom adapters
+ */
+export type InvokeFunction = (
+	request: ProviderRequest,
+) => Promise<ProviderResponse>;
+
+/**
+ * Error parser function signature
+ */
+export type ErrorParserFunction = (error: unknown) => ErrorAnalysis;
+
+/**
+ * Health check function signature
+ */
+export type HealthCheckFunction = () => Promise<HealthCheckResult>;
+
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+	healthy: boolean;
+	latencyMs?: number;
+	message?: string;
+	timestamp: string;
+}
+
+/**
+ * Lifecycle hooks for adapter management
+ */
+export interface AdapterLifecycle {
+	onInit?: () => Promise<void>;
+	onHealthCheck?: HealthCheckFunction;
+	onTeardown?: () => Promise<void>;
+}
+
+/**
+ * Adapter metadata for registry listing
+ */
+export interface AdapterInfo {
+	id: string;
+	name: string;
+	version?: AdapterVersion;
+	capabilities: ProviderCapability[];
+	models: string[];
+	registeredAt: string;
+	state: AdapterState;
+	lastHealthCheck?: HealthCheckResult;
+}
+
+/**
+ * Adapter state in registry
+ */
+export type AdapterState =
+	| "registered"
+	| "initializing"
+	| "ready"
+	| "error"
+	| "unavailable";
+
+/**
+ * Test result from AdapterTester
+ */
+export interface TestResult {
+	name: string;
+	passed: boolean;
+	duration: number;
+	message?: string;
+	error?: string;
+	details?: Record<string, unknown>;
+}
+
+/**
+ * Full test report from AdapterTester
+ */
+export interface TestReport {
+	adapterId: string;
+	timestamp: string;
+	results: TestResult[];
+	summary: {
+		total: number;
+		passed: number;
+		failed: number;
+		duration: number;
+	};
+	overall: "passed" | "failed" | "partial";
+}
+
+/**
+ * Test configuration
+ */
+export interface TestConfig {
+	testInvocation?: boolean;
+	testQuotaDetection?: boolean;
+	testErrorParsing?: boolean;
+	testHealthCheck?: boolean;
+	testRateLimiting?: boolean;
+	mockResponses?: boolean;
+	timeout?: number;
+}
+
+/**
+ * Mock response for testing
+ */
+export interface MockResponse {
+	request: ProviderRequest;
+	response: ProviderResponse;
+	delayMs?: number;
+}
+
+/**
+ * Compatibility check result
+ */
+export interface CompatibilityResult {
+	compatible: boolean;
+	issues: string[];
+	warnings: string[];
+}
+
+/**
+ * Registry events
+ */
+export interface RegistryEvents {
+	onAdapterRegistered: (adapter: AdapterInfo) => void;
+	onAdapterUnregistered: (adapterId: string) => void;
+	onAdapterStateChanged: (adapterId: string, state: AdapterState) => void;
+	onHealthCheckFailed: (adapterId: string, result: HealthCheckResult) => void;
+}
+
+// --- Provider Adapter Types ------------------------------------------------
+
+/**
+ * Provider adapter interface
+ */
+export interface ProviderAdapter {
+	name: string;
+	provider?: string;
+	config?: Record<string, unknown>;
+	complete: (
+		prompt: string,
+		options?: Record<string, unknown>,
+	) => Promise<ProviderResponse>;
+	streaming?: (
+		prompt: string,
+		options?: Record<string, unknown>,
+	) => AsyncGenerator<StreamEvent>;
+	embed?: (input: string) => Promise<number[]>;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Stream event from streaming response
+ */
+export interface StreamEvent {
+	type: "content" | "done" | "error";
+	content?: string;
+	error?: string;
+}

package/packages/provider-router/dist/capability-registry/src/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Capability Registry Types (RFC-0051)
+ */
+export type Capability = "code_generation" | "code_review" | "planning" | "test_generation" | "e2e_testing" | "refactoring" | "analysis" | "debugging" | "documentation" | "vision" | "function_calling" | "json_mode" | "streaming";
+export type Latency = "fast" | "medium" | "slow";
+export interface CapabilityProfile {
+    capability: Capability;
+    score: number;
+    latency: Latency;
+    contextWindow: number;
+    maxOutputTokens: number;
+}
+export interface CapabilityQuery {
+    minScore?: number;
+    maxLatency?: Latency;
+    requiresContextWindow?: number;
+    requiresMaxOutput?: number;
+}
+export interface ModelWithCapability {
+    providerId: string;
+    modelId: string;
+    profile: CapabilityProfile;
+}
+export interface CapabilityRegistry {
+    register(providerId: string, modelId: string, capabilities: CapabilityProfile[]): void;
+    unregister(providerId: string, modelId: string): void;
+    getCapabilities(providerId: string, modelId: string): CapabilityProfile[];
+    query(capability: Capability, requirements?: CapabilityQuery): ModelWithCapability[];
+    listProviders(): string[];
+    listModels(providerId: string): string[];
+}
+export type CapabilityRegistryEvent = {
+    type: "capability.registered";
+    providerId: string;
+    modelId: string;
+    count: number;
+} | {
+    type: "capability.unregistered";
+    providerId: string;
+    modelId: string;
+} | {
+    type: "capability.queried";
+    capability: Capability;
+    results: number;
+};
+export declare const LATENCY_RANK: Record<Latency, number>;
+//# sourceMappingURL=types.d.ts.map

package/packages/provider-router/dist/capability-registry/src/types.js

@@ -0,0 +1,10 @@
+/**
+ * Capability Registry Types (RFC-0051)
+ */
+// ─── Latency Ranking ─────────────────────────────────────────────────
+export const LATENCY_RANK = {
+    fast: 1,
+    medium: 2,
+    slow: 3,
+};
+//# sourceMappingURL=types.js.map

package/packages/provider-router/dist/provider-router/src/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Provider Router Package (RFC-0054)
+ *
+ * Enhanced provider routing with capability, cost, and quota awareness.
+ *
+ * @example
+ * ```typescript
+ * import { createProviderRouter, DEFAULT_ROUTING_POLICY } from "@pi-harness/provider-router";
+ *
+ * const router = createProviderRouter();
+ *
+ * const decision = await router.selectProvider(task, context, {
+ *   preferCheapest: true,
+ *   requiredCapabilities: ["code_generation"],
+ * });
+ * ```
+ */
+export type { RoutingStrategy, RoutingPolicy, QuotaState, RoutingContext, RoutingOptions, ProviderCandidate, RoutingDecision, ProviderRouter, ProviderRouterEvent, Latency, } from "./types.js";
+export { LATENCY_RANK } from "./types.js";
+export { EnhancedProviderRouter, createProviderRouter, } from "./provider-router.js";
+export { DEFAULT_ROUTING_POLICY, createRoutingPolicy } from "./policy.js";
+export { applyStrategy, calculateWeightedScore, createDecision, } from "./strategies.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/provider-router/dist/provider-router/src/index.js

@@ -0,0 +1,25 @@
+/**
+ * Provider Router Package (RFC-0054)
+ *
+ * Enhanced provider routing with capability, cost, and quota awareness.
+ *
+ * @example
+ * ```typescript
+ * import { createProviderRouter, DEFAULT_ROUTING_POLICY } from "@pi-harness/provider-router";
+ *
+ * const router = createProviderRouter();
+ *
+ * const decision = await router.selectProvider(task, context, {
+ *   preferCheapest: true,
+ *   requiredCapabilities: ["code_generation"],
+ * });
+ * ```
+ */
+export { LATENCY_RANK } from "./types.js";
+// Router
+export { EnhancedProviderRouter, createProviderRouter, } from "./provider-router.js";
+// Policy
+export { DEFAULT_ROUTING_POLICY, createRoutingPolicy } from "./policy.js";
+// Strategies
+export { applyStrategy, calculateWeightedScore, createDecision, } from "./strategies.js";
+//# sourceMappingURL=index.js.map

package/packages/provider-router/dist/provider-router/src/policy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default Routing Policy (RFC-0054)
+ */
+import type { RoutingPolicy } from "./types.js";
+export declare const DEFAULT_ROUTING_POLICY: RoutingPolicy;
+/**
+ * Create a custom routing policy
+ */
+export declare function createRoutingPolicy(overrides: Partial<RoutingPolicy>): RoutingPolicy;
+//# sourceMappingURL=policy.d.ts.map

package/packages/provider-router/dist/provider-router/src/policy.js

@@ -0,0 +1,45 @@
+/**
+ * Default Routing Policy (RFC-0054)
+ */
+export const DEFAULT_ROUTING_POLICY = {
+    defaultStrategy: "balanced",
+    costWeight: 30,
+    qualityWeight: 40,
+    latencyWeight: 20,
+    quotaWeight: 10,
+    fallbackProviders: ["anthropic", "openai"],
+    taskTypeOverrides: {
+        planning: "best_quality",
+        code_generation: "balanced",
+        code_review: "best_quality",
+        test_generation: "fastest",
+        e2e_testing: "quota_aware",
+        analysis: "best_quality",
+        refactoring: "balanced",
+        debugging: "fastest",
+        documentation: "cheapest",
+    },
+    providerPreferences: {
+        minimax: 20, // prefer cheaper options
+        openai: 0,
+        anthropic: 10,
+    },
+};
+/**
+ * Create a custom routing policy
+ */
+export function createRoutingPolicy(overrides) {
+    return {
+        ...DEFAULT_ROUTING_POLICY,
+        ...overrides,
+        taskTypeOverrides: {
+            ...DEFAULT_ROUTING_POLICY.taskTypeOverrides,
+            ...overrides.taskTypeOverrides,
+        },
+        providerPreferences: {
+            ...DEFAULT_ROUTING_POLICY.providerPreferences,
+            ...overrides.providerPreferences,
+        },
+    };
+}
+//# sourceMappingURL=policy.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * Enhanced Provider Router (RFC-0054)
+ */
+import type { ProviderRouter, ProviderRouterEvent, RoutingContext, RoutingDecision, RoutingOptions, RoutingPolicy } from "./types.js";
+type EventHandler = (event: ProviderRouterEvent) => void;
+/**
+ * Enhanced Provider Router with capability and cost awareness
+ */
+export declare class EnhancedProviderRouter implements ProviderRouter {
+    private policy;
+    private eventHandlers;
+    private defaultCandidates;
+    constructor(policy?: RoutingPolicy);
+    /**
+     * Select the best provider for a task
+     */
+    selectProvider(task: RoutingContext["task"], context: RoutingContext, options?: RoutingOptions): Promise<RoutingDecision>;
+    /**
+     * Select multiple providers
+     */
+    selectProviders(task: RoutingContext["task"], context: RoutingContext, count: number): Promise<RoutingDecision[]>;
+    /**
+     * Get current routing policy
+     */
+    getRoutingPolicy(): RoutingPolicy;
+    /**
+     * Update routing policy
+     */
+    setRoutingPolicy(policy: RoutingPolicy): void;
+    /**
+     * Subscribe to events
+     */
+    onEvent(handler: EventHandler): () => void;
+    /**
+     * Build candidate list from context
+     */
+    private buildCandidates;
+    /**
+     * Filter candidates based on options and context
+     */
+    private filterCandidates;
+    /**
+     * Determine routing strategy for a task
+     */
+    private determineStrategy;
+    /**
+     * Emit an event
+     */
+    private emit;
+}
+/**
+ * Create a new provider router
+ */
+export declare function createProviderRouter(policy?: RoutingPolicy): EnhancedProviderRouter;
+export {};
+//# sourceMappingURL=provider-router.d.ts.map