@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

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

@@ -0,0 +1,211 @@
+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 SERPER_SEARCH_URL = "https://google.serper.dev/search";
+const CONFIG_PATH = getWebSearchConfigPath();
+const SEARCH_TIMEOUT_MS = 60_000;
+const RECENCY_TBS: Record<NonNullable<SearchOptions["recencyFilter"]>, string> = {
+	day: "qdr:d",
+	week: "qdr:w",
+	month: "qdr:m",
+	year: "qdr:y",
+};
+
+interface WebSearchConfig {
+	serperApiKey?: unknown;
+}
+
+interface SerperResult {
+	title?: unknown;
+	link?: unknown;
+	snippet?: 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: "Serper",
+		configuredValue: loadConfig().serperApiKey,
+		environmentValue: process.env.SERPER_API_KEY,
+		signal,
+	});
+}
+
+async function requireApiKey(signal?: AbortSignal): Promise<string> {
+	const apiKey = await getApiKey(signal);
+	if (!apiKey) {
+		throw new Error(
+			"Serper API key not found. Either:\n" +
+			`  1. Create ${CONFIG_PATH} with { "serperApiKey": "your-key" }\n` +
+			"  2. Set SERPER_API_KEY environment variable\n" +
+			"Get a key at https://serper.dev",
+		);
+	}
+	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));
+}
+
+interface DomainFilters {
+	include: string[];
+	exclude: string[];
+}
+
+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 parseDomainFilter(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;
+	let hostname: string;
+	try {
+		hostname = new URL(url).hostname.toLowerCase();
+	} catch {
+		return false;
+	}
+	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 buildQuery(query: string, filters: DomainFilters): string {
+	const parts = [query];
+	if (filters.include.length === 1) parts.push(`site:${filters.include[0]}`);
+	if (filters.include.length > 1) parts.push(`(${filters.include.map(domain => `site:${domain}`).join(" OR ")})`);
+	for (const domain of filters.exclude) parts.push(`-site:${domain}`);
+	return parts.join(" ");
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function invalidResponse(message: string): Error {
+	return new Error(`Serper API returned invalid response: ${message}`);
+}
+
+function parseResponse(value: unknown): SerperResult[] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidResponse("expected an object envelope");
+	const envelope = value as Record<string, unknown>;
+	if (!Array.isArray(envelope.organic)) throw invalidResponse("expected organic array");
+	return envelope.organic as SerperResult[];
+}
+
+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 isSerperAvailable(): boolean {
+	return hasCredentialSource({ provider: "Serper", configuredValue: loadConfig().serperApiKey, environmentValue: process.env.SERPER_API_KEY });
+}
+
+export async function searchWithSerper(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+	const apiKey = await requireApiKey(options.signal);
+	const numResults = normalizeCount(options.numResults);
+	const filters = parseDomainFilter(options.domainFilter);
+	const requestCount = options.domainFilter?.length ? Math.min(20, numResults + 5) : numResults;
+	const activityId = activityMonitor.logStart({ type: "api", query });
+	let response: Response;
+	try {
+		response = await fetch(SERPER_SEARCH_URL, {
+			method: "POST",
+			headers: { "X-API-KEY": apiKey, "Content-Type": "application/json", Accept: "application/json" },
+			body: JSON.stringify({ q: buildQuery(query, filters), num: requestCount, ...(options.recencyFilter ? { tbs: RECENCY_TBS[options.recencyFilter] } : {}) }),
+			signal: options.signal ? AbortSignal.any([AbortSignal.timeout(SEARCH_TIMEOUT_MS), options.signal]) : AbortSignal.timeout(SEARCH_TIMEOUT_MS),
+		});
+	} 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;
+	}
+	if (!response.ok) {
+		activityMonitor.logComplete(activityId, response.status);
+		const errorText = redactCredential(await response.text(), apiKey);
+		throw new Error(`Serper API error ${response.status}: ${errorText.slice(0, 300)}`);
+	}
+	let rawData: unknown;
+	try {
+		rawData = await response.json();
+	} catch (err) {
+		activityMonitor.logComplete(activityId, response.status);
+		throw new Error(`Serper API returned invalid JSON: ${errorMessage(err)}`);
+	}
+	let entries: SerperResult[];
+	try {
+		entries = parseResponse(rawData);
+	} catch (err) {
+		activityMonitor.logComplete(activityId, response.status);
+		throw err;
+	}
+	activityMonitor.logComplete(activityId, response.status);
+	const results: SearchResponse["results"] = [];
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		if (typeof entry.link !== "string" || !entry.link) continue;
+		if (!passesDomainFilters(entry.link, filters)) continue;
+		results.push({
+			title: typeof entry.title === "string" && entry.title.trim() ? entry.title.trim() : `Source ${results.length + 1}`,
+			url: entry.link,
+			snippet: typeof entry.snippet === "string" ? entry.snippet : "",
+		});
+		if (results.length >= numResults) break;
+	}
+	return { answer: buildAnswer(results), results };
+}

