@demigodmode/pi-web-agent 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -18,6 +18,21 @@ The format is intentionally simple and release-oriented.
 ### Breaking
 - None.
 
+## [1.7.0] - 2026-07-17
+### Added
+- Exa is now available as a hosted search backend for `web_explore`, aimed at research-quality source discovery. Set `EXA_API_KEY` in the environment and choose `exa` from **Settings → Backends**. Closes #2.
+- Tavily is now available as a hosted search backend for `web_explore` alongside Exa, DuckDuckGo, SearXNG, Brave, and You.com. Set `TAVILY_API_KEY` and choose `tavily` from **Settings → Backends**. Closes #2.
+- Both new backends support optional fallback to DuckDuckGo, and `/web-agent doctor` reports their setup status and validates configured access when a key is present.
+
+### Changed
+- Bumped @earendil-works/pi-coding-agent and pi-tui devDependencies to 0.80.10.
+
+### Fixed
+- None.
+
+### Breaking
+- None.
+
 ## [1.6.2] - 2026-07-10
 ### Added
 - None.

package/README.md

@@ -119,7 +119,7 @@ Backend settings can be changed from:
 /web-agent settings
 ```
 
-Choose **Backends** to edit search/fetch providers, fallback behavior, and SearXNG or Firecrawl base URLs interactively. Brave Search uses `PI_WEB_AGENT_BRAVE_API_KEY` and You.com uses `YDC_API_KEY`. Firecrawl API keys should also stay in environment variables rather than being written into config files.
+Choose **Backends** to edit search/fetch providers, fallback behavior, and SearXNG or Firecrawl base URLs interactively. Brave Search uses `PI_WEB_AGENT_BRAVE_API_KEY`, You.com uses `YDC_API_KEY`, Exa uses `EXA_API_KEY`, and Tavily uses `TAVILY_API_KEY`. Firecrawl API keys should also stay in environment variables rather than being written into config files.
 
 For the full backend config shape, including SearXNG, Brave, You.com, Firecrawl, and fallback behavior, see:
 

package/dist/backends/config.d.ts

@@ -8,7 +8,7 @@ export type FirecrawlOptions = {
     onlyMainContent?: boolean;
 };
 export type SearchBackendConfig = {
-    provider: 'duckduckgo' | 'searxng' | 'brave' | 'youcom';
+    provider: 'duckduckgo' | 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
     baseUrl?: string;
     fallback?: 'duckduckgo';
     options?: SearxngOptions;

package/dist/backends/config.js

@@ -41,7 +41,9 @@ export function extractBackendConfigOverride(file) {
     if (backends?.search?.provider === 'duckduckgo' ||
         backends?.search?.provider === 'searxng' ||
         backends?.search?.provider === 'brave' ||
-        backends?.search?.provider === 'youcom') {
+        backends?.search?.provider === 'youcom' ||
+        backends?.search?.provider === 'exa' ||
+        backends?.search?.provider === 'tavily') {
         override.search = { provider: backends.search.provider };
         if (backends.search.provider === 'searxng' && typeof backends.search.baseUrl === 'string') {
             override.search.baseUrl = backends.search.baseUrl;
@@ -85,8 +87,8 @@ export function validateBackendConfig(config) {
     if (config.fetch.provider === 'firecrawl' && !config.fetch.baseUrl) {
         issues.push('fetch provider firecrawl requires backends.fetch.baseUrl');
     }
-    if (config.search.fallback === 'duckduckgo' && config.search.provider !== 'searxng' && config.search.provider !== 'brave' && config.search.provider !== 'youcom') {
-        issues.push('search fallback duckduckgo is only supported when search provider is searxng, brave, or youcom');
+    if (config.search.fallback === 'duckduckgo' && config.search.provider !== 'searxng' && config.search.provider !== 'brave' && config.search.provider !== 'youcom' && config.search.provider !== 'exa' && config.search.provider !== 'tavily') {
+        issues.push('search fallback duckduckgo is only supported when search provider is searxng, brave, youcom, exa, or tavily');
     }
     if (config.fetch.fallback === 'http' && config.fetch.provider !== 'firecrawl') {
         issues.push('fetch fallback http is only supported when fetch provider is firecrawl');

package/dist/backends/doctor.js

@@ -15,6 +15,12 @@ function braveDoctorUrl() {
 function youcomDoctorBody() {
     return JSON.stringify({ query: 'pi-web-agent-doctor', max_results: 1 });
 }
+function exaDoctorBody() {
+    return JSON.stringify({ query: 'pi-web-agent-doctor', numResults: 1 });
+}
+function tavilyDoctorBody() {
+    return JSON.stringify({ query: 'pi-web-agent-doctor', max_results: 1 });
+}
 function searxngDoctorUrl(baseUrl, options = {}) {
     const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     url.searchParams.set('q', 'pi-web-agent-doctor');
@@ -108,6 +114,78 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
             }
         }
     }
+    else if (config.search.provider === 'exa') {
+        const apiKey = process.env.EXA_API_KEY;
+        if (!apiKey?.trim()) {
+            lines.push('search backend: exa warning (missing EXA_API_KEY)');
+        }
+        else {
+            const timeout = withTimeout(timeoutMs);
+            try {
+                const response = await fetchImpl('https://api.exa.ai/search', {
+                    method: 'POST',
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json',
+                        'x-api-key': apiKey
+                    },
+                    body: exaDoctorBody(),
+                    signal: timeout.signal
+                });
+                if (!response.ok) {
+                    lines.push(`search backend: exa warning (HTTP ${response.status})`);
+                }
+                else {
+                    const json = (await response.json());
+                    lines.push(Array.isArray(json.results)
+                        ? 'search backend: exa ok'
+                        : 'search backend: exa warning (unexpected response)');
+                }
+            }
+            catch (error) {
+                lines.push(`search backend: exa warning (${message(error)})`);
+            }
+            finally {
+                timeout.done();
+            }
+        }
+    }
+    else if (config.search.provider === 'tavily') {
+        const apiKey = process.env.TAVILY_API_KEY;
+        if (!apiKey?.trim()) {
+            lines.push('search backend: tavily warning (missing TAVILY_API_KEY)');
+        }
+        else {
+            const timeout = withTimeout(timeoutMs);
+            try {
+                const response = await fetchImpl('https://api.tavily.com/search', {
+                    method: 'POST',
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${apiKey}`
+                    },
+                    body: tavilyDoctorBody(),
+                    signal: timeout.signal
+                });
+                if (!response.ok) {
+                    lines.push(`search backend: tavily warning (HTTP ${response.status})`);
+                }
+                else {
+                    const json = (await response.json());
+                    lines.push(Array.isArray(json.results)
+                        ? 'search backend: tavily ok'
+                        : 'search backend: tavily warning (unexpected response)');
+                }
+            }
+            catch (error) {
+                lines.push(`search backend: tavily warning (${message(error)})`);
+            }
+            finally {
+                timeout.done();
+            }
+        }
+    }
     else if (!config.search.baseUrl) {
         lines.push('search backend: searxng warning (missing baseUrl)');
     }

