pi-harness-runtime 0.10.11 → 0.10.12

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

@@ -0,0 +1,222 @@
+/**
+ * Enhanced Provider Router (RFC-0054)
+ */
+import { DEFAULT_ROUTING_POLICY } from "./policy.js";
+import { applyStrategy, createDecision, calculateWeightedScore, } from "./strategies.js";
+/**
+ * Enhanced Provider Router with capability and cost awareness
+ */
+export class EnhancedProviderRouter {
+    policy;
+    eventHandlers = new Set();
+    // Default providers for fallback
+    defaultCandidates = [
+        {
+            providerId: "anthropic",
+            modelId: "claude-sonnet-4",
+            estimatedCost: 0.003, // $3/1M tokens average
+            estimatedLatency: "fast",
+            qualityScore: 90,
+        },
+        {
+            providerId: "openai",
+            modelId: "gpt-4o-mini",
+            estimatedCost: 0.0006,
+            estimatedLatency: "fast",
+            qualityScore: 82,
+        },
+        {
+            providerId: "minimax",
+            modelId: "MiniMax-Text-01",
+            estimatedCost: 0.0001,
+            estimatedLatency: "fast",
+            qualityScore: 75,
+        },
+        {
+            providerId: "google",
+            modelId: "gemini-1.5-flash",
+            estimatedCost: 0.00007,
+            estimatedLatency: "fast",
+            qualityScore: 78,
+        },
+    ];
+    constructor(policy) {
+        this.policy = policy ?? DEFAULT_ROUTING_POLICY;
+    }
+    /**
+     * Select the best provider for a task
+     */
+    async selectProvider(task, context, options) {
+        const candidates = this.buildCandidates(context, options);
+        // Filter candidates
+        const filtered = this.filterCandidates(candidates, context, options);
+        if (filtered.length === 0) {
+            this.emit({
+                type: "router.no_candidates",
+                taskId: task.id,
+                reason: "All candidates filtered out",
+            });
+            // Fallback to default
+            const fallback = this.policy.fallbackProviders[0];
+            const defaultCandidate = this.defaultCandidates.find((c) => c.providerId === fallback) ??
+                this.defaultCandidates[0];
+            return createDecision({
+                providerId: defaultCandidate.providerId,
+                modelId: defaultCandidate.modelId,
+                capabilities: [],
+                estimatedCost: defaultCandidate.estimatedCost,
+                estimatedLatency: defaultCandidate.estimatedLatency ?? "medium",
+                qualityScore: defaultCandidate.qualityScore,
+                remainingQuotaPct: context.quotaStates[defaultCandidate.providerId]?.remainingPct ?? 1,
+            }, `Fallback to ${defaultCandidate.providerId}`);
+        }
+        // Determine strategy
+        const strategy = this.determineStrategy(task, options);
+        // Apply strategy
+        const selected = applyStrategy(filtered, strategy, this.policy, options);
+        const decision = createDecision(selected, `Selected via ${strategy} strategy`);
+        this.emit({
+            type: "router.provider_selected",
+            taskId: task.id,
+            providerId: decision.providerId,
+            reason: decision.reason,
+        });
+        return decision;
+    }
+    /**
+     * Select multiple providers
+     */
+    async selectProviders(task, context, count) {
+        const candidates = this.buildCandidates(context);
+        const sorted = candidates.sort((a, b) => {
+            return (calculateWeightedScore(b, this.policy) -
+                calculateWeightedScore(a, this.policy));
+        });
+        const selected = sorted.slice(0, count);
+        return selected.map((c, i) => createDecision(c, `Ranked #${i + 1} for ${task.id}`));
+    }
+    /**
+     * Get current routing policy
+     */
+    getRoutingPolicy() {
+        return { ...this.policy };
+    }
+    /**
+     * Update routing policy
+     */
+    setRoutingPolicy(policy) {
+        const oldPolicy = this.policy;
+        this.policy = policy;
+        this.emit({
+            type: "router.policy_updated",
+            oldPolicy,
+            newPolicy: policy,
+        });
+    }
+    /**
+     * Subscribe to events
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Build candidate list from context
+     */
+    buildCandidates(context, options) {
+        const candidates = [];
+        // Add default candidates
+        for (const candidate of this.defaultCandidates) {
+            const providerState = context.providerStates[candidate.providerId] ?? "unknown";
+            const quotaState = context.quotaStates[candidate.providerId];
+            // Skip disabled providers
+            if (providerState === "disabled")
+                continue;
+            candidates.push({
+                providerId: candidate.providerId,
+                modelId: candidate.modelId,
+                capabilities: [], // Would be populated from capability registry
+                estimatedCost: candidate.estimatedCost,
+                estimatedLatency: candidate.estimatedLatency ?? "medium",
+                qualityScore: candidate.qualityScore,
+                remainingQuotaPct: quotaState?.remainingPct ?? 1,
+            });
+        }
+        return candidates;
+    }
+    /**
+     * Filter candidates based on options and context
+     */
+    filterCandidates(candidates, context, options) {
+        let filtered = [...candidates];
+        // Filter by cost
+        if (options?.maxCostPerTask) {
+            filtered = filtered.filter((c) => (c.estimatedCost ?? Infinity) <= options.maxCostPerTask);
+        }
+        // Filter by quota
+        filtered = filtered.filter((c) => {
+            const quota = context.quotaStates[c.providerId];
+            return !quota || !quota.exhausted;
+        });
+        // Filter by provider state
+        filtered = filtered.filter((c) => {
+            const state = context.providerStates[c.providerId] ?? "unknown";
+            return state !== "disabled" && state !== "exhausted";
+        });
+        // Prefer providers
+        if (options?.preferProviders?.length) {
+            filtered.sort((a, b) => {
+                const aPreferred = options.preferProviders.includes(a.providerId)
+                    ? 1
+                    : 0;
+                const bPreferred = options.preferProviders.includes(b.providerId)
+                    ? 1
+                    : 0;
+                return bPreferred - aPreferred;
+            });
+        }
+        // Avoid providers
+        if (options?.avoidProviders?.length) {
+            filtered = filtered.filter((c) => !options.avoidProviders.includes(c.providerId));
+        }
+        return filtered;
+    }
+    /**
+     * Determine routing strategy for a task
+     */
+    determineStrategy(task, options) {
+        // Check for explicit preferences
+        if (options?.preferCheapest)
+            return "cheapest";
+        if (options?.preferFastest)
+            return "fastest";
+        if (options?.preferHighestQuality)
+            return "best_quality";
+        // Check task type override
+        if (this.policy.taskTypeOverrides[task.type]) {
+            return this.policy.taskTypeOverrides[task.type];
+        }
+        // Fall back to default
+        return this.policy.defaultStrategy;
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+}
+/**
+ * Create a new provider router
+ */
+export function createProviderRouter(policy) {
+    return new EnhancedProviderRouter(policy);
+}
+//# sourceMappingURL=provider-router.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * Routing Strategies (RFC-0054)
+ */
+import type { ProviderCandidate, RoutingDecision, RoutingPolicy, RoutingStrategy } from "./types.js";
+/**
+ * Apply a routing strategy to select the best candidate
+ */
+export declare function applyStrategy(candidates: ProviderCandidate[], strategy: RoutingStrategy, policy: RoutingPolicy, options?: {
+    preferProviders?: string[];
+}): ProviderCandidate;
+/**
+ * Calculate weighted score for a candidate
+ */
+export declare function calculateWeightedScore(candidate: ProviderCandidate, policy: RoutingPolicy): number;
+/**
+ * Create a routing decision from a candidate
+ */
+export declare function createDecision(candidate: ProviderCandidate, reason: string): RoutingDecision;
+//# sourceMappingURL=strategies.d.ts.map

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

@@ -0,0 +1,110 @@
+/**
+ * Routing Strategies (RFC-0054)
+ */
+import { LATENCY_RANK } from "./types.js";
+/**
+ * Apply a routing strategy to select the best candidate
+ */
+export function applyStrategy(candidates, strategy, policy, options) {
+    switch (strategy) {
+        case "cheapest":
+            return selectCheapest(candidates);
+        case "fastest":
+            return selectFastest(candidates);
+        case "best_quality":
+            return selectBestQuality(candidates);
+        case "balanced":
+            return selectBalanced(candidates, policy);
+        case "quota_aware":
+            return selectQuotaAware(candidates);
+        default:
+            return selectBalanced(candidates, policy);
+    }
+}
+/**
+ * Select the cheapest candidate
+ */
+function selectCheapest(candidates) {
+    return candidates.reduce((cheapest, current) => (current.estimatedCost ?? Infinity) < (cheapest.estimatedCost ?? Infinity)
+        ? current
+        : cheapest);
+}
+/**
+ * Select the fastest candidate
+ */
+function selectFastest(candidates) {
+    return candidates.reduce((fastest, current) => LATENCY_RANK[current.estimatedLatency] <
+        LATENCY_RANK[fastest.estimatedLatency]
+        ? current
+        : fastest);
+}
+/**
+ * Select the highest quality candidate
+ */
+function selectBestQuality(candidates) {
+    return candidates.reduce((best, current) => (current.qualityScore ?? 0) > (best.qualityScore ?? 0) ? current : best);
+}
+/**
+ * Select based on weighted scoring
+ */
+function selectBalanced(candidates, policy) {
+    return candidates.reduce((best, current) => {
+        const scoreBest = calculateWeightedScore(best, policy);
+        const scoreCurrent = calculateWeightedScore(current, policy);
+        return scoreCurrent > scoreBest ? current : best;
+    });
+}
+/**
+ * Select based on quota availability
+ */
+function selectQuotaAware(candidates) {
+    return candidates.reduce((best, current) => {
+        const quotaBest = best.remainingQuotaPct ?? 0;
+        const quotaCurrent = current.remainingQuotaPct ?? 0;
+        const costBest = best.estimatedCost ?? Infinity;
+        const costCurrent = current.estimatedCost ?? Infinity;
+        // Prefer high quota / low cost
+        const ratioBest = quotaBest / (costBest || 1);
+        const ratioCurrent = quotaCurrent / (costCurrent || 1);
+        return ratioCurrent > ratioBest ? current : best;
+    });
+}
+/**
+ * Calculate weighted score for a candidate
+ */
+export function calculateWeightedScore(candidate, policy) {
+    // Cost score (inverse - lower is better)
+    const maxReasonableCost = 1; // $1 per task
+    const costScore = 100 -
+        Math.min(((candidate.estimatedCost ?? 0) * 100) / maxReasonableCost, 100);
+    // Quality score (already 0-100)
+    const qualityScore = candidate.qualityScore ?? 50;
+    // Latency score (inverse)
+    const latencyScore = 100 - LATENCY_RANK[candidate.estimatedLatency] * 33;
+    // Quota score (0-100)
+    const quotaScore = (candidate.remainingQuotaPct ?? 1) * 100;
+    // Normalize weights
+    const totalWeight = policy.costWeight +
+        policy.qualityWeight +
+        policy.latencyWeight +
+        policy.quotaWeight;
+    return ((costScore * policy.costWeight +
+        qualityScore * policy.qualityWeight +
+        latencyScore * policy.latencyWeight +
+        quotaScore * policy.quotaWeight) /
+        totalWeight);
+}
+/**
+ * Create a routing decision from a candidate
+ */
+export function createDecision(candidate, reason) {
+    return {
+        providerId: candidate.providerId,
+        modelId: candidate.modelId,
+        reason,
+        estimatedCost: candidate.estimatedCost,
+        estimatedLatency: candidate.estimatedLatency,
+        confidence: candidate.qualityScore ? candidate.qualityScore / 100 : 0.8,
+    };
+}
+//# sourceMappingURL=strategies.js.map

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

@@ -0,0 +1,91 @@
+/**
+ * Provider Router Types (RFC-0054)
+ */
+import type { ProviderState } from "../../types/src/runtime-types.ts";
+import type { Capability } from "../../capability-registry/src/types.ts";
+export type Latency = "fast" | "medium" | "slow";
+export type RoutingStrategy = "cheapest" | "fastest" | "best_quality" | "balanced" | "quota_aware";
+export interface RoutingPolicy {
+    defaultStrategy: RoutingStrategy;
+    costWeight: number;
+    qualityWeight: number;
+    latencyWeight: number;
+    quotaWeight: number;
+    fallbackProviders: string[];
+    taskTypeOverrides: Record<string, RoutingStrategy>;
+    providerPreferences: Record<string, number>;
+}
+export interface QuotaState {
+    exhausted: boolean;
+    remainingPct: number;
+}
+export interface RoutingContext {
+    task: {
+        id: string;
+        title: string;
+        description: string;
+        type: string;
+    };
+    requirement?: {
+        id: string;
+        description: string;
+    };
+    providerStates: Record<string, ProviderState>;
+    quotaStates: Record<string, QuotaState>;
+    costBudget?: {
+        remaining: number;
+    };
+}
+export interface RoutingOptions {
+    preferCheapest?: boolean;
+    preferFastest?: boolean;
+    preferHighestQuality?: boolean;
+    maxCostPerTask?: number;
+    requiredCapabilities?: Capability[];
+    preferProviders?: string[];
+    avoidProviders?: string[];
+}
+export interface ProviderCandidate {
+    providerId: string;
+    modelId: string;
+    capabilities: Capability[];
+    estimatedCost?: number;
+    estimatedLatency: Latency;
+    qualityScore?: number;
+    remainingQuotaPct: number;
+}
+export interface RoutingDecision {
+    providerId: string;
+    modelId: string;
+    reason: string;
+    estimatedCost?: number;
+    estimatedLatency?: Latency;
+    confidence: number;
+}
+export interface ProviderRouter {
+    selectProvider(task: RoutingContext["task"], context: RoutingContext, options?: RoutingOptions): Promise<RoutingDecision>;
+    selectProviders(task: RoutingContext["task"], context: RoutingContext, count: number): Promise<RoutingDecision[]>;
+    getRoutingPolicy(): RoutingPolicy;
+    setRoutingPolicy(policy: RoutingPolicy): void;
+}
+export type ProviderRouterEvent = {
+    type: "router.provider_selected";
+    taskId: string;
+    providerId: string;
+    reason: string;
+} | {
+    type: "router.no_candidates";
+    taskId: string;
+    reason: string;
+} | {
+    type: "router.policy_updated";
+    oldPolicy: RoutingPolicy;
+    newPolicy: RoutingPolicy;
+} | {
+    type: "router.fallback_triggered";
+    taskId: string;
+    originalProvider: string;
+    fallbackProvider: string;
+};
+export declare const LATENCY_RANK: Record<Latency, number>;
+//# sourceMappingURL=types.d.ts.map

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

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

package/packages/provider-router/dist/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/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/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/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/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