@danypops/jittor 0.6.0 → 0.7.0

package/src/ports/metric-store.ts

@@ -1,8 +1,38 @@
+import type { UsageAggregateRow } from "../domain/usage.ts";
 import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../domain/metric.ts";
 
+export interface DistinctScopesFilter {
+	source: string;
+	since: number;
+	until: number;
+	limit: number;
+}
+
+export interface UsageAggregateFilter {
+	source: string;
+	/** Only these scopes are summed -- callers pass the bounded result of distinctScopes, so a real explosion of distinct scopes truncates honestly instead of this method silently discovering and aggregating an unbounded set on its own. */
+	scopes: string[];
+	since: number;
+	until: number;
+	bucketSizeMs: number;
+	bucketCount: number;
+}
+
 export interface MetricStore {
 	record(observation: MetricObservation): StoredMetricObservation;
 	query(filter?: MetricQuery): StoredMetricObservation[];
+	/** Bounded distinct scope values for a source within a time window, so callers can fetch a fair share per scope instead of one flat query a single heavy scope could monopolize. */
+	distinctScopes(filter: DistinctScopesFilter): string[];
+	/**
+	 * SQL-side (scope, metric, bucket) sums for a bounded scope list -- result size scales with
+	 * (scopes x distinct metrics x buckets), never with raw event count, so a heavy scope's full
+	 * history is represented exactly regardless of how many observations fed it. Replaces fetching
+	 * up to a fixed number of raw rows per scope, which could silently truncate a single heavy
+	 * scope's own older history within the requested window (a real incident: a scope with 49,270
+	 * rows in a week had its "weekly" chart built from the 250 most recent rows alone -- 3.3
+	 * minutes of real activity mislabeled as a full week).
+	 */
+	aggregateUsage(filter: UsageAggregateFilter): UsageAggregateRow[];
 	pruneBefore(cutoff: number): number;
 	checkpoint(): void;
 	close(): void;

package/src/providers/anthropic-contracts.ts

@@ -27,6 +27,7 @@ export interface AnthropicRateLimitSnapshot {
 }
 
 function metric(
+	source: AnthropicMetricSource,
 	scope: string,
 	name: string,
 	value: number,
@@ -34,7 +35,7 @@ function metric(
 	observedAt: number,
 	attributes: Record<string, unknown> = {},
 ): MetricObservation {
-	return { source: "anthropic", scope, metric: name, value, unit, observedAt, attributes };
+	return { source, scope, metric: name, value, unit, observedAt, attributes };
 }
 
 function headerInteger(headers: Headers, name: string): number | null {
@@ -61,20 +62,30 @@ function parseWindow(headers: Headers, prefix: string): AnthropicRateLimitWindow
 	return { limit, remaining, resetsAt };
 }
 
-function windowMetrics(scope: string, window: AnthropicRateLimitWindow | null, observedAt: number): MetricObservation[] {
+function windowMetrics(source: AnthropicMetricSource, 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));
+		metrics.push(metric(source, scope, "remaining-fraction", remainingFraction, "ratio", observedAt, attributes));
+		metrics.push(metric(source, scope, "used-fraction", 1 - remainingFraction, "ratio", observedAt, attributes));
 	}
 	return metrics;
 }
 
-export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Date.now()): AnthropicRateLimitSnapshot {
+/**
+ * Direct Anthropic API calls and Anthropic-on-Vertex passthroughs (e.g. the third-party
+ * `@twogiants/pi-anthropic-vertex` extension, which reuses Pi's built-in Anthropic Messages stream
+ * with Anthropic's own `@anthropic-ai/vertex-sdk` client) may both emit this same header shape, but
+ * they are different accounts against different quota pools -- Anthropic's own org-scoped buckets
+ * vs whatever a Vertex project's passthrough exposes, if anything. Tagging the metric source keeps
+ * them from ever being blended into one budget reading.
+ */
+export type AnthropicMetricSource = "anthropic" | "anthropic-vertex";
+
+export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Date.now(), source: AnthropicMetricSource = "anthropic"): AnthropicRateLimitSnapshot {
 	const requests = parseWindow(headers, "anthropic-ratelimit-requests");
 	const tokens = parseWindow(headers, "anthropic-ratelimit-tokens");
 	const inputTokens = parseWindow(headers, "anthropic-ratelimit-input-tokens");
@@ -96,12 +107,12 @@ export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Da
 		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),
