@danypops/jittor 0.5.1 → 0.7.0

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

@@ -0,0 +1,181 @@
+import type { BudgetWindow } from "../policy.ts";
+import type { MetricObservation } from "../domain/metric.ts";
+import type { GoogleVertexMetricSource } from "./google-vertex-contracts.ts";
+import {
+	GOOGLE_VERTEX_BUDGET_CONFIDENCE,
+	GOOGLE_VERTEX_BUDGET_DISPLAY_NAME_MAX_CHARACTERS,
+	MILLISECONDS_PER_SECOND,
+} from "../constants.ts";
+
+/**
+ * Cloud Billing's programmatic budget notification schema (Pub/Sub attributes + base64 JSON data
+ * body), verified against
+ * https://docs.cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification-format
+ * and the worked example in
+ * https://docs.cloud.google.com/billing/docs/how-to/listen-to-notifications (fetched 2026-07-23).
+ * This is the individual-GCP-project era's real hot(ish)-path budget signal Google documents:
+ * "Budget notifications are sent to the Pub/Sub topic multiple times per day with the current
+ * status of your budget", unlike the per-response rate-limit header Vertex generateContent itself
+ * does not expose (see google-vertex-contracts.ts). Two honesty caveats the docs are explicit
+ * about and this module must not paper over: (1) "Budgets use estimated Cloud Billing data which
+ * is subject to change until your invoice is finalized" and (2) "Pub/Sub only provides
+ * at-least-once delivery. You might receive a message multiple times, and messages might arrive
+ * out of order."
+ */
+export type GoogleVertexBudgetAmountType = "SPECIFIED_AMOUNT" | "LAST_MONTH_COST" | "LAST_PERIODS_COST";
+
+export interface GoogleVertexBudgetNotification {
+	billingAccountId: string;
+	budgetId: string;
+	schemaVersion: string;
+	budgetDisplayName: string;
+	costAmount: number;
+	costIntervalStart: number;
+	budgetAmount: number;
+	budgetAmountType: GoogleVertexBudgetAmountType;
+	currencyCode: string;
+	alertThresholdExceeded?: number;
+	forecastThresholdExceeded?: number;
+	publishedAt: number;
+}
+
+const BUDGET_AMOUNT_TYPES: readonly GoogleVertexBudgetAmountType[] = ["SPECIFIED_AMOUNT", "LAST_MONTH_COST", "LAST_PERIODS_COST"];
+
+function requiredString(value: unknown, name: string, maxLength = 512): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+		throw new Error(`Google Vertex budget notification schema changed: ${name}`);
+	}
+	return value;
+}
+
+function requiredFiniteNumber(value: unknown, name: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`Google Vertex budget notification schema changed: ${name}`);
+	return value;
+}
+
+function requiredTimestamp(value: unknown, name: string): number {
+	const parsed = typeof value === "string" ? Date.parse(value) : Number.NaN;
+	if (Number.isNaN(parsed)) throw new Error(`Google Vertex budget notification schema changed: ${name} is not RFC 3339`);
+	return parsed;
+}
+
+function optionalFraction(value: unknown, name: string): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`Google Vertex budget notification schema changed: ${name}`);
+	return value;
+}
+
+/**
+ * Parses one already-base64-decoded, JSON-parsed notification body plus its Pub/Sub message
+ * attributes (`billingAccountId`, `budgetId`, `schemaVersion`) and the message's own
+ * `publishTime`. Fails closed (throws) on any missing/mistyped field, matching the
+ * `classifyGoogleVertexFailure`/Anthropic header-parsing convention: an unrecognized shape must
+ * never be silently coerced into a plausible-looking budget number.
+ */
+export function parseGoogleVertexBudgetNotification(
+	data: unknown,
+	attributes: { billingAccountId?: unknown; budgetId?: unknown; schemaVersion?: unknown },
+	publishedAt: number,
+): GoogleVertexBudgetNotification {
+	if (typeof data !== "object" || data === null || Array.isArray(data)) throw new Error("Google Vertex budget notification schema changed: data");
+	const input = data as Record<string, unknown>;
+	if (!Number.isFinite(publishedAt) || publishedAt < 0) throw new Error("Google Vertex budget notification schema changed: publishTime");
+
+	const budgetAmountType = requiredString(input["budgetAmountType"], "budgetAmountType");
+	if (!BUDGET_AMOUNT_TYPES.includes(budgetAmountType as GoogleVertexBudgetAmountType)) {
+		throw new Error("Google Vertex budget notification schema changed: budgetAmountType");
+	}
+
+	return {
+		billingAccountId: requiredString(attributes.billingAccountId, "billingAccountId"),
+		budgetId: requiredString(attributes.budgetId, "budgetId"),
+		schemaVersion: requiredString(attributes.schemaVersion, "schemaVersion"),
+		budgetDisplayName: requiredString(input["budgetDisplayName"], "budgetDisplayName", GOOGLE_VERTEX_BUDGET_DISPLAY_NAME_MAX_CHARACTERS),
+		costAmount: requiredFiniteNumber(input["costAmount"], "costAmount"),
+		costIntervalStart: requiredTimestamp(input["costIntervalStart"], "costIntervalStart"),
+		budgetAmount: requiredFiniteNumber(input["budgetAmount"], "budgetAmount"),
+		budgetAmountType: budgetAmountType as GoogleVertexBudgetAmountType,
+		currencyCode: requiredString(input["currencyCode"], "currencyCode", 8),
+		alertThresholdExceeded: optionalFraction(input["alertThresholdExceeded"], "alertThresholdExceeded"),
+		forecastThresholdExceeded: optionalFraction(input["forecastThresholdExceeded"], "forecastThresholdExceeded"),
+		publishedAt,
+	};
+}
+
+/**
+ * Real dollar figures from Google, not a fabricated fraction: `spend`/`cap` are the two numbers
+ * the notification actually carries, and `spend-fraction` is their honest quotient (which the
+ * BudgetWindow below separately clamps to 1 for policy purposes -- this raw metric intentionally
+ * is not clamped, so a genuine over-cap soft-quota period stays visible in the metrics history).
+ */
+export function googleVertexBudgetMetrics(
+	notification: GoogleVertexBudgetNotification,
+	observedAt: number,
+	source: GoogleVertexMetricSource = "google-vertex",
+): MetricObservation[] {
+	const attributes: Record<string, unknown> = {
+		billingAccountId: notification.billingAccountId,
+		budgetId: notification.budgetId,
+		budgetDisplayName: notification.budgetDisplayName,
+		budgetAmountType: notification.budgetAmountType,
+		currencyCode: notification.currencyCode,
+		...(notification.alertThresholdExceeded !== undefined ? { alertThresholdExceeded: notification.alertThresholdExceeded } : {}),
+		...(notification.forecastThresholdExceeded !== undefined ? { forecastThresholdExceeded: notification.forecastThresholdExceeded } : {}),
+	};
+	const metrics: MetricObservation[] = [
+		{ source, scope: "budget", metric: "spend", value: notification.costAmount, unit: "usd", observedAt, attributes },
+		{ source, scope: "budget", metric: "cap", value: notification.budgetAmount, unit: "usd", observedAt, attributes },
+	];
+	if (notification.budgetAmount > 0) {
+		metrics.push({ source, scope: "budget", metric: "spend-fraction", value: notification.costAmount / notification.budgetAmount, unit: "ratio", observedAt, attributes });
+	}
+	return metrics;
+}
+
+/**
+ * Cloud Billing's notification payload does not carry the budget's configured calendar period
+ * (month/quarter/year/custom); the Budget resource itself defaults to a monthly period when
+ * unset (see the Budget REST resource docs), and this is what Cloud Billing budgets default to
+ * and what the P&GE individual-project migration documents ("The $500 quota limit is a monthly
+ * limit"). Calendar periods reset "at 12 AM US and Canadian Pacific Time (UTC-8)" per Google's
+ * own documented wording -- a fixed offset, not DST-aware America/Los_Angeles -- so this mirrors
+ * that literal documented rule rather than a locale-aware guess.
+ */
+const PACIFIC_FIXED_OFFSET_MS = 8 * 60 * 60 * MILLISECONDS_PER_SECOND;
+
+function nextPacificCalendarMonthStart(epochMs: number): number {
+	const pacific = new Date(epochMs - PACIFIC_FIXED_OFFSET_MS);
+	const nextMonthStartPacific = Date.UTC(pacific.getUTCFullYear(), pacific.getUTCMonth() + 1, 1, 0, 0, 0, 0);
+	return nextMonthStartPacific + PACIFIC_FIXED_OFFSET_MS;
+}
+
+/**
+ * Builds the BudgetWindow the routing policy consumes. Returns null (no window, not a fabricated
+ * one) when `budgetAmount` isn't a usable positive cap. `usedFraction` is clamped to 1 for the
+ * policy-facing window even when real spend has exceeded a soft-quota cap (the P&GE rollout keeps
+ * serving requests past 100% during its soft-quota phase) -- clamping a known-to-be->=100% real
+ * number to the window's documented [0,1] invariant is not fabrication; the unclamped truth is
+ * still recorded by `googleVertexBudgetMetrics`'s `spend-fraction`.
+ */
+export function googleVertexBudgetWindow(
+	notification: GoogleVertexBudgetNotification,
+	observedAt: number,
+	source: GoogleVertexMetricSource = "google-vertex",
+): BudgetWindow | null {
+	if (notification.budgetAmount <= 0) return null;
+	const resetsAt = nextPacificCalendarMonthStart(notification.costIntervalStart);
+	const windowSeconds = (resetsAt - notification.costIntervalStart) / MILLISECONDS_PER_SECOND;
+	if (windowSeconds <= 0) return null;
+	const usedFraction = Math.min(1, Math.max(0, notification.costAmount / notification.budgetAmount));
+	return {
+		id: `google-vertex-budget:${notification.budgetId}@${observedAt}`,
+		source,
+		scope: `budget:${notification.budgetId}`,
+		usedFraction,
+		windowSeconds,
+		resetsAt,
+		observedAt,
+		freshness: "fresh",
+		confidence: GOOGLE_VERTEX_BUDGET_CONFIDENCE,
+	};
+}

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