package/dist/backends/factory.d.ts

@@ -1,6 +1,8 @@
 import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
 import { createBraveSearchTool } from '../search/brave.js';
 import { createYouComSearchTool } from '../search/youcom.js';
+import { createExaSearchTool } from '../search/exa.js';
+import { createTavilySearchTool } from '../search/tavily.js';
 import { createSearxngSearchTool } from '../search/searxng.js';
 import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
 import { createWebFetchTool } from '../tools/web-fetch.js';
@@ -23,6 +25,8 @@ export type BackendFactoryDeps = {
     createSearxngSearch?: typeof createSearxngSearchTool;
     createBraveSearch?: typeof createBraveSearchTool;
     createYouComSearch?: typeof createYouComSearchTool;
+    createExaSearch?: typeof createExaSearchTool;
+    createTavilySearch?: typeof createTavilySearchTool;
     createHttpFetch?: typeof createWebFetchTool;
     createFirecrawlFetch?: typeof createFirecrawlFetcher;
     createHeadlessFetch?: typeof createWebFetchHeadlessTool;

package/dist/backends/factory.js

@@ -1,6 +1,8 @@
 import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
 import { createBraveSearchTool } from '../search/brave.js';
 import { createYouComSearchTool } from '../search/youcom.js';
+import { createExaSearchTool } from '../search/exa.js';
+import { createTavilySearchTool } from '../search/tavily.js';
 import { createSearxngSearchTool } from '../search/searxng.js';
 import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
 import { buildSearchPresentation } from '../presentation/search-presentation.js';
@@ -75,6 +77,8 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
     const createSearxngSearch = deps.createSearxngSearch ?? createSearxngSearchTool;
     const createBraveSearch = deps.createBraveSearch ?? createBraveSearchTool;
     const createYouComSearch = deps.createYouComSearch ?? createYouComSearchTool;
+    const createExaSearch = deps.createExaSearch ?? createExaSearchTool;
+    const createTavilySearch = deps.createTavilySearch ?? createTavilySearchTool;
     const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
     const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
     const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
@@ -86,7 +90,11 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
             ? createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY })
             : config.search.provider === 'youcom'
                 ? createYouComSearch({ apiKey: process.env.YDC_API_KEY })
