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

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

@@ -0,0 +1,292 @@
+import { type ApiKey, type AuthStorage, withAuth } from "@oh-my-pi/pi-ai";
+import type { SearchCitation, SearchResponse, SearchSource, SearchUsage } 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 XAI_RESPONSES_URL = "https://api.x.ai/v1/responses";
+const XAI_WEB_SEARCH_MODEL = "grok-4.3";
+const DEFAULT_NUM_RESULTS = 10;
+const MAX_NUM_RESULTS = 30;
+const RECENCY_DAYS: Record<NonNullable<SearchParams["recency"]>, number> = {
+	day: 1,
+	week: 7,
+	month: 30,
+	year: 365,
+};
+
+function formatUtcDate(date: Date): string {
+	return date.toISOString().slice(0, 10);
+}
+
+function buildRecencyDateBounds(
+	recency: NonNullable<SearchParams["recency"]>,
+	now = new Date(),
+): {
+	from_date: string;
+	to_date: string;
+} {
+	const toDate = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+	const fromDate = new Date(toDate);
+	fromDate.setUTCDate(fromDate.getUTCDate() - RECENCY_DAYS[recency]);
+	return {
+		from_date: formatUtcDate(fromDate),
+		to_date: formatUtcDate(toDate),
+	};
+}
+
+interface XAIUrlCitationAnnotation {
+	type?: string;
+	url?: string | null;
+	title?: string | null;
+	text?: string | null;
+	cited_text?: string | null;
+}
+
+interface XAIResponseContentPart {
+	type?: string;
+	text?: string | null;
+	output_text?: string | null;
+	annotations?: XAIUrlCitationAnnotation[] | null;
+}
+
+interface XAIResponseOutputItem {
+	content?: XAIResponseContentPart[] | null;
+	annotations?: XAIUrlCitationAnnotation[] | null;
+}
+
+interface XAIResponsesUsage {
+	input_tokens?: number;
+	output_tokens?: number;
+	total_tokens?: number;
+	inputTokens?: number;
+	outputTokens?: number;
+	totalTokens?: number;
+}
+
+interface XAIResponsesResponse {
+	id?: string;
+	model?: string;
+	output_text?: string | null;
+	output?: XAIResponseOutputItem[] | null;
+	annotations?: XAIUrlCitationAnnotation[] | null;
+	citations?: string[] | null;
+	usage?: XAIResponsesUsage | null;
+}
+
+function buildRequestBody(params: SearchParams): Record<string, unknown> {
+	const body: Record<string, unknown> = {
+		model: XAI_WEB_SEARCH_MODEL,
+		input: [
+			{ role: "system", content: params.systemPrompt },
+			{ role: "user", content: params.query },
+		],
+		tools: [{ type: "web_search" }],
+	};
+
+	const requestedSearchResults = params.numSearchResults ?? params.limit;
+	const searchParameters: Record<string, unknown> = {};
+	if (requestedSearchResults !== undefined) {
+		searchParameters.max_search_results = clampNumResults(
+			requestedSearchResults,
+			DEFAULT_NUM_RESULTS,
+			MAX_NUM_RESULTS,
+		);
+	}
+	if (params.recency) {
+		Object.assign(searchParameters, buildRecencyDateBounds(params.recency));
+	}
+	if (Object.keys(searchParameters).length > 0) {
+		body.search_parameters = searchParameters;
+	}
+
+	if (params.maxOutputTokens !== undefined) {
+		body.max_output_tokens = params.maxOutputTokens;
+	}
+	if (params.temperature !== undefined) {
+		body.temperature = params.temperature;
+	}
+
+	return body;
+}
+
+async function postXAIResponses(
+	apiKey: string,
+	params: SearchParams,
+	body: Record<string, unknown>,
+): Promise<Response> {
+	return (params.fetch ?? fetch)(XAI_RESPONSES_URL, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${apiKey}`,
+		},
+		body: JSON.stringify(body),
+		signal: withHardTimeout(params.signal),
+	});
+}
+
+function throwXAIResponsesError(status: number, errorText: string): never {
+	const classified = classifyProviderHttpError("xai", status, errorText);
+	if (classified) throw classified;
+	throw new SearchProviderError("xai", `xAI Responses API error (${status}): ${errorText}`, status);
+}
+
+async function callXAIResponses(apiKey: string, params: SearchParams): Promise<XAIResponsesResponse> {
+	const requestBody = buildRequestBody(params);
+	const response = await postXAIResponses(apiKey, params, requestBody);
+
+	if (!response.ok) {
+		throwXAIResponsesError(response.status, await response.text());
+	}
+
+	return (await response.json()) as XAIResponsesResponse;
+}
+
+function addCitationSource(
+	sources: SearchSource[],
+	citations: SearchCitation[],
+	seenUrls: Set<string>,
+	url: string,
+	title?: string | null,
+	citedText?: string | null,
+): void {
+	const trimmedUrl = url.trim();
+	if (!trimmedUrl || seenUrls.has(trimmedUrl)) return;
+	seenUrls.add(trimmedUrl);
+	const sourceTitle = title?.trim() || trimmedUrl;
+	const sourceSnippet = citedText?.trim() || undefined;
+
+	sources.push({
+		title: sourceTitle,
+		url: trimmedUrl,
+		snippet: sourceSnippet,
+	});
+	citations.push({
+		title: sourceTitle,
+		url: trimmedUrl,
+		citedText: sourceSnippet,
+	});
+}
+
+function collectAnnotationSources(
+	annotations: readonly XAIUrlCitationAnnotation[] | null | undefined,
+	sources: SearchSource[],
+	citations: SearchCitation[],
+	seenUrls: Set<string>,
+): void {
+	if (!annotations) return;
+	for (const annotation of annotations) {
+		if (annotation.type !== "url_citation" || !annotation.url) continue;
+		addCitationSource(
+			sources,
+			citations,
+			seenUrls,
+			annotation.url,
+			annotation.title,
+			annotation.cited_text ?? annotation.text,
+		);
+	}
+}
+
+function parseAnswer(response: XAIResponsesResponse): string | undefined {
+	const topLevelText = response.output_text?.trim();
+	if (topLevelText) return topLevelText;
+
+	const answerParts: string[] = [];
+	for (const item of response.output ?? []) {
+		for (const part of item.content ?? []) {
+			const text = part.output_text ?? part.text;
+			if ((part.type === "output_text" || part.type === "text") && text?.trim()) {
+				answerParts.push(text.trim());
+			}
+		}
+	}
+
+	const answer = answerParts.join("\n").trim();
+	return answer ? answer : undefined;
+}
+
+function parseUsage(usage: XAIResponsesUsage | null | undefined): SearchUsage | undefined {
+	if (!usage) return undefined;
+	const parsed: SearchUsage = {};
+	const inputTokens = usage.input_tokens ?? usage.inputTokens;
+	const outputTokens = usage.output_tokens ?? usage.outputTokens;
+	const totalTokens = usage.total_tokens ?? usage.totalTokens;
+
+	if (typeof inputTokens === "number") parsed.inputTokens = inputTokens;
+	if (typeof outputTokens === "number") parsed.outputTokens = outputTokens;
+	if (typeof totalTokens === "number") parsed.totalTokens = totalTokens;
+
+	return Object.keys(parsed).length > 0 ? parsed : undefined;
+}
+
+function applyResultCap(
+	sources: SearchSource[],
+	citations: SearchCitation[],
+	resultCap: number,
+): { sources: SearchSource[]; citations: SearchCitation[] } {
+	return {
+		sources: sources.slice(0, resultCap),
+		citations: citations.slice(0, resultCap),
+	};
+}
+
+function parseResponse(response: XAIResponsesResponse, resultCap: number): SearchResponse {
+	const sources: SearchSource[] = [];
+	const citations: SearchCitation[] = [];
+	const seenUrls = new Set<string>();
+
+	collectAnnotationSources(response.annotations, sources, citations, seenUrls);
+	for (const item of response.output ?? []) {
+		collectAnnotationSources(item.annotations, sources, citations, seenUrls);
+		for (const part of item.content ?? []) {
+			collectAnnotationSources(part.annotations, sources, citations, seenUrls);
+		}
+	}
+	for (const url of response.citations ?? []) {
+		addCitationSource(sources, citations, seenUrls, url);
+	}
+	const limited = applyResultCap(sources, citations, resultCap);
+
+	return {
+		provider: "xai",
+		answer: parseAnswer(response),
+		sources: limited.sources,
+		citations: limited.citations.length > 0 ? limited.citations : undefined,
+		usage: parseUsage(response.usage),
+		model: response.model,
+		requestId: response.id,
+		authMode: "api_key",
+	};
+}
+
+/** Execute xAI Responses API web search. */
+export async function searchXAI(params: SearchParams): Promise<SearchResponse> {
+	const keyOrResolver: ApiKey = params.authStorage.resolver("xai", {
+		sessionId: params.sessionId,
+	});
+
+	const resultCap = clampNumResults(params.numSearchResults ?? params.limit, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
+	const response = await withAuth(keyOrResolver, (key: string) => callXAIResponses(key, params), {
+		signal: params.signal,
+		missingKeyMessage: 'xAI credentials not found. Set XAI_API_KEY or configure an API key for provider "xai".',
+	});
+	return parseResponse(response, resultCap);
+}
+
+/** Search provider for xAI web search. */
+export class XAIProvider extends SearchProvider {
+	readonly id = "xai";
+	readonly label = "xAI";
+
+	isAvailable(authStorage: AuthStorage): boolean {
+		return authStorage.hasAuth("xai");
+	}
+
+	search(params: SearchParams): Promise<SearchResponse> {
+		return searchXAI(params);
+	}
+}

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

@@ -5,7 +5,7 @@
  * 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 { asRecord, asString } from "../../../web/scrapers/utils";
+import { isRecord } from "@oh-my-pi/pi-utils";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { dateToAgeSeconds } from "../utils";
@@ -54,49 +54,24 @@ interface JsonRpcPayload {
 	error?: JsonRpcError;
 }
 
-/** Resolve Z.AI API credentials through the unified auth storage pipeline. */
-export async function findApiKey(
-	authStorage: AuthStorage,
-	sessionId?: string,
-	signal?: AbortSignal,
-): Promise<string | null> {
-	return (await authStorage.getApiKey("zai", sessionId, { signal })) ?? null;
+interface ZaiMcpPostResult {
+	parsed?: unknown;
+	sessionId?: string;
 }
 
-async function callZaiTool(
-	apiKey: string,
-	args: Record<string, unknown>,
-	signal: AbortSignal | undefined,
-	fetchImpl: FetchImpl,
-): Promise<unknown> {
-	const response = await fetchImpl(ZAI_MCP_URL, {
-		method: "POST",
-		headers: {
-			Authorization: `Bearer ${apiKey}`,
-			"Content-Type": "application/json",
-			Accept: "application/json, text/event-stream",
-		},
-		body: JSON.stringify({
-			jsonrpc: "2.0",
-			id: crypto.randomUUID(),
-			method: "tools/call",
-			params: {
-				name: ZAI_TOOL_NAME,
-				arguments: args,
-			},
-		}),
-		signal: withHardTimeout(signal),
-	});
-
-	if (!response.ok) {
-		const errorText = await response.text();
-		const classified = classifyProviderHttpError("zai", response.status, errorText);
-		if (classified) throw classified;
-		throw new SearchProviderError("zai", `Z.AI MCP error (${response.status}): ${errorText}`, response.status);
-	}
+const ZAI_MCP_PROTOCOL_VERSION = "2025-03-26";
+const ZAI_MCP_CLIENT_INFO = {
+	name: "omp-coding-agent",
+	version: "1.0.0",
+};
 
-	const rawText = await response.text();
+function asString(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
 
+function parseZaiMcpResponse(rawText: string): unknown {
 	const parsedMessages: unknown[] = [];
 	for (const line of rawText.split("\n")) {
 		const trimmed = line.trim();
@@ -118,8 +93,64 @@ async function callZaiTool(
 		}
 	}
 
-	const parsed = parsedMessages[parsedMessages.length - 1];
-	const parsedRecord = asRecord(parsed);
+	return parsedMessages[parsedMessages.length - 1];
+}
+
+async function postZaiMcp(
+	apiKey: string,
+	method: string,
+	params: Record<string, unknown>,
+	sessionId: string | undefined,
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+	expectResponse: boolean,
+): Promise<ZaiMcpPostResult> {
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${apiKey}`,
+		"Content-Type": "application/json",
+		Accept: "application/json, text/event-stream",
+	};
+	if (sessionId) {
+		headers["Mcp-Session-Id"] = sessionId;
+	}
+
+	const body: Record<string, unknown> = {
+		jsonrpc: "2.0",
+		method,
+		params,
+	};
+	if (expectResponse) {
+		body.id = crypto.randomUUID();
+	}
+
+	const response = await fetchImpl(ZAI_MCP_URL, {
+		method: "POST",
+		headers,
+		body: JSON.stringify(body),
+		signal: withHardTimeout(signal),
+	});
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		const classified = classifyProviderHttpError("zai", response.status, errorText);
+		if (classified) throw classified;
+		throw new SearchProviderError("zai", `Z.AI MCP error (${response.status}): ${errorText}`, response.status);
+	}
+
+	const nextSessionId = response.headers.get("Mcp-Session-Id") ?? sessionId;
+	if (!expectResponse) {
+		await response.body?.cancel();
+		return { sessionId: nextSessionId };
+	}
+
+	return {
+		parsed: parseZaiMcpResponse(await response.text()),
+		sessionId: nextSessionId,
+	};
+}
+
+function readJsonRpcPayload(parsed: unknown): JsonRpcPayload {
+	const parsedRecord = isRecord(parsed) ? parsed : null;
 	const directErrorCode = typeof parsedRecord?.code === "number" ? parsedRecord.code : undefined;
 	const directErrorSuccess = parsedRecord?.success;
 	const directErrorMessage =
@@ -132,6 +163,10 @@ async function callZaiTool(
 		);
 	}
 
