@wahack/pi-coding-agent 15.11.0

package/src/web/search/provider.ts

@@ -0,0 +1,157 @@
+// Lazy registry of web search providers.
+//
+// Each provider is loaded on first use; importing this module loads zero
+// provider implementations. Provider modules are heavy (each pulls in
+// fetch/parse/format helpers) and only one — at most — is needed per session,
+// so eager construction was wasted work at startup.
+//
+// Provider modules are loaded lazily; display metadata lives in types.ts so UI
+// listings can share it without importing provider implementations.
+
+import type { AuthStorage } from "@oh-my-pi/pi-ai";
+import type { SearchProvider } from "./providers/base";
+import { SEARCH_PROVIDER_LABELS, SEARCH_PROVIDER_ORDER, type SearchProviderId } from "./types";
+
+export type { SearchParams } from "./providers/base";
+export { SearchProvider } from "./providers/base";
+export { SEARCH_PROVIDER_ORDER } from "./types";
+
+interface ProviderMeta {
+	id: SearchProviderId;
+	label: string;
+	load: () => Promise<SearchProvider>;
+}
+
+/** 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(),
+	},
+	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(),
+	},
+	tavily: {
+		id: "tavily",
+		label: SEARCH_PROVIDER_LABELS.tavily,
+		load: async () => new (await import("./providers/tavily")).TavilyProvider(),
+	},
+	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,
+		load: async () => new (await import("./providers/synthetic")).SyntheticProvider(),
+	},
+	searxng: {
+		id: "searxng",
+		label: SEARCH_PROVIDER_LABELS.searxng,
+		load: async () => new (await import("./providers/searxng")).SearXNGProvider(),
+	},
+};
+
+const instanceCache = new Map<SearchProviderId, SearchProvider>();
+
+/** Cheap, sync metadata accessor — never triggers a provider load. */
+export function getSearchProviderLabel(id: SearchProviderId): string {
+	return PROVIDER_META[id]?.label ?? id;
+}
+
+/**
+ * Resolve and cache a provider instance. First call for a given id loads the
+ * underlying module; subsequent calls return the cached singleton.
+ */
+export async function getSearchProvider(id: SearchProviderId): Promise<SearchProvider> {
+	const cached = instanceCache.get(id);
+	if (cached) return cached;
+	const meta = PROVIDER_META[id];
+	if (!meta) {
+		throw new Error(`Unknown search provider: ${id}`);
+	}
+	const provider = await meta.load();
+	instanceCache.set(id, provider);
+	return provider;
+}
+
+/** Preferred provider set via settings (default: auto) */
+let preferredProvId: SearchProviderId | "auto" = "auto";
+
+/** Set the preferred web search provider from settings */
+export function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void {
+	preferredProvId = provider;
+}
+
+/**
+ * Determine which providers are configured and currently available.
+ * Each candidate is loaded (and its `isAvailable()` called) only as the chain
+ * is walked, so unconfigured providers never pay the load cost.
+ */
+export async function resolveProviderChain(
+	authStorage: AuthStorage,
+	preferredProvider: SearchProviderId | "auto" = preferredProvId,
+): Promise<SearchProvider[]> {
+	const providers: SearchProvider[] = [];
+
+	if (preferredProvider !== "auto") {
+		const provider = await getSearchProvider(preferredProvider);
+		if (await provider.isExplicitlyAvailable(authStorage)) {
+			providers.push(provider);
+		}
+	}
+
+	for (const id of SEARCH_PROVIDER_ORDER) {
+		if (id === preferredProvider) continue;
+		const provider = await getSearchProvider(id);
+		if (await provider.isAvailable(authStorage)) {
+			providers.push(provider);
+		}
+	}
+
+	return providers;
+}

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

