@pi-unipi/web-api 2.1.2 → 2.2.0

package/README.md

@@ -2,7 +2,22 @@
 
 Web search, page reading, and content summarization for the agent. The read path uses a local smart-fetch engine by default — free, no API key, browser-grade TLS fingerprinting that bypasses Cloudflare.
 
-Paid providers (SerpAPI, Tavily, Firecrawl, Perplexity) are available as fallbacks. DuckDuckGo and Jina work out of the box for search.
+[wigolo](https://github.com/KnockOutEZ/wigolo) is the default search and read provider when installed — a local-first engine with multi-engine search, rank fusion and on-device reranking, at $0/query with no API key. Paid providers (SerpAPI, Tavily, Firecrawl, Perplexity) are available as fallbacks, and DuckDuckGo and Jina work out of the box.
+
+### wigolo (optional, recommended)
+
+wigolo is ranked first for both search and read but is **not bundled** — it is an
+AGPL-licensed project while UniPi is MIT, so it is an optional dependency loaded
+at runtime only if you installed it. Set it up once:
+
+```bash
+npm install -g wigolo
+npx wigolo init      # downloads the browser engine + on-device models (~1.5 GB)
+npx wigolo doctor    # verify
+```
+
+Until then, web calls fall through automatically to the next-ranked provider, so
+nothing breaks if you skip it. Disable it entirely in `/unipi:web-settings`.
 
 ## Commands
 
@@ -39,7 +54,7 @@ The footer and info-screen don't display web-api data — it's a tool package, n
 web_search(query: "TypeScript generics")
 
 # Use specific provider
-web_search(query: "latest AI research", source: 4)  # Tavily
+web_search(query: "latest AI research", source: 5)  # Tavily
 ```
 
 ### multi_web_content_read
@@ -51,7 +66,7 @@ multi_web_content_read(url: "https://example.com/article")
 # Batch URLs
 multi_web_content_read(url: ["https://example.com/a", "https://example.com/b"])
 
-# Provider fallback (Jina Reader)
+# Provider fallback (wigolo)
 multi_web_content_read(url: "https://example.com/article", source: 1)
 
 # Custom options
@@ -83,20 +98,22 @@ Outputs clean markdown with metadata (title, author, site, word count). Supports
 
 | Provider | Rank | Cost | API Key |
 |----------|------|------|---------|
-| DuckDuckGo | 1 | Free | No |
-| Jina AI Search | 2 | Freemium | Optional |
-| SerpAPI | 3 | Paid | Required |
-| Tavily | 4 | Paid | Required |
-| Perplexity | 5 | Paid | Required |
+| wigolo (local) | 1 | Free | No |
+| DuckDuckGo | 2 | Free | No |
+| Jina AI Search | 3 | Freemium | Optional |
+| SerpAPI | 4 | Paid | Required |
+| Tavily | 5 | Paid | Required |
+| Perplexity | 6 | Paid | Required |
 
 ### Read
 
 | Provider | Rank | Cost | API Key |
 |----------|------|------|---------|
 | Smart-Fetch Engine | 0 | Free | No |
-| Jina AI Reader | 1 | Freemium | Optional |
-| Firecrawl | 2 | Paid | Required |
-| Perplexity | 3 | Paid | Required |
+| wigolo (local) | 1 | Free | No |
+| Jina AI Reader | 2 | Freemium | Optional |
+| Firecrawl | 3 | Paid | Required |
+| Perplexity | 4 | Paid | Required |
 
 ### Summarize
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/web-api",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Web search, read, and summarize tools with provider-based backend selection for Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -31,13 +31,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "2.1.2",
+    "@pi-unipi/core": "2.2.0",
     "defuddle": "^0.18.1",
     "linkedom": "^0.18.12",
     "lodash": "^4.17.21",
     "mime-types": "^2.1.35",
     "wreq-js": "^2.3.0"
   },
+  "optionalDependencies": {
+    "wigolo-sdk": "^0.2.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",
     "@earendil-works/pi-tui": "^0.80.0",
@@ -48,6 +51,9 @@
     "@types/mime-types": "^3.0.1",
     "@types/node": "^25.6.0"
   },
+  "scripts": {
+    "test": "npx tsx --test tests/**/*.test.ts"
+  },
   "pi": {
     "extensions": [],
     "skills": [],

package/skills/web/SKILL.md

@@ -21,7 +21,7 @@ Search the web for information. Lower `source` = simpler/cheaper providers.
 **Examples:**
 ```
 web_search(query: "TypeScript generics tutorial")
-web_search(query: "latest AI research", source: 4)  # Use Tavily
+web_search(query: "latest AI research", source: 5)  # Use Tavily
 ```
 
 ## multi_web_content_read
@@ -87,25 +87,51 @@ web_llm_summarize(url: "https://example.com/research", prompt: "Extract key find
 - Specify `source` number for specific provider
 - If provider unavailable, tool throws descriptive error
 
+**Auto-selection falls through on failure.** With `source` omitted, a failing
+provider is skipped and the next-ranked one is tried, so an uninitialized
+wigolo never blocks a search. With an explicit `source`, the choice is
+respected and the error is reported instead.
+
 ### Provider Rankings
 
 **Search providers:**
-1. DuckDuckGo (free)
-2. Jina AI Search (freemium)
-3. SerpAPI (paid)
-4. Tavily (paid)
-5. Perplexity (paid)
+1. wigolo (free, local) — default
+2. DuckDuckGo (free)
+3. Jina AI Search (freemium)
+4. SerpAPI (paid)
+5. Tavily (paid)
+6. Perplexity (paid)
 
 **Read providers:**
 0. **Smart-Fetch Engine** (free, local) — default
-1. Jina AI Reader (freemium)
-2. Firecrawl (paid)
-3. Perplexity (paid)
+1. wigolo (free, local)
+2. Jina AI Reader (freemium)
+3. Firecrawl (paid)
+4. Perplexity (paid)
 
 **Summarize providers:**
 1. Perplexity (paid)
 2. LLM Summarize (uses pi's LLM)
 
+## wigolo
+
+[wigolo](https://github.com/KnockOutEZ/wigolo) is a local-first web engine:
+multi-engine search (18 direct adapters) with rank fusion and on-device
+reranking, plus a tiered fetch router that escalates to a headless browser on
+anti-bot challenges. No API key, nothing leaves the machine, $0 per query.
+
+It is **not bundled** — wigolo is AGPL-licensed and UniPi is MIT, so it is an
+optional dependency loaded at runtime only when the user installed it:
+
+```bash
+npm install -g wigolo && npx wigolo init
+```
+
+If it is missing or uninitialized, the provider raises an actionable error and
+auto-selection falls through to the next provider. Never tell the user wigolo
+is broken — tell them to run `npx wigolo init`, or to disable it in
+`/unipi:web-settings`.
+
 ## Smart-Fetch Engine
 
 The smart-fetch engine is a local content extraction pipeline:
@@ -127,6 +153,7 @@ The smart-fetch engine is a local content extraction pipeline:
 ## Cost Awareness
 
 - **Smart-Fetch Engine:** Free (read only, no API key)
+- **wigolo:** Free (search + read, local, no API key) — prefer this
 - **DuckDuckGo:** Free (search only)
 - **Jina:** Freemium (search + read)
 - **SerpAPI/Tavily:** Paid (search)

package/src/index.ts

@@ -19,6 +19,8 @@ import { registerWebCommands, WEB_COMMANDS } from "./commands.js";
 import { webCache } from "./cache.js";
 import { loadConfig, loadSmartFetchSettings } from "./settings.js";
 import { checkDependencies } from "./engine/dependencies.js";
+import { closeWigoloClient, isWigoloInstalled } from "./providers/wigolo-client.js";
+import "./providers/wigolo.js";
 import "./providers/duckduckgo.js";
 import "./providers/jina-search.js";
 import "./providers/jina-reader.js";
@@ -74,6 +76,7 @@ export default function (pi: ExtensionAPI) {
           showByDefault: true,
           stats: [
             { id: "providers", label: "Enabled Providers", show: true },
+            { id: "wigolo", label: "wigolo", show: true },
             { id: "smartFetch", label: "Smart-Fetch", show: true },
             { id: "cacheEntries", label: "Cache Entries", show: true },
             { id: "cacheSize", label: "Cache Size", show: true },
@@ -91,8 +94,18 @@ export default function (pi: ExtensionAPI) {
           const deps = await checkDependencies();
           const smartFetchStatus = deps.available ? "✓ Ready" : `Missing: ${deps.missing.join(", ")}`;
 
+          // wigolo status — only probe when the user has it enabled, so a
+          // disabled provider never pays the daemon-startup cost.
+          let wigoloStatus = "Disabled";
+          if (config.providers.wigolo?.enabled !== false) {
+            wigoloStatus = (await isWigoloInstalled())
+              ? "✓ Installed"
+              : "Not installed (npx wigolo init)";
+          }
+
           return {
             providers: { value: String(enabledCount) },
+            wigolo: { value: wigoloStatus },
             smartFetch: { value: smartFetchStatus },
             cacheEntries: { value: String(stats.totalEntries) },
             cacheSize: { value: `${(stats.totalSizeBytes / 1024).toFixed(1)} KB` },
@@ -106,5 +119,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_shutdown", async (_event, _ctx) => {
     // Cleanup: clear expired cache entries
     webCache.clearExpired();
+    // Stop the wigolo daemon if this session started it.
+    await closeWigoloClient();
   });
 }

package/src/providers/duckduckgo.ts

@@ -19,43 +19,87 @@ interface DDGResult {
   snippet: string;
 }
 
+/** Decode the handful of HTML entities DuckDuckGo emits. */
+export function decodeEntities(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#x27;|&#39;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)));
+}
+
+/** Strip inline markup (DuckDuckGo bolds query terms with <b> inside snippets). */
+function stripTags(html: string): string {
+  return html.replace(/<[^>]*>/g, "");
+}
+
+/**
+ * Unwrap DuckDuckGo's redirect links.
+ *
+ * Result hrefs look like `//duckduckgo.com/l/?uddg=<encoded>&rut=<hash>`; the
+ * real destination is the `uddg` parameter. Returning the wrapper would give
+ * the agent a URL that is useless to read or cite.
+ */
+export function unwrapRedirect(href: string): string {
+  const decoded = decodeEntities(href);
+
+  const match = decoded.match(/[?&]uddg=([^&]+)/);
+  if (match) {
+    try {
+      return decodeURIComponent(match[1]);
+    } catch {
+      // Fall through to the protocol-relative fix below.
+    }
+  }
+
+  // Protocol-relative links would otherwise be unusable.
+  if (decoded.startsWith("//")) return `https:${decoded}`;
+
+  return decoded;
+}
+
 /**
  * Parse DuckDuckGo HTML search results.
- * Extracts result titles, URLs, and snippets from the HTML.
+ *
+ * Titles and snippets are parsed per result block rather than as two
+ * independent streams: a result without a snippet used to shift every
+ * subsequent snippet onto the wrong title.
  */
-function parseDDGResults(html: string): DDGResult[] {
+export function parseDDGResults(html: string): DDGResult[] {
   const results: DDGResult[] = [];
 
-  // Match result links and snippets
-  // DuckDuckGo results are in <a class="result__a"> tags
-  const linkRegex = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([^<]*)<\/a>/g;
-  const snippetRegex = /<a[^>]*class="result__snippet"[^>]*>([^<]*)<\/a>/g;
-
-  const links: { url: string; title: string }[] = [];
-  const snippets: string[] = [];
+  // `[\s\S]*?` (not `.`) so blocks spanning newlines are matched.
+  const linkRegex =
+    /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/g;
+  // Snippets contain <b> highlights, so the body cannot be `[^<]*`.
+  const snippetRegex =
+    /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g;
 
-  let match;
+  const snippets: Array<{ index: number; text: string }> = [];
+  let match: RegExpExecArray | null;
 
-  // Extract links
-  while ((match = linkRegex.exec(html)) !== null) {
-    links.push({
-      url: match[1],
-      title: match[2].trim(),
+  while ((match = snippetRegex.exec(html)) !== null) {
+    snippets.push({
+      index: match.index,
+      text: decodeEntities(stripTags(match[1])).replace(/\s+/g, " ").trim(),
     });
   }
 
-  // Extract snippets
-  while ((match = snippetRegex.exec(html)) !== null) {
-    snippets.push(match[1].trim());
-  }
+  while ((match = linkRegex.exec(html)) !== null) {
+    const url = unwrapRedirect(match[1]);
+    const title = decodeEntities(stripTags(match[2])).replace(/\s+/g, " ").trim();
+    if (!url || !title) continue;
 
-  // Combine results
-  for (let i = 0; i < Math.min(links.length, snippets.length); i++) {
-    results.push({
-      title: links[i].title,
-      url: links[i].url,
-      snippet: snippets[i],
-    });
+    // The snippet belongs to this result if it appears before the next one.
+    const linkEnd = match.index + match[0].length;
+    const nextLink = html.indexOf('class="result__a"', linkEnd);
+    const boundary = nextLink === -1 ? html.length : nextLink;
+    const snippet = snippets.find((s) => s.index > match!.index && s.index < boundary);
+
+    results.push({ title, url, snippet: snippet?.text ?? "" });
   }
 
   return results;
@@ -98,7 +142,7 @@ const duckduckgoProvider: WebProvider = {
   capabilities: ["search"],
   requiresApiKey: false,
   ranking: {
-    search: 1,
+    search: 2,
     read: 0,
     summarize: 0,
   },

package/src/providers/firecrawl.ts

@@ -76,7 +76,7 @@ const firecrawlProvider: WebProvider = {
   apiKeyEnv: "FIRECRAWL_API_KEY",
   ranking: {
     search: 0,
-    read: 2,
+    read: 3,
     summarize: 0,
   },
   config: {},

package/src/providers/jina-reader.ts

@@ -63,7 +63,7 @@ const jinaReaderProvider: WebProvider = {
   apiKeyEnv: "JINA_API_KEY",
   ranking: {
     search: 0,
-    read: 1,
+    read: 2,
     summarize: 0,
   },
   config: {},

package/src/providers/jina-search.ts

@@ -61,7 +61,7 @@ const jinaSearchProvider: WebProvider = {
   requiresApiKey: false,
   apiKeyEnv: "JINA_API_KEY",
   ranking: {
-    search: 2,
+    search: 3,
     read: 0,
     summarize: 0,
   },

package/src/providers/perplexity.ts

@@ -138,8 +138,8 @@ const perplexityProvider: WebProvider = {
   requiresApiKey: true,
   apiKeyEnv: "PERPLEXITY_API_KEY",
   ranking: {
-    search: 5,
-    read: 3,
+    search: 6,
+    read: 4,
     summarize: 1,
   },
   config: {},

package/src/providers/serpapi.ts

@@ -56,7 +56,7 @@ const serpapiProvider: WebProvider = {
   requiresApiKey: true,
   apiKeyEnv: "SERPAPI_KEY",
   ranking: {
-    search: 3,
+    search: 4,
     read: 0,
     summarize: 0,
   },

package/src/providers/tavily.ts

@@ -65,7 +65,7 @@ const tavilyProvider: WebProvider = {
   requiresApiKey: true,
   apiKeyEnv: "TAVILY_API_KEY",
   ranking: {
-    search: 4,
+    search: 5,
     read: 0,
     summarize: 0,
   },

package/src/providers/wigolo-client.ts

@@ -0,0 +1,196 @@
+/**
+ * @unipi/web-api — wigolo daemon client lifecycle
+ *
+ * wigolo (https://github.com/KnockOutEZ/wigolo) is a local-first web engine:
+ * multi-engine search, tiered fetch, on-device reranking. It needs no API key
+ * and nothing leaves the machine.
+ *
+ * `wigolo-sdk` is AGPL-3.0-only while UniPi is MIT, so it is an *optional*
+ * dependency loaded through a dynamic `import()`. UniPi therefore ships no
+ * AGPL code; wigolo is used only if the user has installed it. When it is
+ * absent (or not initialized) the provider reports an actionable error and
+ * auto-selection falls through to the next-ranked provider.
+ *
+ * The daemon is expensive to start, so the client is a lazily-created
+ * module-level singleton, closed on session shutdown.
+ */
+
+/** Minimal structural types — avoids a type-level dependency on the AGPL SDK. */
+interface WigoloSearchResponse {
+  results?: unknown[];
+  answer?: string;
+  error?: string;
+  warning?: string;
+  [key: string]: unknown;
+}
+
+interface WigoloFetchResponse {
+  url?: string;
+  title?: string;
+  markdown?: string;
+  error?: string;
+  [key: string]: unknown;
+}
+
+interface WigoloHealthResponse {
+  status?: string;
+  [key: string]: unknown;
+}
+
+interface WigoloClientLike {
+  search(params: Record<string, unknown>): Promise<WigoloSearchResponse>;
+  fetch(params: Record<string, unknown>): Promise<WigoloFetchResponse>;
+  health(): Promise<WigoloHealthResponse>;
+}
+
+interface WigoloLocalClient {
+  client: WigoloClientLike;
+  owned: boolean;
+  close(): Promise<void>;
+}
+
+/** Raised when wigolo is unavailable, with an actionable remedy. */
+export class WigoloUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WigoloUnavailableError";
+  }
+}
+
+const NOT_INSTALLED_MESSAGE =
+  "wigolo is not installed.\n" +
+  "→ Install it:  npm install -g wigolo && npx wigolo init\n" +
+  "→ wigolo is a separate AGPL-licensed project and is not bundled with UniPi.\n" +
+  "→ Disable it in /unipi:web-settings to silence this.";
+
+const NOT_RUNNING_MESSAGE =
+  "wigolo is installed but the local daemon could not be reached.\n" +
+  "→ Initialize it:  npx wigolo init\n" +
+  "→ Check health:   npx wigolo doctor\n" +
+  "→ Disable it in /unipi:web-settings to silence this.";
+
+/** Cached singleton — the daemon is far too expensive to start per call. */
+let clientPromise: Promise<WigoloLocalClient> | null = null;
+
+/**
+ * Test seam. ESM bindings are read-only, so tests cannot monkey-patch the
+ * exported `getWigoloClient`; they inject a stub daemon here instead.
+ */
+let clientOverride: WigoloClientLike | null = null;
+
+/** Last known availability, for the settings TUI and info screen. */
+let lastError: string | null = null;
+
+/** Load the optional SDK. Returns null when it is not installed. */
+async function loadSdk(): Promise<
+  { createLocalClient: (opts?: unknown) => Promise<WigoloLocalClient> } | null
+> {
+  try {
+    // Non-literal specifier keeps bundlers from trying to resolve the optional
+    // dependency at build time.
+    const specifier = "wigolo-sdk/local";
+    return (await import(/* @vite-ignore */ specifier)) as {
+      createLocalClient: (opts?: unknown) => Promise<WigoloLocalClient>;
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the shared wigolo client, starting the daemon if needed.
+ * @throws {WigoloUnavailableError} when wigolo is not installed or unreachable.
+ */
+export async function getWigoloClient(): Promise<WigoloClientLike> {
+  if (clientOverride) return clientOverride;
+
+  if (!clientPromise) {
+    clientPromise = (async () => {
+      const sdk = await loadSdk();
+      if (!sdk) {
+        throw new WigoloUnavailableError(NOT_INSTALLED_MESSAGE);
+      }
+      try {
+        return await sdk.createLocalClient();
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new WigoloUnavailableError(`${NOT_RUNNING_MESSAGE}\n→ Cause: ${detail}`);
+      }
+    })();
+
+    // A failed attempt must not be cached forever — the user may run
+    // `wigolo init` mid-session.
+    clientPromise.catch(() => {
+      clientPromise = null;
+    });
+  }
+
+  try {
+    const local = await clientPromise;
+    lastError = null;
+    return local.client;
+  } catch (error) {
+    lastError = error instanceof Error ? error.message : String(error);
+    throw error;
+  }
+}
+
+/** Close the daemon if this process started it. Safe to call repeatedly. */
+export async function closeWigoloClient(): Promise<void> {
+  const pending = clientPromise;
+  clientPromise = null;
+  if (!pending) return;
+  try {
+    const local = await pending;
+    await local.close();
+  } catch {
+    // Never let shutdown cleanup throw.
+  }
+}
+
+/** Availability for the settings TUI / info screen. Never throws. */
+export async function checkWigoloHealth(): Promise<{
+  available: boolean;
+  status: string;
+  detail?: string;
+}> {
+  const sdk = await loadSdk();
+  if (!sdk) {
+    return { available: false, status: "not installed", detail: NOT_INSTALLED_MESSAGE };
+  }
+  try {
+    const client = await getWigoloClient();
+    const health = await client.health();
+    const status = typeof health?.status === "string" ? health.status : "unknown";
+    // wigolo reports 200 "ok" when up and 503 with a body when degraded.
+    return { available: status === "ok" || status === "healthy", status };
+  } catch (error) {
+    return {
+      available: false,
+      status: "unreachable",
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/** Whether the SDK is importable, without starting a daemon. Never throws. */
+export async function isWigoloInstalled(): Promise<boolean> {
+  return (await loadSdk()) !== null;
+}
+
+/** Last recorded failure, for diagnostics. */
+export function getWigoloLastError(): string | null {
+  return lastError;
+}
+
+/** Inject a stub daemon client. Test-only. */
+export function __setWigoloClientForTests(client: WigoloClientLike | null): void {
+  clientOverride = client;
+}
+
+/** Reset module state. Test-only. */
+export function __resetWigoloClientForTests(): void {
+  clientPromise = null;
+  clientOverride = null;
+  lastError = null;
+}

package/src/providers/wigolo.ts

@@ -0,0 +1,117 @@
+/**
+ * @unipi/web-api — wigolo provider
+ *
+ * Local-first search and fetch via the wigolo engine. No API key, no cloud,
+ * $0 per query — results are produced by 18 direct search-engine adapters with
+ * rank fusion and on-device reranking, and pages are fetched through a tiered
+ * router that escalates to a headless browser on anti-bot challenges.
+ *
+ * Ranked 1 for both search and read: it is the preferred default when
+ * available. When wigolo is not installed or not initialized, the calls throw
+ * a {@link WigoloUnavailableError} and auto-selection falls through to the
+ * next-ranked provider (see `selectProvider` in ../tools.ts).
+ */
+
+import type { WebProvider, SearchResult, ReadResult, ProviderConfig } from "./base.js";
+import { registry } from "./registry.js";
+import { getWigoloClient } from "./wigolo-client.js";
+
+/** Default number of results requested from wigolo. */
+const DEFAULT_MAX_RESULTS = 10;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object";
+}
+
+function readString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Normalize one wigolo search result.
+ *
+ * The REST contract types `results` as `unknown[]` because the shape is
+ * extensible, so every field is read defensively. wigolo returns an `excerpt`
+ * pinned to a byte-exact source span; older/alternate builds use `snippet` or
+ * `content`.
+ */
+function toSearchResult(raw: unknown): SearchResult | null {
+  if (!isRecord(raw)) return null;
+
+  const url = readString(raw.url);
+  if (!url) return null;
+
+  const snippet =
+    readString(raw.excerpt) ||
+    readString(raw.snippet) ||
+    readString(raw.content) ||
+    readString(raw.description);
+
+  return {
+    title: readString(raw.title) || url,
+    url,
+    snippet,
+  };
+}
+
+/** Surface an in-body error field — a 200 response can still carry one. */
+function assertNoBodyError(body: { error?: string }, action: string): void {
+  if (body?.error) {
+    throw new Error(`wigolo ${action} failed: ${body.error}`);
+  }
+}
+
+const wigoloProvider: WebProvider = {
+  id: "wigolo",
+  name: "wigolo (local)",
+  capabilities: ["search", "read"],
+  requiresApiKey: false,
+  ranking: {
+    search: 1,
+    read: 1,
+    summarize: 0,
+  },
+  config: {},
+
+  async search(query: string, config?: ProviderConfig): Promise<SearchResult[]> {
+    const client = await getWigoloClient();
+
+    const maxResults =
+      typeof config?.maxResults === "number" ? config.maxResults : DEFAULT_MAX_RESULTS;
+
+    const response = await client.search({
+      query,
+      max_results: maxResults,
+    });
+
+    assertNoBodyError(response, "search");
+
+    const results = Array.isArray(response.results) ? response.results : [];
+    return results
+      .map(toSearchResult)
+      .filter((result): result is SearchResult => result !== null);
+  },
+
+  async read(url: string, _config?: ProviderConfig): Promise<ReadResult> {
+    const client = await getWigoloClient();
+
+    const response = await client.fetch({ url });
+
+    assertNoBodyError(response, "fetch");
+
+    const content = readString(response.markdown);
+    if (!content) {
+      throw new Error(`wigolo returned no content for ${url}`);
+    }
+
+    return {
+      url: readString(response.url) || url,
+      content,
+      contentType: "markdown",
+    };
+  },
+};
+
+registry.register(wigoloProvider);
+
+export { wigoloProvider };

package/src/settings.ts

@@ -66,6 +66,7 @@ const DEFAULT_SMART_FETCH_SETTINGS: SmartFetchSettings = {
 /** Default configuration */
 const DEFAULT_CONFIG: WebApiConfig = {
   providers: {
+    wigolo: { enabled: true },
     duckduckgo: { enabled: true },
     "jina-search": { enabled: true },
     "jina-reader": { enabled: true },

package/src/tools.ts

@@ -71,6 +71,26 @@ function selectProvider(
   capability: WebCapability,
   sourceRank?: number
 ): WebProvider {
+  const candidates = selectProviderChain(capability, sourceRank);
+  return candidates[0];
+}
+
+/**
+ * Build the ordered list of providers to try for a capability.
+ *
+ * With an explicit `sourceRank` the user named a provider, so exactly that one
+ * is returned — their intent is respected and a failure is reported rather
+ * than silently served by someone else.
+ *
+ * Without one, the full ranked list is returned so a failing provider can fall
+ * through to the next. This matters because the rank-1 provider (wigolo) is a
+ * local engine that requires a separate `npx wigolo init`: without
+ * fallthrough, an enabled-but-uninitialized wigolo would break every web call.
+ */
+export function selectProviderChain(
+  capability: WebCapability,
+  sourceRank?: number
+): WebProvider[] {
   const available = getAvailableProviders(capability);
 
   if (available.length === 0) {
@@ -79,7 +99,7 @@ function selectProvider(
     throw new Error(
       `No ${capability} provider configured.\n` +
       `→ Run /unipi:web-settings to enable providers and add API keys.\n` +
-      `→ Free options: DuckDuckGo (search), Jina Reader (read).\n` +
+      `→ Free options: wigolo (search + read, local), DuckDuckGo (search), Jina Reader (read).\n` +
       `→ Available providers: ${providerNames}`
     );
   }
@@ -94,11 +114,42 @@ function selectProvider(
         `Available ranks: ${availableRanks}`
       );
     }
-    return provider;
+    return [provider];
+  }
+
+  // Ranked cheapest/simplest first
+  return available;
+}
+
+/**
+ * Run `attempt` against each candidate provider in turn, returning the first
+ * success. If every candidate fails, the first error is rethrown with the
+ * later failures appended, so the message explains the whole chain rather
+ * than only the last hop.
+ */
+export async function withProviderFallthrough<T>(
+  providers: WebProvider[],
+  attempt: (provider: WebProvider) => Promise<T>
+): Promise<T> {
+  const failures: string[] = [];
+
+  for (const provider of providers) {
+    try {
+      return await attempt(provider);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`${provider.name}: ${message}`);
+    }
+  }
+
+  if (failures.length === 1) {
+    throw new Error(failures[0]);
   }
 
-  // Return lowest-ranked (cheapest/simplest) available provider
-  return available[0];
+  throw new Error(
+    `All ${failures.length} providers failed:\n` +
+    failures.map((f) => `→ ${f}`).join("\n")
+  );
 }
 
 /**
@@ -108,16 +159,18 @@ async function executeSearch(
   query: string,
   sourceRank?: number
 ): Promise<SearchResult[]> {
-  const provider = selectProvider("search", sourceRank);
+  const candidates = selectProviderChain("search", sourceRank);
 
-  if (!provider.search) {
-    throw new Error(`Provider "${provider.name}" does not support search`);
-  }
+  return withProviderFallthrough(candidates, async (provider) => {
+    if (!provider.search) {
+      throw new Error(`Provider "${provider.name}" does not support search`);
+    }
 
-  const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
-  const config = { enabled: true, apiKey };
+    const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
+    const config = { enabled: true, apiKey };
 
-  return provider.search(query, config);
+    return provider.search(query, config);
+  });
 }
 
 /**
@@ -127,16 +180,18 @@ async function executeProviderRead(
   url: string,
   sourceRank?: number
 ): Promise<ReadResult> {
-  const provider = selectProvider("read", sourceRank);
+  const candidates = selectProviderChain("read", sourceRank);
 
-  if (!provider.read) {
-    throw new Error(`Provider "${provider.name}" does not support read`);
-  }
+  return withProviderFallthrough(candidates, async (provider) => {
+    if (!provider.read) {
+      throw new Error(`Provider "${provider.name}" does not support read`);
+    }
 
-  const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
-  const config = { enabled: true, apiKey };
+    const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
+    const config = { enabled: true, apiKey };
 
-  return provider.read(url, config);
+    return provider.read(url, config);
+  });
 }
 
 /**
@@ -147,16 +202,18 @@ async function executeSummarize(
   prompt?: string,
   sourceRank?: number
 ): Promise<SummarizeResult> {
-  const provider = selectProvider("summarize", sourceRank);
+  const candidates = selectProviderChain("summarize", sourceRank);
 
-  if (!provider.summarize) {
-    throw new Error(`Provider "${provider.name}" does not support summarize`);
-  }
+  return withProviderFallthrough(candidates, async (provider) => {
+    if (!provider.summarize) {
+      throw new Error(`Provider "${provider.name}" does not support summarize`);
+    }
 
-  const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
-  const config = { enabled: true, apiKey };
+    const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
+    const config = { enabled: true, apiKey };
 
-  return provider.summarize(url, prompt, config);
+    return provider.summarize(url, prompt, config);
+  });
 }
 
 /**
@@ -248,24 +305,24 @@ export function registerWebTools(pi: ExtensionAPI): void {
     label: "Web Search",
     description:
       "Search the web for information using various providers. " +
-      "Lower source = simpler/cheaper providers (DuckDuckGo, Jina Search). " +
+      "Lower source = simpler/cheaper providers (wigolo, DuckDuckGo, Jina Search). " +
       "Higher source = more capable providers (SerpAPI, Tavily, Perplexity).",
     promptSnippet: "Search the web for information.",
     promptGuidelines: [
       "Use web_search to find information on the web.",
-      "Omit source for auto-selection (cheapest available).",
-      "Specify source number for specific provider (1=DuckDuckGo, 2=Jina, 3=SerpAPI, 4=Tavily, 5=Perplexity).",
-      "Quick facts: source 1-2. Research: source 3-5.",
+      "Omit source for auto-selection (cheapest available, falling through on failure).",
+      "Specify source number for specific provider (1=wigolo, 2=DuckDuckGo, 3=Jina, 4=SerpAPI, 5=Tavily, 6=Perplexity).",
+      "Quick facts: source 1-3. Research: source 4-6.",
     ],
     parameters: Type.Object({
       query: Type.String({ description: "Search query string" }),
       source: Type.Optional(
         Type.Number({
           description:
-            "Provider selection (1=DuckDuckGo, 2=Jina Search, 3=SerpAPI, 4=Tavily, 5=Perplexity). " +
+            "Provider selection (1=wigolo, 2=DuckDuckGo, 3=Jina Search, 4=SerpAPI, 5=Tavily, 6=Perplexity). " +
             "Omit for auto-selection.",
           minimum: 1,
-          maximum: 5,
+          maximum: 6,
         })
       ),
     }),
@@ -321,7 +378,7 @@ export function registerWebTools(pi: ExtensionAPI): void {
       "Use multi_web_content_read to extract content from web pages.",
       "Pass a single URL string or an array of URLs for batch reading.",
       "Default source (0 or omitted) uses the local smart-fetch engine — free, no API key.",
-      "source 1-3 uses provider fallbacks: Jina Reader, Firecrawl, Perplexity.",
+      "source 1-4 uses provider fallbacks: wigolo, Jina Reader, Firecrawl, Perplexity.",
       "Batch mode: pass an array of URLs, returns results for each.",
     ],
     parameters: Type.Object({
@@ -332,10 +389,10 @@ export function registerWebTools(pi: ExtensionAPI): void {
       source: Type.Optional(
         Type.Number({
           description:
-            "Provider selection (0=smart-fetch engine, 1=Jina Reader, 2=Firecrawl, 3=Perplexity). " +
+            "Provider selection (0=smart-fetch engine, 1=wigolo, 2=Jina Reader, 3=Firecrawl, 4=Perplexity). " +
             "Default is 0 (smart-fetch).",
           minimum: 0,
-          maximum: 3,
+          maximum: 4,
         })
       ),
       browser: Type.Optional(
@@ -556,10 +613,10 @@ export function registerWebTools(pi: ExtensionAPI): void {
       source: Type.Optional(
         Type.Number({
           description:
-            "Provider selection for content fetch (1=Jina Reader, 2=Firecrawl, 3=Perplexity). " +
+            "Provider selection for content fetch (1=Perplexity, 2=LLM summarize). " +
             "Omit for auto-selection.",
           minimum: 1,
-          maximum: 3,
+          maximum: 2,
         })
       ),
     }),