@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

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

@@ -9,7 +9,8 @@ import { findContent, type FindMode } from "./content-find.ts";
 import { answerFromPage } from "./page-query.ts";
 import { rewriteSearchQuery } from "./query-rewrite.ts";
 import { clearCloneCache } from "./github-extract.ts";
-import { getConfiguredSearchRouting, normalizeSearchProviderSelection, RESOLVED_SEARCH_PROVIDERS, SEARCH_PROVIDERS, search, type AttributedSearchResponse, type SearchProvider, type SearchProviderSelection, type ResolvedSearchProvider } from "./gemini-search.ts";
+import { ALL_SEARCH_PROVIDERS, getConfiguredSearchRouting, normalizeSearchProviderSelection, RESOLVED_SEARCH_PROVIDERS, SEARCH_PROVIDERS, search, type AttributedSearchResponse, type ProviderAvailability, type SearchProvider, type SearchProviderSelection, type ResolvedSearchProvider } from "./gemini-search.ts";
+export type { ProviderAvailability } from "./gemini-search.ts";
 import type { SearchResult } from "./perplexity.ts";
 import { formatSeconds, getWebSearchConfigDir, getWebSearchConfigPath, installGlobalProxyFetch, resolveCuratorNetworkConfig, runWithProxy } from "./utils.ts";
 import {
@@ -68,6 +69,7 @@ import { isBrightDataAvailable } from "./brightdata.ts";
 import { isSerpBaseAvailable } from "./serpbase.ts";
 import { isSerperAvailable } from "./serper.ts";
 import { isValyuAvailable } from "./valyu.ts";
+import { isXcrawlAvailable } from "./xcrawl.ts";
 import { buildSearchErrorPlan, type SearchErrorDetails, type SearchErrorPlan } from "./render-search-error.ts";
 import { findModelWithProviderRouting, loadEnabledModelPatterns, modelMatchesEnabledPatterns, splitThinkingSuffix } from "./summary-model-scope.ts";
 import {
@@ -129,6 +131,7 @@ function renderSearchErrorPlan(plan: SearchErrorPlan, expanded: boolean, theme:
 
 interface WebSearchConfig {
 	anysearchApiKey?: unknown;
+	xcrawlApiKey?: unknown;
 	brightdataApiKey?: unknown;
 	brightdataSerpZone?: unknown;
 	kagiApiKey?: unknown;
@@ -165,37 +168,6 @@ interface WebSearchConfig {
 	};
 }
 
-export interface ProviderAvailability {
-	all: boolean;
-	openai: boolean;
-	brave: boolean;
-	parallel: boolean;
-	"parallel-mcp": boolean;
-	tinyfish: boolean;
-	search1api: boolean;
-	searchinfinity: boolean;
-	querit: boolean;
-	tavily: boolean;
-	firecrawl: boolean;
-	jina: boolean;
-	serpdive: boolean;
-	searxng: boolean;
-	duckduckgo: boolean;
-	perplexity: boolean;
-	exa: boolean;
-	gemini: boolean;
-	kimi: boolean;
-	kagi: boolean;
-	bocha: boolean;
-	ollama: boolean;
-	anysearch: boolean;
-	xai: boolean;
-	brightdata: boolean;
-	serpbase: boolean;
-	serper: boolean;
-	valyu: boolean;
-}
-
 type WebSearchWorkflow = "none" | "summary-review" | "auto-summary";
 type CuratorWorkflow = "summary-review";
 export type CuratorProvider = Exclude<SearchProvider, "auto">;
@@ -374,6 +346,33 @@ function normalizeQueryList(queryList: unknown[]): string[] {
 	return normalized;
 }
 
+// Some local models serialize a multi-query list into the single-string `query`
+// field as a JSON array (query: "[\"a\", \"b\"]") instead of using the
+// `queries` parameter. Forwarding that raw string verbatim makes every backend
+// search for the literal array text and return zero results, with no signal to
+// the model that its argument shape was wrong. Expand a string that parses as a
+// JSON array of strings so each element is searched independently.
+function expandQueryString(query: unknown): string[] {
+	if (typeof query !== "string") return [];
+	const trimmed = query.trim();
+	if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+		try {
+			const parsed: unknown = JSON.parse(trimmed);
+			// Only expand an unambiguously string-only array. Mixed or non-string
+			// arrays are kept as the literal query so we never silently drop
+			// members or collapse them into an empty search.
+			if (Array.isArray(parsed) && parsed.every((entry): entry is string => typeof entry === "string")) {
+				return parsed
+					.map((entry) => entry.trim())
+					.filter((entry) => entry.length > 0);
+			}
+		} catch {
+			// Not JSON — treat as a literal query string.
+		}
+	}
+	return [query];
+}
+
 function getCuratorTimeoutSeconds(): number {
 	const source = loadConfig();
 	const explicit = normalizeCuratorTimeoutSeconds(source.curatorTimeoutSeconds);
@@ -422,15 +421,16 @@ async function getProviderAvailability(ctx: ExtensionContext): Promise<ProviderA
 		gemini: geminiApiAvail || !!geminiWebAvail,
 		kimi: await isKimiSearchAvailable(ctx),
 		anysearch: isAnySearchAvailable(),
+		xcrawl: isXcrawlAvailable(),
 		xai: await isXaiSearchAvailable(ctx),
 		brightdata: isBrightDataAvailable(),
 		serpbase: isSerpBaseAvailable(),
 		serper: isSerperAvailable(),
 		valyu: isValyuAvailable(),
 	};
+	const allSearchProviders = new Set<ResolvedSearchProvider>(ALL_SEARCH_PROVIDERS);
 	return {
-		// Parallel MCP, DuckDuckGo, Kimi, AnySearch, Valyu, xAI, Bright Data, SerpBase, and Serper are explicit-only, so they never make `all` eligible.
-		all: Object.entries(providers).some(([provider, available]) => provider !== "parallel-mcp" && provider !== "duckduckgo" && provider !== "kimi" && provider !== "anysearch" && provider !== "valyu" && provider !== "xai" && provider !== "brightdata" && provider !== "serpbase" && provider !== "serper" && provider !== "gemini" && available) || geminiApiAvail,
+		all: Object.entries(providers).some(([provider, available]) => provider !== "gemini" && allSearchProviders.has(provider as ResolvedSearchProvider) && available) || geminiApiAvail,
 		...providers,
 	};
 }
@@ -1750,7 +1750,7 @@ export default function (pi: ExtensionAPI) {
 		name: toolNames.webSearch,
 		label: "Web Search",
 		description:
-			`Search the web using OpenAI, Brave, Parallel, Parallel MCP, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, SearXNG, DuckDuckGo, Exa, Perplexity, Gemini, Kimi, AnySearch, Valyu, xAI, Bright Data, SerpBase, or Serper. Pass a provider array to search only those providers simultaneously, or use provider "all" to search every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, Valyu, xAI, Bright Data, SerpBase, and Serper. Returns an AI-synthesized answer with source citations. OpenAI search uses a Codex subscription or OpenAI API key; Kimi search uses a Kimi Code Plan authenticated through /login kimi-coding; xAI search uses a SuperGrok/X Premium subscription or xAI API key. Parallel MCP, DuckDuckGo, Kimi, AnySearch, Valyu, xAI, Bright Data, SerpBase, and Serper are available only when explicitly selected. For comprehensive research, prefer queries (plural) with 2-4 varied angles over a single query — each query gets its own synthesized answer, so varying phrasing and scope gives much broader coverage. When includeContent is true, full page content is fetched in the background. Searches auto-open the interactive browser curator and stream results live; set workflow to "none" to skip curation or "auto-summary" for a model-generated summary without the browser curator. The configured provider is used when provider is omitted or set to auto; omit provider unless explicitly overriding it. Without a configured provider, SearXNG is preferred first for local/private search. When the active Pi model is openai-codex, Codex-backed OpenAI search is preferred next. Otherwise Exa is preferred before OpenAI, then Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, Perplexity, Gemini API, or Gemini Web.`,
+			`Search the web using OpenAI, Brave, Parallel, Parallel MCP, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, SearXNG, DuckDuckGo, Exa, Perplexity, Gemini, Kimi, AnySearch, XCrawl, Valyu, xAI, Bright Data, SerpBase, or Serper. Pass a provider array to search only those providers simultaneously, or use provider "all" to search every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, XCrawl, Valyu, xAI, Bright Data, SerpBase, and Serper. Returns an AI-synthesized answer with source citations. OpenAI search uses a Codex subscription or OpenAI API key; Kimi search uses a Kimi Code Plan authenticated through /login kimi-coding; xAI search uses a SuperGrok/X Premium subscription or xAI API key. Parallel MCP, DuckDuckGo, Kimi, AnySearch, XCrawl, Valyu, xAI, Bright Data, SerpBase, and Serper are available only when explicitly selected. For comprehensive research, prefer queries (plural) with 2-4 varied angles over a single query — each query gets its own synthesized answer, so varying phrasing and scope gives much broader coverage. When includeContent is true, full page content is fetched in the background. Searches auto-open the interactive browser curator and stream results live; set workflow to "none" to skip curation or "auto-summary" for a model-generated summary without the browser curator. The configured provider is used when provider is omitted or set to auto; omit provider unless explicitly overriding it. Without a configured provider, SearXNG is preferred first for local/private search. When the active Pi model is openai-codex, Codex-backed OpenAI search is preferred next. Otherwise Exa is preferred before OpenAI, then Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, Perplexity, Gemini API, or Gemini Web.`,
 		promptSnippet:
 			"Use for web research questions. Prefer {queries:[...]} with 2-4 varied angles over a single query for broader coverage. Omit provider unless explicitly overriding the configured default.",
 		parameters: Type.Object({
@@ -1762,7 +1762,7 @@ export default function (pi: ExtensionAPI) {
 				StringEnum(["day", "week", "month", "year"], { description: "Filter by recency" }),
 			),
 			domainFilter: Type.Optional(Type.Array(Type.String(), { description: "Limit to domains (prefix with - to exclude)" })),
-			provider: Type.Optional(searchProviderSchema("Search provider or non-empty list of providers to search simultaneously; use all to search every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, Valyu, xAI, Bright Data, SerpBase, and Serper, omit this field to use the configured provider, or use auto when none is configured")),
+			provider: Type.Optional(searchProviderSchema("Search provider or non-empty list of providers to search simultaneously; use all to search every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, XCrawl, Valyu, xAI, Bright Data, SerpBase, and Serper, omit this field to use the configured provider, or use auto when none is configured")),
 			workflow: Type.Optional(
 				StringEnum(["none", "summary-review", "auto-summary"], {
 					description: "Search workflow mode: none = no curator, summary-review = open curator with auto summary draft (default), auto-summary = generate summary without opening curator",
@@ -1777,7 +1777,7 @@ export default function (pi: ExtensionAPI) {
 			return runWithProxy(typeof params.proxy === "string" ? params.proxy : undefined, async () => {
 				const rawQueryList: unknown[] = Array.isArray(params.queries)
 					? params.queries
-					: (params.query !== undefined ? [params.query] : []);
+					: (params.query !== undefined ? expandQueryString(params.query) : []);
 				const queryList = normalizeQueryList(rawQueryList);
 				const configWorkflow = loadConfigForExtensionInit().workflow;
 				const workflow = resolveWorkflow(params.workflow ?? configWorkflow, ctx?.hasUI !== false);
@@ -2073,7 +2073,7 @@ export default function (pi: ExtensionAPI) {
 			const input = args as { query?: unknown; queries?: unknown };
 			const rawQueryList: unknown[] = Array.isArray(input.queries)
 				? input.queries
-				: (input.query !== undefined ? [input.query] : []);
+				: (input.query !== undefined ? expandQueryString(input.query) : []);
 			const queryList = normalizeQueryList(rawQueryList);
 			if (queryList.length === 0) {
 				return new Text(theme.fg("toolTitle", theme.bold("search ")) + theme.fg("error", "(no query)"), 0, 0);
@@ -2337,7 +2337,7 @@ export default function (pi: ExtensionAPI) {
 			fetchContent: Type.Optional(Type.Boolean({ description: "Fetch up to 5 result pages for exact passage extraction." })),
 			recencyFilter: Type.Optional(StringEnum(["day", "week", "month", "year"], { description: "Filter by recency." })),
 			domainFilter: Type.Optional(Type.Array(Type.String(), { description: "Limit to domains; prefix with - to exclude." })),
-			provider: Type.Optional(searchProviderSchema("Search provider or non-empty list of providers to search simultaneously; all searches every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, Valyu, xAI, Bright Data, SerpBase, and Serper")),
+			provider: Type.Optional(searchProviderSchema("Search provider or non-empty list of providers to search simultaneously; all searches every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, XCrawl, Valyu, xAI, Bright Data, SerpBase, and Serper")),
 			proxy: Type.Optional(Type.String({
 				description: "http(s) proxy URL (e.g. http://host:port) used for every outbound request in this call (search APIs and result-page fetches). Empty string forces direct access.",
 			})),
@@ -2443,7 +2443,7 @@ export default function (pi: ExtensionAPI) {
 				description: "Fetch mode: readable (default extraction), raw (exact textual HTTP body), or answer (answer prompt using only fetched content).",
 			})),
 			answerModel: Type.Optional(Type.String({
-				description: "Optional provider/model-id override for mode answer. Defaults to the current Pi model.",
+				description: "Optional provider/model-id override for mode answer. Defaults to fetch.answerProvider + fetch.answerModel when configured, otherwise the current Pi model.",
 			})),
 			timestamp: Type.Optional(Type.String({
 				description: "Extract video frame(s) at a timestamp or time range. Single: '1:23:45', '23:45', or '85' (seconds). Range: '23:41-25:00' extracts evenly-spaced frames across that span (default 6). Use frames with ranges to control density; single+frames uses a fixed 5s interval. YouTube requires yt-dlp + ffmpeg; local videos require ffmpeg. Use a range when you know the approximate area but not the exact moment — you'll get a contact sheet to visually identify the right frame.",

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-access",
-  "version": "0.25.0",
+  "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.",
   "type": "module",
   "scripts": {

package/node_modules/pi-web-access/page-query.ts

@@ -1,6 +1,8 @@
 import { complete, type Api, type Message, type Model } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { loadEnabledModelPatterns, modelMatchesEnabledPatterns } from "./summary-model-scope.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { findModelWithProviderRouting, loadEnabledModelPatterns, modelMatchesEnabledPatterns } from "./summary-model-scope.ts";
+import { getWebSearchConfigPath } from "./utils.ts";
 
 const OUTPUT_TOKENS = 2_000;
 const INPUT_CONTEXT_FRACTION = 0.6;
@@ -16,7 +18,48 @@ export interface PageAnswer {
 	truncated: boolean;
 }
 
-function parseModelSelector(value: string): { provider: string; id: string } {
+interface AnswerModelSelector {
+	provider: string;
+	id: string;
+}
+
+function loadConfiguredAnswerModel(): AnswerModelSelector | undefined {
+	const configPath = getWebSearchConfigPath();
+	if (!existsSync(configPath)) return undefined;
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(configPath, "utf8"));
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${configPath}: ${message}`);
+	}
+
+	const root = raw && typeof raw === "object" && !Array.isArray(raw)
+		? raw as Record<string, unknown>
+		: undefined;
+	const fetchConfig = root?.fetch;
+	if (!fetchConfig || typeof fetchConfig !== "object" || Array.isArray(fetchConfig)) return undefined;
+	const values = fetchConfig as Record<string, unknown>;
+	const hasProvider = Object.hasOwn(values, "answerProvider");
+	const hasModel = Object.hasOwn(values, "answerModel");
+	if (!hasProvider && !hasModel) return undefined;
+
+	const provider = values.answerProvider;
+	const model = values.answerModel;
+	if (hasProvider && (typeof provider !== "string" || provider.trim().length === 0)) {
+		throw new Error(`fetch.answerProvider in ${configPath} must be a non-empty string`);
+	}
+	if (hasModel && (typeof model !== "string" || model.trim().length === 0)) {
+		throw new Error(`fetch.answerModel in ${configPath} must be a non-empty string`);
+	}
+	if (!hasProvider || !hasModel) {
+		throw new Error(`fetch.answerProvider and fetch.answerModel must be configured together in ${configPath}`);
+	}
+	return { provider: (provider as string).trim(), id: (model as string).trim() };
+}
+
+function parseModelSelector(value: string): AnswerModelSelector {
 	const separator = value.indexOf("/");
 	if (separator <= 0 || separator === value.length - 1) {
 		throw new Error(`Invalid answerModel: ${value}. Use provider/model-id.`);
@@ -24,14 +67,20 @@ function parseModelSelector(value: string): { provider: string; id: string } {
 	return { provider: value.slice(0, separator), id: value.slice(separator + 1) };
 }
 
-function resolveModel(ctx: ExtensionContext, override?: string): Model<Api> {
-	const model = override
+function resolveModel(ctx: ExtensionContext, override?: string, configured?: AnswerModelSelector): Model<Api> {
+	const selector = override ? parseModelSelector(override) : configured;
+	const model = selector
 		? (() => {
-			const selector = parseModelSelector(override);
-			return ctx.modelRegistry.find(selector.provider, selector.id);
+			return findModelWithProviderRouting(ctx.modelRegistry, selector.provider, selector.id);
 		})()
 		: ctx.model;
-	if (!model) throw new Error(override ? `Answer model not found: ${override}` : "No current model available for page answering");
+	if (!model) {
+		if (override) throw new Error(`Answer model not found: ${override}`);
+		if (configured) {
+			throw new Error(`Answer model not found: ${configured.provider}/${configured.id} (from fetch.answerProvider/fetch.answerModel in ${getWebSearchConfigPath()})`);
+		}
+		throw new Error("No current model available for page answering");
+	}
 	if (!model.input.includes("text")) throw new Error(`Answer model does not support text input: ${model.provider}/${model.id}`);
 	if (!modelMatchesEnabledPatterns(model, loadEnabledModelPatterns(ctx))) {
 		throw new Error(`Answer model is not enabled: ${model.provider}/${model.id}`);
@@ -53,7 +102,11 @@ export async function answerFromPage(
 	ctx: ExtensionContext,
 	signal?: AbortSignal,
 ): Promise<PageAnswer> {
-	const model = resolveModel(ctx, input.model);
+	// Resolve an explicit per-call model first. In particular, do not read a
+	// malformed or partial config when the caller has supplied an override.
+	const model = input.model
+		? resolveModel(ctx, input.model)
+		: resolveModel(ctx, undefined, loadConfiguredAnswerModel());
 	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
 	if (!auth.ok || !auth.apiKey) throw new Error(`No API key available for answer model ${model.provider}/${model.id}`);
 	const registry = ctx.modelRegistry as typeof ctx.modelRegistry & { complete?: typeof complete };

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

@@ -0,0 +1,264 @@
+import { existsSync, readFileSync } from "node:fs";
+import { activityMonitor } from "./activity.ts";
+import type { SearchOptions, SearchResponse } from "./perplexity.ts";
+import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
+import { getWebSearchConfigPath } from "./utils.ts";
+
+const XCRAWL_API_URL = "https://run.xcrawl.com/v1/serp";
+const CONFIG_PATH = getWebSearchConfigPath();
+// The SERP API is usually fast (a few seconds, cached responses are quicker),
+// but leave generous headroom before treating a slow job as a provider failure.
+const SEARCH_TIMEOUT_MS = 60_000;
+
+interface WebSearchConfig {
+	xcrawlApiKey?: unknown;
+}
+
+interface XCrawlSerpResult {
+	title?: unknown;
+	link?: unknown;
+	snippet?: unknown;
+}
+
+interface XCrawlSerpResponse {
+	search_metadata?: unknown;
+	organic_results?: 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 getApiKey(signal?: AbortSignal): Promise<string | null> {
+	return resolveCredential({
+		provider: "XCrawl",
+		configuredValue: loadConfig().xcrawlApiKey,
+		environmentValue: process.env.XCRAWL_API_KEY,
+		signal,
+	});
+}
+
+export function isXcrawlAvailable(): boolean {
+	return hasCredentialSource({ provider: "XCrawl", configuredValue: loadConfig().xcrawlApiKey, environmentValue: process.env.XCRAWL_API_KEY });
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function invalidResponse(message: string): Error {
+	return new Error(`XCrawl API returned invalid response: ${message}`);
+}
+
+function normalizeCount(value: number | undefined): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return 5;
+	return Math.max(1, Math.min(Math.floor(value), 20));
+}
+
+function hostnameOf(url: string): string {
+	try {
+		return new URL(url).hostname.toLowerCase();
+	} catch {
+		return "";
+	}
+}
+
+// XCrawl's Google SERP results can carry links relative to the API origin
+// (e.g. "/goto?url=..." redirect stubs) instead of the documented absolute
+// URLs. Resolve those against the API origin so callers always receive a
+// well-formed absolute URL; absolute http(s) links pass through unchanged.
+function absolutizeLink(link: string): string {
+	if (/^https?:\/\//i.test(link)) return link;
+	try {
+		return new URL(link, XCRAWL_API_URL).href;
+	} catch {
+		return link;
+	}
+}
+
+// Normalize a shared domainFilter entry the same way Valyu does before
+// matching: trim, lowercase, strip URL/paths/ports, validate the shape.
+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;
+}
+
+// XCrawl's SERP API has no server-side domain filter, so apply the shared
+// include/exclude domainFilter locally instead of returning off-domain results.
+function applyDomainFilter(results: SearchResponse["results"], domainFilter: NonNullable<SearchOptions["domainFilter"]>): SearchResponse["results"] {
+	const includes: string[] = [];
+	const excludes: string[] = [];
+	for (const raw of domainFilter) {
+		const normalized = normalizeDomain(raw);
+		if (!normalized) continue;
+		if (raw.trim().startsWith("-")) excludes.push(normalized);
+		else includes.push(normalized);
+	}
+	if (!includes.length && !excludes.length) return results;
+	return results.filter((result) => {
+		const host = hostnameOf(result.url);
+		if (!host) return false;
+		const matches = (domain: string) => host === domain || host.endsWith(`.${domain}`);
+		if (excludes.some(matches)) return false;
+		if (includes.length && !includes.some(matches)) return false;
+		return true;
+	});
+}
+
+function parseResponse(value: unknown): SearchResponse["results"] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw invalidResponse("expected an object envelope");
+	}
+	const envelope = value as XCrawlSerpResponse;
+	const metadata = envelope.search_metadata;
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+		throw invalidResponse("expected search_metadata object");
+	}
+	const status = (metadata as Record<string, unknown>).status;
+	if (status !== undefined && status !== "completed") {
+		throw invalidResponse(`expected search_metadata.status \"completed\", got ${JSON.stringify(status)}`);
+	}
+	if (!Array.isArray(envelope.organic_results)) throw invalidResponse("expected organic_results array");
+
+	const results: SearchResponse["results"] = [];
+	for (const [index, value] of (envelope.organic_results as unknown[]).entries()) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) {
+			throw invalidResponse(`expected organic_results[${index}] object`);
+		}
+		const result = value as XCrawlSerpResult;
+		const { title, link, snippet } = result;
+		if (typeof link !== "string" || !link.trim()) throw invalidResponse(`expected organic_results[${index}].link to be a non-empty string`);
+		if (title !== null && title !== undefined && typeof title !== "string") {
+			throw invalidResponse(`expected organic_results[${index}].title to be a string or null`);
+		}
+		if (snippet !== undefined && snippet !== null && typeof snippet !== "string") {
+			throw invalidResponse(`expected organic_results[${index}].snippet to be a string or null`);
+		}
+		const resolved = absolutizeLink(link.trim());
+		results.push({
+			title: typeof title === "string" && title.trim().length > 0 ? title : resolved,
+			url: resolved,
+			snippet: typeof snippet === "string" ? snippet : "",
+		});
+	}
+
+	return results;
+}
+
+function buildAnswer(results: SearchResponse["results"]): string {
+	return results
+		.map((result) => result.snippet
+			? `${result.snippet}\nSource: ${result.title} (${result.url})`
+			: `Source: ${result.title} (${result.url})`)
+		.join("\n\n");
+}
+
+export async function searchWithXCrawl(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+	const apiKey = await getApiKey(options.signal);
+	const numResults = normalizeCount(options.numResults);
+	if (!apiKey) {
+		throw new Error(
+			"XCrawl search requires an API key. Set xcrawlApiKey in " + CONFIG_PATH +
+			" or export XCRAWL_API_KEY. Get one at https://dash.xcrawl.com/",
+		);
+	}
+	const body = { engine: "google_search", q: query };
+	const activityId = activityMonitor.logStart({ type: "api", query });
+	// Distinguishing caller cancellation from a provider-side timeout lets the
+	// timeout surface as a retriable failure instead of looking like an abort.
+	const timeoutSignal = AbortSignal.timeout(SEARCH_TIMEOUT_MS);
+	let response: Response;
+
+	try {
+		response = await fetch(XCRAWL_API_URL, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify(body),
+			signal: options.signal
+				? AbortSignal.any([timeoutSignal, options.signal])
+				: timeoutSignal,
+		});
+	} catch (err) {
+		const message = errorMessage(err);
+		if (options.signal?.aborted) {
+			activityMonitor.logComplete(activityId, 0);
+			throw new Error("Aborted");
+		}
+		// AbortSignal.timeout rejects with a TimeoutError; treat either that
+		// shape or our own fired timer as a retriable provider-side timeout so
+		// routing fallback still applies.
+		const providerTimeout = timeoutSignal.aborted || (err instanceof Error && err.name === "TimeoutError");
+		let outgoing: Error;
+		if (providerTimeout) {
+			outgoing = new Error(`XCrawl search request timed out after ${Math.round(SEARCH_TIMEOUT_MS / 1000)}s`);
+		} else {
+			const redactedMessage = redactCredential(message, apiKey);
+			outgoing = redactedMessage === message && err instanceof Error ? err : new Error(redactedMessage);
+			if (err instanceof Error && outgoing.name === "Error") outgoing.name = err.name;
+		}
+		activityMonitor.logError(activityId, redactCredential(errorMessage(outgoing), apiKey));
+		throw outgoing;
+	}
+
+	if (!response.ok) {
+		activityMonitor.logComplete(activityId, response.status);
+		const errorText = redactCredential(await response.text(), apiKey);
+		let detail = errorText.slice(0, 300);
+		try {
+			const parsed = JSON.parse(errorText) as { message?: unknown; error?: unknown };
+			if (typeof parsed.message === "string") detail = parsed.message.slice(0, 300);
+			else if (typeof parsed.error === "string") detail = parsed.error.slice(0, 300);
+		} catch {
+			// keep raw text slice
+		}
+		throw new Error(`XCrawl API error (${response.status}): ${detail}`);
+	}
+	activityMonitor.logComplete(activityId, response.status);
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch (err) {
+		throw invalidResponse(`response body is not valid JSON: ${errorMessage(err)}`);
+	}
+	const results = parseResponse(payload);
+	const filtered = (options.domainFilter?.length ? applyDomainFilter(results, options.domainFilter) : results).slice(0, numResults);
+
+	return {
+		answer: buildAnswer(filtered),
+		results: filtered,
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-extensions",
-  "version": "2026.8.13",
+  "version": "2026.8.15",
   "description": "Aggregate installer for HerbertGao-maintained Pi extensions.",
   "keywords": [
     "extensions",
@@ -37,18 +37,18 @@
   "dependencies": {
     "@ast-grep/cli": "^0.45.0",
     "@ast-grep/napi": "^0.45.0",
-    "@czottmann/pi-automode": "1.13.0",
+    "@czottmann/pi-automode": "1.15.0",
     "@dietrichgebert/ponytail": "4.9.0",
-    "@earendil-works/pi-coding-agent": "^0.84.2",
-    "@earendil-works/pi-tui": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@effect/platform-node": "4.0.0-beta.103",
     "@effect/platform-node-shared": "4.0.0-beta.103",
-    "@herbertgao/pi-cc-extensions": "0.8.59",
-    "@herbertgao/pi-stash": "0.1.2",
-    "@herbertgao/pi-subagents": "0.17.0",
+    "@herbertgao/pi-bark": "0.1.0",
+    "@herbertgao/pi-cc-extensions": "0.8.60",
+    "@herbertgao/pi-subagents": "0.17.1",
     "@herbertgao/resume-from": "0.2.0",
-    "@juicesharp/rpiv-ask-user-question": "2.7.1",
-    "@juicesharp/rpiv-config": "^2.7.1",
+    "@juicesharp/rpiv-ask-user-question": "2.8.0",
+    "@juicesharp/rpiv-config": "^2.8.0",
     "@luxusai/pi-hindsight": "0.12.0",
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/core": "2.0.0",
@@ -56,20 +56,19 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
     "@napi-rs/keyring": "^1.3.0",
-    "@narumitw/pi-btw": "0.55.4",
+    "@narumitw/pi-btw": "0.56.0",
     "@narumitw/pi-tui-kit": "^0.59.0",
     "@noble/ed25519": "^3.1.0",
     "@pi-plugins/fast-mode": "0.1.10",
     "@shikijs/cli": "^4.0.2",
     "@sinclair/typebox": "^0.34.49",
     "@tifan/pi-copy-response": "0.2.6",
-    "@tifan/pi-handoff": "2.0.1",
+    "@tifan/pi-handoff": "2.2.0",
     "@tifan/pi-inline-skills": "1.0.5",
     "@tifan/pi-mermaid-open": "0.2.0",
-    "@tifan/pi-preferred-thinking": "1.0.0",
-    "@tifan/pi-recap": "0.4.5",
-    "@tifan/pi-rename": "0.5.1",
-    "@tifan/pi-titlebar-spinner": "0.1.3",
+    "@tifan/pi-preferred-thinking": "1.0.1",
+    "@tifan/pi-recap": "0.4.6",
+    "@tifan/pi-rename": "0.6.0",
     "@vectorize-io/hindsight-client": "^0.9.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -89,9 +88,9 @@
     "open": "^10.2.0",
     "p-limit": "^6.1.0",
     "pi-footer": "0.5.1",
-    "pi-lens": "4.1.2",
-    "pi-mcp-adapter": "2.29.0",
-    "pi-web-access": "0.25.0",
+    "pi-lens": "4.1.3",
+    "pi-mcp-adapter": "2.31.0",
+    "pi-web-access": "0.27.0",
     "pidusage": "^4.0.1",
     "promise.try": "^2.0.1",
     "qrcode-terminal": "^0.12.0",
@@ -114,8 +113,8 @@
   "bundledDependencies": [
     "@czottmann/pi-automode",
     "@dietrichgebert/ponytail",
+    "@herbertgao/pi-bark",
     "@herbertgao/pi-cc-extensions",
-    "@herbertgao/pi-stash",
     "@herbertgao/pi-subagents",
     "@herbertgao/resume-from",
     "@juicesharp/rpiv-ask-user-question",
@@ -129,7 +128,6 @@
     "@tifan/pi-preferred-thinking",
     "@tifan/pi-recap",
     "@tifan/pi-rename",
-    "@tifan/pi-titlebar-spinner",
     "pi-footer",
     "pi-lens",
     "pi-mcp-adapter",
@@ -152,10 +150,9 @@
       "./node_modules/@tifan/pi-preferred-thinking/src/index.ts",
       "./node_modules/@tifan/pi-recap/src/index.ts",
       "./node_modules/@tifan/pi-rename/src/index.ts",
-      "./node_modules/@herbertgao/pi-stash/src/index.ts",
       "./node_modules/@herbertgao/pi-subagents/src/index.ts",
-      "./node_modules/@tifan/pi-titlebar-spinner/src/index.ts",
       "./node_modules/@juicesharp/rpiv-ask-user-question/index.ts",
+      "./node_modules/@herbertgao/pi-bark/src/index.ts",
       "./node_modules/@luxusai/pi-hindsight/extensions/index.ts",
       "./node_modules/@narumitw/pi-btw/dist/index.ts",
       "./node_modules/@pi-plugins/fast-mode/dist/index.mjs",