@bacnh85/pi-web 0.4.1 → 0.4.4

package/extensions/.mocharc.yml

@@ -0,0 +1,5 @@
+require:
+  - tsx
+spec:
+  - test/**/*.test.ts
+timeout: 10000

package/{index.ts → extensions/index.ts}

@@ -49,6 +49,7 @@ const crawl4aiControlSchema = {
 	timeout_ms: Type.Optional(Type.Number({ description: "Request timeout in milliseconds." })),
 };
 
+
 // ---------------------------------------------------------------------------
 // Helper: format unified search results for text output
 // ---------------------------------------------------------------------------
@@ -81,7 +82,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_search",
 		label: "Web Search",
 		description:
-			"Search the web with adaptive backend selection. Uses SearXNG (self-hosted) for broad discovery, Brave (hosted API) for precision-sensitive queries and include_content, and Firecrawl as a last resort. Use backend to force a provider.",
+			"Search the web. Auto-selects backends adaptively: SearXNG, Brave, Firecrawl.",
 		promptSnippet: "Search current web results",
 		promptGuidelines: [
 			"Use web_search for source discovery, documentation lookup, current facts, and general web search.",
@@ -132,7 +133,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_extract",
 		label: "Web Content Extraction",
 		description:
-			"Extract readable content from a URL with automatic backend selection. Tries static extraction (JSDOM+Readability, no API key) first, then dynamic extraction (Firecrawl Scrape, JS rendering), then full browser extraction (Crawl4AI, headless browser). Use the mode parameter for explicit control. If all modes fail, try web_screenshot for a visual snapshot.",
+			"Extract readable content from a URL. Auto backend: static \u2192 dynamic \u2192 full.",
 		promptSnippet: "Extract readable webpage content as markdown",
 		promptGuidelines: [
 			"Use web_extract to get clean markdown content from a known URL.",
@@ -183,7 +184,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_map",
 		label: "Site URL Discovery",
 		description:
-			"Discover URLs from a site using Firecrawl Map. Best for finding candidate pages from a site or docs section before targeted extraction. Works best on base domains; may return empty results on sub-paths.",
+			"Discover URLs from a site using Firecrawl Map.",
 		promptSnippet: "Map site URLs",
 		promptGuidelines: [
 			"Use web_map to discover URLs from a site before crawling or targeted extraction.",
@@ -213,7 +214,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 			if (params.use_index !== undefined) body.useIndex = params.use_index;
 			if (params.ignore_cache !== undefined) body.ignoreCache = params.ignore_cache;
 			const config = loadFirecrawlConfig(params as Record<string, unknown>, cwdFromContext(ctx), includeProjectEnv(ctx));
-			const result = await firecrawlRequest(config, "POST", "/map", body, true, signal);
+			const result = await firecrawlRequest(config, "POST", "/map", body, signal);
 			const urls = result.data || result.links || result.urls || [];
 			const text = Array.isArray(urls) && urls.length > 0
 				? (urls as Array<Record<string, unknown> | string>).map((u: any) => u.url || u).join("\n")
@@ -227,7 +228,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_crawl",
 		label: "Site Crawl",
 		description:
-			"Crawl one or more pages from a site. Uses Firecrawl Crawl in 'light' mode (conservative, doc-focused) or Crawl4AI in 'full' mode (headless browser, rendered data, media, links). Accepts a single URL for Firecrawl-style crawling or multiple URLs for Crawl4AI-style crawling.",
+			"Crawl site pages. Firecrawl 'light' or Crawl4AI 'full' headless mode.",
 		promptSnippet: "Crawl a small site section",
 		promptGuidelines: [
 			"Use web_crawl only when multiple pages from a site are truly needed; prefer web_map + web_extract for small numbers of pages.",
@@ -288,14 +289,13 @@ export default function piWebExtension(pi: ExtensionAPI) {
 						: [],
 					scrapeOptions: { formats: ["markdown"], onlyMainContent: true },
 				},
-				true,
 				signal,
 			);
 			const id = result.id || (result.data as Record<string, unknown> | undefined)?.id;
 			if (params.poll && id && !Array.isArray(result.data)) {
 				const { abortableSleep } = await import("./lib/retry");
 				for (let i = 0; i < 60; i++) {
-					result = await firecrawlRequest(fcConfig, "GET", `/crawl/${id}`, undefined, true, signal);
+					result = await firecrawlRequest(fcConfig, "GET", `/crawl/${id}`, undefined, signal);
 					if (["completed", "failed", "cancelled"].includes(
 						String(result.status || (result.data as Record<string, unknown> | undefined)?.status || ""),
 					)) break;
@@ -319,7 +319,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_screenshot",
 		label: "Web Page Screenshot",
 		description:
-			"Capture a full-page PNG screenshot of a URL using Crawl4AI's headless browser. Returns a base64-encoded PNG image suitable for visual inspection.",
+			"Capture a full-page PNG screenshot via Crawl4AI headless browser.",
 		promptSnippet: "Screenshot a webpage",
 		promptGuidelines: [
 			"Use web_screenshot when a visual snapshot of a rendered page is needed, or when web_extract fails on a heavily JS-dependent or bot-protected page.",
@@ -360,7 +360,7 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_pdf",
 		label: "Web Page PDF",
 		description:
-			"Generate a PDF document of a URL using Crawl4AI's headless browser. Returns a base64-encoded PDF suitable for saving or archiving.",
+			"Generate a PDF document via Crawl4AI headless browser.",
 		promptSnippet: "PDF a webpage",
 		promptGuidelines: [
 			"Use web_pdf when a printable or archivable snapshot of a page is needed.",
@@ -389,13 +389,14 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		name: "web_status",
 		label: "Web Provider Status",
 		description:
-			"Show all web provider configuration status (Brave, SearXNG, Firecrawl, Crawl4AI) without printing secrets. Includes Crawl4AI server health check. Use when web tools fail due to missing credentials or configuration issues.",
+			"Show web provider configuration status without printing secrets.",
 		promptSnippet: "Check web provider configuration and server status",
 		promptGuidelines: [
 			"Use web_status when web tools fail due to missing credentials/config or to verify which backends are available.",
 			"The output shows which backends are configured; if a backend is missing, configure its env vars.",
 			"Never print API key values; this tool reports only presence and source.",
 			"Shows Crawl4AI server health, version, and auth status when the server is reachable.",
+			"For Firecrawl, `apiKeyFound: false` is normal for self-hosted instances without auth. Use the `ready` field to check whether Firecrawl is actually usable.",
 		],
 		parameters: Type.Object({}),
 		async execute(_id: string, _params: Record<string, unknown>, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
@@ -410,15 +411,19 @@ export default function piWebExtension(pi: ExtensionAPI) {
 			const c4aiUrl = findEnvValue("CRAWL4AI_API_URL", cwd, trusted);
 			const c4aiToken = findEnvValue("CRAWL4AI_API_TOKEN", cwd, trusted);
 
+			const fcBaseUrl = normalizeFirecrawlBaseUrl(fireUrl.value);
+			const fcHosted = !fireUrl.value || fcBaseUrl.startsWith(HOSTED_FIRECRAWL_BASE_URL);
+
 			const status: Record<string, unknown> = {
 				brave: { apiKeyFound: Boolean(braveKey.value), apiKeySource: braveKey.value ? braveKey.source : "not set" },
 				searxng: { baseUrl: normalizeSearxngBaseUrl(searxngUrl.value), baseUrlSource: searxngUrl.source || "default local" },
 				firecrawl: {
-					baseUrl: normalizeFirecrawlBaseUrl(fireUrl.value),
+					baseUrl: fcBaseUrl,
 					apiUrlSource: fireUrl.source || "default hosted",
 					apiKeyFound: Boolean(fireKey.value),
 					apiKeySource: fireKey.value ? fireKey.source : "not set",
-					hostedMode: !fireUrl.value || normalizeFirecrawlBaseUrl(fireUrl.value).startsWith(HOSTED_FIRECRAWL_BASE_URL),
+					hostedMode: fcHosted,
+					ready: fcHosted ? Boolean(fireKey.value) : Boolean(fireUrl.value?.trim()),
 				},
 				crawl4ai: {
 					baseUrl: normalizeCrawl4aiApiUrl(c4aiUrl.value),
@@ -442,29 +447,4 @@ export default function piWebExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	// ── /web-status command ──────────────────────────────────────────────
-	pi.registerCommand("web-status", {
-		description: "Show web provider configuration status",
-		handler: async (_args: string, ctx: any) => {
-			const cwd = cwdFromContext(ctx);
-			const trusted = includeProjectEnv(ctx);
-			const braveKey = findEnvValue("BRAVE_API_KEY", cwd, trusted);
-			const searxngUrl = findEnvValue("SEARXNG_BASE_URL", cwd, trusted);
-			const fireKey = findEnvValue("FIRECRAWL_API_KEY", cwd, trusted);
-			const fireUrl = findEnvValue("FIRECRAWL_API_URL", cwd, trusted);
-			const c4aiUrl = findEnvValue("CRAWL4AI_API_URL", cwd, trusted);
-			const c4aiToken = findEnvValue("CRAWL4AI_API_TOKEN", cwd, trusted);
-			ctx.ui.notify(
-				[
-					`Brave API key: ${braveKey.value ? `found (${braveKey.source})` : "not set"}`,
-					`SearXNG base URL: ${normalizeSearxngBaseUrl(searxngUrl.value)} (${searxngUrl.source || "default local"})`,
-					`Firecrawl base URL: ${normalizeFirecrawlBaseUrl(fireUrl.value)}`,
-					`Firecrawl API key: ${fireKey.value ? `found (${fireKey.source})` : "not set"}`,
-					`Crawl4AI API URL: ${normalizeCrawl4aiApiUrl(c4aiUrl.value)} (${c4aiUrl.source || "default"})`,
-					`Crawl4AI API token: ${c4aiToken.value ? `found (${c4aiToken.source})` : "not set"}`,
-				].join("\n"),
-				"info",
-			);
-		},
-	});
 }

package/extensions/lib/brave.ts

@@ -0,0 +1,45 @@
+// Brave Search API client.
+
+import { sanitizeSnippet, type SearchResultItem } from "./format";
+
+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[]> {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		try {
+			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 || ""),
+				}));
+		} catch (e) {
+			if (attempt === 2) throw e;
+			await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
+		}
+	}
+	throw new Error("unreachable");
+}

package/{lib → extensions/lib}/config.ts

@@ -1,4 +1,4 @@
-// Configuration loading and environment helpers for pi-web.
+// ponytail: duplicated in pi-munin/lib/helpers.ts. Extract when a third package needs it.
 
 import fs from "node:fs";
 import os from "node:os";
@@ -8,8 +8,6 @@ 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";
 export const DEFAULT_CRAWL4AI_API_URL = "http://172.30.55.22:11235";
@@ -183,7 +181,6 @@ export function loadFirecrawlConfig(params: Record<string, unknown> = {}, cwd =
 	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 → extensions/lib}/crawl4ai.ts

@@ -3,7 +3,7 @@
 // Endpoints: /crawl, /crawl/stream, /md, /screenshot, /pdf, /health
 
 import type { Crawl4aiConfig } from "./config";
-import { signalWithTimeout, withRetry } from "./retry";
+import { signalWithTimeout } from "./retry";
 
 // ---------------------------------------------------------------------------
 // Error
@@ -52,9 +52,15 @@ export async function crawl4aiRequest(
 	body?: unknown,
 	signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
-	return withRetry(async () => {
-		return await crawl4aiRequestJson(config, method, endpoint, body, signal);
-	}, { maxRetries: 2, retryableErrors: ["timeout", "econn", "etimedout", "network", "socket"] });
+	for (let attempt = 0; attempt < 3; attempt++) {
+		try {
+			return await crawl4aiRequestJson(config, method, endpoint, body, signal);
+		} catch (e) {
+			if (attempt === 2) throw e;
+			await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
+		}
+	}
+	throw new Error("unreachable");
 }
 
 // ---------------------------------------------------------------------------
@@ -142,36 +148,6 @@ export async function fetchCrawl4aiCrawl(
 	};
 }
 
-/**
- * Crawl one or more URLs via POST /crawl/stream.
- * Returns newline-delimited JSON lines as a string.
- */
-export async function fetchCrawl4aiStream(
-	config: Crawl4aiConfig,
-	urls: string[],
-	browserConfig?: Record<string, unknown>,
-	crawlerConfig?: Record<string, unknown>,
-	signal?: AbortSignal,
-): Promise<string> {
-	const body: Record<string, unknown> = { urls };
-	if (browserConfig) body.browser_config = browserConfig;
-	if (crawlerConfig) body.crawler_config = crawlerConfig;
-	const headers: Record<string, string> = { Accept: "application/json" };
-	if (config.apiToken) headers.Authorization = `Bearer ${config.apiToken}`;
-	headers["Content-Type"] = "application/json";
-	const response = await fetch(`${config.baseUrl}/crawl/stream`, {
-		method: "POST",
-		headers,
-		body: JSON.stringify(body),
-		signal: signalWithTimeout(config.timeoutMs, signal),
-	});
-	if (!response.ok) {
-		const text = await response.text();
-		throw new Crawl4aiHttpError(response.status, response.statusText, text);
-	}
-	return await response.text();
-}
-
 /**
  * Capture a screenshot via POST /screenshot.
  */
@@ -206,17 +182,7 @@ export async function fetchCrawl4aiHealth(
 	config: Crawl4aiConfig,
 	signal?: AbortSignal,
 ): Promise<{ status?: string; version?: string; timestamp?: number }> {
-	const headers: Record<string, string> = { Accept: "application/json" };
-	if (config.apiToken) headers.Authorization = `Bearer ${config.apiToken}`;
-	const timeoutMs = Math.min(config.timeoutMs, 10000);
-	const response = await fetch(`${config.baseUrl}/health`, {
-		method: "GET",
-		headers,
-		signal: signalWithTimeout(timeoutMs, signal),
-	});
-	const text = await response.text();
-	if (!response.ok) throw new Crawl4aiHttpError(response.status, response.statusText, text);
-	const data = text ? JSON.parse(text) : {};
+	const data = await crawl4aiRequest({ ...config, timeoutMs: Math.min(config.timeoutMs, 10000) }, "GET", "/health", undefined, signal);
 	return {
 		status: data.status as string | undefined,
 		version: data.version as string | undefined,

package/{lib → extensions/lib}/extract.ts

@@ -111,7 +111,7 @@ async function extractDynamic(params: ExtractParams, ctx?: Record<string, unknow
 		...(params.wait_for ? { waitFor: params.wait_for } : {}),
 		...(params.mobile ? { mobile: true } : {}),
 	};
-	const result = await firecrawlRequest(fcConfig, "POST", "/scrape", body, true, params.signal) as FirecrawlResult;
+	const result = await firecrawlRequest(fcConfig, "POST", "/scrape", body, params.signal) as FirecrawlResult;
 	const structured = findStructuredPayload(result);
 	const raw = `${formatFirecrawlScrape(result as Record<string, unknown>, params.content_chars ?? 20000)}${structuredSection(structured)}`;
 	const titleMatch = raw.match(/^# (.+)$/m);
@@ -183,7 +183,3 @@ export async function extractWithDiagnostics(params: ExtractParams): Promise<Ext
 	);
 }
 
-/** Compatibility wrapper returning only the selected extraction result. */
-export async function universalExtract(params: ExtractParams): Promise<ExtractResult> {
-	return (await extractWithDiagnostics(params)).result;
-}

package/{lib → extensions/lib}/firecrawl.ts

@@ -1,7 +1,7 @@
 // Firecrawl API client (search, scrape, map, crawl).
 
 import type { FirecrawlConfig } from "./config";
-import { signalWithTimeout, withRetry } from "./retry";
+import { signalWithTimeout } from "./retry";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -53,34 +53,22 @@ async function firecrawlRequestJson(
 }
 
 /**
- * Firecrawl API request with optional v2→v1 fallback on 404.
- * Returns the response data and optionally logs fallback via console.warn.
+ * Firecrawl API request with retry.
  */
 export async function firecrawlRequest(
 	config: FirecrawlConfig,
 	method: string,
 	endpoint: string,
 	body?: unknown,
-	allowFallback = true,
 	signal?: AbortSignal,
 ): Promise<Record<string, unknown>> {
-	return withRetry(async () => {
+	for (let attempt = 0; attempt < 3; attempt++) {
 		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);
+			if (attempt === 2) throw e;
+			await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
 		}
-	}, { maxRetries: 2, retryableErrors: ["timeout", "econn", "etimedout", "network", "socket"] });
+	}
+	throw new Error("unreachable");
 }

package/{lib → extensions/lib}/format.ts

@@ -1,6 +1,7 @@
 // Text formatting and result formatting helpers for pi-web.
 
-import { OUTPUT_MAX_BYTES, OUTPUT_MAX_LINES } from "./config";
+const OUTPUT_MAX_BYTES = 50 * 1024;
+const OUTPUT_MAX_LINES = 2_000;
 
 // ---------------------------------------------------------------------------
 // Search result item types
@@ -47,28 +48,6 @@ export function truncateText(text: string): string {
 	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
 // ---------------------------------------------------------------------------
@@ -175,51 +154,3 @@ export function formatCrawl4aiResult(data: Record<string, unknown>, maxChars = 2
 		.join("\n\n---\n\n") || "(No data)";
 }
 
-export function formatCrawl4aiStream(lines: string, _maxChars = 20000): string {
-	const results: string[] = [];
-	for (const line of lines.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		try {
-			const parsed = JSON.parse(trimmed);
-			if (parsed.status === "completed") {
-				results.push("[Stream complete]");
-				break;
-			}
-			results.push(formatCrawl4aiResult(parsed, _maxChars));
-		} catch {
-			results.push(trimmed.slice(0, 1000));
-		}
-	}
-	return results.join("\n\n---\n\n");
-}
-
-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/extensions/lib/retry.ts

@@ -0,0 +1,29 @@
+// Retry utility: signal/timeout helpers.
+
+/**
+ * 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 → extensions/lib}/search.ts

@@ -144,7 +144,7 @@ async function searchBrave(params: SearchParams, backends: BackendConfig): Promi
 
 async function searchFirecrawl(params: SearchParams, backends: BackendConfig): Promise<SearchResult[]> {
 	if (!backends.firecrawl.configured || !backends.firecrawl.config) {
-		throw new Error("Firecrawl not configured (no FIRECRAWL_API_KEY/FIRECRAWL_API_URL)");
+		throw new Error("Firecrawl not configured (no FIRECRAWL_API_URL)");
 	}
 	const body: Record<string, unknown> = {
 		query: params.query,
@@ -152,7 +152,7 @@ async function searchFirecrawl(params: SearchParams, backends: BackendConfig): P
 		sources: [{ type: "web" }],
 		...(params.country ? { country: String(params.country).toUpperCase() } : {}),
 	};
-	const result = await firecrawlRequest(backends.firecrawl.config, "POST", "/search", body, true, params.signal) as FirecrawlResult;
+	const result = await firecrawlRequest(backends.firecrawl.config, "POST", "/search", body, params.signal) as FirecrawlResult;
 	const rootData = result.data as Record<string, unknown> | undefined;
 	const web = (rootData?.web as unknown[]) || [];
 	const news = (rootData?.news as unknown[]) || [];
@@ -238,7 +238,3 @@ export async function searchWithDiagnostics(params: SearchParams): Promise<Searc
 	);
 }
 
-/** Compatibility wrapper returning only results. */
-export async function universalSearch(params: SearchParams): Promise<SearchResult[]> {
-	return (await searchWithDiagnostics(params)).results;
-}

package/extensions/lib/searxng.ts

@@ -0,0 +1,69 @@
+// SearXNG metasearch client.
+
+import { sanitizeSnippet } from "./format";
+import { signalWithTimeout } 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> {
+	for (let attempt = 0; attempt < 3; attempt++) {
+		try {
+			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 };
+		} catch (e) {
+			if (attempt === 2) throw e;
+			await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
+		}
+	}
+	throw new Error("unreachable");
+}

package/extensions/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}