@antseed/router-core 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @antseed/router-core
+
+Shared infrastructure for building Antseed router plugins. Provides multi-factor peer scoring and per-peer metrics tracking.
+
+## Installation
+
+```bash
+pnpm add @antseed/router-core
+```
+
+Peer dependency: `@antseed/node >= 0.1.0`
+
+## Key Exports
+
+### scoreCandidates
+
+Scores and ranks peers using a weighted multi-factor algorithm:
+
+| Factor | Description |
+|--------|-------------|
+| **price** | Lower price scores higher |
+| **latency** | Lower latency EMA scores higher |
+| **capacity** | More available capacity scores higher |
+| **reputation** | Higher trust/reputation scores higher |
+| **freshness** | More recently seen peers score higher |
+| **reliability** | Lower failure rate scores higher |
+
+```ts
+import { scoreCandidates, DEFAULT_WEIGHTS } from '@antseed/router-core';
+
+const scored = scoreCandidates(peers, {
+  weights: DEFAULT_WEIGHTS,
+  metrics: tracker,
+  now: Date.now(),
+  maxPeerStalenessMs: 300_000,
+});
+// Returns ScoredCandidate[] sorted by score descending
+```
+
+### PeerMetricsTracker
+
+Tracks per-peer performance metrics for routing decisions.
+
+```ts
+import { PeerMetricsTracker } from '@antseed/router-core';
+
+const tracker = new PeerMetricsTracker({ maxFailures: 3, failureCooldownMs: 30_000 });
+
+// Record results
+tracker.recordSuccess(peerId, latencyMs);
+tracker.recordFailure(peerId);
+
+// Check if peer is on cooldown
+tracker.isOnCooldown(peerId, Date.now());
+```
+
+### Tool Hints
+
+```ts
+import { WELL_KNOWN_TOOL_HINTS, formatToolHints } from '@antseed/router-core';
+```
+
+## Default Scoring Weights
+
+```ts
+const DEFAULT_WEIGHTS = {
+  price: 0.25,
+  latency: 0.25,
+  capacity: 0.15,
+  reputation: 0.15,
+  freshness: 0.10,
+  reliability: 0.10,
+};
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { scoreCandidates, DEFAULT_WEIGHTS, type ScoringWeights, type ScoredCandidate, type TokenPricingUsdPerMillion, type PeerMetrics, } from './peer-scorer.js';
+export { PeerMetricsTracker, type PeerMetricsTrackerConfig, } from './peer-metrics.js';
+export { WELL_KNOWN_TOOL_HINTS, formatToolHints, type ToolHint, } from './tool-hints.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { scoreCandidates, DEFAULT_WEIGHTS, } from './peer-scorer.js';
+export { PeerMetricsTracker, } from './peer-metrics.js';
+export { WELL_KNOWN_TOOL_HINTS, formatToolHints, } from './tool-hints.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,GAKhB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,kBAAkB,GAEnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,qBAAqB,EACrB,eAAe,GAEhB,MAAM,iBAAiB,CAAA"}

package/dist/peer-metrics.d.ts

@@ -0,0 +1,27 @@
+import type { PeerMetrics } from './peer-scorer.js';
+export interface PeerMetricsTrackerConfig {
+    latencyAlpha?: number;
+    maxFailures?: number;
+    failureCooldownMs?: number;
+    now?: () => number;
+}
+export declare class PeerMetricsTracker {
+    private readonly _latencyMap;
+    private readonly _failureStreakMap;
+    private readonly _totalFailureMap;
+    private readonly _attemptMap;
+    private readonly _cooldownUntilMap;
+    private readonly _latencyAlpha;
+    private readonly _maxFailures;
+    private readonly _failureCooldownMs;
+    private readonly _now;
+    constructor(config?: PeerMetricsTrackerConfig);
+    recordResult(peerId: string, result: {
+        success: boolean;
+        latencyMs: number;
+    }): void;
+    getMetrics(peerId: string): PeerMetrics;
+    isCoolingDown(peerId: string): boolean;
+    getMedianLatency(): number;
+}
+//# sourceMappingURL=peer-metrics.d.ts.map

package/dist/peer-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-metrics.d.ts","sourceRoot":"","sources":["../src/peer-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,MAAM,WAAW,wBAAwB;IACvC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4B;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;IAE9D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;gBAEvB,MAAM,CAAC,EAAE,wBAAwB;IAO7C,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA6BnF,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW;IAUvC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAWtC,gBAAgB,IAAI,MAAM;CAS3B"}

package/dist/peer-metrics.js

@@ -0,0 +1,72 @@
+export class PeerMetricsTracker {
+    _latencyMap = new Map();
+    _failureStreakMap = new Map();
+    _totalFailureMap = new Map();
+    _attemptMap = new Map();
+    _cooldownUntilMap = new Map();
+    _latencyAlpha;
+    _maxFailures;
+    _failureCooldownMs;
+    _now;
+    constructor(config) {
+        this._latencyAlpha = config?.latencyAlpha ?? 0.3;
+        this._maxFailures = Math.max(1, config?.maxFailures ?? 3);
+        this._failureCooldownMs = Math.max(1, config?.failureCooldownMs ?? 30_000);
+        this._now = config?.now ?? (() => Date.now());
+    }
+    recordResult(peerId, result) {
+        const now = this._now();
+        const attempts = (this._attemptMap.get(peerId) ?? 0) + 1;
+        this._attemptMap.set(peerId, attempts);
+        if (result.success) {
+            // Update latency EMA
+            const prev = this._latencyMap.get(peerId) ?? result.latencyMs;
+            this._latencyMap.set(peerId, prev * (1 - this._latencyAlpha) + result.latencyMs * this._latencyAlpha);
+            // Reset failure count on success
+            this._failureStreakMap.delete(peerId);
+            this._cooldownUntilMap.delete(peerId);
+        }
+        else {
+            const currentStreak = this._failureStreakMap.get(peerId) ?? 0;
+            const nextStreak = currentStreak + 1;
+            this._failureStreakMap.set(peerId, nextStreak);
+            this._totalFailureMap.set(peerId, (this._totalFailureMap.get(peerId) ?? 0) + 1);
+            if (nextStreak >= this._maxFailures) {
+                const penaltyPower = Math.min(4, nextStreak - this._maxFailures);
+                const cooldownMs = this._failureCooldownMs * (2 ** penaltyPower);
+                this._cooldownUntilMap.set(peerId, now + cooldownMs);
+            }
+        }
+    }
+    getMetrics(peerId) {
+        return {
+            latencyEma: this._latencyMap.get(peerId),
+            failureStreak: this._failureStreakMap.get(peerId) ?? 0,
+            totalFailures: this._totalFailureMap.get(peerId) ?? 0,
+            totalAttempts: this._attemptMap.get(peerId) ?? 0,
+            cooldownUntil: this._cooldownUntilMap.get(peerId),
+        };
+    }
+    isCoolingDown(peerId) {
+        const now = this._now();
+        const until = this._cooldownUntilMap.get(peerId);
+        if (until === undefined)
+            return false;
+        if (until <= now) {
+            this._cooldownUntilMap.delete(peerId);
+            return false;
+        }
+        return true;
+    }
+    getMedianLatency() {
+        const values = [...this._latencyMap.values()];
+        if (values.length === 0)
+            return 500;
+        values.sort((a, b) => a - b);
+        const mid = Math.floor(values.length / 2);
+        return values.length % 2 === 0
+            ? (values[mid - 1] + values[mid]) / 2
+            : values[mid];
+    }
+}
+//# sourceMappingURL=peer-metrics.js.map

package/dist/peer-metrics.js.map

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

package/dist/peer-scorer.d.ts

@@ -0,0 +1,52 @@
+import type { PeerInfo } from '@antseed/node';
+export interface TokenPricingUsdPerMillion {
+    inputUsdPerMillion: number;
+    outputUsdPerMillion: number;
+}
+export interface ScoringWeights {
+    price: number;
+    latency: number;
+    capacity: number;
+    reputation: number;
+    freshness: number;
+    reliability: number;
+}
+export declare const DEFAULT_WEIGHTS: ScoringWeights;
+export interface PeerMetrics {
+    latencyEma: number | undefined;
+    failureStreak: number;
+    totalFailures: number;
+    totalAttempts: number;
+    cooldownUntil: number | undefined;
+}
+export interface ScoredCandidate {
+    peer: PeerInfo;
+    provider: string;
+    providerRank: number;
+    offer: TokenPricingUsdPerMillion;
+    score: number;
+}
+interface CandidateInput {
+    peer: PeerInfo;
+    provider: string;
+    providerRank: number;
+    offer: TokenPricingUsdPerMillion;
+    metrics: PeerMetrics;
+}
+interface ScoringContext {
+    now: number;
+    medianLatency: number;
+    maxPeerStalenessMs: number;
+    maxFailures: number;
+    weights?: Partial<ScoringWeights>;
+}
+/**
+ * Score and rank candidates using the composite scoring algorithm.
+ *
+ * Calculates normalization context (min/max price, latency, capacity),
+ * scores each candidate with weighted factors, and returns candidates
+ * sorted by score (highest first).
+ */
+export declare function scoreCandidates(candidates: CandidateInput[], context: ScoringContext): ScoredCandidate[];
+export {};
+//# sourceMappingURL=peer-scorer.d.ts.map

package/dist/peer-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-scorer.d.ts","sourceRoot":"","sources":["../src/peer-scorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,mBAAmB,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,eAAO,MAAM,eAAe,EAAE,cAO7B,CAAA;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,yBAAyB,CAAA;IAChC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,QAAQ,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,yBAAyB,CAAA;IAChC,OAAO,EAAE,WAAW,CAAA;CACrB;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CAClC;AAgDD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,cAAc,EAAE,EAC5B,OAAO,EAAE,cAAc,GACtB,eAAe,EAAE,CAkFnB"}

package/dist/peer-scorer.js

@@ -0,0 +1,130 @@
+export const DEFAULT_WEIGHTS = {
+    price: 0.30,
+    latency: 0.25,
+    capacity: 0.20,
+    reputation: 0.10,
+    freshness: 0.10,
+    reliability: 0.05,
+};
+function normalizedInverted(value, min, range) {
+    if (range <= 0) {
+        return 1;
+    }
+    return 1 - (value - min) / range;
+}
+function effectiveReputation(p) {
+    if (p.onChainReputation !== undefined) {
+        return p.onChainReputation;
+    }
+    return p.trustScore ?? p.reputationScore ?? 0;
+}
+function availableCapacity(p) {
+    const max = p.maxConcurrency ?? 1;
+    const current = p.currentLoad ?? 0;
+    return Math.max(0, max - current);
+}
+function freshnessFactor(p, now, maxPeerStalenessMs) {
+    if (!Number.isFinite(p.lastSeen))
+        return 0.5;
+    const age = Math.max(0, now - p.lastSeen);
+    if (age >= maxPeerStalenessMs)
+        return 0;
+    return 1 - (age / maxPeerStalenessMs);
+}
+function reliabilityFactor(metrics, maxFailures) {
+    const historicalPenalty = metrics.totalAttempts > 0 ? metrics.totalFailures / metrics.totalAttempts : 0;
+    const streakPenalty = Math.min(1, metrics.failureStreak / maxFailures);
+    return Math.max(0, 1 - Math.max(historicalPenalty, streakPenalty));
+}
+function peerLatency(metrics, medianLatency) {
+    return metrics.latencyEma ?? medianLatency;
+}
+function tieBreak(a, aLatencyEma, b, bLatencyEma) {
+    const latA = aLatencyEma ?? Number.POSITIVE_INFINITY;
+    const latB = bLatencyEma ?? Number.POSITIVE_INFINITY;
+    if (latA !== latB) {
+        return latA - latB;
+    }
+    return a.peerId.localeCompare(b.peerId);
+}
+/**
+ * Score and rank candidates using the composite scoring algorithm.
+ *
+ * Calculates normalization context (min/max price, latency, capacity),
+ * scores each candidate with weighted factors, and returns candidates
+ * sorted by score (highest first).
+ */
+export function scoreCandidates(candidates, context) {
+    if (candidates.length === 0)
+        return [];
+    const w = { ...DEFAULT_WEIGHTS, ...context.weights };
+    // --- Normalization context ---
+    const knownPrices = candidates
+        .map((c) => c.offer.inputUsdPerMillion)
+        .filter((value) => Number.isFinite(value));
+    const fallbackPrice = knownPrices.length > 0 ? Math.max(...knownPrices) * 1.25 : 1;
+    let minPrice = knownPrices.length > 0 ? Math.min(...knownPrices) : fallbackPrice;
+    let maxPrice = knownPrices.length > 0 ? Math.max(...knownPrices) : fallbackPrice;
+    let minLatency = Number.POSITIVE_INFINITY;
+    let maxLatency = 0;
+    let maxCap = 0;
+    for (const c of candidates) {
+        const price = c.offer.inputUsdPerMillion;
+        if (price < minPrice)
+            minPrice = price;
+        if (price > maxPrice)
+            maxPrice = price;
+        const lat = peerLatency(c.metrics, context.medianLatency);
+        if (lat < minLatency)
+            minLatency = lat;
+        if (lat > maxLatency)
+            maxLatency = lat;
+        const cap = availableCapacity(c.peer);
+        if (cap > maxCap)
+            maxCap = cap;
+    }
+    const priceRange = maxPrice - minPrice;
+    const latencyRange = maxLatency - minLatency;
+    // --- Score each candidate ---
+    const scored = [];
+    for (const c of candidates) {
+        // Price factor (lower is better, inverted)
+        const price = c.offer.inputUsdPerMillion ?? fallbackPrice;
+        const priceFactor = normalizedInverted(price, minPrice, priceRange);
+        // Latency factor (lower is better, inverted)
+        const lat = peerLatency(c.metrics, context.medianLatency);
+        const latencyFactor = normalizedInverted(lat, minLatency, latencyRange);
+        // Capacity factor (higher is better)
+        const capFactor = maxCap > 0
+            ? availableCapacity(c.peer) / maxCap
+            : 1;
+        // Reputation factor (higher is better, normalized 0-100 to 0-1)
+        const repFactor = effectiveReputation(c.peer) / 100;
+        const fresh = freshnessFactor(c.peer, context.now, context.maxPeerStalenessMs);
+        const reliability = reliabilityFactor(c.metrics, context.maxFailures);
+        const score = w.price * priceFactor +
+            w.latency * latencyFactor +
+            w.capacity * capFactor +
+            w.reputation * repFactor +
+            w.freshness * fresh +
+            w.reliability * reliability;
+        scored.push({
+            peer: c.peer,
+            provider: c.provider,
+            providerRank: c.providerRank,
+            offer: c.offer,
+            score,
+        });
+    }
+    // Sort by score descending, tie-break by latency then peerId
+    scored.sort((a, b) => {
+        if (Math.abs(a.score - b.score) < 1e-9) {
+            const aMetrics = candidates.find((c) => c.peer.peerId === a.peer.peerId);
+            const bMetrics = candidates.find((c) => c.peer.peerId === b.peer.peerId);
+            return tieBreak(a.peer, aMetrics?.metrics.latencyEma, b.peer, bMetrics?.metrics.latencyEma);
+        }
+        return b.score - a.score;
+    });
+    return scored;
+}
+//# sourceMappingURL=peer-scorer.js.map

package/dist/peer-scorer.js.map

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

package/dist/tool-hints.d.ts

@@ -0,0 +1,7 @@
+export interface ToolHint {
+    name: string;
+    envVar: string;
+}
+export declare const WELL_KNOWN_TOOL_HINTS: ToolHint[];
+export declare function formatToolHints(hints: ToolHint[], proxyUrl: string): string[];
+//# sourceMappingURL=tool-hints.d.ts.map

package/dist/tool-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hints.d.ts","sourceRoot":"","sources":["../src/tool-hints.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,eAAO,MAAM,qBAAqB,EAAE,QAAQ,EAK3C,CAAA;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7E"}

package/dist/tool-hints.js

@@ -0,0 +1,10 @@
+export const WELL_KNOWN_TOOL_HINTS = [
+    { name: 'Claude Code', envVar: 'ANTHROPIC_BASE_URL' },
+    { name: 'Aider', envVar: 'OPENAI_API_BASE' },
+    { name: 'Continue.dev', envVar: 'OPENAI_BASE_URL' },
+    { name: 'Codex', envVar: 'OPENAI_BASE_URL' },
+];
+export function formatToolHints(hints, proxyUrl) {
+    return hints.map(hint => `export ${hint.envVar}=${proxyUrl}   # ${hint.name}`);
+}
+//# sourceMappingURL=tool-hints.js.map

