@herbertgao/pi-extensions 2026.9.10 → 2026.9.12

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

@@ -10,10 +10,10 @@ 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 { 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";
+import { ALL_SEARCH_PROVIDERS, assertSearchProviderSelectionAllowed, getAllowedSearchProviders, getConfiguredSearchRouting, normalizeSearchProviderSelection, providerLabel, RESOLVED_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 { formatSeconds, getWebSearchConfigDir, getWebSearchConfigPath, resolveCuratorNetworkConfig, runWithProxy } from "./utils.ts";
 import {
 	clearResults,
 	deleteResult,
@@ -71,6 +71,7 @@ import { isBrightDataAvailable } from "./brightdata.ts";
 import { isSerpBaseAvailable } from "./serpbase.ts";
 import { isSerpApiAvailable } from "./serpapi.ts";
 import { isSerperAvailable } from "./serper.ts";
+import { isSerplyAvailable } from "./serply.ts";
 import { isValyuAvailable } from "./valyu.ts";
 import { isXcrawlAvailable } from "./xcrawl.ts";
 import { buildSearchErrorPlan, type SearchErrorDetails, type SearchErrorPlan } from "./render-search-error.ts";
@@ -153,6 +154,7 @@ interface WebSearchConfig {
 	serpbaseApiKey?: unknown;
 	serpapiApiKey?: unknown;
 	serperApiKey?: unknown;
+	serplyApiKey?: unknown;
 	tinyfishApiKey?: unknown;
 	valyuApiKey?: unknown;
 	xaiApiKey?: unknown;
@@ -165,8 +167,13 @@ interface WebSearchConfig {
 	summaryModel?: string;
 	summaryGenerationDeadlineMs?: unknown;
 	maxInlineContentChars?: unknown;
+	fetch?: {
+		defaultMode?: unknown;
+		allowedModes?: unknown;
+	};
 	webSearch?: {
 		enabled?: boolean;
+		allowedProviders?: unknown;
 	};
 	tools?: Partial<Record<keyof ToolNames, { enabled?: boolean }>>;
 	commands?: Partial<Record<"websearch" | "curator" | "search" | "google-account", { enabled?: boolean }>>;
@@ -184,12 +191,12 @@ interface WebSearchConfig {
 }
 
 type CuratorWorkflow = "summary-review";
-export type CuratorProvider = Exclude<SearchProvider, "auto">;
+export type CuratorProvider = SearchProvider;
 type SummaryWorkflow = "summary-review" | "auto-summary";
 
 interface CuratorBootstrap {
 	availableProviders: ProviderAvailability;
-	defaultProvider: CuratorProvider;
+	defaultProvider: SearchProvider;
 	timeoutSeconds: number;
 }
 
@@ -244,6 +251,30 @@ const DEFAULT_REMOTE_CURATOR_TIMEOUT_SECONDS = 60;
 const MAX_CURATOR_TIMEOUT_SECONDS = 600;
 const MAX_SUMMARY_GENERATION_DEADLINE_MS = 600_000;
 const SEARCH_QUERY_CONCURRENCY = 3;
+const FETCH_MODES = ["readable", "raw", "answer"] as const;
+type FetchMode = typeof FETCH_MODES[number];
+const FETCH_MODE_DESCRIPTIONS: Record<FetchMode, string> = {
+	readable: "extract readable content as markdown",
+	raw: "return the exact textual body using direct HTTP only",
+	answer: "answer a prompt using only fetched content",
+};
+
+function resolveFetchModeConfig(config: WebSearchConfig): { defaultMode: FetchMode; allowedModes: FetchMode[] } {
+	const configuredModes = config.fetch?.allowedModes ?? FETCH_MODES;
+	if (!Array.isArray(configuredModes) || configuredModes.length === 0 || configuredModes.some(mode => !FETCH_MODES.includes(mode as FetchMode))) {
+		throw new Error(`fetch.allowedModes in ${WEB_SEARCH_CONFIG_PATH} must be a non-empty array containing only "readable", "raw", or "answer"`);
+	}
+	const allowedModes = configuredModes as FetchMode[];
+	const duplicateMode = allowedModes.find((mode, index) => allowedModes.indexOf(mode) !== index);
+	if (duplicateMode) {
+		throw new Error(`fetch.allowedModes in ${WEB_SEARCH_CONFIG_PATH} must not contain duplicates: "${duplicateMode}"`);
+	}
+	const defaultMode = config.fetch?.defaultMode ?? "readable";
+	if (!allowedModes.includes(defaultMode as FetchMode)) {
+		throw new Error(`fetch.defaultMode in ${WEB_SEARCH_CONFIG_PATH} must be one of fetch.allowedModes`);
+	}
+	return { defaultMode: defaultMode as FetchMode, allowedModes };
+}
 
 // Limit each batch independently so separate Pi tool calls can still run in parallel.
 function runSearchQueries<T>(queries: string[], run: (query: string, index: number) => Promise<T>): Promise<T[]> {
@@ -261,10 +292,10 @@ function curatorResultIndexCapacity(queryCount: number): number {
 	return queryCount * RESOLVED_SEARCH_PROVIDERS.length;
 }
 
-function searchProviderSchema(description: string) {
+function searchProviderSchema(description: string, allowedProviders: readonly ResolvedSearchProvider[]) {
 	return Type.Union([
-		StringEnum([...SEARCH_PROVIDERS]),
-		Type.Array(StringEnum([...RESOLVED_SEARCH_PROVIDERS]), { minItems: 1 }),
+		StringEnum(["auto", "all", ...allowedProviders]),
+		Type.Array(StringEnum([...allowedProviders]), { minItems: 1 }),
 	], { description });
 }
 
@@ -329,12 +360,17 @@ function normalizeProviderInput(value: unknown, label = "provider"): SearchProvi
 
 function resolveRequestedProvider(requested: unknown): SearchProviderSelection {
 	const normalizedRequested = normalizeProviderInput(requested);
-	if (normalizedRequested && normalizedRequested !== "auto") return normalizedRequested;
+	if (normalizedRequested && normalizedRequested !== "auto") {
+		assertSearchProviderSelectionAllowed(normalizedRequested, "Requested provider");
+		return normalizedRequested;
+	}
 	const config = loadConfig();
-	return normalizeProviderInput(config.searchProvider ?? config.provider, `provider in ${WEB_SEARCH_CONFIG_PATH}`) ?? "auto";
+	const provider = normalizeProviderInput(config.searchProvider ?? config.provider, `provider in ${WEB_SEARCH_CONFIG_PATH}`) ?? "auto";
+	assertSearchProviderSelectionAllowed(provider, `configured provider in ${WEB_SEARCH_CONFIG_PATH}`);
+	return provider;
 }
 
-function toCuratorProvider(provider: SearchProviderSelection): CuratorProvider | undefined {
+function toCuratorProvider(provider: SearchProviderSelection): SearchProvider | undefined {
 	if (Array.isArray(provider)) return "all";
 	return provider === "auto" ? undefined : provider;
 }
@@ -342,8 +378,7 @@ function toCuratorProvider(provider: SearchProviderSelection): CuratorProvider |
 function resolveCuratorSearchProvider(requested: unknown, current: SearchProviderSelection): SearchProviderSelection {
 	const normalized = normalizeProviderInput(requested);
 	if (!normalized || normalized === "auto") return current;
-	if (normalized === "all" && Array.isArray(current)) return current;
-	return normalized;
+	return normalized === "all" && Array.isArray(current) ? current : normalized;
 }
 
 function normalizeRecencyFilter(value: unknown): RecencyFilter | undefined {
@@ -419,43 +454,44 @@ function shouldAutoOpenCuratorBrowser(config: WebSearchConfig): boolean {
 }
 
 async function getProviderAvailability(ctx: ExtensionContext): Promise<ProviderAvailability> {
-	const geminiWebAvail = await getOptionalGeminiWebAvailability();
-	const geminiApiAvail = isGeminiApiAvailable();
+	const allowedProviders = new Set(getAllowedSearchProviders());
+	const geminiWebAvail = allowedProviders.has("gemini") ? await getOptionalGeminiWebAvailability() : null;
+	const geminiApiAvail = allowedProviders.has("gemini") && isGeminiApiAvailable();
 	const providers = {
-		openai: await isOpenAISearchAvailable(ctx),
-		brave: isBraveAvailable(),
-		parallel: isParallelAvailable(),
-		"parallel-mcp": isParallelMcpAvailable(),
-		tinyfish: isTinyFishAvailable(),
-		search1api: isSearch1APIAvailable(),
-		searchinfinity: isSearchinfinityAvailable(),
-		querit: isQueritAvailable(),
-		tavily: isTavilyAvailable(),
-		firecrawl: isFirecrawlAvailable(),
-		jina: isJinaSearchAvailable(),
-		serpdive: isSerpdiveAvailable(),
-		kagi: isKagiAvailable(),
-		bocha: isBochaAvailable(),
-		ollama: isOllamaAvailable(),
-		searxng: isSearXNGAvailable(),
-		duckduckgo: isDuckDuckGoAvailable(),
-		perplexity: isPerplexityAvailable(),
-		exa: isExaAvailable(),
+		openai: allowedProviders.has("openai") && await isOpenAISearchAvailable(ctx),
+		brave: allowedProviders.has("brave") && isBraveAvailable(),
+		parallel: allowedProviders.has("parallel") && isParallelAvailable(),
+		"parallel-mcp": allowedProviders.has("parallel-mcp") && isParallelMcpAvailable(),
+		tinyfish: allowedProviders.has("tinyfish") && isTinyFishAvailable(),
+		search1api: allowedProviders.has("search1api") && isSearch1APIAvailable(),
+		searchinfinity: allowedProviders.has("searchinfinity") && isSearchinfinityAvailable(),
+		querit: allowedProviders.has("querit") && isQueritAvailable(),
+		tavily: allowedProviders.has("tavily") && isTavilyAvailable(),
+		firecrawl: allowedProviders.has("firecrawl") && isFirecrawlAvailable(),
+		jina: allowedProviders.has("jina") && isJinaSearchAvailable(),
+		serpdive: allowedProviders.has("serpdive") && isSerpdiveAvailable(),
+		kagi: allowedProviders.has("kagi") && isKagiAvailable(),
+		bocha: allowedProviders.has("bocha") && isBochaAvailable(),
+		ollama: allowedProviders.has("ollama") && isOllamaAvailable(),
+		searxng: allowedProviders.has("searxng") && isSearXNGAvailable(),
+		duckduckgo: allowedProviders.has("duckduckgo") && isDuckDuckGoAvailable(),
+		perplexity: allowedProviders.has("perplexity") && isPerplexityAvailable(),
+		exa: allowedProviders.has("exa") && isExaAvailable(),
 		gemini: geminiApiAvail || !!geminiWebAvail,
-		kimi: await isKimiSearchAvailable(ctx),
-		anysearch: isAnySearchAvailable(),
-		xcrawl: isXcrawlAvailable(),
-		xai: await isXaiSearchAvailable(ctx),
-		mistral: isMistralAvailable(),
-		brightdata: isBrightDataAvailable(),
-		serpbase: isSerpBaseAvailable(),
-		serpapi: isSerpApiAvailable(),
-		serper: isSerperAvailable(),
-		valyu: isValyuAvailable(),
+		kimi: allowedProviders.has("kimi") && await isKimiSearchAvailable(ctx),
+		anysearch: allowedProviders.has("anysearch") && isAnySearchAvailable(),
+		xcrawl: allowedProviders.has("xcrawl") && isXcrawlAvailable(),
+		xai: allowedProviders.has("xai") && await isXaiSearchAvailable(ctx),
+		mistral: allowedProviders.has("mistral") && isMistralAvailable(),
+		brightdata: allowedProviders.has("brightdata") && isBrightDataAvailable(),
+		serpbase: allowedProviders.has("serpbase") && isSerpBaseAvailable(),
+		serpapi: allowedProviders.has("serpapi") && isSerpApiAvailable(),
+		serper: allowedProviders.has("serper") && isSerperAvailable(),
+		serply: allowedProviders.has("serply") && isSerplyAvailable(),
+		valyu: allowedProviders.has("valyu") && isValyuAvailable(),
 	};
-	const allSearchProviders = new Set<ResolvedSearchProvider>(ALL_SEARCH_PROVIDERS);
 	return {
-		all: Object.entries(providers).some(([provider, available]) => provider !== "gemini" && allSearchProviders.has(provider as ResolvedSearchProvider) && available) || geminiApiAvail,
+		all: ALL_SEARCH_PROVIDERS.some(provider => provider === "gemini" ? geminiApiAvail : providers[provider]),
 		...providers,
 	};
 }
@@ -500,31 +536,20 @@ export function resolveCuratorDefaultProvider(
 	available: ProviderAvailability,
 	ctx?: Pick<ExtensionContext, "model">,
 	options?: Pick<PendingCurate, "numResults" | "recencyFilter">,
-): CuratorProvider {
+): SearchProvider {
 	return resolveProvider(provider, available, options, shouldUseOpenAICodexDefault(ctx), ctx);
 }
 
-function firstAvailableProvider(available: ProviderAvailability, preferOpenAI: boolean, fallback: ResolvedSearchProvider): ResolvedSearchProvider {
+function firstAvailableProvider(available: ProviderAvailability, preferOpenAI: boolean, fallback: ResolvedSearchProvider): ResolvedSearchProvider | "auto" {
 	if (available.searxng) return "searxng";
 	if (preferOpenAI && available.openai) return "openai";
 	if (available.exa) return "exa";
-	if (available.openai) return "openai";
-	if (available.brave) return "brave";
-	if (available.parallel) return "parallel";
-	if (available.tinyfish) return "tinyfish";
-	if (available.search1api) return "search1api";
-	if (available.searchinfinity) return "searchinfinity";
-	if (available.querit) return "querit";
-	if (available.tavily) return "tavily";
-	if (available.firecrawl) return "firecrawl";
-	if (available.jina) return "jina";
-	if (available.serpdive) return "serpdive";
-	if (available.kagi) return "kagi";
-	if (available.bocha) return "bocha";
-	if (available.ollama) return "ollama";
-	if (available.perplexity) return "perplexity";
-	if (available.gemini) return "gemini";
-	return fallback;
+	for (const provider of ALL_SEARCH_PROVIDERS) {
+		if (provider === "ollama" && available.bocha) return "bocha";
+		if (available[provider]) return provider;
+	}
+	const allowed = getAllowedSearchProviders();
+	return allowed.includes(fallback) ? fallback : "auto";
 }
 
 function resolveProvider(
@@ -533,7 +558,7 @@ function resolveProvider(
 	options?: Pick<PendingCurate, "numResults" | "recencyFilter">,
 	preferOpenAICodexDefault = false,
 	ctx?: Pick<ExtensionContext, "model">,
-): CuratorProvider {
+): SearchProvider {
 	if (Array.isArray(provider)) return "all";
 	const preferOpenAI = shouldPreferOpenAI(options, preferOpenAICodexDefault);
 
@@ -548,62 +573,11 @@ function resolveProvider(
 		}
 		return firstAvailableProvider(available, preferOpenAI, "exa");
 	}
-	if (provider === "all" && !available.all) {
-		return firstAvailableProvider(available, preferOpenAI, "exa");
-	}
-	if (provider === "openai" && !available.openai) {
-		return firstAvailableProvider(available, false, "openai");
-	}
-	if (provider === "brave" && !available.brave) {
-		return firstAvailableProvider(available, preferOpenAI, "brave");
-	}
-	if (provider === "parallel" && !available.parallel) {
-		return firstAvailableProvider(available, preferOpenAI, "parallel");
-	}
-	if (provider === "tinyfish" && !available.tinyfish) {
-		return firstAvailableProvider(available, preferOpenAI, "tinyfish");
-	}
-	if (provider === "search1api" && !available.search1api) {
-		return firstAvailableProvider(available, preferOpenAI, "search1api");
-	}
-	if (provider === "searchinfinity" && !available.searchinfinity) {
-		return firstAvailableProvider(available, preferOpenAI, "searchinfinity");
-	}
-	if (provider === "querit" && !available.querit) {
-		return firstAvailableProvider(available, preferOpenAI, "querit");
-	}
-	if (provider === "tavily" && !available.tavily) {
-		return firstAvailableProvider(available, preferOpenAI, "tavily");
-	}
-	if (provider === "firecrawl" && !available.firecrawl) {
-		return firstAvailableProvider(available, preferOpenAI, "firecrawl");
-	}
-	if (provider === "jina" && !available.jina) {
-		return firstAvailableProvider(available, preferOpenAI, "jina");
-	}
-	if (provider === "serpdive" && !available.serpdive) {
-		return firstAvailableProvider(available, preferOpenAI, "serpdive");
-	}
-	if (provider === "kagi" && !available.kagi) {
-		return firstAvailableProvider(available, preferOpenAI, "kagi");
-	}
-	if (provider === "bocha" && !available.bocha) {
-		return firstAvailableProvider(available, preferOpenAI, "bocha");
-	}
-	if (provider === "ollama" && !available.ollama) {
-		return firstAvailableProvider(available, preferOpenAI, "ollama");
-	}
-	if (provider === "searxng" && !available.searxng) {
-		return firstAvailableProvider(available, preferOpenAI, "searxng");
-	}
-	if (provider === "exa" && !available.exa) {
-		return firstAvailableProvider(available, preferOpenAI, "exa");
-	}
-	if (provider === "perplexity" && !available.perplexity) {
-		return firstAvailableProvider(available, preferOpenAI, "perplexity");
+	if (provider === "all") {
+		return available.all ? "all" : firstAvailableProvider(available, preferOpenAI, "exa");
 	}
-	if (provider === "gemini" && !available.gemini) {
-		return firstAvailableProvider(available, preferOpenAI, "gemini");
+	if (ALL_SEARCH_PROVIDERS.includes(provider) && !available[provider]) {
+		return firstAvailableProvider(available, provider === "openai" ? false : preferOpenAI, provider);
 	}
 	return provider;
 }
@@ -629,7 +603,7 @@ interface PendingCurate {
 	recencyFilter?: "day" | "week" | "month" | "year";
 	domainFilter?: string[];
 	availableProviders: ProviderAvailability;
-	defaultProvider: CuratorProvider;
+	defaultProvider: SearchProvider;
 	searchProvider: SearchProviderSelection;
 	summaryModels: Array<{ value: string; label: string }>;
 	defaultSummaryModel: string | null;
@@ -1063,8 +1037,16 @@ function handleSessionChange(ctx: ExtensionContext): void {
 
 export default function (pi: ExtensionAPI) {
 	const initConfig = loadConfigForExtensionInit();
+	const fetchModeConfig = resolveFetchModeConfig(initConfig);
+	const allowedSearchProviders = initConfig.webSearch?.allowedProviders === undefined ? RESOLVED_SEARCH_PROVIDERS : getAllowedSearchProviders();
+	const allEligibleProviders = allowedSearchProviders.filter(provider => ALL_SEARCH_PROVIDERS.includes(provider));
+	const allExcludedProviders = allowedSearchProviders.filter(provider => !ALL_SEARCH_PROVIDERS.includes(provider));
+	const allPolicyDescription = allEligibleProviders.length === 0
+		? `all has no eligible allowed providers; explicit-only allowed providers (${allExcludedProviders.map(providerLabel).join(", ")}) remain excluded`
+		: allExcludedProviders.length > 0
+		? `all searches eligible allowed providers (${allEligibleProviders.map(providerLabel).join(", ")}); explicit-only allowed providers (${allExcludedProviders.map(providerLabel).join(", ")}) remain excluded`
+		: `all searches every eligible allowed provider (${allEligibleProviders.map(providerLabel).join(", ")})`;
 	const curatorRunState = registerCuratorRunLifecycle(pi);
-	installGlobalProxyFetch();
 	const toolNames = resolveToolNames(initConfig);
 	const webSearchEnabled = isToolEnabled(initConfig, "webSearch");
 	const sourceCheckEnabled = isToolEnabled(initConfig, "sourceCheck");
@@ -1087,6 +1069,9 @@ export default function (pi: ExtensionAPI) {
 	const fetchContentStorageNote = getSearchContentEnabled
 		? `Full original content is stored for retrieval with ${toolNames.getSearchContent}.`
 		: "Full original content is stored internally, but the retrieval tool is not registered.";
+	const fetchModeDescription = fetchModeConfig.allowedModes
+		.map(mode => `${mode}${mode === fetchModeConfig.defaultMode ? " (default)" : ""}: ${FETCH_MODE_DESCRIPTIONS[mode]}`)
+		.join("; ");
 	const curateKey = initConfig.shortcuts?.curate || DEFAULT_SHORTCUTS.curate;
 	const activityKey = initConfig.shortcuts?.activity || DEFAULT_SHORTCUTS.activity;
 
@@ -1790,22 +1775,22 @@ 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, XCrawl, Valyu, xAI, Mistral, Bright Data, SerpBase, SerpApi, 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, Mistral, Bright Data, SerpBase, SerpApi, 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; Mistral search uses a Mistral API key. Parallel MCP, DuckDuckGo, Kimi, AnySearch, XCrawl, Valyu, xAI, Mistral, Bright Data, SerpBase, SerpApi, 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 with ${allowedSearchProviders.map(providerLabel).join(", ")}. Provider arrays run simultaneously; ${allPolicyDescription}. By default, returns source-linked search results or provider answers. For comprehensive research, prefer queries (plural) with 2-4 varied angles over a single query. When includeContent is true, full page content is fetched in the background. Searches return without the interactive browser curator by default; set workflow to "summary-review" to open the curator with an auto-generated summary draft or "auto-summary" to generate a summary without the browser curator. The configured provider is used when provider is omitted or set to auto; omit provider unless explicitly overriding it.`,
 		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({
 			query: Type.Optional(Type.String({ description: "Single search query. For research tasks, prefer 'queries' with multiple varied angles instead." })),
-			queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple queries searched concurrently (up to three at a time), each returning its own synthesized answer. Prefer this for research — vary phrasing, scope, and angle across 2-4 queries to maximize coverage. Good: ['React vs Vue performance benchmarks 2026', 'React vs Vue developer experience comparison', 'React ecosystem size vs Vue ecosystem']. Bad: ['React vs Vue', 'React vs Vue comparison', 'React vs Vue review'] (too similar, redundant results)." })),
+			queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple queries searched concurrently (up to three at a time), each returning source-linked search results or a provider answer. Prefer this for research — vary phrasing, scope, and angle across 2-4 queries to maximize coverage. Good: ['React vs Vue performance benchmarks 2026', 'React vs Vue developer experience comparison', 'React ecosystem size vs Vue ecosystem']. Bad: ['React vs Vue', 'React vs Vue comparison', 'React vs Vue review'] (too similar, redundant results)." })),
 			numResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Results per query (default: 5, max: 20)" })),
 			includeContent: Type.Optional(Type.Boolean({ description: "Fetch full page content (async)" })),
 			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; use all to search every eligible provider except Parallel MCP, DuckDuckGo, Kimi, AnySearch, XCrawl, Valyu, xAI, Mistral, Bright Data, SerpBase, SerpApi, 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 allowed providers to search simultaneously; ${allPolicyDescription}; omit this field to use the configured provider, or use auto when none is configured`, allowedSearchProviders)),
 			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",
+					description: "Search workflow mode: none = no curator (default), summary-review = open curator with auto summary draft, auto-summary = generate summary without opening curator",
 				}),
 			),
 			proxy: Type.Optional(Type.String({
@@ -1869,6 +1854,7 @@ export default function (pi: ExtensionAPI) {
 				const summaryContext: SummaryGenerationContext = {
 					model: ctx.model,
 					modelRegistry: ctx.modelRegistry,
+					sessionManager: ctx.sessionManager,
 					cwd: ctx.cwd,
 					isProjectTrusted: () => ctx.isProjectTrusted(),
 				};
@@ -2097,6 +2083,7 @@ export default function (pi: ExtensionAPI) {
 				const summaryContext: SummaryGenerationContext = {
 					model: ctx.model,
 					modelRegistry: ctx.modelRegistry,
+					sessionManager: ctx.sessionManager,
 					cwd: ctx.cwd,
 					isProjectTrusted: () => ctx.isProjectTrusted(),
 				};
@@ -2387,16 +2374,16 @@ export default function (pi: ExtensionAPI) {
 	if (sourceCheckEnabled) pi.registerTool({
 		name: toolNames.sourceCheck,
 		label: "Source Check",
-		description: "Check a claim against web sources and return a bounded machine-readable research artifact with exact passage citations.",
-		promptSnippet: "Verify a claim with structured source evidence and passage-level citations.",
+		description: "Gather web sources for a claim and return a bounded machine-readable research artifact with exact passage citations for manual review.",
+		promptSnippet: "Gather structured source evidence and passage-level citations for manual semantic review of a claim.",
 		parameters: Type.Object({
-			claim: Type.String({ description: "The assertion to check against web sources." }),
+			claim: Type.String({ description: "The assertion to gather web sources for." }),
 			queries: Type.Optional(Type.Array(Type.String(), { description: "Search queries (default: the claim)." })),
 			numResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Results per query (default: 5, max: 20)." })),
 			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, XCrawl, Valyu, xAI, Mistral, Bright Data, SerpBase, SerpApi, and Serper")),
+			provider: Type.Optional(searchProviderSchema(`Search provider or non-empty list of allowed providers to search simultaneously; ${allPolicyDescription}`, allowedSearchProviders)),
 			proxy: Type.Optional(Type.String({
 				description: "http(s) or socks proxy URL (e.g. http://host:port or socks5h://host:port) used for every outbound request in this call (search APIs and result-page fetches). Empty string forces direct access.",
 			})),
@@ -2486,9 +2473,9 @@ export default function (pi: ExtensionAPI) {
 	if (fetchContentEnabled) pi.registerTool({
 		name: toolNames.fetchContent,
 		label: "Fetch Content",
-		description: `Fetch URL(s) and extract readable content as markdown. Use mode "raw" for exact textual HTTP response bodies or mode "answer" with prompt to answer using only fetched content. Direct image URLs return resized image content. Supports YouTube transcripts, GitHub repositories, PDFs, and local videos. ${fetchContentStorageNote}`,
+		description: `Fetch URL(s). Available modes: ${fetchModeDescription}. Direct image URLs return resized image content when supported by the selected mode. Supports YouTube transcripts, GitHub repositories, PDFs, and local videos when supported by the selected mode. ${fetchContentStorageNote}`,
 		promptSnippet:
-			"Use to fetch readable or raw URL content, direct images, GitHub repos, and videos. Mode answer answers a prompt using only the fetched source.",
+			"Use to fetch URL content, direct images, GitHub repos, and videos.",
 		parameters: Type.Object({
 			url: Type.Optional(Type.String({ description: "Single URL to fetch" })),
 			urls: Type.Optional(Type.Array(Type.String(), { description: "Multiple URLs (parallel)" })),
@@ -2496,14 +2483,18 @@ export default function (pi: ExtensionAPI) {
 				description: "Force cloning large GitHub repositories that exceed the size threshold",
 			})),
 			prompt: Type.Optional(Type.String({
-				description: "Question or instruction for video analysis, or the page-local question required by mode answer.",
-			})),
-			mode: Type.Optional(StringEnum(["readable", "raw", "answer"], {
-				description: "Fetch mode: readable (default extraction), raw (exact textual HTTP body), or answer (answer prompt using only fetched content).",
+				description: fetchModeConfig.allowedModes.includes("answer")
+					? "Question or instruction for video analysis, or the page-local question required by answer mode."
+					: "Question or instruction for video analysis.",
 			})),
-			answerModel: Type.Optional(Type.String({
-				description: "Optional provider/model-id override for mode answer. Defaults to fetch.answerProvider + fetch.answerModel when configured, otherwise the current Pi model.",
+			mode: Type.Optional(StringEnum(fetchModeConfig.allowedModes, {
+				description: `Fetch mode. ${fetchModeDescription}.`,
 			})),
+			...(fetchModeConfig.allowedModes.includes("answer") ? {
+				answerModel: Type.Optional(Type.String({
+					description: "Optional provider/model-id override for answer mode. 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.",
 			})),
@@ -2532,8 +2523,12 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text", text: `Error: ${error}` }], details: { error } };
 			}
 			const { urlList, options } = normalized;
+			const mode = options.mode ?? fetchModeConfig.defaultMode;
+			if (!fetchModeConfig.allowedModes.includes(mode)) {
+				const error = `Fetch mode "${mode}" is disabled by fetch.allowedModes.`;
+				return { content: [{ type: "text", text: `Error: ${error}` }], details: { error } };
+			}
 			return runWithProxy(options.proxy, async () => {
-				const mode = options.mode ?? "readable";
 				if (mode === "answer" && !options.prompt) {
 					return { content: [{ type: "text", text: "Error: mode answer requires prompt." }], details: { error: "mode answer requires prompt" } };
 				}
@@ -2570,13 +2565,12 @@ export default function (pi: ExtensionAPI) {
 					details: { phase: "fetch", progress: 0 },
 				});
 
-				const { answerModel: _answerModel, auth: _auth, ...extractionOptions } = options;
-				const fetchOptions = mode === "answer"
-					? (() => {
-						const { prompt: _prompt, ...rest } = extractionOptions;
-						return { ...rest, ...(authFetchProfile ? { authFetchProfile } : {}) };
-					})()
-					: { ...extractionOptions, ...(authFetchProfile ? { authFetchProfile } : {}) };
+				const { answerModel: _answerModel, auth: _auth, ...extractionOptions } = { ...options, mode };
+				const { prompt: _prompt, ...answerExtractionOptions } = extractionOptions;
+				const fetchOptions = {
+					...(mode === "answer" ? answerExtractionOptions : extractionOptions),
+					...(authFetchProfile ? { authFetchProfile } : {}),
+				};
 				const fetchResults = await fetchAllContent(urlList, signal, withRegisteredFetchOptions(fetchOptions, registeredToolNames, options.proxy));
 				const presentedResults = mode === "answer"
 					? await Promise.all(fetchResults.map(async result => {
@@ -2693,7 +2687,13 @@ export default function (pi: ExtensionAPI) {
 		},
 
 		renderCall(args, theme) {
-			const { urlList, options } = normalizeFetchContentParams(args);
+			let normalized: ReturnType<typeof normalizeFetchContentParams>;
+			try {
+				normalized = normalizeFetchContentParams(args);
+			} catch {
+				return new Text(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("error", "(invalid parameters)"), 0, 0);
+			}
+			const { urlList, options } = normalized;
 			const { prompt, timestamp, frames, model, mode, answerModel, auth } = options;
 			if (urlList.length === 0) {
 				return new Text(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("error", "(no URL)"), 0, 0);
@@ -3184,7 +3184,7 @@ export default function (pi: ExtensionAPI) {
 			const availableProviders = bootstrap.availableProviders;
 			const initialProvider = bootstrap.defaultProvider;
 			const curatorTimeoutSeconds = bootstrap.timeoutSeconds;
-			let currentProvider: CuratorProvider = initialProvider;
+			let currentProvider: SearchProvider = initialProvider;
 			const commandConfig = loadConfig();
 			const rawSearchProvider = normalizeProviderInput(
 				commandConfig.searchProvider ?? commandConfig.provider ?? "auto",
@@ -3196,6 +3196,7 @@ export default function (pi: ExtensionAPI) {
 			const summaryContext: SummaryGenerationContext = {
 				model: ctx.model,
 				modelRegistry: ctx.modelRegistry,
+				sessionManager: ctx.sessionManager,
 				cwd: ctx.cwd,
 				isProjectTrusted: () => ctx.isProjectTrusted(),
 			};

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

@@ -3,6 +3,8 @@ import { activityMonitor } from "./activity.ts";
 import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
 import type { ExtractedContent } from "./extract.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";
 
 const JINA_SEARCH_BASE_URL = "https://s.jina.ai/";
@@ -74,11 +76,6 @@ async function requireApiKey(signal?: AbortSignal): Promise<string> {
 	return apiKey;
 }
 
-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 normalizeDomain(value: string): string | null {
 	let input = value.trim().toLowerCase();
 	if (input.startsWith("-")) input = input.slice(1).trim();
@@ -181,14 +178,6 @@ function mapItems(items: JinaSearchItem[], numResults: number, filters: ReturnTy
 	return { results, content };
 }
 
-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");
-}
-
 function rethrowRequestError(
 	err: unknown,
 	apiKey: string,
@@ -220,7 +209,7 @@ export function isJinaSearchAvailable(): boolean {
 
 export async function searchWithJina(query: string, options: JinaSearchOptions = {}): Promise<SearchResponse> {
 	const apiKey = await requireApiKey(options.signal);
-	const numResults = normalizeCount(options.numResults);
+	const numResults = normalizeSearchResultCount(options.numResults);
 	const { url, filters } = buildSearchRequest(query, options, numResults);
 	const activityId = activityMonitor.logStart({ type: "api", query });
 	const request = requestSignal(options.signal);
@@ -276,7 +265,7 @@ export async function searchWithJina(query: string, options: JinaSearchOptions =
 	}
 	activityMonitor.logComplete(activityId, response.status);
 	const result: SearchResponse = {
-		answer: buildAnswer(mapped.results),
+		answer: formatSearchResultsAsAnswer(mapped.results),
 		results: mapped.results,
 	};
 	if (options.includeContent && mapped.content.length > 0) result.inlineContent = mapped.content;

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

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { activityMonitor } from "./activity.ts";
 import type { ExtractedContent, ExtractOptions } from "./extract.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 { fetchRemoteUrl, loadFetchContentDomainPolicy, loadSsrfConfig, validateRemoteUrl, type SsrfConfig } from "./ssrf-protection.ts";
 import { getWebSearchConfigPath } from "./utils.ts";
@@ -68,11 +70,6 @@ async function requireApiKey(signal?: AbortSignal): Promise<string> {
 	return apiKey;
 }
 
-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 errorMessage(err: unknown): string {
 	return err instanceof Error ? err.message : String(err);
 }
@@ -153,19 +150,13 @@ function parseExtractResponse(value: unknown, requestedUrl: string): ExtractedCo
 	return null;
 }
 
-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 function isKagiAvailable(): boolean {
 	return hasCredentialSource({ provider: "Kagi", configuredValue: loadConfig().kagiApiKey, environmentValue: process.env.KAGI_API_KEY });
 }
 
 export async function searchWithKagi(query: string, options: KagiSearchOptions = {}): Promise<SearchResponse> {
 	const apiKey = await requireApiKey(options.signal);
-	const numResults = normalizeCount(options.numResults);
+	const numResults = normalizeSearchResultCount(options.numResults);
 	const activityId = activityMonitor.logStart({ type: "api", query });
 	let response: Response;
 	try {
@@ -200,7 +191,7 @@ export async function searchWithKagi(query: string, options: KagiSearchOptions =
 	const parsed = parseSearchResponse(rawData);
 	activityMonitor.logComplete(activityId, response.status);
 	const results = parsed.results.slice(0, numResults);
-	const mapped: SearchResponse = { answer: buildAnswer(results), results };
+	const mapped: SearchResponse = { answer: formatSearchResultsAsAnswer(results), results };
 	if (options.includeContent) {
 		const urls = new Set(results.map(result => result.url));
 		const inlineContent = parsed.inlineContent.filter(content => urls.has(content.url));