@gajae-code/coding-agent 0.1.1

package/src/web/search/providers/exa.ts

@@ -0,0 +1,193 @@
+/**
+ * Exa Web Search Provider
+ *
+ * High-quality neural search via Exa Search API.
+ * Returns structured search results with optional content extraction.
+ * Requests per-result summaries via `contents.summary` and synthesizes
+ * them into a combined `answer` string on the SearchResponse.
+ */
+import { type AuthStorage, getEnvApiKey } from "@gajae-code/ai";
+import { settings } from "../../../config/settings";
+
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import { SearchProviderError } from "../../../web/search/types";
+import { dateToAgeSeconds } from "../utils";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+import { classifyProviderHttpError, withHardTimeout } from "./utils";
+
+const EXA_API_URL = "https://api.exa.ai/search";
+
+type ExaSearchType = "neural" | "fast" | "auto" | "deep";
+
+type ExaSearchParamType = ExaSearchType | "keyword";
+
+export interface ExaSearchParams {
+	query: string;
+	num_results?: number;
+	type?: ExaSearchParamType;
+	include_domains?: string[];
+	exclude_domains?: string[];
+	start_published_date?: string;
+	end_published_date?: string;
+	signal?: AbortSignal;
+}
+
+interface ExaSearchResult {
+	title?: string | null;
+	url?: string | null;
+	author?: string | null;
+	publishedDate?: string | null;
+	text?: string | null;
+	highlights?: string[] | null;
+	summary?: string | null;
+}
+
+interface ExaSearchResponse {
+	requestId?: string;
+	resolvedSearchType?: string;
+	results?: ExaSearchResult[];
+	costDollars?: { total: number };
+	searchTime?: number;
+}
+
+export function normalizeSearchType(type: ExaSearchParamType | undefined): ExaSearchType {
+	if (!type) return "auto";
+	if (type === "keyword") return "fast";
+	return type;
+}
+
+/** Maximum number of per-result summaries to include in the synthesized answer. */
+const MAX_ANSWER_SUMMARIES = 3;
+
+/**
+ * Synthesize an answer string from per-result summaries returned by Exa.
+ * Returns `undefined` when no non-empty summaries are available so callers
+ * can leave `SearchResponse.answer` unset (matching other providers).
+ */
+export function synthesizeAnswer(results: ExaSearchResult[]): string | undefined {
+	const parts: string[] = [];
+	for (const r of results) {
+		if (parts.length >= MAX_ANSWER_SUMMARIES) break;
+		const summary = r.summary?.trim();
+		if (!summary) continue;
+		const title = r.title?.trim() || r.url || "Untitled";
+		parts.push(`**${title}**: ${summary}`);
+	}
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}
+
+/** Build the request body for `callExaSearch`. Exported for testing. */
+export function buildExaRequestBody(params: ExaSearchParams): Record<string, unknown> {
+	const body: Record<string, unknown> = {
+		query: params.query,
+		numResults: params.num_results ?? 10,
+		type: normalizeSearchType(params.type),
+		contents: {
+			summary: { query: params.query },
+		},
+	};
+
+	if (params.include_domains?.length) {
+		body.includeDomains = params.include_domains;
+	}
+	if (params.exclude_domains?.length) {
+		body.excludeDomains = params.exclude_domains;
+	}
+	if (params.start_published_date) {
+		body.startPublishedDate = params.start_published_date;
+	}
+	if (params.end_published_date) {
+		body.endPublishedDate = params.end_published_date;
+	}
+
+	return body;
+}
+
+/** Call Exa Search API */
+async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<ExaSearchResponse> {
+	const body = buildExaRequestBody(params);
+
+	const response = await fetch(EXA_API_URL, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"x-api-key": apiKey,
+		},
+		body: JSON.stringify(body),
+		signal: withHardTimeout(params.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("exa", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError("exa", `Exa API error (${response.status}): ${errorText}`, response.status);
+	}
+
+	return response.json() as Promise<ExaSearchResponse>;
+}
+
+/** Execute Exa web search */
+export async function searchExa(params: ExaSearchParams): Promise<SearchResponse> {
+	const apiKey = getEnvApiKey("exa");
+	if (!apiKey) {
+		throw new SearchProviderError("exa", "EXA_API_KEY is required; Exa MCP fallback is disabled in gajae-code.", 401);
+	}
+	const response = await callExaSearch(apiKey, params);
+
+	// Convert to unified SearchResponse
+	const sources: SearchSource[] = [];
+
+	if (response.results) {
+		for (const result of response.results) {
+			if (!result.url) continue;
+			sources.push({
+				title: result.title ?? result.url,
+				url: result.url,
+				snippet: result.summary || result.text || result.highlights?.join(" ") || undefined,
+				publishedDate: result.publishedDate ?? undefined,
+				ageSeconds: dateToAgeSeconds(result.publishedDate ?? undefined),
+				author: result.author ?? undefined,
+			});
+		}
+	}
+
+	// Apply num_results limit if specified
+	const limitedSources = params.num_results ? sources.slice(0, params.num_results) : sources;
+
+	// Synthesize answer only from results that have a URL (same guard as sources loop)
+	const answer = response.results ? synthesizeAnswer(response.results.filter(r => !!r.url)) : undefined;
+
+	return {
+		provider: "exa",
+		answer,
+		sources: limitedSources,
+		requestId: response.requestId,
+	};
+}
+
+/** Search provider for Exa. */
+export class ExaProvider extends SearchProvider {
+	readonly id = "exa";
+	readonly label = "Exa";
+
+	isAvailable(_authStorage: AuthStorage): boolean {
+		try {
+			if (settings.get("exa.enabled") === false || settings.get("exa.enableSearch") === false) {
+				return false;
+			}
+		} catch {
+			// Settings not initialized; availability still requires explicit API credentials.
+		}
+		return !!getEnvApiKey("exa");
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchExa({
+			query: params.query,
+			num_results: params.numSearchResults ?? params.limit,
+			signal: params.signal,
+		});
+	}
+}

package/src/web/search/providers/gemini.ts

@@ -0,0 +1,455 @@
+/**
+ * Google Gemini Web Search Provider
+ *
+ * Uses Gemini's Google Search grounding via Cloud Code Assist API.
+ * Auth is resolved through `AuthStorage.getOAuthAccess(...)` for both
+ * `google-gemini-cli` (stable prod) and `google-antigravity` (daily sandbox)
+ * — the broker is the sole refresh authority, so this module never opens a
+ * sibling SQLite store and never POSTs the broker sentinel to a Google token
+ * endpoint.
+ */
+import {
+	ANTIGRAVITY_SYSTEM_INSTRUCTION,
+	type AuthStorage,
+	getAntigravityUserAgent,
+	getGeminiCliHeaders,
+} from "@gajae-code/ai";
+import { fetchWithRetry } from "@gajae-code/utils";
+
+import type { SearchCitation, SearchResponse, SearchSource } from "../../../web/search/types";
+import { SearchProviderError } from "../../../web/search/types";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+import { classifyProviderHttpError, withHardTimeout } from "./utils";
+
+const DEFAULT_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+const ANTIGRAVITY_DAILY_ENDPOINT = "https://daily-cloudcode-pa.googleapis.com";
+const ANTIGRAVITY_SANDBOX_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
+const ANTIGRAVITY_ENDPOINT_FALLBACKS = [ANTIGRAVITY_DAILY_ENDPOINT, ANTIGRAVITY_SANDBOX_ENDPOINT] as const;
+const DEFAULT_MODEL = "gemini-2.5-flash";
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+const RATE_LIMIT_BUDGET_MS = 5 * 60 * 1000;
+
+const GEMINI_PROVIDERS = ["google-gemini-cli", "google-antigravity"] as const;
+type GeminiProviderId = (typeof GEMINI_PROVIDERS)[number];
+
+interface GeminiToolParams {
+	google_search?: Record<string, unknown>;
+	code_execution?: Record<string, unknown>;
+	url_context?: Record<string, unknown>;
+}
+
+export interface GeminiSearchParams extends GeminiToolParams {
+	query: string;
+	system_prompt?: string;
+	num_results?: number;
+	/** Maximum output tokens. */
+	max_output_tokens?: number;
+	/** Sampling temperature (0–1). Lower = more focused/factual. */
+	temperature?: number;
+	signal?: AbortSignal;
+	authStorage: AuthStorage;
+	sessionId?: string;
+}
+
+export function buildGeminiRequestTools(params: GeminiToolParams): Array<Record<string, Record<string, unknown>>> {
+	const tools: Array<Record<string, Record<string, unknown>>> = [{ googleSearch: params.google_search ?? {} }];
+	if (params.code_execution !== undefined) {
+		tools.push({ codeExecution: params.code_execution });
+	}
+	if (params.url_context !== undefined) {
+		tools.push({ urlContext: params.url_context });
+	}
+	return tools;
+}
+
+/** Resolved auth for a Gemini API request. */
+interface GeminiAuth {
+	accessToken: string;
+	projectId: string;
+	isAntigravity: boolean;
+}
+
+/**
+ * Walks the configured Gemini OAuth providers in deterministic order and
+ * returns the first one that yields a usable access token + projectId via
+ * {@link AuthStorage.getOAuthAccess}. AuthStorage handles refresh + broker
+ * routing internally; this helper never touches refresh tokens directly.
+ */
+export async function findGeminiAuth(
+	authStorage: AuthStorage,
+	sessionId: string | undefined,
+	signal: AbortSignal | undefined,
+): Promise<GeminiAuth | null> {
+	for (const provider of GEMINI_PROVIDERS) {
+		const access = await authStorage.getOAuthAccess(provider, sessionId, { signal });
+		if (!access?.accessToken || !access.projectId) continue;
+		return {
+			accessToken: access.accessToken,
+			projectId: access.projectId,
+			isAntigravity: provider === "google-antigravity",
+		};
+	}
+	return null;
+}
+
+function hasGeminiOAuth(authStorage: AuthStorage): boolean {
+	return GEMINI_PROVIDERS.some((provider: GeminiProviderId) => authStorage.hasOAuth(provider));
+}
+
+/** Cloud Code Assist API response types */
+interface GeminiGroundingChunk {
+	web?: {
+		uri?: string;
+		title?: string;
+	};
+}
+
+interface GeminiGroundingSupport {
+	segment?: {
+		startIndex?: number;
+		endIndex?: number;
+		text?: string;
+	};
+	groundingChunkIndices?: number[];
+	confidenceScores?: number[];
+}
+
+interface GeminiGroundingMetadata {
+	groundingChunks?: GeminiGroundingChunk[];
+	groundingSupports?: GeminiGroundingSupport[];
+	webSearchQueries?: string[];
+}
+
+interface CloudCodeResponseChunk {
+	response?: {
+		candidates?: Array<{
+			content?: {
+				role: string;
+				parts?: Array<{ text?: string }>;
+			};
+			finishReason?: string;
+			groundingMetadata?: GeminiGroundingMetadata;
+		}>;
+		usageMetadata?: {
+			promptTokenCount?: number;
+			candidatesTokenCount?: number;
+			totalTokenCount?: number;
+		};
+		modelVersion?: string;
+	};
+}
+
+/**
+ * Calls the Cloud Code Assist API with Google Search grounding enabled.
+ *
+ * If a request returns a refreshable auth failure (401/403/auth-flavoured 400),
+ * we ask AuthStorage to invalidate + refresh the credential and retry once.
+ * Provider-direct refresh helpers are intentionally not used: AuthStorage owns
+ * the single-flight refresh and broker round-trip.
+ */
+async function callGeminiSearch(
+	auth: GeminiAuth,
+	query: string,
+	systemPrompt: string | undefined,
+	maxOutputTokens: number | undefined,
+	temperature: number | undefined,
+	toolParams: GeminiToolParams,
+	signal: AbortSignal | undefined,
+): Promise<{
+	answer: string;
+	sources: SearchSource[];
+	citations: SearchCitation[];
+	searchQueries: string[];
+	model: string;
+	usage?: { inputTokens: number; outputTokens: number; totalTokens: number };
+}> {
+	const endpoints = auth.isAntigravity ? ANTIGRAVITY_ENDPOINT_FALLBACKS : [DEFAULT_ENDPOINT];
+	const headers = auth.isAntigravity ? { "User-Agent": getAntigravityUserAgent() } : getGeminiCliHeaders();
+
+	const requestMetadata = auth.isAntigravity
+		? {
+				requestType: "agent",
+				userAgent: "antigravity",
+				requestId: `agent-${crypto.randomUUID()}`,
+			}
+		: {
+				userAgent: "gajae-code",
+				requestId: `pi-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+			};
+
+	const normalizedSystemPrompt = systemPrompt?.toWellFormed();
+	const systemInstructionParts: Array<{ text: string }> = [
+		...(auth.isAntigravity
+			? [
+					{ text: ANTIGRAVITY_SYSTEM_INSTRUCTION },
+					{ text: `Please ignore following [ignore]${ANTIGRAVITY_SYSTEM_INSTRUCTION}[/ignore]` },
+				]
+			: []),
+		...(normalizedSystemPrompt ? [{ text: normalizedSystemPrompt }] : []),
+	];
+
+	const requestBody: Record<string, unknown> = {
+		project: auth.projectId,
+		model: DEFAULT_MODEL,
+		request: {
+			contents: [
+				{
+					role: "user",
+					parts: [{ text: query }],
+				},
+			],
+			tools: buildGeminiRequestTools(toolParams),
+			...(systemInstructionParts.length > 0 && {
+				systemInstruction: {
+					...(auth.isAntigravity ? { role: "user" } : {}),
+					parts: systemInstructionParts,
+				},
+			}),
+		},
+		...requestMetadata,
+	};
+
+	if (maxOutputTokens !== undefined || temperature !== undefined) {
+		const generationConfig: Record<string, number> = {};
+		if (maxOutputTokens !== undefined) {
+			generationConfig.maxOutputTokens = maxOutputTokens;
+		}
+		if (temperature !== undefined) {
+			generationConfig.temperature = temperature;
+		}
+		(requestBody.request as Record<string, unknown>).generationConfig = generationConfig;
+	}
+	const buildInit = (): RequestInit => ({
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${auth.accessToken}`,
+			"Content-Type": "application/json",
+			Accept: "text/event-stream",
+			...headers,
+		},
+		body: JSON.stringify(requestBody),
+		signal: withHardTimeout(signal),
+	});
+	const urlFor = (attempt: number) =>
+		`${endpoints[Math.min(attempt, endpoints.length - 1)]}/v1internal:streamGenerateContent?alt=sse`;
+
+	const response = await fetchWithRetry(urlFor, {
+		...buildInit(),
+		maxAttempts: MAX_RETRIES + 1,
+		defaultDelayMs: attempt => BASE_DELAY_MS * 2 ** attempt,
+		maxDelayMs: RATE_LIMIT_BUDGET_MS,
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("gemini", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError(
+			"gemini",
+			`Gemini Cloud Code API error (${response.status}): ${errorText}`,
+			response.status,
+		);
+	}
+
+	if (!response.body) {
+		throw new SearchProviderError("gemini", "Gemini API returned no response body", 500);
+	}
+
+	// Parse SSE stream
+	const answerParts: string[] = [];
+	const sources: SearchSource[] = [];
+	const citations: SearchCitation[] = [];
+	const searchQueries: string[] = [];
+	const seenUrls = new Set<string>();
+	let model = DEFAULT_MODEL;
+	let usage: { inputTokens: number; outputTokens: number; totalTokens: number } | undefined;
+
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+
+			for (const line of lines) {
+				if (!line.startsWith("data:")) continue;
+
+				const jsonStr = line.slice(5).trim();
+				if (!jsonStr) continue;
+
+				let chunk: CloudCodeResponseChunk;
+				try {
+					chunk = JSON.parse(jsonStr) as CloudCodeResponseChunk;
+				} catch {
+					continue;
+				}
+
+				const responseData = chunk.response;
+				if (!responseData) continue;
+
+				const candidate = responseData.candidates?.[0];
+
+				// Extract text content
+				if (candidate?.content?.parts) {
+					for (const part of candidate.content.parts) {
+						if (part.text) {
+							answerParts.push(part.text);
+						}
+					}
+				}
+
+				// Extract grounding metadata
+				const groundingMetadata = candidate?.groundingMetadata;
+				if (groundingMetadata) {
+					// Extract sources from grounding chunks
+					if (groundingMetadata.groundingChunks) {
+						for (const grChunk of groundingMetadata.groundingChunks) {
+							if (grChunk.web?.uri) {
+								const sourceUrl = grChunk.web.uri;
+								if (!seenUrls.has(sourceUrl)) {
+									seenUrls.add(sourceUrl);
+									sources.push({
+										title: grChunk.web.title ?? sourceUrl,
+										url: sourceUrl,
+									});
+								}
+							}
+						}
+					}
+
+					// Extract citations from grounding supports
+					if (groundingMetadata.groundingSupports && groundingMetadata.groundingChunks) {
+						for (const support of groundingMetadata.groundingSupports) {
+							const citedText = support.segment?.text;
+							const chunkIndices = support.groundingChunkIndices ?? [];
+
+							for (const idx of chunkIndices) {
+								const grChunk = groundingMetadata.groundingChunks[idx];
+								if (grChunk?.web?.uri) {
+									citations.push({
+										url: grChunk.web.uri,
+										title: grChunk.web.title ?? grChunk.web.uri,
+										citedText,
+									});
+								}
+							}
+						}
+					}
+
+					// Extract search queries
+					if (groundingMetadata.webSearchQueries) {
+						for (const q of groundingMetadata.webSearchQueries) {
+							if (!searchQueries.includes(q)) {
+								searchQueries.push(q);
+							}
+						}
+					}
+				}
+
+				// Extract usage metadata
+				if (responseData.usageMetadata) {
+					usage = {
+						inputTokens: responseData.usageMetadata.promptTokenCount ?? 0,
+						outputTokens: responseData.usageMetadata.candidatesTokenCount ?? 0,
+						totalTokens: responseData.usageMetadata.totalTokenCount ?? 0,
+					};
+				}
+
+				// Extract model version
+				if (responseData.modelVersion) {
+					model = responseData.modelVersion;
+				}
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+
+	return {
+		answer: answerParts.join(""),
+		sources,
+		citations,
+		searchQueries,
+		model,
+		usage,
+	};
+}
+
+/**
+ * Executes a web search using Google Gemini with Google Search grounding.
+ */
+export async function searchGemini(params: GeminiSearchParams): Promise<SearchResponse> {
+	const auth = await findGeminiAuth(params.authStorage, params.sessionId, params.signal);
+	if (!auth) {
+		throw new Error(
+			"No Gemini OAuth credentials found. Login with 'gjc /login google-gemini-cli' or 'gjc /login google-antigravity' to enable Gemini web search.",
+		);
+	}
+
+	const result = await callGeminiSearch(
+		auth,
+		params.query,
+		params.system_prompt,
+		params.max_output_tokens,
+		params.temperature,
+		{
+			google_search: params.google_search,
+			code_execution: params.code_execution,
+			url_context: params.url_context,
+		},
+		params.signal,
+	);
+
+	let sources = result.sources;
+
+	if (params.num_results && sources.length > params.num_results) {
+		sources = sources.slice(0, params.num_results);
+	}
+
+	return {
+		provider: "gemini",
+		answer: result.answer || undefined,
+		sources,
+		citations: result.citations.length > 0 ? result.citations : undefined,
+		searchQueries: result.searchQueries.length > 0 ? result.searchQueries : undefined,
+		usage: result.usage,
+		model: result.model,
+	};
+}
+
+/** Search provider for Google Gemini web search. */
+export class GeminiProvider extends SearchProvider {
+	readonly id = "gemini";
+	readonly label = "Gemini";
+
+	isAvailable(authStorage: AuthStorage): boolean {
+		// Cheap, in-memory check — avoids driving the refresh pipeline during
+		// the provider-chain probe. `searchGemini` calls `getOAuthAccess` which
+		// will refresh lazily on the actual request.
+		return hasGeminiOAuth(authStorage);
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchGemini({
+			query: params.query,
+			system_prompt: params.systemPrompt,
+			num_results: params.numSearchResults ?? params.limit,
+			max_output_tokens: params.maxOutputTokens,
+			temperature: params.temperature,
+			google_search: params.googleSearch,
+			code_execution: params.codeExecution,
+			url_context: params.urlContext,
+			signal: params.signal,
+			authStorage: params.authStorage,
+			sessionId: params.sessionId,
+		});
+	}
+}