@@ -0,0 +1,318 @@
+/**
+ * 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 {
+	type AnthropicAuthConfig,
+	type AnthropicSystemBlock,
+	type ApiKey,
+	type AuthStorage,
+	buildAnthropicAuthConfig,
+	buildAnthropicSearchHeaders,
+	buildAnthropicSystemBlocks,
+	buildAnthropicUrl,
+	type FetchImpl,
+	stripClaudeToolPrefix,
+	withAuth,
+	wrapFetchForCch,
+} from "@oh-my-pi/pi-ai";
+import { $env } from "@oh-my-pi/pi-utils";
+import type {
+	AnthropicApiResponse,
+	AnthropicCitation,
+	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_MODEL = "claude-haiku-4-5";
+const DEFAULT_MAX_TOKENS = 4096;
+const WEB_SEARCH_TOOL_NAME = "web_search";
+const WEB_SEARCH_TOOL_TYPE = "web_search_20250305";
+export interface AnthropicSearchParams {
+	query: string;
+	system_prompt?: string;
+	num_results?: number;
+	max_tokens?: number;
+	temperature?: number;
+	signal?: AbortSignal;
+	fetch?: FetchImpl;
+}
+
+/**
+ * Gets the model to use for web search from environment or default.
+ * @returns Model identifier string
+ */
+function getModel(): string {
+	return $env.ANTHROPIC_SEARCH_MODEL ?? DEFAULT_MODEL;
+}
+
+/**
+ * Builds system instruction blocks for the Anthropic API request.
+ * @param auth - Authentication configuration
+ * @param model - Model identifier (affects whether Claude Code instruction is included)
+ * @param systemPrompt - Optional system prompt for guiding response style
+ * @returns Array of system blocks for the API request
+ */
+function buildSystemBlocks(
+	auth: AnthropicAuthConfig,
+	model: string,
+	systemPrompt?: string,
+): AnthropicSystemBlock[] | undefined {
+	// 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, {
+		includeClaudeCodeInstruction: includeClaudeCode,
+		extraInstructions,
+		cacheControl: { type: "ephemeral" },
+	});
+}
+
+/**
+ * Calls the Anthropic API with web search tool enabled.
+ * @param auth - Authentication configuration (API key or OAuth)
+ * @param model - Model identifier to use
+ * @param query - Search query from the user
+ * @param systemPrompt - Optional system prompt for guiding response style
+ * @returns Raw API response from Anthropic
+ * @throws {SearchProviderError} If the API request fails
+ */
+async function callSearch(
+	auth: AnthropicAuthConfig,
+	model: string,
+	query: string,
+	systemPrompt?: string,
+	maxTokens?: number,
+	temperature?: number,
+	signal?: AbortSignal,
+	fetchImpl: FetchImpl = fetch,
+): Promise<AnthropicApiResponse> {
+	const url = buildAnthropicUrl(auth);
+	const headers = buildAnthropicSearchHeaders(auth);
+
+	const systemBlocks = buildSystemBlocks(auth, model, systemPrompt);
+
+	const body: Record<string, unknown> = {
+		model,
+		max_tokens: maxTokens ?? DEFAULT_MAX_TOKENS,
+		messages: [{ role: "user", content: query }],
+		tools: [
+			{
+				type: WEB_SEARCH_TOOL_TYPE,
+				name: WEB_SEARCH_TOOL_NAME,
+			},
+		],
+	};
+
+	if (temperature !== undefined) {
+		body.temperature = temperature;
+	}
+
+	if (systemBlocks && systemBlocks.length > 0) {
+		body.system = systemBlocks;
+	}
+
+	// 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),
+		signal: withHardTimeout(signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("anthropic", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError(
+			"anthropic",
+			`Anthropic API error (${response.status}): ${errorText}`,
+			response.status,
+		);
+	}
+
+	return response.json() as Promise<AnthropicApiResponse>;
+}
+
+/**
+ * Parses a human-readable page age string into seconds.
+ * @param pageAge - Age string like "2 days ago", "3h ago", "1 week ago"
+ * @returns Age in seconds, or undefined if parsing fails
+ */
+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);
+}
+
+/**
+ * Parses the Anthropic API response into a unified SearchResponse.
+ * @param response - Raw API response containing content blocks
+ * @returns Normalized response with answer, sources, citations, and usage
+ */
+function parseResponse(response: AnthropicApiResponse): SearchResponse {
+	const answerParts: string[] = [];
+	const searchQueries: string[] = [];
+	const sources: SearchSource[] = [];
+	const citations: SearchCitation[] = [];
+
+	for (const block of response.content) {
+		if (
+			block.type === "server_tool_use" &&
+			block.name &&
+			stripClaudeToolPrefix(block.name) === WEB_SEARCH_TOOL_NAME
+		) {
+			// 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: undefined,
+						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,
+	};
+}
+
+/**
+ * Executes a web search using Anthropic's Claude with built-in web search tool.
+ * @param params - Search parameters including query and optional settings
+ * @returns Search response with synthesized answer, sources, and citations
+ * @throws {Error} If no Anthropic credentials are configured
+ */
+export async function searchAnthropic(
+	params: SearchParams | AnthropicSearchParams,
+	_legacyStorage?: unknown,
+): Promise<SearchResponse> {
+	const searchApiKey = $env.ANTHROPIC_SEARCH_API_KEY;
+	const searchBaseUrl = $env.ANTHROPIC_SEARCH_BASE_URL;
+	const keyOrResolver: ApiKey | undefined = searchApiKey
+		? searchApiKey
+		: "authStorage" in params
+			? params.authStorage.resolver("anthropic", { sessionId: params.sessionId })
+			: undefined;
+
+	if (!keyOrResolver) {
+		throw new Error(
+			"No Anthropic credentials found. Set ANTHROPIC_SEARCH_API_KEY or ANTHROPIC_API_KEY, or configure Anthropic OAuth.",
+		);
+	}
+
+	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 withAuth(
+		keyOrResolver,
+		key =>
+			callSearch(
+				buildAnthropicAuthConfig(key, searchBaseUrl),
+				model,
+				params.query,
+				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);
+
+	const numResults = "authStorage" in params ? (params.numSearchResults ?? params.limit) : params.num_results;
+	if (numResults && result.sources.length > numResults) {
+		result.sources = result.sources.slice(0, numResults);
+	}
+
+	return result;
+}
+
+/** Search provider for Anthropic Claude web search. */
+export class AnthropicProvider extends SearchProvider {
+	readonly id = "anthropic";
+	readonly label = "Anthropic";
+
+	isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean {
+		return Boolean($env.ANTHROPIC_SEARCH_API_KEY) || authStorage.hasAuth("anthropic");
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchAnthropic(params);
+	}
+}

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

@@ -0,0 +1,89 @@
+import type { AuthStorage, FetchImpl } from "@oh-my-pi/pi-ai";
+import type { SearchProviderId, SearchResponse } from "../types";
+
+/**
+ * Shared web search parameters passed to providers.
+ *
+ * `authStorage` is the **only** credential source providers may consult.
+ * Opening a sibling SQLite handle or calling provider-direct refresh helpers
+ * (e.g. `refreshOpenAICodexToken`, `refreshGoogleCloudToken`) is prohibited:
+ * it races the broker's per-credential refresh and POSTs the broker sentinel
+ * (`REMOTE_REFRESH_SENTINEL`) to the upstream token endpoint, which classifies
+ * as `invalid_grant` and disables the row.
+ */
+export interface SearchParams {
+	query: string;
+	limit?: number;
+	/**
+	 * Temporal filter narrowing results to the specified time window.
+	 *
+	 * Providers MUST interpret this as a pure time filter. Providers MUST NOT
+	 * use recency as an implicit signal to change topic scope, content domain,
+	 * or ranking strategy. If a provider API couples temporal filtering with
+	 * other dimensions (e.g. Tavily's `topic=news`), the provider implementation
+	 * is responsible for decoupling them before calling the upstream API.
+	 *
+	 * Providers that do not support temporal filtering MUST ignore this field
+	 * silently; they MUST NOT approximate it by rewriting the query or altering
+	 * any other request parameter.
+	 */
+	recency?: "day" | "week" | "month" | "year";
+	systemPrompt: string;
+	signal?: AbortSignal;
+	fetch?: FetchImpl;
+	maxOutputTokens?: number;
+	numSearchResults?: number;
+	temperature?: number;
+	googleSearch?: Record<string, unknown>;
+	codeExecution?: Record<string, unknown>;
+	urlContext?: Record<string, unknown>;
+	/**
+	 * The single source of truth for credentials. Providers MUST consult this
+	 * handle exclusively (`getApiKey` for bearer-style auth, `getOAuthAccess`
+	 * when identity metadata is required). Do not open `AgentStorage` or any
+	 * `AuthCredentialStore` directly — that bypasses the broker pipeline and
+	 * the per-credential single-flight refresh.
+	 */
+	authStorage: AuthStorage;
+	/**
+	 * Optional session id used as the round-robin / sticky key when selecting
+	 * among multiple credentials for the same provider. Pass through from the
+	 * caller's agent session when available; otherwise omit.
+	 */
+	sessionId?: string;
+}
+
+/** Base class for web search providers. */
+export abstract class SearchProvider {
+	abstract readonly id: SearchProviderId;
+	abstract readonly label: string;
+
+	/**
+	 * Indicates whether this provider has the credentials/config it needs to
+	 * service a request right now. Implementations consult the passed
+	 * {@link AuthStorage} — never a sibling store.
+	 *
+	 * Drives auto-chain admission: providers that return `false` are skipped
+	 * when {@link resolveProviderChain} walks the order. Explicit selection
+	 * uses {@link isExplicitlyAvailable} instead.
+	 */
+	abstract isAvailable(authStorage: AuthStorage): Promise<boolean> | boolean;
+
+	/**
+	 * Returns `true` when this provider should run when the user explicitly
+	 * selects it, even if {@link isAvailable} would reject it for the auto
+	 * chain. Providers that ship an unauthenticated fallback (e.g. Exa's
+	 * public MCP) override this so explicit selection still routes through
+	 * the fallback rather than silently falling back to another provider.
+	 *
+	 * Defaults to mirroring {@link isAvailable}.
+	 */
+	isExplicitlyAvailable(authStorage: AuthStorage): Promise<boolean> | boolean {
+		return this.isAvailable(authStorage);
+	}
+
+	/**
+	 * Execute a search. Credentials MUST be resolved through `params.authStorage`.
+	 */
+	abstract search(params: SearchParams): Promise<SearchResponse>;
+}