repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

extensions/web/zai.ts

Raw
/**
 * Z.AI Coding Plan Web Search client.
 * Uses the Coding Plan MCP endpoint, not the paid REST Web Search API.
 * Docs: https://docs.z.ai/devpack/mcp/search-mcp-server
 */

import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
import type { SearchResult } from "./constants.js";

export type ZaiSearchFreshness = "day" | "week" | "month" | "year";

type ZaiRecencyFilter =
	| "oneDay"
	| "oneWeek"
	| "oneMonth"
	| "oneYear"
	| "noLimit";

interface ZaiSearchObjectResponse {
	title?: string;
	content?: string;
	link?: string;
	url?: string;
	media?: string;
	icon?: string;
	refer?: string;
	publish_date?: string;
	date?: string;
}

interface ZaiErrorResponse {
	code?: number | string;
	message?: string;
	error?: { code?: number | string; message?: string };
}

interface JsonRpcResponse<T = unknown> {
	jsonrpc?: string;
	id?: string | number | null;
	result?: T;
	error?: { code?: number | string; message?: string; data?: unknown };
}

interface McpInitializeResult {
	protocolVersion?: string;
	capabilities?: Record<string, unknown>;
	serverInfo?: Record<string, unknown>;
}

interface McpToolCallResult {
	content?: Array<{ type?: string; text?: string }>;
	isError?: boolean;
}

export class ZaiApiError extends Error {
	constructor(
		message: string,
		public readonly code?: string,
		public readonly status?: number,
		public readonly rawMessage = "unknown error",
	) {
		super(message);
		this.name = "ZaiApiError";
	}
}

const DEFAULT_ZAI_MCP_URL = "https://api.z.ai/api/mcp/web_search_prime/mcp";
const ZAI_PROVIDER_NAMES = ["zai", "z-ai", "z.ai", "bigmodel"] as const;
const ZAI_API_KEY_ENV = ["ZAI_API_KEY", "Z_AI_API_KEY"] as const;
const ZAI_NO_FRESHNESS = new Set(["", "none", "nolimit", "no_limit"]);
const ZAI_FRESHNESS = new Set(["day", "week", "month", "year"]);

const FRESHNESS_TO_RECENCY: Record<ZaiSearchFreshness, ZaiRecencyFilter> = {
	day: "oneDay",
	week: "oneWeek",
	month: "oneMonth",
	year: "oneYear",
};

function resolveDefaultFreshness(): ZaiSearchFreshness | undefined {
	const value = process.env.ZAI_SEARCH_FRESHNESS?.trim().toLowerCase() ?? "";
	if (ZAI_NO_FRESHNESS.has(value)) return undefined;
	return ZAI_FRESHNESS.has(value) ? (value as ZaiSearchFreshness) : undefined;
}

export async function resolveZaiApiKey(
	ctx?: ExtensionContext,
): Promise<string | undefined> {
	if (ctx) {
		for (const provider of ZAI_PROVIDER_NAMES) {
			const key = await ctx.modelRegistry.getApiKeyForProvider(provider);
			if (key) return key;
		}
	}

	for (const envName of ZAI_API_KEY_ENV) {
		const value = process.env[envName]?.trim();
		if (value) return value;
	}
	return undefined;
}

export function resolveZaiMcpUrl(): string {
	const envUrl =
		process.env.ZAI_SEARCH_MCP_URL?.trim() ||
		process.env.ZAI_SEARCH_BASE_URL?.trim();
	if (envUrl) return normalizeMcpUrl(envUrl);
	return DEFAULT_ZAI_MCP_URL;
}

export async function isZaiAvailable(ctx?: ExtensionContext): Promise<boolean> {
	return !!(await resolveZaiApiKey(ctx));
}

function normalizeMcpUrl(input: string): string {
	const value = input.trim().replace(/\/+$/, "");
	try {
		const url = new URL(value);
		if (url.pathname.endsWith("/mcp")) return value;
		return `${url.origin}/api/mcp/web_search_prime/mcp`;
	} catch {}
	return value.endsWith("/mcp")
		? value
		: `${value}/api/mcp/web_search_prime/mcp`;
}

function makeZaiApiError(
	status: number | undefined,
	code: unknown,
	message: unknown,
): ZaiApiError {
	const codeText =
		code === undefined || code === null ? undefined : String(code);
	const rawMessage =
		typeof message === "string" && message ? message : "unknown error";
	const tag = codeText
		? ` (${codeText})`
		: status !== undefined && status >= 400
			? ` (HTTP ${status})`
			: "";
	return new ZaiApiError(
		`Z.AI API error${tag}: ${rawMessage}`,
		codeText,
		status,
		rawMessage,
	);
}

async function parseZaiError(response: Response): Promise<ZaiApiError> {
	const text = await response.text().catch(() => "");
	if (!text)
		return makeZaiApiError(
			response.status,
			undefined,
			response.statusText || "request failed",
		);
	try {
		const data = JSON.parse(text) as ZaiErrorResponse;
		return makeZaiApiError(
			response.status,
			data.error?.code ?? data.code,
			data.error?.message ?? data.message ?? response.statusText,
		);
	} catch {}
	return makeZaiApiError(
		response.status,
		undefined,
		`${response.statusText}: ${text.slice(0, 500)}`,
	);
}