package/dist/tool-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hints.js","sourceRoot":"","sources":["../src/tool-hints.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,qBAAqB,GAAe;IAC/C,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,oBAAoB,EAAE;IACrD,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE;IAC5C,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE;IACnD,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE;CAC7C,CAAA;AAED,MAAM,UAAU,eAAe,CAAC,KAAiB,EAAE,QAAgB;IACjE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,IAAI,CAAC,MAAM,IAAI,QAAQ,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;AAChF,CAAC"}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@antseed/router-core",
+  "version": "0.1.0",
+  "description": "Shared router infrastructure for Antseed plugins",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@antseed/node": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@antseed/node": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  scoreCandidates,
+  DEFAULT_WEIGHTS,
+  type ScoringWeights,
+  type ScoredCandidate,
+  type TokenPricingUsdPerMillion,
+  type PeerMetrics,
+} from './peer-scorer.js'
+export {
+  PeerMetricsTracker,
+  type PeerMetricsTrackerConfig,
+} from './peer-metrics.js'
+export {
+  WELL_KNOWN_TOOL_HINTS,
+  formatToolHints,
+  type ToolHint,
+} from './tool-hints.js'

package/src/peer-metrics.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect } from 'vitest'
+import { PeerMetricsTracker } from './peer-metrics.js'
+
+describe('PeerMetricsTracker', () => {
+  describe('latency EMA calculation', () => {
+    it('initializes EMA to the first latency value', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+
+      const metrics = tracker.getMetrics('peer1')
+      // First call: prev = 100 (default to result), EMA = 100 * 0.7 + 100 * 0.3 = 100
+      expect(metrics.latencyEma).toBe(100)
+    })
+
+    it('applies exponential moving average on subsequent results', () => {
+      const tracker = new PeerMetricsTracker({ latencyAlpha: 0.3 })
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: true, latencyMs: 200 })
+
+      const metrics = tracker.getMetrics('peer1')
+      // After first: EMA = 100
+      // After second: EMA = 100 * 0.7 + 200 * 0.3 = 70 + 60 = 130
+      expect(metrics.latencyEma).toBe(130)
+    })
+
+    it('respects custom latencyAlpha', () => {
+      const tracker = new PeerMetricsTracker({ latencyAlpha: 0.5 })
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: true, latencyMs: 200 })
+
+      const metrics = tracker.getMetrics('peer1')
+      // After first: EMA = 100
+      // After second: EMA = 100 * 0.5 + 200 * 0.5 = 150
+      expect(metrics.latencyEma).toBe(150)
+    })
+  })
+
+  describe('failure streak tracking', () => {
+    it('increments failure streak on consecutive failures', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+
+      const metrics = tracker.getMetrics('peer1')
+      expect(metrics.failureStreak).toBe(2)
+      expect(metrics.totalFailures).toBe(2)
+      expect(metrics.totalAttempts).toBe(2)
+    })
+
+    it('success resets failure streak', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+
+      const metrics = tracker.getMetrics('peer1')
+      expect(metrics.failureStreak).toBe(0)
+      // Total failures and attempts remain
+      expect(metrics.totalFailures).toBe(2)
+      expect(metrics.totalAttempts).toBe(3)
+    })
+
+    it('tracks total failures independently from streak', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+
+      const metrics = tracker.getMetrics('peer1')
+      expect(metrics.failureStreak).toBe(1)
+      expect(metrics.totalFailures).toBe(2)
+      expect(metrics.totalAttempts).toBe(3)
+    })
+  })
+
+  describe('cooldown timing', () => {
+    it('enters cooldown after maxFailures consecutive failures', () => {
+      let now = 1_000_000
+      const tracker = new PeerMetricsTracker({
+        maxFailures: 2,
+        failureCooldownMs: 500,
+        now: () => now,
+      })
+
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      expect(tracker.isCoolingDown('peer1')).toBe(false)
+
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      expect(tracker.isCoolingDown('peer1')).toBe(true)
+    })
+
+    it('cooldown expires after failureCooldownMs', () => {
+      let now = 1_000_000
+      const tracker = new PeerMetricsTracker({
+        maxFailures: 2,
+        failureCooldownMs: 500,
+        now: () => now,
+      })
+
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      expect(tracker.isCoolingDown('peer1')).toBe(true)
+
+      now += 501
+      expect(tracker.isCoolingDown('peer1')).toBe(false)
+    })
+
+    it('success clears cooldown', () => {
+      let now = 1_000_000
+      const tracker = new PeerMetricsTracker({
+        maxFailures: 2,
+        failureCooldownMs: 500,
+        now: () => now,
+      })
+
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      expect(tracker.isCoolingDown('peer1')).toBe(true)
+
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+      expect(tracker.isCoolingDown('peer1')).toBe(false)
+    })
+
+    it('applies exponential backoff for repeated failure streaks beyond threshold', () => {
+      let now = 1_000_000
+      const tracker = new PeerMetricsTracker({
+        maxFailures: 2,
+        failureCooldownMs: 500,
+        now: () => now,
+      })
+
+      // 2 failures: cooldown = 500 * 2^0 = 500
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+
+      const metrics2 = tracker.getMetrics('peer1')
+      expect(metrics2.cooldownUntil).toBe(now + 500)
+
+      // 3rd failure: cooldown = 500 * 2^1 = 1000
+      now += 501 // past first cooldown
+      tracker.recordResult('peer1', { success: false, latencyMs: 100 })
+
+      const metrics3 = tracker.getMetrics('peer1')
+      expect(metrics3.cooldownUntil).toBe(now + 1000)
+    })
+  })
+
+  describe('median latency', () => {
+    it('returns 500 when no latencies recorded', () => {
+      const tracker = new PeerMetricsTracker()
+      expect(tracker.getMedianLatency()).toBe(500)
+    })
+
+    it('returns single value when only one peer has latency', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: true, latencyMs: 200 })
+      expect(tracker.getMedianLatency()).toBe(200)
+    })
+
+    it('returns median of odd number of values', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+      tracker.recordResult('peer2', { success: true, latencyMs: 300 })
+      tracker.recordResult('peer3', { success: true, latencyMs: 200 })
+
+      expect(tracker.getMedianLatency()).toBe(200)
+    })
+
+    it('returns average of two middle values for even count', () => {
+      const tracker = new PeerMetricsTracker()
+      tracker.recordResult('peer1', { success: true, latencyMs: 100 })
+      tracker.recordResult('peer2', { success: true, latencyMs: 200 })
+      tracker.recordResult('peer3', { success: true, latencyMs: 300 })
+      tracker.recordResult('peer4', { success: true, latencyMs: 400 })
+
+      expect(tracker.getMedianLatency()).toBe(250)
+    })
+  })
+
+  describe('getMetrics', () => {
+    it('returns zeroed metrics for unknown peer', () => {
+      const tracker = new PeerMetricsTracker()
+      const metrics = tracker.getMetrics('unknown')
+
+      expect(metrics.latencyEma).toBeUndefined()
+      expect(metrics.failureStreak).toBe(0)
+      expect(metrics.totalFailures).toBe(0)
+      expect(metrics.totalAttempts).toBe(0)
+      expect(metrics.cooldownUntil).toBeUndefined()
+    })
+  })
+})

