@oh-my-pi/pi-coding-agent 17.2.12 → 17.2.13

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, type FetchImpl, getEnvApiKey } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, type FetchImpl, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import type { QuerySyntax, StructuredQuery } from "../query";
@@ -17,6 +17,9 @@ import { classifyProviderHttpError, withHardTimeout } from "./utils";
 const BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search";
 const DEFAULT_NUM_RESULTS = 10;
 const MAX_NUM_RESULTS = 20;
+const MAX_QUERY_CHARACTERS = 500;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const MAX_ERROR_BYTES = 8 * 1024;
 
 const RECENCY_MAP: Record<"day" | "week" | "month" | "year", "pd" | "pw" | "pm" | "py"> = {
 	day: "pd",
@@ -51,62 +54,121 @@ export interface BraveSearchParams {
 	num_results?: number;
 	recency?: "day" | "week" | "month" | "year";
 	parsedQuery?: StructuredQuery;
+	/** Two-letter market code, or `ALL`. */
+	country?: string;
+	/** Brave search language code, such as `en` or `zh-hans`. */
+	search_lang?: string;
+	safesearch?: "off" | "moderate" | "strict";
+	authStorage: AuthStorage;
+	sessionId?: string;
 	signal?: AbortSignal;
 	timeoutMs?: number;
 	fetch?: FetchImpl;
 }
 
-interface BraveSearchResult {
-	title?: string | null;
-	url?: string | null;
-	description?: string | null;
-	age?: string | null;
-	extra_snippets?: string[] | null;
+interface BraveSearchResponse {
+	web?: unknown;
 }
 
-interface BraveSearchResponse {
-	web?: {
-		results?: BraveSearchResult[];
-	};
+function normalizeText(value: unknown, maxLength: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const text = value
+		.replace(/<[^>]*>/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	if (!text) return undefined;
+	return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
 }
 
-/** Find BRAVE_API_KEY from environment or .env files. */
-export function findApiKey(): string | null {
-	return getEnvApiKey("brave") ?? null;
+function normalizeUrl(value: unknown): string | undefined {
+	if (typeof value !== "string" || value.length > 2048) return undefined;
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+		return url.toString();
+	} catch {
+		return undefined;
+	}
 }
 
-function buildSnippet(result: BraveSearchResult): string | undefined {
-	const snippets: string[] = [];
+function webResults(response: BraveSearchResponse): readonly unknown[] {
+	if (typeof response.web !== "object" || response.web === null || !("results" in response.web)) return [];
+	return Array.isArray(response.web.results) ? response.web.results : [];
+}
 
-	if (result.description?.trim()) {
-		snippets.push(result.description.trim());
+async function readLimitedText(response: Response, maxBytes: number, truncate = false): Promise<string> {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	let buffer = new Uint8Array(Math.min(maxBytes, 64 * 1024));
+	let bytes = 0;
+
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const accepted = Math.min(value.byteLength, maxBytes - bytes);
+			const nextBytes = bytes + accepted;
+			if (nextBytes > buffer.byteLength) {
+				const grown = new Uint8Array(Math.min(maxBytes, Math.max(nextBytes, buffer.byteLength * 2)));
+				grown.set(buffer.subarray(0, bytes));
+				buffer = grown;
+			}
+			buffer.set(value.subarray(0, accepted), bytes);
+			bytes = nextBytes;
+			if (accepted < value.byteLength) {
+				await reader.cancel().catch(() => undefined);
+				if (!truncate) throw new SearchProviderError("brave", "Brave API response exceeded 2 MiB", 500);
+				break;
+			}
+		}
+	} finally {
+		reader.releaseLock();
 	}
 
-	if (Array.isArray(result.extra_snippets)) {
-		for (const snippet of result.extra_snippets) {
-			if (!snippet?.trim()) continue;
-			if (snippets.includes(snippet.trim())) continue;
-			snippets.push(snippet.trim());
+	return new TextDecoder().decode(buffer.subarray(0, bytes));
+}
+
+function buildSnippet(result: object): string | undefined {
+	const snippets = new Set<string>();
+	const description = normalizeText("description" in result ? result.description : undefined, 8_000);
+	if (description) snippets.add(description);
+
+	const extras = "extra_snippets" in result ? result.extra_snippets : undefined;
+	if (Array.isArray(extras)) {
+		for (const value of extras) {
+			const snippet = normalizeText(value, 8_000);
+			if (snippet) snippets.add(snippet);
 		}
 	}
 
-	return snippets.length > 0 ? snippets.join("\n") : undefined;
+	const combined = [...snippets].join("\n");
+	return combined ? (combined.length <= 8_000 ? combined : `${combined.slice(0, 7_999)}…`) : undefined;
 }
 
 async function callBraveSearch(
 	apiKey: string,
 	params: BraveSearchParams,
 ): Promise<{ response: BraveSearchResponse; requestId?: string }> {
-	const numResults = clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
+	const numResults = Math.floor(clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS));
 	const parsed = params.parsedQuery ?? parseSearchQuery(params.query);
+	const query = parsed.hasDirectives ? formatQuery(parsed, BRAVE_QUERY_SYNTAX) : params.query;
+	if (query.length > MAX_QUERY_CHARACTERS) {
+		throw new SearchProviderError(
+			"brave",
+			`Brave search queries cannot exceed ${MAX_QUERY_CHARACTERS} characters`,
+			400,
+		);
+	}
 	const url = new URL(BRAVE_SEARCH_URL);
-	url.searchParams.set("q", parsed.hasDirectives ? formatQuery(parsed, BRAVE_QUERY_SYNTAX) : params.query);
+	url.searchParams.set("q", query);
 	url.searchParams.set("count", String(numResults));
 	url.searchParams.set("extra_snippets", "true");
+	url.searchParams.set("text_decorations", "false");
+	url.searchParams.set("safesearch", params.safesearch ?? "moderate");
+	if (params.country) url.searchParams.set("country", params.country.toUpperCase());
+	if (params.search_lang) url.searchParams.set("search_lang", params.search_lang);
 	const freshness = braveFreshness(parsed, params.recency);
-	if (freshness) {
-		url.searchParams.set("freshness", freshness);
-	}
+	if (freshness) url.searchParams.set("freshness", freshness);
 
 	const fetchImpl = params.fetch ?? fetch;
 	const response = await fetchImpl(url, {
@@ -118,36 +180,46 @@ async function callBraveSearch(
 	});
 
 	if (!response.ok) {
-		const errorText = await response.text();
+		const errorText = await readLimitedText(response, MAX_ERROR_BYTES, true);
 		const classified = classifyProviderHttpError("brave", response.status, errorText);
 		if (classified) throw classified;
 		throw new SearchProviderError("brave", `Brave API error (${response.status}): ${errorText}`, response.status);
 	}
 
-	const data = (await response.json()) as BraveSearchResponse;
+	const raw = await readLimitedText(response, MAX_RESPONSE_BYTES);
+	let data: BraveSearchResponse;
+	try {
+		data = JSON.parse(raw) as BraveSearchResponse;
+	} catch {
+		throw new SearchProviderError("brave", "Brave API returned invalid JSON", 500);
+	}
 	const requestId = response.headers.get("x-request-id") ?? response.headers.get("request-id") ?? undefined;
 	return { response: data, requestId };
 }
 
 /** Execute Brave web search. */
 export async function searchBrave(params: BraveSearchParams): Promise<SearchResponse> {
-	const numResults = clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
-	const apiKey = findApiKey();
-	if (!apiKey) {
-		throw new Error("BRAVE_API_KEY not found. Set it in environment or .env file.");
-	}
-
-	const { response, requestId } = await callBraveSearch(apiKey, params);
+	const numResults = Math.floor(clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS));
+	const keyOrResolver: ApiKey = params.authStorage.resolver("brave", {
+		sessionId: params.sessionId,
+	});
+	const { response, requestId } = await withAuth(keyOrResolver, key => callBraveSearch(key, params), {
+		signal: params.signal,
+		missingKeyMessage: 'Brave credentials not found. Set BRAVE_API_KEY or configure an API key for provider "brave".',
+	});
 	const sources: SearchSource[] = [];
 
-	for (const result of response.web?.results ?? []) {
-		if (!result.url) continue;
+	for (const result of webResults(response)) {
+		if (typeof result !== "object" || result === null) continue;
+		const url = normalizeUrl("url" in result ? result.url : undefined);
+		if (!url) continue;
+		const publishedDate = normalizeText("age" in result ? result.age : undefined, 100);
 		sources.push({
-			title: result.title ?? result.url,
-			url: result.url,
+			title: normalizeText("title" in result ? result.title : undefined, 300) ?? url,
+			url,
 			snippet: buildSnippet(result),
-			publishedDate: result.age ?? undefined,
-			ageSeconds: dateToAgeSeconds(result.age),
+			publishedDate,
+			ageSeconds: dateToAgeSeconds(publishedDate),
 		});
 	}
 
@@ -155,6 +227,7 @@ export async function searchBrave(params: BraveSearchParams): Promise<SearchResp
 		provider: "brave",
 		sources: sources.slice(0, numResults),
 		requestId,
+		authMode: "api_key",
 	};
 }
 
@@ -163,8 +236,8 @@ export class BraveProvider extends SearchProvider {
 	readonly id = "brave";
 	readonly label = "Brave";
 
-	isAvailable(_authStorage: AuthStorage): boolean {
-		return !!findApiKey();
+	isAvailable(authStorage: AuthStorage): boolean {
+		return authStorage.hasAuth("brave") || !!getEnvApiKey("brave");
 	}
 
 	search(params: SearchParams): Promise<SearchResponse> {
@@ -173,6 +246,8 @@ export class BraveProvider extends SearchProvider {
 			num_results: params.numSearchResults ?? params.limit,
 			recency: params.recency,
 			parsedQuery: params.parsedQuery,
+			authStorage: params.authStorage,
+			sessionId: params.sessionId,
 			signal: params.signal,
 			timeoutMs: params.timeoutMs,
 			fetch: params.fetch,

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

@@ -4,7 +4,6 @@
  * Uses the configured Codex Responses transport for proxy/API-key setups and
  * the official ChatGPT backend for OAuth logins.
  */
-import * as os from "node:os";
 import {
 	type AuthStorage,
 	type FetchImpl,
@@ -22,8 +21,7 @@ import {
 	OPENAI_HEADER_VALUES,
 	OPENAI_HEADERS,
 } from "@oh-my-pi/pi-catalog/wire/codex";
-import { $env, readSseJson } from "@oh-my-pi/pi-utils";
-import packageJson from "../../../../package.json" with { type: "json" };
+import { $env, readSseJson, USER_AGENT } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../../../config/model-registry";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
@@ -151,6 +149,13 @@ export interface CodexSearchParams {
 }
 
 /** Codex API response structure */
+interface CodexWebSearchSource {
+	url?: string;
+	source_website_url?: string;
+	title?: string;
+	caption?: string;
+}
+
 interface CodexResponseItem {
 	type: string;
 	id?: string;
@@ -161,6 +166,9 @@ interface CodexResponseItem {
 	arguments?: string;
 	content?: CodexContentPart[];
 	summary?: Array<{ type: string; text: string }>;
+	action?: { sources?: CodexWebSearchSource[] };
+	sources?: CodexWebSearchSource[];
+	results?: CodexWebSearchSource[];
 }
 
 interface CodexContentPart {
@@ -221,12 +229,45 @@ function isImagePlaceholderAnswer(text: string): boolean {
 	return IMAGE_PLACEHOLDER_ANSWERS.has(normalized);
 }
 
+function cleanSourceUrl(rawUrl: string): string {
+	try {
+		const url = new URL(rawUrl);
+		if (url.searchParams.get("utm_source") === "openai") {
+			url.searchParams.delete("utm_source");
+		}
+		return url.toString();
+	} catch {
+		return rawUrl.replace(/[?&]utm_source=openai$/u, "");
+	}
+}
+
 function addSource(sources: SearchSource[], source: SearchSource): void {
-	if (!sources.some(existing => existing.url === source.url)) {
-		sources.push(source);
+	const normalizedSource = { ...source, url: cleanSourceUrl(source.url) };
+	const existing = sources.find(candidate => candidate.url === normalizedSource.url);
+	if (!existing) {
+		sources.push(normalizedSource);
+		return;
+	}
+	if (existing.title === existing.url && normalizedSource.title !== normalizedSource.url) {
+		existing.title = normalizedSource.title;
+	}
+	if (!existing.snippet && normalizedSource.snippet) {
+		existing.snippet = normalizedSource.snippet;
 	}
 }
 
+function extractCitationSnippet(text: string, start: number | undefined, end: number | undefined): string | undefined {
+	if (start === undefined || end === undefined || !text) return undefined;
+	const before = Math.max(0, start - 100);
+	const after = Math.min(text.length, end + 100);
+	const snippet = text
+		.slice(before, after)
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+		.trim();
+	if (!snippet) return undefined;
+	return snippet.length > 300 ? `${snippet.slice(0, 297)}...` : snippet;
+}
+
 function countCharacter(text: string, target: string): number {
 	let count = 0;
 	for (const char of text) {
@@ -398,7 +439,7 @@ function buildCodexHeaders(
 	headers.set(OPENAI_HEADERS.BETA, OPENAI_HEADER_VALUES.BETA_RESPONSES);
 	headers.set(OPENAI_HEADERS.ORIGINATOR, OPENAI_HEADER_VALUES.ORIGINATOR_CODEX);
 	headers.set(OPENAI_HEADERS.VERSION, CODEX_CLIENT_VERSION);
-	headers.set("User-Agent", `pi/${packageJson.version} (${os.platform()} ${os.release()}; ${os.arch()})`);
+	headers.set("User-Agent", USER_AGENT);
 	headers.set("Accept", "text/event-stream");
 	headers.set("Content-Type", "application/json");
 	return headers;
@@ -428,6 +469,15 @@ function extractCodexSseError(rawEvent: Record<string, unknown>): { code: string
 	return { code, message };
 }
 
+function classifyCodexSseErrorStatus(code: string, message: string): number {
+	const detail = `${code} ${message}`.toLowerCase();
+	if (/rate[- ]?limit|too many requests|quota|\b429\b/u.test(detail)) return 429;
+	if (/unauthori[sz]ed|\b401\b/u.test(detail)) return 401;
+	if (/forbidden|\b403\b/u.test(detail)) return 403;
+	if (/timeout|timed out/u.test(detail)) return 504;
+	return 500;
+}
+
 /**
  * Calls the Codex Responses API with web search tool enabled.
  * The caller provides the exact model id to send; retry / fallback policy
@@ -455,6 +505,8 @@ async function callCodexSearch(
 		model: requestedModel,
 		stream: true,
 		store: false,
+		include: ["web_search_call.action.sources"],
+		parallel_tool_calls: true,
 		input: [
 			{
 				type: "message",
@@ -510,7 +562,11 @@ async function callCodexSearch(
 			webSearchInvoked = true;
 		}
 
-		if (eventType === "response.output_text.delta") {
+		if (eventType === "response.created") {
+			const resp = (rawEvent as { response?: CodexResponse }).response;
+			if (resp?.id) requestId = resp.id;
+			if (resp?.model) model = resp.model;
+		} else if (eventType === "response.output_text.delta") {
 			const delta = typeof rawEvent.delta === "string" ? rawEvent.delta : "";
 			if (delta) {
 				streamedAnswerParts.push(delta);
@@ -518,7 +574,20 @@ async function callCodexSearch(
 		} else if (eventType === "response.output_item.done") {
 			const item = rawEvent.item as CodexResponseItem | undefined;
 			if (!item) continue;
-			if (item.type === "web_search_call") webSearchInvoked = true;
+			if (item.type === "web_search_call") {
+				webSearchInvoked = true;
+				const sourceGroups = [item.action?.sources, item.sources, item.results];
+				for (const group of sourceGroups) {
+					for (const source of group ?? []) {
+						const url = source.url ?? source.source_website_url;
+						if (!url) continue;
+						addSource(sources, {
+							title: source.title ?? source.caption ?? url,
+							url,
+						});
+					}
+				}
+			}
 
 			// Handle text message content and extract sources from annotations
 			if (item.type === "message" && item.content) {
@@ -530,8 +599,11 @@ async function callCodexSearch(
 						if (part.annotations) {
 							for (const annotation of part.annotations) {
 								if (annotation.type === "url_citation" && annotation.url) {
-									// Deduplicate by URL
-									addSource(sources, { title: annotation.title ?? annotation.url, url: annotation.url });
+									addSource(sources, {
+										title: annotation.title ?? annotation.url,
+										url: annotation.url,
+										snippet: extractCitationSnippet(part.text, annotation.start_index, annotation.end_index),
+									});
 								}
 							}
 						}
@@ -563,13 +635,17 @@ async function callCodexSearch(
 			}
 		} else if (eventType === "error") {
 			const { code, message } = extractCodexSseError(rawEvent);
-			throw new SearchProviderError("codex", `Codex error (${code}): ${message || "Unknown error"}`, 500);
+			throw new SearchProviderError(
+				"codex",
+				`Codex error (${code}): ${message || "Unknown error"}`,
+				classifyCodexSseErrorStatus(code, message),
+			);
 		} else if (eventType === "response.failed") {
 			const { code, message } = extractCodexSseError(rawEvent);
 			const detail = code
 				? `Codex request failed (${code}): ${message || "Request failed"}`
 				: `Codex request failed: ${message || "Request failed"}`;
-			throw new SearchProviderError("codex", detail, 500);
+			throw new SearchProviderError("codex", detail, classifyCodexSseErrorStatus(code, message));
 		}
 	}
 

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

@@ -19,6 +19,9 @@ import { SearchProvider } from "./base";
 import { classifyProviderHttpError, withHardTimeout } from "./utils";
 
 const EXA_API_URL = "https://api.exa.ai/search";
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+const EXA_MCP_SOURCE = "oh-my-pi";
+const MAX_EXA_SNIPPET_CHARS = 500;
 const DEFAULT_EXA_SEARCH_DELAY_MS = getDefault("exa.searchDelayMs");
 
 let nextExaSearchRequestAt = 0;
@@ -329,13 +332,20 @@ async function callExaSearch(apiKey: string, params: ExaSearchParams): Promise<E
 	return response.json() as Promise<ExaSearchResponse>;
 }
 function buildExaMcpArgs(params: ExaSearchParams): Record<string, unknown> {
-	const args: Record<string, unknown> = { query: params.query };
-	if (params.num_results !== undefined) args.num_results = params.num_results;
-	if (params.type !== undefined) args.type = params.type;
-	if (params.include_domains !== undefined) args.include_domains = params.include_domains;
-	if (params.exclude_domains !== undefined) args.exclude_domains = params.exclude_domains;
-	if (params.start_published_date !== undefined) args.start_published_date = params.start_published_date;
-	if (params.end_published_date !== undefined) args.end_published_date = params.end_published_date;
+	const queryParts = [params.query];
+	for (const domain of params.include_domains ?? []) {
+		const trimmed = domain.trim();
+		if (trimmed) queryParts.push(`site:${trimmed}`);
+	}
+	for (const domain of params.exclude_domains ?? []) {
+		const trimmed = domain.trim();
+		if (trimmed) queryParts.push(`-site:${trimmed}`);
+	}
+	if (params.start_published_date) queryParts.push(`after:${params.start_published_date}`);
+	if (params.end_published_date) queryParts.push(`before:${params.end_published_date}`);
+
+	const args: Record<string, unknown> = { query: queryParts.join(" ") };
+	if (params.num_results !== undefined) args.numResults = params.num_results;
 	return args;
 }
 
@@ -346,11 +356,12 @@ async function callExaMcpSearch(params: ExaSearchParams): Promise<ExaSearchRespo
 	query.set("tools", "web_search_exa");
 	const fetchImpl = params.fetch ?? fetch;
 	await waitForExaSearchSlot(params.signal);
-	const response = await fetchImpl(`https://mcp.exa.ai/mcp?${query.toString()}`, {
+	const response = await fetchImpl(`${EXA_MCP_URL}?${query.toString()}`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
 			Accept: "application/json, text/event-stream",
+			"x-exa-source": EXA_MCP_SOURCE,
 		},
 		body: JSON.stringify({
 			jsonrpc: "2.0",
@@ -364,11 +375,26 @@ async function callExaMcpSearch(params: ExaSearchParams): Promise<ExaSearchRespo
 		signal: withHardTimeout(params.signal, params.timeoutMs),
 	});
 	if (!response.ok) {
-		throw new Error(`MCP request failed: ${response.status} ${response.statusText}`);
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("exa", response.status, errorText);
+		if (classified) throw classified;
+		if (response.status === 429) {
+			throw new SearchProviderError(
+				"exa",
+				"exa: MCP rate limit reached (429); configure an Exa API key for higher limits",
+				response.status,
+			);
+		}
+		throw new SearchProviderError(
+			"exa",
+			`Exa MCP request failed (${response.status}): ${errorText}`,
+			response.status,
+		);
 	}
 	const mcpResponse = parseSSE(await response.text()) as {
 		result?: {
 			content?: Array<{ type: string; text?: string }>;
+			isError?: boolean;
 		};
 		error?: {
 			code: number;
@@ -381,6 +407,12 @@ async function callExaMcpSearch(params: ExaSearchParams): Promise<ExaSearchRespo
 	if (mcpResponse.error) {
 		throw new Error(`MCP error: ${mcpResponse.error.message}`);
 	}
+	if (mcpResponse.result?.isError) {
+		const message = mcpResponse.result.content
+			?.find(item => item.type === "text" && typeof item.text === "string")
+			?.text?.trim();
+		throw new SearchProviderError("exa", message || "Exa MCP returned an error");
+	}
 	const responsePayload = normalizeExaMcpPayload(mcpResponse.result);
 	if (isSearchResponse(responsePayload)) {
 		return responsePayload as ExaSearchResponse;
@@ -419,7 +451,10 @@ export async function searchExa(params: ExaSearchParams): Promise<SearchResponse
 			sources.push({
 				title: result.title ?? result.url,
 				url: result.url,
-				snippet: result.summary || result.text || result.highlights?.join(" ") || undefined,
+				snippet: (result.summary || result.text || result.highlights?.join(" ") || undefined)?.slice(
+					0,
+					MAX_EXA_SNIPPET_CHARS,
+				),
 				publishedDate: result.publishedDate ?? undefined,
 				ageSeconds: dateToAgeSeconds(result.publishedDate ?? undefined),
 				author: result.author ?? undefined,

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

@@ -20,7 +20,7 @@ import type { SearchParams } from "./base";
 import { SearchProvider } from "./base";
 import { classifyProviderHttpError, withHardTimeout } from "./utils";
 
-const FIRECRAWL_SEARCH_URL = "https://api.firecrawl.dev/v2/search";
+const FIRECRAWL_DEFAULT_BASE_URL = "https://api.firecrawl.dev/v2";
 const DEFAULT_NUM_RESULTS = 10;
 const MAX_NUM_RESULTS = 100;
 
@@ -30,6 +30,28 @@ const RECENCY_TBS: Record<NonNullable<SearchParams["recency"]>, string> = {
 	month: "qdr:m",
 	year: "qdr:y",
 };
+function resolveSearchUrl(): string {
+	const configured = process.env.FIRECRAWL_BASE_URL ?? process.env.FIRECRAWL_API_URL;
+	if (!configured?.trim()) return `${FIRECRAWL_DEFAULT_BASE_URL}/search`;
+	let url: URL;
+	try {
+		url = new URL(configured.trim());
+	} catch {
+		throw new Error("Invalid Firecrawl base URL: expected an HTTP or HTTPS URL");
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") {
+		throw new Error("Invalid Firecrawl base URL: expected an HTTP or HTTPS URL");
+	}
+	if (url.username || url.password) {
+		throw new Error("Invalid Firecrawl base URL: URL credentials are not allowed");
+	}
+	url.search = "";
+	url.hash = "";
+	url.pathname = url.pathname.replace(/\/+$/, "");
+	if (!/\/v[12]$/i.test(url.pathname)) url.pathname += "/v2";
+	url.pathname += "/search";
+	return url.toString();
+}
 
 export interface FirecrawlSearchParams {
 	query: string;
@@ -46,14 +68,23 @@ interface FirecrawlWebResult {
 	title?: string | null;
 	url?: string | null;
 	description?: string | null;
+	snippet?: string | null;
 	markdown?: string | null;
 }
 
 interface FirecrawlSearchResponse {
+	success?: boolean;
+	error?: string | null;
 	id?: string | null;
-	data?: {
-		web?: FirecrawlWebResult[] | null;
-	} | null;
+	data?:
+		| FirecrawlWebResult[]
+		| {
+				web?: FirecrawlWebResult[] | null;
+				news?: FirecrawlWebResult[] | null;
+				images?: FirecrawlWebResult[] | null;
+		  }
+		| null;
+	results?: FirecrawlWebResult[] | null;
 }
 
 /** Resolve Firecrawl API key through the shared auth storage pipeline. */
@@ -88,7 +119,7 @@ async function callFirecrawlSearch(
 	if (apiKey) {
 		headers.Authorization = `Bearer ${apiKey}`;
 	}
-	const response = await (params.fetch ?? fetch)(FIRECRAWL_SEARCH_URL, {
+	const response = await (params.fetch ?? fetch)(resolveSearchUrl(), {
 		method: "POST",
 		headers,
 		body: JSON.stringify(buildRequestBody(params)),
@@ -106,7 +137,11 @@ async function callFirecrawlSearch(
 		);
 	}
 
-	return (await response.json()) as FirecrawlSearchResponse;
+	const data = (await response.json()) as FirecrawlSearchResponse;
+	if (data.success === false) {
+		throw new SearchProviderError("firecrawl", data.error?.trim() || "Firecrawl request failed");
+	}
+	return data;
 }
 
 /** ISO `YYYY-MM-DD` to Google `MM/DD/YYYY` for `tbs=cdr` custom date ranges. */
@@ -128,6 +163,11 @@ function buildDateTbs(parsed: StructuredQuery): string | undefined {
 	return parts.join(",");
 }
 
+function getWebResults(data: FirecrawlSearchResponse): FirecrawlWebResult[] {
+	if (Array.isArray(data.data)) return data.data;
+	if (data.data && Array.isArray(data.data.web)) return data.data.web;
+	return data.results ?? [];
+}
 /** Execute Firecrawl web search. */
 export async function searchFirecrawl(params: SearchParams): Promise<SearchResponse> {
 	const parsed = params.parsedQuery ?? parseSearchQuery(params.query);
@@ -169,12 +209,12 @@ export async function searchFirecrawl(params: SearchParams): Promise<SearchRespo
 
 	const sources: SearchSource[] = [];
 
-	for (const result of data.data?.web ?? []) {
+	for (const result of getWebResults(data)) {
 		if (!result.url) continue;
 		sources.push({
 			title: result.title ?? result.url,
 			url: result.url,
-			snippet: result.description ?? result.markdown ?? undefined,
+			snippet: result.description ?? result.snippet ?? result.markdown ?? undefined,
 		});
 	}
 
@@ -192,11 +232,13 @@ export class FirecrawlProvider extends SearchProvider {
 	readonly label = "Firecrawl";
 
 	/**
-	 * Auto-chain admission: requires a credential so an unconfigured Firecrawl
-	 * doesn't displace other providers that the user has set up with API keys.
+	 * Auto-chain admission requires either a credential or an explicitly
+	 * configured self-hosted endpoint. Hosted keyless mode remains explicit-only
+	 * so it does not displace providers the user configured.
 	 */
 	isAvailable(authStorage: AuthStorage): boolean {
-		return authStorage.hasAuth("firecrawl") || !!getEnvApiKey("firecrawl");
+		const configuredBaseUrl = process.env.FIRECRAWL_BASE_URL ?? process.env.FIRECRAWL_API_URL;
+		return !!configuredBaseUrl?.trim() || authStorage.hasAuth("firecrawl") || !!getEnvApiKey("firecrawl");
 	}
 
 	/**