+			...windowMetrics(source, "requests", requests, observedAt),
+			...windowMetrics(source, "tokens", tokens, observedAt),
+			...windowMetrics(source, "input-tokens", inputTokens, observedAt),
+			...windowMetrics(source, "output-tokens", outputTokens, observedAt),
+			...windowMetrics(source, "priority-input-tokens", priorityInputTokens, observedAt),
+			...windowMetrics(source, "priority-output-tokens", priorityOutputTokens, observedAt),
 		],
 	};
 }

package/src/providers/google-adc-auth.ts

@@ -0,0 +1,63 @@
+import { GoogleAuth } from "google-auth-library";
+import { GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS } from "../constants.ts";
+
+/**
+ * The only file in Jittor that imports `google-auth-library` (Jittor's first runtime dependency;
+ * see docs/PROVIDER_RESEARCH.md for why ADC token acquisition -- not the Vertex/Budget API
+ * surface itself -- is the one piece worth a mature dependency instead of hand-rolling: it is
+ * security-sensitive OAuth/JWT/metadata-server protocol code, the exact class of thing the
+ * project's own off-the-shelf-modules guidance calls out as worth not reimplementing).
+ *
+ * This matches the individual-GCP-project migration's "passwordless/keyless" model: Application
+ * Default Credentials (a user's own `gcloud auth application-default login` session, a Compute/
+ * Cloud Run metadata identity, or Workload Identity Federation), never a static service-account
+ * key file. `google-auth-library` auto-detects which of those applies to the environment it runs
+ * in; Jittor does not choose or configure a credential type itself.
+ */
+export type GoogleAdcTokenProvider = () => Promise<string>;
+
+/** The minimal shape this module actually calls on an ADC client; matches google-auth-library's real `AuthClient`/`Credentials` fields (verified against its published `.d.ts`), kept narrow so tests can inject a fake without constructing a real `GoogleAuth`. */
+export interface GoogleAdcClient {
+	getAccessToken(): Promise<{ token?: string | null }>;
+	credentials?: { expiry_date?: number | null };
+}
+
+export type GoogleAdcClientFactory = (scopes: readonly string[]) => Promise<GoogleAdcClient>;
+
+async function defaultAdcClientFactory(scopes: readonly string[]): Promise<GoogleAdcClient> {
+	return new GoogleAuth({ scopes: [...scopes] }).getClient();
+}
+
+/**
+ * Wraps ADC token acquisition with the caching every other Jittor provider adapter skips
+ * only because their upstreams don't require an OAuth exchange per call: a fresh Google access
+ * token is valid for roughly an hour, and re-deriving ADC (which may itself make a metadata-server
+ * or token-exchange network call) on every poll would be wasteful and, for some ADC sources,
+ * rate-limited. `GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS` triggers a refresh slightly before Google
+ * itself would consider the cached token invalid.
+ */
+export function createGoogleAdcTokenProvider(
+	scopes: readonly string[],
+	clock: () => number = Date.now,
+	clientFactory: GoogleAdcClientFactory = defaultAdcClientFactory,
+): GoogleAdcTokenProvider {
+	let cachedClient: GoogleAdcClient | undefined;
+	let cachedToken: string | undefined;
+	let cachedExpiryEpochMs = 0;
+
+	return async function getAccessToken(): Promise<string> {
+		const now = clock();
+		if (cachedToken && now < cachedExpiryEpochMs - GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS) return cachedToken;
+		cachedClient ??= await clientFactory(scopes);
+		const { token } = await cachedClient.getAccessToken();
+		if (!token) throw new Error("Google Application Default Credentials did not return an access token");
+		// `credentials.expiry_date` is the verified google-auth-library field (epoch ms). When a
+		// credential type doesn't report one, this deliberately does not fabricate an assumed TTL --
+		// it treats the token as already due for refresh, so the next call re-fetches rather than
+		// caching for a guessed duration.
+		const expiryDate = cachedClient.credentials?.expiry_date;
+		cachedToken = token;
+		cachedExpiryEpochMs = typeof expiryDate === "number" ? expiryDate : now;
+		return token;
+	};
+}

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

@@ -86,10 +86,22 @@ export function classifyGoogleVertexFailure(value: unknown, metadata: GoogleVert
 	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): MetricObservation[] {
+export function googleVertexFailureMetrics(failure: GoogleVertexFailure, observedAt: number, source: GoogleVertexMetricSource = "google-vertex"): MetricObservation[] {
 	return [{
-		source: "google-vertex",
+		source,
 		scope: "failure",
 		metric: failure.kind,
 		value: 1,

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] : [] };
+	}
+}