@juicesharp/rpiv-web-tools 1.12.0 → 1.14.0

package/README.md

@@ -8,18 +8,31 @@
   </a>
 </div>
 
-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.
+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/), [Ollama](https://ollama.com)), plus `/web-tools` 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)
 
+## Providers
+
+Pick one as the active backend; switch any time without losing the others' keys.
+
+| Provider | Env var | Signup | Fetch mode | Notes |
+|---|---|---|---|---|
+| Brave | `BRAVE_SEARCH_API_KEY` | [brave.com/search/api](https://brave.com/search/api/) | raw HTTP → htmlToText, `raw: true` available | default |
+| Tavily | `TAVILY_API_KEY` | [tavily.com](https://tavily.com) | native extraction (plain text) | |
+| Serper | `SERPER_API_KEY` | [serper.dev](https://serper.dev) | raw HTTP → htmlToText, `raw: true` available | |
+| Exa | `EXA_API_KEY` | [exa.ai](https://exa.ai) | native extraction (plain text) | |
+| Jina | `JINA_API_KEY` | [jina.ai/reader](https://jina.ai/reader) | native extraction (markdown) | |
+| Firecrawl | `FIRECRAWL_API_KEY` | [firecrawl.dev](https://firecrawl.dev) | native extraction (markdown) | |
+| SearXNG | `SEARXNG_URL` (+ optional `SEARXNG_API_KEY`) | self-hosted | raw HTTP → htmlToText, `raw: true` available | see [§SearXNG](#searxng-self-hosted) |
+| Ollama | `OLLAMA_HOST` / `OLLAMA_API_KEY` | local or [ollama.com](https://ollama.com) | native extraction | see [§Ollama](#ollama-local-or-cloud) |
+
 ## Features
 
-- **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).
+- **Read any URL** - fetch http/https pages with HTML-to-text extraction, or get the raw response with `raw: true` (honoured by Brave/Serper/SearXNG; extraction providers — Tavily/Exa/Jina/Firecrawl/Ollama — 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`).
-- **Interactive setup** - `/web-search-config` lists providers (active one first, configured ones marked) and writes to `~/.config/rpiv-web-tools/config.json` (chmod 0600); per-provider env vars also work and take precedence over persisted keys.
+- **Interactive setup** - `/web-tools` lists providers (active one first, configured ones marked) and writes to `~/.config/rpiv-web-tools/config.json` (chmod 0600); per-provider env vars also work and take precedence over persisted keys.
 
 ## Install
 
@@ -34,7 +47,7 @@ Then restart your Pi session.
 - **`web_search`** - query the active provider's search API and return titled snippets.
   1–10 results per call.
 - **`web_fetch`** - fetch an http/https URL through the active provider's content path
-  (raw HTTP+htmlToText for Brave/Serper; native extraction for Tavily/Exa/Jina/Firecrawl),
+  (raw HTTP+htmlToText for Brave/Serper/SearXNG; native extraction for Tavily/Exa/Jina/Firecrawl/Ollama),
   truncate large responses with a temp-file spill for the full content.
 
 ### Schema - `web_search`
@@ -53,7 +66,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" | "searxng",
+    backend: "brave" | "tavily" | "serper" | "exa" | "jina" | "firecrawl" | "searxng" | "ollama",
     resultCount: number,
     results?: Array<{ title: string, url: string, snippet: string }>,
   }
@@ -91,7 +104,7 @@ Throws on invalid URL, non-http(s) protocol, private/loopback hostnames (SSRF gu
 
 ## Commands
 
-- **`/web-search-config`** - pick the active provider and set its API key interactively.
+- **`/web-tools`** - pick the active provider and set its API key interactively.
   Providers already configured show `(configured)`; the active one is listed first with a `✓`.
   Pressing Enter on an empty input keeps the existing key for the chosen provider while
   persisting the provider switch. Pass `--show` to see all per-provider keys (masked) and env var status.
@@ -100,11 +113,11 @@ 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`, `FIRECRAWL_API_KEY`, or `SEARXNG_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`, `SEARXNG_API_KEY`, or `OLLAMA_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.
+The active provider is `config.provider` (set by `/web-tools`); falls back to `brave` if absent.
 
 ## SearXNG (self-hosted)
 
@@ -116,7 +129,7 @@ export SEARXNG_URL=http://localhost:8080
 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.
+Resolution order for the URL: `SEARXNG_URL` env var → `baseUrls.searxng` in `~/.config/rpiv-web-tools/config.json` → default `http://localhost:8080`. `/web-tools` 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.
 
@@ -143,6 +156,39 @@ curl -sf 'http://localhost:8080/search?q=hello&format=json' | jq '.results | len
 
 `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`.
 
+## Ollama (local or cloud)
+
+Ollama provides web search and fetch as built-in capabilities — no third-party API key needed for local usage. For cloud access, an API key is required.
+
+### Local Ollama
+
+Just run Ollama locally and it works out of the box:
+
+```bash
+ollama serve
+```
+
+No API key needed. The provider talks to `http://localhost:11434` by default.
+
+### Ollama Cloud
+
+For cloud access via [Ollama Cloud](https://ollama.com), set the base URL and API key:
+
+```bash
+export OLLAMA_HOST=https://ollama.com
+export OLLAMA_API_KEY=your_api_key   # generate at https://ollama.com/settings/keys
+```
+
+Or configure interactively via `/web-tools` — select "Ollama" and enter the URL and key.
+
+Resolution order:
+- **Base URL**: `OLLAMA_HOST` env var → `baseUrls.ollama` in config → default `http://localhost:11434`
+- **API key**: `OLLAMA_API_KEY` env var → `apiKeys.ollama` in config (optional for local, required for cloud)
+
+The provider automatically uses the correct API paths:
+- **Local** (`localhost`, `127.0.0.1`, `0.0.0.0`): `/api/experimental/web_search` and `/api/experimental/web_fetch`
+- **Cloud** (any other host): `/api/web_search` and `/api/web_fetch`
+
 ## 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`):

package/index.ts

@@ -2,7 +2,7 @@
  * rpiv-web-tools — Pi extension
  *
  * Registers the `web_search` and `web_fetch` tools, plus the
- * `/web-search-config` slash command. Body lives in `web-tools.ts`.
+ * `/web-tools` slash command. Body lives in `web-tools.ts`.
  *
  * Config persists at ~/.config/rpiv-web-tools/config.json. Per-provider env
  * vars (e.g. BRAVE_SEARCH_API_KEY, TAVILY_API_KEY) win over the config file.

package/package.json

@@ -1,21 +1,30 @@
 {
 	"name": "@juicesharp/rpiv-web-tools",
-	"version": "1.12.0",
-	"description": "Pi extension. Web search and fetch for the model with pluggable providers (Brave, Tavily, Serper, Exa, Jina, Firecrawl).",
+	"version": "1.14.0",
+	"description": "Pi extension. Web search and fetch for the model with pluggable providers (Brave, Tavily, Serper, Exa, Jina, Firecrawl, SearXNG, Ollama).",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
 		"rpiv",
 		"web-search",
+		"web-fetch",
 		"search",
 		"fetch",
 		"scrape",
+		"web-scraping",
+		"ai",
+		"llm",
+		"agent",
+		"local",
+		"self-hosted",
 		"brave",
 		"tavily",
 		"serper",
 		"exa",
 		"jina",
-		"firecrawl"
+		"firecrawl",
+		"searxng",
+		"ollama"
 	],
 	"type": "module",
 	"license": "MIT",
@@ -48,7 +57,7 @@
 		]
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^1.12.0"
+		"@juicesharp/rpiv-config": "^1.14.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",

package/providers/brave.ts

@@ -30,7 +30,7 @@ export class BraveProvider implements SearchProvider {
 
 	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const url = new URL(BRAVE_SEARCH_API_URL);

package/providers/exa.ts

@@ -39,7 +39,7 @@ export class ExaProvider implements SearchProvider {
 
 	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const res = await fetch(EXA_API_URL, {
@@ -69,7 +69,7 @@ export class ExaProvider implements SearchProvider {
 
 	async fetch(url: string, _raw: boolean, signal?: AbortSignal): Promise<FetchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const res = await fetch(EXA_CONTENTS_API_URL, {

package/providers/factory.ts

@@ -2,6 +2,7 @@ import { BraveProvider } from "./brave.js";
 import { ExaProvider } from "./exa.js";
 import { FirecrawlProvider } from "./firecrawl.js";
 import { JinaProvider } from "./jina.js";
+import { OllamaProvider } from "./ollama.js";
 import { SearxngProvider } from "./searxng.js";
 import { SerperProvider } from "./serper.js";
 import { TavilyProvider } from "./tavily.js";
@@ -29,6 +30,8 @@ export function createSearchProvider(name: string, creds: ProviderCredentials):
 			return new FirecrawlProvider(apiKey);
 		case "searxng":
 			return new SearxngProvider({ apiKey: creds.apiKey, baseUrl: creds.baseUrl ?? "" });
+		case "ollama":
+			return new OllamaProvider({ apiKey: creds.apiKey, baseUrl: creds.baseUrl ?? "" });
 		default:
 			throw new Error(`Unknown search provider: "${name}"`);
 	}

package/providers/firecrawl.ts

@@ -52,7 +52,7 @@ export class FirecrawlProvider implements SearchProvider {
 
 	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const res = await fetch(`${FIRECRAWL_API_URL}/search`, {
@@ -79,7 +79,7 @@ export class FirecrawlProvider implements SearchProvider {
 
 	async fetch(url: string, _raw: boolean, signal?: AbortSignal): Promise<FetchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const res = await fetch(`${FIRECRAWL_API_URL}/scrape`, {

package/providers/index.ts

@@ -2,6 +2,7 @@ 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 { OLLAMA_PROVIDER_META } from "./ollama.js";
 import { SEARXNG_PROVIDER_META } from "./searxng.js";
 import { SERPER_PROVIDER_META } from "./serper.js";
 import { TAVILY_PROVIDER_META } from "./tavily.js";
@@ -12,6 +13,14 @@ export { EXA_API_KEY_ENV_VAR, EXA_PROVIDER_META, ExaProvider } from "./exa.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 {
+	configureOllama,
+	OLLAMA_API_KEY_ENV_VAR,
+	OLLAMA_DEFAULT_URL,
+	OLLAMA_HOST_ENV_VAR,
+	OLLAMA_PROVIDER_META,
+	OllamaProvider,
+} from "./ollama.js";
 export {
 	configureSearxng,
 	SEARXNG_API_KEY_ENV_VAR,
@@ -48,4 +57,5 @@ export const PROVIDERS: readonly ProviderMeta[] = [
 	JINA_PROVIDER_META,
 	FIRECRAWL_PROVIDER_META,
 	SEARXNG_PROVIDER_META,
+	OLLAMA_PROVIDER_META,
 ];

package/providers/jina.ts

@@ -42,7 +42,7 @@ export class JinaProvider implements SearchProvider {
 
 	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		// Jina s.jina.ai uses the URL path for the query. The `num` query param
@@ -73,7 +73,7 @@ export class JinaProvider implements SearchProvider {
 
 	async fetch(url: string, _raw: boolean, signal?: AbortSignal): Promise<FetchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		// No Accept header = Reader returns markdown by default. Setting

package/providers/ollama.ts

@@ -0,0 +1,274 @@
+import {
+	type FetchResponse,
+	isCancellation,
+	type ProviderConfigChange,
+	type ProviderConfigCurrent,
+	type ProviderConfigUi,
+	type ProviderMeta,
+	type SearchProvider,
+	type SearchResponse,
+	type SearchResult,
+} from "./types.js";
+
+export const OLLAMA_API_KEY_ENV_VAR = "OLLAMA_API_KEY";
+export const OLLAMA_HOST_ENV_VAR = "OLLAMA_HOST";
+export const OLLAMA_DEFAULT_URL = "http://localhost:11434";
+
+// Ollama API paths — cloud (ollama.com) uses stable /api/... paths,
+// local instances use /api/experimental/... (at least through v0.24).
+const CLOUD_SEARCH_PATH = "/api/web_search";
+const CLOUD_FETCH_PATH = "/api/web_fetch";
+const LOCAL_SEARCH_PATH = "/api/experimental/web_search";
+const LOCAL_FETCH_PATH = "/api/experimental/web_fetch";
+
+function isLocalHost(baseUrl: string): boolean {
+	try {
+		const hostname = new URL(baseUrl).hostname;
+		return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname === "[::1]";
+	} catch {
+		return true; // default to local paths if URL is somehow invalid
+	}
+}
+
+// Number of leading + trailing characters preserved when masking an API key
+// in the config prompt. Mirrors API_KEY_MASK_VISIBLE_CHARS in web-tools.ts.
+const MASK_VISIBLE_CHARS = 4;
+
+export const OLLAMA_PROVIDER_META: ProviderMeta = {
+	name: "ollama",
+	label: "Ollama",
+	envVar: OLLAMA_API_KEY_ENV_VAR,
+	baseUrlEnvVar: OLLAMA_HOST_ENV_VAR,
+	defaultBaseUrl: OLLAMA_DEFAULT_URL,
+	configure: (ui, current) => configureOllama(ui, current),
+};
+
+// ---------------------------------------------------------------------------
+// Vendor response types (file-private)
+// ---------------------------------------------------------------------------
+
+interface OllamaRawSearchResult {
+	title?: string;
+	url?: string;
+	content?: string;
+}
+
+interface OllamaSearchResponse {
+	results?: OllamaRawSearchResult[];
+}
+
+interface OllamaFetchResponse {
+	title?: string;
+	content?: string;
+	links?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+
+function normalizeOllamaResults(raw: OllamaSearchResponse): SearchResult[] {
+	return (raw.results ?? []).map((r) => ({
+		title: r.title ?? "",
+		url: r.url ?? "",
+		snippet: r.content ?? "",
+	}));
+}
+
+// ---------------------------------------------------------------------------
+// URL helpers
+// ---------------------------------------------------------------------------
+
+function stripTrailingSlashes(url: string): string {
+	return url.replace(/\/+$/, "");
+}
+
+function assertHttpUrl(url: string): void {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new Error(`${OLLAMA_HOST_ENV_VAR} is not a valid URL (got: ${url})`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error(
+			`${OLLAMA_HOST_ENV_VAR} must use http:// or https:// (got: ${parsed.protocol.replace(":", "")}://)`,
+		);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Network error handling
+// ---------------------------------------------------------------------------
+
+// Node's fetch wraps ECONNREFUSED in a TypeError. Detect the cause chain
+// and re-throw with an actionable hint.
+function isConnectionRefused(error: unknown): boolean {
+	if (error instanceof TypeError) {
+		const cause = (error as unknown as { cause?: { code?: string } }).cause;
+		return cause?.code === "ECONNREFUSED";
+	}
+	return false;
+}
+
+function connectionRefusedError(host: string): Error {
+	return new Error(`Could not connect to Ollama at ${host}. Make sure Ollama is running (ollama serve).`);
+}
+
+// ---------------------------------------------------------------------------
+// Provider class
+// ---------------------------------------------------------------------------
+
+interface OllamaProviderOptions {
+	apiKey?: string;
+	baseUrl: string;
+}
+
+export class OllamaProvider implements SearchProvider {
+	readonly name = "ollama";
+	readonly label = "Ollama";
+	readonly envVar = OLLAMA_API_KEY_ENV_VAR;
+
+	private readonly apiKey?: string;
+	private readonly baseUrl: string;
+	private readonly local: boolean;
+
+	constructor(options: OllamaProviderOptions) {
+		this.apiKey = options.apiKey?.trim() || undefined;
+		const trimmed = stripTrailingSlashes(options.baseUrl?.trim() ?? "");
+		if (trimmed) assertHttpUrl(trimmed);
+		this.baseUrl = trimmed;
+		this.local = isLocalHost(trimmed);
+	}
+
+	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
+		this.requireBaseUrl();
+		const path = this.local ? LOCAL_SEARCH_PATH : CLOUD_SEARCH_PATH;
+		try {
+			const res = await fetch(`${this.baseUrl}${path}`, {
+				method: "POST",
+				headers: this.buildHeaders(),
+				body: JSON.stringify({ query, max_results: maxResults }),
+				signal,
+			});
+			if (!res.ok) throw await this.formatError("Search", res);
+			const raw = (await res.json()) as OllamaSearchResponse;
+			return { query, results: normalizeOllamaResults(raw) };
+		} catch (error) {
+			if (isConnectionRefused(error)) throw connectionRefusedError(this.baseUrl);
+			throw error;
+		}
+	}
+
+	async fetch(url: string, _raw: boolean, signal?: AbortSignal): Promise<FetchResponse> {
+		this.requireBaseUrl();
+		const path = this.local ? LOCAL_FETCH_PATH : CLOUD_FETCH_PATH;
+		try {
+			const res = await fetch(`${this.baseUrl}${path}`, {
+				method: "POST",
+				headers: this.buildHeaders(),
+				body: JSON.stringify({ url }),
+				signal,
+			});
+			if (!res.ok) throw await this.formatError("Fetch", res);
+			const data = (await res.json()) as OllamaFetchResponse;
+			if (!data.content) {
+				throw new Error(`${this.label} Fetch API error: no content returned for ${url}`);
+			}
+			return {
+				text: data.content,
+				title: data.title || undefined,
+				contentType: "text/plain",
+			};
+		} catch (error) {
+			if (isConnectionRefused(error)) throw connectionRefusedError(this.baseUrl);
+			throw error;
+		}
+	}
+
+	private requireBaseUrl(): void {
+		if (!this.baseUrl) {
+			throw new Error(`${OLLAMA_HOST_ENV_VAR} is not set. Run /web-tools to configure, or export the env var.`);
+		}
+	}
+
+	private buildHeaders(): Record<string, string> {
+		const headers: Record<string, string> = { "Content-Type": "application/json" };
+		if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+		return headers;
+	}
+
+	private async formatError(label: string, res: Response): Promise<Error> {
+		const body = await res.text();
+		const hint = hintForStatus(res.status);
+		return new Error(`${this.label} ${label} API error (${res.status})${hint}: ${body}`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Status hints
+// ---------------------------------------------------------------------------
+
+function hintForStatus(status: number): string {
+	if (status === 401) {
+		return " (run `ollama signin` to authenticate)";
+	}
+	if (status === 404) {
+		return " (the Ollama instance may not support web search; ensure you are running a recent version)";
+	}
+	return "";
+}
+
+// ---------------------------------------------------------------------------
+// /web-tools helper
+// ---------------------------------------------------------------------------
+
+function maskKey(key: string): string {
+	const head = key.slice(0, MASK_VISIBLE_CHARS);
+	const tail = key.slice(-MASK_VISIBLE_CHARS);
+	return `${head}...${tail}`;
+}
+
+async function promptForBaseUrl(ui: ProviderConfigUi, current: string | undefined): Promise<string | undefined> {
+	const existing = current?.trim();
+	const input = await ui.input(
+		"Ollama base URL",
+		existing
+			? `Press Enter to keep current (${existing}), or type new URL`
+			: `Press Enter for default (${OLLAMA_DEFAULT_URL}), or type instance URL`,
+	);
+	if (isCancellation(input)) return undefined;
+	return input.trim() || existing || OLLAMA_DEFAULT_URL;
+}
+
+async function promptForOptionalKey(
+	ui: ProviderConfigUi,
+	current: string | undefined,
+): Promise<string | null | undefined> {
+	const existing = current?.trim() || undefined;
+	const input = await ui.input(
+		"Ollama API key (optional — for direct cloud access; local Ollama authenticates via `ollama signin`)",
+		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 Ollama base URL and optional API key.
+ * Returns `null` if the user cancels at either prompt.
+ */
+export async function configureOllama(
+	ui: ProviderConfigUi,
+	current: ProviderConfigCurrent,
+): Promise<ProviderConfigChange | 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/searxng.ts

@@ -144,9 +144,7 @@ export class SearxngProvider implements SearchProvider {
 
 	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.`,
-			);
+			throw new Error(`${SEARXNG_URL_ENV_VAR} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 	}
 
@@ -176,7 +174,7 @@ export class SearxngProvider implements SearchProvider {
 }
 
 // ---------------------------------------------------------------------------
-// /web-search-config helper — SearXNG branch
+// /web-tools helper — SearXNG branch
 // ---------------------------------------------------------------------------
 // SEARXNG_PROVIDER_META.configure wires configureSearxng() in; the orchestrator
 // dispatches generically through ProviderMeta.configure without naming

package/providers/serper.ts

@@ -37,7 +37,7 @@ export class SerperProvider implements SearchProvider {
 
 	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const res = await fetch(SERPER_API_URL, {

package/providers/tavily.ts

@@ -48,7 +48,7 @@ export class TavilyProvider implements SearchProvider {
 
 	async search(query: string, maxResults: number, signal?: AbortSignal): Promise<SearchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		const res = await fetch(TAVILY_API_URL, {
@@ -73,7 +73,7 @@ export class TavilyProvider implements SearchProvider {
 
 	async fetch(url: string, _raw: boolean, signal?: AbortSignal): Promise<FetchResponse> {
 		if (!this.apiKey) {
-			throw new Error(`${this.envVar} is not set. Run /web-search-config to configure, or export the env var.`);
+			throw new Error(`${this.envVar} is not set. Run /web-tools to configure, or export the env var.`);
 		}
 
 		// Bearer header per current Tavily docs. Existing search() above still

package/providers/types.ts

@@ -67,7 +67,7 @@ export interface ProviderConfigChange {
 //   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
+//   configure       — interactive setup; if present, /web-tools
 //                     dispatches here instead of the default single-key prompt
 export interface ProviderMeta {
 	name: string;

package/web-tools.ts

@@ -2,7 +2,7 @@
  * rpiv-web-tools — body
  *
  * Provides `web_search` and `web_fetch` tools backed by configurable search
- * providers (Brave, Tavily, Serper, Exa), plus the `/web-search-config`
+ * providers (Brave, Tavily, Serper, Exa), plus the `/web-tools`
  * slash command for provider and API key configuration.
  *
  * API key resolution precedence per provider (first wins):
@@ -49,7 +49,7 @@ const CONFIG_PATH = configPath("rpiv-web-tools");
 
 const SUPPORTED_HTTP_PROTOCOLS = new Set(["http:", "https:"]);
 
-const WEB_SEARCH_CONFIG_COMMAND_NAME = "web-search-config";
+const WEB_TOOLS_COMMAND_NAME = "web-tools";
 const SHOW_FLAG = "--show";
 const UNSET_LABEL = "(not set)";
 
@@ -58,7 +58,7 @@ 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).
+// /web-tools (the dispatch deletes apiKey from the saved object).
 const LEGACY_TOP_LEVEL_KEY_PROVIDER = "brave";
 
 // ---------------------------------------------------------------------------
@@ -100,7 +100,7 @@ export const DEFAULT_WEB_SEARCH_GUIDELINES: string[] = [
 	'Use the current year from "Current date:" in your context when searching for recent information or documentation.',
 	'After answering using search results, include a "Sources:" section listing relevant URLs as markdown hyperlinks: [Title](URL). Never skip this.',
 	"Domain filtering is supported to include or block specific websites.",
-	"If no API key is configured, ask the user to run /web-search-config before proceeding.",
+	"If no API key is configured, ask the user to run /web-tools before proceeding.",
 ];
 
 export const DEFAULT_WEB_FETCH_SNIPPET = "Fetch and read content from a specific URL";
@@ -450,7 +450,7 @@ function renderFetchedContentPreview(content: string, theme: Theme): string {
 }
 
 // ---------------------------------------------------------------------------
-// /web-search-config command
+// /web-tools command
 // ---------------------------------------------------------------------------
 
 function formatShowConfigMessage(current: WebToolsConfig): string {
@@ -485,11 +485,11 @@ function formatShowConfigMessage(current: WebToolsConfig): string {
 }
 
 export function registerWebSearchConfigCommand(pi: ExtensionAPI): void {
-	pi.registerCommand(WEB_SEARCH_CONFIG_COMMAND_NAME, {
+	pi.registerCommand(WEB_TOOLS_COMMAND_NAME, {
 		description: "Configure the search provider and API key used by web_search",
 		handler: async (args, ctx) => {
 			if (!ctx.hasUI) {
-				ctx.ui?.notify?.(`/${WEB_SEARCH_CONFIG_COMMAND_NAME} requires interactive mode`, "error");
+				ctx.ui?.notify?.(`/${WEB_TOOLS_COMMAND_NAME} requires interactive mode`, "error");
 				return;
 			}