@bacnh85/pi-web 0.1.2 → 0.2.1

package/lib/brave.ts

@@ -0,0 +1,40 @@
+// Brave Search API client.
+
+import { sanitizeSnippet, type SearchResultItem } from "./format";
+import { withRetry } from "./retry";
+
+export interface BraveResult extends SearchResultItem {
+	age: string;
+}
+
+export async function fetchBraveResults(
+	query: string,
+	count: number,
+	country: string,
+	freshness: string,
+	apiKey: string,
+	signal?: AbortSignal,
+): Promise<BraveResult[]> {
+	return withRetry(async () => {
+		const params = new URLSearchParams({ q: query, count: String(count), country });
+		if (freshness) params.append("freshness", freshness);
+		const response = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "gzip",
+				"X-Subscription-Token": apiKey,
+			},
+			signal,
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}\n${await response.text()}`);
+		const data: any = await response.json();
+		return (data.web?.results || [])
+			.slice(0, count)
+			.map((r: any) => ({
+				title: sanitizeSnippet(r.title || ""),
+				url: r.url || "",
+				snippet: sanitizeSnippet(r.description || ""),
+				age: sanitizeSnippet(r.age || r.page_age || ""),
+			}));
+	}, { maxRetries: 2, retryableErrors: ["timeout", "econn", "etimedout", "network", "socket"] });
+}

package/lib/config.ts

@@ -0,0 +1,155 @@
+// Configuration loading and environment helpers for pi-web.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const OUTPUT_MAX_BYTES = 50 * 1024;
+export const OUTPUT_MAX_LINES = 2_000;
+export const HOSTED_FIRECRAWL_BASE_URL = "https://api.firecrawl.dev/v2";
+export const DEFAULT_SEARXNG_BASE_URL = "http://172.30.55.22:8888";
+
+// ---------------------------------------------------------------------------
+// Environment loading
+// ---------------------------------------------------------------------------
+
+export function piConfigDirs(): string[] {
+	return process.env.PI_CODING_AGENT_DIR
+		? [process.env.PI_CODING_AGENT_DIR]
+		: [path.join(os.homedir(), ".pi", "agent")];
+}
+
+export function envFileCandidates(cwd = process.cwd(), includeCwd = true): string[] {
+	return [
+		...(includeCwd ? [path.resolve(cwd, ".env.local"), path.resolve(cwd, ".env")] : []),
+		...piConfigDirs().flatMap((dir) => [path.join(dir, ".env.local"), path.join(dir, ".env")]),
+	];
+}
+
+export function stripInlineComment(value: string): string {
+	let quote = "";
+	let escaped = false;
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (escaped) { escaped = false; continue; }
+		if (char === "\\") { escaped = true; continue; }
+		if (quote) { if (char === quote) quote = ""; continue; }
+		if (char === '"' || char === "'") { quote = char; continue; }
+		if (char === "#" && (i === 0 || /\s/.test(value[i - 1]))) return value.slice(0, i);
+	}
+	return value;
+}
+
+export function parseDotenvValue(rawValue: string): string {
+	let value = stripInlineComment(rawValue).trim();
+	if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+		value = value.slice(1, -1);
+		return value.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "\t");
+	}
+	return value.trim();
+}
+
+export function parseDotenvFile(file: string): Record<string, string> | null {
+	let text: string;
+	try { text = fs.readFileSync(file, "utf8"); } catch (e: any) { if (e?.code === "ENOENT") return null; throw e; }
+	const values: Record<string, string> = {};
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+		if (match) values[match[1]] = parseDotenvValue(match[2]);
+	}
+	return values;
+}
+
+export function findEnvValue(name: string, cwd = process.cwd(), includeCwd = true): { value?: string; source: string; checkedFiles: string[] } {
+	if (process.env[name]) return { value: process.env[name], source: "process.env", checkedFiles: [] };
+	const checkedFiles = envFileCandidates(cwd, includeCwd);
+	for (const file of checkedFiles) {
+		const parsed = parseDotenvFile(file);
+		if (parsed?.[name]) return { value: parsed[name], source: file, checkedFiles };
+	}
+	return { value: undefined, source: "", checkedFiles };
+}
+
+// ---------------------------------------------------------------------------
+// Context helpers
+// ---------------------------------------------------------------------------
+
+export function cwdFromContext(ctx: Record<string, unknown>): string {
+	return typeof ctx?.cwd === "string" && (ctx.cwd as string) ? (ctx.cwd as string) : process.cwd();
+}
+
+export function includeProjectEnv(ctx: Record<string, unknown>): boolean {
+	return typeof ctx?.isProjectTrusted === "function" ? (ctx.isProjectTrusted as () => boolean)() : false;
+}
+
+// ---------------------------------------------------------------------------
+// SearXNG config
+// ---------------------------------------------------------------------------
+
+export interface SearxngConfig {
+	baseUrl: string;
+	source: string;
+}
+
+export function normalizeSearxngBaseUrl(raw?: string): string {
+	let value = (raw || DEFAULT_SEARXNG_BASE_URL).trim();
+	if (!/^https?:\/\//i.test(value)) {
+		value = /^(localhost|127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/i.test(value)
+			? `http://${value}`
+			: `https://${value}`;
+	}
+	return value.replace(/\/+$/, "");
+}
+
+export function loadSearxngConfig(params: Record<string, unknown> = {}, cwd = process.cwd(), includeCwdEnv = false): SearxngConfig {
+	const baseUrlEnv = findEnvValue("SEARXNG_BASE_URL", cwd, includeCwdEnv);
+	const explicitBaseUrl = params.searxng_base_url as string | undefined;
+	const baseUrl = normalizeSearxngBaseUrl(explicitBaseUrl || (params.base_url as string) || baseUrlEnv.value);
+	const source = explicitBaseUrl || params.base_url ? "tool parameter" : baseUrlEnv.source || "default local";
+	return { baseUrl, source };
+}
+
+// ---------------------------------------------------------------------------
+// Firecrawl config
+// ---------------------------------------------------------------------------
+
+export interface FirecrawlConfig {
+	baseUrl: string;
+	apiKey: string;
+	isHosted: boolean;
+	timeoutMs: number;
+}
+
+export function normalizeFirecrawlBaseUrl(raw?: string): string {
+	let value = (raw || HOSTED_FIRECRAWL_BASE_URL).trim();
+	if (!/^https?:\/\//i.test(value)) {
+		value = /^(localhost|127\.|10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/i.test(value)
+			? `http://${value}`
+			: `https://${value}`;
+	}
+	value = value.replace(/\/+$/, "");
+	if (!/\/v\d+$/i.test(value)) value += "/v2";
+	return value;
+}
+
+export function loadFirecrawlConfig(params: Record<string, unknown> = {}, cwd = process.cwd(), includeCwdEnv = false): FirecrawlConfig {
+	const apiUrlLookup = findEnvValue("FIRECRAWL_API_URL", cwd, includeCwdEnv);
+	const apiKeyLookup = findEnvValue("FIRECRAWL_API_KEY", cwd, includeCwdEnv);
+	const explicitApiKey = (params.firecrawl_api_key as string) || (params.api_key as string);
+	const apiUrl = (params.firecrawl_api_url as string) || (params.api_url as string) || apiUrlLookup.value;
+	const apiKey = explicitApiKey || apiKeyLookup.value || "";
+	const timeoutValue = (params.timeout_ms as number) || findEnvValue("FIRECRAWL_TIMEOUT_MS", cwd).value;
+	const baseUrl = normalizeFirecrawlBaseUrl(apiUrl);
+	const isHosted = !apiUrl || baseUrl.startsWith(HOSTED_FIRECRAWL_BASE_URL);
+	const timeoutMs = timeoutValue ? Number.parseInt(String(timeoutValue), 10) : 60000;
+	if (!Number.isInteger(timeoutMs) || timeoutMs < 1000) throw new Error("FIRECRAWL_TIMEOUT_MS/timeout_ms must be an integer >= 1000.");
+	if (!isHosted && apiKey && !explicitApiKey) throw new Error("Refusing to send a configured FIRECRAWL_API_KEY to a custom Firecrawl URL. Pass firecrawl_api_key explicitly for that URL.");
+	if (isHosted && !apiKey) throw new Error("FIRECRAWL_API_KEY is required for hosted Firecrawl.");
+	return { baseUrl, apiKey, isHosted, timeoutMs };
+}

package/lib/content.ts

@@ -0,0 +1,78 @@
+// Readable content extraction using JSDOM + Readability + Turndown.
+
+import { createRequire } from "node:module";
+import { signalWithTimeout } from "./retry";
+
+const require = createRequire(import.meta.url);
+
+export interface ReadableContentDeps {
+	Readability: any;
+	JSDOM: any;
+	TurndownService: any;
+	gfm: unknown;
+}
+
+export function loadReadableContentDependencies(): ReadableContentDeps {
+	try {
+		return {
+			Readability: require("@mozilla/readability").Readability,
+			JSDOM: require("jsdom").JSDOM,
+			TurndownService: require("turndown"),
+			gfm: require("turndown-plugin-gfm").gfm,
+		};
+	} catch (error: any) {
+		throw new Error(
+			`Readable content extraction dependencies are missing. Install pi-web dependencies with \`npm install\` in the pi-web extension directory, or install the package with Pi so runtime dependencies are installed. Original error: ${error?.message || error}`,
+		);
+	}
+}
+
+export function htmlToMarkdown(html: string, deps = loadReadableContentDependencies()): string {
+	const turndown = new deps.TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+	turndown.use(deps.gfm as any);
+	turndown.addRule("removeEmptyLinks", {
+		filter: (node: any) => node.nodeName === "A" && !node.textContent?.trim(),
+		replacement: () => "",
+	});
+	return turndown
+		.turndown(html)
+		.replace(/\[\\?\[\s*\\?\]\]\([^)]*\)/g, "")
+		.replace(/ +/g, " ")
+		.replace(/\s+,/g, ",")
+		.replace(/\s+\./g, ".")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+export async function fetchReadableContent(
+	url: string,
+	timeoutMs = 15000,
+	signal?: AbortSignal,
+): Promise<{ title: string; markdown: string }> {
+	const response = await fetch(url, {
+		headers: {
+			"User-Agent":
+				"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120 Safari/537.36",
+			Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+			"Accept-Language": "en-US,en;q=0.9",
+		},
+		signal: signalWithTimeout(timeoutMs, signal),
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+	const html = await response.text();
+	const deps = loadReadableContentDependencies();
+	const dom = new deps.JSDOM(html, { url });
+	const article = new deps.Readability(dom.window.document).parse();
+	if (article?.content) {
+		return { title: article.title || "", markdown: htmlToMarkdown(article.content, deps) };
+	}
+	// Fallback: strip non-content elements and use main/article/body
+	const fallbackDoc = new deps.JSDOM(html, { url });
+	const doc = fallbackDoc.window.document;
+	doc.querySelectorAll("script, style, noscript, nav, header, footer, aside").forEach((el: any) => el.remove());
+	const title = doc.querySelector("title")?.textContent?.trim() || "";
+	const main = doc.querySelector("main, article, [role='main'], .content, #content") || doc.body;
+	const fallbackHtml = main?.innerHTML || "";
+	if (fallbackHtml.trim().length <= 100) throw new Error("Could not extract readable content from this page.");
+	return { title, markdown: htmlToMarkdown(fallbackHtml, deps) };
+}

package/lib/firecrawl.ts

@@ -0,0 +1,86 @@
+// Firecrawl API client (search, scrape, map, crawl).
+
+import type { FirecrawlConfig } from "./config";
+import { signalWithTimeout, withRetry } from "./retry";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FirecrawlResult {
+	success: boolean;
+	data?: Record<string, unknown>;
+	warning?: string;
+	id?: string;
+	[key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class FirecrawlHttpError extends Error {
+	status: number;
+	constructor(status: number, statusText: string, text: string) {
+		super(`HTTP ${status}: ${statusText}${text ? `\n${text}` : ""}`);
+		this.status = status;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Low-level HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function firecrawlRequestJson(
+	config: FirecrawlConfig,
+	method: string,
+	endpoint: string,
+	body?: unknown,
+	signal?: AbortSignal,
+): Promise<Record<string, unknown>> {
+	const headers: Record<string, string> = { Accept: "application/json" };
+	if (body !== undefined) headers["Content-Type"] = "application/json";
+	if (config.apiKey) headers.Authorization = `Bearer ${config.apiKey}`;
+	const response = await fetch(`${config.baseUrl}${endpoint}`, {
+		method,
+		headers,
+		body: body === undefined ? undefined : JSON.stringify(body),
+		signal: signalWithTimeout(config.timeoutMs, signal),
+	});
+	const text = await response.text();
+	if (!response.ok) throw new FirecrawlHttpError(response.status, response.statusText, text);
+	return text ? JSON.parse(text) : { success: true };
+}
+
+/**
+ * Firecrawl API request with optional v2→v1 fallback on 404.
+ * Returns the response data and optionally logs fallback via console.warn.
+ */
+export async function firecrawlRequest(
+	config: FirecrawlConfig,
+	method: string,
+	endpoint: string,
+	body?: unknown,
+	allowFallback = true,
+	signal?: AbortSignal,
+): Promise<Record<string, unknown>> {
+	return withRetry(async () => {
+		try {
+			return await firecrawlRequestJson(config, method, endpoint, body, signal);
+		} catch (e) {
+			if (
+				!allowFallback ||
+				config.isHosted ||
+				!config.baseUrl.endsWith("/v2") ||
+				!(e instanceof FirecrawlHttpError) ||
+				e.status !== 404
+			)
+				throw e;
+			const v1Config = { ...config, baseUrl: config.baseUrl.replace(/\/v2$/, "/v1") };
+			console.warn(
+				`[pi-web] Firecrawl v2 endpoint returned 404, falling back to v1 at ${v1Config.baseUrl}`,
+			);
+			return await firecrawlRequestJson(v1Config, method, endpoint, body, signal);
+		}
+	}, { maxRetries: 2, retryableErrors: ["timeout", "econn", "etimedout", "network", "socket"] });
+}

package/lib/format.ts

@@ -0,0 +1,121 @@
+// Text formatting and result formatting helpers for pi-web.
+
+import { OUTPUT_MAX_BYTES, OUTPUT_MAX_LINES } from "./config";
+
+// ---------------------------------------------------------------------------
+// Search result item types
+// ---------------------------------------------------------------------------
+
+export interface SearchResultItem {
+	title: string;
+	url: string;
+	snippet?: string;
+	age?: string;
+	description?: string;
+	content?: string;
+	markdown?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Text utilities
+// ---------------------------------------------------------------------------
+
+export function sanitizeSnippet(text = ""): string {
+	return text
+		.replace(/<[^>]*>/g, "")
+		.replace(/&nbsp;/gi, " ")
+		.replace(/&amp;/gi, "&")
+		.replace(/&lt;/gi, "<")
+		.replace(/&gt;/gi, ">")
+		.replace(/&quot;/gi, '"')
+		.replace(/&#39;|&#x27;/gi, "'")
+		.replace(/&#(\d+);/g, (_: string, code: string) => String.fromCodePoint(Number(code)))
+		.replace(/&#x([0-9a-f]+);/gi, (_: string, code: string) => String.fromCodePoint(Number.parseInt(code, 16)))
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function truncateText(text: string): string {
+	const lines = text.split("\n");
+	let output = lines.slice(0, OUTPUT_MAX_LINES).join("\n");
+	while (Buffer.byteLength(output, "utf8") > OUTPUT_MAX_BYTES) {
+		output = output.slice(0, Math.max(0, output.length - 1024));
+	}
+	if (lines.length > OUTPUT_MAX_LINES || output.length < text.length) {
+		output += `\n\n[Web output truncated to ${OUTPUT_MAX_LINES} lines / ${OUTPUT_MAX_BYTES} bytes.]`;
+	}
+	return output;
+}
+
+// ---------------------------------------------------------------------------
+// Search result formatting
+// ---------------------------------------------------------------------------
+
+export function formatSearchResults(results: SearchResultItem[]): string {
+	if (!results.length) return "No results found.";
+	return results
+		.map((r, i) =>
+			[
+				`--- Result ${i + 1} ---`,
+				`Title: ${r.title || ""}`,
+				`Link: ${r.url || ""}`,
+				r.age ? `Age: ${r.age}` : "",
+				r.snippet || r.description ? `Snippet: ${r.snippet || r.description}` : "",
+				r.content || r.markdown ? `Content:\n${r.content || r.markdown}` : "",
+			]
+				.filter(Boolean)
+				.join("\n"),
+		)
+		.join("\n\n");
+}
+
+// ---------------------------------------------------------------------------
+// Firecrawl scrape formatting
+// ---------------------------------------------------------------------------
+
+export function formatFirecrawlScrape(data: Record<string, unknown>, maxChars = 20000): string {
+	const page = (data.data as Record<string, unknown>) || data;
+	const meta = (page.metadata as Record<string, unknown>) || {};
+	const parts: string[] = [];
+	if (meta.title) parts.push(`# ${meta.title}`);
+	if (meta.sourceURL || meta.url) parts.push(`Source: ${(meta.sourceURL || meta.url) as string}`);
+	if (meta.statusCode) parts.push(`Status: ${meta.statusCode}`);
+	const warning = (data.warning || page.warning) as string | undefined;
+	if (warning) parts.push(`Warning: ${warning}`);
+	const body = (page.markdown || page.summary || page.answer || page.html || page.rawHtml) as string | undefined;
+	if (body) parts.push(String(body).slice(0, maxChars));
+	if (Array.isArray(page.links)) {
+		parts.push(["## Links", ...(page.links as string[]).slice(0, 100).map((l: string) => `- ${l}`)].join("\n"));
+	}
+	return parts.join("\n\n") || JSON.stringify(data, null, 2);
+}
+
+export function formatFirecrawlSearch(data: Record<string, unknown>, maxChars = 5000): string {
+	const rootData = data.data as Record<string, unknown> | undefined;
+	const web = (rootData?.web as unknown[]) || [];
+	const news = (rootData?.news as unknown[]) || [];
+	const images = (rootData?.images as unknown[]) || [];
+	const results: SearchResultItem[] = [...web, ...news].map((r: any) => ({
+		title: r.title || r.metadata?.title || "",
+		url: r.url || r.metadata?.sourceURL || "",
+		snippet: r.description || r.snippet || "",
+		markdown: r.markdown ? String(r.markdown).slice(0, maxChars) : "",
+	}));
+	let text = formatSearchResults(results);
+	if (images.length) {
+		text +=
+			"\n\n" +
+			images
+				.map((img: any, i: number) =>
+					[
+						`--- Image ${i + 1} ---`,
+						`Title: ${img.title || ""}`,
+						`Image: ${img.imageUrl || ""}`,
+						`Page: ${img.url || ""}`,
+					].join("\n"),
+				)
+				.join("\n\n");
+	}
+	if (data.warning) text += `\n\nWarning: ${data.warning}`;
+	return text;
+}

package/lib/retry.ts

@@ -0,0 +1,142 @@
+// Retry logic with exponential backoff for transient network failures.
+// Ported from pi-munin/lib/retry.ts.
+
+export interface RetryOptions {
+	maxRetries?: number;
+	initialDelay?: number;
+	maxDelay?: number;
+	multiplier?: number;
+	retryableErrors?: string[];
+	onRetry?: (attempt: number, max: number, delay: number, error: Error) => void;
+}
+
+function isRetryableError(error: Error): boolean {
+	const errorMessage = (error.message || "").toLowerCase();
+	const retryablePatterns = [
+		"econnrefused",
+		"enotfound",
+		"etimedout",
+		"econnreset",
+		"econnaborted",
+		"enetunreach",
+		"etimeout",
+		"timeout",
+		"network",
+		"socket hang up",
+		"socket",
+		"connection",
+		"fetch",
+		"request timeout",
+	];
+	return retryablePatterns.some((pattern) => errorMessage.includes(pattern));
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function calculateDelay(
+	attempt: number,
+	initialDelay: number,
+	maxDelay: number,
+	multiplier: number,
+): number {
+	const exponentialDelay = initialDelay * Math.pow(multiplier, attempt);
+	const jitter = Math.random() * 0.1 * exponentialDelay;
+	return Math.min(exponentialDelay + jitter, maxDelay);
+}
+
+/**
+ * Retry a function with exponential backoff.
+ * Never retries auth, not_found, or validation errors.
+ */
+export async function withRetry<T>(
+	fn: () => Promise<T>,
+	options: RetryOptions = {},
+): Promise<T> {
+	const {
+		maxRetries = 3,
+		initialDelay = 1000,
+		maxDelay = 10000,
+		multiplier = 2,
+		retryableErrors = [],
+		onRetry,
+	} = options;
+
+	// Errors we never retry (non-transient)
+	const nonRetryablePatterns = [
+		"unauthorized",
+		"invalid api key",
+		"not found",
+		"validation",
+		"required",
+		"refusing to send",
+		"refusing to send a configured",
+		"must use http or https",
+		"could not extract readable content",
+		"brave_api_key is required",
+		"firecrawl_api_key is required",
+	];
+
+	let lastError: Error;
+
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			return await fn();
+		} catch (error) {
+			lastError = error as Error;
+
+			if (attempt === maxRetries) throw error;
+
+			// Never retry non-transient errors
+			const msg = lastError.message.toLowerCase();
+			if (nonRetryablePatterns.some((p) => msg.includes(p))) throw error;
+
+			// Check if error is retryable
+			const shouldRetry =
+				retryableErrors.length > 0
+					? retryableErrors.some((pattern) => msg.includes(pattern.toLowerCase()))
+					: isRetryableError(lastError);
+
+			if (!shouldRetry) throw error;
+
+			const delay = calculateDelay(attempt, initialDelay, maxDelay, multiplier);
+
+			if (onRetry) {
+				onRetry(attempt + 1, maxRetries + 1, delay, lastError);
+			}
+
+			await sleep(delay);
+		}
+	}
+
+	throw lastError!;
+}
+
+/**
+ * Combine a timeout signal with an optional external signal.
+ */
+export function signalWithTimeout(timeoutMs: number, signal?: AbortSignal): AbortSignal {
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	if (!signal) return timeoutSignal;
+	return AbortSignal.any([signal, timeoutSignal]);
+}
+
+/**
+ * Sleep that is abortable via an AbortSignal.
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Operation aborted."));
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(cleanupResolve, ms);
+		function cleanupResolve() {
+			signal?.removeEventListener("abort", cleanupReject);
+			resolve();
+		}
+		function cleanupReject() {
+			clearTimeout(timer);
+			reject(signal?.reason ?? new Error("Operation aborted."));
+		}
+		signal?.addEventListener("abort", cleanupReject, { once: true });
+	});
+}

package/lib/searxng.ts

@@ -0,0 +1,63 @@
+// SearXNG metasearch client.
+
+import { sanitizeSnippet } from "./format";
+import { signalWithTimeout, withRetry } from "./retry";
+
+export interface SearxngResultItem {
+	title: string;
+	url: string;
+	snippet: string;
+	engine: string;
+	category: string;
+	score?: number;
+	publishedDate: string;
+}
+
+export interface SearxngResponse {
+	results: SearxngResultItem[];
+	[key: string]: unknown;
+}
+
+export async function fetchSearxngResults(
+	params: Record<string, unknown>,
+	baseUrl: string,
+	signal?: AbortSignal,
+): Promise<SearxngResponse> {
+	return withRetry(async () => {
+		const limit = Math.min(50, Math.max(1, (params.count as number) ?? 5));
+		const url = new URL(`${baseUrl}/search`);
+		url.searchParams.set("q", params.query as string);
+		url.searchParams.set("format", "json");
+		url.searchParams.set("pageno", String(Math.max(1, (params.pageno as number) ?? 1)));
+		for (const key of ["categories", "engines", "language", "time_range", "safesearch"] as const) {
+			const val = params[key];
+			if (val !== undefined && val !== "") url.searchParams.set(key, String(val));
+		}
+		const timeoutMs = (params.timeout_ms as number) || 15000;
+		const response = await fetch(url, {
+			headers: { Accept: "application/json", "User-Agent": "pi-web/0.1 SearXNG" },
+			signal: signalWithTimeout(timeoutMs, signal),
+		});
+		const text = await response.text();
+		if (!response.ok) {
+			const hint =
+				response.status === 403
+					? "\nHint: enable JSON output in SearXNG settings.yml with search.formats including json."
+					: "";
+			throw new Error(`HTTP ${response.status}: ${response.statusText}${hint}${text ? `\n${text}` : ""}`);
+		}
+		const data: any = text ? JSON.parse(text) : {};
+		const results = (data.results || [])
+			.slice(0, limit)
+			.map((r: any) => ({
+				title: sanitizeSnippet(r.title || ""),
+				url: r.url || "",
+				snippet: sanitizeSnippet(r.content || r.snippet || ""),
+				engine: r.engine || "",
+				category: r.category || "",
+				score: r.score,
+				publishedDate: r.publishedDate || r.published_date || "",
+			}));
+		return { ...data, results };
+	}, { maxRetries: 2, retryableErrors: ["timeout", "econn", "etimedout", "network", "socket"] });
+}