-                : createDuckDuckGoSearch();
+                : config.search.provider === 'exa'
+                    ? createExaSearch({ apiKey: process.env.EXA_API_KEY })
+                    : config.search.provider === 'tavily'
+                        ? createTavilySearch({ apiKey: process.env.TAVILY_API_KEY })
+                        : createDuckDuckGoSearch();
     if (config.search.provider === 'searxng' && config.search.fallback === 'duckduckgo') {
         search = withSearchFallback(search, createDuckDuckGoSearch(), 'searxng');
     }
@@ -96,6 +104,12 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
     if (config.search.provider === 'youcom' && config.search.fallback === 'duckduckgo') {
         search = withSearchFallback(search, createDuckDuckGoSearch(), 'youcom');
     }
+    if (config.search.provider === 'exa' && config.search.fallback === 'duckduckgo') {
+        search = withSearchFallback(search, createDuckDuckGoSearch(), 'exa');
+    }
+    if (config.search.provider === 'tavily' && config.search.fallback === 'duckduckgo') {
+        search = withSearchFallback(search, createDuckDuckGoSearch(), 'tavily');
+    }
     const httpFetch = createHttpFetch();
     let fetchPage = config.fetch.provider === 'firecrawl'
         ? config.fetch.baseUrl

package/dist/commands/web-agent-config.js

@@ -166,7 +166,7 @@ function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange
             id: 'backend:search:provider',
             label: 'Search backend',
             currentValue: backends.search.provider,
