@juicesharp/rpiv-web-tools 1.10.2 → 1.12.0

package/README.md

@@ -8,17 +8,14 @@
   </a>
 </div>
 
-[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-web-tools.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-web-tools)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-Let the model search the web and read pages. `rpiv-web-tools` adds `web_search` and `web_fetch` tools to [Pi Agent](https://github.com/badlogic/pi-mono) with pluggable providers (Brave, Tavily, Serper, Exa, Jina, Firecrawl), plus `/web-search-config` for interactive provider selection and API-key setup.
+Let the model search the web and read pages. `rpiv-web-tools` adds `web_search` and `web_fetch` tools to [Pi Agent](https://github.com/badlogic/pi-mono) with pluggable providers (Brave, Tavily, Serper, Exa, Jina, Firecrawl, [SearXNG](https://docs.searxng.org/)), plus `/web-search-config` for interactive provider selection and API-key setup.
 
 ![Provider selection prompt](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-web-tools/docs/config.jpg)
 
 ## Features
 
-- **Six pluggable providers** - Brave, Tavily, Serper, Exa, Jina, Firecrawl. Pick one as the active backend; switch any time without losing the others' keys.
-- **Per-provider fetch strategy** - Brave and Serper read the URL directly and strip HTML to text; Tavily/Exa/Jina/Firecrawl use their native extraction endpoints (markdown for Jina/Firecrawl, plain text for Tavily/Exa).
+- **Seven pluggable providers** - Brave, Tavily, Serper, Exa, Jina, Firecrawl, and self-hosted SearXNG. Pick one as the active backend; switch any time without losing the others' keys.
+- **Per-provider fetch strategy** - Brave, Serper, and SearXNG read the URL directly and strip HTML to text; Tavily/Exa/Jina/Firecrawl use their native extraction endpoints (markdown for Jina/Firecrawl, plain text for Tavily/Exa).
 - **Read any URL** - fetch http/https pages with HTML-to-text extraction, or get the raw response with `raw: true` (honoured by Brave/Serper; extraction providers always return their parsed text).
 - **Large-page spillover** - oversized responses truncate inline and spill the full body to a temp file the model can read on demand.
 - **SSRF guard** - refuses loopback, RFC 1918, link-local, and cloud-metadata addresses (`localhost`, `127.0.0.0/8`, `10.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.168.0.0/16`, `::1`, `fc00::/7`, `fe80::/10`).
@@ -56,7 +53,7 @@ Returns:
   content: [{ type: "text", text: string }], // markdown list of "**title**\n url\n snippet"
   details: {
     query: string,
-    backend: "brave" | "tavily" | "serper" | "exa" | "jina" | "firecrawl",
+    backend: "brave" | "tavily" | "serper" | "exa" | "jina" | "firecrawl" | "searxng",
     resultCount: number,
     results?: Array<{ title: string, url: string, snippet: string }>,
   }
@@ -103,12 +100,49 @@ Throws on invalid URL, non-http(s) protocol, private/loopback hostnames (SSRF gu
 
 First match wins:
 
-1. The active provider's environment variable: `BRAVE_SEARCH_API_KEY`, `TAVILY_API_KEY`, `SERPER_API_KEY`, `EXA_API_KEY`, `JINA_API_KEY`, or `FIRECRAWL_API_KEY`
+1. The active provider's environment variable: `BRAVE_SEARCH_API_KEY`, `TAVILY_API_KEY`, `SERPER_API_KEY`, `EXA_API_KEY`, `JINA_API_KEY`, `FIRECRAWL_API_KEY`, or `SEARXNG_API_KEY`
 2. `apiKeys.<provider>` field in `~/.config/rpiv-web-tools/config.json`
 3. Legacy `apiKey` field (Brave only — auto-migrated to the new shape on next save)
 
 The active provider is `config.provider` (set by `/web-search-config`); falls back to `brave` if absent.
 
+## SearXNG (self-hosted)
+
+SearXNG is the only provider that talks to an instance you control, so it needs a base URL instead of (or in addition to) an API key.
+
+```bash
+export SEARXNG_URL=http://localhost:8080
+# Optional: only if your instance sits behind a Bearer-auth reverse proxy
+export SEARXNG_API_KEY=…
+```
+
+Resolution order for the URL: `SEARXNG_URL` env var → `baseUrls.searxng` in `~/.config/rpiv-web-tools/config.json` → default `http://localhost:8080`. `/web-search-config` prompts for the URL first and the (optional) API key second.
+
+Your instance must have `json` enabled in `settings.yml` under `search.formats` — default SearXNG installs ship with JSON disabled and will return `403 Forbidden` otherwise (per the [SearXNG search API docs](https://docs.searxng.org/dev/search_api.html)). The provider surfaces that case with an actionable hint. SearXNG's `web_fetch` reuses the same raw-HTTP + HTML-to-text pipeline as Brave/Serper, so URLs returned by `web_search` can be fetched without any extra setup.
+
+The SSRF guard (which refuses loopback and RFC-1918 addresses) applies to URLs `web_fetch` retrieves on the model's behalf, not to the SearXNG search endpoint itself: a `SEARXNG_URL` pointing at `http://localhost:8080` or another private host is intentionally reachable, since SearXNG is self-hosted by design.
+
+### Running SearXNG locally with Docker
+
+The `searxng/searxng` entrypoint **overwrites** `/etc/searxng/settings.yml` on first start with the bundled default (ships with `formats: [html]` only). Pre-populating the mounted file doesn't stick — wait for the entrypoint, then patch:
+
+```bash
+mkdir -p ~/.searxng
+docker run -d --name searxng --restart unless-stopped \
+  -p 8080:8080 -v "$HOME/.searxng":/etc/searxng \
+  -e BASE_URL=http://localhost:8080/ searxng/searxng:latest
+sleep 5  # wait for entrypoint to write settings.yml
+sed -i.bak '/^  formats:$/,/^[^ ]/ { /- html/a\
+    - json
+}' ~/.searxng/settings.yml
+docker restart searxng
+
+# Sanity check — a number > 0 means it's wired correctly
+curl -sf 'http://localhost:8080/search?q=hello&format=json' | jq '.results | length'
+```
+
+`403` means JSON is still disabled — re-check `~/.searxng/settings.yml`. Works identically on Docker Desktop or OrbStack. For a throwaway test instance, swap `~/.searxng` for `/tmp/searxng` and drop `--restart unless-stopped`.
+
 ## Executor guidance overrides
 
 Override the `promptSnippet` / `promptGuidelines` the model sees for each tool by editing `~/.config/rpiv-web-tools/config.json`. Note the per-tool nesting under `guidance.web_search` / `guidance.web_fetch` — this differs from the flat `guidance` shape used by single-tool siblings (`rpiv-advisor`, `rpiv-todo`, `rpiv-ask-user-question`):
@@ -145,4 +179,7 @@ The guard is host-literal only; it does NOT resolve DNS or validate redirects. A
 
 ## License
 
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-web-tools.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-web-tools)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-web-tools",
-	"version": "1.10.2",
+	"version": "1.12.0",
 	"description": "Pi extension. Web search and fetch for the model with pluggable providers (Brave, Tavily, Serper, Exa, Jina, Firecrawl).",
 	"keywords": [
 		"pi-package",
@@ -48,7 +48,7 @@
 		]
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^1.10.2"
+		"@juicesharp/rpiv-config": "^1.12.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",

package/providers/factory.ts

@@ -2,11 +2,18 @@ import { BraveProvider } from "./brave.js";
 import { ExaProvider } from "./exa.js";
 import { FirecrawlProvider } from "./firecrawl.js";
 import { JinaProvider } from "./jina.js";
+import { SearxngProvider } from "./searxng.js";
 import { SerperProvider } from "./serper.js";
 import { TavilyProvider } from "./tavily.js";
 import type { SearchProvider } from "./types.js";
 
-export function createSearchProvider(name: string, apiKey: string): SearchProvider {
+export interface ProviderCredentials {
+	apiKey?: string;
+	baseUrl?: string;
+}
+
+export function createSearchProvider(name: string, creds: ProviderCredentials): SearchProvider {
+	const apiKey = creds.apiKey ?? "";
 	switch (name) {
 		case "brave":
 			return new BraveProvider(apiKey);
@@ -20,6 +27,8 @@ export function createSearchProvider(name: string, apiKey: string): SearchProvid
 			return new JinaProvider(apiKey);
 		case "firecrawl":
 			return new FirecrawlProvider(apiKey);
+		case "searxng":
+			return new SearxngProvider({ apiKey: creds.apiKey, baseUrl: creds.baseUrl ?? "" });
 		default:
 			throw new Error(`Unknown search provider: "${name}"`);
 	}

package/providers/index.ts

@@ -2,23 +2,50 @@ import { BRAVE_PROVIDER_META } from "./brave.js";
 import { EXA_PROVIDER_META } from "./exa.js";
 import { FIRECRAWL_PROVIDER_META } from "./firecrawl.js";
 import { JINA_PROVIDER_META } from "./jina.js";
+import { SEARXNG_PROVIDER_META } from "./searxng.js";
 import { SERPER_PROVIDER_META } from "./serper.js";
 import { TAVILY_PROVIDER_META } from "./tavily.js";
+import type { ProviderMeta } from "./types.js";
 
 export { BRAVE_API_KEY_ENV_VAR, BRAVE_PROVIDER_META, BraveProvider } from "./brave.js";
 export { EXA_API_KEY_ENV_VAR, EXA_PROVIDER_META, ExaProvider } from "./exa.js";
-export { createSearchProvider } from "./factory.js";
+export { createSearchProvider, type ProviderCredentials } from "./factory.js";
 export { FIRECRAWL_API_KEY_ENV_VAR, FIRECRAWL_PROVIDER_META, FirecrawlProvider } from "./firecrawl.js";
 export { JINA_API_KEY_ENV_VAR, JINA_PROVIDER_META, JinaProvider } from "./jina.js";
+export {
+	configureSearxng,
+	SEARXNG_API_KEY_ENV_VAR,
+	SEARXNG_DEFAULT_URL,
+	SEARXNG_PROVIDER_META,
+	SEARXNG_URL_ENV_VAR,
+	type SearxngConfigChange,
+	type SearxngConfigCurrent,
+	type SearxngConfigUi,
+	SearxngProvider,
+} from "./searxng.js";
 export { SERPER_API_KEY_ENV_VAR, SERPER_PROVIDER_META, SerperProvider } from "./serper.js";
 export { TAVILY_API_KEY_ENV_VAR, TAVILY_PROVIDER_META, TavilyProvider } from "./tavily.js";
-export type { FetchResponse, SearchProvider, SearchResponse, SearchResult } from "./types.js";
+export type {
+	FetchResponse,
+	ProviderConfigChange,
+	ProviderConfigCurrent,
+	ProviderConfigUi,
+	ProviderMeta,
+	SearchProvider,
+	SearchResponse,
+	SearchResult,
+} from "./types.js";
 
-export const PROVIDERS = [
+// Typed as readonly ProviderMeta[] (not `as const`) so iterators can access
+// the optional META fields (baseUrlEnvVar, defaultBaseUrl, configure) without
+// per-element narrowing. Individual META consts still expose their narrow
+// literal types when imported directly.
+export const PROVIDERS: readonly ProviderMeta[] = [
 	BRAVE_PROVIDER_META,
 	TAVILY_PROVIDER_META,
 	SERPER_PROVIDER_META,
 	EXA_PROVIDER_META,
 	JINA_PROVIDER_META,
 	FIRECRAWL_PROVIDER_META,
-] as const;
+	SEARXNG_PROVIDER_META,
+];

package/providers/searxng.ts

@@ -0,0 +1,242 @@
+import { assertTextContentType, extractBodyAsText, fetchUrlOrThrow } from "./fetch-helpers.js";
+import {
+	type FetchResponse,
+	isCancellation,
+	type ProviderConfigChange,
+	type ProviderConfigCurrent,
+	type ProviderConfigUi,
+	type ProviderMeta,
+	type SearchProvider,
+	type SearchResponse,
+	type SearchResult,
+} from "./types.js";
+
+export const SEARXNG_API_KEY_ENV_VAR = "SEARXNG_API_KEY";
+export const SEARXNG_URL_ENV_VAR = "SEARXNG_URL";
+export const SEARXNG_DEFAULT_URL = "http://localhost:8080";
+
+// SearXNG search API knobs (per https://docs.searxng.org/dev/search_api.html).
+const SEARXNG_SEARCH_PATH = "/search";
+const SEARXNG_FORMAT_JSON = "json";
+const SEARXNG_SAFESEARCH_OFF = "0"; // 0/1/2 = none/moderate/strict
+
+// Number of leading + trailing characters preserved when masking a Bearer key
+// in the config prompt. Mirrors API_KEY_MASK_VISIBLE_CHARS in web-tools.ts.
+const MASK_VISIBLE_CHARS = 4;
+
+// SearXNG-specific aliases of the generic config shapes — preserved for
+// backward compatibility with the symbols exported in v1.11.0. New providers
+// should consume the generic ProviderConfig* types from ./types.js directly.
+export type SearxngConfigUi = ProviderConfigUi;
+export type SearxngConfigCurrent = ProviderConfigCurrent;
+export type SearxngConfigChange = ProviderConfigChange;
+
+export const SEARXNG_PROVIDER_META: ProviderMeta = {
+	name: "searxng",
+	label: "SearXNG",
+	envVar: SEARXNG_API_KEY_ENV_VAR,
+	baseUrlEnvVar: SEARXNG_URL_ENV_VAR,
+	defaultBaseUrl: SEARXNG_DEFAULT_URL,
+	configure: (ui, current) => configureSearxng(ui, current),
+};
+
+interface SearxngRawResult {
+	title?: string;
+	url?: string;
+	content?: string;
+}
+
+interface SearxngRawResponse {
+	results?: SearxngRawResult[];
+}
+
+function normalizeSearxngResults(raw: SearxngRawResponse, maxResults: number): SearchResult[] {
+	return (raw.results ?? []).slice(0, maxResults).map((r) => ({
+		title: r.title ?? "",
+		url: r.url ?? "",
+		snippet: r.content ?? "",
+	}));
+}
+
+function stripTrailingSlashes(url: string): string {
+	return url.replace(/\/+$/, "");
+}
+
+// Reject anything that isn't an http(s) URL — a user-supplied SEARXNG_URL
+// must not be allowed to silently become `file://`, `javascript:`, `data:`
+// or any other scheme that `new URL()` accepts but we'd misuse downstream.
+function assertHttpUrl(url: string): void {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`${SEARXNG_URL_ENV_VAR} is not a valid URL (got: ${url})`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error(
+			`${SEARXNG_URL_ENV_VAR} must use http:// or https:// (got: ${parsed.protocol.replace(":", "")}://)`,
+		);
+	}
+}
+
+// 401 ≈ reverse-proxy auth rejected the Bearer token. 403 from a default
+// SearXNG install almost always means JSON output is disabled — the docs
+// explicitly warn that "Requesting an unset format will return a 403
+// Forbidden error". Surface the actionable fix for each.
+function hintForSearchStatus(status: number): string {
+	if (status === 401) {
+		return ` (the SearXNG instance's reverse-proxy rejected the Bearer token; check ${SEARXNG_API_KEY_ENV_VAR} or apiKeys.searxng)`;
+	}
+	if (status === 403) {
+		return " (the SearXNG instance may have JSON output disabled; enable 'json' under 'search.formats' in its settings.yml)";
+	}
+	return "";
+}
+
+interface SearxngProviderOptions {
+	apiKey?: string;
+	baseUrl: string;
+}
+
+export class SearxngProvider implements SearchProvider {
+	readonly name = "searxng";
+	readonly label = "SearXNG";
+	readonly envVar = SEARXNG_API_KEY_ENV_VAR;
+
+	private readonly apiKey?: string;
+	private readonly baseUrl: string;
+
+	constructor(options: SearxngProviderOptions) {
+		this.apiKey = options.apiKey?.trim() || undefined;
+		const trimmed = stripTrailingSlashes(options.baseUrl?.trim() ?? "");
+		if (trimmed) assertHttpUrl(trimmed);
+		this.baseUrl = trimmed;
+	}
+
+	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
+		this.requireBaseUrl();
+		const res = await fetch(this.buildSearchUrl(query), {
+			method: "GET",
+			headers: this.buildAuthHeaders(),
+			signal,
+		});
+		if (!res.ok) throw await this.searchApiError(res);
+		const raw = (await res.json()) as SearxngRawResponse;
+		return { query, results: normalizeSearxngResults(raw, maxResults) };
+	}
+
+	// No guard: SearXNG's fetch() wraps the built-in HTTP+htmlToText pipeline
+	// and does not call the SearXNG instance — same contract as Brave/Serper.
+	async fetch(url: string, raw: boolean, signal?: AbortSignal): Promise<FetchResponse> {
+		const res = await fetchUrlOrThrow(url, signal);
+		const contentType = res.headers.get("content-type") ?? "";
+		assertTextContentType(contentType);
+
+		const { text, title } = await extractBodyAsText(res, contentType, raw);
+		const contentLengthHeader = res.headers.get("content-length");
+		return {
+			text,
+			title,
+			contentType: contentType || undefined,
+			contentLength: contentLengthHeader ? Number(contentLengthHeader) : undefined,
+		};
+	}
+
+	private requireBaseUrl(): void {
+		if (!this.baseUrl) {
+			throw new Error(
+				`${SEARXNG_URL_ENV_VAR} is not set. Run /web-search-config to configure, or export the env var.`,
+			);
+		}
+	}
+
+	// The SearXNG API exposes only `pageno` for pagination, not `count`/`limit`
+	// (https://docs.searxng.org/dev/search_api.html), so we ask for a single
+	// page and slice to maxResults client-side.
+	private buildSearchUrl(query: string): string {
+		const url = new URL(`${this.baseUrl}${SEARXNG_SEARCH_PATH}`);
+		url.searchParams.set("q", query);
+		url.searchParams.set("format", SEARXNG_FORMAT_JSON);
+		url.searchParams.set("safesearch", SEARXNG_SAFESEARCH_OFF);
+		return url.toString();
+	}
+
+	// SearXNG itself has no native auth; the optional Bearer key is for
+	// instances fronted by a reverse-proxy that gates on Authorization.
+	private buildAuthHeaders(): Record<string, string> {
+		const headers: Record<string, string> = { Accept: "application/json" };
+		if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+		return headers;
+	}
+
+	private async searchApiError(res: Response): Promise<Error> {
+		const body = await res.text();
+		return new Error(`${this.label} Search API error (${res.status})${hintForSearchStatus(res.status)}: ${body}`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// /web-search-config helper — SearXNG branch
+// ---------------------------------------------------------------------------
+// SEARXNG_PROVIDER_META.configure wires configureSearxng() in; the orchestrator
+// dispatches generically through ProviderMeta.configure without naming
+// SearXNG specifically.
+
+// Mirrors web-tools.ts:maskApiKey. Duplicated here (3 lines) to keep
+// providers/* free of web-tools internals; consolidate if this ever grows.
+function maskKey(key: string): string {
+	const head = key.slice(0, MASK_VISIBLE_CHARS);
+	const tail = key.slice(-MASK_VISIBLE_CHARS);
+	return `${head}...${tail}`;
+}
+
+// Returns the resolved URL string, or `undefined` if the user cancelled.
+// Empty input keeps the current URL or falls back to SEARXNG_DEFAULT_URL.
+async function promptForBaseUrl(ui: ProviderConfigUi, current: string | undefined): Promise<string | undefined> {
+	const existing = current?.trim();
+	const input = await ui.input(
+		"SearXNG base URL",
+		existing
+			? `Press Enter to keep current (${existing}), or type new URL`
+			: `Press Enter for default (${SEARXNG_DEFAULT_URL}), or type instance URL`,
+	);
+	if (isCancellation(input)) return undefined;
+	return input.trim() || existing || SEARXNG_DEFAULT_URL;
+}
+
+// Returns the resolved key string, `null` to leave unset, or `undefined` if
+// the user cancelled. Empty input keeps the current key or leaves it unset.
+async function promptForOptionalKey(
+	ui: ProviderConfigUi,
+	current: string | undefined,
+): Promise<string | null | undefined> {
+	const existing = current?.trim() || undefined;
+	const input = await ui.input(
+		"SearXNG API key (optional — for instances behind a Bearer-auth proxy)",
+		existing
+			? `Press Enter to keep current (${maskKey(existing)}), or type new key`
+			: "Press Enter to leave unset, or type a key",
+	);
+	if (isCancellation(input)) return undefined;
+	return input.trim() || existing || null;
+}
+
+/**
+ * Prompts the user for the SearXNG base URL and optional Bearer API key.
+ * Returns `null` if the user cancels at either prompt.
+ *
+ * The caller owns persistence (loading/merging/saving WebToolsConfig) and
+ * user-visible notifications. This helper only handles the prompt flow.
+ */
+export async function configureSearxng(
+	ui: SearxngConfigUi,
+	current: SearxngConfigCurrent,
+): Promise<SearxngConfigChange | null> {
+	const baseUrl = await promptForBaseUrl(ui, current.baseUrl);
+	if (baseUrl === undefined) return null;
+
+	const apiKey = await promptForOptionalKey(ui, current.apiKey);
+	if (apiKey === undefined) return null;
+
+	return { baseUrl, apiKey };
+}

package/providers/types.ts

@@ -23,3 +23,57 @@ export interface SearchProvider {
 	search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse>;
 	fetch(url: string, raw: boolean, signal?: AbortSignal): Promise<FetchResponse>;
 }
+
+// ---------------------------------------------------------------------------
+// PROVIDER_META + per-provider configure() contract
+// ---------------------------------------------------------------------------
+
+// User input from a ProviderConfigUi prompt. Both `null` and `undefined`
+// indicate the user cancelled (different UI implementations may return
+// either); use isCancellation() to test instead of comparing manually.
+export type UserInput = string | null | undefined;
+
+export function isCancellation(input: UserInput): input is null | undefined {
+	return input == null;
+}
+
+// Minimal UI surface a provider's configure() helper is allowed to depend on.
+// Intentionally narrow so providers/ stays free of web-tools internals (no
+// circular import) and so the contract can grow deliberately if a future
+// provider needs more.
+export interface ProviderConfigUi {
+	input(label: string, placeholder: string): Promise<UserInput>;
+}
+
+// What the orchestrator hands to configure(): the provider's currently
+// persisted state (if any).
+export interface ProviderConfigCurrent {
+	baseUrl?: string;
+	apiKey?: string;
+}
+
+// What configure() returns for the orchestrator to merge into WebToolsConfig.
+// `null` apiKey = "leave unset"; absent baseUrl = "this provider has no URL
+// knob"; whole-result `null` = "user cancelled, do not persist".
+export interface ProviderConfigChange {
+	baseUrl?: string;
+	apiKey?: string | null;
+}
+
+// Per-provider metadata declared alongside each provider's class. Drives
+// generic dispatch in web-tools.ts so adding a new provider doesn't require
+// touching the orchestrator.
+//
+//   envVar          — the API-key env var (omit if the provider has no key)
+//   baseUrlEnvVar   — the URL env var (set for self-hosted providers)
+//   defaultBaseUrl  — fallback URL when neither env nor config supplies one
+//   configure       — interactive setup; if present, /web-search-config
+//                     dispatches here instead of the default single-key prompt
+export interface ProviderMeta {
+	name: string;
+	label: string;
+	envVar?: string;
+	baseUrlEnvVar?: string;
+	defaultBaseUrl?: string;
+	configure?(ui: ProviderConfigUi, current: ProviderConfigCurrent): Promise<ProviderConfigChange | null>;
+}

package/web-tools.ts

@@ -28,7 +28,7 @@ import { configPath, loadJsonConfig, saveJsonConfig, validateGuidanceFields } fr
 import { Type } from "typebox";
 import { createSearchProvider } from "./providers/factory.js";
 import { PROVIDERS } from "./providers/index.js";
-import type { SearchResult } from "./providers/types.js";
+import type { ProviderMeta, SearchProvider, SearchResult } from "./providers/types.js";
 
 // ---------------------------------------------------------------------------
 // Tunables and external surface
@@ -55,6 +55,12 @@ const UNSET_LABEL = "(not set)";
 
 const DEFAULT_PROVIDER_NAME = "brave";
 
+// Brave is the only provider whose key was historically stored at the top
+// level (config.apiKey) before the per-provider apiKeys map. The legacy
+// field is auto-migrated to apiKeys.brave on the next save by
+// /web-search-config (the dispatch deletes apiKey from the saved object).
+const LEGACY_TOP_LEVEL_KEY_PROVIDER = "brave";
+
 // ---------------------------------------------------------------------------
 // Config file persistence
 // ---------------------------------------------------------------------------
@@ -69,6 +75,7 @@ interface WebToolsGuidance {
 interface WebToolsConfig {
 	provider?: string;
 	apiKeys?: Record<string, string>;
+	baseUrls?: Record<string, string>;
 	apiKey?: string; // legacy — kept for backward compat
 	guidance?: WebToolsGuidance;
 }
@@ -112,19 +119,44 @@ function resolveProviderApiKey(providerName: string, config: WebToolsConfig): st
 	const meta = PROVIDERS.find((p) => p.name === providerName);
 	if (!meta) return undefined;
 
-	const envKey = process.env[meta.envVar]?.trim();
+	const envKey = meta.envVar ? process.env[meta.envVar]?.trim() : undefined;
 	if (envKey) return envKey;
 
 	const configKey = config.apiKeys?.[providerName]?.trim();
 	if (configKey) return configKey;
 
-	if (providerName === "brave") {
+	if (providerName === LEGACY_TOP_LEVEL_KEY_PROVIDER) {
 		return config.apiKey?.trim() || undefined;
 	}
 
 	return undefined;
 }
 
+// Generic per-provider base-URL resolution: env → config.baseUrls[name] →
+// meta.defaultBaseUrl → "". Providers without baseUrlEnvVar (hosted ones)
+// short-circuit to "". The orchestrator only calls this for providers that
+// declare baseUrlEnvVar, so the empty-string fallback is a safety net rather
+// than a runtime path.
+function resolveProviderBaseUrl(meta: ProviderMeta, config: WebToolsConfig): string {
+	if (!meta.baseUrlEnvVar) return "";
+	const envUrl = process.env[meta.baseUrlEnvVar]?.trim();
+	if (envUrl) return envUrl;
+	const configUrl = config.baseUrls?.[meta.name]?.trim();
+	if (configUrl) return configUrl;
+	return meta.defaultBaseUrl ?? "";
+}
+
+// Centralized instantiation: load active provider name + creds, build via
+// the factory. Called by both registerWebSearchTool and registerWebFetchTool.
+function instantiateActiveProvider(config: WebToolsConfig): { providerName: string; provider: SearchProvider } {
+	const providerName = config.provider ?? DEFAULT_PROVIDER_NAME;
+	const apiKey = resolveProviderApiKey(providerName, config);
+	const meta = PROVIDERS.find((p) => p.name === providerName);
+	const baseUrl = meta?.baseUrlEnvVar ? resolveProviderBaseUrl(meta, config) : undefined;
+	const provider = createSearchProvider(providerName, { apiKey: apiKey ?? "", baseUrl });
+	return { providerName, provider };
+}
+
 function maskApiKey(key: string | undefined): string {
 	if (!key) return UNSET_LABEL;
 	const head = key.slice(0, API_KEY_MASK_VISIBLE_CHARS);
@@ -261,9 +293,7 @@ export function registerWebSearchTool(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
 			const maxResults = clampSearchResultCount(params.max_results);
 			const config = loadConfig();
-			const providerName = config.provider ?? DEFAULT_PROVIDER_NAME;
-			const apiKey = resolveProviderApiKey(providerName, config);
-			const provider = createSearchProvider(providerName, apiKey ?? "");
+			const { providerName, provider } = instantiateActiveProvider(config);
 
 			onUpdate?.({
 				content: [{ type: "text", text: `Searching ${provider.label} for: "${params.query}"...` }],
@@ -351,9 +381,7 @@ export function registerWebFetchTool(pi: ExtensionAPI): void {
 			});
 
 			const config = loadConfig();
-			const providerName = config.provider ?? DEFAULT_PROVIDER_NAME;
-			const apiKey = resolveProviderApiKey(providerName, config);
-			const provider = createSearchProvider(providerName, apiKey ?? "");
+			const { provider } = instantiateActiveProvider(config);
 
 			const { text: bodyText, title, contentType, contentLength } = await provider.fetch(url, raw, signal);
 
@@ -432,15 +460,27 @@ function formatShowConfigMessage(current: WebToolsConfig): string {
 	lines.push(`  active provider: ${providerName}`);
 
 	for (const meta of PROVIDERS) {
-		const envKey = process.env[meta.envVar]?.trim();
+		const envKey = meta.envVar ? process.env[meta.envVar]?.trim() : undefined;
 		const configKey = current.apiKeys?.[meta.name]?.trim();
-		const legacyKey = meta.name === "brave" ? current.apiKey?.trim() : undefined;
+		const legacyKey = meta.name === LEGACY_TOP_LEVEL_KEY_PROVIDER ? current.apiKey?.trim() : undefined;
 		const resolved = envKey ?? configKey ?? legacyKey;
 		lines.push(
 			`  ${meta.name}: ${maskApiKey(resolved)} (env: ${maskApiKey(envKey)}, config: ${maskApiKey(configKey ?? legacyKey)})`,
 		);
 	}
 
+	// One URL line per provider that declares baseUrlEnvVar. Today this is
+	// only SearXNG, but a second self-hosted provider lands without touching
+	// this loop.
+	for (const meta of PROVIDERS) {
+		if (!meta.baseUrlEnvVar) continue;
+		const envUrl = process.env[meta.baseUrlEnvVar]?.trim();
+		const configUrl = current.baseUrls?.[meta.name]?.trim();
+		const resolvedUrl = envUrl || configUrl || meta.defaultBaseUrl || "";
+		const urlSource = envUrl ? "env" : configUrl ? "config" : "default";
+		lines.push(`  ${meta.name} url: ${resolvedUrl} (source: ${urlSource})`);
+	}
+
 	return lines.join("\n");
 }
 
@@ -465,7 +505,15 @@ export function registerWebSearchConfigCommand(pi: ExtensionAPI): void {
 				...PROVIDERS.filter((p) => p.name === activeProvider),
 				...PROVIDERS.filter((p) => p.name !== activeProvider),
 			];
-			const hasKey = (p: (typeof PROVIDERS)[number]) => resolveProviderApiKey(p.name, current) !== undefined;
+			const hasKey = (p: ProviderMeta) => {
+				// Self-hosted providers are "configured" once they have a base URL
+				// (env or config). The bare default URL doesn't count — it's just a
+				// hint that the user hasn't touched the setting yet.
+				if (p.baseUrlEnvVar) {
+					return Boolean(process.env[p.baseUrlEnvVar]?.trim() || current.baseUrls?.[p.name]?.trim());
+				}
+				return resolveProviderApiKey(p.name, current) !== undefined;
+			};
 			const labelOf = (p: (typeof PROVIDERS)[number]) => {
 				const markers: string[] = [];
 				if (p.name === activeProvider) markers.push("✓");
@@ -490,8 +538,46 @@ export function registerWebSearchConfigCommand(pi: ExtensionAPI): void {
 			}
 			const selectedProvider = selectedMeta.name;
 
+			// Providers that declare a `configure` callback own their prompt flow
+			// (e.g. SearXNG: URL prompt then optional Bearer key). The orchestrator
+			// dispatches generically and owns persistence + notifications.
+			if (selectedMeta.configure) {
+				const result = await selectedMeta.configure(ctx.ui, {
+					baseUrl: current.baseUrls?.[selectedProvider],
+					apiKey: current.apiKeys?.[selectedProvider],
+				});
+				if (!result) {
+					ctx.ui.notify("Web search config unchanged", "info");
+					return;
+				}
+				const toSave: WebToolsConfig = {
+					...current,
+					provider: selectedProvider,
+					...(result.baseUrl !== undefined && {
+						baseUrls: { ...current.baseUrls, [selectedProvider]: result.baseUrl },
+					}),
+					...(result.apiKey ? { apiKeys: { ...current.apiKeys, [selectedProvider]: result.apiKey } } : {}),
+				};
+				delete (toSave as { apiKey?: string }).apiKey;
+				if (!saveConfig(toSave)) {
+					ctx.ui.notify(
+						`Failed to save ${selectedMeta.label} config to ${CONFIG_PATH} — disk write failed`,
+						"error",
+					);
+					return;
+				}
+				ctx.ui.notify(
+					result.baseUrl
+						? `Saved ${selectedMeta.label} config (url: ${result.baseUrl}) to ${CONFIG_PATH}`
+						: `Saved ${selectedMeta.label} config to ${CONFIG_PATH}`,
+					"info",
+				);
+				return;
+			}
+
 			const existingKey =
-				current.apiKeys?.[selectedProvider] ?? (selectedProvider === "brave" ? current.apiKey : undefined);
+				current.apiKeys?.[selectedProvider] ??
+				(selectedProvider === LEGACY_TOP_LEVEL_KEY_PROVIDER ? current.apiKey : undefined);
 			const input = await ctx.ui.input(
 				`${selectedMeta.label} API key`,
 				existingKey ? `Press Enter to keep current (${maskApiKey(existingKey)}), or type new key` : "...",