@danypops/jittor 0.5.1 → 0.6.0

package/src/domain/model-ranking.ts

@@ -0,0 +1,213 @@
+import { BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT, MAX_DYNAMIC_ROUTES, MODEL_AGGREGATE_MAX_ROWS } from "../constants.ts";
+import { normalizeModelIdentity, type BenchmarkObservation } from "./benchmark.ts";
+import { TASK_CLASSES, type ModelMetricAggregate, type ModelTaskClass } from "./model-observation.ts";
+
+export type ScopeAuthority = "exact-session" | "available-models";
+export type UtilityComponentName = "quality" | "cost" | "latency" | "context" | "reliability";
+
+export interface ModelCandidate {
+	provider: string;
+	model: string;
+	thinking: string;
+}
+
+export interface UtilityWeights {
+	quality: number;
+	cost: number;
+	latency: number;
+	context: number;
+	reliability: number;
+}
+
+export interface ModelRankingInput {
+	candidates: ModelCandidate[];
+	scopeAuthority: ScopeAuthority;
+	taskClass: ModelTaskClass;
+	budgetPressure: number;
+	weights: UtilityWeights;
+	externalEvidence: BenchmarkObservation[];
+	localEvidence: ModelMetricAggregate[];
+	now: number;
+}
+
+export interface UtilityComponent {
+	name: UtilityComponentName;
+	score: number | null;
+	confidence: number;
+	weight: number;
+	evidenceCount: number;
+	reason: string;
+}
+
+export interface RankingProvenance {
+	sourceId: string;
+	publisher: string;
+	url: string;
+	revision: string;
+	freshness: "fresh" | "stale";
+}
+
+export interface RankedModel {
+	candidate: ModelCandidate;
+	identity: string;
+	utility: number | null;
+	confidence: number;
+	components: UtilityComponent[];
+	provenance: RankingProvenance[];
+	trace: string[];
+}
+
+export interface ModelRankingResult {
+	scopeAuthority: ScopeAuthority;
+	scopeWarning: string | null;
+	taskClass: ModelTaskClass;
+	completeness: "complete" | "partial" | "insufficient-evidence";
+	ranked: RankedModel[];
+	automaticSelection: ModelCandidate | null;
+}
+
+interface RawComponent {
+	value: number | null;
+	confidence: number;
+	evidenceCount: number;
+	reason: string;
+	lowerIsBetter: boolean;
+}
+
+const COMPONENTS: UtilityComponentName[] = ["quality", "cost", "latency", "context", "reliability"];
+
+function finiteBound(value: number, name: string, minimum: number, maximum: number): number {
+	if (!Number.isFinite(value) || value < minimum || value > maximum) throw new Error(`${name} is outside its supported range`);
+	return value;
+}
+
+function candidateIdentity(candidate: ModelCandidate): string {
+	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
+	if (typeof candidate.thinking !== "string" || candidate.thinking.length === 0 || candidate.thinking.length > 160) throw new Error("candidate thinking level is invalid");
+	return `${identity.canonical}:${candidate.thinking}`;
+}
+
+function average(values: number[]): number {
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function externalValues(candidate: ModelCandidate, evidence: BenchmarkObservation[], dimensions: string[], now: number): { values: number[]; confidences: number[]; provenance: RankingProvenance[] } {
+	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
+	const matching = evidence.filter((item) => (item.model.canonical === identity.canonical || item.model.aliases.includes(identity.canonical)) && dimensions.includes(item.dimension));
+	return {
+		values: matching.map((item) => item.value),
+		confidences: matching.map((item) => item.provenance.confidence * (now <= item.provenance.freshUntil ? 1 : 0.25)),
+		provenance: matching.map((item) => ({ sourceId: item.provenance.sourceId, publisher: item.provenance.publisher, url: item.provenance.url, revision: item.provenance.revision, freshness: now <= item.provenance.freshUntil ? "fresh" : "stale" })),
+	};
+}
+
+function localValues(candidate: ModelCandidate, taskClass: ModelTaskClass, evidence: ModelMetricAggregate[], dimension: string): ModelMetricAggregate[] {
+	const identity = normalizeModelIdentity(candidate.provider, candidate.model);
+	return evidence.filter((item) => item.provider === identity.provider && item.model === identity.model && item.thinking === candidate.thinking && item.taskClass === taskClass && item.dimension === dimension);
+}
+
+function rawComponents(candidate: ModelCandidate, input: ModelRankingInput): { components: Record<UtilityComponentName, RawComponent>; provenance: RankingProvenance[] } {
+	const quality = externalValues(candidate, input.externalEvidence, [`quality-${input.taskClass}`, "quality-general"], input.now);
+	const priceInput = externalValues(candidate, input.externalEvidence, ["price-input"], input.now);
+	const priceOutput = externalValues(candidate, input.externalEvidence, ["price-output"], input.now);
+	const measuredLatency = externalValues(candidate, input.externalEvidence, ["latency"], input.now);
+	const rankedLatency = externalValues(candidate, input.externalEvidence, ["latency-rank", "throughput-rank"], input.now);
+	const latency = measuredLatency.values.length > 0 ? measuredLatency : rankedLatency;
+	const context = externalValues(candidate, input.externalEvidence, ["context-window"], input.now);
+	const localLatency = localValues(candidate, input.taskClass, input.localEvidence, "wall-latency");
+	const failures = localValues(candidate, input.taskClass, input.localEvidence, "failure");
+	const outcomes = localValues(candidate, input.taskClass, input.localEvidence, "outcome-accepted");
+	const qualityValues = quality.values;
+	const prices = [...priceInput.values, ...priceOutput.values];
+	const latencyValues = localLatency.length > 0 ? localLatency.map((item) => item.median) : latency.values;
+	const latencyConfidences = localLatency.length > 0 ? localLatency.map((item) => item.confidence) : latency.confidences;
+	const reliabilityValues = [...failures.map((item) => 1 - item.median), ...outcomes.map((item) => item.median)];
+	const withEvidence = (values: number[], confidences: number[], lowerIsBetter: boolean, label: string): RawComponent => values.length === 0
+		? { value: null, confidence: 0, evidenceCount: 0, reason: `${label} evidence is missing`, lowerIsBetter }
+		: {
+			value: average(values),
+			confidence: average(confidences) / (1 + ((Math.max(...values) - Math.min(...values)) / Math.max(Math.abs(average(values)), Number.EPSILON))),
+			evidenceCount: values.length,
+			reason: `${values.length} ${label} observation${values.length === 1 ? "" : "s"}`,
+			lowerIsBetter,
+		};
+	const components: Record<UtilityComponentName, RawComponent> = {
+		quality: withEvidence(qualityValues, quality.confidences, false, "task quality"),
+		cost: withEvidence(prices, [...priceInput.confidences, ...priceOutput.confidences], true, "price"),
+		latency: withEvidence(latencyValues, latencyConfidences, true, "latency"),
+		context: withEvidence(context.values, context.confidences, false, "context window"),
+		reliability: withEvidence(reliabilityValues, [...failures, ...outcomes].map((item) => item.confidence), false, "local reliability"),
+	};
+	return { components, provenance: [...quality.provenance, ...priceInput.provenance, ...priceOutput.provenance, ...latency.provenance, ...context.provenance] };
+}
+
+function normalizedScore(value: number, values: number[], lowerIsBetter: boolean): number {
+	const minimum = Math.min(...values);
+	const maximum = Math.max(...values);
+	if (maximum === minimum) return 0.5;
+	const score = (value - minimum) / (maximum - minimum);
+	return lowerIsBetter ? 1 - score : score;
+}
+
+export function rankModelCandidates(value: ModelRankingInput): ModelRankingResult {
+	if (!Array.isArray(value.candidates) || value.candidates.length === 0 || value.candidates.length > MAX_DYNAMIC_ROUTES) throw new Error("candidate count is outside its supported range");
+	if (!Array.isArray(value.externalEvidence) || value.externalEvidence.length > BENCHMARK_MAX_OBSERVATIONS_PER_SNAPSHOT * 4) throw new Error("external evidence exceeds the supported bound");
+	if (!Array.isArray(value.localEvidence) || value.localEvidence.length > MODEL_AGGREGATE_MAX_ROWS) throw new Error("local evidence exceeds the supported bound");
+	if (value.scopeAuthority !== "exact-session" && value.scopeAuthority !== "available-models") throw new Error("scope authority is invalid");
+	if (!TASK_CLASSES.includes(value.taskClass)) throw new Error("task class is invalid");
+	if (!Number.isSafeInteger(value.now) || value.now <= 0) throw new Error("ranking time is invalid");
+	const budgetPressure = finiteBound(value.budgetPressure, "budget pressure", 0, 2);
+	const weights = Object.fromEntries(COMPONENTS.map((name) => [name, finiteBound(value.weights[name], `${name} weight`, 0, 10)])) as unknown as UtilityWeights;
+	const seen = new Set<string>();
+	const candidates = value.candidates.map((candidate) => ({ ...candidate })).filter((candidate) => {
+		const identity = candidateIdentity(candidate);
+		if (seen.has(identity)) return false;
+		seen.add(identity);
+		return true;
+	});
+	const raw = candidates.map((candidate) => rawComponents(candidate, value));
+	const effectiveWeights: UtilityWeights = { ...weights, cost: weights.cost * (1 + budgetPressure) };
+	const ranked = candidates.map((candidate, index): RankedModel => {
+		const source = raw[index]!;
+		const components = COMPONENTS.map((name): UtilityComponent => {
+			const component = source.components[name];
+			const comparable = raw.map((item) => item.components[name].value).filter((item): item is number => item !== null);
+			return {
+				name,
+				score: component.value === null ? null : normalizedScore(component.value, comparable, component.lowerIsBetter),
+				confidence: component.confidence,
+				weight: effectiveWeights[name],
+				evidenceCount: component.evidenceCount,
+				reason: component.reason,
+			};
+		});
+		const known = components.filter((component): component is UtilityComponent & { score: number } => component.score !== null && component.weight > 0);
+		const knownWeight = known.reduce((sum, component) => sum + component.weight, 0);
+		const totalWeight = components.reduce((sum, component) => sum + component.weight, 0);
+		const utility = knownWeight === 0 ? null : known.reduce((sum, component) => sum + (component.score * component.weight), 0) / knownWeight;
+		const confidence = totalWeight === 0 ? 0 : known.reduce((sum, component) => sum + (component.confidence * component.weight), 0) / totalWeight;
+		const provenance = [...new Map(source.provenance.map((item) => [`${item.sourceId}:${item.revision}:${item.url}`, item])).values()]
+			.sort((left, right) => left.sourceId.localeCompare(right.sourceId) || left.revision.localeCompare(right.revision));
+		return {
+			candidate,
+			identity: candidateIdentity(candidate),
+			utility,
+			confidence,
+			components,
+			provenance,
+			trace: [`task class ${value.taskClass}`, `budget pressure ${budgetPressure.toFixed(3)} makes cost weight ${effectiveWeights.cost.toFixed(3)}`, `${known.length}/${components.length} utility components have evidence`, `scope authority ${value.scopeAuthority}`],
+		};
+	}).sort((left, right) => (right.utility ?? -1) - (left.utility ?? -1) || right.confidence - left.confidence || left.identity.localeCompare(right.identity));
+	const knownComponents = ranked.reduce((sum, item) => sum + item.components.filter((component) => component.score !== null).length, 0);
+	const possibleComponents = ranked.length * COMPONENTS.length;
+	const completeness = knownComponents === 0 ? "insufficient-evidence" : knownComponents === possibleComponents ? "complete" : "partial";
+	const exact = value.scopeAuthority === "exact-session";
+	return {
+		scopeAuthority: value.scopeAuthority,
+		scopeWarning: exact ? null : "Pi available models are not the exact session scope; automatic selection is disabled",
+		taskClass: value.taskClass,
+		completeness,
+		ranked,
+		automaticSelection: exact && ranked[0]?.utility !== null ? ranked[0]!.candidate : null,
+	};
+}

package/src/domain/usage.ts

@@ -6,6 +6,7 @@ export const USAGE_PERIODS = [
 	{ id: "daily", label: "Daily", windowMs: MILLISECONDS_PER_DAY, bucketCount: 24 },
 	{ id: "weekly", label: "Weekly", windowMs: 7 * MILLISECONDS_PER_DAY, bucketCount: 28 },
 	{ id: "monthly", label: "Monthly", windowMs: 30 * MILLISECONDS_PER_DAY, bucketCount: 30 },
+	{ id: "quarterly", label: "Quarterly", windowMs: 90 * MILLISECONDS_PER_DAY, bucketCount: 90 },
 ] as const;
 export type UsagePeriod = typeof USAGE_PERIODS[number]["id"];
 
@@ -63,7 +64,7 @@ export function usagePeriodStart(period: UsagePeriod, now: number): number {
 	return Math.max(0, now - usagePeriod(period).windowMs);
 }
 
-function identity(row: StoredMetricObservation): { key: string; provider: string; model: string } {
+export function identity(row: StoredMetricObservation): { key: string; provider: string; model: string } {
 	const separator = row.scope.indexOf(":");
 	const fallbackProvider = separator >= 0 ? row.scope.slice(0, separator) : row.scope;
 	const fallbackModel = separator >= 0 ? row.scope.slice(separator + 1) : "unknown";
@@ -72,18 +73,34 @@ function identity(row: StoredMetricObservation): { key: string; provider: string
 	return { key: `${provider}/${model}`, provider, model };
 }
 
-export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): UsageGraph {
+interface BucketWindow { start: number; end: number; bucketCount: number; bucketSize: number }
+
+function bucketWindow(options: UsageGraphOptions): BucketWindow {
 	const end = options.now;
 	const start = usagePeriodStart(options.period, end);
 	const requestedBuckets = options.bucketCount ?? usagePeriod(options.period).bucketCount;
 	const bucketCount = Math.max(1, Math.min(MAX_USAGE_BUCKETS, Math.floor(requestedBuckets)));
 	const bucketSize = Math.max(1, (end - start) / bucketCount);
-	const buckets: UsageBucket[] = Array.from({ length: bucketCount }, (_, index) => ({
-		start: start + index * bucketSize,
-		end: index === bucketCount - 1 ? end : start + (index + 1) * bucketSize,
+	return { start, end, bucketCount, bucketSize };
+}
+
+function emptyBuckets(window: BucketWindow): { start: number; end: number; total: number; series: Record<string, number> }[] {
+	return Array.from({ length: window.bucketCount }, (_, index) => ({
+		start: window.start + index * window.bucketSize,
+		end: index === window.bucketCount - 1 ? window.end : window.start + (index + 1) * window.bucketSize,
 		total: 0,
 		series: {},
 	}));
+}
+
+function bucketIndexFor(observedAt: number, window: BucketWindow): number {
+	return Math.min(window.bucketCount - 1, Math.floor((observedAt - window.start) / window.bucketSize));
+}
+
+export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): UsageGraph {
+	const window = bucketWindow(options);
+	const { start, end } = window;
+	const buckets: UsageBucket[] = emptyBuckets(window);
 	const breakdown: UsageBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 	const identities = new Map<string, UsageSeries>();
 
@@ -91,8 +108,7 @@ export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageG
 		const breakdownKey = BREAKDOWN_KEYS[row.metric as keyof typeof BREAKDOWN_KEYS];
 		if (row.source !== "pi" || row.unit !== "tokens" || !breakdownKey || typeof row.value !== "number" || row.value < 0) continue;
 		if (row.observedAt < start || row.observedAt > end) continue;
-		const bucketIndex = Math.min(bucketCount - 1, Math.floor((row.observedAt - start) / bucketSize));
-		const bucket = buckets[bucketIndex]!;
+		const bucket = buckets[bucketIndexFor(row.observedAt, window)]!;
 		const series = identity(row);
 		bucket.total += row.value;
 		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.value;
@@ -114,3 +130,64 @@ export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageG
 		truncated: options.truncated === true,
 	};
 }
+
+export interface CostSeries {
+	key: string;
+	provider: string;
+	model: string;
+	total: number;
+}
+
+export interface CostBucket {
+	start: number;
+	end: number;
+	total: number;
+	series: Record<string, number>;
+}
+
+export interface CostGraph {
+	period: UsagePeriod;
+	start: number;
+	end: number;
+	buckets: CostBucket[];
+	series: CostSeries[];
+	totalUsd: number;
+	truncated: boolean;
+}
+
+/**
+ * Mirrors buildUsageGraph but for the "cost" (unit "usd") metric already recorded content-free on
+ * every finalized Pi assistant message (see assistantUsageMetrics), so this needs no new
+ * instrumentation. Aggregated spend by model/time is one of the metrics LLM usage dashboards
+ * surface from day one (alongside raw token counts), since token counts alone do not reflect that
+ * output tokens and premium models cost disproportionately more per token.
+ */
+export function buildCostGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): CostGraph {
+	const window = bucketWindow(options);
+	const { start, end } = window;
+	const buckets: CostBucket[] = emptyBuckets(window);
+	const identities = new Map<string, CostSeries>();
+
+	for (const row of rows) {
+		if (row.source !== "pi" || row.unit !== "usd" || row.metric !== "cost" || typeof row.value !== "number" || row.value < 0) continue;
+		if (row.observedAt < start || row.observedAt > end) continue;
+		const bucket = buckets[bucketIndexFor(row.observedAt, window)]!;
+		const series = identity(row);
+		bucket.total += row.value;
+		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.value;
+		const current = identities.get(series.key) ?? { ...series, total: 0 };
+		current.total += row.value;
+		identities.set(series.key, current);
+	}
+
+	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
+	return {
+		period: options.period,
+		start,
+		end,
+		buckets,
+		series,
+		totalUsd: buckets.reduce((sum, bucket) => sum + bucket.total, 0),
+		truncated: options.truncated === true,
+	};
+}

package/src/ports/benchmark-controller.ts

@@ -0,0 +1,11 @@
+import type {
+	BenchmarkQuery,
+	BenchmarkQueryResult,
+	BenchmarkRefreshResult,
+} from "../domain/benchmark.ts";
+
+export interface BenchmarkController {
+	refresh(force?: boolean): Promise<BenchmarkRefreshResult>;
+	status(): BenchmarkRefreshResult;
+	query(input: BenchmarkQuery): BenchmarkQueryResult;
+}

package/src/ports/benchmark-source.ts

@@ -0,0 +1,7 @@
+import type { BenchmarkSourceSnapshot } from "../domain/benchmark.ts";
+
+/** External evidence boundary. Implementations validate one source-specific schema. */
+export interface BenchmarkSource {
+	readonly id: string;
+	fetch(): Promise<BenchmarkSourceSnapshot>;
+}

package/src/ports/benchmark-store.ts

@@ -0,0 +1,7 @@
+import type { BenchmarkObservation, BenchmarkSnapshot } from "../domain/benchmark.ts";
+
+/** Immutable evidence snapshot boundary. Only complete snapshots become visible. */
+export interface BenchmarkStore {
+	publish(sourceId: string, snapshotId: string, observations: BenchmarkObservation[]): BenchmarkSnapshot;
+	latest(sourceId: string): BenchmarkSnapshot | null;
+}

package/src/ports/router-controller.ts

@@ -39,4 +39,5 @@ export interface RouterController {
 	clearOverride(): RouterStatus;
 	setCurrentRoute(route: Route): RouterStatus;
 	setAvailableRoutes(routes: Route[]): RouterStatus;
+	applyModelRanking?(candidates: Route[]): RouterStatus;
 }

package/src/providers/anthropic-contracts.ts

@@ -0,0 +1,116 @@
+import type { MetricObservation } from "../domain/metric.ts";
+
+/**
+ * Official Anthropic Messages API rate-limit response headers, verified against
+ * https://platform.claude.com/docs/en/api/rate-limits (fetched 2026-07-21). These headers are
+ * returned on every Messages API response (per-request, not from a standalone polling endpoint —
+ * Anthropic's Admin/Rate Limits API is documented as "unavailable for individual accounts"), so
+ * Jittor observes them from Pi's own `after_provider_response` event rather than daemon-side
+ * polling. Priority Tier buckets are optional and only present for organizations enrolled in it.
+ */
+export interface AnthropicRateLimitWindow {
+	limit: number | null;
+	remaining: number | null;
+	resetsAt: number | null;
+}
+
+export interface AnthropicRateLimitSnapshot {
+	requests: AnthropicRateLimitWindow | null;
+	tokens: AnthropicRateLimitWindow | null;
+	inputTokens: AnthropicRateLimitWindow | null;
+	outputTokens: AnthropicRateLimitWindow | null;
+	priorityInputTokens: AnthropicRateLimitWindow | null;
+	priorityOutputTokens: AnthropicRateLimitWindow | null;
+	retryAfterMs: number | null;
+	observedAt: number;
+	metrics: MetricObservation[];
+}
+
+function metric(
+	scope: string,
+	name: string,
+	value: number,
+	unit: MetricObservation["unit"],
+	observedAt: number,
+	attributes: Record<string, unknown> = {},
+): MetricObservation {
+	return { source: "anthropic", scope, metric: name, value, unit, observedAt, attributes };
+}
+
+function headerInteger(headers: Headers, name: string): number | null {
+	const raw = headers.get(name);
+	if (raw === null) return null;
+	const value = Number(raw);
+	if (!Number.isFinite(value) || !Number.isSafeInteger(value) || value < 0) throw new Error(`Anthropic rate-limit header schema changed: ${name}`);
+	return value;
+}
+
+function headerResetTime(headers: Headers, name: string): number | null {
+	const raw = headers.get(name);
+	if (raw === null) return null;
+	const parsed = Date.parse(raw);
+	if (!Number.isFinite(parsed)) throw new Error(`Anthropic rate-limit header schema changed: ${name} is not RFC 3339`);
+	return parsed;
+}
+
+function parseWindow(headers: Headers, prefix: string): AnthropicRateLimitWindow | null {
+	const limit = headerInteger(headers, `${prefix}-limit`);
+	const remaining = headerInteger(headers, `${prefix}-remaining`);
+	const resetsAt = headerResetTime(headers, `${prefix}-reset`);
+	if (limit === null && remaining === null && resetsAt === null) return null;
+	return { limit, remaining, resetsAt };
+}
+
+function windowMetrics(scope: string, window: AnthropicRateLimitWindow | null, observedAt: number): MetricObservation[] {
+	if (!window) return [];
+	const metrics: MetricObservation[] = [];
+	const attributes = { limit: window.limit, remaining: window.remaining, resetsAt: window.resetsAt };
+	if (window.limit !== null && window.limit > 0 && window.remaining !== null) {
+		const remainingFraction = window.remaining / window.limit;
+		if (remainingFraction < 0 || remainingFraction > 1) throw new Error(`Anthropic ${scope} remaining exceeds its configured limit`);
+		metrics.push(metric(scope, "remaining-fraction", remainingFraction, "ratio", observedAt, attributes));
+		metrics.push(metric(scope, "used-fraction", 1 - remainingFraction, "ratio", observedAt, attributes));
+	}
+	return metrics;
+}
+
+export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Date.now()): AnthropicRateLimitSnapshot {
+	const requests = parseWindow(headers, "anthropic-ratelimit-requests");
+	const tokens = parseWindow(headers, "anthropic-ratelimit-tokens");
+	const inputTokens = parseWindow(headers, "anthropic-ratelimit-input-tokens");
+	const outputTokens = parseWindow(headers, "anthropic-ratelimit-output-tokens");
+	const priorityInputTokens = parseWindow(headers, "anthropic-priority-input-tokens");
+	const priorityOutputTokens = parseWindow(headers, "anthropic-priority-output-tokens");
+	const retryAfterRaw = headers.get("retry-after");
+	const retryAfterSeconds = retryAfterRaw === null ? null : Number(retryAfterRaw);
+	if (retryAfterRaw !== null && (!Number.isFinite(retryAfterSeconds) || (retryAfterSeconds as number) < 0)) {
+		throw new Error("Anthropic rate-limit header schema changed: retry-after");
+	}
+	return {
+		requests,
+		tokens,
+		inputTokens,
+		outputTokens,
+		priorityInputTokens,
+		priorityOutputTokens,
+		retryAfterMs: retryAfterSeconds === null ? null : Math.round(retryAfterSeconds * 1_000),
+		observedAt,
+		metrics: [
+			...windowMetrics("requests", requests, observedAt),
+			...windowMetrics("tokens", tokens, observedAt),
+			...windowMetrics("input-tokens", inputTokens, observedAt),
+			...windowMetrics("output-tokens", outputTokens, observedAt),
+			...windowMetrics("priority-input-tokens", priorityInputTokens, observedAt),
+			...windowMetrics("priority-output-tokens", priorityOutputTokens, observedAt),
+		],
+	};
+}
+
+/** True when the response carries at least one recognized Anthropic rate-limit header. */
+export function hasAnthropicRateLimitHeaders(headers: Headers): boolean {
+	for (const name of headers.keys()) {
+		const lower = name.toLowerCase();
+		if (lower.startsWith("anthropic-ratelimit-") || lower.startsWith("anthropic-priority-")) return true;
+	}
+	return false;
+}

package/src/providers/google-vertex-contracts.ts

@@ -0,0 +1,104 @@
+import type { MetricObservation } from "../domain/metric.ts";
+import { MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_SECOND } from "../constants.ts";
+
+/**
+ * Google Vertex AI has no documented per-response rate-limit or remaining-quota header, and no
+ * personal polling endpoint Jittor could daemon-poll: quota lives in AWS/GCP-style account-level
+ * Service Usage configuration, and errors surface as a `google.rpc.Status` shape
+ * (`{error: {code, message, status, details[]}}`, `status` one of the canonical gRPC codes such as
+ * `RESOURCE_EXHAUSTED`, `PERMISSION_DENIED`, `UNAVAILABLE`) rather than a header Jittor can read
+ * before a request fails (verified against Google Cloud/Gemini API error reports fetched
+ * 2026-07-21; no `x-goog-quota-*` or equivalent response header is documented for Vertex
+ * generateContent). Jittor therefore does not fabricate a remaining-budget bar for this provider.
+ * What it can honestly observe is classified failure pressure: how often and what kind of
+ * capacity/auth/request failures Pi is seeing, from the same bounded, content-free
+ * `errorMessage` string Pi already exposes for every provider (see classifyCodexFailure for the
+ * established pattern this mirrors).
+ */
+export type GoogleVertexFailureKind =
+	| "quota"
+	| "authentication"
+	| "invalid-request"
+	| "overload"
+	| "transport"
+	| "unknown";
+
+export interface GoogleVertexFailure {
+	kind: GoogleVertexFailureKind;
+	transient: boolean;
+	status?: string;
+	code?: number;
+	message?: string;
+	retryAfterMs?: number;
+}
+
+export interface GoogleVertexFailureMetadata {
+	status?: number;
+	retryAfter?: string;
+}
+
+const GOOGLE_VERTEX_ERROR_MESSAGE_LIMIT = 160;
+const GOOGLE_VERTEX_RETRY_AFTER_MAX_MS = 5 * MILLISECONDS_PER_MINUTE;
+
+function matches(value: string, patterns: readonly string[]): boolean {
+	return patterns.some((pattern) => value.includes(pattern));
+}
+
+function retryAfterMs(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const seconds = Number(value.trim().replace(/s$/i, ""));
+	if (!Number.isFinite(seconds) || seconds < 0) return undefined;
+	return Math.min(GOOGLE_VERTEX_RETRY_AFTER_MAX_MS, Math.round(seconds * MILLISECONDS_PER_SECOND));
+}
+
+/** Extracts a `google.rpc.RetryInfo.retryDelay` (e.g. `"16s"`) if the stringified error embeds one. */
+function embeddedRetryDelay(evidence: string): string | undefined {
+	const match = evidence.match(/"retrydelay"\s*:\s*"(\d+(?:\.\d+)?s)"/);
+	return match?.[1];
+}
+
+export function classifyGoogleVertexFailure(value: unknown, metadata: GoogleVertexFailureMetadata = {}): GoogleVertexFailure {
+	const rawMessage = typeof value === "string" ? value : undefined;
+	const message = rawMessage?.slice(0, GOOGLE_VERTEX_ERROR_MESSAGE_LIMIT);
+	const evidence = (rawMessage ?? "").toLowerCase();
+	const retry = retryAfterMs(metadata.retryAfter) ?? retryAfterMs(embeddedRetryDelay(evidence));
+	const base = {
+		...(message ? { message } : {}),
+		...(metadata.status !== undefined ? { code: metadata.status } : {}),
+		...(retry !== undefined ? { retryAfterMs: retry } : {}),
+	};
+
+	if (matches(evidence, ["resource_exhausted", "quota"]) || metadata.status === 429) {
+		return { kind: "quota", transient: true, status: "RESOURCE_EXHAUSTED", ...base };
+	}
+	if (matches(evidence, ["unauthenticated", "permission_denied"]) || metadata.status === 401 || metadata.status === 403) {
+		return { kind: "authentication", transient: false, status: matches(evidence, ["unauthenticated"]) ? "UNAUTHENTICATED" : "PERMISSION_DENIED", ...base };
+	}
+	if (matches(evidence, ["invalid_argument", "failed_precondition", "out_of_range"]) || metadata.status === 400 || metadata.status === 422) {
+		return { kind: "invalid-request", transient: false, status: "INVALID_ARGUMENT", ...base };
+	}
+	if (matches(evidence, ["unavailable", "internal", "aborted"]) || (metadata.status !== undefined && metadata.status >= 500 && metadata.status <= 599)) {
+		return { kind: "overload", transient: true, status: "UNAVAILABLE", ...base };
+	}
+	if (matches(evidence, ["deadline_exceeded", "timeout", "timed out", "network", "connection", "fetch failed", "cancelled"])) {
+		return { kind: "transport", transient: true, status: "DEADLINE_EXCEEDED", ...base };
+	}
+	return { kind: "unknown", transient: false, ...base };
+}
+
+/** A bounded failure-count observation; never a fabricated remaining-budget fraction. */
+export function googleVertexFailureMetrics(failure: GoogleVertexFailure, observedAt: number): MetricObservation[] {
+	return [{
+		source: "google-vertex",
+		scope: "failure",
+		metric: failure.kind,
+		value: 1,
+		unit: "count",
+		observedAt,
+		attributes: {
+			transient: failure.transient,
+			...(failure.status ? { status: failure.status } : {}),
+			...(failure.code !== undefined ? { code: failure.code } : {}),
+		},
+	}];
+}

package/src/router.ts

@@ -120,6 +120,18 @@ export class JittorRouter implements RouterController {
 		return this.status();
 	}
 
+	applyModelRanking(candidates: Route[]): RouterStatus {
+		if (!Array.isArray(candidates) || candidates.length === 0) throw new Error("model ranking must contain candidates");
+		const ranked = candidates
+			.filter((candidate, index) => candidates.findIndex((other) => sameRoute(other, candidate)) === index)
+			.map((candidate) => this.availableRoutes.find((route) => sameRoute(route, candidate)))
+			.filter((route): route is Route => route !== undefined);
+		const current = ranked.find((route) => sameRoute(route, this.currentRoute));
+		if (!current) throw new Error("model ranking does not contain the current available route");
+		this.availableRoutes = [structuredClone(current), ...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route))];
+		return this.status();
+	}
+
 	private async runPoll(): Promise<TelemetryPollResult> {
 		const statuses = await Promise.all(this.options.sources.map(async (source): Promise<TelemetrySourceStatus> => {
 			try {