jeopi-ai 16.2.13

package/src/error/oauth.ts

@@ -0,0 +1,58 @@
+import { attach, create, Flag } from "./flags";
+
+/**
+ * What stage of an OAuth / device-code login flow failed. Discriminates the
+ * single {@link OAuthError} class so login flows don't each mint a bespoke
+ * error type.
+ */
+export type OAuthErrorKind =
+	/** Token-exchange / refresh / discovery HTTP response was non-2xx or unparseable. */
+	| "http"
+	/** Response body was missing required fields (token, account id, endpoints, …). */
+	| "validation"
+	/** Authorization-code → token exchange failed. */
+	| "token-exchange"
+	/** Refresh-token grant failed. */
+	| "token-refresh"
+	/** Device-code / authorization polling failed (server error, too many retries). */
+	| "polling"
+	/** The flow exceeded its deadline (device-code expiry, polling timeout). */
+	| "timeout"
+	/** Device authorization was denied or cancelled by the user/provider. */
+	| "device-auth"
+	/** Misconfiguration (bad redirect URI, missing projectId, callback bind, …). */
+	| "configuration"
+	/** Cloud project provisioning / onboarding (loadCodeAssist, onboardUser). */
+	| "provisioning"
+	/** OIDC / endpoint discovery failed. */
+	| "discovery";
+
+export interface OAuthErrorOptions {
+	kind?: OAuthErrorKind;
+	provider?: string;
+	status?: number;
+	cause?: unknown;
+}
+
+/**
+ * A failure inside an interactive OAuth / device-code login flow. The `kind`
+ * pinpoints the stage. Timeout/polling are classified transient; everything
+ * else is a hard auth failure so the credential layer does not silently retry.
+ */
+export class OAuthError extends Error {
+	readonly kind: OAuthErrorKind;
+	readonly provider: string | undefined;
+	readonly status: number | undefined;
+
+	constructor(message: string, options: OAuthErrorOptions = {}) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "OAuthError";
+		this.kind = options.kind ?? "http";
+		this.provider = options.provider;
+		this.status = options.status;
+		attach(
+			this,
+			this.kind === "timeout" || this.kind === "polling" ? create(Flag.Transient) : create(Flag.AuthFailed),
+		);
+	}
+}

package/src/error/provider.ts

