@herbertgao/pi-extensions 2026.9.17 → 2026.9.19

package/node_modules/pi-web-access/tavily.ts

@@ -60,6 +60,19 @@ async function getApiKey(signal?: AbortSignal): Promise<string | null> {
 	});
 }
 
+const TAVILY_KEY_POOL_RETRIES = new Set([401, 402, 403, 429, 432]);
+
+function tavilyKeyPool(): string[] {
+	const slots: Array<[number, string]> = [];
+	for (let slot = 1; slot <= 20; slot++) {
+		const key = process.env[`TAVILY_API_KEY_${slot}`]?.trim();
+		if (key) slots.push([slot, key]);
+	}
+	const requestedSlot = Number.parseInt(process.env.TAVILY_API_KEY_INDEX ?? "", 10) || 1;
+	const start = Math.max(0, slots.findIndex(([slot]) => slot >= requestedSlot));
+	return [...new Set([...slots.slice(start), ...slots.slice(0, start)].map(([, key]) => key))];
+}
+
 function getApiUrl(): string {
 	return `${resolveApiBaseUrl({
 		configKey: "tavilyBaseUrl",
@@ -141,12 +154,11 @@ export function isTavilyAvailable(): boolean {
 		provider: "Tavily",
 		configuredValue: loadConfig().tavilyApiKey,
 		environmentValue: process.env.TAVILY_API_KEY,
-	});
+	}) || tavilyKeyPool().length > 0;
 }
 
 export async function searchWithTavily(query: string, options: TavilySearchOptions = {}): Promise<SearchResponse> {
 	const apiUrl = getApiUrl();
-	const apiKey = await requireApiKey(options.signal);
 	const numResults = normalizeSearchResultCount(options.numResults);
 	const body: Record<string, unknown> = {
 		query,
@@ -158,7 +170,58 @@ export async function searchWithTavily(query: string, options: TavilySearchOptio
 		...mapDomainFilter(options.domainFilter),
 	};
 
+	const signal = requestSignal(options.signal);
 	const activityId = activityMonitor.logStart({ type: "api", query });
+	let data: TavilyResponse;
+	try {
+		data = await requestWithKeyFailover(apiUrl, body, signal);
+	} catch (err) {
+		if (options.signal?.aborted || (err instanceof Error && err.name === "AbortError")) activityMonitor.logComplete(activityId, 0);
+		else {
+			const status = tavilyErrorStatus(err);
+			if (status > 0) activityMonitor.logComplete(activityId, status);
+			else activityMonitor.logError(activityId, errorMessage(err));
+		}
+		throw err;
+	}
+
+	activityMonitor.logComplete(activityId, 200);
+	const result: SearchResponse = {
+		answer: typeof data.answer === "string" ? data.answer : "",
+		results: mapResults(data.results, numResults),
+	};
+	if (options.includeContent) {
+		const inlineContent = mapInlineContent(data.results);
+		if (inlineContent.length > 0) result.inlineContent = inlineContent;
+	}
+	return result;
+}
+
+function tavilyErrorStatus(err: unknown): number {
+	return Number(errorMessage(err).match(/^Tavily API error (\d{3}):/)?.[1] ?? 0);
+}
+
+async function requestWithKeyFailover(apiUrl: string, body: Record<string, unknown>, signal: AbortSignal): Promise<TavilyResponse> {
+	const pool = tavilyKeyPool();
+	const keys = pool.length > 0 ? pool : [await requireApiKey(signal)];
+	let fallbackChecked = pool.length === 0;
+	for (let i = 0; ; i++) {
+		try {
+			return await tavilyRequest(apiUrl, keys[i], body, signal);
+		} catch (err) {
+			if (!TAVILY_KEY_POOL_RETRIES.has(tavilyErrorStatus(err))) throw err;
+			if (i + 1 < keys.length) continue;
+			if (fallbackChecked) throw err;
+			// Resolve the standalone credential only after every numbered pool key failed.
+			fallbackChecked = true;
+			const fallback = await getApiKey(signal);
+			if (!fallback || keys.includes(fallback)) throw err;
+			keys.push(fallback);
+		}
+	}
+}
+
+async function tavilyRequest(apiUrl: string, apiKey: string, body: Record<string, unknown>, signal: AbortSignal): Promise<TavilyResponse> {
 	let response: Response;
 	try {
 		response = await fetchWithCredentialRedirects(apiUrl, {
@@ -168,13 +231,11 @@ export async function searchWithTavily(query: string, options: TavilySearchOptio
 				"Content-Type": "application/json",
 			},
 			body: JSON.stringify(body),
-			signal: requestSignal(options.signal),
+			signal,
 		}, ["Authorization"]);
 	} catch (err) {
 		const message = errorMessage(err);
 		const redactedMessage = redactCredential(message, apiKey);
-		if (redactedMessage.toLowerCase().includes("abort")) activityMonitor.logComplete(activityId, 0);
-		else activityMonitor.logError(activityId, redactedMessage);
 		if (redactedMessage === message) throw err;
 		const redactedError = new Error(redactedMessage);
 		if (err instanceof Error) redactedError.name = err.name;
@@ -182,27 +243,13 @@ export async function searchWithTavily(query: string, options: TavilySearchOptio
 	}
 
 	if (!response.ok) {
-		activityMonitor.logComplete(activityId, response.status);
 		const errorText = redactCredential(await response.text(), apiKey);
 		throw new Error(`Tavily API error ${response.status}: ${errorText.slice(0, 300)}`);
 	}
 
-	let data: TavilyResponse;
 	try {
-		data = await response.json() as TavilyResponse;
+		return await response.json() as TavilyResponse;
 	} catch (err) {
-		activityMonitor.logComplete(activityId, response.status);
 		throw new Error(`Tavily API returned invalid JSON: ${errorMessage(err)}`);
 	}
-
-	activityMonitor.logComplete(activityId, response.status);
-	const result: SearchResponse = {
-		answer: typeof data.answer === "string" ? data.answer : "",
-		results: mapResults(data.results, numResults),
-	};
-	if (options.includeContent) {
-		const inlineContent = mapInlineContent(data.results);
-		if (inlineContent.length > 0) result.inlineContent = inlineContent;
-	}
-	return result;
 }

package/node_modules/pi-web-access/tool-activation.ts

@@ -1,7 +1,4 @@
-import { buildSessionContext, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { dirname, join } from "node:path";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import { buildSessionContext, type ExtensionAPI, type ExtensionContext, type SessionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 export type WebCapability = "search" | "source-check" | "fetch" | "stored-content";
@@ -21,31 +18,52 @@ const CAPABILITY_LABELS: Record<WebCapability, string> = {
 
 function supportsDynamicTools(pi: ExtensionAPI): boolean {
 	if (typeof pi.getAllTools !== "function" || typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return false;
-	try {
-		const packagePath = join(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "..", "package.json");
-		const [major, minor, patch] = JSON.parse(readFileSync(packagePath, "utf8")).version.split(".").map(Number);
-		return major > 0 || minor > 86 || minor === 86 && patch >= 1;
-	} catch {
-		return false;
-	}
+	// Pi 0.86.0 shipped transcript-backed tool changes in the same release that made pi.on() return
+	// an unsubscribe function. Probe the host API object: an imported VERSION can come from a stale
+	// Pi package installed beside this extension instead of the running host.
+	const unsubscribe: unknown = pi.on("session_start", () => {});
+	if (typeof unsubscribe !== "function") return false;
+	unsubscribe();
+	return true;
 }
 
-function hasToolDeclarations(messages: unknown[]): boolean {
-	return messages.some(message => message && typeof message === "object" && (
-		"toolsAdded" in message || "toolsRemoved" in message
-	));
+// Mirrors pi-ai's per-API transcript handling: without these flags, Pi resends the whole transcript
+// as a checkpoint when web_enable changes the tools and prompt, which can miss the prompt cache.
+function addsToolsWithoutCheckpoint(model: ExtensionContext["model"]): boolean {
+	const compat = model?.compat as {
+		supportsMidConvoSystemMessages?: boolean;
+		supportsMidConvoToolChanges?: boolean;
+		supportsMidConvoToolAdditions?: boolean;
+		supportsAdditionalTools?: boolean;
+		supportsToolSearch?: boolean;
+	} | undefined;
+	if (!model || compat?.supportsMidConvoSystemMessages !== true) return false;
+	switch (model.api) {
+		case "anthropic-messages": return compat.supportsMidConvoToolChanges === true;
+		case "openai-completions": return compat.supportsMidConvoToolAdditions === true;
+		case "openai-responses":
+		case "openai-codex-responses":
+		case "azure-openai-responses": return compat.supportsAdditionalTools === true || compat.supportsToolSearch === true;
+		default: return false;
+	}
 }
 
-async function currentTranscriptToolNames(messages: unknown[]): Promise<string[]> {
-	const moduleName = "@earendil-works/pi-ai/utils/transcript";
-	const { getCurrentTools } = await import(moduleName);
-	return getCurrentTools(messages).map((tool: { name: string }) => tool.name);
+// Undefined when the transcript never declared tool changes.
+function transcriptToolNames(messages: SessionContext["messages"]): Set<string> | undefined {
+	let tools: Set<string> | undefined;
+	for (const message of messages) {
+		if (message.role !== "system" || !("toolsAdded" in message || "toolsRemoved" in message)) continue;
+		tools ??= new Set();
+		for (const tool of message.toolsRemoved ?? []) tools.delete(tool.name);
+		for (const tool of message.toolsAdded ?? []) tools.add(tool.name);
+	}
+	return tools;
 }
 
-export function registerWebToolActivation(pi: ExtensionAPI, tools: ReadonlyArray<WebActivationTool>): void {
+export function registerWebToolActivation(pi: ExtensionAPI, tools: ReadonlyArray<WebActivationTool>, mode: "auto" | "dynamic"): void {
 	if (tools.length === 0) return;
 	if (!supportsDynamicTools(pi)) {
-		console.warn("[pi-web-access] Dynamic tool activation requires Pi 0.86.1 or newer; web tools remain eagerly available.");
+		console.warn("[pi-web-access] Dynamic tool activation requires Pi 0.86.0 or newer; web tools remain eagerly available.");
 		return;
 	}
 	const names = tools.map(tool => tool.name);
@@ -56,7 +74,7 @@ export function registerWebToolActivation(pi: ExtensionAPI, tools: ReadonlyArray
 		name: LOADER_NAME,
 		label: "Enable Web Access",
 		description: "Enable configured pi-web-access tools for web research and content retrieval. Does not search or fetch. Enabled tools are available on the next model request; disabled capabilities remain unavailable.",
-		promptSnippet: `pi-web-access is configured for ${capabilities}. Call web_enable to activate these tools; use them on the next model request.`,
+		promptSnippet: `If tools for ${capabilities} are not already available, call web_enable first whenever current, external, or linked information could help; the tools appear on the next model request.`,
 		parameters,
 		async execute() {
 			const registered = new Set(pi.getAllTools().map(tool => tool.name));
@@ -100,19 +118,21 @@ export function registerWebToolActivation(pi: ExtensionAPI, tools: ReadonlyArray
 	}
 
 	let warned = false;
-	async function selectFromSession(ctx: ExtensionContext): Promise<void> {
+	// A resumed transcript that declared its tools without the loader keeps that set; adding the
+	// loader there would record a mid-conversation tool change the user never asked for (#462).
+	let loaderSelected = true;
+	function selectFromSession(ctx: ExtensionContext): void {
 		if (!loaderAvailable()) return;
 		try {
 			const messages = buildSessionContext(ctx.sessionManager.getBranch()).messages;
-			const recorded = hasToolDeclarations(messages)
-				? new Set(await currentTranscriptToolNames(messages))
-				: messages.length > 0
-					? new Set(names)
-					: new Set<string>();
-			const heavy = new Set(names);
-			const active = pi.getActiveTools().filter(name => !heavy.has(name));
-			for (const name of names) if (recorded.has(name)) active.push(name);
-			pi.setActiveTools([...new Set([...active, LOADER_NAME])]);
+			const declared = transcriptToolNames(messages);
+			// "auto" decides once, for a fresh session; recorded sessions keep their tools.
+			const eager = mode === "auto" && !declared && messages.length === 0 && !addsToolsWithoutCheckpoint(ctx.model);
+			// Sessions from before transcript tool declarations keep every web tool; fresh ones start with none.
+			const recorded = declared ?? new Set(messages.length > 0 || eager ? names : []);
+			loaderSelected = !eager && (!declared || declared.has(LOADER_NAME));
+			const others = pi.getActiveTools().filter(name => name !== LOADER_NAME && !names.includes(name));
+			pi.setActiveTools([...new Set([...others, ...names.filter(name => recorded.has(name)), ...(loaderSelected ? [LOADER_NAME] : [])])]);
 		} catch (error) {
 			if (!warned) {
 				warned = true;
@@ -124,7 +144,7 @@ export function registerWebToolActivation(pi: ExtensionAPI, tools: ReadonlyArray
 	pi.on("session_start", (_event, ctx) => selectFromSession(ctx));
 	pi.on("session_tree", (_event, ctx) => selectFromSession(ctx));
 	pi.on("before_agent_start", () => {
-		if (!loaderAvailable() || pi.getActiveTools().includes(LOADER_NAME)) return;
+		if (!loaderSelected || !loaderAvailable() || pi.getActiveTools().includes(LOADER_NAME)) return;
 		try {
 			pi.setActiveTools([...pi.getActiveTools(), LOADER_NAME]);
 		} catch {

package/node_modules/pi-web-access/utils.ts

@@ -249,7 +249,7 @@ function redactProxyUrl(value: string): string {
 	return parsed.toString();
 }
 
-function loadConfiguredProxy(): string | null {
+export function loadConfiguredProxy(): string | null {
 	let configured: unknown;
 	const path = getWebSearchConfigPath();
 	if (existsSync(path)) {

package/node_modules/pi-web-access/you.ts

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync } from "node:fs";
+import { activityMonitor } from "./activity.ts";
+import { normalizeDomain } from "./domain-filter-normalization.ts";
+import type { SearchOptions, SearchResponse } from "./perplexity.ts";
+import { formatSearchResultsAsAnswer } from "./search-answer-formatting.ts";
+import { normalizeSearchResultCount } from "./search-result-count-normalization.ts";
+import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
+import { fetchWithCredentialRedirects, getWebSearchConfigPath } from "./utils.ts";
+
+const YOU_SEARCH_URL = "https://ydc-index.io/v1/search";
+const CONFIG_PATH = getWebSearchConfigPath();
+const SEARCH_TIMEOUT_MS = 60_000;
+
+interface WebSearchConfig {
+	youApiKey?: unknown;
+}
+
+let cachedConfig: WebSearchConfig | null = null;
+
+function loadConfig(): WebSearchConfig {
+	if (cachedConfig) return cachedConfig;
+	if (!existsSync(CONFIG_PATH)) {
+		cachedConfig = {};
+		return cachedConfig;
+	}
+	const raw = readFileSync(CONFIG_PATH, "utf-8");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${CONFIG_PATH}: ${message}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Invalid config in ${CONFIG_PATH}: expected a JSON object`);
+	}
+	cachedConfig = parsed as WebSearchConfig;
+	return cachedConfig;
+}
+
+async function requireApiKey(signal?: AbortSignal): Promise<string> {
+	const apiKey = await resolveCredential({
+		provider: "You.com",
+		configuredValue: loadConfig().youApiKey,
+		environmentValue: process.env.YDC_API_KEY,
+		signal,
+	});
+	if (!apiKey) {
+		throw new Error(
+			"You.com API key not found. Either:\n" +
+			`  1. Create ${CONFIG_PATH} with { "youApiKey": "your-key" }\n` +
+			"  2. Set YDC_API_KEY environment variable\n" +
+			"Get a key at https://you.com/platform/api-keys",
+		);
+	}
+	return apiKey;
+}
+
+function mapDomainFilter(domainFilter: string[] | undefined): { include_domains?: string[]; exclude_domains?: string[] } {
+	const include_domains: string[] = [];
+	const exclude_domains: string[] = [];
+	for (const raw of domainFilter ?? []) {
+		const domain = normalizeDomain(raw);
+		if (!domain) continue;
+		const target = raw.trim().startsWith("-") ? exclude_domains : include_domains;
+		if (!target.includes(domain)) target.push(domain);
+	}
+	return {
+		...(include_domains.length > 0 ? { include_domains } : {}),
+		...(exclude_domains.length > 0 ? { exclude_domains } : {}),
+	};
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function parseWebResults(value: unknown): unknown[] {
+	const results = value && typeof value === "object" ? (value as { results?: unknown }).results : undefined;
+	const web = results && typeof results === "object" ? (results as { web?: unknown }).web : undefined;
+	if (!Array.isArray(web)) throw new Error("You.com returned invalid response: expected results.web array");
+	return web;
+}
+
+export function isYouAvailable(): boolean {
+	return hasCredentialSource({ provider: "You.com", configuredValue: loadConfig().youApiKey, environmentValue: process.env.YDC_API_KEY });
+}
+
+export async function searchWithYou(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+	const apiKey = await requireApiKey(options.signal);
+	const numResults = normalizeSearchResultCount(options.numResults);
+	const body = {
+		query,
+		count: numResults,
+		...(options.recencyFilter ? { freshness: options.recencyFilter } : {}),
+		...mapDomainFilter(options.domainFilter),
+	};
+	const activityId = activityMonitor.logStart({ type: "api", query });
+	const timeoutSignal = AbortSignal.timeout(SEARCH_TIMEOUT_MS);
+	let response: Response;
+	let entries: unknown[];
+	try {
+		response = await fetchWithCredentialRedirects(YOU_SEARCH_URL, {
+			method: "POST",
+			headers: { Accept: "application/json", "Content-Type": "application/json", "X-API-Key": apiKey },
+			body: JSON.stringify(body),
+			signal: options.signal ? AbortSignal.any([timeoutSignal, options.signal]) : timeoutSignal,
+		}, ["X-API-Key"]);
+		if (!response.ok) {
+			const errorText = await response.text();
+			throw new Error(`You.com error ${response.status}: ${redactCredential(errorText, apiKey).slice(0, 300)}`);
+		}
+		let rawData: unknown;
+		try {
+			rawData = await response.json();
+		} catch (err) {
+			if (err instanceof Error && err.name === "TimeoutError") throw err;
+			throw new Error(`You.com returned invalid JSON: ${errorMessage(err)}`);
+		}
+		entries = parseWebResults(rawData);
+	} catch (err) {
+		if (options.signal?.aborted) {
+			activityMonitor.logComplete(activityId, 0);
+			throw new Error("Aborted");
+		}
+		const message = errorMessage(err);
+		const providerTimeout = timeoutSignal.aborted || (err instanceof Error && err.name === "TimeoutError");
+		const outgoing = providerTimeout
+			? new Error(`You.com request timed out after ${Math.round(SEARCH_TIMEOUT_MS / 1000)}s`)
+			: (() => {
+				const redactedMessage = redactCredential(message, apiKey);
+				if (redactedMessage === message && err instanceof Error) return err;
+				const redactedError = new Error(redactedMessage);
+				if (err instanceof Error) redactedError.name = err.name;
+				return redactedError;
+			})();
+		activityMonitor.logError(activityId, redactCredential(errorMessage(outgoing), apiKey));
+		throw outgoing;
+	}
+	activityMonitor.logComplete(activityId, response.status);
+	const results: SearchResponse["results"] = [];
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const { url, title, description, snippets } = entry as Record<string, unknown>;
+		if (typeof url !== "string" || !url) continue;
+		let resultUrl: URL;
+		try {
+			resultUrl = new URL(url);
+		} catch {
+			continue;
+		}
+		if (resultUrl.protocol !== "http:" && resultUrl.protocol !== "https:") continue;
+		const snippet = typeof description === "string" && description.trim()
+			? description
+			: Array.isArray(snippets) && typeof snippets[0] === "string" ? snippets[0] : "";
+		results.push({
+			title: typeof title === "string" && title.trim() ? title.trim() : `Source ${results.length + 1}`,
+			url: resultUrl.href,
+			snippet,
+		});
+		if (results.length >= numResults) break;
+	}
+	return { answer: formatSearchResultsAsAnswer(results), results };
+}