-            values: ['duckduckgo', 'searxng', 'brave', 'youcom']
+            values: ['duckduckgo', 'searxng', 'brave', 'youcom', 'exa', 'tavily']
         },
         {
             id: 'backend:search:baseUrl',
@@ -177,8 +177,8 @@ function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange
         {
             id: 'backend:search:fallback',
             label: 'Search fallback',
-            currentValue: backends.search.provider === 'searxng' || backends.search.provider === 'brave' || backends.search.provider === 'youcom' ? backends.search.fallback ?? 'off' : 'off',
-            values: backends.search.provider === 'searxng' || backends.search.provider === 'brave' || backends.search.provider === 'youcom' ? ['off', 'duckduckgo'] : ['off']
+            currentValue: backends.search.provider === 'searxng' || backends.search.provider === 'brave' || backends.search.provider === 'youcom' || backends.search.provider === 'exa' || backends.search.provider === 'tavily' ? backends.search.fallback ?? 'off' : 'off',
+            values: backends.search.provider === 'searxng' || backends.search.provider === 'brave' || backends.search.provider === 'youcom' || backends.search.provider === 'exa' || backends.search.provider === 'tavily' ? ['off', 'duckduckgo'] : ['off']
         },
         {
             id: 'backend:secret:brave',
@@ -192,6 +192,18 @@ function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange
             currentValue: 'env var',
             values: ['env var']
         },
+        {
+            id: 'backend:secret:exa',
+            label: 'Exa API key',
+            currentValue: 'env var',
+            values: ['env var']
+        },
+        {
+            id: 'backend:secret:tavily',
+            label: 'Tavily API key',
+            currentValue: 'env var',
+            values: ['env var']
+        },
         {
             id: 'backend:fetch:provider',
             label: 'Fetch backend',
@@ -303,7 +315,7 @@ export function applySettingsValue(state, id, newValue) {
         }
         currentDraft.tools = nextTools;
     }
-    if (id === 'backend:search:provider' && (newValue === 'duckduckgo' || newValue === 'searxng' || newValue === 'brave' || newValue === 'youcom')) {
+    if (id === 'backend:search:provider' && (newValue === 'duckduckgo' || newValue === 'searxng' || newValue === 'brave' || newValue === 'youcom' || newValue === 'exa' || newValue === 'tavily')) {
         currentBackends.search.provider = newValue;
         if (newValue !== 'searxng') {
             delete currentBackends.search.baseUrl;
@@ -314,7 +326,7 @@ export function applySettingsValue(state, id, newValue) {
         }
     }
     if (id === 'backend:search:fallback') {
-        if (newValue === 'duckduckgo' && (currentBackends.search.provider === 'searxng' || currentBackends.search.provider === 'brave' || currentBackends.search.provider === 'youcom')) {
+        if (newValue === 'duckduckgo' && (currentBackends.search.provider === 'searxng' || currentBackends.search.provider === 'brave' || currentBackends.search.provider === 'youcom' || currentBackends.search.provider === 'exa' || currentBackends.search.provider === 'tavily')) {
             currentBackends.search.fallback = 'duckduckgo';
         }
         else {

package/dist/search/exa.d.ts

@@ -0,0 +1,7 @@
+import type { WebSearchResponse } from '../types.js';
+export declare function createExaSearchTool({ apiKey, fetchImpl }: {
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}): ({ query }: {
+    query: string;
+}) => Promise<WebSearchResponse>;

package/dist/search/exa.js

@@ -0,0 +1,81 @@
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+const EXA_SEARCH_URL = 'https://api.exa.ai/search';
+function resultWithPresentation(result) {
+    return { ...result, presentation: buildSearchPresentation(result) };
+}
+function normalizeResults(response) {
+    return (response.results ?? []).flatMap((item) => {
+        if (typeof item.title !== 'string' || typeof item.url !== 'string') {
+            return [];
+        }
+        return [
+            {
+                title: item.title,
+                url: item.url,
+                snippet: typeof item.text === 'string' ? item.text : ''
+            }
+        ];
+    });
+}
+export function createExaSearchTool({ apiKey, fetchImpl = fetch }) {
+    return async function exaSearch({ query }) {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery) {
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'exa', cacheHit: false },
+                error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
+            });
+        }
+        if (!apiKey?.trim()) {
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'exa', cacheHit: false },
+                error: {
+                    code: 'BACKEND_CONFIG_INVALID',
+                    message: 'Exa search requires EXA_API_KEY.'
+                }
+            });
+        }
+        try {
+            const response = await fetchImpl(EXA_SEARCH_URL, {
+                method: 'POST',
+                headers: {
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                    'x-api-key': apiKey
+                },
+                body: JSON.stringify({ query: normalizedQuery, numResults: 10 })
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const parsed = (await response.json());
+            const results = normalizeResults(parsed);
+            if (results.length === 0) {
+                return resultWithPresentation({
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'exa', cacheHit: false },
+                    error: { code: 'NO_RESULTS', message: 'Exa returned no usable results for this query.' }
+                });
+            }
+            return resultWithPresentation({
+                status: 'ok',
+                results,
+                metadata: { backend: 'exa', cacheHit: false }
+            });
+        }
+        catch (error) {
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'exa', cacheHit: false },
+                error: { code: 'FETCH_FAILED', message: `Exa search request failed: ${rawMessage}` }
+            });
+        }
+    };
+}