@@ -0,0 +1,62 @@
+import { ProviderHttpError } from "./classes";
+import { attach, create, Flag } from "./flags";
+
+/** Which part of a provider exchange produced a non-HTTP error. */
+export type ProviderResponseErrorKind =
+	/** Stream closed before a terminal completion/response event. */
+	| "incomplete-stream"
+	/** Terminal event carried an error / unexpected stop reason. */
+	| "output"
+	/** Response body was empty/missing when content was required. */
+	| "empty-body"
+	/** Malformed wire envelope (unexpected message ordering / shape). */
+	| "envelope"
+	/** Content was blocked by a provider safety filter. */
+	| "content-blocked"
+	/** Runtime/namespace resolution or other provider-internal failure. */
+	| "runtime";
+
+export interface ProviderResponseErrorOptions {
+	provider?: string;
+	kind?: ProviderResponseErrorKind;
+	cause?: unknown;
+}
+
+/**
+ * A non-HTTP provider failure: a truncated stream, an error stop reason, an
+ * empty body, a malformed envelope, or a runtime fault. For non-2xx HTTP
+ * responses use {@link ProviderHttpError} (or a provider subclass) instead.
+ */
+export class ProviderResponseError extends Error {
+	readonly provider: string | undefined;
+	readonly kind: ProviderResponseErrorKind;
+
+	constructor(message: string, options: ProviderResponseErrorOptions = {}) {
+		super(message, options.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ProviderResponseError";
+		this.provider = options.provider;
+		this.kind = options.kind ?? "output";
+		// A safety filter block is a terminal provider finish, not a transient fault.
+		if (this.kind === "content-blocked") attach(this, create(Flag.ProviderFinishError));
+		// An incomplete stream (connection dropped / truncated before any terminal
+		// event) never produced a finish reason — the request didn't complete, so it
+		// is safe to retry. The retry layer's replay-unsafe guard still blocks a
+		// retry when partial tool output was already emitted.
+		else if (this.kind === "incomplete-stream") attach(this, create(Flag.Transient));
+	}
+}
+
+/** Non-2xx response from the Devin API. */
+export class DevinApiError extends ProviderHttpError {
+	override readonly name = "DevinApiError";
+}
+
+/** Non-2xx response from the GitLab Duo direct-access API. */
+export class GitLabDuoApiError extends ProviderHttpError {
+	override readonly name = "GitLabDuoApiError";
+}
+
+/** Non-2xx response from the GitLab Duo Workflow API. */
+export class GitLabDuoWorkflowApiError extends ProviderHttpError {
+	override readonly name = "GitLabDuoWorkflowApiError";
+}

package/src/error/rate-limit.ts

@@ -0,0 +1,161 @@
+/**
+ * Rate limit reason classification and backoff calculation utilities.
+ * Ported from opencode-antigravity-auth plugin for consistency.
+ */
+
+export type RateLimitReason =
+	| "QUOTA_EXHAUSTED"
+	| "RATE_LIMIT_EXCEEDED"
+	| "MODEL_CAPACITY_EXHAUSTED"
+	| "SERVER_ERROR"
+	| "UNKNOWN";
+
+const QUOTA_EXHAUSTED_BACKOFF_MS = 30 * 60 * 1000; // 30 min
+const RATE_LIMIT_EXCEEDED_BACKOFF_MS = 30 * 1000; // 30s
+const MODEL_CAPACITY_BASE_MS = 45 * 1000; // 45s base
+const MODEL_CAPACITY_JITTER_MS = 30 * 1000; // ±15s
+const SERVER_ERROR_BACKOFF_MS = 20 * 1000; // 20s
+
+const ACCOUNT_RATE_LIMIT_PATTERN =
+	/\baccount(?:'s)?\b[^\n]{0,80}\brate.?limit\b|\brate.?limit\b[^\n]{0,80}\baccount\b/i;
+const INSUFFICIENT_BALANCE_PATTERN = /insufficient.?balance/i;
+
+/**
+ * Classify a rate-limit error message into a reason category.
+ * Priority order: QUOTA (Antigravity "quota will reset") > MODEL_CAPACITY > QUOTA (account) >
+ * RATE_LIMIT > QUOTA (generic) > SERVER_ERROR > UNKNOWN.
+ *
+ * "resource exhausted" maps to MODEL_CAPACITY (transient, short wait)
+ * "quota exceeded" / "quota will reset" maps to QUOTA_EXHAUSTED (long wait, switch account)
+ */
+export function parseRateLimitReason(errorMessage: string): RateLimitReason {
+	const lower = errorMessage.toLowerCase();
+
+	// Antigravity / Cloud Code Assist surface multi-hour daily-quota exhaustion as
+	// "You have exhausted your capacity on this model. Your quota will reset after …".
+	// The literal "capacity" used to pre-empt the QUOTA branch even though "quota
+	// will reset" is the long-wait signal — short-circuit here before the
+	// MODEL_CAPACITY fallthrough so credential rotation (not 60s backoff) kicks in.
+	if (lower.includes("quota will reset") || lower.includes("exhausted your capacity")) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (
+		lower.includes("capacity") ||
+		lower.includes("overloaded") ||
+		lower.includes("529") ||
+		lower.includes("503") ||
+		lower.includes("resource exhausted")
+	) {
+		return "MODEL_CAPACITY_EXHAUSTED";
+	}
+
+	if (ACCOUNT_RATE_LIMIT_PATTERN.test(errorMessage)) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (
+		lower.includes("per minute") ||
+		lower.includes("rate limit") ||
+		lower.includes("too many requests") ||
+		lower.includes("presque")
+	) {
+		return "RATE_LIMIT_EXCEEDED";
+	}
+
+	if (
+		lower.includes("exhausted") ||
+		lower.includes("quota") ||
+		lower.includes("usage limit") ||
+		INSUFFICIENT_BALANCE_PATTERN.test(errorMessage)
+	) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (lower.includes("500") || lower.includes("internal error") || lower.includes("internal server error")) {
+		return "SERVER_ERROR";
+	}
+
+	return "UNKNOWN";
+}
+
+/**
+ * Calculate backoff delay in ms for a given rate limit reason.
+ * MODEL_CAPACITY gets jitter to prevent thundering herd.
+ */
+export function calculateRateLimitBackoffMs(reason: RateLimitReason): number {
+	switch (reason) {
+		case "QUOTA_EXHAUSTED":
+			return QUOTA_EXHAUSTED_BACKOFF_MS;
+		case "RATE_LIMIT_EXCEEDED":
+			return RATE_LIMIT_EXCEEDED_BACKOFF_MS;
+		case "MODEL_CAPACITY_EXHAUSTED":
+			return MODEL_CAPACITY_BASE_MS + Math.random() * MODEL_CAPACITY_JITTER_MS;
+		case "SERVER_ERROR":
+			return SERVER_ERROR_BACKOFF_MS;
+		default:
+			return QUOTA_EXHAUSTED_BACKOFF_MS; // conservative default
+	}
+}
+
+/** Detect usage/quota limit errors in error messages (persistent, requires credential switch). */
+const USAGE_LIMIT_PATTERN =
+	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|quota.?exceeded|quota.?reached|resource.?exhausted|exhausted your capacity|quota will reset|insufficient.?(?:balance|quota)/i;
+
+/**
+ * HTTP status codes that, absent richer body classification, represent an
+ * account-local usage cap rather than a bad credential or a transient blip.
+ * Always combine with {@link isUsageLimitOutcome} when a message is available
+ * — a 429 carrying transient rate-limit wording is NOT a usage cap.
+ */
+export function isUsageLimitStatus(status: number | undefined): boolean {
+	return status === 429;
+}
+
+/**
+ * Returns true for failures that should burn one credential and rotate to a
+ * sibling account. Decision tree:
+ *
+ *  1. Body matches {@link isUsageLimitError} (Codex `usage_limit_reached`,
+ *     Anthropic account rate-limit, Google `resource_exhausted`, OpenAI
+ *     `insufficient_quota`, …) → rotate.
+ *  2. Status is not 429 → backoff (caller's domain).
+ *  3. Body is absent or {@link isOpaqueStatusBody opaque} (just the status,
+ *     empty JSON, HTTP framing only) → rotate conservatively: the server
+ *     gave us nothing else to go on.
+ *  4. Body has content → defer to {@link parseRateLimitReason}. Only
+ *     `QUOTA_EXHAUSTED` rotates; `RATE_LIMIT_EXCEEDED` (`Too many requests`,
+ *     per-minute caps), `MODEL_CAPACITY_EXHAUSTED` (`Service overloaded`),
+ *     `SERVER_ERROR`, and `UNKNOWN` (`Please retry in 5s`) stay in the
+ *     provider's own backoff layer so transient 429s don't burn sibling
+ *     credentials.
+ */
+export function isUsageLimitOutcome(status: number | undefined, message: string | undefined): boolean {
+	if (message && matchesUsageLimitText(message)) return true;
+	if (!isUsageLimitStatus(status)) return false;
+	if (!message || isOpaqueStatusBody(message)) return true;
+	return parseRateLimitReason(message) === "QUOTA_EXHAUSTED";
+}
+
+/**
+ * A 429 body is opaque when it carries no signal beyond the status itself —
+ * empty, whitespace-only, the status digits with HTTP/JSON framing, or
+ * generic punctuation. Anything else (retry hints, capacity wording, error
+ * descriptions) is informative enough to defer to the classifier.
+ */
+export function isOpaqueStatusBody(message: string): boolean {
+	const cleaned = message
+		.replace(/\b429\b/g, "")
+		.replace(/\b(?:http|https|status|error|code|response|message)\b/gi, "");
+	return !/[a-z\d]{3,}/i.test(cleaned);
+}
+
+/**
+ * Internal text matcher for usage/quota-limit phrasing. NOT part of the public
+ * API — callers classify through {@link import("./flags").isUsageLimit} (the
+ * flag accessor). `flags.ts` consumes this to populate `Flag.UsageLimit`, and
+ * {@link isUsageLimitOutcome} uses it for the account-rotation decision.
+ */
+export function matchesUsageLimitText(errorMessage: string): boolean {
+	return USAGE_LIMIT_PATTERN.test(errorMessage) || ACCOUNT_RATE_LIMIT_PATTERN.test(errorMessage);
+}

package/src/error/retryable.ts

@@ -0,0 +1,70 @@
+import { isRetryableError, isUnexpectedSocketCloseMessage } from "jeopi-utils";
+import {
+	isRetryableStreamEnvelopeError,
+	isTransientStreamParseError,
+	isUsageLimit,
+	status,
+	TRANSIENT_TRANSPORT_PATTERN,
+} from "./flags";
+
+/**
+ * Whether a numeric HTTP status is in the canonical transient/retryable set:
+ * 408 (Request Timeout), 429 (Too Many Requests), and any 5xx.
+ *
+ * This is a pure predicate over a status code already in hand — distinct from
+ * {@link classify}, which inspects a whole error (including message text) and
+ * may match more. Use this when you only have a `status: number`.
+ */
+export function isTransientStatus(status: number | undefined): boolean {
+	return status !== undefined && (status === 408 || status === 429 || status >= 500);
+}
+
+// Provider-stream transient phrasings not covered by the shared
+// TRANSIENT_TRANSPORT_PATTERN (TLS record corruption, HTTP/2 peer stream
+// errors, upstream code 1302). The shared pattern already covers rate-limit /
+// overloaded / 5xx / timeout / first-event wording.
+const PROVIDER_TRANSIENT_EXTRA_PATTERN = /bad record mac|stream error.*received from peer|1302/i;
+
+function isTransientTransportMessage(message: string): boolean {
+	return message.includes("tls: bad record mac") || message.includes("type=server_error");
+}
+
+/** Hook for provider-specific transient detection that the error module must not import directly. */
+export interface ProviderRetryableHooks {
+	/** Provider id of the failing request, used to gate provider-specific checks. */
+	provider?: string;
+	/** Provider-specific transient predicate (e.g. Copilot `model_not_supported`). */
+	isProviderTransient?: (error: Error) => boolean;
+}
+
+/**
+ * Whether a provider stream error should be retried against the same credential.
+ *
+ * Account-level usage/quota limits are deliberately treated as **non**-retryable
+ * here — they are owned by the credential-rotation layer (auth-gateway /
+ * `streamSimple` a/b/c policy), not this seconds-scale provider backoff.
+ *
+ * Provider-specific transient cases are injected via {@link ProviderRetryableHooks}
+ * so this stays free of provider imports.
+ */
+export function isProviderRetryableError(error: unknown, hooks: ProviderRetryableHooks = {}): boolean {
+	if (!(error instanceof Error)) return false;
+	if (hooks.isProviderTransient?.(error)) return true;
+	if (isUsageLimit(error)) return false;
+	const httpStatus = status(error);
+	if (httpStatus !== undefined && httpStatus >= 400 && httpStatus < 500 && httpStatus !== 408 && httpStatus !== 429) {
+		return false;
+	}
+	const msg = error.message.toLowerCase();
+	if (
+		isUnexpectedSocketCloseMessage(msg) ||
+		isTransientTransportMessage(msg) ||
+		TRANSIENT_TRANSPORT_PATTERN.test(msg) ||
+		PROVIDER_TRANSIENT_EXTRA_PATTERN.test(msg) ||
+		isTransientStreamParseError(error) ||
+		isRetryableStreamEnvelopeError(error)
+	) {
+		return true;
+	}
+	return isRetryableError(error);
+}

package/src/error/validation.ts

@@ -0,0 +1,44 @@
+import { attach, create, Flag } from "./flags";
+
+/**
+ * Caller-supplied input failed validation before/while building a provider
+ * request: bad request body, malformed tool arguments, unsupported content
+ * type, a schema that cannot be normalized, an unknown tool, etc.
+ *
+ * This is a programmer/config/contract error, not a transient provider fault —
+ * it is never retried.
+ */
+export class ValidationError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ValidationError";
+	}
+}
+
+/** A referenced tool was not found in the active tool set. */
+export class ToolNotFoundError extends ValidationError {
+	constructor(toolName: string) {
+		super(`Tool "${toolName}" not found`);
+		this.name = "ToolNotFoundError";
+	}
+}
+
+/**
+ * Provider/auth configuration was missing or malformed (env var pointing at a
+ * missing file, missing projectId, bad bind string, mTLS half-configured, …).
+ */
+export class ConfigurationError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "ConfigurationError";
+	}
+}
+
+/** A request was abandoned because it exceeded a stream/idle/first-event deadline. */
+export class StreamTimeoutError extends Error {
+	constructor(message = "Request timed out.", options?: { cause?: unknown }) {
+		super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+		this.name = "StreamTimeoutError";
+		attach(this, create(Flag.Transient, Flag.Timeout));
+	}
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export { type Type, type } from "arktype";
+export { type ZodType, z } from "zod/v4";
+export * from "./api-registry";
+export type * from "./auth-broker";
+export type { AuthGatewayBootOptions, ModelResolver } from "./auth-gateway/server";
+export * from "./auth-gateway/types";
+export * from "./auth-retry";
+export * from "./auth-storage";
+export * from "./error/rate-limit";
+export * from "./provider-details";
+export * from "./providers/anthropic";
+export * from "./providers/anthropic-client";
+export * from "./providers/azure-openai-responses";
+export type * from "./providers/cursor";
+export * from "./providers/gitlab-duo";
+export * from "./providers/gitlab-duo-workflow";
+export type * from "./providers/google";
+export type * from "./providers/google-gemini-cli";
+export type * from "./providers/google-vertex";
+export * from "./providers/kimi";
+export * from "./providers/mock";
+export * from "./providers/ollama";
+export * from "./providers/openai-codex-responses";
+export * from "./providers/openai-completions";
+export * from "./providers/openai-responses";
+export * from "./providers/synthetic";
+export * from "./registry";
+export * from "./stream";
+export * from "./types";
+export * from "./usage";
+export * from "./usage/claude";
+export * from "./usage/gemini";
+export * from "./usage/github-copilot";
+export * from "./usage/google-antigravity";
+export * from "./usage/kimi";
+export * from "./usage/minimax-code";
+export * from "./usage/ollama";
+export * from "./usage/openai-codex";
+export * from "./usage/openai-codex-reset";
+export * from "./usage/opencode-go";
+export * from "./usage/zai";
+export * from "./utils/anthropic-auth";
+export * from "./utils/event-stream";
+export * from "./utils/openrouter-headers";
+export * from "./utils/retry";
+export * from "./utils/schema";
+export * from "./utils/thinking-loop";
+export * from "./utils/tool-call-loop-guard";
+export * from "./utils/validation";

package/src/provider-details.ts

@@ -0,0 +1,90 @@
+import { getOpenAICodexTransportDetails, type OpenAICodexTransportDetails } from "./providers/openai-codex-responses";
+import type { Api, Model, Provider, ProviderSessionState } from "./types";
+
+export interface ProviderDetailField {
+	label: string;
+	value: string;
+}
+
+export interface ProviderDetails {
+	provider: Provider;
+	api: Api;
+	fields: ProviderDetailField[];
+}
+
+export interface ProviderDetailsContext {
+	model: Model<Api>;
+	sessionId?: string;
+	authMode?: string;
+	/**
+	 * Human-readable description of the active credential, e.g.
+	 * `"broker http://omp.internal:8765 · oauth #5 (foo@bar.com)"`.
+	 * Rendered as a `Source` field; omitted when undefined.
+	 */
+	credentialSource?: string;
+	preferWebsockets?: boolean;
+	providerSessionState?: Map<string, ProviderSessionState>;
+}
+
+export function getProviderDetails(context: ProviderDetailsContext): ProviderDetails {
+	const endpoint = formatEndpoint(context.model.baseUrl);
+	const fields: ProviderDetailField[] = [
+		{ label: "Model", value: context.model.id },
+		{ label: "API", value: context.model.api },
+		{ label: "Auth", value: context.authMode ?? "auto" },
+		{ label: "Endpoint", value: endpoint },
+	];
+	if (context.credentialSource) {
+		fields.push({ label: "Source", value: context.credentialSource });
+	}
+
+	if (context.model.api === "openai-codex-responses") {
+		const codexDetails = getOpenAICodexTransportDetails(context.model as Model<"openai-codex-responses">, {
+			sessionId: context.sessionId,
+			baseUrl: context.model.baseUrl,
+			preferWebsockets: context.preferWebsockets,
+			providerSessionState: context.providerSessionState,
+		});
+		fields.push({ label: "Transport", value: formatCodexTransport(codexDetails) });
+		fields.push({ label: "WebSocket", value: formatCodexWebSocket(codexDetails) });
+		fields.push({ label: "Reuse", value: formatCodexReuse(codexDetails, context.sessionId) });
+	}
+
+	return {
+		provider: context.model.provider,
+		api: context.model.api,
+		fields,
+	};
+}
+
+function formatEndpoint(baseUrl: string): string {
+	try {
+		const parsed = new URL(baseUrl);
+		const path = parsed.pathname.replace(/\/$/, "");
+		return `${parsed.origin}${path || "/"}`;
+	} catch {
+		return baseUrl;
+	}
+}
+
+function formatCodexTransport(details: OpenAICodexTransportDetails): string {
+	if (details.lastTransport === "websocket") return "websocket";
+	if (details.lastTransport === "sse" && (details.websocketDisabled || details.fallbackCount > 0)) {
+		return "sse (fallback)";
+	}
+	if (details.lastTransport === "sse") return "sse";
+	return details.websocketPreferred ? "websocket preferred" : "sse";
+}
+
+function formatCodexWebSocket(details: OpenAICodexTransportDetails): string {
+	if (!details.websocketPreferred) return "off";
+	if (details.websocketDisabled) return "disabled after fallback";
+	if (details.websocketConnected) return "connected";
+	if (details.prewarmed) return "prewarmed";
+	return details.hasSessionState ? "enabled" : "waiting for first request";
+}
+
+function formatCodexReuse(details: OpenAICodexTransportDetails, sessionId: string | undefined): string {
+	if (!sessionId) return "no session key";
+	return details.canAppend ? "append enabled" : "full request";
+}

package/src/providers/__tests__/google-auth.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { Buffer } from "node:buffer";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { FetchImpl } from "../../types";
+import { __resetVertexTokenCache, getVertexAccessToken } from "../google-auth";
+
+const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+
+/** Generate a real RS256 private key so signJwtRs256 / pemToPkcs8 run for real. */
+async function generateServiceAccountPem(): Promise<string> {
+	const keyPair = (await globalThis.crypto.subtle.generateKey(
+		{ name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" },
+		true,
+		["sign", "verify"],
+	)) as CryptoKeyPair;
+	const pkcs8 = new Uint8Array(await globalThis.crypto.subtle.exportKey("pkcs8", keyPair.privateKey));
+	const body = (
+		Buffer.from(pkcs8)
+			.toString("base64")
+			.match(/.{1,64}/g) ?? []
+	).join("\n");
+	return `-----BEGIN PRIVATE KEY-----\n${body}\n-----END PRIVATE KEY-----\n`;
+}
+
+function urlOf(input: string | URL | Request): string {
+	if (typeof input === "string") return input;
+	if (input instanceof URL) return input.toString();
+	return input.url;
+}
+
+describe("getVertexAccessToken impersonated_service_account ADC", () => {
+	let tmpDir: string;
+	let originalGac: string | undefined;
+
+	beforeEach(async () => {
+		__resetVertexTokenCache();
+		originalGac = Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+		tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-vertex-adc-"));
+	});
+
+	afterEach(async () => {
+		__resetVertexTokenCache();
+		if (originalGac === undefined) delete Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+		else Bun.env.GOOGLE_APPLICATION_CREDENTIALS = originalGac;
+		await fs.rm(tmpDir, { recursive: true, force: true });
+	});
+
+	it("rejects a malformed service_account_impersonation_url before any network call", async () => {
+		const adcPath = path.join(tmpDir, "impersonated-bad-url.json");
+		await Bun.write(
+			adcPath,
+			JSON.stringify({
+				type: "impersonated_service_account",
+				// Missing the trailing ":generateAccessToken" the principal parser requires.
+				service_account_impersonation_url:
+					"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com",
+				source_credentials: {
+					type: "authorized_user",
+					client_id: "client-id",
+					client_secret: "client-secret",
+					refresh_token: "refresh-token",
+				},
+			}),
+		);
+		Bun.env.GOOGLE_APPLICATION_CREDENTIALS = adcPath;
+
+		const calls: string[] = [];
+		const fetchImpl: FetchImpl = async input => {
+			calls.push(urlOf(input));
+			return new Response("{}");
+		};
+
+		// The principal is parsed before the source exchange, so a bad URL must fail
+		// up front rather than after burning a source-token round trip.
+		await expect(getVertexAccessToken({ fetch: fetchImpl })).rejects.toBeInstanceOf(RangeError);
+		expect(calls).toEqual([]);
+	});
+
+	it("signs an RS256 JWT for a service_account source and reconstructs the IAM URL", async () => {
+		const pem = await generateServiceAccountPem();
+		const adcPath = path.join(tmpDir, "impersonated-sa.json");
+		await Bun.write(
+			adcPath,
+			JSON.stringify({
+				type: "impersonated_service_account",
+				// Non-canonical project segment proves the request URL is rebuilt, not echoed.
+				service_account_impersonation_url:
+					"https://iamcredentials.googleapis.com/v1/projects/explicit-proj/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+				source_credentials: {
+					type: "service_account",
+					client_email: "source@project.iam.gserviceaccount.com",
+					private_key: pem,
+					private_key_id: "key-1",
+				},
+				// delegates intentionally omitted — the IAM body must default to [].
+			}),
+		);
+		Bun.env.GOOGLE_APPLICATION_CREDENTIALS = adcPath;
+
+		const calls: { url: string; init?: RequestInit }[] = [];
+		const fetchImpl: FetchImpl = async (input, init) => {
+			const url = urlOf(input);
+			calls.push({ url, init });
+			if (url === "https://oauth2.googleapis.com/token") {
+				return new Response(JSON.stringify({ access_token: "sa-source-token", expires_in: 3600 }));
+			}
+			if (url.startsWith("https://iamcredentials.googleapis.com/")) {
+				return new Response(
+					JSON.stringify({
+						accessToken: "impersonated-token",
+						expireTime: new Date(Date.now() + 3_600_000).toISOString(),
+					}),
+				);
+			}
+			return new Response("unexpected", { status: 404 });
+		};
+
+		const token = await getVertexAccessToken({ fetch: fetchImpl });
+		expect(token).toBe("impersonated-token");
+
+		// Source JWT exchange happens first, then the impersonation exchange.
+		expect(calls.map(c => c.url)).toEqual([
+			"https://oauth2.googleapis.com/token",
+			"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+		]);
+
+		// Source credential is exchanged via a signed JWT bearer assertion, not a refresh grant.
+		const sourceBody = new URLSearchParams(String(calls[0].init?.body));
+		expect(sourceBody.get("grant_type")).toBe(JWT_BEARER_GRANT);
+		expect((sourceBody.get("assertion") ?? "").split(".")).toHaveLength(3);
+
+		// The IAM call carries the source-derived bearer token and defaults delegates to [].
+		const iamHeaders = calls[1].init?.headers as Record<string, string>;
+		expect(iamHeaders.Authorization).toBe("Bearer sa-source-token");
+		expect(JSON.parse(String(calls[1].init?.body))).toEqual({
+			delegates: [],
+			scope: [CLOUD_PLATFORM_SCOPE],
+			lifetime: "3600s",
+		});
+	});
+});