pi-harness-runtime 0.9.4 → 0.9.6

package/packages/provider-selector/dist/selector.js

@@ -0,0 +1,93 @@
+/**
+ * Provider Selector — multi-criteria provider ranking and selection (RFC-0012)
+ */
+/** Normalize a provider metric across all providers (0=lowest, 1=highest). */
+function normalize(values) {
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    if (max === min)
+        return values.map(() => 0.5);
+    return values.map((v) => (v - min) / (max - min));
+}
+/** Cost score: cheaper = higher score. */
+function costScore(p, all) {
+    const costs = all.map((x) => x.inputCostPer1M + x.outputCostPer1M);
+    const norm = normalize(costs);
+    const idx = all.indexOf(p);
+    return 1 - norm[idx]; // invert: lower cost = higher score
+}
+/** Latency score: faster = higher score. */
+function latencyScore(p, all) {
+    const lats = all.map((x) => x.latencyMs);
+    const norm = normalize(lats);
+    const idx = all.indexOf(p);
+    return 1 - norm[idx]; // invert: lower latency = higher score
+}
+function qualityScoreFn(p) {
+    return p.qualityScore / 100;
+}
+function combinedScore(p, criteria, all) {
+    const c = costScore(p, all);
+    const l = latencyScore(p, all);
+    const q = qualityScoreFn(p);
+    switch (criteria) {
+        case "cost":
+            return c * 0.8 + q * 0.1 + l * 0.1;
+        case "latency":
+            return l * 0.7 + q * 0.2 + c * 0.1;
+        case "quality":
+            return q * 0.9 + l * 0.05 + c * 0.05;
+        case "balanced":
+            return c * 0.33 + l * 0.33 + q * 0.34;
+        default:
+            return q;
+    }
+}
+/** Select the best provider based on criteria. */
+export function selectProvider(providers, criteria = "balanced") {
+    const available = providers.filter((p) => p.available);
+    if (available.length === 0)
+        return null;
+    const scored = available.map((p) => ({
+        provider: p,
+        score: combinedScore(p, criteria, available),
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    const alternatives = scored.slice(1).map((s) => s.provider);
+    return {
+        provider: best.provider,
+        reason: `Selected ${best.provider.name} (score: ${(best.score * 100).toFixed(1)}%) based on ${criteria} priority`,
+        score: best.score,
+        alternatives,
+    };
+}
+/** Rank all providers by score. */
+export function rank(providers, criteria = "balanced") {
+    return providers
+        .filter((p) => p.available)
+        .map((p) => ({ p, score: combinedScore(p, criteria, providers) }))
+        .sort((a, b) => b.score - a.score)
+        .map((s) => s.p);
+}
+/** Compare two providers by cost. Returns negative if a is cheaper. */
+export function compareCost(a, b) {
+    const aCost = a.inputCostPer1M + a.outputCostPer1M;
+    const bCost = b.inputCostPer1M + b.outputCostPer1M;
+    return aCost - bCost;
+}
+/** Compare two providers by latency. Returns negative if a is faster. */
+export function compareLatency(a, b) {
+    return a.latencyMs - b.latencyMs;
+}
+/** Filter providers by capability. */
+export function filterByCapability(providers, capability) {
+    return providers.filter((p) => p.capabilities.includes(capability));
+}
+/** Filter providers by region. */
+export function filterByRegion(providers, region) {
+    if (region === "global")
+        return providers;
+    return providers.filter((p) => p.region === region || p.region === "global");
+}
+//# sourceMappingURL=selector.js.map

package/packages/provider-selector/dist/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,8EAA8E;AAC9E,SAAS,SAAS,CAAC,MAAgB;IAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAChC,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,0CAA0C;AAC1C,SAAS,SAAS,CAAC,CAAW,EAAE,GAAe;IAC9C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,oCAAoC;AAC3D,CAAC;AAED,4CAA4C;AAC5C,SAAS,YAAY,CAAC,CAAW,EAAE,GAAe;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,uCAAuC;AAC9D,CAAC;AAED,SAAS,cAAc,CAAC,CAAW;IAClC,OAAO,CAAC,CAAC,YAAY,GAAG,GAAG,CAAC;AAC7B,CAAC;AAED,SAAS,aAAa,CACrB,CAAW,EACX,QAA2B,EAC3B,GAAe;IAEf,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAC5B,QAAQ,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM;YACV,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QACpC,KAAK,SAAS;YACb,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QACpC,KAAK,SAAS;YACb,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC;QACtC,KAAK,UAAU;YACd,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC;QACvC;YACC,OAAO,CAAC,CAAC;IACX,CAAC;AACF,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,cAAc,CAC7B,SAAqB,EACrB,QAAQ,GAAsB,UAAU;IAExC,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAExC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACpC,QAAQ,EAAE,CAAC;QACX,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC;KAC5C,CAAC,CAAC,CAAC;IACJ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAE5D,OAAO;QACN,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,MAAM,EAAE,YAAY,IAAI,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,QAAQ,WAAW;QACjH,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY;KACZ,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,IAAI,CACnB,SAAqB,EACrB,QAAQ,GAAsB,UAAU;IAExC,OAAO,SAAS;SACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;SACjE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,CAAW,EAAE,CAAW;IACnD,MAAM,KAAK,GAAG,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,eAAe,CAAC;IACnD,MAAM,KAAK,GAAG,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,eAAe,CAAC;IACnD,OAAO,KAAK,GAAG,KAAK,CAAC;AACtB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,CAAW,EAAE,CAAW;IACtD,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;AAClC,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,kBAAkB,CACjC,SAAqB,EACrB,UAA4C;IAE5C,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,cAAc,CAC7B,SAAqB,EACrB,MAA0B;IAE1B,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;AAC9E,CAAC"}

package/packages/provider-selector/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Provider Selector Types (RFC-0012)
+ */
+export type ProviderCapability = "text" | "vision" | "function_calling" | "streaming";
+export type ProviderRegion = "us" | "eu" | "asia" | "global";
+export interface Provider {
+    id: string;
+    name: string;
+    baseURL: string;
+    capabilities: ProviderCapability[];
+    region: ProviderRegion;
+    inputCostPer1M: number;
+    outputCostPer1M: number;
+    latencyMs: number;
+    qualityScore: number;
+    maxContextTokens: number;
+    available: boolean;
+}
+export type SelectionCriteria = "cost" | "latency" | "quality" | "balanced";
+export interface SelectionResult {
+    provider: Provider;
+    reason: string;
+    score: number;
+    alternatives: Provider[];
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/provider-selector/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,kBAAkB,GAC3B,MAAM,GACN,QAAQ,GACR,kBAAkB,GAClB,WAAW,CAAC;AACf,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,QAAQ,EAAE,CAAC;CACzB"}

package/packages/provider-selector/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Provider Selector Types (RFC-0012)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/provider-selector/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/packages/provider-selector/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pi-harness/provider-selector",
+  "version": "0.9.6",
+  "description": "Multi-Provider Selector — route requests by cost, quality, and latency (RFC-0012)",
+  "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"
+  },
+  "devDependencies": {
+    "bun-types": "^1.0.0"
+  }
+}

package/packages/provider-selector/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider Selector — Main Entry (RFC-0012)
+ */
+
+export {
+	selectProvider,
+	rank,
+	compareCost,
+	compareLatency,
+	filterByCapability,
+	filterByRegion,
+} from "./selector.js";
+export type * from "./types.js";

package/packages/provider-selector/src/selector.ts

@@ -0,0 +1,120 @@
+/**
+ * Provider Selector — multi-criteria provider ranking and selection (RFC-0012)
+ */
+
+import type { Provider, SelectionCriteria, SelectionResult } from "./types.js";
+
+/** Normalize a provider metric across all providers (0=lowest, 1=highest). */
+function normalize(values: number[]): number[] {
+	const min = Math.min(...values);
+	const max = Math.max(...values);
+	if (max === min) return values.map(() => 0.5);
+	return values.map((v) => (v - min) / (max - min));
+}
+
+/** Cost score: cheaper = higher score. */
+function costScore(p: Provider, all: Provider[]): number {
+	const costs = all.map((x) => x.inputCostPer1M + x.outputCostPer1M);
+	const norm = normalize(costs);
+	const idx = all.indexOf(p);
+	return 1 - norm[idx]; // invert: lower cost = higher score
+}
+
+/** Latency score: faster = higher score. */
+function latencyScore(p: Provider, all: Provider[]): number {
+	const lats = all.map((x) => x.latencyMs);
+	const norm = normalize(lats);
+	const idx = all.indexOf(p);
+	return 1 - norm[idx]; // invert: lower latency = higher score
+}
+
+function qualityScoreFn(p: Provider): number {
+	return p.qualityScore / 100;
+}
+
+function combinedScore(
+	p: Provider,
+	criteria: SelectionCriteria,
+	all: Provider[],
+): number {
+	const c = costScore(p, all);
+	const l = latencyScore(p, all);
+	const q = qualityScoreFn(p);
+	switch (criteria) {
+		case "cost":
+			return c * 0.8 + q * 0.1 + l * 0.1;
+		case "latency":
+			return l * 0.7 + q * 0.2 + c * 0.1;
+		case "quality":
+			return q * 0.9 + l * 0.05 + c * 0.05;
+		case "balanced":
+			return c * 0.33 + l * 0.33 + q * 0.34;
+		default:
+			return q;
+	}
+}
+
+/** Select the best provider based on criteria. */
+export function selectProvider(
+	providers: Provider[],
+	criteria: SelectionCriteria = "balanced",
+): SelectionResult | null {
+	const available = providers.filter((p) => p.available);
+	if (available.length === 0) return null;
+
+	const scored = available.map((p) => ({
+		provider: p,
+		score: combinedScore(p, criteria, available),
+	}));
+	scored.sort((a, b) => b.score - a.score);
+	const best = scored[0];
+	const alternatives = scored.slice(1).map((s) => s.provider);
+
+	return {
+		provider: best.provider,
+		reason: `Selected ${best.provider.name} (score: ${(best.score * 100).toFixed(1)}%) based on ${criteria} priority`,
+		score: best.score,
+		alternatives,
+	};
+}
+
+/** Rank all providers by score. */
+export function rank(
+	providers: Provider[],
+	criteria: SelectionCriteria = "balanced",
+): Provider[] {
+	return providers
+		.filter((p) => p.available)
+		.map((p) => ({ p, score: combinedScore(p, criteria, providers) }))
+		.sort((a, b) => b.score - a.score)
+		.map((s) => s.p);
+}
+
+/** Compare two providers by cost. Returns negative if a is cheaper. */
+export function compareCost(a: Provider, b: Provider): number {
+	const aCost = a.inputCostPer1M + a.outputCostPer1M;
+	const bCost = b.inputCostPer1M + b.outputCostPer1M;
+	return aCost - bCost;
+}
+
+/** Compare two providers by latency. Returns negative if a is faster. */
+export function compareLatency(a: Provider, b: Provider): number {
+	return a.latencyMs - b.latencyMs;
+}
+
+/** Filter providers by capability. */
+export function filterByCapability(
+	providers: Provider[],
+	capability: Provider["capabilities"][number],
+): Provider[] {
+	return providers.filter((p) => p.capabilities.includes(capability));
+}
+
+/** Filter providers by region. */
+export function filterByRegion(
+	providers: Provider[],
+	region: Provider["region"],
+): Provider[] {
+	if (region === "global") return providers;
+	return providers.filter((p) => p.region === region || p.region === "global");
+}

package/packages/provider-selector/src/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Provider Selector Types (RFC-0012)
+ */
+
+export type ProviderCapability =
+	| "text"
+	| "vision"
+	| "function_calling"
+	| "streaming";
+export type ProviderRegion = "us" | "eu" | "asia" | "global";
+
+export interface Provider {
+	id: string;
+	name: string;
+	baseURL: string;
+	capabilities: ProviderCapability[];
+	region: ProviderRegion;
+	inputCostPer1M: number;
+	outputCostPer1M: number;
+	latencyMs: number;
+	qualityScore: number;
+	maxContextTokens: number;
+	available: boolean;
+}
+
+export type SelectionCriteria = "cost" | "latency" | "quality" | "balanced";
+
+export interface SelectionResult {
+	provider: Provider;
+	reason: string;
+	score: number;
+	alternatives: Provider[];
+}

package/packages/provider-selector/test/selector.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Provider Selector Tests (RFC-0012)
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+	selectProvider,
+	rank,
+	compareCost,
+	compareLatency,
+	filterByCapability,
+	filterByRegion,
+} from "../src/index.js";
+import type { Provider } from "../src/index.js";
+
+const makeProvider = (overrides?: Partial<Provider>): Provider => ({
+	id: "p1",
+	name: "Provider 1",
+	baseURL: "https://api.example.com",
+	capabilities: ["text"],
+	region: "us",
+	inputCostPer1M: 1.0,
+	outputCostPer1M: 3.0,
+	latencyMs: 500,
+	qualityScore: 80,
+	maxContextTokens: 128000,
+	available: true,
+	...overrides,
+});
+
+const PROVIDERS: Provider[] = [
+	makeProvider({
+		id: "cheap",
+		name: "Cheap",
+		inputCostPer1M: 0.1,
+		latencyMs: 200,
+		qualityScore: 60,
+	}),
+	makeProvider({
+		id: "fast",
+		name: "Fast",
+		inputCostPer1M: 2.0,
+		latencyMs: 50,
+		qualityScore: 90,
+	}),
+	makeProvider({
+		id: "quality",
+		name: "Quality",
+		inputCostPer1M: 5.0,
+		latencyMs: 800,
+		qualityScore: 98,
+	}),
+];
+
+describe("selectProvider", () => {
+	it("selects a provider", () => {
+		const result = selectProvider(PROVIDERS);
+		expect(result).not.toBeNull();
+		expect(result!.provider.available).toBe(true);
+	});
+
+	it("returns null for empty list", () => {
+		expect(selectProvider([])).toBeNull();
+	});
+
+	it("returns null when none available", () => {
+		const unavailable = PROVIDERS.map((p) => ({ ...p, available: false }));
+		expect(selectProvider(unavailable)).toBeNull();
+	});
+
+	it("prefers cheapest for cost criteria", () => {
+		const result = selectProvider(PROVIDERS, "cost");
+		expect(result!.provider.id).toBe("cheap");
+	});
+
+	it("prefers fastest for latency criteria", () => {
+		const result = selectProvider(PROVIDERS, "latency");
+		expect(result!.provider.id).toBe("fast");
+	});
+
+	it("prefers high quality for quality criteria", () => {
+		const result = selectProvider(PROVIDERS, "quality");
+		expect(result!.score).toBeGreaterThan(0.8);
+	});
+
+	it("includes alternatives", () => {
+		const result = selectProvider(PROVIDERS);
+		expect(result!.alternatives.length).toBeGreaterThan(0);
+	});
+
+	it("includes reason", () => {
+		const result = selectProvider(PROVIDERS);
+		expect(result!.reason).toContain("score:");
+	});
+});
+
+describe("rank", () => {
+	it("returns sorted providers", () => {
+		const ranked = rank(PROVIDERS);
+		expect(ranked.length).toBe(3);
+		expect(ranked[0].available).toBe(true);
+	});
+
+	it("uses criteria for ranking", () => {
+		const byCost = rank(PROVIDERS, "cost");
+		const byLatency = rank(PROVIDERS, "latency");
+		expect(byCost[0].id).not.toBe(byLatency[0].id);
+	});
+
+	it("filters unavailable", () => {
+		const mixed = [
+			...PROVIDERS,
+			{ ...PROVIDERS[0], id: "down", available: false },
+		];
+		expect(rank(mixed).length).toBe(3);
+	});
+});
+
+describe("compareCost", () => {
+	it("negative when a is cheaper", () => {
+		const cheap = makeProvider({
+			id: "c",
+			inputCostPer1M: 0.5,
+			outputCostPer1M: 1.0,
+		});
+		const expensive = makeProvider({
+			id: "e",
+			inputCostPer1M: 5.0,
+			outputCostPer1M: 10.0,
+		});
+		expect(compareCost(cheap, expensive)).toBeLessThan(0);
+	});
+
+	it("positive when a is more expensive", () => {
+		const cheap = makeProvider({
+			id: "c",
+			inputCostPer1M: 0.5,
+			outputCostPer1M: 1.0,
+		});
+		const expensive = makeProvider({
+			id: "e",
+			inputCostPer1M: 5.0,
+			outputCostPer1M: 10.0,
+		});
+		expect(compareCost(expensive, cheap)).toBeGreaterThan(0);
+	});
+});
+
+describe("compareLatency", () => {
+	it("negative when a is faster", () => {
+		const fast = makeProvider({ id: "f", latencyMs: 50 });
+		const slow = makeProvider({ id: "s", latencyMs: 500 });
+		expect(compareLatency(fast, slow)).toBeLessThan(0);
+	});
+});
+
+describe("filterByCapability", () => {
+	it("filters to matching capability", () => {
+		const mixed = [
+			makeProvider({ id: "t", capabilities: ["text"] }),
+			makeProvider({ id: "tv", capabilities: ["text", "vision"] }),
+		];
+		expect(filterByCapability(mixed, "vision")).toHaveLength(1);
+		expect(filterByCapability(mixed, "vision")[0].id).toBe("tv");
+	});
+});
+
+describe("filterByRegion", () => {
+	it("filters by region", () => {
+		const mixed = [
+			makeProvider({ id: "us1", region: "us" }),
+			makeProvider({ id: "eu1", region: "eu" }),
+		];
+		expect(filterByRegion(mixed, "us")).toHaveLength(1);
+	});
+
+	it("global returns all", () => {
+		const mixed = [
+			makeProvider({ region: "us" }),
+			makeProvider({ region: "eu" }),
+		];
+		expect(filterByRegion(mixed, "global")).toHaveLength(2);
+	});
+
+	it("global regions always match", () => {
+		const mixed = [
+			makeProvider({ id: "g", region: "global" }),
+			makeProvider({ id: "us", region: "us" }),
+		];
+		expect(filterByRegion(mixed, "eu")).toHaveLength(1);
+	});
+});

package/packages/provider-selector/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "./dist", "rootDir": "./src", "types": ["node"], "lib": ["ES2022"] },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}