package/node_modules/pi-web-access/summary-model-scope.ts

@@ -4,6 +4,8 @@ import { join } from "node:path";
 
 const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
+export type SummaryThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
 interface SummaryModelScopeContext {
 	cwd: string;
 	isProjectTrusted(): boolean;
@@ -78,11 +80,17 @@ export function summaryModelValue(model: ModelLike): string {
 	return `${model.provider}/${model.id}`;
 }
 
+export function splitThinkingSuffix(value: string): { value: string; thinkingLevel?: SummaryThinkingLevel } {
+	const index = value.lastIndexOf(":");
+	if (index < 0) return { value };
+	const suffix = value.slice(index + 1);
+	return THINKING_LEVELS.has(suffix)
+		? { value: value.slice(0, index), thinkingLevel: suffix as SummaryThinkingLevel }
+		: { value };
+}
+
 function stripThinkingSuffix(pattern: string): string {
-	const index = pattern.lastIndexOf(":");
-	if (index < 0) return pattern;
-	const suffix = pattern.slice(index + 1);
-	return THINKING_LEVELS.has(suffix) ? pattern.slice(0, index) : pattern;
+ return splitThinkingSuffix(pattern).value;
 }
 
 function globToRegExp(pattern: string): RegExp {

package/node_modules/pi-web-access/summary-review.ts

@@ -1,6 +1,7 @@
-import { complete, type Api, type Message, type Model } from "@earendil-works/pi-ai/compat";
+import { clampThinkingLevel, type ModelThinkingLevel, type ThinkingLevel } from "@earendil-works/pi-ai";
+import { complete, completeSimple, type Api, type Message, type Model } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { findModelWithProviderRouting, loadEnabledModelPatterns, modelMatchesEnabledPatterns } from "./summary-model-scope.ts";
+import { findModelWithProviderRouting, loadEnabledModelPatterns, modelMatchesEnabledPatterns, splitThinkingSuffix, type SummaryThinkingLevel } from "./summary-model-scope.ts";
 import type { QueryResultData } from "./storage.ts";
 
 type ProviderHeaders = Record<string, string | null>;
@@ -9,7 +10,11 @@ type SummaryModelRegistry = SummaryGenerationContext["modelRegistry"] & { comple
 
 const PREFERRED_SUMMARY_MODELS = [
 	{ provider: "anthropic", id: "claude-haiku-4-5" },
-	{ provider: "openai-codex", id: "gpt-5.3-codex-spark" },
+	{ provider: "openai-codex", id: "gpt-5.6-luna" },
+	{ provider: "openai-codex", id: "gpt-5.6-terra" },
+	{ provider: "google", id: "gemini-3.6-flash" },
+	{ provider: "openai", id: "gpt-5-mini" },
+	{ provider: "deepseek", id: "deepseek-v4-flash" },
 ] as const;
 
 export const SUMMARY_GENERATION_DEADLINE_MS = 30_000;
@@ -186,28 +191,35 @@ export function buildDeterministicSummary(results: QueryResultData[]): { summary
 	};
 }
 
-function parseModelSelector(value: string): { provider: string; id: string } {
-	const slashIndex = value.indexOf("/");
-	if (slashIndex <= 0 || slashIndex >= value.length - 1) {
+function parseModelSelector(value: string): { provider: string; id: string; thinkingLevel?: SummaryThinkingLevel } {
+	const selector = splitThinkingSuffix(value);
+	const slashIndex = selector.value.indexOf("/");
+	if (slashIndex <= 0 || slashIndex >= selector.value.length - 1) {
 		throw new Error(`Invalid summary model: ${value}. Use provider/model-id.`);
 	}
 	return {
-		provider: value.slice(0, slashIndex),
-		id: value.slice(slashIndex + 1),
+		provider: selector.value.slice(0, slashIndex),
+		id: selector.value.slice(slashIndex + 1),
+		thinkingLevel: selector.thinkingLevel,
 	};
 }
 
+function resolveThinkingLevel(model: Model<Api>, requested?: SummaryThinkingLevel): ModelThinkingLevel | undefined {
+	if (!requested) return undefined;
+	return clampThinkingLevel(model, requested as ModelThinkingLevel);
+}
+
 async function resolveSummaryModelCandidates(
 	ctx: SummaryGenerationContext,
 	modelOverride?: string,
-): Promise<{ candidates: Array<{ model: Model<Api>; apiKey?: string; headers?: ProviderHeaders }>; errors: string[] }> {
+): Promise<{ candidates: Array<{ model: Model<Api>; apiKey?: string; headers?: ProviderHeaders; thinkingLevel?: SummaryThinkingLevel }>; errors: string[] }> {
 	const enabledModelPatterns = loadEnabledModelPatterns(ctx);
-	const specs: Array<{ provider: string; id: string }> = [];
+	const specs: Array<{ provider: string; id: string; thinkingLevel?: SummaryThinkingLevel }> = [];
 	const normalizedOverride = typeof modelOverride === "string" ? modelOverride.trim() : "";
 	if (normalizedOverride.length > 0) specs.push(parseModelSelector(normalizedOverride));
 	specs.push(...PREFERRED_SUMMARY_MODELS);
 
-	const candidates: Array<{ model: Model<Api>; apiKey?: string; headers?: ProviderHeaders }> = [];
+	const candidates: Array<{ model: Model<Api>; apiKey?: string; headers?: ProviderHeaders; thinkingLevel?: SummaryThinkingLevel }> = [];
 	const errors: string[] = [];
 	const seen = new Set<string>();
 	for (const spec of specs) {
@@ -229,7 +241,7 @@ async function resolveSummaryModelCandidates(
 			errors.push(`No API key available for summary model ${value}`);
 			continue;
 		}
-		candidates.push({ model, apiKey: auth.apiKey, headers: auth.headers });
+		candidates.push({ model, apiKey: auth.apiKey, headers: auth.headers, thinkingLevel: spec.thinkingLevel });
 	}
 	return { candidates, errors };
 }
@@ -285,7 +297,8 @@ export async function generateSummaryDraft(
 	}
 
 	const registry = ctx.modelRegistry as SummaryModelRegistry;
-	const usesRegistryComplete = !completeFn && typeof registry.complete === "function";
+	const customCompleteFn = completeFn !== undefined;
+	const usesRegistryComplete = !customCompleteFn && typeof registry.complete === "function";
 	completeFn ??= usesRegistryComplete ? registry.complete!.bind(registry) as CompleteFunction : complete;
 
 	const generationStartedAt = Date.now();
@@ -343,7 +356,7 @@ export async function generateSummaryDraft(
 		}
 
 		let lastError = resolved.errors.at(-1);
-		for (const { model, apiKey, headers } of resolved.candidates) {
+		for (const { model, apiKey, headers, thinkingLevel } of resolved.candidates) {
 			const startedAt = Date.now();
 			try {
 				const userMessage: Message = {
@@ -351,25 +364,34 @@ export async function generateSummaryDraft(
 					content: [{ type: "text", text: prompt }],
 					timestamp: Date.now(),
 				};
+				const requestedThinkingLevel = resolveThinkingLevel(model, thinkingLevel);
+				const enabledThinkingLevel = requestedThinkingLevel && requestedThinkingLevel !== "off"
+					? requestedThinkingLevel as ThinkingLevel
+					: undefined;
+				const completionOptions = {
+					...(usesRegistryComplete ? {} : { apiKey, headers }),
+					signal: completionSignal,
+					...(requestedThinkingLevel ? { reasoning: requestedThinkingLevel } : {}),
+					...(enabledThinkingLevel ? { reasoningEffort: enabledThinkingLevel } : {}),
+				};
+				const completion = thinkingLevel !== undefined && !customCompleteFn && !usesRegistryComplete
+					? completeSimple(model, { messages: [userMessage] }, { apiKey, headers, signal: completionSignal, ...(enabledThinkingLevel ? { reasoning: enabledThinkingLevel } : {}) })
+					: completeFn(model, { messages: [userMessage] }, completionOptions);
 
-				const response = await raceSummaryOperation(Promise.resolve(completeFn(
-					model,
-					{ messages: [userMessage] },
-					usesRegistryComplete ? { signal: completionSignal } : { apiKey, headers, signal: completionSignal },
-				)));
+				const response = await raceSummaryOperation(Promise.resolve(completion));
 				if (response.stopReason === "aborted") {
 					throw new Error("Aborted");
 				}
 
 				const contentParts = Array.isArray(response.content) ? response.content : [];
 				const summary = contentParts
-					.map(part => getTextFromContentPart(part))
-					.filter(text => text.trim().length > 0)
+					.map((part: unknown) => getTextFromContentPart(part))
+					.filter((text: string) => text.trim().length > 0)
 					.join("\n")
 					.trim();
 
 				if (summary.length === 0) {
-					const partTypes = contentParts.map(part => getContentPartType(part));
+					const partTypes = contentParts.map((part: unknown) => getContentPartType(part));
 					const typesLabel = partTypes.length > 0 ? partTypes.join(", ") : "none";
 					throw new Error(`Summary model returned empty response (content parts: ${typesLabel})`);
 				}

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

@@ -3,14 +3,15 @@ import { activityMonitor } from "./activity.ts";
 import type { ExtractedContent } from "./extract.ts";
 import type { SearchOptions, SearchResponse } from "./perplexity.ts";
 import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
-import { getWebSearchConfigPath } from "./utils.ts";
+import { fetchWithCredentialRedirects, getWebSearchConfigPath, resolveApiBaseUrl } from "./utils.ts";
 
-const TAVILY_API_URL = "https://api.tavily.com/search";
+const TAVILY_API_BASE_URL = "https://api.tavily.com";
 const CONFIG_PATH = getWebSearchConfigPath();
 const SEARCH_TIMEOUT_MS = 60_000;
 
 interface WebSearchConfig {
 	tavilyApiKey?: unknown;
+	tavilyBaseUrl?: unknown;
 }
 
 interface TavilyResult {
@@ -57,6 +58,16 @@ async function getApiKey(signal?: AbortSignal): Promise<string | null> {
 	});
 }
 
+function getApiUrl(): string {
+	return `${resolveApiBaseUrl({
+		configKey: "tavilyBaseUrl",
+		configuredValue: loadConfig().tavilyBaseUrl,
+		defaultValue: TAVILY_API_BASE_URL,
+		environmentKey: "TAVILY_BASE_URL",
+		environmentValue: process.env.TAVILY_BASE_URL,
+	})}/search`;
+}
+
 async function requireApiKey(signal?: AbortSignal): Promise<string> {
 	const apiKey = await getApiKey(signal);
 	if (!apiKey) {
@@ -152,6 +163,7 @@ export function isTavilyAvailable(): boolean {
 }
 
 export async function searchWithTavily(query: string, options: TavilySearchOptions = {}): Promise<SearchResponse> {
+	const apiUrl = getApiUrl();
 	const apiKey = await requireApiKey(options.signal);
 	const numResults = normalizeCount(options.numResults);
 	const body: Record<string, unknown> = {
@@ -167,7 +179,7 @@ export async function searchWithTavily(query: string, options: TavilySearchOptio
 	const activityId = activityMonitor.logStart({ type: "api", query });
 	let response: Response;
 	try {
-		response = await fetch(TAVILY_API_URL, {
+		response = await fetchWithCredentialRedirects(apiUrl, {
 			method: "POST",
 			headers: {
 				"Authorization": `Bearer ${apiKey}`,
@@ -175,7 +187,7 @@ export async function searchWithTavily(query: string, options: TavilySearchOptio
 			},
 			body: JSON.stringify(body),
 			signal: requestSignal(options.signal),
-		});
+		}, ["Authorization"]);
 	} catch (err) {
 		const message = errorMessage(err);
 		const redactedMessage = redactCredential(message, apiKey);

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

@@ -12,6 +12,93 @@ export function getWebSearchConfigPath(): string {
 	return join(getWebSearchConfigDir(), "web-search.json");
 }
 
+interface ApiBaseUrlOptions {
+	configKey: string;
+	configuredValue: unknown;
+	defaultValue: string;
+	environmentKey: string;
+	environmentValue: string | undefined;
+}
+
+export function resolveApiBaseUrl(options: ApiBaseUrlOptions): string {
+	const fromEnvironment = options.environmentValue !== undefined;
+	const value = fromEnvironment ? options.environmentValue : options.configuredValue;
+	if (value === undefined) return options.defaultValue;
+
+	const source = fromEnvironment
+		? options.environmentKey
+		: `${options.configKey} in ${getWebSearchConfigPath()}`;
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new Error(`${source} must be an absolute HTTP(S) URL`);
+	}
+
+	let url: URL;
+	try {
+		url = new URL(value.trim());
+	} catch {
+		throw new Error(`${source} must be an absolute HTTP(S) URL`);
+	}
+	if (url.protocol !== "https:") {
+		throw new Error(`${source} must be an absolute HTTPS URL`);
+	}
+	if (url.username || url.password) {
+		throw new Error(`${source} must not include credentials`);
+	}
+	if (url.search || url.hash) {
+		throw new Error(`${source} must not include query parameters or fragments`);
+	}
+
+	url.search = "";
+	url.hash = "";
+	url.pathname = url.pathname.replace(/\/+$/, "");
+	return url.toString().replace(/\/+$/, "");
+}
+
+const API_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const API_REQUEST_BODY_HEADERS = ["Content-Encoding", "Content-Language", "Content-Location", "Content-Type"];
+const MAX_API_REDIRECTS = 5;
+
+export async function fetchWithCredentialRedirects(
+	url: string,
+	init: RequestInit,
+	credentialHeaders: readonly string[],
+): Promise<Response> {
+	let current = new URL(url);
+	let requestInit = init;
+
+	for (let redirects = 0; ; redirects++) {
+		const response = await fetch(current, { ...requestInit, redirect: "manual" });
+		if (!API_REDIRECT_STATUSES.has(response.status)) return response;
+
+		const location = response.headers.get("location");
+		if (!location) return response;
+		if (redirects === MAX_API_REDIRECTS) {
+			throw new Error(`Too many API redirects from ${url}`);
+		}
+
+		const next = new URL(location, current);
+		if (next.protocol !== "http:" && next.protocol !== "https:") {
+			throw new Error(`API redirect from ${current.origin} must use HTTP(S)`);
+		}
+		const method = requestInit.method?.toUpperCase() ?? "GET";
+		if (
+			((response.status === 301 || response.status === 302) && method === "POST")
+			|| (response.status === 303 && method !== "GET" && method !== "HEAD")
+		) {
+			const headers = new Headers(requestInit.headers);
+			for (const name of API_REQUEST_BODY_HEADERS) headers.delete(name);
+			const { body: _body, ...withoutBody } = requestInit;
+			requestInit = { ...withoutBody, method: "GET", headers };
+		}
+		if (next.origin !== current.origin) {
+			const headers = new Headers(requestInit.headers);
+			for (const name of credentialHeaders) headers.delete(name);
+			requestInit = { ...requestInit, headers };
+		}
+		current = next;
+	}
+}
+
 export interface CuratorNetworkConfig {
 	/** Whether remote access was opted into via curatorRemote. */
 	enabled: boolean;