@oh-my-pi/pi-coding-agent 16.1.23 → 16.2.1

package/src/web/search/provider.ts

@@ -24,66 +24,81 @@ interface ProviderMeta {
 
 /** Lazy factories. Each `load()` dynamic-imports its provider module on first call. */
 const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
-	exa: {
-		id: "exa",
-		label: SEARCH_PROVIDER_LABELS.exa,
-		load: async () => new (await import("./providers/exa")).ExaProvider(),
-	},
-	brave: {
-		id: "brave",
-		label: SEARCH_PROVIDER_LABELS.brave,
-		load: async () => new (await import("./providers/brave")).BraveProvider(),
-	},
-	jina: {
-		id: "jina",
-		label: SEARCH_PROVIDER_LABELS.jina,
-		load: async () => new (await import("./providers/jina")).JinaProvider(),
-	},
 	perplexity: {
 		id: "perplexity",
 		label: SEARCH_PROVIDER_LABELS.perplexity,
 		load: async () => new (await import("./providers/perplexity")).PerplexityProvider(),
 	},
-	kimi: {
-		id: "kimi",
-		label: SEARCH_PROVIDER_LABELS.kimi,
-		load: async () => new (await import("./providers/kimi")).KimiProvider(),
-	},
-	zai: {
-		id: "zai",
-		label: SEARCH_PROVIDER_LABELS.zai,
-		load: async () => new (await import("./providers/zai")).ZaiProvider(),
+	gemini: {
+		id: "gemini",
+		label: SEARCH_PROVIDER_LABELS.gemini,
+		load: async () => new (await import("./providers/gemini")).GeminiProvider(),
 	},
 	anthropic: {
 		id: "anthropic",
 		label: SEARCH_PROVIDER_LABELS.anthropic,
 		load: async () => new (await import("./providers/anthropic")).AnthropicProvider(),
 	},
-	gemini: {
-		id: "gemini",
-		label: SEARCH_PROVIDER_LABELS.gemini,
-		load: async () => new (await import("./providers/gemini")).GeminiProvider(),
-	},
 	codex: {
 		id: "codex",
 		label: SEARCH_PROVIDER_LABELS.codex,
 		load: async () => new (await import("./providers/codex")).CodexProvider(),
 	},
+	xai: {
+		id: "xai",
+		label: SEARCH_PROVIDER_LABELS.xai,
+		load: async () => new (await import("./providers/xai")).XAIProvider(),
+	},
+	zai: {
+		id: "zai",
+		label: SEARCH_PROVIDER_LABELS.zai,
+		load: async () => new (await import("./providers/zai")).ZaiProvider(),
+	},
+	exa: {
+		id: "exa",
+		label: SEARCH_PROVIDER_LABELS.exa,
+		load: async () => new (await import("./providers/exa")).ExaProvider(),
+	},
+	tinyfish: {
+		id: "tinyfish",
+		label: SEARCH_PROVIDER_LABELS.tinyfish,
+		load: async () => new (await import("./providers/tinyfish")).TinyFishProvider(),
+	},
+	jina: {
+		id: "jina",
+		label: SEARCH_PROVIDER_LABELS.jina,
+		load: async () => new (await import("./providers/jina")).JinaProvider(),
+	},
+	kagi: {
+		id: "kagi",
+		label: SEARCH_PROVIDER_LABELS.kagi,
+		load: async () => new (await import("./providers/kagi")).KagiProvider(),
+	},
 	tavily: {
 		id: "tavily",
 		label: SEARCH_PROVIDER_LABELS.tavily,
 		load: async () => new (await import("./providers/tavily")).TavilyProvider(),
 	},
+	firecrawl: {
+		id: "firecrawl",
+		label: SEARCH_PROVIDER_LABELS.firecrawl,
+		load: async () => new (await import("./providers/firecrawl")).FirecrawlProvider(),
+	},
+	brave: {
+		id: "brave",
+		label: SEARCH_PROVIDER_LABELS.brave,
+		load: async () => new (await import("./providers/brave")).BraveProvider(),
+	},
+	kimi: {
+		id: "kimi",
+		label: SEARCH_PROVIDER_LABELS.kimi,
+		load: async () => new (await import("./providers/kimi")).KimiProvider(),
+	},
 	parallel: {
 		id: "parallel",
 		label: SEARCH_PROVIDER_LABELS.parallel,
 		load: async () => new (await import("./providers/parallel")).ParallelProvider(),
 	},
-	kagi: {
-		id: "kagi",
-		label: SEARCH_PROVIDER_LABELS.kagi,
-		load: async () => new (await import("./providers/kagi")).KagiProvider(),
-	},
 	synthetic: {
 		id: "synthetic",
 		label: SEARCH_PROVIDER_LABELS.synthetic,
@@ -94,6 +109,11 @@ const PROVIDER_META: Record<SearchProviderId, ProviderMeta> = {
 		label: SEARCH_PROVIDER_LABELS.searxng,
 		load: async () => new (await import("./providers/searxng")).SearXNGProvider(),
 	},
+	duckduckgo: {
+		id: "duckduckgo",
+		label: SEARCH_PROVIDER_LABELS.duckduckgo,
+		load: async () => new (await import("./providers/duckduckgo")).DuckDuckGoProvider(),
+	},
 };
 
 const instanceCache = new Map<SearchProviderId, SearchProvider>();

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

@@ -0,0 +1,140 @@
+import type { AuthStorage } from "@oh-my-pi/pi-ai";
+import type { SearchResponse, SearchSource } from "../../../web/search/types";
+import { SearchProviderError } from "../../../web/search/types";
+import { clampNumResults } from "../utils";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+import { classifyProviderHttpError, withHardTimeout } from "./utils";
+
+const DUCKDUCKGO_SEARCH_URL = "https://api.duckduckgo.com/";
+const DEFAULT_NUM_RESULTS = 10;
+const MAX_NUM_RESULTS = 20;
+
+interface DuckDuckGoTopic {
+	FirstURL?: string | null;
+	Text?: string | null;
+	Topics?: DuckDuckGoTopic[] | null;
+}
+
+interface DuckDuckGoResponse {
+	AbstractText?: string | null;
+	AbstractURL?: string | null;
+	AbstractSource?: string | null;
+	Answer?: string | null;
+	Definition?: string | null;
+	Heading?: string | null;
+	Results?: DuckDuckGoTopic[] | null;
+	RelatedTopics?: DuckDuckGoTopic[] | null;
+}
+
+function cleanText(value: string | null | undefined): string | undefined {
+	const cleaned = value
+		?.replace(/<[^>]*>/g, " ")
+		.replace(/&nbsp;/gi, " ")
+		.replace(/&amp;/gi, "&")
+		.replace(/&lt;/gi, "<")
+		.replace(/&gt;/gi, ">")
+		.replace(/&quot;/gi, '"')
+		.replace(/&#39;/gi, "'")
+		.replace(/\s+/g, " ")
+		.trim();
+	return cleaned ? cleaned : undefined;
+}
+
+function addSource(sources: SearchSource[], source: SearchSource): void {
+	if (!source.url || sources.some(existing => existing.url === source.url)) return;
+	sources.push(source);
+}
+
+function addTopicSource(sources: SearchSource[], topic: DuckDuckGoTopic): void {
+	const url = topic.FirstURL?.trim();
+	if (!url) return;
+	const text = cleanText(topic.Text);
+	addSource(sources, {
+		title: text ?? url,
+		url,
+		snippet: text,
+	});
+}
+
+function collectTopicSources(sources: SearchSource[], topics: readonly DuckDuckGoTopic[] | null | undefined): void {
+	if (!topics) return;
+	for (const topic of topics) {
+		addTopicSource(sources, topic);
+		collectTopicSources(sources, topic.Topics);
+	}
+}
+
+async function callDuckDuckGoSearch(params: SearchParams): Promise<DuckDuckGoResponse> {
+	const queryString = [
+		["q", params.query],
+		["format", "json"],
+		["no_redirect", "1"],
+		["no_html", "1"],
+		["skip_disambig", "1"],
+		["t", "oh-my-pi"],
+	]
+		.map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+		.join("&");
+	const response = await (params.fetch ?? fetch)(`${DUCKDUCKGO_SEARCH_URL}?${queryString}`, {
+		method: "GET",
+		signal: withHardTimeout(params.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("duckduckgo", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError(
+			"duckduckgo",
+			`DuckDuckGo API error (${response.status}): ${errorText}`,
+			response.status,
+		);
+	}
+
+	return (await response.json()) as DuckDuckGoResponse;
+}
+
+/** Execute DuckDuckGo Instant Answer API search. */
+export async function searchDuckDuckGo(params: SearchParams): Promise<SearchResponse> {
+	const numResults = clampNumResults(params.numSearchResults ?? params.limit, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
+	const data = await callDuckDuckGoSearch(params);
+	const answer = cleanText(data.AbstractText) ?? cleanText(data.Answer) ?? cleanText(data.Definition);
+	const sources: SearchSource[] = [];
+
+	const abstractUrl = data.AbstractURL?.trim();
+	if (abstractUrl) {
+		addSource(sources, {
+			title: cleanText(data.AbstractSource) ?? cleanText(data.Heading) ?? abstractUrl,
+			url: abstractUrl,
+			snippet: cleanText(data.AbstractText),
+		});
+	}
+
+	collectTopicSources(sources, data.Results);
+	collectTopicSources(sources, data.RelatedTopics);
+
+	return {
+		provider: "duckduckgo",
+		answer,
+		sources: sources.slice(0, numResults),
+	};
+}
+
+/** Search provider for DuckDuckGo Instant Answer API. */
+export class DuckDuckGoProvider extends SearchProvider {
+	readonly id = "duckduckgo";
+	readonly label = "DuckDuckGo";
+
+	isAvailable(_authStorage: AuthStorage): boolean {
+		return true;
+	}
+
+	isExplicitlyAvailable(_authStorage: AuthStorage): boolean {
+		return true;
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchDuckDuckGo(params);
+	}
+}

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

@@ -0,0 +1,144 @@
+/**
+ * Firecrawl Web Search Provider
+ *
+ * Calls Firecrawl's search API and maps web results into the unified
+ * SearchResponse shape used by the web search tool.
+ */
+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 { clampNumResults } from "../utils";
+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 DEFAULT_NUM_RESULTS = 10;
+const MAX_NUM_RESULTS = 100;
+
+const RECENCY_TBS: Record<NonNullable<SearchParams["recency"]>, string> = {
+	day: "qdr:d",
+	week: "qdr:w",
+	month: "qdr:m",
+	year: "qdr:y",
+};
+
+export interface FirecrawlSearchParams {
+	query: string;
+	num_results?: number;
+	recency?: SearchParams["recency"];
+	signal?: AbortSignal;
+	fetch?: FetchImpl;
+}
+
+interface FirecrawlWebResult {
+	title?: string | null;
+	url?: string | null;
+	description?: string | null;
+	markdown?: string | null;
+}
+
+interface FirecrawlSearchResponse {
+	id?: string | null;
+	data?: {
+		web?: FirecrawlWebResult[] | null;
+	} | null;
+}
+
+/** Resolve Firecrawl API key through the shared auth storage pipeline. */
+export function findApiKey(
+	authStorage: AuthStorage,
+	sessionId?: string,
+	signal?: AbortSignal,
+): Promise<string | undefined> {
+	return authStorage.getApiKey("firecrawl", sessionId, { signal });
+}
+
+function buildRequestBody(params: FirecrawlSearchParams): Record<string, unknown> {
+	const body: Record<string, unknown> = {
+		query: params.query,
+		limit: clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS),
+		sources: [{ type: "web" }],
+	};
+	if (params.recency) {
+		body.tbs = RECENCY_TBS[params.recency];
+	}
+	return body;
+}
+
+async function callFirecrawlSearch(apiKey: string, params: FirecrawlSearchParams): Promise<FirecrawlSearchResponse> {
+	const response = await (params.fetch ?? fetch)(FIRECRAWL_SEARCH_URL, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${apiKey}`,
+		},
+		body: JSON.stringify(buildRequestBody(params)),
+		signal: withHardTimeout(params.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("firecrawl", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError(
+			"firecrawl",
+			`Firecrawl API error (${response.status}): ${errorText}`,
+			response.status,
+		);
+	}
+
+	return (await response.json()) as FirecrawlSearchResponse;
+}
+
+/** Execute Firecrawl web search. */
+export async function searchFirecrawl(params: SearchParams): Promise<SearchResponse> {
+	const firecrawlParams: FirecrawlSearchParams = {
+		query: params.query,
+		num_results: params.numSearchResults ?? params.limit,
+		recency: params.recency,
+		signal: params.signal,
+		fetch: params.fetch,
+	};
+	const keyOrResolver: ApiKey = params.authStorage.resolver("firecrawl", {
+		sessionId: params.sessionId,
+	});
+	const numResults = clampNumResults(firecrawlParams.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
+
+	const data = await withAuth(keyOrResolver, key => callFirecrawlSearch(key, firecrawlParams), {
+		signal: params.signal,
+		missingKeyMessage:
+			'Firecrawl credentials not found. Set FIRECRAWL_API_KEY or configure an API key for provider "firecrawl".',
+	});
+	const sources: SearchSource[] = [];
+
+	for (const result of data.data?.web ?? []) {
+		if (!result.url) continue;
+		sources.push({
+			title: result.title ?? result.url,
+			url: result.url,
+			snippet: result.description ?? result.markdown ?? undefined,
+		});
+	}
+
+	return {
+		provider: "firecrawl",
+		sources: sources.slice(0, numResults),
+		requestId: data.id ?? undefined,
+		authMode: "api_key",
+	};
+}
+
+/** Search provider for Firecrawl web search. */
+export class FirecrawlProvider extends SearchProvider {
+	readonly id = "firecrawl";
+	readonly label = "Firecrawl";
+
+	isAvailable(authStorage: AuthStorage): boolean {
+		return authStorage.hasAuth("firecrawl") || !!getEnvApiKey("firecrawl");
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchFirecrawl(params);
+	}
+}

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

@@ -0,0 +1,159 @@
+/**
+ * TinyFish Web Search Provider
+ *
+ * Calls TinyFish's search API and maps results into the unified
+ * SearchResponse shape used by the web search tool.
+ */
+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 { clampNumResults } from "../utils";
+import type { SearchParams } from "./base";
+import { SearchProvider } from "./base";
+import { classifyProviderHttpError, withHardTimeout } from "./utils";
+
+const TINYFISH_SEARCH_URL = "https://api.search.tinyfish.ai";
+const DEFAULT_NUM_RESULTS = 10;
+const MAX_NUM_RESULTS = 20;
+const MAX_PAGE = 10;
+
+const RECENCY_MINUTES: Record<NonNullable<SearchParams["recency"]>, number> = {
+	day: 1440,
+	week: 10080,
+	month: 43200,
+	year: 525600,
+};
+
+export interface TinyFishSearchParams {
+	query: string;
+	num_results?: number;
+	recency?: SearchParams["recency"];
+	page?: number;
+	signal?: AbortSignal;
+	fetch?: FetchImpl;
+}
+
+interface TinyFishSearchResult {
+	title?: string | null;
+	url?: string | null;
+	snippet?: string | null;
+	site_name?: string | null;
+}
+
+interface TinyFishSearchResponse {
+	total_results?: number | null;
+	page?: number | null;
+	results?: TinyFishSearchResult[] | null;
+}
+
+/** Resolve TinyFish API key through the shared auth storage pipeline. */
+export function findApiKey(
+	authStorage: AuthStorage,
+	sessionId?: string,
+	signal?: AbortSignal,
+): Promise<string | undefined> {
+	return authStorage.getApiKey("tinyfish", sessionId, { signal });
+}
+
+async function callTinyFishSearch(apiKey: string, params: TinyFishSearchParams): Promise<TinyFishSearchResponse> {
+	const url = new URL(TINYFISH_SEARCH_URL);
+	url.searchParams.set("query", params.query);
+	if (params.recency) {
+		url.searchParams.set("recency_minutes", String(RECENCY_MINUTES[params.recency]));
+	}
+	if (params.num_results !== undefined) {
+		url.searchParams.set("num_results", String(params.num_results));
+	}
+	if (params.page !== undefined) {
+		url.searchParams.set("page", String(params.page));
+	}
+
+	const response = await (params.fetch ?? fetch)(url, {
+		method: "GET",
+		headers: {
+			Accept: "application/json",
+			"X-API-Key": apiKey,
+		},
+		signal: withHardTimeout(params.signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("tinyfish", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError(
+			"tinyfish",
+			`TinyFish API error (${response.status}): ${errorText}`,
+			response.status,
+		);
+	}
+
+	return (await response.json()) as TinyFishSearchResponse;
+}
+
+function appendTinyFishSources(sources: SearchSource[], results: readonly TinyFishSearchResult[]): void {
+	for (const result of results) {
+		if (!result.url) continue;
+		sources.push({
+			title: result.title ?? result.site_name ?? result.url,
+			url: result.url,
+			snippet: result.snippet ?? undefined,
+			author: result.site_name ?? undefined,
+		});
+	}
+}
+
+/** Execute TinyFish web search. */
+export async function searchTinyFish(params: SearchParams): Promise<SearchResponse> {
+	const numResults = clampNumResults(params.numSearchResults ?? params.limit, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
+	const pageSize = Math.min(numResults, DEFAULT_NUM_RESULTS);
+	const tinyFishParams: TinyFishSearchParams = {
+		query: params.query,
+		num_results: pageSize,
+		recency: params.recency,
+		signal: params.signal,
+		fetch: params.fetch,
+	};
+	const keyOrResolver: ApiKey = params.authStorage.resolver("tinyfish", {
+		sessionId: params.sessionId,
+	});
+	const sources = await withAuth(
+		keyOrResolver,
+		async key => {
+			const collected: SearchSource[] = [];
+			for (let page = 0; page <= MAX_PAGE && collected.length < numResults; page += 1) {
+				const searchPage = await callTinyFishSearch(key, { ...tinyFishParams, page });
+				const results = searchPage.results ?? [];
+				appendTinyFishSources(collected, results);
+				if (results.length < pageSize) break;
+			}
+
+			return collected.slice(0, numResults);
+		},
+		{
+			signal: params.signal,
+			missingKeyMessage:
+				'TinyFish credentials not found. Set TINYFISH_API_KEY or configure an API key for provider "tinyfish".',
+		},
+	);
+
+	return {
+		provider: "tinyfish",
+		sources,
+		authMode: "api_key",
+	};
+}
+
+/** Search provider for TinyFish web search. */
+export class TinyFishProvider extends SearchProvider {
+	readonly id = "tinyfish";
+	readonly label = "TinyFish";
+
+	isAvailable(authStorage: AuthStorage): boolean {
+		return authStorage.hasAuth("tinyfish") || !!getEnvApiKey("tinyfish");
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchTinyFish(params);
+	}
+}