package/src/peer-metrics.ts

@@ -0,0 +1,88 @@
+import type { PeerMetrics } from './peer-scorer.js'
+
+export interface PeerMetricsTrackerConfig {
+  latencyAlpha?: number       // Default: 0.3
+  maxFailures?: number        // Default: 3
+  failureCooldownMs?: number  // Default: 30000
+  now?: () => number
+}
+
+export class PeerMetricsTracker {
+  private readonly _latencyMap = new Map<string, number>()
+  private readonly _failureStreakMap = new Map<string, number>()
+  private readonly _totalFailureMap = new Map<string, number>()
+  private readonly _attemptMap = new Map<string, number>()
+  private readonly _cooldownUntilMap = new Map<string, number>()
+
+  private readonly _latencyAlpha: number
+  private readonly _maxFailures: number
+  private readonly _failureCooldownMs: number
+  private readonly _now: () => number
+
+  constructor(config?: PeerMetricsTrackerConfig) {
+    this._latencyAlpha = config?.latencyAlpha ?? 0.3
+    this._maxFailures = Math.max(1, config?.maxFailures ?? 3)
+    this._failureCooldownMs = Math.max(1, config?.failureCooldownMs ?? 30_000)
+    this._now = config?.now ?? (() => Date.now())
+  }
+
+  recordResult(peerId: string, result: { success: boolean; latencyMs: number }): void {
+    const now = this._now()
+    const attempts = (this._attemptMap.get(peerId) ?? 0) + 1
+    this._attemptMap.set(peerId, attempts)
+
+    if (result.success) {
+      // Update latency EMA
+      const prev = this._latencyMap.get(peerId) ?? result.latencyMs
+      this._latencyMap.set(
+        peerId,
+        prev * (1 - this._latencyAlpha) + result.latencyMs * this._latencyAlpha,
+      )
+      // Reset failure count on success
+      this._failureStreakMap.delete(peerId)
+      this._cooldownUntilMap.delete(peerId)
+    } else {
+      const currentStreak = this._failureStreakMap.get(peerId) ?? 0
+      const nextStreak = currentStreak + 1
+      this._failureStreakMap.set(peerId, nextStreak)
+      this._totalFailureMap.set(peerId, (this._totalFailureMap.get(peerId) ?? 0) + 1)
+
+      if (nextStreak >= this._maxFailures) {
+        const penaltyPower = Math.min(4, nextStreak - this._maxFailures)
+        const cooldownMs = this._failureCooldownMs * (2 ** penaltyPower)
+        this._cooldownUntilMap.set(peerId, now + cooldownMs)
+      }
+    }
+  }
+
+  getMetrics(peerId: string): PeerMetrics {
+    return {
+      latencyEma: this._latencyMap.get(peerId),
+      failureStreak: this._failureStreakMap.get(peerId) ?? 0,
+      totalFailures: this._totalFailureMap.get(peerId) ?? 0,
+      totalAttempts: this._attemptMap.get(peerId) ?? 0,
+      cooldownUntil: this._cooldownUntilMap.get(peerId),
+    }
+  }
+
+  isCoolingDown(peerId: string): boolean {
+    const now = this._now()
+    const until = this._cooldownUntilMap.get(peerId)
+    if (until === undefined) return false
+    if (until <= now) {
+      this._cooldownUntilMap.delete(peerId)
+      return false
+    }
+    return true
+  }
+
+  getMedianLatency(): number {
+    const values = [...this._latencyMap.values()]
+    if (values.length === 0) return 500
+    values.sort((a, b) => a - b)
+    const mid = Math.floor(values.length / 2)
+    return values.length % 2 === 0
+      ? (values[mid - 1]! + values[mid]!) / 2
+      : values[mid]!
+  }
+}