@@ -0,0 +1,127 @@
+import type { BudgetWindow } from "../policy.ts";
+import type { MetricObservation } from "../domain/metric.ts";
+import {
+	googleVertexBudgetMetrics,
+	googleVertexBudgetWindow,
+	parseGoogleVertexBudgetNotification,
+	type GoogleVertexBudgetNotification,
+} from "./google-vertex-budget-contracts.ts";
+import type { GoogleVertexMetricSource } from "./google-vertex-contracts.ts";
+import type { GoogleAdcTokenProvider } from "./google-adc-auth.ts";
+import { GOOGLE_VERTEX_BUDGET_MAX_MESSAGES_PER_PULL } from "../constants.ts";
+
+export {
+	googleVertexBudgetMetrics,
+	googleVertexBudgetWindow,
+	parseGoogleVertexBudgetNotification,
+	type GoogleVertexBudgetAmountType,
+	type GoogleVertexBudgetNotification,
+} from "./google-vertex-budget-contracts.ts";
+
+const PUBSUB_BASE_URL = "https://pubsub.googleapis.com/v1";
+export const GOOGLE_PUBSUB_READONLY_SCOPE = "https://www.googleapis.com/auth/pubsub";
+
+export type GoogleVertexBudgetTransport = (request: Request) => Promise<Response>;
+
+export interface GoogleVertexBudgetSnapshot {
+	notification: GoogleVertexBudgetNotification;
+	metrics: MetricObservation[];
+	window: BudgetWindow | null;
+}
+
+interface RawPubSubMessage {
+	ackId?: unknown;
+	message?: { data?: unknown; publishTime?: unknown; attributes?: Record<string, unknown> };
+}
+
+const SUBSCRIPTION_NAME_PATTERN = /^projects\/[^/]+\/subscriptions\/[^/]+$/;
+
+/**
+ * Pulls (never pushes -- Jittor is a local loopback-only daemon with no public inbound endpoint)
+ * the individual GCP project's budget-notification Pub/Sub subscription, and turns Cloud
+ * Billing's own documented notification payload into Jittor's normalized metrics/BudgetWindow
+ * shape. One-time setup outside Jittor (create the topic, connect it to the budget, create a pull
+ * subscription) is required first -- see docs/PROVIDER_RESEARCH.md.
+ */
+export class GoogleVertexBudgetTelemetryAdapter {
+	constructor(
+		private readonly subscription: string,
+		private readonly tokenProvider: GoogleAdcTokenProvider,
+		private readonly transport: GoogleVertexBudgetTransport = fetch,
+		private readonly source: GoogleVertexMetricSource = "google-vertex",
+	) {
+		if (!SUBSCRIPTION_NAME_PATTERN.test(subscription)) {
+			throw new Error("Google Vertex budget subscription must be of the form projects/{project}/subscriptions/{subscription}");
+		}
+	}
+
+	/**
+	 * Pulls the pending notifications, acknowledges every message it received (Pub/Sub pull
+	 * subscriptions redeliver un-acked messages forever, and Cloud Billing publishes multiple
+	 * times per day regardless of whether Jittor is running -- an un-drained subscription would
+	 * grow without bound), and returns the freshest successfully-parsed notification by the
+	 * message's own `publishTime`. Throws (fail closed, matching every other Jittor provider's
+	 * schema-drift contract) if any pulled message fails to parse, after acknowledging it so a
+	 * single malformed message cannot wedge every future poll.
+	 */
+	async pull(observedAt = Date.now()): Promise<GoogleVertexBudgetSnapshot | null> {
+		const token = await this.tokenProvider();
+		const pullResponse = await this.request(":pull", token, { maxMessages: GOOGLE_VERTEX_BUDGET_MAX_MESSAGES_PER_PULL });
+		const body = await pullResponse.json() as { receivedMessages?: RawPubSubMessage[] };
+		const received = Array.isArray(body.receivedMessages) ? body.receivedMessages : [];
+		if (received.length === 0) return null;
+
+		const ackIds = received.map((entry) => entry.ackId).filter((id): id is string => typeof id === "string" && id.length > 0);
+		let parseFailure: unknown;
+		const parsed: GoogleVertexBudgetNotification[] = [];
+		for (const entry of received) {
+			try {
+				parsed.push(this.parseMessage(entry));
+			} catch (error) {
+				parseFailure = error;
+			}
+		}
+		if (ackIds.length > 0) await this.acknowledge(token, ackIds);
+		if (parseFailure) throw parseFailure;
+		if (parsed.length === 0) return null;
+
+		const freshest = parsed.reduce((latest, candidate) => candidate.publishedAt > latest.publishedAt ? candidate : latest);
+		return {
+			notification: freshest,
+			metrics: googleVertexBudgetMetrics(freshest, observedAt, this.source),
+			window: googleVertexBudgetWindow(freshest, observedAt, this.source),
+		};
+	}
+
+	private parseMessage(entry: RawPubSubMessage): GoogleVertexBudgetNotification {
+		const data = entry.message?.data;
+		if (typeof data !== "string" || data.length === 0) throw new Error("Google Vertex budget notification schema changed: message.data");
+		const publishTime = entry.message?.publishTime;
+		if (typeof publishTime !== "string") throw new Error("Google Vertex budget notification schema changed: message.publishTime");
+		const publishedAt = Date.parse(publishTime);
+		if (Number.isNaN(publishedAt)) throw new Error("Google Vertex budget notification schema changed: message.publishTime is not RFC 3339");
+		let decoded: unknown;
+		try {
+			decoded = JSON.parse(Buffer.from(data, "base64").toString("utf8"));
+		} catch {
+			throw new Error("Google Vertex budget notification schema changed: message.data is not valid base64 JSON");
+		}
+		return parseGoogleVertexBudgetNotification(decoded, entry.message?.attributes ?? {}, publishedAt);
+	}
+
+	private async acknowledge(token: string, ackIds: string[]): Promise<void> {
+		// Best-effort: a failed ack only causes redelivery after the ack deadline, which the next
+		// poll will drain again; it must never fail the poll that already extracted real metrics.
+		await this.request(":acknowledge", token, { ackIds }).catch(() => undefined);
+	}
+
+	private async request(action: ":pull" | ":acknowledge", token: string, body: Record<string, unknown>): Promise<Response> {
+		const response = await this.transport(new Request(`${PUBSUB_BASE_URL}/${this.subscription}${action}`, {
+			method: "POST",
+			headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+			body: JSON.stringify(body),
+		}));
+		if (!response.ok) throw new Error(`Google Cloud Pub/Sub ${action.slice(1)} failed with HTTP ${response.status}`);
+		return response;
+	}
+}

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

