@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/web/search/index.ts

@@ -7,7 +7,7 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
 import type { AuthStorage } from "@prometheus-ai/ai";
 import { prompt } from "@prometheus-ai/utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { CustomTool, CustomToolContext, RenderResultOptions } from "../../extensibility/custom-tools/types";
 import type { Theme } from "../../modes/theme/theme";
 import webSearchSystemPrompt from "../../prompts/system/web-search.md" with { type: "text" };
@@ -115,6 +115,15 @@ function formatForLLM(response: SearchResponse): string {
 	return parts.join("\n");
 }
 
+function hasRenderableSearchContent(response: SearchResponse): boolean {
+	if (response.answer?.trim()) return true;
+	if (response.sources.length > 0) return true;
+	if (response.citations?.length) return true;
+	if (response.relatedQuestions?.some(question => question.trim())) return true;
+	if (response.searchQueries?.some(query => query.trim())) return true;
+	return false;
+}
+
 interface ExecuteSearchOptions {
 	authStorage: AuthStorage;
 	sessionId?: string;
@@ -150,7 +159,7 @@ async function executeSearch(
 		lastProvider = provider;
 		try {
 			const response = await provider.search({
-				query: params.query.replace(/202\d/g, String(new Date().getFullYear())), // LUL
+				query: params.query,
 				limit: params.limit,
 				recency: params.recency,
 				systemPrompt: webSearchSystemPrompt,
@@ -162,6 +171,10 @@ async function executeSearch(
 				sessionId,
 			});
 
+			if (!hasRenderableSearchContent(response)) {
+				throw new SearchProviderError(provider.id, `${provider.label} returned no renderable search content.`, 204);
+			}
+
 			const text = formatForLLM(response);
 
 			return {

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

@@ -7,12 +7,17 @@
 import {
 	type AnthropicAuthConfig,
 	type AnthropicSystemBlock,
+	type ApiKey,
 	type AuthStorage,
 	buildAnthropicAuthConfig,
 	buildAnthropicSearchHeaders,
 	buildAnthropicSystemBlocks,
 	buildAnthropicUrl,
+	type FetchImpl,
+	resolveAnthropicMetadataUserId,
 	stripClaudeToolPrefix,
+	withAuth,
+	wrapFetchForCch,
 } from "@prometheus-ai/ai";
 import { $env } from "@prometheus-ai/utils";
 import type {
@@ -38,6 +43,7 @@ export interface AnthropicSearchParams {
 	max_tokens?: number;
 	temperature?: number;
 	signal?: AbortSignal;
+	fetch?: FetchImpl;
 }
 
 /**
@@ -60,7 +66,9 @@ function buildSystemBlocks(
 	model: string,
 	systemPrompt?: string,
 ): AnthropicSystemBlock[] | undefined {
-	const includeClaudeCode = !model.startsWith("claude-3-5-haiku");
+	// Match the streaming path: the CC billing header + system instruction are
+	// an OAuth fingerprint and must not be claimed on API-key requests.
+	const includeClaudeCode = auth.isOAuth && !model.startsWith("claude-3-5-haiku");
 	const extraInstructions = auth.isOAuth ? ["You are a helpful AI assistant with web search capabilities."] : [];
 
 	return buildAnthropicSystemBlocks(systemPrompt ? [systemPrompt] : undefined, {
@@ -75,6 +83,7 @@ function buildSystemBlocks(
  * @param auth - Authentication configuration (API key or OAuth)
  * @param model - Model identifier to use
  * @param query - Search query from the user
+ * @param metadataUserId - Optional Anthropic Messages metadata.user_id (already shaped for OAuth)
  * @param systemPrompt - Optional system prompt for guiding response style
  * @returns Raw API response from Anthropic
  * @throws {SearchProviderError} If the API request fails
@@ -83,10 +92,12 @@ async function callSearch(
 	auth: AnthropicAuthConfig,
 	model: string,
 	query: string,
+	metadataUserId?: string,
 	systemPrompt?: string,
 	maxTokens?: number,
 	temperature?: number,
 	signal?: AbortSignal,
+	fetchImpl: FetchImpl = fetch,
 ): Promise<AnthropicApiResponse> {
 	const url = buildAnthropicUrl(auth);
 	const headers = buildAnthropicSearchHeaders(auth);
@@ -105,6 +116,10 @@ async function callSearch(
 		],
 	};
 
+	if (metadataUserId) {
+		body.metadata = { user_id: metadataUserId };
+	}
+
 	if (temperature !== undefined) {
 		body.temperature = temperature;
 	}
@@ -113,7 +128,10 @@ async function callSearch(
 		body.system = systemBlocks;
 	}
 
-	const response = await fetch(url, {
+	// OAuth requests inject the CC billing header (buildSystemBlocks); patch its
+	// cch attestation like the streaming path instead of shipping `cch=00000`.
+	const doFetch = auth.isOAuth ? wrapFetchForCch(fetchImpl) : fetchImpl;
+	const response = await doFetch(url, {
 		method: "POST",
 		headers,
 		body: JSON.stringify(body),
@@ -247,18 +265,13 @@ export async function searchAnthropic(
 ): Promise<SearchResponse> {
 	const searchApiKey = $env.ANTHROPIC_SEARCH_API_KEY;
 	const searchBaseUrl = $env.ANTHROPIC_SEARCH_BASE_URL;
-	let auth: AnthropicAuthConfig | undefined;
-
-	if (searchApiKey) {
-		auth = buildAnthropicAuthConfig(searchApiKey, searchBaseUrl);
-	} else if ("authStorage" in params) {
-		const apiKey = await params.authStorage.getApiKey("anthropic", params.sessionId, {
-			signal: params.signal,
-		});
-		if (apiKey) auth = buildAnthropicAuthConfig(apiKey, searchBaseUrl);
-	}
+	const keyOrResolver: ApiKey | undefined = searchApiKey
+		? searchApiKey
+		: "authStorage" in params
+			? params.authStorage.resolver("anthropic", { sessionId: params.sessionId })
+			: undefined;
 
-	if (!auth) {
+	if (!keyOrResolver) {
 		throw new Error(
 			"No Anthropic credentials found. Set ANTHROPIC_SEARCH_API_KEY or ANTHROPIC_API_KEY, or configure Anthropic OAuth.",
 		);
@@ -267,14 +280,42 @@ export async function searchAnthropic(
 	const model = getModel();
 	const systemPrompt = "authStorage" in params ? params.systemPrompt : params.system_prompt;
 	const maxTokens = "authStorage" in params ? params.maxOutputTokens : params.max_tokens;
-	const response = await callSearch(
-		auth,
-		model,
-		params.query,
-		systemPrompt,
-		maxTokens,
-		params.temperature,
-		params.signal,
+	const callerSessionId = "authStorage" in params ? params.sessionId : undefined;
+	const accountId =
+		"authStorage" in params ? params.authStorage.getOAuthAccountId("anthropic", params.sessionId) : undefined;
+	const response = await withAuth(
+		keyOrResolver,
+		key => {
+			const auth = buildAnthropicAuthConfig(key, searchBaseUrl);
+			// Mirror the main Messages path: OAuth requests need a Claude-Code-shaped
+			// metadata.user_id (`{session_id, account_uuid?, device_id}`) so the
+			// CC billing header + system fingerprint installed by
+			// `buildAnthropicSearchHeaders`/`buildSystemBlocks` line up with the
+			// attribution Anthropic and enterprise gateways expect. API-key tokens
+			// forward the raw session id verbatim.
+			const metadataUserId = resolveAnthropicMetadataUserId(
+				callerSessionId,
+				auth.isOAuth,
+				callerSessionId,
+				accountId,
+			);
+			return callSearch(
+				auth,
+				model,
+				params.query,
+				metadataUserId,
+				systemPrompt,
+				maxTokens,
+				params.temperature,
+				params.signal,
+				params.fetch,
+			);
+		},
+		{
+			signal: params.signal,
+			missingKeyMessage:
+				"No Anthropic credentials found. Set ANTHROPIC_SEARCH_API_KEY or ANTHROPIC_API_KEY, or configure Anthropic OAuth.",
+		},
 	);
 
 	const result = parseResponse(response);

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

@@ -1,4 +1,4 @@
-import type { AuthStorage } from "@prometheus-ai/ai";
+import type { AuthStorage, FetchImpl } from "@prometheus-ai/ai";
 import type { SearchProviderId, SearchResponse } from "../types";
 
 /**
@@ -30,6 +30,7 @@ export interface SearchParams {
 	recency?: "day" | "week" | "month" | "year";
 	systemPrompt: string;
 	signal?: AbortSignal;
+	fetch?: FetchImpl;
 	maxOutputTokens?: number;
 	numSearchResults?: number;
 	temperature?: number;

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

@@ -4,7 +4,7 @@
  * Calls Brave's web search REST API and maps results into the unified
  * SearchResponse shape used by the web search tool.
  */
-import { type AuthStorage, getEnvApiKey } from "@prometheus-ai/ai";
+import { type AuthStorage, type FetchImpl, getEnvApiKey } from "@prometheus-ai/ai";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { clampNumResults, dateToAgeSeconds } from "../utils";
@@ -28,6 +28,7 @@ export interface BraveSearchParams {
 	num_results?: number;
 	recency?: "day" | "week" | "month" | "year";
 	signal?: AbortSignal;
+	fetch?: FetchImpl;
 }
 
 interface BraveSearchResult {
@@ -80,7 +81,8 @@ async function callBraveSearch(
 		url.searchParams.set("freshness", RECENCY_MAP[params.recency]);
 	}
 
-	const response = await fetch(url, {
+	const fetchImpl = params.fetch ?? fetch;
+	const response = await fetchImpl(url, {
 		headers: {
 			Accept: "application/json",
 			"X-Subscription-Token": apiKey,
@@ -144,6 +146,7 @@ export class BraveProvider extends SearchProvider {
 			num_results: params.numSearchResults ?? params.limit,
 			recency: params.recency,
 			signal: params.signal,
+			fetch: params.fetch,
 		});
 	}
 }

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

@@ -7,8 +7,9 @@
  * SQLite store, never POSTs the broker sentinel to an OpenAI token endpoint.
  */
 import * as os from "node:os";
-import { type AuthStorage, getBundledModels } from "@prometheus-ai/ai";
-import { decodeJwt } from "@prometheus-ai/ai/utils/oauth/openai-codex";
+import { type AuthStorage, type FetchImpl, type OAuthAccess, withOAuthAccess } from "@prometheus-ai/ai";
+import { decodeJwt } from "@prometheus-ai/ai/oauth/openai-codex";
+import { getBundledModels } from "@prometheus-ai/catalog/models";
 import { $env, readSseJson } from "@prometheus-ai/utils";
 import packageJson from "../../../../package.json" with { type: "json" };
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
@@ -66,6 +67,7 @@ function shouldRetryWithNextDefaultModel(error: unknown): boolean {
 
 export interface CodexSearchParams {
 	signal?: AbortSignal;
+	fetch?: FetchImpl;
 	query: string;
 	system_prompt?: string;
 	num_results?: number;
@@ -114,8 +116,34 @@ interface CodexResponse {
 	usage?: CodexUsage;
 }
 
+/**
+ * Known Codex "image placeholder" answers — short prose the assistant emits in
+ * place of a real answer when it produced a screenshot instead of text. These
+ * carry no information, so callers treat them as non-answers and advance the
+ * chain to a provider that returns text. Extend by adding the normalized
+ * literal below; no regex tuning required.
+ */
+const IMAGE_PLACEHOLDER_ANSWERS: ReadonlySet<string> = new Set([
+	"see attached image",
+	"attached image",
+	"see the attached image",
+	"see image",
+	"see image above",
+	"image above",
+	"see image below",
+	"image below",
+]);
+
 function isImagePlaceholderAnswer(text: string): boolean {
-	return text.trim().toLowerCase() === "(see attached image)";
+	// Strip surrounding brackets/quotes and trailing punctuation, lowercase,
+	// then match against the known-placeholder set.
+	const normalized = text
+		.trim()
+		.replace(/^[[("'`*_]+/, "")
+		.replace(/[\])"'`*_.!?]+$/, "")
+		.trim()
+		.toLowerCase();
+	return IMAGE_PLACEHOLDER_ANSWERS.has(normalized);
 }
 
 function addSource(sources: SearchSource[], source: SearchSource): void {
@@ -259,12 +287,12 @@ async function findCodexAuth(
 	authStorage: AuthStorage,
 	sessionId: string | undefined,
 	signal: AbortSignal | undefined,
-): Promise<{ accessToken: string; accountId: string } | null> {
+): Promise<{ access: OAuthAccess; accountId: string } | null> {
 	const access = await authStorage.getOAuthAccess("openai-codex", sessionId, { signal });
 	if (!access) return null;
 	const accountId = access.accountId ?? getAccountIdFromJwt(access.accessToken);
 	if (!accountId) return null;
-	return { accessToken: access.accessToken, accountId };
+	return { access, accountId };
 }
 
 /**
@@ -275,8 +303,8 @@ function buildCodexHeaders(accessToken: string, accountId: string): Record<strin
 		Authorization: `Bearer ${accessToken}`,
 		"chatgpt-account-id": accountId,
 		"OpenAI-Beta": "responses=experimental",
-		originator: "prometheus",
-		"User-Agent": `prometheus/${packageJson.version} (${os.platform()} ${os.release()}; ${os.arch()})`,
+		originator: "pi",
+		"User-Agent": `pi/${packageJson.version} (${os.platform()} ${os.release()}; ${os.arch()})`,
 		Accept: "text/event-stream",
 		"Content-Type": "application/json",
 	};
@@ -296,6 +324,7 @@ async function callCodexSearch(
 		systemPrompt?: string;
 		searchContextSize?: "low" | "medium" | "high";
 		modelId: string;
+		fetch?: FetchImpl;
 	},
 ): Promise<{
 	answer: string;
@@ -330,7 +359,8 @@ async function callCodexSearch(
 		instructions: options.systemPrompt ?? DEFAULT_INSTRUCTIONS,
 	};
 
-	const response = await fetch(url, {
+	const fetchImpl = options.fetch ?? fetch;
+	const response = await fetchImpl(url, {
 		method: "POST",
 		headers,
 		body: JSON.stringify(body),
@@ -423,15 +453,18 @@ async function callCodexSearch(
 
 	const finalAnswer = answerParts.join("\n\n").trim();
 	const streamedAnswer = streamedAnswerParts.join("").trim();
-	if (isImagePlaceholderAnswer(finalAnswer) && streamedAnswer.length === 0) {
+	// Throw to advance the chain whenever Codex emitted nothing but image
+	// placeholder prose — including the case where the streamed delta itself
+	// is the placeholder (the model occasionally streams the same text it
+	// publishes as the final output_text).
+	const finalIsPlaceholder = finalAnswer.length > 0 && isImagePlaceholderAnswer(finalAnswer);
+	const streamedIsPlaceholder = streamedAnswer.length > 0 && isImagePlaceholderAnswer(streamedAnswer);
+	const hasFinalText = finalAnswer.length > 0 && !finalIsPlaceholder;
+	const hasStreamedText = streamedAnswer.length > 0 && !streamedIsPlaceholder;
+	if (!hasFinalText && !hasStreamedText && sources.length === 0) {
 		throw new SearchProviderError("codex", "Codex returned image-only response", 502);
 	}
-	const answer =
-		finalAnswer.length > 0 && !isImagePlaceholderAnswer(finalAnswer)
-			? finalAnswer
-			: streamedAnswer.length > 0
-				? streamedAnswer
-				: finalAnswer;
+	const answer = hasFinalText ? finalAnswer : hasStreamedText ? streamedAnswer : "";
 
 	// Fallback: when Codex omits url_citation annotations, scrape markdown links
 	// and bare URLs from the synthesized answer so callers still receive sources.
@@ -462,8 +495,8 @@ async function callCodexSearch(
  *   `gpt-5-codex-mini` first on ChatGPT accounts, which OpenAI rejects.
  */
 export async function searchCodex(params: SearchParams): Promise<SearchResponse> {
-	const auth = await findCodexAuth(params.authStorage, params.sessionId, params.signal);
-	if (!auth) {
+	const seed = await findCodexAuth(params.authStorage, params.sessionId, params.signal);
+	if (!seed) {
 		throw new Error(
 			"No Codex OAuth credentials found. Login with 'prometheus /login openai-codex' to enable Codex web search.",
 		);
@@ -472,41 +505,44 @@ export async function searchCodex(params: SearchParams): Promise<SearchResponse>
 	const configuredModel = getConfiguredModel();
 	const modelCandidates = configuredModel ? [configuredModel] : getDefaultModelCandidates();
 
-	let result:
-		| {
-				answer: string;
-				sources: SearchSource[];
-				model: string;
-				requestId: string;
-				usage?: { inputTokens: number; outputTokens: number; totalTokens: number };
-		  }
-		| undefined;
-	let lastError: unknown;
-
-	for (let index = 0; index < modelCandidates.length; index += 1) {
-		const modelId = modelCandidates[index];
-		if (!modelId) continue;
-
-		try {
-			result = await callCodexSearch(auth, params.query, {
-				signal: params.signal,
-				systemPrompt: params.systemPrompt,
-				searchContextSize: "high",
-				modelId,
-			});
-			break;
-		} catch (error) {
-			lastError = error;
-			const isLastCandidate = index === modelCandidates.length - 1;
-			if (configuredModel || isLastCandidate || !shouldRetryWithNextDefaultModel(error)) {
-				throw error;
+	const result = await withOAuthAccess(
+		params.authStorage,
+		"openai-codex",
+		async access => {
+			// Derive ALL auth material from the access this attempt received —
+			// a refreshed/rotated credential carries a different bearer and
+			// ChatGPT account id than the seed.
+			const accountId = access.accountId ?? getAccountIdFromJwt(access.accessToken);
+			if (!accountId) {
+				throw new Error("Codex OAuth credential is missing a ChatGPT account id");
 			}
-		}
-	}
-
-	if (!result) {
-		throw lastError ?? new Error("Codex search failed without returning a result");
-	}
+			const auth = { accessToken: access.accessToken, accountId };
+
+			let lastError: unknown;
+			for (let index = 0; index < modelCandidates.length; index += 1) {
+				const modelId = modelCandidates[index];
+				if (!modelId) continue;
+
+				try {
+					return await callCodexSearch(auth, params.query, {
+						signal: params.signal,
+						systemPrompt: params.systemPrompt,
+						searchContextSize: "high",
+						modelId,
+						fetch: params.fetch,
+					});
+				} catch (error) {
+					lastError = error;
+					const isLastCandidate = index === modelCandidates.length - 1;
+					if (configuredModel || isLastCandidate || !shouldRetryWithNextDefaultModel(error)) {
+						throw error;
+					}
+				}
+			}
+			throw lastError ?? new Error("Codex search failed without returning a result");
+		},
+		{ sessionId: params.sessionId, signal: params.signal, seed: seed.access },
+	);
 
 	let sources = result.sources;
 

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

@@ -6,10 +6,10 @@
  * Requests per-result summaries via `contents.summary` and synthesizes
  * them into a combined `answer` string on the SearchResponse.
  */
-import { type AuthStorage, getEnvApiKey } from "@prometheus-ai/ai";
+import { type ApiKey, type AuthStorage, type FetchImpl, getEnvApiKey, withAuth } from "@prometheus-ai/ai";
 import { settings } from "../../../config/settings";
-import { callExaTool, findApiKey, isSearchResponse } from "../../../exa/mcp-client";
-
+import { findApiKey, isSearchResponse } from "../../../exa/mcp-client";
+import { parseSSE } from "../../../mcp/json-rpc";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { dateToAgeSeconds } from "../utils";
@@ -32,6 +32,7 @@ export interface ExaSearchParams {
 	start_published_date?: string;
 	end_published_date?: string;
 	signal?: AbortSignal;
+	fetch?: FetchImpl;
 	/**
 	 * Credential source. Resolved before falling back to `EXA_API_KEY` so
 	 * Exa works when the key is stored via the broker/auth pipeline.
@@ -62,6 +63,48 @@ function asRecord(value: unknown): Record<string, unknown> | null {
 	return value as Record<string, unknown>;
 }
 
+function parseJsonContent(text: string): unknown | null {
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		return null;
+	}
+}
+
+function normalizeExaMcpPayload(payload: unknown): unknown {
+	const candidates: unknown[] = [];
+	const root = asRecord(payload);
+
+	if (root) {
+		if (root.structuredContent !== undefined) candidates.push(root.structuredContent);
+		if (root.data !== undefined) candidates.push(root.data);
+		if (root.result !== undefined) candidates.push(root.result);
+		candidates.push(root);
+
+		const content = root.content;
+		if (Array.isArray(content)) {
+			for (const item of content) {
+				const part = asRecord(item);
+				if (!part) continue;
+				const text = part.text;
+				if (typeof text !== "string" || text.trim().length === 0) continue;
+				const parsed = parseJsonContent(text);
+				if (parsed !== null) candidates.push(parsed);
+			}
+		}
+	} else {
+		candidates.push(payload);
+	}
+
+	for (const candidate of candidates) {
+		if (isSearchResponse(candidate)) {
+			return candidate;
+		}
+	}
+
+	return payload;
+}
+
 function parseOptionalField(section: string, label: string): string | null | undefined {
 	const regex = new RegExp(`(?:^|\\n)${label}:\\s*([^\\n]*)`);
 	const match = section.match(regex);
@@ -180,7 +223,8 @@ export function buildExaRequestBody(params: ExaSearchParams): Record<string, unk
 async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<ExaSearchResponse> {
 	const body = buildExaRequestBody(params);
 
-	const response = await fetch(EXA_API_URL, {
+	const fetchImpl = params.fetch ?? fetch;
+	const response = await fetchImpl(EXA_API_URL, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -211,14 +255,52 @@ function buildExaMcpArgs(params: ExaSearchParams): Record<string, unknown> {
 }
 
 async function callExaMcpSearch(params: ExaSearchParams): Promise<ExaSearchResponse> {
-	const response = await callExaTool("web_search_exa", buildExaMcpArgs(params), findApiKey(), {
+	const query = new URLSearchParams();
+	const apiKey = findApiKey();
+	if (apiKey) query.set("exaApiKey", apiKey);
+	query.set("tools", "web_search_exa");
+	const fetchImpl = params.fetch ?? fetch;
+	const response = await fetchImpl(`https://mcp.exa.ai/mcp?${query.toString()}`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify({
+			jsonrpc: "2.0",
+			id: Math.random().toString(36).slice(2),
+			method: "tools/call",
+			params: {
+				name: "web_search_exa",
+				arguments: buildExaMcpArgs(params),
+			},
+		}),
 		signal: withHardTimeout(params.signal),
 	});
-	if (isSearchResponse(response)) {
-		return response as ExaSearchResponse;
+	if (!response.ok) {
+		throw new Error(`MCP request failed: ${response.status} ${response.statusText}`);
+	}
+	const mcpResponse = parseSSE(await response.text()) as {
+		result?: {
+			content?: Array<{ type: string; text?: string }>;
+		};
+		error?: {
+			code: number;
+			message: string;
+		};
+	} | null;
+	if (!mcpResponse) {
+		throw new Error("Failed to parse MCP response");
+	}
+	if (mcpResponse.error) {
+		throw new Error(`MCP error: ${mcpResponse.error.message}`);
+	}
+	const responsePayload = normalizeExaMcpPayload(mcpResponse.result);
+	if (isSearchResponse(responsePayload)) {
+		return responsePayload as ExaSearchResponse;
 	}
 
-	const parsed = parseExaMcpTextPayload(response);
+	const parsed = parseExaMcpTextPayload(responsePayload);
 	if (parsed) {
 		return parsed;
 	}
@@ -228,11 +310,19 @@ async function callExaMcpSearch(params: ExaSearchParams): Promise<ExaSearchRespo
 
 /** Execute Exa web search */
 export async function searchExa(params: ExaSearchParams): Promise<SearchResponse> {
+	// AuthStorage-backed key takes precedence (existing behavior); probe it once
+	// so the env-key and keyless-MCP fallbacks below stay intact, then drive the
+	// authStorage path through the central force-refresh/rotate retry policy.
 	const storedKey = params.authStorage
 		? await params.authStorage.getApiKey("exa", params.sessionId, { signal: params.signal })
 		: undefined;
-	const apiKey = storedKey ?? getEnvApiKey("exa");
-	const response = apiKey ? await callExaSearch(apiKey, params) : await callExaMcpSearch(params);
+	const keyOrResolver: ApiKey | undefined =
+		storedKey && params.authStorage
+			? params.authStorage.resolver("exa", { sessionId: params.sessionId })
+			: getEnvApiKey("exa");
+	const response = keyOrResolver
+		? await withAuth(keyOrResolver, key => callExaSearch(key, params), { signal: params.signal })
+		: await callExaMcpSearch(params);
 
 	// Convert to unified SearchResponse
 	const sources: SearchSource[] = [];
@@ -304,6 +394,7 @@ export class ExaProvider extends SearchProvider {
 			signal: params.signal,
 			authStorage: params.authStorage,
 			sessionId: params.sessionId,
+			fetch: params.fetch,
 		});
 	}
 }