package/packages/providers/dist/adapters.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Provider Adapter — RFC-0002
+ *
+ * Normalizes provider-specific behavior for:
+ * - model invocation
+ * - error detection
+ * - quota detection
+ * - reset time discovery
+ * - retry policy
+ * - model capability metadata
+ */
+import type { ProviderConfig, ProviderCapability, ProviderRequest, ProviderResponse } from "../../packages/types/src/runtime-types.js";
+export interface AdapterConfig {
+    provider: ProviderConfig;
+    quotaSignalExtractor?: (error: unknown) => QuotaSignal | null;
+}
+export interface QuotaSignal {
+    exhausted: boolean;
+    resetsAt?: string;
+    retryAfterMs?: number;
+}
+export interface AdapterResult {
+    response: ProviderResponse;
+    quotaSignal?: QuotaSignal;
+    retryable: boolean;
+}
+export interface ProviderAdapter {
+    readonly id: string;
+    readonly name: string;
+    invoke(request: ProviderRequest): Promise<AdapterResult>;
+    parseError(error: unknown): {
+        quotaExceeded: boolean;
+        rateLimited: boolean;
+        timeout: boolean;
+        serverError: boolean;
+        clientError: boolean;
+        quotaSignal?: QuotaSignal;
+    };
+    getCapabilities(): ProviderCapability[];
+    supportsModel(model: string): boolean;
+    getDefaultModel(): string;
+    getMaxTokens(model?: string): number;
+}
+/**
+ * Base adapter with common functionality
+ */
+export declare abstract class BaseProviderAdapter implements ProviderAdapter {
+    protected config: ProviderConfig;
+    abstract readonly id: string;
+    abstract readonly name: string;
+    constructor(config: ProviderConfig);
+    abstract invoke(request: ProviderRequest): Promise<AdapterResult>;
+    abstract parseError(error: unknown): {
+        quotaExceeded: boolean;
+        rateLimited: boolean;
+        timeout: boolean;
+        serverError: boolean;
+        clientError: boolean;
+        quotaSignal?: QuotaSignal;
+    };
+    getCapabilities(): ProviderCapability[];
+    supportsModel(model: string): boolean;
+    getDefaultModel(): string;
+    getMaxTokens(model?: string): number;
+    /**
+     * Parse usage from response
+     */
+    protected parseUsage(response: unknown): ProviderResponse["usage"];
+}
+/**
+ * MiniMax adapter
+ */
+export declare class MiniMaxAdapter extends BaseProviderAdapter {
+    readonly id = "minimax";
+    readonly name = "MiniMax";
+    invoke(request: ProviderRequest): Promise<AdapterResult>;
+    parseError(error: unknown): {
+        quotaExceeded: boolean;
+        rateLimited: boolean;
+        timeout: boolean;
+        serverError: boolean;
+        clientError: boolean;
+        quotaSignal?: QuotaSignal;
+    };
+}
+/**
+ * OpenAI adapter
+ */
+export declare class OpenAIAdapter extends BaseProviderAdapter {
+    readonly id = "openai";
+    readonly name = "OpenAI";
+    invoke(request: ProviderRequest): Promise<AdapterResult>;
+    parseError(error: unknown): {
+        quotaExceeded: boolean;
+        rateLimited: boolean;
+        timeout: boolean;
+        serverError: boolean;
+        clientError: boolean;
+        quotaSignal?: QuotaSignal;
+    };
+}
+/**
+ * Claude adapter — Anthropic's Claude models
+ */
+export declare class ClaudeAdapter extends BaseProviderAdapter {
+    readonly id = "anthropic";
+    readonly name = "Anthropic Claude";
+    invoke(request: ProviderRequest): Promise<AdapterResult>;
+    parseError(error: unknown): {
+        quotaExceeded: boolean;
+        rateLimited: boolean;
+        timeout: boolean;
+        serverError: boolean;
+        clientError: boolean;
+        quotaSignal?: QuotaSignal;
+    };
+    getDefaultModel(): string;
+    getMaxTokens(model?: string): number;
+}
+/**
+ * Adapter registry
+ */
+export declare class AdapterRegistry {
+    private adapters;
+    register(adapter: ProviderAdapter): void;
+    get(id: string): ProviderAdapter | undefined;
+    list(): ProviderAdapter[];
+    /**
+     * Create default registry with standard adapters
+     */
+    static createDefault(): AdapterRegistry;
+}
+//# sourceMappingURL=adapters.d.ts.map

package/packages/providers/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"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"}