@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-web-access/mistral-search.ts

@@ -0,0 +1,281 @@
+import { existsSync, readFileSync } from "node:fs";
+import { activityMonitor } from "./activity.ts";
+import type { SearchOptions, SearchResponse, SearchResult } from "./perplexity.ts";
+import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
+import { getWebSearchConfigPath } from "./utils.ts";
+
+const MISTRAL_CONVERSATIONS_URL = "https://api.mistral.ai/v1/conversations";
+const CONFIG_PATH = getWebSearchConfigPath();
+const SEARCH_TIMEOUT_MS = 60_000;
+const DEFAULT_SEARCH_MODEL = "mistral-small-latest";
+const DEFAULT_SEARCH_TOOL = "web_search";
+const MAX_RESULTS = 20;
+
+type MistralSearchTool = "web_search" | "web_search_premium";
+
+interface WebSearchConfig {
+	mistralApiKey?: unknown;
+	mistralSearchModel?: unknown;
+	mistralSearchTool?: unknown;
+}
+
+interface DomainFilters {
+	include: string[];
+	exclude: string[];
+}
+
+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;
+}
+
+function resolveSearchModel(value: unknown): string {
+	if (value === undefined) return DEFAULT_SEARCH_MODEL;
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new Error(`mistralSearchModel in ${CONFIG_PATH} must be a non-empty string`);
+	}
+	return value.trim();
+}
+
+function resolveSearchTool(value: unknown): MistralSearchTool {
+	if (value === undefined) return DEFAULT_SEARCH_TOOL;
+	if (value !== "web_search" && value !== "web_search_premium") {
+		throw new Error(`mistralSearchTool in ${CONFIG_PATH} must be either web_search or web_search_premium`);
+	}
+	return value;
+}
+
+function normalizeCount(value: number | undefined): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return 5;
+	return Math.max(1, Math.min(Math.floor(value), MAX_RESULTS));
+}
+
+function normalizeDomain(value: string): string | null {
+	let input = value.trim().toLowerCase();
+	if (!input) return null;
+	if (input.startsWith("-")) input = input.slice(1).trim();
+	if (!input) return null;
+	try {
+		const parsed = input.includes("://") ? new URL(input) : new URL(`https://${input}`);
+		input = parsed.hostname;
+	} catch {
+		input = input.split("/")[0]?.split(":")[0] ?? "";
+	}
+	input = input.replace(/^\.+|\.+$/g, "");
+	return /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/i.test(input) ? input : null;
+}
+
+function parseDomainFilters(domainFilter: string[] | undefined): DomainFilters {
+	const filters: DomainFilters = { include: [], exclude: [] };
+	for (const raw of domainFilter ?? []) {
+		const domain = normalizeDomain(raw);
+		if (!domain) continue;
+		const target = raw.trim().startsWith("-") ? filters.exclude : filters.include;
+		if (!target.includes(domain)) target.push(domain);
+	}
+	return filters;
+}
+
+function passesDomainFilters(url: string, filters: DomainFilters): boolean {
+	if (filters.include.length === 0 && filters.exclude.length === 0) return true;
+	const hostname = new URL(url).hostname.toLowerCase();
+	const matches = (domain: string) => hostname === domain || hostname.endsWith(`.${domain}`);
+	if (filters.exclude.some(matches)) return false;
+	return filters.include.length === 0 || filters.include.some(matches);
+}
+
+function normalizeResultUrl(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const url = value.trim();
+	if (!url) return null;
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+	} catch {
+		return null;
+	}
+	return url;
+}
+
+function buildSearchPrompt(query: string, options: SearchOptions, numResults: number): string {
+	const lines: string[] = [];
+	if (options.recencyFilter) {
+		const labels: Record<string, string> = {
+			day: "past 24 hours",
+			week: "past week",
+			month: "past month",
+			year: "past year",
+		};
+		lines.push(`Prefer sources from the ${labels[options.recencyFilter] ?? options.recencyFilter}.`);
+	}
+	if (typeof options.numResults === "number" && Number.isFinite(options.numResults) && options.numResults > 0) {
+		lines.push(`Prefer up to ${numResults} distinct sources.`);
+	}
+
+	const filters = parseDomainFilters(options.domainFilter);
+	if (filters.include.length > 0) lines.push(`Only use sources from: ${filters.include.slice(0, 100).join(", ")}.`);
+	if (filters.exclude.length > 0) lines.push(`Do not use sources from: ${filters.exclude.slice(0, 100).join(", ")}.`);
+	return lines.length > 0 ? `${lines.join(" ")}\n\n${query}` : query;
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function invalidResponse(message: string): Error {
+	return new Error(`Mistral API returned invalid response: ${message}`);
+}
+
+function parseConversationResponse(value: unknown, options: SearchOptions, numResults: number): SearchResponse {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw invalidResponse("expected an object envelope");
+	}
+	const outputs = (value as Record<string, unknown>).outputs;
+	if (!Array.isArray(outputs)) throw invalidResponse("outputs must be an array");
+
+	const answerParts: string[] = [];
+	const results: SearchResult[] = [];
+	const seenUrls = new Set<string>();
+	const domainFilters = parseDomainFilters(options.domainFilter);
+
+	for (const output of outputs) {
+		if (!output || typeof output !== "object" || Array.isArray(output)) continue;
+		const entry = output as Record<string, unknown>;
+		if (entry.type !== "message.output") continue;
+		const content = entry.content;
+		if (typeof content === "string") {
+			if (content.trim()) answerParts.push(content.trim());
+			continue;
+		}
+		if (!Array.isArray(content)) continue;
+
+		for (const chunk of content) {
+			if (!chunk || typeof chunk !== "object" || Array.isArray(chunk)) continue;
+			const part = chunk as Record<string, unknown>;
+			if (part.type === "text") {
+				if (typeof part.text === "string" && part.text.trim()) answerParts.push(part.text.trim());
+				continue;
+			}
+			if (part.type !== "tool_reference" || results.length >= numResults) continue;
+
+			const url = normalizeResultUrl(part.url);
+			if (!url || !passesDomainFilters(url, domainFilters) || seenUrls.has(url)) continue;
+			seenUrls.add(url);
+			const title = typeof part.title === "string" && part.title.trim() ? part.title.trim() : url;
+			const snippet = typeof part.description === "string" ? part.description : "";
+			results.push({ title, url, snippet });
+		}
+	}
+
+	const answer = answerParts.join("\n").trim();
+	if (!answer && results.length === 0) throw invalidResponse("no answer or sources");
+	return { answer, results };
+}
+
+async function getApiKey(signal?: AbortSignal): Promise<string> {
+	const apiKey = await resolveCredential({
+		provider: "Mistral",
+		configuredValue: loadConfig().mistralApiKey,
+		environmentValue: process.env.MISTRAL_API_KEY,
+		signal,
+	});
+	if (!apiKey) {
+		throw new Error(
+			"Mistral API key not found. Either:\n" +
+			`  1. Create ${CONFIG_PATH} with { "mistralApiKey": "your-key" }\n` +
+			"  2. Set MISTRAL_API_KEY environment variable\n" +
+			"Get a key at https://console.mistral.ai/api-keys",
+		);
+	}
+	return apiKey;
+}
+
+export function isMistralAvailable(): boolean {
+	try {
+		const config = loadConfig();
+		resolveSearchModel(config.mistralSearchModel);
+		resolveSearchTool(config.mistralSearchTool);
+		return hasCredentialSource({
+			provider: "Mistral",
+			configuredValue: config.mistralApiKey,
+			environmentValue: process.env.MISTRAL_API_KEY,
+		});
+	} catch {
+		return false;
+	}
+}
+
+export async function searchWithMistral(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+	const config = loadConfig();
+	const model = resolveSearchModel(config.mistralSearchModel);
+	const tool = resolveSearchTool(config.mistralSearchTool);
+	const numResults = normalizeCount(options.numResults);
+	const apiKey = await getApiKey(options.signal);
+	const requestSignal = options.signal
+		? AbortSignal.any([AbortSignal.timeout(SEARCH_TIMEOUT_MS), options.signal])
+		: AbortSignal.timeout(SEARCH_TIMEOUT_MS);
+	const activityId = activityMonitor.logStart({ type: "api", query });
+
+	try {
+		const response = await fetch(MISTRAL_CONVERSATIONS_URL, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				inputs: [{ role: "user", content: buildSearchPrompt(query, options, numResults) }],
+				stream: false,
+				model,
+				tools: [{ type: tool }],
+			}),
+			signal: requestSignal,
+		});
+
+		if (!response.ok) {
+			const errorText = redactCredential(await response.text(), apiKey);
+			throw new Error(`Mistral API error ${response.status}: ${errorText.slice(0, 300)}`);
+		}
+
+		let parsed: unknown;
+		try {
+			parsed = await response.json();
+		} catch (err) {
+			throw new Error(`Mistral API returned invalid JSON: ${errorMessage(err)}`);
+		}
+		const result = parseConversationResponse(parsed, options, numResults);
+		activityMonitor.logComplete(activityId, response.status);
+		return result;
+	} 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;
+		throw redactedError;
+	}
+}