package/src/peer-scorer.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect } from 'vitest'
+import type { PeerInfo } from '@antseed/node'
+import { scoreCandidates, DEFAULT_WEIGHTS } from './peer-scorer.js'
+import type { PeerMetrics, TokenPricingUsdPerMillion } from './peer-scorer.js'
+
+function makePeerId(char: string): PeerInfo['peerId'] {
+  return char.repeat(64) as PeerInfo['peerId']
+}
+
+function makePeer(overrides?: Partial<PeerInfo>): PeerInfo {
+  return {
+    peerId: makePeerId('a'),
+    lastSeen: 1_000_000,
+    providers: ['anthropic'],
+    reputationScore: 80,
+    trustScore: 80,
+    maxConcurrency: 10,
+    currentLoad: 1,
+    ...overrides,
+  }
+}
+
+const defaultMetrics: PeerMetrics = {
+  latencyEma: undefined,
+  failureStreak: 0,
+  totalFailures: 0,
+  totalAttempts: 0,
+  cooldownUntil: undefined,
+}
+
+const defaultOffer: TokenPricingUsdPerMillion = {
+  inputUsdPerMillion: 10,
+  outputUsdPerMillion: 10,
+}
+
+const defaultContext = {
+  now: 1_000_000,
+  medianLatency: 500,
+  maxPeerStalenessMs: 300_000,
+  maxFailures: 3,
+}
+
+describe('scoreCandidates', () => {
+  it('returns correct score ordering — cheaper peer ranks higher', () => {
+    const cheapPeer = makePeer({ peerId: makePeerId('1') })
+    const expensivePeer = makePeer({ peerId: makePeerId('2') })
+
+    const result = scoreCandidates(
+      [
+        {
+          peer: expensivePeer,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: { inputUsdPerMillion: 100, outputUsdPerMillion: 100 },
+          metrics: defaultMetrics,
+        },
+        {
+          peer: cheapPeer,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: { inputUsdPerMillion: 5, outputUsdPerMillion: 5 },
+          metrics: defaultMetrics,
+        },
+      ],
+      defaultContext,
+    )
+
+    expect(result).toHaveLength(2)
+    expect(result[0]!.peer.peerId).toBe(cheapPeer.peerId)
+    expect(result[1]!.peer.peerId).toBe(expensivePeer.peerId)
+    expect(result[0]!.score).toBeGreaterThan(result[1]!.score)
+  })
+
+  it('custom weights change ranking — zero out price, maximize latency', () => {
+    const cheapButSlow = makePeer({ peerId: makePeerId('1') })
+    const expensiveButFast = makePeer({ peerId: makePeerId('2') })
+
+    const result = scoreCandidates(
+      [
+        {
+          peer: cheapButSlow,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: { inputUsdPerMillion: 1, outputUsdPerMillion: 1 },
+          metrics: { ...defaultMetrics, latencyEma: 1000 },
+        },
+        {
+          peer: expensiveButFast,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: { inputUsdPerMillion: 100, outputUsdPerMillion: 100 },
+          metrics: { ...defaultMetrics, latencyEma: 50 },
+        },
+      ],
+      {
+        ...defaultContext,
+        weights: {
+          price: 0,
+          latency: 1.0,
+          capacity: 0,
+          reputation: 0,
+          freshness: 0,
+          reliability: 0,
+        },
+      },
+    )
+
+    expect(result[0]!.peer.peerId).toBe(expensiveButFast.peerId)
+  })
+
+  it('handles single candidate', () => {
+    const peer = makePeer({ peerId: makePeerId('1') })
+
+    const result = scoreCandidates(
+      [
+        {
+          peer,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: defaultOffer,
+          metrics: defaultMetrics,
+        },
+      ],
+      defaultContext,
+    )
+
+    expect(result).toHaveLength(1)
+    expect(result[0]!.peer.peerId).toBe(peer.peerId)
+    expect(result[0]!.score).toBeGreaterThan(0)
+  })
+
+  it('handles all equal scores — tie-broken by peerId', () => {
+    const peerA = makePeer({ peerId: makePeerId('a') })
+    const peerB = makePeer({ peerId: makePeerId('b') })
+
+    const result = scoreCandidates(
+      [
+        {
+          peer: peerB,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: defaultOffer,
+          metrics: defaultMetrics,
+        },
+        {
+          peer: peerA,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: defaultOffer,
+          metrics: defaultMetrics,
+        },
+      ],
+      defaultContext,
+    )
+
+    expect(result).toHaveLength(2)
+    // Both have identical inputs so scores should be equal; tie-break by peerId ascending
+    expect(result[0]!.peer.peerId).toBe(peerA.peerId)
+    expect(result[1]!.peer.peerId).toBe(peerB.peerId)
+  })
+
+  it('returns empty array for empty candidates', () => {
+    const result = scoreCandidates([], defaultContext)
+    expect(result).toHaveLength(0)
+  })
+
+  it('uses default weights when none provided', () => {
+    const peer = makePeer({ peerId: makePeerId('1') })
+
+    const result = scoreCandidates(
+      [
+        {
+          peer,
+          provider: 'anthropic',
+          providerRank: 0,
+          offer: defaultOffer,
+          metrics: defaultMetrics,
+        },
+      ],
+      defaultContext,
+    )
+
+    // With a single candidate, all normalized-inverted factors are 1.0
+    // Score = sum of all weights = 1.0 (minus any freshness/reputation adjustments)
+    expect(result[0]!.score).toBeGreaterThan(0)
+    expect(result[0]!.score).toBeLessThanOrEqual(
+      DEFAULT_WEIGHTS.price +
+      DEFAULT_WEIGHTS.latency +
+      DEFAULT_WEIGHTS.capacity +
+      DEFAULT_WEIGHTS.reputation +
+      DEFAULT_WEIGHTS.freshness +
+      DEFAULT_WEIGHTS.reliability,
+    )
+  })
+})

