@oh-my-pi/pi-coding-agent 1.337.0

package/src/core/tools/web-search/providers/anthropic.ts

@@ -0,0 +1,198 @@
+/**
+ * Anthropic Web Search Provider
+ *
+ * Uses Claude's built-in web_search_20250305 tool to search the web.
+ * Returns synthesized answers with citations and source metadata.
+ */
+
+import { buildAnthropicHeaders, buildAnthropicUrl, findAnthropicAuth, getEnv } from "../auth.js";
+import type {
+	AnthropicApiResponse,
+	AnthropicAuthConfig,
+	AnthropicCitation,
+	WebSearchCitation,
+	WebSearchResponse,
+	WebSearchSource,
+} from "../types.js";
+
+const DEFAULT_MODEL = "claude-sonnet-4-5-20250514";
+const DEFAULT_MAX_TOKENS = 4096;
+
+export interface AnthropicSearchParams {
+	query: string;
+	system_prompt?: string;
+	max_tokens?: number;
+	num_results?: number;
+}
+
+/** Get model from env or use default */
+async function getModel(): Promise<string> {
+	return (await getEnv("ANTHROPIC_SEARCH_MODEL")) ?? DEFAULT_MODEL;
+}
+
+/** Call Anthropic API with web search */
+async function callWebSearch(
+	auth: AnthropicAuthConfig,
+	model: string,
+	query: string,
+	systemPrompt?: string,
+	maxTokens?: number,
+): Promise<AnthropicApiResponse> {
+	const url = buildAnthropicUrl(auth);
+	const headers = buildAnthropicHeaders(auth);
+
+	// Build system blocks
+	const systemBlocks: Array<{ type: string; text: string; cache_control?: { type: string } }> = [];
+
+	if (auth.isOAuth) {
+		// OAuth requires Claude Code identity with cache_control
+		systemBlocks.push({
+			type: "text",
+			text: "You are a helpful AI assistant with web search capabilities.",
+			cache_control: { type: "ephemeral" },
+		});
+	}
+
+	if (systemPrompt) {
+		systemBlocks.push({
+			type: "text",
+			text: systemPrompt,
+			...(auth.isOAuth ? { cache_control: { type: "ephemeral" } } : {}),
+		});
+	}
+
+	const body: Record<string, unknown> = {
+		model,
+		max_tokens: maxTokens ?? DEFAULT_MAX_TOKENS,
+		messages: [{ role: "user", content: query }],
+		tools: [{ type: "web_search_20250305", name: "web_search" }],
+	};
+
+	if (systemBlocks.length > 0) {
+		body.system = systemBlocks;
+	}
+
+	const response = await fetch(url, {
+		method: "POST",
+		headers,
+		body: JSON.stringify(body),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Anthropic API error (${response.status}): ${errorText}`);
+	}
+
+	return response.json() as Promise<AnthropicApiResponse>;
+}
+
+/** Parse page_age string into seconds (e.g., "2 days ago", "3h ago", "1 week ago") */
+function parsePageAge(pageAge: string | null | undefined): number | undefined {
+	if (!pageAge) return undefined;
+
+	const match = pageAge.match(/^(\d+)\s*(s|sec|second|m|min|minute|h|hour|d|day|w|week|mo|month|y|year)s?\s*(ago)?$/i);
+	if (!match) return undefined;
+
+	const value = parseInt(match[1], 10);
+	const unit = match[2].toLowerCase();
+
+	const multipliers: Record<string, number> = {
+		s: 1,
+		sec: 1,
+		second: 1,
+		m: 60,
+		min: 60,
+		minute: 60,
+		h: 3600,
+		hour: 3600,
+		d: 86400,
+		day: 86400,
+		w: 604800,
+		week: 604800,
+		mo: 2592000,
+		month: 2592000,
+		y: 31536000,
+		year: 31536000,
+	};
+
+	return value * (multipliers[unit] ?? 86400);
+}
+
+/** Parse API response into unified WebSearchResponse */
+function parseResponse(response: AnthropicApiResponse): WebSearchResponse {
+	const answerParts: string[] = [];
+	const searchQueries: string[] = [];
+	const sources: WebSearchSource[] = [];
+	const citations: WebSearchCitation[] = [];
+
+	for (const block of response.content) {
+		if (block.type === "server_tool_use" && block.name === "web_search") {
+			// Intermediate search query
+			if (block.input?.query) {
+				searchQueries.push(block.input.query);
+			}
+		} else if (block.type === "web_search_tool_result" && block.content) {
+			// Search results
+			for (const result of block.content) {
+				if (result.type === "web_search_result") {
+					sources.push({
+						title: result.title,
+						url: result.url,
+						snippet: result.encrypted_content,
+						publishedDate: result.page_age ?? undefined,
+						ageSeconds: parsePageAge(result.page_age),
+					});
+				}
+			}
+		} else if (block.type === "text" && block.text) {
+			// Synthesized answer with citations
+			answerParts.push(block.text);
+			if (block.citations) {
+				for (const c of block.citations as AnthropicCitation[]) {
+					citations.push({
+						url: c.url,
+						title: c.title,
+						citedText: c.cited_text,
+					});
+				}
+			}
+		}
+	}
+
+	return {
+		provider: "anthropic",
+		answer: answerParts.join("\n\n") || undefined,
+		sources,
+		citations: citations.length > 0 ? citations : undefined,
+		searchQueries: searchQueries.length > 0 ? searchQueries : undefined,
+		usage: {
+			inputTokens: response.usage.input_tokens,
+			outputTokens: response.usage.output_tokens,
+			searchRequests: response.usage.server_tool_use?.web_search_requests,
+		},
+		model: response.model,
+		requestId: response.id,
+	};
+}
+
+/** Execute Anthropic web search */
+export async function searchAnthropic(params: AnthropicSearchParams): Promise<WebSearchResponse> {
+	const auth = await findAnthropicAuth();
+	if (!auth) {
+		throw new Error(
+			"No Anthropic credentials found. Set ANTHROPIC_API_KEY or configure OAuth in ~/.pi/agent/auth.json",
+		);
+	}
+
+	const model = await getModel();
+	const response = await callWebSearch(auth, model, params.query, params.system_prompt, params.max_tokens);
+
+	const result = parseResponse(response);
+
+	// Apply num_results limit if specified
+	if (params.num_results && result.sources.length > params.num_results) {
+		result.sources = result.sources.slice(0, params.num_results);
+	}
+
+	return result;
+}

package/src/core/tools/web-search/providers/exa.ts

@@ -0,0 +1,302 @@
+/**
+ * Exa Web Search Provider
+ *
+ * High-quality neural search via Exa MCP.
+ * Returns structured search results with optional content extraction.
+ */
+
+import * as os from "node:os";
+import type { WebSearchResponse, WebSearchSource } from "../types.js";
+
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+
+export interface ExaSearchParams {
+	query: string;
+	num_results?: number;
+	type?: "neural" | "keyword" | "auto";
+	include_domains?: string[];
+	exclude_domains?: string[];
+	start_published_date?: string;
+	end_published_date?: string;
+}
+
+/** Parse a .env file and return key-value pairs */
+async function parseEnvFile(filePath: string): Promise<Record<string, string>> {
+	const result: Record<string, string> = {};
+	try {
+		const file = Bun.file(filePath);
+		if (!(await file.exists())) return result;
+
+		const content = await file.text();
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex === -1) continue;
+
+			const key = trimmed.slice(0, eqIndex).trim();
+			let value = trimmed.slice(eqIndex + 1).trim();
+
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+
+			result[key] = value;
+		}
+	} catch {
+		// Ignore read errors
+	}
+	return result;
+}
+
+/** Find EXA_API_KEY from environment or .env files */
+export async function findApiKey(): Promise<string | null> {
+	// 1. Check environment variable
+	if (process.env.EXA_API_KEY) {
+		return process.env.EXA_API_KEY;
+	}
+
+	// 2. Check .env in current directory
+	const localEnv = await parseEnvFile(`${process.cwd()}/.env`);
+	if (localEnv.EXA_API_KEY) {
+		return localEnv.EXA_API_KEY;
+	}
+
+	// 3. Check ~/.env
+	const homeEnv = await parseEnvFile(`${os.homedir()}/.env`);
+	if (homeEnv.EXA_API_KEY) {
+		return homeEnv.EXA_API_KEY;
+	}
+
+	return null;
+}
+
+/** Parse SSE response format */
+function parseSSE(text: string): unknown {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		if (line.startsWith("data: ")) {
+			const data = line.slice(6).trim();
+			if (data === "[DONE]") continue;
+			try {
+				return JSON.parse(data);
+			} catch {
+				// Try next line
+			}
+		}
+	}
+	// Fallback: try parsing entire response as JSON
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+interface MCPCallResponse {
+	result?: {
+		content?: Array<{ type: string; text?: string }>;
+	};
+	error?: {
+		code: number;
+		message: string;
+	};
+}
+
+interface ExaSearchResult {
+	title?: string;
+	url?: string;
+	author?: string;
+	publishedDate?: string;
+	text?: string;
+	highlights?: string[];
+}
+
+interface ExaSearchResponse {
+	results?: ExaSearchResult[];
+	costDollars?: { total: number };
+	searchTime?: number;
+}
+
+/** Call Exa MCP API */
+async function callExaMCP(apiKey: string, toolName: string, args: Record<string, unknown>): Promise<MCPCallResponse> {
+	const url = `${EXA_MCP_URL}?exaApiKey=${encodeURIComponent(apiKey)}&tools=${encodeURIComponent(toolName)}`;
+
+	const body = {
+		jsonrpc: "2.0",
+		id: Math.random().toString(36).slice(2),
+		method: "tools/call",
+		params: {
+			name: toolName,
+			arguments: args,
+		},
+	};
+
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify(body),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Exa MCP error (${response.status}): ${errorText}`);
+	}
+
+	const text = await response.text();
+	const result = parseSSE(text);
+
+	if (!result) {
+		throw new Error("Failed to parse Exa MCP response");
+	}
+
+	return result as MCPCallResponse;
+}
+
+/** Parse MCP response content into ExaSearchResponse */
+function parseMCPContent(content: Array<{ type: string; text?: string }>): ExaSearchResponse | null {
+	for (const block of content) {
+		if (block.type === "text" && block.text) {
+			// Try to parse as JSON first
+			try {
+				return JSON.parse(block.text) as ExaSearchResponse;
+			} catch {
+				// Parse markdown format
+				return parseExaMarkdown(block.text);
+			}
+		}
+	}
+	return null;
+}
+
+/** Parse Exa markdown format into ExaSearchResponse */
+function parseExaMarkdown(text: string): ExaSearchResponse | null {
+	const results: ExaSearchResult[] = [];
+	const lines = text.split("\n");
+	let currentResult: Partial<ExaSearchResult> | null = null;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+
+		// Match result header: ## Title
+		if (trimmed.startsWith("## ")) {
+			if (currentResult?.title) {
+				results.push(currentResult as ExaSearchResult);
+			}
+			currentResult = { title: trimmed.slice(3).trim() };
+			continue;
+		}
+
+		if (!currentResult) continue;
+
+		// Match URL: **URL:** ...
+		if (trimmed.startsWith("**URL:**")) {
+			currentResult.url = trimmed.slice(8).trim();
+			continue;
+		}
+
+		// Match Author: **Author:** ...
+		if (trimmed.startsWith("**Author:**")) {
+			currentResult.author = trimmed.slice(11).trim();
+			continue;
+		}
+
+		// Match Published Date: **Published Date:** ...
+		if (trimmed.startsWith("**Published Date:**")) {
+			currentResult.publishedDate = trimmed.slice(19).trim();
+			continue;
+		}
+
+		// Match Text: **Text:** ...
+		if (trimmed.startsWith("**Text:**")) {
+			currentResult.text = trimmed.slice(9).trim();
+		}
+	}
+
+	// Add last result
+	if (currentResult?.title) {
+		results.push(currentResult as ExaSearchResult);
+	}
+
+	if (results.length === 0) return null;
+
+	return { results };
+}
+
+/** Calculate age in seconds from ISO date string */
+function dateToAgeSeconds(dateStr: string | undefined): number | undefined {
+	if (!dateStr) return undefined;
+	try {
+		const date = new Date(dateStr);
+		if (Number.isNaN(date.getTime())) return undefined;
+		return Math.floor((Date.now() - date.getTime()) / 1000);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Execute Exa web search */
+export async function searchExa(params: ExaSearchParams): Promise<WebSearchResponse> {
+	const apiKey = await findApiKey();
+	if (!apiKey) {
+		throw new Error("EXA_API_KEY not found. Set it in environment or .env file.");
+	}
+
+	const args: Record<string, unknown> = {
+		query: params.query,
+		num_results: params.num_results ?? 10,
+		type: params.type ?? "auto",
+		text: true, // Include text for richer results
+		highlights: true,
+	};
+
+	if (params.include_domains?.length) {
+		args.include_domains = params.include_domains;
+	}
+	if (params.exclude_domains?.length) {
+		args.exclude_domains = params.exclude_domains;
+	}
+	if (params.start_published_date) {
+		args.start_published_date = params.start_published_date;
+	}
+	if (params.end_published_date) {
+		args.end_published_date = params.end_published_date;
+	}
+
+	const response = await callExaMCP(apiKey, "web_search", args);
+
+	if (response.error) {
+		throw new Error(`Exa MCP error: ${response.error.message}`);
+	}
+
+	const exaResponse = response.result?.content ? parseMCPContent(response.result.content) : null;
+
+	// Convert to unified WebSearchResponse
+	const sources: WebSearchSource[] = [];
+
+	if (exaResponse?.results) {
+		for (const result of exaResponse.results) {
+			if (!result.url) continue;
+			sources.push({
+				title: result.title ?? result.url,
+				url: result.url,
+				snippet: result.text ?? result.highlights?.join(" "),
+				publishedDate: result.publishedDate,
+				ageSeconds: dateToAgeSeconds(result.publishedDate),
+				author: result.author,
+			});
+		}
+	}
+
+	// Apply num_results limit if specified
+	const limitedSources = params.num_results ? sources.slice(0, params.num_results) : sources;
+
+	return {
+		provider: "exa",
+		sources: limitedSources,
+	};
+}

package/src/core/tools/web-search/providers/perplexity.ts

@@ -0,0 +1,195 @@
+/**
+ * Perplexity Web Search Provider
+ *
+ * Supports both sonar (fast) and sonar-pro (comprehensive) models.
+ * Returns synthesized answers with citations and related questions.
+ */
+
+import * as os from "node:os";
+import type {
+	PerplexityRequest,
+	PerplexityResponse,
+	WebSearchCitation,
+	WebSearchResponse,
+	WebSearchSource,
+} from "../types.js";
+
+const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
+
+export interface PerplexitySearchParams {
+	query: string;
+	model?: "sonar" | "sonar-pro";
+	system_prompt?: string;
+	search_recency_filter?: "day" | "week" | "month" | "year";
+	search_domain_filter?: string[];
+	search_context_size?: "low" | "medium" | "high";
+	return_related_questions?: boolean;
+	num_results?: number;
+}
+
+/** Parse a .env file and return key-value pairs */
+async function parseEnvFile(filePath: string): Promise<Record<string, string>> {
+	const result: Record<string, string> = {};
+	try {
+		const file = Bun.file(filePath);
+		if (!(await file.exists())) return result;
+
+		const content = await file.text();
+		for (const line of content.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) continue;
+
+			const eqIndex = trimmed.indexOf("=");
+			if (eqIndex === -1) continue;
+
+			const key = trimmed.slice(0, eqIndex).trim();
+			let value = trimmed.slice(eqIndex + 1).trim();
+
+			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+				value = value.slice(1, -1);
+			}
+
+			result[key] = value;
+		}
+	} catch {
+		// Ignore read errors
+	}
+	return result;
+}
+
+/** Find PERPLEXITY_API_KEY from environment or .env files */
+export async function findApiKey(): Promise<string | null> {
+	// 1. Check environment variable
+	if (process.env.PERPLEXITY_API_KEY) {
+		return process.env.PERPLEXITY_API_KEY;
+	}
+
+	// 2. Check .env in current directory
+	const localEnv = await parseEnvFile(`${process.cwd()}/.env`);
+	if (localEnv.PERPLEXITY_API_KEY) {
+		return localEnv.PERPLEXITY_API_KEY;
+	}
+
+	// 3. Check ~/.env
+	const homeEnv = await parseEnvFile(`${os.homedir()}/.env`);
+	if (homeEnv.PERPLEXITY_API_KEY) {
+		return homeEnv.PERPLEXITY_API_KEY;
+	}
+
+	return null;
+}
+
+/** Call Perplexity API */
+async function callPerplexity(apiKey: string, request: PerplexityRequest): Promise<PerplexityResponse> {
+	const response = await fetch(PERPLEXITY_API_URL, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${apiKey}`,
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify(request),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		throw new Error(`Perplexity API error (${response.status}): ${errorText}`);
+	}
+
+	return response.json() as Promise<PerplexityResponse>;
+}
+
+/** Calculate age in seconds from ISO date string */
+function dateToAgeSeconds(dateStr: string | undefined): number | undefined {
+	if (!dateStr) return undefined;
+	try {
+		const date = new Date(dateStr);
+		if (Number.isNaN(date.getTime())) return undefined;
+		return Math.floor((Date.now() - date.getTime()) / 1000);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Parse API response into unified WebSearchResponse */
+function parseResponse(response: PerplexityResponse): WebSearchResponse {
+	const answer = response.choices[0]?.message?.content ?? "";
+
+	// Build sources by matching citations to search_results
+	const sources: WebSearchSource[] = [];
+	const citations: WebSearchCitation[] = [];
+
+	const citationUrls = response.citations ?? [];
+	const searchResults = response.search_results ?? [];
+
+	for (const url of citationUrls) {
+		const searchResult = searchResults.find((r) => r.url === url);
+		sources.push({
+			title: searchResult?.title ?? url,
+			url,
+			snippet: searchResult?.snippet,
+			publishedDate: searchResult?.date,
+			ageSeconds: dateToAgeSeconds(searchResult?.date),
+		});
+		citations.push({
+			url,
+			title: searchResult?.title ?? url,
+		});
+	}
+
+	return {
+		provider: "perplexity",
+		answer: answer || undefined,
+		sources,
+		citations: citations.length > 0 ? citations : undefined,
+		relatedQuestions: response.related_questions,
+		usage: {
+			inputTokens: response.usage.prompt_tokens,
+			outputTokens: response.usage.completion_tokens,
+			totalTokens: response.usage.total_tokens,
+		},
+		model: response.model,
+		requestId: response.id,
+	};
+}
+
+/** Execute Perplexity web search */
+export async function searchPerplexity(params: PerplexitySearchParams): Promise<WebSearchResponse> {
+	const apiKey = await findApiKey();
+	if (!apiKey) {
+		throw new Error("PERPLEXITY_API_KEY not found. Set it in environment or .env file.");
+	}
+
+	const messages: PerplexityRequest["messages"] = [];
+	if (params.system_prompt) {
+		messages.push({ role: "system", content: params.system_prompt });
+	}
+	messages.push({ role: "user", content: params.query });
+
+	const request: PerplexityRequest = {
+		model: params.model ?? "sonar",
+		messages,
+		// Default to true for related questions (unlike original which hardcoded false)
+		return_related_questions: params.return_related_questions ?? true,
+	};
+
+	// Add optional parameters
+	if (params.search_recency_filter) {
+		request.search_recency_filter = params.search_recency_filter;
+	}
+	if (params.search_domain_filter && params.search_domain_filter.length > 0) {
+		request.search_domain_filter = params.search_domain_filter;
+	}
+	if (params.search_context_size) {
+		request.search_context_size = params.search_context_size;
+	}
+
+	const response = await callPerplexity(apiKey, request);
+	const result = parseResponse(response);
+
+	// Apply num_results limit if specified
+	if (params.num_results && result.sources.length > params.num_results) {
+		result.sources = result.sources.slice(0, params.num_results);
+	}
+
+	return result;
+}