package/node_modules/pi-web-access/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-web-access",
-  "version": "0.27.0",
-  "description": "Web search, URL fetching, GitHub repo cloning, PDF extraction, YouTube video understanding, and local video analysis for Pi coding agent. Supports OpenAI, Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Ollama, AnySearch, Bright Data SERP, SerpBase, SearXNG, Exa, Perplexity, Gemini, and Kimi.",
+  "version": "0.28.0",
+  "description": "Web search, URL fetching, GitHub repo cloning, PDF extraction, YouTube video understanding, and local video analysis for Pi coding agent. Supports OpenAI, Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Ollama, AnySearch, Bright Data SERP, SerpBase, SearXNG, Exa, Perplexity, Gemini, Kimi, and Mistral.",
   "type": "module",
   "scripts": {
     "test": "node --test",

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

@@ -105,6 +105,18 @@ export function isPerplexityAvailable(): boolean {
 	});
 }
 
+/** Hard ceiling on kept citations, matching the `numResults` clamp. */
+const MAX_CITATIONS = 20;
+
+// Preserve citation numbering by keeping the prefix through the highest cited index, capped at 20.
+function citationsToKeep(answer: string, available: number, numResults: number): number {
+	let highestCited = 0;
+	for (const match of answer.matchAll(/\[(\d{1,3})\]/g)) {
+		highestCited = Math.max(highestCited, Number(match[1]));
+	}
+	return Math.min(available, MAX_CITATIONS, Math.max(numResults, highestCited));
+}
+
 export async function searchWithPerplexity(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
 	checkRateLimit();
 
@@ -184,7 +196,8 @@ export async function searchWithPerplexity(query: string, options: SearchOptions
 	const citations = Array.isArray(data.citations) ? data.citations : [];
 
 	const results: SearchResult[] = [];
-	for (let i = 0; i < Math.min(citations.length, numResults); i++) {
+	const citationCount = citationsToKeep(answer, citations.length, numResults);
+	for (let i = 0; i < citationCount; i++) {
 		const citation = citations[i];
 		if (typeof citation === "string") {
 			results.push({ title: `Source ${i + 1}`, url: citation, snippet: "" });

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

@@ -5,10 +5,24 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname, tmpdir } from "node:os";
 import { join } from "node:path";
 
+let cachedWebSearchConfigDir: string | undefined;
+
 export function getWebSearchConfigDir(): string {
-	if (process.env.PI_CODING_AGENT_DIR) return process.env.PI_CODING_AGENT_DIR;
-	if (process.env.XDG_CONFIG_HOME) return join(process.env.XDG_CONFIG_HOME, "pi");
-	return join(homedir(), ".pi");
+	if (cachedWebSearchConfigDir) return cachedWebSearchConfigDir;
+
+	const explicitDir = process.env.PI_CODING_AGENT_DIR;
+	if (explicitDir) return cachedWebSearchConfigDir = explicitDir;
+
+	const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+	if (xdgConfigHome) {
+		const xdgDir = join(xdgConfigHome, "pi");
+		if (existsSync(join(xdgDir, "web-search.json"))) return cachedWebSearchConfigDir = xdgDir;
+
+		const legacyDir = join(homedir(), ".pi");
+		if (existsSync(join(legacyDir, "web-search.json"))) return cachedWebSearchConfigDir = legacyDir;
+		return cachedWebSearchConfigDir = xdgDir;
+	}
+	return cachedWebSearchConfigDir = join(homedir(), ".pi");
 }
 
 export function getWebSearchConfigPath(): string {
@@ -237,14 +251,17 @@ function loadConfiguredProxy(): string | null {
 }
 
 export function runWithProxy<T>(proxy: string | undefined, fn: () => T): T {
-	if (proxy === undefined) return fn();
+	if (proxy === undefined) {
+		const configured = loadConfiguredProxy();
+		if (configured === null) return fn();
+		return proxyStorage.run(configured, fn);
+	}
 	const normalized = normalizeProxyUrl(proxy, "proxy");
 	return proxyStorage.run(normalized, fn);
 }
 
 export function getActiveProxy(): string | null {
-	const scoped = proxyStorage.getStore();
-	return scoped !== undefined ? scoped : loadConfiguredProxy();
+	return proxyStorage.getStore() ?? null;
 }
 
 export function hasScopedProxyDecision(): boolean {

package/node_modules/pi-web-access/xai-search.ts

@@ -5,8 +5,8 @@ import type { SearchOptions, SearchResponse, SearchResult } from "./perplexity.t
 import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
 import { getWebSearchConfigPath } from "./utils.ts";
 
-// xAI's Agent Tools API: a hosted `web_search` tool on an OpenAI-compatible
-// Responses endpoint. The search runs inside xAI's own inference, so — unlike
+// xAI's Agent Tools API: hosted `web_search` and opt-in `x_search` tools on an
+// OpenAI-compatible Responses endpoint. The search runs inside xAI's own inference, so — unlike
 // every keyed backend here — it is paid for by whatever credential answers for
 // the model, including a SuperGrok / X Premium subscription resolved through
 // pi's model registry.
@@ -19,8 +19,8 @@ import { getWebSearchConfigPath } from "./utils.ts";
 // is the shape verified against a live subscription account. `stream`,
 // `include`, `tool_choice` and `parallel_tool_calls` are all sent by the OpenAI
 // backend but were NOT verified here, and a 400 from an unsupported field would
-// cost the user their search. Sources come back in `web_search_call.action.sources`
-// without asking for them via `include`.
+// cost the user their search. Responses API inline citations are enabled by
+// default; sources may also come back in a search call's `action.sources`.
 
 const XAI_RESPONSES_URL = "https://api.x.ai/v1/responses";
 const CONFIG_PATH = getWebSearchConfigPath();
@@ -29,11 +29,18 @@ const SEARCH_TIMEOUT_MS = 60_000;
 // Ordered best-first. pi's builtin xai catalog is small and xAI retires models
 // briskly, so this is a preference list, not an assumption: the first one the
 // registry actually knows wins, and an unknown id is skipped rather than sent.
-const AUTH_MODEL_CANDIDATES = ["grok-4.5", "grok-4.3", "grok-build-0.1"] as const;
+// xAI's current X Search docs use grok-4.6. Keep the existing web-only default
+// unchanged, while preferring the documented model when X Search is opted in.
+const WEB_SEARCH_AUTH_MODEL_CANDIDATES = ["grok-4.5", "grok-4.3", "grok-build-0.1"] as const;
+const X_SEARCH_AUTH_MODEL_CANDIDATES = ["grok-4.6", ...WEB_SEARCH_AUTH_MODEL_CANDIDATES] as const;
+
+type XaiSearchTool = "web_search" | "x_search";
+const DEFAULT_XAI_SEARCH_TOOLS = ["web_search"] as const satisfies readonly XaiSearchTool[];
 
 interface WebSearchConfig {
 	xaiApiKey?: unknown;
 	xaiSearchModel?: unknown;
+	xaiSearchTools?: unknown;
 }
 
 type ProviderHeaders = Record<string, string | null>;
@@ -71,6 +78,29 @@ function resolveConfiguredSearchModel(value: unknown): string | undefined {
 	return value.trim();
 }
 
+function resolveConfiguredSearchTools(value: unknown): XaiSearchTool[] {
+	if (value === undefined) return [...DEFAULT_XAI_SEARCH_TOOLS];
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new Error(`xaiSearchTools in ${CONFIG_PATH} must be a non-empty array containing only web_search or x_search`);
+	}
+
+	const tools: XaiSearchTool[] = [];
+	for (const tool of value) {
+		if (tool !== "web_search" && tool !== "x_search") {
+			throw new Error(`xaiSearchTools in ${CONFIG_PATH} may only contain web_search or x_search`);
+		}
+		if (tools.includes(tool)) {
+			throw new Error(`xaiSearchTools in ${CONFIG_PATH} must not contain duplicates: ${tool}`);
+		}
+		tools.push(tool);
+	}
+	return tools;
+}
+
+function modelCandidatesForTools(tools: readonly XaiSearchTool[]): readonly string[] {
+	return tools.includes("x_search") ? X_SEARCH_AUTH_MODEL_CANDIDATES : WEB_SEARCH_AUTH_MODEL_CANDIDATES;
+}
+
 function toRequestHeaders(headers: ProviderHeaders): Record<string, string> {
 	const requestHeaders: Record<string, string> = {};
 	for (const [name, value] of Object.entries(headers)) {
@@ -84,8 +114,12 @@ function toRequestHeaders(headers: ProviderHeaders): Record<string, string> {
  * its own searches and no api key has to be configured at all. Mirrors how the
  * OpenAI backend picks up a Codex sign-in.
  */
-async function resolvePiAuth(ctx: ExtensionContext, modelOverride?: string): Promise<XaiAuth | undefined> {
-	for (const modelId of AUTH_MODEL_CANDIDATES) {
+async function resolvePiAuth(
+	ctx: ExtensionContext,
+	modelOverride: string | undefined,
+	tools: readonly XaiSearchTool[],
+): Promise<XaiAuth | undefined> {
+	for (const modelId of modelCandidatesForTools(tools)) {
 		try {
 			const model = ctx.modelRegistry.find("xai", modelId);
 			if (!model) continue;
@@ -102,8 +136,9 @@ async function resolvePiAuth(ctx: ExtensionContext, modelOverride?: string): Pro
 export async function resolveXaiAuth(ctx?: ExtensionContext, signal?: AbortSignal): Promise<XaiAuth | undefined> {
 	const config = loadConfig();
 	const modelOverride = resolveConfiguredSearchModel(config.xaiSearchModel);
+	const tools = resolveConfiguredSearchTools(config.xaiSearchTools);
 	if (ctx) {
-		const auth = await resolvePiAuth(ctx, modelOverride);
+		const auth = await resolvePiAuth(ctx, modelOverride, tools);
 		if (auth) return auth;
 	}
 
@@ -119,12 +154,19 @@ export async function resolveXaiAuth(ctx?: ExtensionContext, signal?: AbortSigna
 		environmentValue: process.env.XAI_API_KEY,
 		signal,
 	});
-	return apiKey ? { apiKey, model: modelOverride ?? AUTH_MODEL_CANDIDATES[0], headers: {} } : undefined;
+	return apiKey ? { apiKey, model: modelOverride ?? modelCandidatesForTools(tools)[0], headers: {} } : undefined;
 }
 
 export async function isXaiSearchAvailable(ctx?: ExtensionContext): Promise<boolean> {
-	if (ctx && await resolvePiAuth(ctx)) return true;
-	const config = loadConfig();
+	let config: WebSearchConfig;
+	let tools: XaiSearchTool[];
+	try {
+		config = loadConfig();
+		tools = resolveConfiguredSearchTools(config.xaiSearchTools);
+	} catch {
+		return false;
+	}
+	if (ctx && await resolvePiAuth(ctx, undefined, tools)) return true;
 	return hasCredentialSource({
 		provider: "xAI",
 		configuredValue: config.xaiApiKey,
@@ -153,9 +195,17 @@ function normalizeDomain(value: string): string | null {
  * an unknown field risks a 400 that costs the whole search; steering through
  * the instruction text degrades to "the model ignored it" instead.
  */
-function buildInput(query: string, options: SearchOptions): string {
+function buildInput(query: string, options: SearchOptions, tools: readonly XaiSearchTool[]): string {
+	let searchInstruction: string;
+	if (tools.includes("x_search") && tools.includes("web_search")) {
+		searchInstruction = "Search the web and X and answer using only what the search results say.";
+	} else if (tools.includes("x_search")) {
+		searchInstruction = "Search X and answer using only what the X results say.";
+	} else {
+		searchInstruction = "Search the web and answer using only what the web results say.";
+	}
 	const lines = [
-		"Search the web and answer using only what the web results say.",
+		searchInstruction,
 		"Cite your sources inline.",
 	];
 
@@ -198,6 +248,21 @@ function addResult(results: SearchResult[], seen: Set<string>, url: unknown, tit
 	});
 }
 
+function addSource(results: SearchResult[], seen: Set<string>, source: unknown): void {
+	if (typeof source === "string") {
+		addResult(results, seen, source, undefined);
+		return;
+	}
+	if (!source || typeof source !== "object") return;
+	const record = source as Record<string, unknown>;
+	addResult(results, seen, record.url ?? record.source_website_url, record.title ?? record.caption);
+}
+
+function addSources(results: SearchResult[], seen: Set<string>, sources: unknown): void {
+	if (!Array.isArray(sources)) return;
+	for (const source of sources) addSource(results, seen, source);
+}
+
 function extractSnippetAround(text: string, start: unknown, end: unknown): string {
 	if (typeof start !== "number" || typeof end !== "number" || !text) return "";
 	const before = Math.max(0, start - 100);
@@ -222,13 +287,13 @@ function extractAnswer(output: unknown[]): string {
 }
 
 /**
- * Sources live in two places and neither is a top-level `citations` array:
- * `url_citation` annotations on the answer text (these carry titles and offsets,
- * so they go first and win the dedupe), and the raw `sources` each
- * `web_search_call` visited. A third-party extension that reads `data.citations`
- * silently returns answers with no sources at all — hence both paths here.
+ * Keep annotation sources first because they carry titles and offsets and must
+ * win URL deduplication. Raw source lists from web/X search calls are next,
+ * followed by xAI's response-level `citations` URL list. The latter is usually
+ * strings, but object entries are tolerated when a compatible gateway adds
+ * metadata.
  */
-function extractSearchResults(output: unknown[], numResults: number | undefined): SearchResult[] {
+function extractSearchResults(output: unknown[], citations: unknown, numResults: number | undefined): SearchResult[] {
 	const results: SearchResult[] = [];
 	const seenUrls = new Set<string>();
 
@@ -256,21 +321,18 @@ function extractSearchResults(output: unknown[], numResults: number | undefined)
 	}
 
 	for (const item of output) {
-		if (!item || typeof item !== "object" || (item as { type?: unknown }).type !== "web_search_call") continue;
+		if (!item || typeof item !== "object") continue;
+		const type = (item as { type?: unknown }).type;
+		if (type !== "web_search_call" && type !== "x_search_call") continue;
 		const value = item as { action?: unknown; sources?: unknown; results?: unknown };
 		const actionSources = value.action && typeof value.action === "object"
 			? (value.action as { sources?: unknown }).sources
 			: undefined;
-		for (const group of [actionSources, value.sources, value.results]) {
-			if (!Array.isArray(group)) continue;
-			for (const source of group) {
-				if (!source || typeof source !== "object") continue;
-				const record = source as Record<string, unknown>;
-				addResult(results, seenUrls, record.url ?? record.source_website_url, record.title ?? record.caption);
-			}
-		}
+		for (const group of [actionSources, value.sources, value.results]) addSources(results, seenUrls, group);
 	}
 
+	addSources(results, seenUrls, citations);
+
 	if (typeof numResults === "number" && Number.isFinite(numResults) && numResults > 0) {
 		return results.slice(0, Math.min(Math.floor(numResults), 20));
 	}
@@ -282,10 +344,11 @@ export async function searchWithXai(
 	options: SearchOptions = {},
 	ctx?: ExtensionContext,
 ): Promise<SearchResponse> {
+	const tools = resolveConfiguredSearchTools(loadConfig().xaiSearchTools);
 	const auth = await resolveXaiAuth(ctx, options.signal);
 	if (!auth) {
 		throw new Error(
-			"xAI web search unavailable. Either:\n" +
+			"xAI search unavailable. Either:\n" +
 			"  1. Use /login to sign in with a SuperGrok or X Premium subscription\n" +
 			`  2. Create ${CONFIG_PATH} with { "xaiApiKey": "your-key" }\n` +
 			"  3. Set XAI_API_KEY environment variable",
@@ -303,8 +366,8 @@ export async function searchWithXai(
 			},
 			body: JSON.stringify({
 				model: auth.model,
-				input: buildInput(query, options),
-				tools: [{ type: "web_search" }],
+				input: buildInput(query, options, tools),
+				tools: tools.map((type) => ({ type })),
 			}),
 			signal: options.signal
 				? AbortSignal.any([AbortSignal.timeout(SEARCH_TIMEOUT_MS), options.signal])
@@ -326,10 +389,10 @@ export async function searchWithXai(
 		}
 		const output = Array.isArray(parsed.output) ? parsed.output : [];
 		const answer = extractAnswer(output);
-		const results = extractSearchResults(output, options.numResults);
+		const results = extractSearchResults(output, parsed.citations, options.numResults);
 
 		if (!answer && results.length === 0) {
-			throw new Error("xAI web_search returned no answer or sources");
+			throw new Error(`xAI ${tools.join("+")} returned no answer or sources`);
 		}
 
 		activityMonitor.logComplete(activityId, response.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-extensions",
-  "version": "2026.9.0",
+  "version": "2026.9.1",
   "description": "Aggregate installer for HerbertGao-maintained Pi extensions.",
   "keywords": [
     "extensions",
@@ -37,7 +37,7 @@
   "dependencies": {
     "@ast-grep/cli": "^0.45.0",
     "@ast-grep/napi": "^0.45.0",
-    "@czottmann/pi-automode": "1.15.0",
+    "@czottmann/pi-automode": "1.16.0",
     "@dietrichgebert/ponytail": "4.9.0",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
@@ -60,7 +60,7 @@
     "@narumitw/pi-caffeinate": "0.49.7",
     "@narumitw/pi-tui-kit": "^0.59.0",
     "@noble/ed25519": "^3.1.0",
-    "@pi-plugins/fast-mode": "0.1.10",
+    "@pi-plugins/fast-mode": "0.1.11",
     "@shikijs/cli": "^4.0.2",
     "@sinclair/typebox": "^0.34.49",
     "@tifan/pi-copy-response": "0.2.6",
@@ -90,9 +90,9 @@
     "open": "^10.2.0",
     "p-limit": "^6.1.0",
     "pi-footer": "0.5.1",
-    "pi-lens": "4.1.3",
+    "pi-lens": "4.1.4",
     "pi-mcp-adapter": "2.32.1",
-    "pi-web-access": "0.27.0",
+    "pi-web-access": "0.28.0",
     "pidusage": "^4.0.1",
     "promise.try": "^2.0.1",
     "qrcode-terminal": "^0.12.0",