function parseSseOrJson<T>(text: string): JsonRpcResponse<T> {
	const trimmed = text.trim();
	if (!trimmed) return {};

	const dataLines = trimmed
		.split(/\r?\n/)
		.filter((line) => line.startsWith("data:"))
		.map((line) => line.slice(5).trim())
		.filter(Boolean);

	if (dataLines.length > 0) {
		for (const dataLine of dataLines) {
			const parsed = JSON.parse(dataLine) as JsonRpcResponse<T>;
			if (parsed.result !== undefined || parsed.error !== undefined)
				return parsed;
		}
		return JSON.parse(dataLines[dataLines.length - 1]) as JsonRpcResponse<T>;
	}

	return JSON.parse(trimmed) as JsonRpcResponse<T>;
}

async function postJsonRpc<T>(
	url: string,
	apiKey: string,
	payload: Record<string, unknown>,
	signal: AbortSignal,
	sessionId?: string,
): Promise<{ data: JsonRpcResponse<T>; sessionId?: string }> {
	const response = await fetch(url, {
		method: "POST",
		headers: {
			Authorization: `Bearer ${apiKey}`,
			"Content-Type": "application/json",
			Accept: "application/json, text/event-stream",
			...(sessionId ? { "mcp-session-id": sessionId } : {}),
		},
		body: JSON.stringify(payload),
		signal,
	});

	if (!response.ok) {
		throw await parseZaiError(response);
	}

	const text = await response.text();
	if (!text.trim())
		return {
			data: {},
			sessionId: response.headers.get("mcp-session-id") ?? undefined,
		};

	let data: JsonRpcResponse<T>;
	try {
		data = parseSseOrJson<T>(text);
	} catch {
		throw makeZaiApiError(
			response.status,
			undefined,
			`Malformed MCP response: ${text.slice(0, 500)}`,
		);
	}

	if (data.error) {
		throw makeZaiApiError(response.status, data.error.code, data.error.message);
	}

	return {
		data,
		sessionId: response.headers.get("mcp-session-id") ?? undefined,
	};
}

async function initializeMcpSession(
	url: string,
	apiKey: string,
	signal: AbortSignal,
): Promise<string | undefined> {
	const { sessionId } = await postJsonRpc<McpInitializeResult>(
		url,
		apiKey,
		{
			jsonrpc: "2.0",
			id: 1,
			method: "initialize",
			params: {
				protocolVersion: "2025-03-26",
				capabilities: {},
				clientInfo: { name: "pi-web-extension", version: "0.1.0" },
			},
		},
		signal,
	);

	await postJsonRpc(
		url,
		apiKey,
		{
			jsonrpc: "2.0",
			method: "notifications/initialized",
			params: {},
		},
		signal,
		sessionId,
	);

	return sessionId;
}

function decodeSearchItems(text: string): ZaiSearchObjectResponse[] {
	let value: unknown = text.trim();

	for (let i = 0; i < 3 && typeof value === "string"; i++) {
		try {
			value = JSON.parse(value);
		} catch {
			break;
		}
	}

	if (Array.isArray(value)) return value as ZaiSearchObjectResponse[];
	if (value && typeof value === "object") {
		const record = value as {
			search_result?: ZaiSearchObjectResponse[];
			results?: ZaiSearchObjectResponse[];
		};
		if (Array.isArray(record.search_result)) return record.search_result;
		if (Array.isArray(record.results)) return record.results;
	}

	return [];
}

function mcpResultToSearchResults(result: McpToolCallResult): SearchResult[] {
	const text =
		result.content?.find((item) => item.type === "text" && item.text)?.text ??
		result.content?.find((item) => item.text)?.text;

	if (result.isError) {
		throw makeZaiApiError(200, undefined, text ?? "MCP tool returned an error");
	}
	if (!text) return [];

	return decodeSearchItems(text)
		.map((r) => ({
			title: r.title ?? r.link ?? r.url ?? "Untitled",
			url: r.link ?? r.url ?? "",
			snippet: r.content ?? r.media ?? "",
			date: r.publish_date ?? r.date,
		}))
		.filter((r) => r.url);
}

export async function zaiSearch(
	query: string,
	ctx: ExtensionContext | undefined,
	signal?: AbortSignal,
	options?: {
		count?: number;
		freshness?: ZaiSearchFreshness;
		timeoutMs?: number;
	},
): Promise<SearchResult[]> {
	const apiKey = await resolveZaiApiKey(ctx);
	if (!apiKey) {
		throw new Error(
			"Z.AI API key not configured. Set ZAI_API_KEY or configure a zai provider.",
		);
	}

	const freshness = options?.freshness ?? resolveDefaultFreshness();
	const toolArgs: Record<string, unknown> = {
		search_query: query,
		content_size: process.env.ZAI_SEARCH_CONTENT_SIZE?.trim() || "medium",
		location: process.env.ZAI_SEARCH_LOCATION?.trim() || "us",
	};
	if (freshness)
		toolArgs.search_recency_filter = FRESHNESS_TO_RECENCY[freshness];

	const timeoutSignal = AbortSignal.timeout(options?.timeoutMs ?? 30_000);
	const requestSignal = signal
		? AbortSignal.any([signal, timeoutSignal])
		: timeoutSignal;
	const url = resolveZaiMcpUrl();
	const sessionId = await initializeMcpSession(url, apiKey, requestSignal);

	const { data } = await postJsonRpc<McpToolCallResult>(
		url,
		apiKey,
		{
			jsonrpc: "2.0",
			id: 2,
			method: "tools/call",
			params: {
				name: "web_search_prime",
				arguments: toolArgs,
			},
		},
		requestSignal,
		sessionId,
	);

	const results = mcpResultToSearchResults(data.result ?? {});
	const count = Math.min(
		Math.max(Math.trunc(options?.count ?? results.length), 1),
		50,
	);
	return results.slice(0, count);
}