@herbertgao/pi-extensions 2026.9.20 → 2026.10.1

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

@@ -2,9 +2,11 @@ import { existsSync, readFileSync } from "node:fs";
 import { activityMonitor } from "./activity.ts";
 import type { ExtractedContent } from "./extract.ts";
 import { hasCredentialSource, redactCredential, resolveCredential } from "./credential-source.ts";
+import { formatSearchResultsAsAnswer } from "./search-answer-formatting.ts";
 import { getWebSearchConfigPath } from "./utils.ts";
 
-const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
+const PERPLEXITY_SEARCH_URL = "https://api.perplexity.ai/search";
+const PERPLEXITY_CHAT_URL = "https://api.perplexity.ai/chat/completions";
 const CONFIG_PATH = getWebSearchConfigPath();
 
 const RATE_LIMIT = {
@@ -105,22 +107,19 @@ export function isPerplexityAvailable(): boolean {
 	});
 }
 
-/** Hard ceiling on kept citations, matching the `numResults` clamp. */
-const MAX_CITATIONS = 20;
-
-// Preserve citation numbering by keeping the prefix through the highest cited index, capped at 20.
-function citationsToKeep(answer: string, available: number, numResults: number): number {
-	let highestCited = 0;
-	for (const match of answer.matchAll(/\[(\d{1,3})\]/g)) {
-		highestCited = Math.max(highestCited, Number(match[1]));
-	}
-	return Math.min(available, MAX_CITATIONS, Math.max(numResults, highestCited));
+interface PerplexityRequestOptions {
+	activityQuery: string;
+	signal?: AbortSignal;
 }
 
-export async function searchWithPerplexity(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+async function postPerplexity(
+	url: string,
+	body: Record<string, unknown>,
+	options: PerplexityRequestOptions,
+): Promise<Record<string, unknown>> {
 	checkRateLimit();
 
-	const activityId = activityMonitor.logStart({ type: "api", query });
+	const activityId = activityMonitor.logStart({ type: "api", query: options.activityQuery });
 
 	activityMonitor.updateRateLimit({
 		used: requestTimestamps.length,
@@ -130,37 +129,16 @@ export async function searchWithPerplexity(query: string, options: SearchOptions
 	});
 
 	const apiKey = await getApiKey(options.signal);
-	const numResults = typeof options.numResults === "number" && Number.isFinite(options.numResults)
-		? Math.max(1, Math.min(Math.floor(options.numResults), 20))
-		: 5;
-
-	const requestBody: Record<string, unknown> = {
-		model: "sonar",
-		messages: [{ role: "user", content: query }],
-		max_tokens: 1024,
-		return_related_questions: false,
-	};
-
-	if (options.recencyFilter) {
-		requestBody.search_recency_filter = options.recencyFilter;
-	}
-
-	if (options.domainFilter && options.domainFilter.length > 0) {
-		const validated = validateDomainFilter(options.domainFilter);
-		if (validated.length > 0) {
-			requestBody.search_domain_filter = validated;
-		}
-	}
 
 	let response: Response;
 	try {
-		response = await fetch(PERPLEXITY_API_URL, {
+		response = await fetch(url, {
 			method: "POST",
 			headers: {
 				Authorization: `Bearer ${apiKey}`,
 				"Content-Type": "application/json",
 			},
-			body: JSON.stringify(requestBody),
+			body: JSON.stringify(body),
 			...(options.signal ? { signal: options.signal } : {}),
 		});
 	} catch (err) {
@@ -177,39 +155,69 @@ export async function searchWithPerplexity(query: string, options: SearchOptions
 		throw redactedError;
 	}
 
+	activityMonitor.logComplete(activityId, response.status);
+
 	if (!response.ok) {
-		activityMonitor.logComplete(activityId, response.status);
 		const errorText = redactCredential(await response.text(), apiKey);
 		throw new Error(`Perplexity API error ${response.status}: ${errorText}`);
 	}
 
-	let data: Record<string, unknown>;
 	try {
-		data = await response.json();
+		return await response.json();
 	} catch (err) {
-		activityMonitor.logComplete(activityId, response.status);
 		const message = err instanceof Error ? err.message : String(err);
 		throw new Error(`Perplexity API returned invalid JSON: ${message}`);
 	}
+}
 
-	const answer = (data.choices as Array<{ message?: { content?: string } }>)?.[0]?.message?.content || "";
-	const citations = Array.isArray(data.citations) ? data.citations : [];
+export async function searchWithPerplexity(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
+	const numResults = typeof options.numResults === "number" && Number.isFinite(options.numResults)
+		? Math.max(1, Math.min(Math.floor(options.numResults), 20))
+		: 5;
 
-	const results: SearchResult[] = [];
-	const citationCount = citationsToKeep(answer, citations.length, numResults);
-	for (let i = 0; i < citationCount; i++) {
-		const citation = citations[i];
-		if (typeof citation === "string") {
-			results.push({ title: `Source ${i + 1}`, url: citation, snippet: "" });
-		} else if (citation && typeof citation === "object" && typeof citation.url === "string") {
-			results.push({
-				title: citation.title || `Source ${i + 1}`,
-				url: citation.url,
-				snippet: "",
-			});
+	const requestBody: Record<string, unknown> = {
+		query,
+		max_results: numResults,
+		search_type: "fast",
+		search_context_size: "medium",
+	};
+
+	if (options.recencyFilter) {
+		requestBody.search_recency_filter = options.recencyFilter;
+	}
+
+	if (options.domainFilter && options.domainFilter.length > 0) {
+		const validated = validateDomainFilter(options.domainFilter);
+		if (validated.length > 0) {
+			requestBody.search_domain_filter = validated;
 		}
 	}
 
-	activityMonitor.logComplete(activityId, response.status);
-	return { answer, results };
+	const data = await postPerplexity(PERPLEXITY_SEARCH_URL, requestBody, { activityQuery: query, signal: options.signal });
+
+	const results: SearchResult[] = [];
+	for (const entry of Array.isArray(data.results) ? data.results : []) {
+		if (!entry || typeof entry !== "object" || typeof entry.url !== "string" || !entry.url) continue;
+		results.push({
+			title: typeof entry.title === "string" && entry.title.trim() ? entry.title.trim() : `Source ${results.length + 1}`,
+			url: entry.url,
+			snippet: typeof entry.snippet === "string" ? entry.snippet.trim() : "",
+		});
+		if (results.length >= numResults) break;
+	}
+
+	return { answer: formatSearchResultsAsAnswer(results), results };
+}
+
+/** Asks Sonar for a prose answer. The Search API returns only ranked pages, so prompts that need prose use this. */
+export async function askPerplexity(prompt: string, options: { signal?: AbortSignal } = {}): Promise<string> {
+	const data = await postPerplexity(PERPLEXITY_CHAT_URL, {
+		model: "sonar",
+		messages: [{ role: "user", content: prompt }],
+		max_tokens: 1024,
+		return_related_questions: false,
+	}, { activityQuery: prompt, signal: options.signal });
+
+	const content = (data.choices as Array<{ message?: { content?: unknown } }> | undefined)?.[0]?.message?.content;
+	return typeof content === "string" ? content : "";
 }

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

@@ -63,7 +63,7 @@ function summarizeQueryResult(result: QueryResultData): string {
 	return lines.join("\n");
 }
 
-export function buildSummaryPrompt(results: QueryResultData[], feedback?: string): string {
+export function buildSummaryPrompt(results: QueryResultData[], feedback?: string, instructions?: string): string {
 	const sections = [
 		"You are writing the final web search summary for a coding assistant.",
 		"Write a concise, factual summary using only the provided search results.",
@@ -75,6 +75,11 @@ export function buildSummaryPrompt(results: QueryResultData[], feedback?: string
 		"- End with a short \"Sources\" section listing the most relevant URLs.",
 	];
 
+	const extraInstructions = typeof instructions === "string" ? instructions.trim() : "";
+	if (extraInstructions) {
+		sections.push(extraInstructions);
+	}
+
 	if (feedback) {
 		sections.push("- Incorporate the user feedback provided below into the summary.");
 	}
@@ -292,6 +297,7 @@ export async function generateSummaryDraft(
 	feedback?: string,
 	completeFn?: CompleteFunction,
 	deadlineMs = SUMMARY_GENERATION_DEADLINE_MS,
+	instructions?: string,
 ): Promise<{ summary: string; meta: SummaryMeta }> {
 	if (!ctx || !ctx.modelRegistry) {
 		throw new Error("Summary generation context unavailable");
@@ -349,7 +355,7 @@ export async function generateSummaryDraft(
 
 	try {
 		if (signal?.aborted) throw new Error("Aborted");
-		const prompt = buildSummaryPrompt(results, feedback);
+		const prompt = buildSummaryPrompt(results, feedback, instructions);
 		let resolved: Awaited<ReturnType<typeof resolveSummaryModelCandidates>>;
 		try {
 			checkSummaryDeadline();

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

@@ -0,0 +1,20 @@
+// Some models send array arguments as a JSON string, for example
+// `provider: "[\"parallel-mcp\"]"`, which fails schema validation before the tool
+// runs. Parse such strings back into arrays of strings; leave anything else as is.
+export function parseStringifiedArrays(args: unknown, keys: readonly string[]): unknown {
+	if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+	const input = args as Record<string, unknown>;
+	let output: Record<string, unknown> | undefined;
+	for (const key of keys) {
+		const value = input[key];
+		if (typeof value !== "string" || !value.trim().startsWith("[")) continue;
+		try {
+			const parsed: unknown = JSON.parse(value);
+			if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
+				output ??= { ...input };
+				output[key] = parsed;
+			}
+		} catch {}
+	}
+	return output ?? args;
+}

package/node_modules/pi-web-access/video-extract.ts

@@ -249,7 +249,7 @@ async function tryVideoGeminiWeb(
 		if (signal?.aborted) return null;
 
 		const text = await queryWithCookies(prompt, cookies, {
-			files: [info.absolutePath],
+			files: [{ path: info.absolutePath, mimeType: info.mimeType }],
 			...(model !== "gemini-3.6-flash" ? { model } : {}),
 			signal,
 			timeoutMs: 180000,

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

@@ -0,0 +1,86 @@
+// Host-neutral contract for the web tools. The Pi extension (index.ts) and the
+// MCP server (mcp-server.ts) both drive tools through WebToolCore so tool
+// behavior lives in one place; each host keeps its own schemas and transport.
+
+import type { FindMode } from "./content-find.ts";
+import type { RecencyFilter } from "./source-check.ts";
+
+export type WebToolContent =
+	| { type: "text"; text: string }
+	| { type: "image"; data: string; mimeType: string };
+
+export interface WebToolResult {
+	content: WebToolContent[];
+	details: Record<string, unknown>;
+	isError?: boolean;
+	/** Data for programmatic callers such as Pi codemode scripts; never sent to the model or over MCP. */
+	structuredContent?: WebSearchStructuredContent | FetchContentStructuredContent;
+}
+
+export type WebSearchStructuredContent = {
+	responseId: string;
+	fetchId: string | null;
+	queries: Array<{
+		query: string;
+		answer: string;
+		error: string | null;
+		provider?: string;
+		providers?: string[];
+		results: Array<{ title: string; url: string; snippet: string }>;
+	}>;
+};
+
+export type FetchContentStructuredContent = {
+	responseId: string | null;
+	urls: Array<{ url: string; title: string; content: string; error: string | null; mimeType?: string; status?: number; duration?: number }>;
+};
+
+export interface WebSearchCallParams {
+	query?: string;
+	queries?: string[];
+	numResults?: number;
+	includeContent?: boolean;
+	recencyFilter?: RecencyFilter;
+	domainFilter?: string[];
+	category?: string;
+	provider?: string | string[];
+	proxy?: string;
+}
+
+export interface FetchContentCallParams {
+	url?: string;
+	urls?: string[];
+	mode?: string;
+	forceClone?: boolean;
+	proxy?: string;
+}
+
+export interface GetSearchContentCallParams {
+	responseId: string;
+	query?: string;
+	queryIndex?: number;
+	url?: string;
+	urlIndex?: number;
+	offset?: number;
+	limit?: number;
+	findText?: string | string[];
+	findMode?: FindMode;
+}
+
+export interface SourceCheckCallParams {
+	claim: string;
+	queries?: string[];
+	numResults?: number;
+	fetchContent?: boolean;
+	recencyFilter?: RecencyFilter;
+	domainFilter?: string[];
+	provider?: string | string[];
+	proxy?: string;
+}
+
+export interface WebToolCore {
+	webSearch(params: WebSearchCallParams, signal?: AbortSignal): Promise<WebToolResult>;
+	fetchContent(params: FetchContentCallParams, signal?: AbortSignal): Promise<WebToolResult>;
+	getSearchContent(params: GetSearchContentCallParams, signal?: AbortSignal): Promise<WebToolResult>;
+	sourceCheck(params: SourceCheckCallParams, signal?: AbortSignal): Promise<WebToolResult>;
+}