@@ -0,0 +1,116 @@
+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 };
+}
+
+/**
+ * Also reused for the third-party `anthropic-vertex` provider (Anthropic Claude models served
+ * through Google Vertex, e.g. via `@twogiants/pi-anthropic-vertex`): real-world reports show its
+ * 429s still carry GCP's own quota-exceeded message shape
+ * (`aiplatform.googleapis.com/online_prediction_requests_per_base_model`) even through Anthropic's
+ * own official Vertex SDK client, since Google's quota enforcement happens at the infra layer
+ * regardless of client wire format. `source` keeps its metrics distinguishable from Pi's native
+ * `google-vertex` provider (a different, unrelated Vertex route) and from direct Anthropic (a
+ * different account/quota pool at Anthropic's origin).
+ */
+export type GoogleVertexMetricSource = "google-vertex" | "anthropic-vertex";
+
+/** A bounded failure-count observation; never a fabricated remaining-budget fraction. */
+export function googleVertexFailureMetrics(failure: GoogleVertexFailure, observedAt: number, source: GoogleVertexMetricSource = "google-vertex"): MetricObservation[] {
+	return [{
+		source,
+		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/providers/telemetry-sources.ts

@@ -2,6 +2,9 @@ import type { BudgetWindow } from "../policy.ts";
 import type { TelemetryBatch, TelemetrySource } from "../ports/telemetry-source.ts";
 import { CodexSubscriptionTelemetryAdapter, loadCodexFileCredentials, type CodexRateLimitSnapshot, type CodexWindow, type CodexTransport } from "./codex.ts";
 import { OpenRouterTelemetryAdapter, type OpenRouterTransport } from "./openrouter.ts";
+import { GoogleVertexBudgetTelemetryAdapter, type GoogleVertexBudgetTransport } from "./google-vertex-budget.ts";
+import type { GoogleVertexMetricSource } from "./google-vertex-contracts.ts";
+import type { GoogleAdcTokenProvider } from "./google-adc-auth.ts";
 
 function budgetWindow(
 	limit: CodexRateLimitSnapshot,
@@ -67,3 +70,35 @@ export class OpenRouterTelemetrySource implements TelemetrySource {
 		return { observedAt, metrics: snapshot.metrics, windows: [] };
 	}
 }
+
+/**
+ * Optional (never `required`): the one-time GCP setup (Pub/Sub topic + pull subscription
+ * connected to the individual project's budget) lives entirely outside Jittor, so a subscription
+ * that doesn't exist yet, or a project not yet migrated onto the individual-project model, must
+ * not block every other route the way a missing required source would.
+ */
+export class GoogleVertexBudgetTelemetrySource implements TelemetrySource {
+	readonly id: string;
+	readonly provider = "google-vertex";
+	readonly required = false;
+
+	private readonly adapter: GoogleVertexBudgetTelemetryAdapter;
+
+	constructor(
+		subscription: string,
+		tokenProvider: GoogleAdcTokenProvider,
+		private readonly clock: () => number = Date.now,
+		transport: GoogleVertexBudgetTransport = fetch,
+		source: GoogleVertexMetricSource = "google-vertex",
+	) {
+		this.id = `google-vertex-budget:${source}`;
+		this.adapter = new GoogleVertexBudgetTelemetryAdapter(subscription, tokenProvider, transport, source);
+	}
+
+	async poll(): Promise<TelemetryBatch> {
+		const observedAt = this.clock();
+		const snapshot = await this.adapter.pull(observedAt);
+		if (!snapshot) return { observedAt, metrics: [], windows: [] };
+		return { observedAt, metrics: snapshot.metrics, windows: snapshot.window ? [snapshot.window] : [] };
+	}
+}

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 {