package/dist/search/tavily.d.ts

@@ -0,0 +1,7 @@
+import type { WebSearchResponse } from '../types.js';
+export declare function createTavilySearchTool({ apiKey, fetchImpl }: {
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}): ({ query }: {
+    query: string;
+}) => Promise<WebSearchResponse>;

package/dist/search/tavily.js

@@ -0,0 +1,81 @@
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+const TAVILY_SEARCH_URL = 'https://api.tavily.com/search';
+function resultWithPresentation(result) {
+    return { ...result, presentation: buildSearchPresentation(result) };
+}
+function normalizeResults(response) {
+    return (response.results ?? []).flatMap((item) => {
+        if (typeof item.title !== 'string' || typeof item.url !== 'string') {
+            return [];
+        }
+        return [
+            {
+                title: item.title,
+                url: item.url,
+                snippet: typeof item.content === 'string' ? item.content : ''
+            }
+        ];
+    });
+}
+export function createTavilySearchTool({ apiKey, fetchImpl = fetch }) {
+    return async function tavilySearch({ query }) {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery) {
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'tavily', cacheHit: false },
+                error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
+            });
+        }
+        if (!apiKey?.trim()) {
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'tavily', cacheHit: false },
+                error: {
+                    code: 'BACKEND_CONFIG_INVALID',
+                    message: 'Tavily search requires TAVILY_API_KEY.'
+                }
+            });
+        }
+        try {
+            const response = await fetchImpl(TAVILY_SEARCH_URL, {
+                method: 'POST',
+                headers: {
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`
+                },
+                body: JSON.stringify({ query: normalizedQuery, max_results: 10 })
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const parsed = (await response.json());
+            const results = normalizeResults(parsed);
+            if (results.length === 0) {
+                return resultWithPresentation({
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'tavily', cacheHit: false },
+                    error: { code: 'NO_RESULTS', message: 'Tavily returned no usable results for this query.' }
+                });
+            }
+            return resultWithPresentation({
+                status: 'ok',
+                results,
+                metadata: { backend: 'tavily', cacheHit: false }
+            });
+        }
+        catch (error) {
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'tavily', cacheHit: false },
+                error: { code: 'FETCH_FAILED', message: `Tavily search request failed: ${rawMessage}` }
+            });
+        }
+    };
+}

package/dist/types.d.ts

@@ -11,9 +11,9 @@ export type ToolError = {
     message: string;
 };
 export type SearchMetadata = {
-    backend: 'duckduckgo' | 'searxng' | 'brave' | 'youcom';
+    backend: 'duckduckgo' | 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
     cacheHit: boolean;
-    fallbackFrom?: 'searxng' | 'brave' | 'youcom';
+    fallbackFrom?: 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
     fallbackReason?: string;
 };
 export type FetchMetadata = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demigodmode/pi-web-agent",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
   "type": "module",
   "main": "./dist/extension.js",
@@ -27,6 +27,8 @@
     "searxng",
     "brave-search",
     "you-com",
+    "exa",
+    "tavily",
     "firecrawl"
   ],
   "repository": {
@@ -68,8 +70,8 @@
     "typebox": "^1.1.37"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.79.10",
-    "@earendil-works/pi-tui": "^0.79.10",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.6",