@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/pi-web-access/curator-page.ts

@@ -8,7 +8,7 @@ function safeInlineJSON(data: unknown): string {
 }
 
 function buildProviderButtons(
-	available: { all: boolean; openai: boolean; brave: boolean; parallel: boolean; "parallel-mcp": boolean; tinyfish: boolean; search1api: boolean; searchinfinity: boolean; querit: boolean; tavily: boolean; firecrawl: boolean; jina: boolean; serpdive: boolean; kagi: boolean; bocha: boolean; ollama: boolean; searxng: boolean; duckduckgo: boolean; perplexity: boolean; exa: boolean; gemini: boolean; anysearch: boolean; xai: boolean; brightdata: boolean; serpbase: boolean; serper: boolean; valyu: boolean },
+	available: { all: boolean; openai: boolean; brave: boolean; parallel: boolean; "parallel-mcp": boolean; tinyfish: boolean; search1api: boolean; searchinfinity: boolean; querit: boolean; tavily: boolean; firecrawl: boolean; jina: boolean; serpdive: boolean; kagi: boolean; bocha: boolean; ollama: boolean; searxng: boolean; duckduckgo: boolean; perplexity: boolean; exa: boolean; gemini: boolean; kimi: boolean; anysearch: boolean; xai: boolean; brightdata: boolean; serpbase: boolean; serper: boolean; valyu: boolean },
 	selected: string,
 	hasInitialQueries: boolean,
 ): string {
@@ -34,6 +34,7 @@ function buildProviderButtons(
 		{ value: "duckduckgo", label: "DuckDuckGo", available: available.duckduckgo },
 		{ value: "perplexity", label: "Perplexity", available: available.perplexity },
 		{ value: "gemini", label: "Gemini", available: available.gemini },
+		{ value: "kimi", label: "Kimi", available: available.kimi },
 		{ value: "anysearch", label: "AnySearch", available: available.anysearch },
 		{ value: "xai", label: "xAI", available: available.xai },
 		{ value: "brightdata", label: "Bright Data", available: available.brightdata },
@@ -58,7 +59,7 @@ export function generateCuratorPage(
 	queries: string[],
 	sessionToken: string,
 	timeout: number,
-	availableProviders: { all: boolean; openai: boolean; brave: boolean; parallel: boolean; "parallel-mcp": boolean; tinyfish: boolean; search1api: boolean; searchinfinity: boolean; querit: boolean; tavily: boolean; firecrawl: boolean; jina: boolean; serpdive: boolean; kagi: boolean; bocha: boolean; ollama: boolean; searxng: boolean; duckduckgo: boolean; perplexity: boolean; exa: boolean; gemini: boolean; anysearch: boolean; xai: boolean; brightdata: boolean; serpbase: boolean; serper: boolean; valyu: boolean },
+	availableProviders: { all: boolean; openai: boolean; brave: boolean; parallel: boolean; "parallel-mcp": boolean; tinyfish: boolean; search1api: boolean; searchinfinity: boolean; querit: boolean; tavily: boolean; firecrawl: boolean; jina: boolean; serpdive: boolean; kagi: boolean; bocha: boolean; ollama: boolean; searxng: boolean; duckduckgo: boolean; perplexity: boolean; exa: boolean; gemini: boolean; kimi: boolean; anysearch: boolean; xai: boolean; brightdata: boolean; serpbase: boolean; serper: boolean; valyu: boolean },
 	defaultProvider: string,
 	searchProvider: string,
 	summaryModels: Array<{ value: string; label: string }>,
@@ -1459,7 +1460,7 @@ const SCRIPT = `(function() {
   var token = DATA.sessionToken;
   var timeoutSec = DATA.timeout;
   var queries = Array.isArray(DATA.queries) ? DATA.queries : [];
-  var providers = ["all", "openai", "exa", "brave", "parallel", "parallel-mcp", "tinyfish", "search1api", "searchinfinity", "querit", "tavily", "firecrawl", "jina", "serpdive", "kagi", "bocha", "ollama", "searxng", "duckduckgo", "perplexity", "gemini", "anysearch", "xai", "brightdata", "serpbase", "serper", "valyu"];
+  var providers = ["all", "openai", "exa", "brave", "parallel", "parallel-mcp", "tinyfish", "search1api", "searchinfinity", "querit", "tavily", "firecrawl", "jina", "serpdive", "kagi", "bocha", "ollama", "searxng", "duckduckgo", "perplexity", "gemini", "kimi", "anysearch", "xai", "brightdata", "serpbase", "serper", "valyu"];
   var availProviders = DATA.availableProviders && typeof DATA.availableProviders === "object" ? DATA.availableProviders : {};
   var workflow = "summary-review";
   var initialDefaultProvider = typeof DATA.defaultProvider === "string" ? DATA.defaultProvider : "exa";
@@ -1682,6 +1683,7 @@ const SCRIPT = `(function() {
     if (provider === "perplexity") return "Perplexity";
     if (provider === "exa") return "Exa";
     if (provider === "gemini") return "Gemini";
+    if (provider === "kimi") return "Kimi";
     if (provider === "anysearch") return "AnySearch";
     if (provider === "xai") return "xAI";
     if (provider === "brightdata") return "Bright Data";

package/node_modules/pi-web-access/curator-server.ts

@@ -18,7 +18,7 @@ export interface CuratorServerOptions {
 	queries: string[];
 	sessionToken: string;
 	timeout: number;
-	availableProviders: { all: boolean; openai: boolean; brave: boolean; parallel: boolean; "parallel-mcp": boolean; tinyfish: boolean; search1api: boolean; searchinfinity: boolean; querit: boolean; tavily: boolean; firecrawl: boolean; jina: boolean; serpdive: boolean; kagi: boolean; bocha: boolean; ollama: boolean; searxng: boolean; duckduckgo: boolean; perplexity: boolean; exa: boolean; gemini: boolean; anysearch: boolean; xai: boolean; brightdata: boolean; serpbase: boolean; serper: boolean; valyu: boolean };
+	availableProviders: { all: boolean; openai: boolean; brave: boolean; parallel: boolean; "parallel-mcp": boolean; tinyfish: boolean; search1api: boolean; searchinfinity: boolean; querit: boolean; tavily: boolean; firecrawl: boolean; jina: boolean; serpdive: boolean; kagi: boolean; bocha: boolean; ollama: boolean; searxng: boolean; duckduckgo: boolean; perplexity: boolean; exa: boolean; gemini: boolean; kimi: boolean; anysearch: boolean; xai: boolean; brightdata: boolean; serpbase: boolean; serper: boolean; valyu: boolean };
 	defaultProvider: string;
 	searchProvider: string;
 	summaryModels: Array<{ value: string; label: string }>;
@@ -292,6 +292,7 @@ export function startCuratorServer(
 		if (provider === "perplexity") return availableProviders.perplexity;
 		if (provider === "exa") return availableProviders.exa;
 		if (provider === "gemini") return availableProviders.gemini;
+		if (provider === "kimi") return availableProviders.kimi;
 		if (provider === "anysearch") return availableProviders.anysearch;
 		if (provider === "xai") return availableProviders.xai;
 		if (provider === "brightdata") return availableProviders.brightdata;

package/node_modules/pi-web-access/extract.ts

@@ -8,6 +8,7 @@ import { activityMonitor } from "./activity.ts";
 import { extractRSCContent } from "./rsc-extract.ts";
 import { extractPDFToMarkdown, isPDF, loadPDFConfig } from "./pdf-extract.ts";
 import { extractGitHub } from "./github-extract.ts";
+import { extractGitHubIssuePr } from "./github-issue-pr.ts";
 import { isYouTubeURL, isYouTubeEnabled, extractYouTube, extractYouTubeFrame, extractYouTubeFrames, getYouTubeStreamInfo } from "./youtube-extract.ts";
 import { CredentialResolutionError } from "./credential-source.ts";
 import { extractWithUrlContext, extractWithGeminiWeb } from "./gemini-url-context.ts";
@@ -23,7 +24,7 @@ import { extractWithBrightDataUnlocker, isBrightDataUnlockerAvailable } from "./
 import { isVideoFile, extractVideo, extractVideoFrame, getLocalVideoDuration } from "./video-extract.ts";
 import { appendDeclaredWebLinks, discoverDeclaredWebLinks, type DeclaredWebLink } from "./declared-web-links.ts";
 import { fetchRemoteUrl, loadFetchContentDomainPolicy, loadSsrfConfig, validateRemoteUrl, type DomainPolicy, type Lookup, type SsrfConfig } from "./ssrf-protection.ts";
-import { formatSeconds, getWebSearchConfigPath } from "./utils.ts";
+import { formatSeconds, getWebSearchConfigPath, type ProxiedRequestInit } from "./utils.ts";
 import { isImageEnabled } from "./feature-config.ts";
 import { assertAuthFetchUrl, authFetchRedirectGuard, type AuthFetchProfile } from "./auth-fetch.ts";
 import { getBrowserCookiesForHosts, getLastBrowserCookieDiagnostic } from "./chrome-cookies.ts";
@@ -42,6 +43,13 @@ type FetchRouting = { providers: FetchProvider[]; allowRemoteHostedProviders: bo
 const DEFAULT_FETCH_PROVIDER_ORDER: FetchProvider[] = ["http", "firecrawl", "jina", "tinyfish", "search1api", "querit", "kagi", "ollama", "parallel", "brightdata", "gemini"];
 const REMOTE_HOSTED_FETCH_PROVIDERS = new Set<FetchProvider>(["jina", "tinyfish", "search1api", "querit", "kagi", "ollama", "parallel", "parallel-mcp", "brightdata", "gemini"]);
 
+async function extractWithDefuddle(text: string, url: string): Promise<{ title: string; content: string } | null> {
+	const { Defuddle } = await import("defuddle/node");
+	const { document } = parseHTML(text);
+	const result = await Defuddle(document as unknown as Document, url, { markdown: true, useAsync: false });
+	return typeof result.content === "string" ? { title: result.title, content: result.content } : null;
+}
+
 export { loadSsrfConfig } from "./ssrf-protection.ts";
 
 export function loadSsrfAllowRanges(): string[] {
@@ -183,6 +191,32 @@ function loadFetchRouting(): FetchRouting {
 	return { providers, allowRemoteHostedProviders: allowRemoteHostedProvidersValue === true };
 }
 
+/** Names of the search/fetch tools the caller has actually registered, so
+ * failure guidance never points at tools that do not exist in the session. */
+export interface RegisteredToolNames {
+	webSearch?: string;
+	fetchContent?: string;
+}
+
+/** Guidance for definitive origin 404/410 responses: no extraction provider
+ * can retrieve a page the origin says is gone, so point at the registered
+ * search/fetch tools (when the caller knows them) instead of provider config. */
+function notFoundGuidance(result: ExtractedContent, toolNames?: RegisteredToolNames): string {
+	const lines = [
+		result.error ?? `HTTP ${result.status}`,
+		"",
+		`The origin server says this page does not exist (HTTP ${result.status}), so extraction providers cannot retrieve it.`,
+	];
+	if (toolNames?.webSearch && toolNames.fetchContent) {
+		lines.push(`The page may have moved or been renamed. Use ${toolNames.webSearch} to find the current URL, then retry ${toolNames.fetchContent} with it.`);
+	} else if (toolNames?.webSearch) {
+		lines.push(`The page may have moved or been renamed. Use ${toolNames.webSearch} to find the current URL.`);
+	} else {
+		lines.push("The page may have moved or been renamed. Find the current URL, then retry the fetch with it.");
+	}
+	return lines.join("\n");
+}
+
 function abortedResult(url: string): ExtractedContent {
 	return { url, title: "", content: "", error: "Aborted" };
 }
@@ -227,6 +261,9 @@ export interface ExtractOptions {
 	mode?: "readable" | "raw" | "answer";
 	answerModel?: string;
 	authFetchProfile?: AuthFetchProfile;
+	toolNames?: RegisteredToolNames;
+	/** Optional http(s) proxy URL; routed through the curl-backed transport. */
+	proxy?: string;
 	/** Custom DNS resolver used for SSRF validation. Primarily a test seam. */
 	lookup?: Lookup;
 }
@@ -585,6 +622,18 @@ export async function extractContent(
 		return { url, title: "", content: "", error: errorMessage(err) };
 	}
 
+	try {
+		const ghIssuePrResult = await extractGitHubIssuePr(url, signal, options);
+		if (ghIssuePrResult) return ghIssuePrResult;
+		if (signal?.aborted) return abortedResult(url);
+	} catch (err) {
+		const message = errorMessage(err);
+		if (isAbortError(err)) return abortedResult(url);
+		if (isConfigParseError(err)) {
+			return { url, title: "", content: "", error: message };
+		}
+	}
+
 	try {
 		const ghResult = await extractGitHub(url, signal, options?.forceClone);
 		if (ghResult) return ghResult;
@@ -856,6 +905,14 @@ export async function extractContent(
 	const finalHttpResult = httpResult as ExtractedContent | null;
 	if (finalHttpResult && declaredLinks.length > 0) return { ...finalHttpResult, error: null };
 
+	// A definitive 404/410 from the origin means no extraction provider can
+	// retrieve the page, so the provider-configuration checklist below would
+	// send users down the wrong path. Point at search instead.
+	if (finalHttpResult?.status === 404 || finalHttpResult?.status === 410) {
+		return { ...finalHttpResult, error: notFoundGuidance(finalHttpResult, options?.toolNames) };
+	}
+
+	const searchToolName = options?.toolNames?.webSearch;
 	const guidance = [
 		finalHttpResult?.error ?? "No fetch_content provider returned content",
 		...(firecrawlError ? [`Firecrawl fallback failed: ${firecrawlError}`] : []),
@@ -879,19 +936,17 @@ export async function extractContent(
 		`  • Set brightdataApiKey and brightdataUnlockerZone in ${WEB_SEARCH_CONFIG_PATH} or BRIGHTDATA_API_KEY and BRIGHTDATA_UNLOCKER_ZONE`,
 		`  • Set GEMINI_API_KEY in ${WEB_SEARCH_CONFIG_PATH}`,
 		"  • Sign into gemini.google.com in Chrome",
-		"  • Use web_search to find content about this topic",
+		...(searchToolName ? [`  • Use ${searchToolName} to find content about this topic`] : []),
 	].join("\n");
 	return { ...(finalHttpResult ?? { url, title: "", content: "", error: null }), error: guidance };
 }
 
 function isLikelyJSRendered(html: string): boolean {
-	// Extract body content
 	const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
 	if (!bodyMatch) return false;
 
 	const bodyHtml = bodyMatch[1];
 
-	// Strip tags to get text content
 	const textContent = bodyHtml
 		.replace(/<script[\s\S]*?<\/script>/gi, "")
 		.replace(/<style[\s\S]*?<\/style>/gi, "")
@@ -899,10 +954,8 @@ function isLikelyJSRendered(html: string): boolean {
 		.replace(/\s+/g, " ")
 		.trim();
 
-	// Count scripts
 	const scriptCount = (html.match(/<script/gi) || []).length;
 
-	// Heuristic: little text content but many scripts suggests JS rendering
 	return textContent.length < 500 && scriptCount > 3;
 }
 
@@ -999,8 +1052,10 @@ async function extractViaHttp(
 		const ssrf = loadSsrfConfig();
 		const domainPolicy = loadFetchContentDomainPolicy();
 		const authProfile = options?.authFetchProfile;
-		const requestInit = {
+		const trustEnvProxy = options?.proxy === undefined && ssrf.trustEnvProxy;
+		const requestInit: ProxiedRequestInit = {
 			signal: controller.signal,
+			__proxy: options?.proxy,
 			headers: {
 				"User-Agent": "OpenAI File Downloader, XaiImageApiFetch/1.0",
 				"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
@@ -1014,13 +1069,13 @@ async function extractViaHttp(
 			},
 		};
 		const response = authProfile
-			? await fetchAuthenticatedRemoteUrl(url, requestInit, { ssrf, domainPolicy, ...(options?.lookup ? { lookup: options.lookup } : {}) }, authProfile)
+			? await fetchAuthenticatedRemoteUrl(url, requestInit, { ssrf: { ...ssrf, trustEnvProxy }, domainPolicy, ...(options?.lookup ? { lookup: options.lookup } : {}) }, authProfile)
 			: await fetchRemoteUrl(
 				url,
 				requestInit,
 				{
 					allowRanges: ssrf.allowRanges,
-					trustEnvProxy: ssrf.trustEnvProxy,
+					trustEnvProxy,
 					domainPolicy,
 					...(options?.lookup ? { lookup: options.lookup } : {}),
 				},
@@ -1170,6 +1225,19 @@ async function extractViaHttp(
 					declaredLinks,
 				};
 			}
+			controller.signal.throwIfAborted();
+			const defuddleResult = await extractWithDefuddle(text, response.url || url);
+			controller.signal.throwIfAborted();
+			if (defuddleResult && defuddleResult.content.length >= MIN_USEFUL_CONTENT) {
+				activityMonitor.logComplete(activityId, response.status);
+				return {
+					url,
+					title: documentTitle || defuddleResult.title,
+					content: appendDeclaredWebLinks(defuddleResult.content, declaredLinks),
+					error: null,
+					declaredLinks,
+				};
+			}
 
 			activityMonitor.logComplete(activityId, response.status);
 			const jsRendered = isLikelyJSRendered(text);
@@ -1203,6 +1271,18 @@ async function extractViaHttp(
 					declaredLinks,
 				};
 			}
+			controller.signal.throwIfAborted();
+			const defuddleResult = await extractWithDefuddle(text, response.url || url);
+			controller.signal.throwIfAborted();
+			if (defuddleResult && defuddleResult.content.length >= MIN_USEFUL_CONTENT) {
+				return {
+					url,
+					title: article.title || documentTitle || defuddleResult.title,
+					content: appendDeclaredWebLinks(defuddleResult.content, declaredLinks),
+					error: null,
+					declaredLinks,
+				};
+			}
 			return {
 				url,
 				title: article.title || documentTitle,

package/node_modules/pi-web-access/fetch-params.ts

@@ -1,3 +1,5 @@
+import { normalizeProxyUrl } from "./utils.ts";
+
 export interface FetchContentParams {
 	url?: unknown;
 	urls?: unknown;
@@ -9,6 +11,7 @@ export interface FetchContentParams {
 	mode?: unknown;
 	answerModel?: unknown;
 	auth?: unknown;
+	proxy?: unknown;
 }
 
 export interface NormalizedFetchContentParams {
@@ -22,6 +25,7 @@ export interface NormalizedFetchContentParams {
 		mode?: "readable" | "raw" | "answer";
 		answerModel?: string;
 		auth?: true | string;
+		proxy?: string;
 	};
 }
 
@@ -39,6 +43,7 @@ export function normalizeFetchContentParams(params: FetchContentParams): Normali
 	const mode = normalizeMode(params.mode);
 	const answerModel = normalizeOptionalString(params.answerModel);
 	const auth = normalizeAuth(params.auth);
+	const proxy = normalizeProxy(params.proxy);
 
 	return {
 		urlList,
@@ -51,6 +56,7 @@ export function normalizeFetchContentParams(params: FetchContentParams): Normali
 			...(mode !== undefined ? { mode } : {}),
 			...(answerModel !== undefined ? { answerModel } : {}),
 			...(auth !== undefined ? { auth } : {}),
+			...(proxy !== undefined ? { proxy } : {}),
 		},
 	};
 }
@@ -88,6 +94,13 @@ function normalizeAuth(value: unknown): true | string | undefined {
 	throw new Error("auth must be a profile name, true, or false");
 }
 
+function normalizeProxy(value: unknown): string | undefined {
+	if (value === undefined || value === false) return undefined;
+	if (value === null) throw new Error("proxy must be an http(s) proxy URL string");
+	const normalized = normalizeProxyUrl(value, "proxy");
+	return normalized ?? "";
+}
+
 function normalizeOptionalFrameCount(value: unknown): number | undefined {
 	if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 12) return undefined;
 	return value;

package/node_modules/pi-web-access/gemini-adc.ts

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createSign } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getWebSearchConfigPath } from "./utils.ts";
+import { redactCredential, CredentialResolutionError } from "./credential-source.ts";
+
+const CONFIG_PATH = getWebSearchConfigPath();
+const DEFAULT_ADC_PATH = join(homedir(), ".config", "gcloud", "application_default_credentials.json");
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const VERTEX_HOST = "https://aiplatform.googleapis.com";
+const VERTEX_API_VERSION = "v1";
+const REFRESH_SKEW_MS = 60_000;
+
+interface GeminiAdcConfig {
+	geminiAuth?: unknown;
+	geminiProject?: unknown;
+	geminiLocation?: unknown;
+	geminiApiKey?: unknown;
+	geminiBaseUrl?: unknown;
+}
+
+let cachedConfig: GeminiAdcConfig | null = null;
+
+function loadConfig(): GeminiAdcConfig {
+	if (cachedConfig) return cachedConfig;
+	if (!existsSync(CONFIG_PATH)) {
+		cachedConfig = {};
+		return cachedConfig;
+	}
+	const raw = readFileSync(CONFIG_PATH, "utf-8");
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error("config root must be an object");
+		}
+		cachedConfig = parsed as GeminiAdcConfig;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${CONFIG_PATH}: ${message}`);
+	}
+	return cachedConfig;
+}
+
+function normalizeIdentifier(value: unknown, envName: string): string | null {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed) return trimmed;
+	}
+	const fromEnv = process.env[envName]?.trim();
+	return fromEnv ? fromEnv : null;
+}
+
+export function isAdcAuthSelected(): boolean {
+	return (loadConfig().geminiAuth ?? "").toString().trim().toLowerCase() === "adc";
+}
+
+export function getAdcProject(): string | null {
+	return (
+		normalizeIdentifier(loadConfig().geminiProject, "GOOGLE_CLOUD_PROJECT") ??
+		normalizeIdentifier(null, "GCLOUD_PROJECT")
+	);
+}
+
+export function getAdcLocation(): string | null {
+	return normalizeIdentifier(loadConfig().geminiLocation, "GOOGLE_CLOUD_LOCATION");
+}
+
+function getAdcPath(): string {
+	return process.env.GOOGLE_APPLICATION_CREDENTIALS?.trim() || DEFAULT_ADC_PATH;
+}
+
+export function getVertexApiBase(project: string, location: string): string {
+	return `${VERTEX_HOST}/${VERTEX_API_VERSION}/projects/${encodeURIComponent(project)}/locations/${encodeURIComponent(location)}/publishers/google`;
+}
+
+export function isVertexHost(origin: string): boolean {
+	return origin === VERTEX_HOST;
+}
+
+interface AdcFile {
+	type?: string;
+	client_id?: string;
+	client_secret?: string;
+	refresh_token?: string;
+	client_email?: string;
+	private_key?: string;
+	private_key_id?: string;
+	token_uri?: string;
+	universe_domain?: string;
+}
+
+function objectRecord(value: unknown): Record<string, unknown> | null {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function stringField(record: Record<string, unknown>, name: string): string | undefined {
+	const value = record[name];
+	return typeof value === "string" ? value : undefined;
+}
+
+function requiredString(record: Record<string, unknown>, name: string, context: string): string {
+	const value = stringField(record, name)?.trim();
+	if (!value) throw new Error(`${context} is missing ${name}`);
+	return value;
+}
+
+function parseAdcFile(raw: string): AdcFile {
+	const parsed = objectRecord(JSON.parse(raw));
+	if (!parsed) throw new Error("credential root must be an object");
+	const type = stringField(parsed, "type") ?? "authorized_user";
+	if (type === "authorized_user") {
+		return {
+			type,
+			client_id: requiredString(parsed, "client_id", "Gemini ADC authorized_user file"),
+			client_secret: requiredString(parsed, "client_secret", "Gemini ADC authorized_user file"),
+			refresh_token: requiredString(parsed, "refresh_token", "Gemini ADC authorized_user file"),
+			universe_domain: stringField(parsed, "universe_domain"),
+		};
+	}
+	if (type === "service_account") {
+		return {
+			type,
+			client_email: requiredString(parsed, "client_email", "Gemini ADC service_account file"),
+			private_key: requiredString(parsed, "private_key", "Gemini ADC service_account file"),
+			private_key_id: stringField(parsed, "private_key_id"),
+			token_uri: stringField(parsed, "token_uri"),
+			universe_domain: stringField(parsed, "universe_domain"),
+		};
+	}
+	return { type };
+}
+
+function parseTokenExchangeResponse(text: string, context: string): CachedToken {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`${context} returned invalid JSON: ${message}`);
+	}
+	const parsed = objectRecord(raw);
+	if (!parsed) throw new Error(`${context} returned a non-object response`);
+	const token = stringField(parsed, "access_token")?.trim();
+	if (!token) throw new Error(`${context} returned no access_token`);
+	const expiresIn = parsed.expires_in ?? 3600;
+	if (typeof expiresIn !== "number" || !Number.isFinite(expiresIn)) {
+		throw new Error(`${context} returned invalid expires_in`);
+	}
+	return { token, expiresAt: Date.now() + Math.max((expiresIn * 1000) - REFRESH_SKEW_MS, 60_000) };
+}
+
+async function loadAdcFile(): Promise<AdcFile> {
+	const path = getAdcPath();
+	if (!path || !existsSync(path)) {
+		throw new Error(`Google Application Default Credentials file not found at ${path}`);
+	}
+	const raw = readFileSync(path, "utf-8");
+	try {
+		return parseAdcFile(raw);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse Google Application Default Credentials file at ${path}: ${message}`);
+	}
+}
+
+interface CachedToken {
+	token: string;
+	expiresAt: number;
+}
+
+let cachedToken: CachedToken | null = null;
+
+export function clearAdcTokenCache(): void {
+	cachedToken = null;
+}
+
+/**
+ * Classifies a failed OAuth token exchange. Only explicit credential/authorization
+ * rejections (400 invalid_client/invalid_grant/invalid_scope, 401, 403 denied)
+ * mean the configured credentials themselves were refused — a hard credential
+ * problem callers should surface rather than silently fall back. Everything else
+ * (429 rate limit, 404, 5xx, network failures, timeouts) is transient, so it is
+ * left as a plain Error and existing per-provider fallbacks keep working.
+ */
+const OAUTH_CREDENTIAL_REJECTION_STATUSES = new Set([400, 401, 403]);
+
+function throwOnTokenExchangeFailure(res: Response, detail: string, status: number): never {
+	if (OAUTH_CREDENTIAL_REJECTION_STATUSES.has(status)) {
+		throw new CredentialResolutionError("Gemini ADC", "oauth-credential-rejected");
+	}
+	throw new Error(`Gemini ADC token exchange failed (${status}): ${detail.slice(0, 300)}`);
+}
+
+async function exchangeRefreshToken(cfg: AdcFile, signal?: AbortSignal): Promise<CachedToken> {
+	const body = new URLSearchParams({
+		client_id: cfg.client_id ?? "",
+		client_secret: cfg.client_secret ?? "",
+		refresh_token: cfg.refresh_token ?? "",
+		grant_type: "refresh_token",
+	});
+	const res = await fetch(TOKEN_ENDPOINT, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body,
+		signal,
+	});
+	const text = await res.text();
+	if (!res.ok) {
+		throwOnTokenExchangeFailure(res, text, res.status);
+	}
+	return parseTokenExchangeResponse(text, "Gemini ADC token exchange");
+}
+
+async function exchangeServiceAccountJwt(cfg: AdcFile, signal?: AbortSignal): Promise<CachedToken> {
+	if (!cfg.client_email || !cfg.private_key) {
+		throw new Error("Gemini ADC service_account file is missing client_email or private_key");
+	}
+	const now = Math.floor(Date.now() / 1000);
+	const header = { alg: "RS256", typ: "JWT" };
+	const claims = {
+		iss: cfg.client_email,
+		scope: "https://www.googleapis.com/auth/cloud-platform",
+		aud: TOKEN_ENDPOINT,
+		iat: now,
+		exp: now + 3600,
+	};
+	const encodePart = (obj: object): string =>
+		Buffer.from(JSON.stringify(obj)).toString("base64url");
+	const assertion = `${encodePart(header)}.${encodePart(claims)}`;
+	const signer = createSign("RSA-SHA256");
+	signer.update(assertion);
+	signer.end();
+	const signature = signer.sign(cfg.private_key, "base64url");
+	const jwt = `${assertion}.${signature}`;
+
+	const body = new URLSearchParams({
+		grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+		assertion: jwt,
+	});
+	const res = await fetch(cfg.token_uri || TOKEN_ENDPOINT, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body,
+		signal,
+	});
+	const text = await res.text();
+	if (!res.ok) {
+		throwOnTokenExchangeFailure(res, text, res.status);
+	}
+	return parseTokenExchangeResponse(text, "Gemini ADC service account token exchange");
+}
+
+export async function getAdcAccessToken(signal?: AbortSignal): Promise<string> {
+	if (cachedToken && cachedToken.expiresAt > Date.now()) {
+		return cachedToken.token;
+	}
+	const cfg = await loadAdcFile();
+	const type = cfg.type ?? "authorized_user";
+	if (type === "authorized_user") {
+		cachedToken = await exchangeRefreshToken(cfg, signal);
+	} else if (type === "service_account") {
+		cachedToken = await exchangeServiceAccountJwt(cfg, signal);
+	} else {
+		throw new Error(`Gemini ADC unsupported credential type "${type}" (expected authorized_user or service_account)`);
+	}
+	return cachedToken.token;
+}
+
+export function isGeminiAdcAvailable(): boolean {
+	if (!isAdcAuthSelected()) return false;
+	// An explicitly configured Gemini API key takes precedence over ADC, so
+	// existing key-based setups and their unit tests keep working unchanged.
+	if (hasGeminiApiKeySource()) return false;
+	// An explicit base URL (gateway/relay/proxy) also wins over ADC: if the
+	// user deliberately routed Gemini somewhere, honor that routing.
+	if (hasExplicitApiBase()) return false;
+	if (!getAdcProject() || !getAdcLocation()) return false;
+	return existsSync(getAdcPath());
+}
+
+function hasGeminiApiKeySource(): boolean {
+	const configured = loadConfig().geminiApiKey;
+	if (typeof configured === "string" && configured.trim()) return true;
+	const fromEnv = process.env.GEMINI_API_KEY?.trim();
+	return !!fromEnv;
+}
+
+function hasExplicitApiBase(): boolean {
+	const fromEnv = process.env.GOOGLE_GEMINI_BASE_URL?.trim();
+	if (fromEnv) return true;
+	const configured = loadConfig().geminiBaseUrl;
+	return typeof configured === "string" && configured.trim().length > 0;
+}
+
+export function redactAdcToken(text: string): string {
+	return cachedToken ? redactCredential(text, cachedToken.token) : text;
+}