package/src/peer-scorer.ts

@@ -0,0 +1,196 @@
+import type { PeerInfo } from '@antseed/node'
+
+export interface TokenPricingUsdPerMillion {
+  inputUsdPerMillion: number
+  outputUsdPerMillion: number
+}
+
+export interface ScoringWeights {
+  price: number
+  latency: number
+  capacity: number
+  reputation: number
+  freshness: number
+  reliability: number
+}
+
+export const DEFAULT_WEIGHTS: ScoringWeights = {
+  price: 0.30,
+  latency: 0.25,
+  capacity: 0.20,
+  reputation: 0.10,
+  freshness: 0.10,
+  reliability: 0.05,
+}
+
+export interface PeerMetrics {
+  latencyEma: number | undefined
+  failureStreak: number
+  totalFailures: number
+  totalAttempts: number
+  cooldownUntil: number | undefined
+}
+
+export interface ScoredCandidate {
+  peer: PeerInfo
+  provider: string
+  providerRank: number
+  offer: TokenPricingUsdPerMillion
+  score: number
+}
+
+interface CandidateInput {
+  peer: PeerInfo
+  provider: string
+  providerRank: number
+  offer: TokenPricingUsdPerMillion
+  metrics: PeerMetrics
+}
+
+interface ScoringContext {
+  now: number
+  medianLatency: number
+  maxPeerStalenessMs: number
+  maxFailures: number
+  weights?: Partial<ScoringWeights>
+}
+
+function normalizedInverted(value: number, min: number, range: number): number {
+  if (range <= 0) {
+    return 1
+  }
+  return 1 - (value - min) / range
+}
+
+function effectiveReputation(p: PeerInfo): number {
+  if (p.onChainReputation !== undefined) {
+    return p.onChainReputation
+  }
+  return p.trustScore ?? p.reputationScore ?? 0
+}
+
+function availableCapacity(p: PeerInfo): number {
+  const max = p.maxConcurrency ?? 1
+  const current = p.currentLoad ?? 0
+  return Math.max(0, max - current)
+}
+
+function freshnessFactor(p: PeerInfo, now: number, maxPeerStalenessMs: number): number {
+  if (!Number.isFinite(p.lastSeen)) return 0.5
+  const age = Math.max(0, now - p.lastSeen)
+  if (age >= maxPeerStalenessMs) return 0
+  return 1 - (age / maxPeerStalenessMs)
+}
+
+function reliabilityFactor(metrics: PeerMetrics, maxFailures: number): number {
+  const historicalPenalty = metrics.totalAttempts > 0 ? metrics.totalFailures / metrics.totalAttempts : 0
+  const streakPenalty = Math.min(1, metrics.failureStreak / maxFailures)
+  return Math.max(0, 1 - Math.max(historicalPenalty, streakPenalty))
+}
+
+function peerLatency(metrics: PeerMetrics, medianLatency: number): number {
+  return metrics.latencyEma ?? medianLatency
+}
+
+function tieBreak(a: PeerInfo, aLatencyEma: number | undefined, b: PeerInfo, bLatencyEma: number | undefined): number {
+  const latA = aLatencyEma ?? Number.POSITIVE_INFINITY
+  const latB = bLatencyEma ?? Number.POSITIVE_INFINITY
+  if (latA !== latB) {
+    return latA - latB
+  }
+  return a.peerId.localeCompare(b.peerId)
+}
+
+/**
+ * Score and rank candidates using the composite scoring algorithm.
+ *
+ * Calculates normalization context (min/max price, latency, capacity),
+ * scores each candidate with weighted factors, and returns candidates
+ * sorted by score (highest first).
+ */
+export function scoreCandidates(
+  candidates: CandidateInput[],
+  context: ScoringContext,
+): ScoredCandidate[] {
+  if (candidates.length === 0) return []
+
+  const w: ScoringWeights = { ...DEFAULT_WEIGHTS, ...context.weights }
+
+  // --- Normalization context ---
+  const knownPrices = candidates
+    .map((c) => c.offer.inputUsdPerMillion)
+    .filter((value) => Number.isFinite(value))
+  const fallbackPrice = knownPrices.length > 0 ? Math.max(...knownPrices) * 1.25 : 1
+  let minPrice = knownPrices.length > 0 ? Math.min(...knownPrices) : fallbackPrice
+  let maxPrice = knownPrices.length > 0 ? Math.max(...knownPrices) : fallbackPrice
+  let minLatency = Number.POSITIVE_INFINITY
+  let maxLatency = 0
+  let maxCap = 0
+
+  for (const c of candidates) {
+    const price = c.offer.inputUsdPerMillion
+    if (price < minPrice) minPrice = price
+    if (price > maxPrice) maxPrice = price
+
+    const lat = peerLatency(c.metrics, context.medianLatency)
+    if (lat < minLatency) minLatency = lat
+    if (lat > maxLatency) maxLatency = lat
+
+    const cap = availableCapacity(c.peer)
+    if (cap > maxCap) maxCap = cap
+  }
+
+  const priceRange = maxPrice - minPrice
+  const latencyRange = maxLatency - minLatency
+
+  // --- Score each candidate ---
+  const scored: ScoredCandidate[] = []
+
+  for (const c of candidates) {
+    // Price factor (lower is better, inverted)
+    const price = c.offer.inputUsdPerMillion ?? fallbackPrice
+    const priceFactor = normalizedInverted(price, minPrice, priceRange)
+
+    // Latency factor (lower is better, inverted)
+    const lat = peerLatency(c.metrics, context.medianLatency)
+    const latencyFactor = normalizedInverted(lat, minLatency, latencyRange)
+
+    // Capacity factor (higher is better)
+    const capFactor = maxCap > 0
+      ? availableCapacity(c.peer) / maxCap
+      : 1
+
+    // Reputation factor (higher is better, normalized 0-100 to 0-1)
+    const repFactor = effectiveReputation(c.peer) / 100
+    const fresh = freshnessFactor(c.peer, context.now, context.maxPeerStalenessMs)
+    const reliability = reliabilityFactor(c.metrics, context.maxFailures)
+
+    const score =
+      w.price * priceFactor +
+      w.latency * latencyFactor +
+      w.capacity * capFactor +
+      w.reputation * repFactor +
+      w.freshness * fresh +
+      w.reliability * reliability
+
+    scored.push({
+      peer: c.peer,
+      provider: c.provider,
+      providerRank: c.providerRank,
+      offer: c.offer,
+      score,
+    })
+  }
+
+  // Sort by score descending, tie-break by latency then peerId
+  scored.sort((a, b) => {
+    if (Math.abs(a.score - b.score) < 1e-9) {
+      const aMetrics = candidates.find((c) => c.peer.peerId === a.peer.peerId)
+      const bMetrics = candidates.find((c) => c.peer.peerId === b.peer.peerId)
+      return tieBreak(a.peer, aMetrics?.metrics.latencyEma, b.peer, bMetrics?.metrics.latencyEma)
+    }
+    return b.score - a.score
+  })
+
+  return scored
+}

package/src/tool-hints.ts

@@ -0,0 +1,15 @@
+export interface ToolHint {
+  name: string
+  envVar: string
+}
+
+export const WELL_KNOWN_TOOL_HINTS: ToolHint[] = [
+  { name: 'Claude Code', envVar: 'ANTHROPIC_BASE_URL' },
+  { name: 'Aider', envVar: 'OPENAI_API_BASE' },
+  { name: 'Continue.dev', envVar: 'OPENAI_BASE_URL' },
+  { name: 'Codex', envVar: 'OPENAI_BASE_URL' },
+]
+
+export function formatToolHints(hints: ToolHint[], proxyUrl: string): string[] {
+  return hints.map(hint => `export ${hint.envVar}=${proxyUrl}   # ${hint.name}`)
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}