+	if (!isRecord(parsed)) {
+		throw new SearchProviderError("zai", "Failed to parse Z.AI MCP response", 500);
+	}
+
 	const payload = parsed as JsonRpcPayload;
 	if (payload.error) {
 		const status = typeof payload.error.code === "number" ? payload.error.code : 400;
@@ -142,11 +177,64 @@ async function callZaiTool(
 		);
 	}
 
-	const resultRecord = asRecord(payload.result);
+	return payload;
+}
+
+/** Resolve Z.AI API credentials through the unified auth storage pipeline. */
+export async function findApiKey(
+	authStorage: AuthStorage,
+	sessionId?: string,
+	signal?: AbortSignal,
+): Promise<string | null> {
+	return (await authStorage.getApiKey("zai", sessionId, { signal })) ?? null;
+}
+
+async function callZaiTool(
+	apiKey: string,
+	args: Record<string, unknown>,
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
+): Promise<unknown> {
+	const initialized = await postZaiMcp(
+		apiKey,
+		"initialize",
+		{
+			protocolVersion: ZAI_MCP_PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: ZAI_MCP_CLIENT_INFO,
+		},
+		undefined,
+		signal,
+		fetchImpl,
+		true,
+	);
+	if (initialized.parsed !== undefined) {
+		readJsonRpcPayload(initialized.parsed);
+	}
+
+	await postZaiMcp(apiKey, "notifications/initialized", {}, initialized.sessionId, signal, fetchImpl, false);
+
+	const toolCall = await postZaiMcp(
+		apiKey,
+		"tools/call",
+		{
+			name: ZAI_TOOL_NAME,
+			arguments: args,
+		},
+		initialized.sessionId,
+		signal,
+		fetchImpl,
+		true,
+	);
+	const payload = readJsonRpcPayload(toolCall.parsed);
+	const resultRecord = isRecord(payload.result) ? payload.result : null;
 	if (resultRecord?.isError === true) {
 		const content = Array.isArray(resultRecord.content) ? resultRecord.content : [];
 		const errorText = content
-			.map(item => asString(asRecord(item)?.text))
+			.map(item => {
+				if (!isRecord(item)) return null;
+				return asString(item.text);
+			})
 			.filter((text): text is string => text != null)
 			.join("\n")
 			.trim();
@@ -159,7 +247,7 @@ async function callZaiTool(
 		return payload.result;
 	}
 
-	return parsed;
+	return toolCall.parsed;
 }
 
 async function callZaiSearch(apiKey: string, params: ZaiSearchParams): Promise<unknown> {
@@ -204,8 +292,8 @@ function getSearchResults(value: unknown): ZaiSearchResult[] {
 	if (Array.isArray(value)) {
 		return value as ZaiSearchResult[];
 	}
-	const obj = asRecord(value);
-	if (!obj) return [];
+	if (!isRecord(value)) return [];
+	const obj = value;
 
 	const searchResult = obj.search_result;
 	if (Array.isArray(searchResult)) return searchResult as ZaiSearchResult[];
@@ -224,17 +312,15 @@ function parseSearchPayload(rawResult: unknown): {
 	const candidates: unknown[] = [rawResult];
 	const textParts: string[] = [];
 
-	const root = asRecord(rawResult);
-	if (root) {
-		if (root.structuredContent) candidates.push(root.structuredContent);
-		if (root.data) candidates.push(root.data);
-		if (root.result) candidates.push(root.result);
+	if (isRecord(rawResult)) {
+		if (rawResult.structuredContent) candidates.push(rawResult.structuredContent);
+		if (rawResult.data) candidates.push(rawResult.data);
+		if (rawResult.result) candidates.push(rawResult.result);
 
-		const content = root.content;
+		const content = rawResult.content;
 		if (Array.isArray(content)) {
 			for (const part of content) {
-				const partObj = asRecord(part);
-				const text = asString(partObj?.text);
+				const text = isRecord(part) ? asString(part.text) : null;
 				if (!text) continue;
 				textParts.push(text);
 				try {
@@ -249,7 +335,7 @@ function parseSearchPayload(rawResult: unknown): {
 	for (const candidate of candidates) {
 		const results = getSearchResults(candidate);
 		if (results.length > 0) {
-			const obj = asRecord(candidate) as ZaiWebSearchResponse | null;
+			const obj = isRecord(candidate) ? (candidate as ZaiWebSearchResponse) : null;
 			return {
 				results,
 				answer: textParts.length > 0 ? textParts.join("\n\n") : undefined,

package/src/web/search/types.ts

@@ -30,16 +30,20 @@ export const SEARCH_PROVIDER_OPTIONS = [
 		label: "OpenAI",
 		description: "OpenAI's native web_search (uses ChatGPT OAuth via /login openai-codex)",
 	},
+	{ value: "xai", label: "xAI", description: "Grok web search via xAI Responses API (requires XAI_API_KEY)" },
 	{ value: "zai", label: "Z.AI", description: "Calls Z.AI webSearchPrime MCP" },
 	{ value: "exa", label: "Exa", description: "Uses Exa API when EXA_API_KEY is set; falls back to Exa MCP" },
+	{ value: "tinyfish", label: "TinyFish", description: "Requires TINYFISH_API_KEY" },
 	{ value: "jina", label: "Jina", description: "Requires JINA_API_KEY" },
 	{ value: "kagi", label: "Kagi", description: "Requires KAGI_API_KEY and Kagi Search API beta access" },
 	{ value: "tavily", label: "Tavily", description: "Requires TAVILY_API_KEY" },
+	{ value: "firecrawl", label: "Firecrawl", description: "Requires FIRECRAWL_API_KEY" },
 	{ value: "brave", label: "Brave", description: "Requires BRAVE_API_KEY" },
 	{ value: "kimi", label: "Kimi", description: "Requires MOONSHOT_SEARCH_API_KEY or MOONSHOT_API_KEY" },
 	{ value: "parallel", label: "Parallel", description: "Requires PARALLEL_API_KEY" },
 	{ value: "synthetic", label: "Synthetic", description: "Requires SYNTHETIC_API_KEY" },
 	{ value: "searxng", label: "SearXNG", description: "Requires SEARXNG_ENDPOINT or searxng.endpoint" },
+	{ value: "duckduckgo", label: "DuckDuckGo", description: "Uses DuckDuckGo Instant Answer API (no API key)" },
 ] as const;
 
 /** Supported web search providers (every option except `auto`). */
@@ -81,7 +85,7 @@ export interface SearchSource {
 	author?: string;
 }
 
-/** Citation with text reference (anthropic, perplexity) */
+/** Citation with text reference (LLM-mediated providers) */
 export interface SearchCitation {
 	url: string;
 	title: string;
@@ -101,7 +105,7 @@ export interface SearchUsage {
 /** Unified response across providers */
 export interface SearchResponse {
 	provider: SearchProviderId | "none";
-	/** Synthesized answer text (anthropic, perplexity) */
+	/** Synthesized answer text (LLM-mediated providers) */
 	answer?: string;
 	/** Search result sources */
 	sources: SearchSource[];