@vib-rato/ai 0.16.0

package/src/providers/gitlab-duo.ts

@@ -0,0 +1,393 @@
+import { copyProviderSafetyStopAdapterInvocation } from "../adapter-internals/provider-safety-stop";
+import { ANTHROPIC_THINKING, mapAnthropicToolChoice } from "../stream";
+import type { Api, Context, FetchImpl, Model, SimpleStreamOptions } from "../types";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { createProviderErrorMessage } from "./error-message";
+import type { OpenAICompletionsOptions } from "./openai-completions";
+import type { OpenAIResponsesOptions } from "./openai-responses";
+import { streamAnthropic, streamOpenAICompletions, streamOpenAIResponses } from "./register-builtins";
+
+const GITLAB_COM_URL = "https://gitlab.com";
+const AI_GATEWAY_URL = "https://cloud.gitlab.com";
+const ANTHROPIC_PROXY_URL = `${AI_GATEWAY_URL}/ai/v1/proxy/anthropic/`;
+const OPENAI_PROXY_URL = `${AI_GATEWAY_URL}/ai/v1/proxy/openai/v1`;
+const DIRECT_ACCESS_TTL_MS = 25 * 60 * 1000;
+
+type GitLabProvider = "anthropic" | "openai";
+type GitLabOpenAIApiType = "chat" | "responses";
+
+export type GitLabModelMapping = {
+	provider: GitLabProvider;
+	model: string;
+	openaiApiType?: GitLabOpenAIApiType;
+	name: string;
+	reasoning: boolean;
+	input: ("text" | "image")[];
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow: number;
+	maxTokens: number;
+};
+
+export const MODEL_MAPPINGS: Record<string, GitLabModelMapping> = {
+	"duo-chat-opus-4-6": {
+		provider: "anthropic",
+		model: "claude-opus-4-6",
+		name: "Duo Chat Opus 4.6",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200000,
+		maxTokens: 64000,
+	},
+	"duo-chat-sonnet-4-6": {
+		provider: "anthropic",
+		model: "claude-sonnet-4-6",
+		name: "Duo Chat Sonnet 4.6",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200000,
+		maxTokens: 64000,
+	},
+	"duo-chat-opus-4-5": {
+		provider: "anthropic",
+		model: "claude-opus-4-5-20251101",
+		name: "Duo Chat Opus 4.5",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+		contextWindow: 200000,
+		maxTokens: 64000,
+	},
+	"duo-chat-sonnet-4-5": {
+		provider: "anthropic",
+		model: "claude-sonnet-4-5-20250929",
+		name: "Duo Chat Sonnet 4.5",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+		contextWindow: 200000,
+		maxTokens: 64000,
+	},
+	"duo-chat-haiku-4-5": {
+		provider: "anthropic",
+		model: "claude-haiku-4-5-20251001",
+		name: "Duo Chat Haiku 4.5",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+		contextWindow: 200000,
+		maxTokens: 64000,
+	},
+	"duo-chat-gpt-5-1": {
+		provider: "openai",
+		model: "gpt-5.1-2025-11-13",
+		openaiApiType: "chat",
+		name: "Duo Chat GPT-5.1",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	},
+	"duo-chat-gpt-5-2": {
+		provider: "openai",
+		model: "gpt-5.2-2025-12-11",
+		openaiApiType: "chat",
+		name: "Duo Chat GPT-5.2",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	},
+	"duo-chat-gpt-5-mini": {
+		provider: "openai",
+		model: "gpt-5-mini-2025-08-07",
+		openaiApiType: "chat",
+		name: "Duo Chat GPT-5 Mini",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 0.15, output: 0.6, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	},
+	"duo-chat-gpt-5-codex": {
+		provider: "openai",
+		model: "gpt-5-codex",
+		openaiApiType: "responses",
+		name: "Duo Chat GPT-5 Codex",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 272000,
+		maxTokens: 128000,
+	},
+	"duo-chat-gpt-5-2-codex": {
+		provider: "openai",
+		model: "gpt-5.2-codex",
+		openaiApiType: "responses",
+		name: "Duo Chat GPT-5.2 Codex",
+		reasoning: true,
+		input: ["text", "image"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 272000,
+		maxTokens: 128000,
+	},
+};
+
+export function getModelMapping(modelId: string): GitLabModelMapping | undefined {
+	const direct = MODEL_MAPPINGS[modelId];
+	if (direct) return direct;
+
+	// Support canonical model IDs (e.g. "gpt-5-OpenAI code backend", "Anthropic model-sonnet-4-5-20250929")
+	// in addition to Duo aliases (e.g. "duo-chat-gpt-5-OpenAI code backend").
+	return Object.values(MODEL_MAPPINGS).find(mapping => mapping.model === modelId);
+}
+
+export function getGitLabDuoModels(): Model<Api>[] {
+	return Object.entries(MODEL_MAPPINGS).map(([id, mapping]) => ({
+		id,
+		name: mapping.name,
+		api:
+			mapping.provider === "anthropic"
+				? "anthropic-messages"
+				: mapping.openaiApiType === "responses"
+					? "openai-responses"
+					: "openai-completions",
+		provider: "gitlab-duo",
+		baseUrl: mapping.provider === "anthropic" ? ANTHROPIC_PROXY_URL : OPENAI_PROXY_URL,
+		reasoning: mapping.reasoning,
+		input: [...mapping.input],
+		cost: { ...mapping.cost },
+		contextWindow: mapping.contextWindow,
+		maxTokens: mapping.maxTokens,
+	}));
+}
+
+interface DirectAccessToken {
+	token: string;
+	headers: Record<string, string>;
+	expiresAt: number;
+}
+
+const directAccessCache = new Map<string, DirectAccessToken>();
+
+async function getDirectAccessToken(
+	gitlabAccessToken: string,
+	fetchImpl: FetchImpl = fetch,
+	onStreamCreated?: () => void,
+): Promise<DirectAccessToken> {
+	const cached = directAccessCache.get(gitlabAccessToken);
+	if (cached && cached.expiresAt > Date.now()) {
+		return cached;
+	}
+
+	onStreamCreated?.();
+	const response = await fetchImpl(`${GITLAB_COM_URL}/api/v4/ai/third_party_agents/direct_access`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${gitlabAccessToken}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({
+			feature_flags: { DuoAgentPlatformNext: true },
+		}),
+	});
+
+	if (!response.ok) {
+		const detail = await response.text();
+		if (response.status === 403) {
+			throw new Error(`GitLab Duo access denied. Ensure Duo is enabled for this account. ${detail}`);
+		}
+		throw new Error(`Failed to get GitLab Duo direct access token: ${response.status} ${detail}`);
+	}
+
+	const payload = (await response.json()) as { token?: string; headers?: Record<string, string> };
+	if (!payload.token || typeof payload.token !== "string") {
+		throw new Error("GitLab Duo direct access response missing token");
+	}
+	if (!payload.headers || typeof payload.headers !== "object") {
+		throw new Error("GitLab Duo direct access response missing headers");
+	}
+
+	const token: DirectAccessToken = {
+		token: payload.token,
+		headers: payload.headers,
+		expiresAt: Date.now() + DIRECT_ACCESS_TTL_MS,
+	};
+	directAccessCache.set(gitlabAccessToken, token);
+	return token;
+}
+
+export function clearGitLabDuoDirectAccessCache(): void {
+	directAccessCache.clear();
+}
+
+export function isGitLabDuoModel(model: Model<Api>): boolean {
+	return model.provider === "gitlab-duo";
+}
+
+export function streamGitLabDuo(
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const stream = new AssistantMessageEventStream();
+
+	(async () => {
+		try {
+			if (!options?.apiKey) {
+				throw new Error("Missing GitLab access token. Run /login gitlab-duo or set GITLAB_TOKEN.");
+			}
+
+			const mapping = getModelMapping(model.id);
+			if (!mapping) {
+				throw new Error(`Unsupported GitLab Duo model: ${model.id}`);
+			}
+
+			const directAccess = await getDirectAccessToken(options.apiKey, options.fetch, options.onStreamCreated);
+			const headers = {
+				...directAccess.headers,
+				...options.headers,
+			};
+
+			const reasoningEffort = options.reasoning;
+
+			const inner =
+				mapping.provider === "anthropic"
+					? streamAnthropic(
+							{
+								...model,
+								id: mapping.model,
+								api: "anthropic-messages",
+								baseUrl: ANTHROPIC_PROXY_URL,
+							} as Model<"anthropic-messages">,
+							context,
+							copyProviderSafetyStopAdapterInvocation(options, {
+								apiKey: directAccess.token,
+								isOAuth: true,
+								temperature: options.temperature,
+								topP: options.topP,
+								topK: options.topK,
+								minP: options.minP,
+								presencePenalty: options.presencePenalty,
+								repetitionPenalty: options.repetitionPenalty,
+								maxTokens: options.maxTokens ?? Math.min(model.maxTokens, 32000),
+								signal: options.signal,
+								cacheRetention: options.cacheRetention,
+								headers,
+								maxRetryDelayMs: options.maxRetryDelayMs,
+								requestMaxRetries: options.requestMaxRetries,
+								streamMaxRetries: options.streamMaxRetries,
+								fallbackManaged: options.fallbackManaged,
+								disableProviderRetries: options.disableProviderRetries,
+								metadata: options.metadata,
+								sessionId: options.sessionId,
+								providerSessionState: options.providerSessionState,
+								onPayload: options.onPayload,
+								onStreamCreated: options.onStreamCreated,
+								attemptScope: options?.attemptScope,
+								onResponse: options.onResponse,
+								onSseEvent: options.onSseEvent,
+								fetch: options.fetch,
+								thinkingEnabled: Boolean(reasoningEffort) && model.reasoning,
+								thinkingBudgetTokens: reasoningEffort
+									? (options.thinkingBudgets?.[reasoningEffort] ?? ANTHROPIC_THINKING[reasoningEffort])
+									: undefined,
+								reasoning: reasoningEffort,
+								toolChoice: mapAnthropicToolChoice(options.toolChoice),
+							}),
+						)
+					: mapping.openaiApiType === "responses"
+						? streamOpenAIResponses(
+								{
+									...model,
+									id: mapping.model,
+									api: "openai-responses",
+									baseUrl: OPENAI_PROXY_URL,
+								} as Model<"openai-responses">,
+								context,
+								copyProviderSafetyStopAdapterInvocation(options, {
+									apiKey: directAccess.token,
+									temperature: options.temperature,
+									topP: options.topP,
+									topK: options.topK,
+									minP: options.minP,
+									presencePenalty: options.presencePenalty,
+									repetitionPenalty: options.repetitionPenalty,
+									maxTokens: options.maxTokens ?? model.maxTokens,
+									signal: options.signal,
+									cacheRetention: options.cacheRetention,
+									headers,
+									maxRetryDelayMs: options.maxRetryDelayMs,
+									requestMaxRetries: options.requestMaxRetries,
+									streamMaxRetries: options.streamMaxRetries,
+									fallbackManaged: options.fallbackManaged,
+									disableProviderRetries: options.disableProviderRetries,
+									metadata: options.metadata,
+									sessionId: options.sessionId,
+									providerSessionState: options.providerSessionState,
+									onPayload: options.onPayload,
+									onStreamCreated: options.onStreamCreated,
+									attemptScope: options?.attemptScope,
+									onResponse: options.onResponse,
+									onSseEvent: options.onSseEvent,
+									fetch: options.fetch,
+									reasoning: reasoningEffort,
+									toolChoice: options.toolChoice,
+								}) satisfies OpenAIResponsesOptions,
+							)
+						: streamOpenAICompletions(
+								{
+									...model,
+									id: mapping.model,
+									api: "openai-completions",
+									baseUrl: OPENAI_PROXY_URL,
+								} as Model<"openai-completions">,
+								context,
+								copyProviderSafetyStopAdapterInvocation(options, {
+									apiKey: directAccess.token,
+									temperature: options.temperature,
+									topP: options.topP,
+									topK: options.topK,
+									minP: options.minP,
+									presencePenalty: options.presencePenalty,
+									repetitionPenalty: options.repetitionPenalty,
+									maxTokens: options.maxTokens ?? model.maxTokens,
+									signal: options.signal,
+									cacheRetention: options.cacheRetention,
+									headers,
+									maxRetryDelayMs: options.maxRetryDelayMs,
+									requestMaxRetries: options.requestMaxRetries,
+									streamMaxRetries: options.streamMaxRetries,
+									fallbackManaged: options.fallbackManaged,
+									disableProviderRetries: options.disableProviderRetries,
+									metadata: options.metadata,
+									sessionId: options.sessionId,
+									providerSessionState: options.providerSessionState,
+									onPayload: options.onPayload,
+									onStreamCreated: options.onStreamCreated,
+									attemptScope: options?.attemptScope,
+									onResponse: options.onResponse,
+									onSseEvent: options.onSseEvent,
+									fetch: options.fetch,
+									reasoning: reasoningEffort,
+									toolChoice: options.toolChoice,
+								}) satisfies OpenAICompletionsOptions,
+							);
+
+			for await (const event of inner) {
+				stream.push(event);
+			}
+		} catch (err) {
+			stream.push({
+				type: "error",
+				reason: "error",
+				error: createProviderErrorMessage(model, err),
+			});
+		}
+	})();
+
+	return stream;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Application Default Credentials (ADC) resolution for Vertex AI.
+ *
+ * Replaces `google-auth-library` with a direct WebCrypto + REST implementation.
+ * Sources, in priority order:
+ *   1. `GOOGLE_APPLICATION_CREDENTIALS` env → file with `type: "service_account"` (RS256 JWT exchange)
+ *     or `type: "authorized_user"` (refresh-token exchange).
+ *   2. `~/.config/gcloud/application_default_credentials.json` (user ADC, same authorized_user flow).
+ *   3. GCE / Cloud Run metadata server (`metadata.google.internal`).
+ *
+ * Tokens are cached per source key and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` before expiry
+ * (default 60s). Concurrent callers waiting on a refresh share the same in-flight promise.
+ */
+import type { FetchImpl } from "../types";
+/** Test seam: the ADC credentials file path as resolved from trusted env. */
+export declare function resolveAdcCredentialsPathForTest(): string | undefined;
+/**
+ * Returns a Bearer access token suitable for the `Authorization` header on Vertex AI calls.
+ * The token is cached in module scope and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` ms before it expires.
+ */
+export declare function getVertexAccessToken(options?: {
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}): Promise<string>;
+/** Test seam: clears every cached token. */
+export declare function __resetVertexTokenCache(): void;

package/src/providers/google-auth.ts

@@ -0,0 +1,262 @@
+/**
+ * Application Default Credentials (ADC) resolution for Vertex AI.
+ *
+ * Replaces `google-auth-library` with a direct WebCrypto + REST implementation.
+ * Sources, in priority order:
+ *   1. `GOOGLE_APPLICATION_CREDENTIALS` env → file with `type: "service_account"` (RS256 JWT exchange)
+ *     or `type: "authorized_user"` (refresh-token exchange).
+ *   2. `~/.config/gcloud/application_default_credentials.json` (user ADC, same authorized_user flow).
+ *   3. GCE / Cloud Run metadata server (`metadata.google.internal`).
+ *
+ * Tokens are cached per source key and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` before expiry
+ * (default 60s). Concurrent callers waiting on a refresh share the same in-flight promise.
+ */
+
+import { Buffer } from "node:buffer";
+import * as path from "node:path";
+import { $credentialEnv, $envpos, getTrustedHomeDir, isEnoent, logger } from "@vib-rato/utils";
+import type { FetchImpl } from "../types";
+
+const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const METADATA_TOKEN_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token";
+const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+
+interface CachedToken {
+	token: string;
+	expiresAtMs: number;
+}
+
+interface ServiceAccountCredentials {
+	type: "service_account";
+	client_email: string;
+	private_key: string;
+	private_key_id?: string;
+}
+
+interface AuthorizedUserCredentials {
+	type: "authorized_user";
+	client_id: string;
+	client_secret: string;
+	refresh_token: string;
+}
+
+type AdcFileCredentials = ServiceAccountCredentials | AuthorizedUserCredentials;
+
+interface TokenResponse {
+	access_token: string;
+	expires_in: number;
+	token_type?: string;
+}
+
+const tokenCache = new Map<string, CachedToken>();
+const inflight = new Map<string, Promise<string>>();
+
+function getRefreshSkewMs(): number {
+	return $envpos("GOOGLE_VERTEX_REFRESH_SKEW_MS", 60_000);
+}
+
+function userAdcPath(): string {
+	return path.join(getTrustedHomeDir(), ".config", "gcloud", "application_default_credentials.json");
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T | undefined> {
+	try {
+		return (await Bun.file(filePath).json()) as T;
+	} catch (err) {
+		if (isEnoent(err)) return undefined;
+		throw err;
+	}
+}
+
+/** Test seam: the ADC credentials file path as resolved from trusted env. */
+export function resolveAdcCredentialsPathForTest(): string | undefined {
+	return $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
+}
+
+async function loadAdcCredentials(): Promise<{ source: string; creds: AdcFileCredentials } | undefined> {
+	// Trusted sources only: this path is read as service-account / authorized-user
+	// credentials and exchanged for a Google access token, so whatever can set it
+	// chooses the identity the agent authenticates as. `Bun.env` is `process.env`
+	// and the env module merges the caller's `cwd/.env` into it, so reading it
+	// there would let repository content point this at a key file it ships.
+	// `stream.ts` already resolves the same variable through `$credentialEnv`.
+	const gacPath = $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
+	if (gacPath) {
+		const creds = await readJsonFile<AdcFileCredentials>(gacPath);
+		if (!creds) {
+			throw new Error(`GOOGLE_APPLICATION_CREDENTIALS points to a missing file: ${gacPath}`);
+		}
+		return { source: `gac:${gacPath}`, creds };
+	}
+	const userPath = userAdcPath();
+	const creds = await readJsonFile<AdcFileCredentials>(userPath);
+	if (creds) return { source: `user:${userPath}`, creds };
+	return undefined;
+}
+
+function base64UrlEncode(bytes: Uint8Array | string): string {
+	const buf = typeof bytes === "string" ? Buffer.from(bytes, "utf8") : bytes;
+	return Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength).toString("base64url");
+}
+
+function pemToPkcs8(pem: string): Uint8Array<ArrayBuffer> {
+	const body = pem
+		.replace(/-----BEGIN [^-]+-----/g, "")
+		.replace(/-----END [^-]+-----/g, "")
+		.replace(/\s+/g, "");
+	if (!body) throw new Error("Invalid PEM: empty body");
+	return Uint8Array.fromBase64(body);
+}
+
+async function signJwtRs256(claims: Record<string, unknown>, privateKeyPem: string, keyId?: string): Promise<string> {
+	const header: Record<string, unknown> = { alg: "RS256", typ: "JWT" };
+	if (keyId) header.kid = keyId;
+	const payload = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(claims))}`;
+
+	const key = await globalThis.crypto.subtle.importKey(
+		"pkcs8",
+		pemToPkcs8(privateKeyPem),
+		{ name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+		false,
+		["sign"],
+	);
+	const signature = new Uint8Array(
+		await globalThis.crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(payload)),
+	);
+	return `${payload}.${base64UrlEncode(signature)}`;
+}
+
+async function exchangeJwtForToken(
+	creds: ServiceAccountCredentials,
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+): Promise<TokenResponse> {
+	const now = Math.floor(Date.now() / 1000);
+	const assertion = await signJwtRs256(
+		{
+			iss: creds.client_email,
+			scope: CLOUD_PLATFORM_SCOPE,
+			aud: OAUTH_TOKEN_URL,
+			exp: now + 3600,
+			iat: now,
+		},
+		creds.private_key,
+		creds.private_key_id,
+	);
+	const body = new URLSearchParams({ grant_type: JWT_BEARER_GRANT, assertion });
+	return postForToken(OAUTH_TOKEN_URL, body, signal, fetchImpl);
+}
+
+async function exchangeRefreshToken(
+	creds: AuthorizedUserCredentials,
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+): Promise<TokenResponse> {
+	const body = new URLSearchParams({
+		client_id: creds.client_id,
+		client_secret: creds.client_secret,
+		refresh_token: creds.refresh_token,
+		grant_type: "refresh_token",
+	});
+	return postForToken(OAUTH_TOKEN_URL, body, signal, fetchImpl);
+}
+
+async function fetchMetadataToken(
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+): Promise<TokenResponse | undefined> {
+	const timeout = AbortSignal.timeout(2000);
+	const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+	try {
+		const response = await fetchImpl(METADATA_TOKEN_URL, {
+			method: "GET",
+			headers: { "Metadata-Flavor": "Google" },
+			signal: combined,
+		});
+		if (!response.ok) return undefined;
+		return (await response.json()) as TokenResponse;
+	} catch {
+		return undefined;
+	}
+}
+
+async function postForToken(
+	url: string,
+	body: URLSearchParams,
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+): Promise<TokenResponse> {
+	const response = await fetchImpl(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: body.toString(),
+		signal,
+	});
+	if (!response.ok) {
+		const detail = await response.text().catch(() => "");
+		throw new Error(`Google OAuth token exchange failed (${response.status}): ${detail}`);
+	}
+	return (await response.json()) as TokenResponse;
+}
+
+async function resolveAccessTokenUncached(
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+): Promise<{ source: string; token: TokenResponse }> {
+	const adc = await loadAdcCredentials();
+	if (adc) {
+		const token =
+			adc.creds.type === "service_account"
+				? await exchangeJwtForToken(adc.creds, signal, fetchImpl)
+				: await exchangeRefreshToken(adc.creds, signal, fetchImpl);
+		return { source: adc.source, token };
+	}
+	const metadata = await fetchMetadataToken(signal, fetchImpl);
+	if (metadata) return { source: "metadata", token: metadata };
+	throw new Error(
+		"Vertex AI requires Application Default Credentials. Set GOOGLE_APPLICATION_CREDENTIALS, run `gcloud auth application-default login`, or run on a GCE/Cloud Run instance with a service account.",
+	);
+}
+
+/**
+ * Returns a Bearer access token suitable for the `Authorization` header on Vertex AI calls.
+ * The token is cached in module scope and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` ms before it expires.
+ */
+export async function getVertexAccessToken(options?: { signal?: AbortSignal; fetch?: FetchImpl }): Promise<string> {
+	const fetchImpl = options?.fetch ?? globalThis.fetch.bind(globalThis);
+	const skew = getRefreshSkewMs();
+	const now = Date.now();
+
+	// Best-effort cache key probe: we don't know the source until we resolve, but cached entries
+	// are keyed by their resolved source. Try every cached source first.
+	for (const [source, cached] of tokenCache) {
+		if (cached.expiresAtMs - skew > now) return cached.token;
+		// expired entry — drop and re-resolve
+		tokenCache.delete(source);
+	}
+
+	const cacheKey = "vertex-adc";
+	const existing = inflight.get(cacheKey);
+	if (existing) return existing;
+
+	const promise = (async () => {
+		try {
+			const { source, token } = await resolveAccessTokenUncached(options?.signal, fetchImpl);
+			const expiresAtMs = Date.now() + Math.max(0, token.expires_in * 1000);
+			tokenCache.set(source, { token: token.access_token, expiresAtMs });
+			logger.debug("vertex.adc acquired access token", { source, expiresInSec: token.expires_in });
+			return token.access_token;
+		} finally {
+			inflight.delete(cacheKey);
+		}
+	})();
+	inflight.set(cacheKey, promise);
+	return promise;
+}
+
+/** Test seam: clears every cached token. */
+export function __resetVertexTokenCache(): void {
+	tokenCache.clear();
+	inflight.clear();
+}