package/node_modules/pi-web-access/zai.ts

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from "node:fs";
+import { activityMonitor } from "./activity.ts";
+import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
+import { normalizeDomain } from "./domain-filter-normalization.ts";
+import type { SearchOptions, SearchResponse } from "./perplexity.ts";
+import { formatSearchResultsAsAnswer } from "./search-answer-formatting.ts";
+import { normalizeSearchResultCount } from "./search-result-count-normalization.ts";
+import { getWebSearchConfigPath } from "./utils.ts";
+
+// GLM Coding Plan keys are issued per site, so the user picks the matching endpoint.
+const MCP_URLS = {
+	global: "https://api.z.ai/api/mcp/web_search_prime/mcp",
+	china: "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp",
+} as const;
+const RECENCY = { day: "oneDay", week: "oneWeek", month: "oneMonth", year: "oneYear" } as const;
+const SEARCH_TIMEOUT_MS = 60_000;
+const CONFIG_PATH = getWebSearchConfigPath();
+
+function loadConfig(): Record<string, unknown> {
+	if (!existsSync(CONFIG_PATH)) return {};
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+		return parsed as Record<string, unknown>;
+	} catch {
+		// JSON parser errors may include a fragment containing a literal key.
+		throw new Error(`Invalid configuration in ${CONFIG_PATH}: expected a JSON object`);
+	}
+}
+
+function credentialOptions(config: Record<string, unknown>) {
+	return { provider: "Z.ai", configuredValue: config.zaiApiKey, environmentValue: process.env.ZAI_API_KEY };
+}
+
+function endpointUrl(config: Record<string, unknown>): string {
+	const endpoint = config.zaiEndpoint ?? "global";
+	if (endpoint !== "global" && endpoint !== "china") {
+		throw new Error(`zaiEndpoint in ${CONFIG_PATH} must be "global" or "china"`);
+	}
+	return MCP_URLS[endpoint];
+}
+
+export function isZaiAvailable(): boolean {
+	return hasCredentialSource(credentialOptions(loadConfig()));
+}
+
+function searchArguments(query: string, options: SearchOptions): Record<string, unknown> {
+	if (!query.trim()) throw new Error("Z.ai search query must not be empty");
+	const domains = (options.domainFilter ?? []).map((raw) => raw.trim()).filter(Boolean);
+	if (domains.length > 1 || domains.some((raw) => raw.startsWith("-"))) {
+		throw new Error("Z.ai domainFilter supports a single included domain");
+	}
+	const domain = domains[0] === undefined ? undefined : normalizeDomain(domains[0]);
+	if (domain === null) throw new Error("Z.ai domain filter must contain a valid domain");
+	return {
+		search_query: query.trim(),
+		...(options.recencyFilter ? { search_recency_filter: RECENCY[options.recencyFilter] } : {}),
+		...(domain ? { search_domain_filter: domain } : {}),
+	};
+}
+
+/** The tool returns its result list as JSON text, sometimes encoded twice. */
+function parseResults(text: string, limit: number, domain: string | undefined): SearchResponse["results"] {
+	let value: unknown = JSON.parse(text);
+	if (typeof value === "string") value = JSON.parse(value);
+	if (!Array.isArray(value)) throw new Error("Z.ai returned invalid response: expected a result list");
+	const results: SearchResponse["results"] = [];
+	for (const entry of value) {
+		if (!entry || typeof entry !== "object") continue;
+		const { link, title, content } = entry as Record<string, unknown>;
+		if (typeof link !== "string") continue;
+		let url: URL;
+		try {
+			url = new URL(link);
+		} catch {
+			continue;
+		}
+		if (url.protocol !== "http:" && url.protocol !== "https:") continue;
+		// The remote filter is undocumented, so enforce it locally too.
+		const host = url.hostname.toLowerCase().replace(/\.+$/, "");
+		if (domain && host !== domain && !host.endsWith(`.${domain}`)) continue;
+		results.push({
+			title: typeof title === "string" && title.trim() ? title.trim() : `Source ${results.length + 1}`,
+			url: url.href,
+			snippet: typeof content === "string" ? content : "",
+		});
+		if (results.length >= limit) break;
+	}
+	return results;
+}
+
+export async function searchWithZai(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+	const config = loadConfig();
+	const mcpUrl = endpointUrl(config);
+	const args = searchArguments(query, options);
+	const limit = normalizeSearchResultCount(options.numResults);
+	const timeoutSignal = AbortSignal.timeout(SEARCH_TIMEOUT_MS);
+	const signal = options.signal ? AbortSignal.any([timeoutSignal, options.signal]) : timeoutSignal;
+	if (signal.aborted) throw new Error("Aborted");
+	const apiKey = await resolveCredential({ ...credentialOptions(config), signal });
+	if (!apiKey) throw new Error("Z.ai API key not found. Set ZAI_API_KEY or zaiApiKey in web-search.json with a GLM Coding Plan key.");
+	let headers: Headers;
+	try { headers = new Headers({ Authorization: `Bearer ${apiKey}` }); }
+	catch { throw new Error("Z.ai credential resolution failed: invalid-header-value"); }
+	// Load the protocol client only when this explicit provider is selected.
+	const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
+		import("@modelcontextprotocol/sdk/client/index.js"),
+		import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+	]);
+	let cleaningUp = false;
+	const transport = new StreamableHTTPClientTransport(new URL(mcpUrl), {
+		requestInit: { headers },
+		fetch: async (url, init) => {
+			// Fixed endpoint, no redirects: neither credentials nor session IDs can
+			// be forwarded to another origin (including MCP discovery redirects).
+			if (String(url) !== mcpUrl) throw new Error("Z.ai endpoint changed unexpectedly");
+			const requestSignal = cleaningUp ? AbortSignal.timeout(1_500) : signal;
+			return fetch(url, { ...init, redirect: "error", signal: !cleaningUp && init?.signal ? AbortSignal.any([init.signal, requestSignal]) : requestSignal });
+		},
+		reconnectionOptions: { maxRetries: 0, initialReconnectionDelay: 1_000, maxReconnectionDelay: 1_000, reconnectionDelayGrowFactor: 1 },
+	});
+	const client = new Client({ name: "pi-web-access-zai", version: "1.0.0" });
+	const activityId = activityMonitor.logStart({ type: "api", query });
+	try {
+		await client.connect(transport, { signal, timeout: SEARCH_TIMEOUT_MS });
+		// The live China server lists `web_search_prime` while both sites document
+		// `webSearchPrime`, so call whichever name this server exposes.
+		const { tools } = await client.listTools(undefined, { signal, timeout: SEARCH_TIMEOUT_MS });
+		const toolName = tools.find((tool) => tool.name === "web_search_prime" || tool.name === "webSearchPrime")?.name;
+		if (!toolName) throw new Error("Z.ai returned invalid response: web search tool not listed");
+		const result = await client.callTool({ name: toolName, arguments: args }, undefined, { signal, timeout: SEARCH_TIMEOUT_MS });
+		if (result.isError) throw new Error("Z.ai search tool returned an error");
+		const text = (Array.isArray(result.content) ? result.content : []).find((item) => item.type === "text" && typeof item.text === "string");
+		if (!text) throw new Error("Z.ai returned invalid response: no search text");
+		const results = parseResults(text.text as string, limit, args.search_domain_filter as string | undefined);
+		activityMonitor.logComplete(activityId, 200);
+		return { answer: formatSearchResultsAsAnswer(results), results };
+	} catch (err) {
+		let message: string;
+		if (options.signal?.aborted) message = "Aborted";
+		else if (timeoutSignal.aborted) message = "Z.ai request timed out after 60s";
+		else {
+			const code = err && typeof err === "object" && "code" in err ? err.code : undefined;
+			// Never expose remote HTTP/JSON-RPC bodies or nested SDK errors: they
+			// can echo credentials in plain, encoded or transformed form.
+			message = typeof code === "number" && Number.isInteger(code) && code >= 400 && code <= 599
+				? `Z.ai HTTP ${code} request failed; check your GLM Coding Plan key, zaiEndpoint and plan quota`
+				: err instanceof TypeError ? "Z.ai network request failed"
+				: err instanceof SyntaxError || code === -32700 || code === -32602 ? "Z.ai returned invalid response"
+				: err instanceof Error && /^Z\.ai (search tool returned an error|returned invalid response:)/.test(err.message) ? err.message
+				: "Z.ai MCP request failed; check your connection and GLM Coding Plan key";
+		}
+		activityMonitor.logError(activityId, redactCredential(message, apiKey));
+		throw new Error(message);
+	} finally {
+		cleaningUp = true;
+		// Best effort, separately bounded DELETE; always close the local streams.
+		try { await transport.terminateSession(); } catch { /* Server may not support DELETE. */ }
+		await client.close();
+	}
+}

package/node_modules/remote-pi/package.json

@@ -81,8 +81,12 @@
     "@noble/ed25519": "^3.1.0",
     "croner": "^10.0.1",
     "qrcode-terminal": "^0.12.0",
-    "typebox": "^1.1.38",
     "ws": "^8.21.0",
     "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   }
 }