@nijaru/pi-search 0.0.1

package/src/gemini.ts

@@ -0,0 +1,298 @@
+import type {
+	Provider,
+	ProviderCapabilities,
+	ProviderContext,
+	ProviderModel,
+	ProviderProfile,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchResult,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import { cancelResponseBody } from "./http";
+import { executeGroundedSearch } from "./grounding";
+import { httpSource, objectValue, optionalString, type SearchHttpFetch } from "./provider-http";
+import { modelAuthHeaders, type ModelExecution } from "./model-selection";
+import { validateSearchRequest } from "./search";
+
+export const GEMINI_GENERATE_CONTENT_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta";
+export const DEFAULT_GEMINI_RESPONSE_BYTES = 4 * 1024 * 1024;
+const GEMINI_GROUNDING_REDIRECT_HOST = "vertexaisearch.cloud.google.com";
+const GEMINI_GROUNDING_REDIRECT_TIMEOUT_MS = 5_000;
+const MAX_GEMINI_ANSWER_LENGTH = 8_000;
+
+export interface GeminiAdapterOptions {
+	readonly endpoint?: string;
+	readonly fetchImpl?: SearchHttpFetch;
+	readonly maxResponseBytes?: number;
+}
+
+const capabilities: ProviderCapabilities = {
+	freshness: true,
+	semantic: true,
+	nativeGrounding: true,
+};
+
+const profile: ProviderProfile = {
+	auth: "modelRegistry",
+	costModel: "usage-based",
+};
+
+export interface GeminiRequestPlan {
+	readonly body: Record<string, unknown>;
+	readonly appliedOptions: readonly SearchOption[];
+	readonly warnings: readonly SearchWarning[];
+}
+
+export function buildGeminiRequest(request: SearchRequest): GeminiRequestPlan {
+	const normalized = validateSearchRequest(request);
+	if (normalized.domains?.include?.length || normalized.domains?.exclude?.length) {
+		throw createProviderError({ provider: "gemini", kind: "unsupported", message: "Gemini grounding does not expose hard domain filters", retryable: false });
+	}
+	if (normalized.dateRange !== undefined || normalized.social !== undefined) {
+		throw createProviderError({ provider: "gemini", kind: "unsupported", message: "Gemini grounding does not expose exact date-range or dedicated social/X constraints", retryable: false });
+	}
+	const warnings: SearchWarning[] = [];
+	if (normalized.mode === "keyword") {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "Gemini grounding uses semantic retrieval rather than keyword-only ranking" });
+	}
+	if (normalized.mode === "fresh") {
+		warnings.push({ code: "unsupported-option", option: "mode", message: "Gemini grounding can use current sources but does not guarantee a freshness-only ranking" });
+	}
+	return {
+		body: {
+			contents: [{ role: "user", parts: [{ text: normalized.mode === "fresh" ? `Prefer current sources. ${normalized.query}` : normalized.query }] }],
+			tools: [{ google_search: {} }],
+		},
+		appliedOptions: ["maxResults", "mode"],
+		warnings,
+	};
+}
+
+function isGroundingRedirectUrl(url: string): boolean {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" && parsed.hostname.toLowerCase() === GEMINI_GROUNDING_REDIRECT_HOST && parsed.pathname.startsWith("/grounding-api-redirect/");
+	} catch {
+		return false;
+	}
+}
+
+function endpointFor(model: ProviderModel, override?: string): string {
+	const base = (override ?? (model.baseUrl.trim().length > 0 ? model.baseUrl : GEMINI_GENERATE_CONTENT_ENDPOINT)).replace(/\/+$/, "");
+	if (base.endsWith(":generateContent")) return base;
+	return `${base}/models/${encodeURIComponent(model.id)}:generateContent`;
+}
+
+function authHeaders(execution: ModelExecution): Readonly<Record<string, string>> {
+	const headers = modelAuthHeaders(execution, { bearerApiKey: false });
+	if (execution.auth.apiKey !== undefined && execution.auth.apiKey.trim().length > 0) headers.set("x-goog-api-key", execution.auth.apiKey);
+	if (!headers.has("x-goog-api-key")) {
+		throw createProviderError({ provider: "gemini", kind: "auth", message: "Gemini authentication returned no API key", retryable: false });
+	}
+	return Object.fromEntries(headers.entries());
+}
+
+async function resolveGroundingUrl(url: string, signal: AbortSignal, fetchImpl: SearchHttpFetch): Promise<string> {
+	if (signal.aborted) throw createProviderError({ provider: "gemini", kind: "canceled", message: "Search canceled", retryable: false });
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return url;
+	}
+	if (!isGroundingRedirectUrl(url)) return url;
+	const controller = new AbortController();
+	const onAbort = () => controller.abort(signal.reason);
+	const timeoutId = setTimeout(() => controller.abort(new DOMException("Gemini grounding URL resolution timed out", "TimeoutError")), GEMINI_GROUNDING_REDIRECT_TIMEOUT_MS);
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		const response = await fetchImpl(url, { method: "HEAD", redirect: "manual", signal: controller.signal });
+		const location = response.headers.get("location");
+		await cancelResponseBody(response);
+		if (location === null || location.trim().length === 0) return url;
+		const target = httpSource(new URL(location, url).toString(), "gemini");
+		return target?.url ?? url;
+	} catch (error) {
+		if (signal.aborted) throw createProviderError({ provider: "gemini", kind: "canceled", message: "Search canceled", retryable: false, cause: error });
+		return url;
+	} finally {
+		clearTimeout(timeoutId);
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+
+async function normalizeGeminiResponse(payload: unknown, request: SearchRequest, signal: AbortSignal, fetchImpl: SearchHttpFetch): Promise<SearchResponse> {
+	const normalized = validateSearchRequest(request);
+	const root = objectValue(payload, "response", "gemini");
+	const promptFeedback = root.promptFeedback;
+	if (promptFeedback !== undefined) {
+		const feedback = objectValue(promptFeedback, "promptFeedback", "gemini");
+		const blockReason = optionalString(feedback.blockReason);
+		if (blockReason !== undefined) {
+			throw createProviderError({ provider: "gemini", kind: "http", message: `Gemini grounding was blocked (${blockReason})`, retryable: false });
+		}
+	}
+	if (!Array.isArray(root.candidates)) {
+		throw createProviderError({ provider: "gemini", kind: "malformed", message: "Gemini returned no candidates array", retryable: false });
+	}
+	const results: SearchResult[] = [];
+	const answerParts: string[] = [];
+	const answerCitationUrls = new Set<string>();
+	const groundingQueries = new Set<string>();
+	const maxResults = normalized.maxResults ?? 10;
+	const seen = new Set<string>();
+	const warnings: SearchWarning[] = [];
+	let discarded = 0;
+	let redirectAttempts = 0;
+	for (const candidateValue of root.candidates) {
+		const candidate = objectValue(candidateValue, "candidates[]", "gemini");
+		const finishReason = optionalString(candidate.finishReason);
+		if (finishReason !== undefined && finishReason !== "STOP" && finishReason !== "UNSPECIFIED") {
+			warnings.push({ code: "partial-results", message: `Gemini grounding candidate finished with ${finishReason}` });
+		}
+		const content = candidate.content;
+		if (content !== null && typeof content === "object" && !Array.isArray(content)) {
+			const parts = (content as Record<string, unknown>).parts;
+			if (Array.isArray(parts)) {
+				for (const part of parts) {
+					if (part !== null && typeof part === "object" && !Array.isArray(part) && typeof (part as Record<string, unknown>).text === "string") answerParts.push((part as Record<string, unknown>).text as string);
+				}
+			}
+		}
+		const metadata = candidate.groundingMetadata;
+		if (metadata === undefined) continue;
+		const grounding = objectValue(metadata, "groundingMetadata", "gemini");
+		if (Array.isArray(grounding.webSearchQueries)) {
+			for (const query of grounding.webSearchQueries) if (typeof query === "string" && query.trim().length > 0) groundingQueries.add(query.trim());
+		}
+		if (!Array.isArray(grounding.groundingChunks)) continue;
+		const chunkUrls: Array<string | undefined> = [];
+		for (const chunkValue of grounding.groundingChunks) {
+			const chunk = objectValue(chunkValue, "groundingChunks[]", "gemini");
+			const web = chunk.web;
+			if (web === undefined) {
+				chunkUrls.push(undefined);
+				continue;
+			}
+			const source = objectValue(web, "groundingChunks[].web", "gemini");
+			const parsed = httpSource(source.uri ?? source.url, "gemini");
+			if (parsed === undefined) {
+				discarded += 1;
+				chunkUrls.push(undefined);
+				continue;
+			}
+			let canonicalUrl = parsed.url;
+			if (isGroundingRedirectUrl(parsed.url) && redirectAttempts < maxResults) {
+				redirectAttempts += 1;
+				canonicalUrl = await resolveGroundingUrl(parsed.url, signal, fetchImpl);
+			}
+			const canonical = httpSource(canonicalUrl, "gemini");
+			if (canonical === undefined) {
+				discarded += 1;
+				chunkUrls.push(undefined);
+				continue;
+			}
+			chunkUrls.push(canonical.url);
+			if (seen.has(canonical.url)) continue;
+			seen.add(canonical.url);
+			if (results.length < maxResults) {
+				results.push({
+					url: canonical.url,
+					...(canonical.url === parsed.url ? {} : { sourceUrl: parsed.url }),
+					title: optionalString(source.title, 500),
+					domain: canonical.domain,
+					provider: "gemini",
+					searchQuery: normalized.query,
+				});
+			}
+		}
+		if (Array.isArray(grounding.groundingSupports)) {
+			for (const supportValue of grounding.groundingSupports) {
+				if (supportValue === null || typeof supportValue !== "object" || Array.isArray(supportValue)) continue;
+				const indices = (supportValue as Record<string, unknown>).groundingChunkIndices;
+				if (!Array.isArray(indices)) continue;
+				for (const index of indices) {
+					if (typeof index === "number" && Number.isInteger(index) && index >= 0) {
+						const url = chunkUrls[index];
+						if (url !== undefined) answerCitationUrls.add(url);
+					}
+				}
+			}
+		}
+	}
+	if (results.length === 0) {
+		throw createProviderError({ provider: "gemini", kind: "malformed", message: "Gemini returned no parseable grounding URLs", retryable: false });
+	}
+	if (discarded > 0) warnings.push({ code: "partial-results", message: `Gemini discarded ${discarded} malformed grounding entr${discarded === 1 ? "y" : "ies"}` });
+	const usage = root.usageMetadata;
+	const usageRecord = usage === undefined ? undefined : objectValue(usage, "usageMetadata", "gemini");
+	const inputTokens = typeof usageRecord?.promptTokenCount === "number" && Number.isFinite(usageRecord.promptTokenCount) ? usageRecord.promptTokenCount : undefined;
+	const outputTokens = typeof usageRecord?.candidatesTokenCount === "number" && Number.isFinite(usageRecord.candidatesTokenCount) ? usageRecord.candidatesTokenCount : undefined;
+	const totalTokens = typeof usageRecord?.totalTokenCount === "number" && Number.isFinite(usageRecord.totalTokenCount) ? usageRecord.totalTokenCount : undefined;
+	const answerText = answerParts.join(" ").replace(/\s+/g, " ").trim().slice(0, MAX_GEMINI_ANSWER_LENGTH);
+	const resultByUrl = new Map(results.map((result) => [result.url, result]));
+	const citations = [...answerCitationUrls].map((url) => resultByUrl.get(url)).filter((result): result is SearchResult => result !== undefined).map((result) => ({ url: result.url, ...(result.title === undefined ? {} : { title: result.title }) }));
+	const answer = normalized.answerMode !== "evidence" && answerText.length > 0 && citations.length > 0
+		? { text: answerText, contentTrust: "untrusted" as const, provider: "gemini" as const, citations }
+		: undefined;
+	const usageDetails = inputTokens === undefined && outputTokens === undefined && totalTokens === undefined && groundingQueries.size === 0
+		? undefined
+		: {
+			...(inputTokens === undefined ? {} : { inputTokens }),
+			...(outputTokens === undefined ? {} : { outputTokens }),
+			...(totalTokens === undefined ? {} : { totalTokens }),
+			...(groundingQueries.size === 0 ? {} : { searchQueries: groundingQueries.size }),
+		};
+	return {
+		query: normalized.query,
+		results,
+		...(answer === undefined ? {} : { answer }),
+		provider: "gemini",
+		appliedOptions: [],
+		warnings,
+		...(usageDetails === undefined ? {} : { usage: usageDetails }),
+	};
+}
+
+export class GeminiProvider implements Provider {
+	readonly id = "gemini" as const;
+	readonly capabilities = capabilities;
+	readonly profile = profile;
+	private readonly endpoint?: string;
+	private readonly fetchImpl: SearchHttpFetch;
+	private readonly maxResponseBytes: number;
+
+	constructor(options: GeminiAdapterOptions = {}) {
+		this.endpoint = options.endpoint;
+		this.fetchImpl = options.fetchImpl ?? (fetch as SearchHttpFetch);
+		this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_GEMINI_RESPONSE_BYTES;
+	}
+
+	async search(request: SearchRequest, signal: AbortSignal, context: ProviderContext): Promise<SearchResponse> {
+		const normalized = validateSearchRequest(request);
+		const plan = buildGeminiRequest(normalized);
+		return executeGroundedSearch({
+			provider: this.id,
+			modelProvider: "google",
+			api: "google-generative-ai",
+			request: normalized,
+			signal,
+			context,
+			fetchImpl: this.fetchImpl,
+			maxResponseBytes: this.maxResponseBytes,
+			// Gemini addresses the model in the URL, not the body.
+			includeModel: false,
+			endpointFor: (model) => endpointFor(model, this.endpoint),
+			headersFor: authHeaders,
+			plan,
+			normalize: (payload, current, grounding) => normalizeGeminiResponse(payload, current, grounding.signal, this.fetchImpl),
+		});
+	}
+}
+
+export function createGeminiProvider(options: GeminiAdapterOptions = {}): GeminiProvider {
+	return new GeminiProvider(options);
+}

package/src/grounding.ts

@@ -0,0 +1,167 @@
+import type {
+	ProviderContext,
+	ProviderId,
+	ProviderModel,
+	ProviderRateLimitInfo,
+	ProviderUsage,
+	SearchOption,
+	SearchRequest,
+	SearchResponse,
+	SearchWarning,
+} from "./contracts";
+import { createProviderError } from "./errors";
+import { modelAuthHeaders, selectModelExecution, type ModelExecution } from "./model-selection";
+import { postJson, type SearchHttpFetch } from "./provider-http";
+import { validateSearchRequest } from "./search";
+
+/**
+ * Shared helpers for model-mediated (native grounding) search adapters.
+ *
+ * Each native API keeps its own request/response mapping because tool names,
+ * citation shapes, and billing fields differ per vendor. What is genuinely
+ * common — model resolution through Pi's registry, bearer auth, endpoint
+ * joining, usage/rate-limit merging, and final response assembly — lives
+ * here so a new adapter is capabilities + build + normalize plus fixtures.
+ *
+ * OpenAI's streaming Responses transport stays bespoke in `openai.ts`; the
+ * `postJson` flow here covers Gemini, xAI, Codex, Anthropic, and Meta.
+ */
+
+export interface GroundingPlan {
+	readonly body: Record<string, unknown>;
+	readonly appliedOptions: readonly SearchOption[];
+	readonly warnings: readonly SearchWarning[];
+}
+
+/** Token-count usage shared by Responses-family payloads. */
+export function tokenUsage(
+	inputTokens: unknown,
+	outputTokens: unknown,
+	totalTokens: unknown,
+): ProviderUsage | undefined {
+	const clean = (value: unknown): number | undefined =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+	const input = clean(inputTokens);
+	const output = clean(outputTokens);
+	const total = clean(totalTokens);
+	if (input === undefined && output === undefined && total === undefined) return undefined;
+	return {
+		...(input === undefined ? {} : { inputTokens: input }),
+		...(output === undefined ? {} : { outputTokens: output }),
+		...(total === undefined ? {} : { totalTokens: total, billedUnits: total, billedUnit: "tokens" }),
+	};
+}
+
+/** Merge provider-reported usage with observed transport rate limits. */
+export function usageWithRateLimits(
+	usage: ProviderUsage | undefined,
+	rateLimits: ProviderRateLimitInfo | undefined,
+): ProviderUsage | undefined {
+	if (usage === undefined && rateLimits === undefined) return undefined;
+	return { ...usage, ...(rateLimits === undefined ? {} : { rateLimits }) };
+}
+
+/** Join a model base URL with an API suffix without doubling the path. */
+export function appendEndpointSuffix(base: string, suffix: string): string {
+	const trimmed = base.replace(/\/+$/, "");
+	return trimmed.endsWith(suffix) ? trimmed : `${trimmed}${suffix}`;
+}
+
+/** Validate a resolved endpoint URL without assuming a vendor path layout. */
+export function assertHttpEndpoint(candidate: string, provider: ProviderId, label: string): string {
+	let url: URL;
+	try {
+		url = new URL(candidate);
+	} catch (error) {
+		throw createProviderError({ provider, kind: "badRequest", message: `${label} is not a valid URL`, retryable: false, cause: error });
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") {
+		throw createProviderError({ provider, kind: "badRequest", message: `${label} must use HTTP or HTTPS`, retryable: false });
+	}
+	return url.toString();
+}
+
+/** Bearer auth derived from the model registry; never reads Pi auth globally. */
+export function bearerAuthHeaders(execution: ModelExecution, provider: ProviderId): Readonly<Record<string, string>> {
+	const headers = modelAuthHeaders(execution);
+	if (!headers.has("authorization")) {
+		throw createProviderError({ provider, kind: "auth", message: "Model authentication returned no authorization header", retryable: false });
+	}
+	return Object.fromEntries(headers.entries());
+}
+
+export interface GroundedSearchOptions {
+	readonly provider: ProviderId;
+	readonly modelProvider: string;
+	readonly api: string;
+	readonly request: SearchRequest;
+	readonly signal: AbortSignal;
+	readonly context: ProviderContext;
+	readonly fetchImpl: SearchHttpFetch;
+	readonly maxResponseBytes: number;
+	/**
+	 * Inject the execution model id into the request body. Gemini addresses
+	 * the model in the URL instead, so it opts out. Defaults to true.
+	 */
+	readonly includeModel?: boolean;
+	readonly endpointFor: (model: ProviderModel) => string;
+	readonly headersFor: (execution: ModelExecution) => Readonly<Record<string, string>>;
+	readonly plan: GroundingPlan;
+	readonly normalize: (
+		payload: unknown,
+		normalized: SearchRequest,
+		context: { readonly signal: AbortSignal },
+	) => Promise<SearchResponse> | SearchResponse;
+}
+
+/**
+ * Run one non-streaming grounded-model search: resolve the execution model,
+ * POST the plan body, normalize the payload, and attach execution metadata.
+ * Callers supply only vendor-specific pieces.
+ */
+export async function executeGroundedSearch(options: GroundedSearchOptions): Promise<SearchResponse> {
+	const normalized = validateSearchRequest(options.request);
+	if (options.signal.aborted) {
+		throw createProviderError({ provider: options.provider, kind: "canceled", message: "Search canceled", retryable: false });
+	}
+	const execution = await selectModelExecution({
+		searchProvider: options.provider,
+		modelProvider: options.modelProvider,
+		api: options.api,
+		request: normalized,
+		context: options.context,
+		// The router rejects an explicit provider hint without an executionModel
+		// before dispatch when the active model is incompatible, and the native
+		// alias requires a compatible active model. So a request that reaches an
+		// adapter without an executionModel is either active-compatible (the
+		// normal active-match path) or a router-initiated registry fallback
+		// (DESIGN backend-resolution step 2), where a registry model is already
+		// confirmed available.
+		...(normalized.executionModel === undefined ? { allowRegistryFallback: true } : {}),
+	});
+	if (options.signal.aborted) {
+		throw createProviderError({ provider: options.provider, kind: "canceled", message: "Search canceled", retryable: false });
+	}
+	const result = await postJson({
+		provider: options.provider,
+		url: options.endpointFor(execution.model),
+		headers: options.headersFor(execution),
+		body: options.includeModel === false ? options.plan.body : { ...options.plan.body, model: execution.model.id },
+		signal: options.signal,
+		fetchImpl: options.fetchImpl,
+		maxResponseBytes: options.maxResponseBytes,
+	});
+	const response = await options.normalize(result.payload, normalized, { signal: options.signal });
+	const usage = usageWithRateLimits(response.usage, result.rateLimits);
+	return {
+		...response,
+		...(response.answer === undefined ? {} : { answer: { ...response.answer, executionModel: execution.model.id } }),
+		...(response.requestId === undefined && result.requestId === undefined
+			? {}
+			: { requestId: response.requestId ?? result.requestId }),
+		...(usage === undefined ? {} : { usage }),
+		executionModel: execution.model.id,
+		appliedOptions: options.plan.appliedOptions,
+		warnings: [...options.plan.warnings, ...response.warnings],
+	};
+}

package/src/http.ts

@@ -0,0 +1,78 @@
+/** Maximum response bytes are enforced while reading, not from Content-Length alone. */
+export class ResponseBodyTooLargeError extends Error {
+	readonly bytesRead: number;
+	readonly maxBytes: number;
+
+	constructor(bytesRead: number, maxBytes: number) {
+		super(`Response body exceeded ${maxBytes} bytes`);
+		this.name = "ResponseBodyTooLargeError";
+		this.bytesRead = bytesRead;
+		this.maxBytes = maxBytes;
+	}
+}
+
+/** Release an unused response body before returning a provider error. */
+export async function cancelResponseBody(response: Response): Promise<void> {
+	try {
+		await response.body?.cancel();
+	} catch {
+		// Preserve the provider status/error; body teardown is best effort.
+	}
+}
+
+function abortError(signal: AbortSignal): Error {
+	return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
+
+/** Read a response body with cancellation and a hard byte bound. */
+export async function readBoundedResponseText(
+	response: Response,
+	maxBytes: number,
+	signal?: AbortSignal,
+): Promise<string> {
+	if (!Number.isInteger(maxBytes) || maxBytes < 1) {
+		throw new RangeError("maxBytes must be a positive integer");
+	}
+	if (signal?.aborted) throw abortError(signal);
+	const contentLength = response.headers.get("content-length");
+	if (contentLength !== null) {
+		const parsedLength = Number(contentLength);
+		if (Number.isFinite(parsedLength) && parsedLength > maxBytes) {
+			await cancelResponseBody(response);
+			throw new ResponseBodyTooLargeError(parsedLength, maxBytes);
+		}
+	}
+	if (response.body === null) return "";
+
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let bytesRead = 0;
+	const onAbort = () => {
+		void reader.cancel(signal?.reason);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		const chunks: string[] = [];
+		while (true) {
+			if (signal?.aborted) throw abortError(signal);
+			const { done, value } = await reader.read();
+			if (signal?.aborted) throw abortError(signal);
+			if (done) break;
+			bytesRead += value.byteLength;
+			if (bytesRead > maxBytes) {
+				throw new ResponseBodyTooLargeError(bytesRead, maxBytes);
+			}
+			chunks.push(decoder.decode(value, { stream: true }));
+		}
+		chunks.push(decoder.decode());
+		return chunks.join("");
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		try {
+			await reader.cancel();
+		} catch {
+			// The body is already being torn down. Preserve the original failure.
+		}
+		reader.releaseLock();
+	}
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createAnthropicProvider } from "./anthropic";
+import { createBraveProvider, BraveQuotaTracker } from "./brave";
+import { createBraveAnswersProvider } from "./brave-answers";
+import { createCodexProvider } from "./codex";
+import { createExaProvider } from "./exa";
+import { createGeminiProvider } from "./gemini";
+import { registerWebFetch } from "./fetch-tool";
+import { createOpenAIProvider } from "./openai";
+import { createParallelProvider } from "./parallel";
+import { createParallelResponsesProvider } from "./parallel-responses";
+import { createMetaProvider } from "./meta";
+import { createSearchRouter } from "./router";
+import { createXProvider } from "./x";
+import { createXAIProvider } from "./xai";
+import { adaptLocalLlamaPayload, isLocalOpenAICompatibleModel } from "./local-llama-compat";
+import { availableProviderHints } from "./provider-availability";
+import { registerWebResearch } from "./research-tool";
+import { registerWebSearch } from "./search-tool";
+
+/**
+ * Native grounding is selected for supported active models. Exa is the
+ * metered non-native default only when explicitly allowed; Brave is the paced
+ * last-resort keyword path. Automatic availability failures may use one
+ * visible fallback.
+ */
+export default function (pi: ExtensionAPI): void {
+	const braveKey = process.env.BRAVE_API_KEY;
+	// Brave is a conservative last-resort path: pace starts at 1 RPS and never claims
+	// to know the account's billing balance. Set `=0` only with explicit metered
+	// opt-in when that pacing is intentionally not wanted.
+	const braveFreeOnly = process.env.PI_SEARCH_BRAVE_FREE_ONLY !== "0";
+	const braveCapacity = new BraveQuotaTracker({ minimumIntervalMs: braveFreeOnly ? 1_000 : 0 });
+	const brave = createBraveProvider({ apiKey: braveKey, capacityTracker: braveCapacity });
+	const openai = createOpenAIProvider({ provider: "openai" });
+	const codex = createCodexProvider();
+	const gemini = createGeminiProvider();
+	const xai = createXAIProvider({ tool: "web_search" });
+	const xaiX = createXAIProvider({ tool: "x_search" });
+	const anthropic = createAnthropicProvider();
+	const meta = createMetaProvider();
+	const exaKey = process.env.EXA_API_KEY;
+	const parallelKey = process.env.PARALLEL_API_KEY;
+	const xToken = process.env.X_API_BEARER_TOKEN;
+	const exa = createExaProvider({ apiKey: exaKey });
+	const parallel = createParallelProvider({ apiKey: parallelKey });
+	const x = createXProvider({ bearerToken: xToken });
+	// Opt-in answer-synthesis providers: the enable gate alone controls
+	// registration so each failure names its actual missing piece. A gate
+	// without a key dispatches to the adapter, which reports the missing key;
+	// a key without the gate never registers the provider at all.
+	const parallelResponsesEnabled = process.env.PI_SEARCH_ENABLE_PARALLEL_RESPONSES === "1";
+	const braveAnswersEnabled = process.env.PI_SEARCH_ENABLE_BRAVE_ANSWERS === "1";
+	const parallelResponses = createParallelResponsesProvider({ apiKey: parallelKey });
+	const braveAnswers = createBraveAnswersProvider({ apiKey: braveKey });
+	const billingPolicy = process.env.PI_SEARCH_ALLOW_METERED === "1"
+		? "allow-configured-metered"
+		: process.env.PI_SEARCH_PREFER_FREE === "1" ? "prefer-free" : "free-only";
+	const braveFreeCapacityConfigured = braveFreeOnly;
+	const route = createSearchRouter({
+		openai,
+		openaiCodex: codex,
+		gemini,
+		xai,
+		xaiX,
+		anthropic,
+		meta,
+		exa,
+		parallel,
+		parallelResponses,
+		braveAnswers,
+		x,
+		brave,
+		braveConfigured: braveKey !== undefined && braveKey.trim().length > 0,
+		exaConfigured: exaKey !== undefined && exaKey.trim().length > 0,
+		parallelConfigured: parallelKey !== undefined && parallelKey.trim().length > 0,
+		parallelResponsesConfigured: parallelResponsesEnabled,
+		braveAnswersConfigured: braveAnswersEnabled,
+		xConfigured: xToken !== undefined && xToken.trim().length > 0,
+		braveFreeCapacityConfigured,
+		braveCapacity,
+		billingPolicy,
+	});
+	// Expose only provider hints this installation can actually dispatch so
+	// the tool schemas never advertise options whose keys or gates are absent.
+	const availableHints = availableProviderHints({
+		brave: braveKey !== undefined && braveKey.trim().length > 0,
+		braveAnswers: braveAnswersEnabled,
+		exa: exaKey !== undefined && exaKey.trim().length > 0,
+		parallel: parallelKey !== undefined && parallelKey.trim().length > 0,
+		parallelResponses: parallelResponsesEnabled,
+		x: xToken !== undefined && xToken.trim().length > 0,
+	});
+	pi.on("before_provider_request", (event, context) => {
+		if (!isLocalOpenAICompatibleModel(context.model)) return;
+		return adaptLocalLlamaPayload(event.payload);
+	});
+	registerWebSearch(pi, route, { availableProviderHints: availableHints });
+	registerWebFetch(pi);
+	registerWebResearch(pi, route, { availableProviderHints: availableHints });
+}