@demigodmode/pi-web-agent 0.4.0 → 0.6.0

package/README.md

@@ -18,6 +18,10 @@ That sounds obvious, but a lot of agent tooling gets fuzzy right there. This pac
 pi install npm:@demigodmode/pi-web-agent
 ```
 
+After installing, reload or restart Pi. Run `/web-agent` for the action menu, or `/web-agent doctor` to check whether the package loaded cleanly and whether headless rendering can find a browser.
+
+Headless rendering currently requires a detectable Chromium-family browser: Chrome, Chromium, Edge, or Brave. Firefox/Safari-only systems can still use search and plain HTTP reads, but browser-rendered fallback pages need a supported Chromium-family browser for now.
+
 Later on, update installed packages with:
 
 ```bash
@@ -65,6 +69,7 @@ Primary UI:
 Helper commands:
 
 ```text
+/web-agent doctor
 /web-agent show
 /web-agent reset project
 /web-agent reset global
@@ -101,6 +106,34 @@ Example:
 }
 ```
 
+Backend config is also supported. Defaults are DuckDuckGo search, plain HTTP fetch, and local browser headless fallback:
+
+```json
+{
+  "backends": {
+    "search": { "provider": "duckduckgo" },
+    "fetch": { "provider": "http" },
+    "headless": { "provider": "local-browser" }
+  }
+}
+```
+
+Self-hosted example for existing SearXNG/Firecrawl services:
+
+```json
+{
+  "backends": {
+    "search": { "provider": "searxng", "baseUrl": "http://localhost:8080" },
+    "fetch": { "provider": "firecrawl", "baseUrl": "http://localhost:3002" },
+    "headless": { "provider": "local-browser" }
+  }
+}
+```
+
+Prefer `PI_WEB_AGENT_FIRECRAWL_API_KEY` for Firecrawl auth instead of putting secrets in project config. `/web-agent doctor` validates required backend fields and checks configured self-hosted endpoints.
+
+Full guide: https://demigodmode.github.io/pi-web-agent/self-hosted-backends
+
 ## Local development
 
 ```bash

package/dist/backends/config.d.ts

@@ -0,0 +1,42 @@
+export type SearchBackendConfig = {
+    provider: 'duckduckgo' | 'searxng';
+    baseUrl?: string;
+};
+export type FetchBackendConfig = {
+    provider: 'http' | 'firecrawl';
+    baseUrl?: string;
+    apiKey?: string;
+};
+export type HeadlessBackendConfig = {
+    provider: 'local-browser';
+};
+export type BackendConfig = {
+    search: SearchBackendConfig;
+    fetch: FetchBackendConfig;
+    headless: HeadlessBackendConfig;
+};
+export type BackendConfigOverride = {
+    search?: Partial<SearchBackendConfig>;
+    fetch?: Partial<FetchBackendConfig>;
+    headless?: Partial<HeadlessBackendConfig>;
+};
+export type BackendConfigFile = {
+    backends?: {
+        search?: {
+            provider?: unknown;
+            baseUrl?: unknown;
+        };
+        fetch?: {
+            provider?: unknown;
+            baseUrl?: unknown;
+            apiKey?: unknown;
+        };
+        headless?: {
+            provider?: unknown;
+        };
+    };
+};
+export declare const DEFAULT_BACKEND_CONFIG: BackendConfig;
+export declare function extractBackendConfigOverride(file: BackendConfigFile | null | undefined): BackendConfigOverride;
+export declare function validateBackendConfig(config: BackendConfig): string[];
+export declare function mergeBackendConfigLayers(...layers: Array<BackendConfig | BackendConfigOverride | undefined>): BackendConfig;

package/dist/backends/config.js

@@ -0,0 +1,61 @@
+export const DEFAULT_BACKEND_CONFIG = {
+    search: { provider: 'duckduckgo' },
+    fetch: { provider: 'http' },
+    headless: { provider: 'local-browser' }
+};
+export function extractBackendConfigOverride(file) {
+    const backends = file?.backends;
+    const override = {};
+    if (backends?.search?.provider === 'duckduckgo' || backends?.search?.provider === 'searxng') {
+        override.search = { provider: backends.search.provider };
+        if (typeof backends.search.baseUrl === 'string') {
+            override.search.baseUrl = backends.search.baseUrl;
+        }
+    }
+    if (backends?.fetch?.provider === 'http' || backends?.fetch?.provider === 'firecrawl') {
+        override.fetch = { provider: backends.fetch.provider };
+        if (typeof backends.fetch.baseUrl === 'string') {
+            override.fetch.baseUrl = backends.fetch.baseUrl;
+        }
+        if (typeof backends.fetch.apiKey === 'string') {
+            override.fetch.apiKey = backends.fetch.apiKey;
+        }
+    }
+    if (backends?.headless?.provider === 'local-browser') {
+        override.headless = { provider: 'local-browser' };
+    }
+    return override;
+}
+export function validateBackendConfig(config) {
+    const issues = [];
+    if (config.search.provider === 'searxng' && !config.search.baseUrl) {
+        issues.push('search provider searxng requires backends.search.baseUrl');
+    }
+    if (config.fetch.provider === 'firecrawl' && !config.fetch.baseUrl) {
+        issues.push('fetch provider firecrawl requires backends.fetch.baseUrl');
+    }
+    return issues;
+}
+function mergeSearchConfig(current, override) {
+    if (!override)
+        return current;
+    if (override.provider && override.provider !== current.provider) {
+        return { ...override, provider: override.provider };
+    }
+    return { ...current, ...override };
+}
+function mergeFetchConfig(current, override) {
+    if (!override)
+        return current;
+    if (override.provider && override.provider !== current.provider) {
+        return { ...override, provider: override.provider };
+    }
+    return { ...current, ...override };
+}
+export function mergeBackendConfigLayers(...layers) {
+    return layers.reduce((merged, layer) => ({
+        search: mergeSearchConfig(merged.search, layer?.search),
+        fetch: mergeFetchConfig(merged.fetch, layer?.fetch),
+        headless: { ...merged.headless, ...layer?.headless }
+    }), DEFAULT_BACKEND_CONFIG);
+}

package/dist/backends/doctor.d.ts

@@ -0,0 +1,5 @@
+import type { BackendConfig } from './config.js';
+export declare function checkBackendHealth(config: BackendConfig, { fetchImpl, timeoutMs }?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<string[]>;

package/dist/backends/doctor.js

@@ -0,0 +1,68 @@
+function withTimeout(timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    return { signal: controller.signal, done: () => clearTimeout(timeout) };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function searxngDoctorUrl(baseUrl) {
+    const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+    url.searchParams.set('q', 'pi-web-agent-doctor');
+    url.searchParams.set('format', 'json');
+    return url.toString();
+}
+export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs = 3_000 } = {}) {
+    const lines = [];
+    if (config.search.provider === 'duckduckgo') {
+        lines.push('search backend: duckduckgo');
+    }
+    else if (!config.search.baseUrl) {
+        lines.push('search backend: searxng warning (missing baseUrl)');
+    }
+    else {
+        const timeout = withTimeout(timeoutMs);
+        try {
+            const response = await fetchImpl(searxngDoctorUrl(config.search.baseUrl), { signal: timeout.signal });
+            const json = (await response.json());
+            lines.push(response.ok && Array.isArray(json.results)
+                ? 'search backend: searxng ok'
+                : 'search backend: searxng warning (unexpected response)');
+        }
+        catch (error) {
+            lines.push(`search backend: searxng warning (${message(error)})`);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+    if (config.fetch.provider === 'http') {
+        lines.push('fetch backend: http');
+    }
+    else if (!config.fetch.baseUrl) {
+        lines.push('fetch backend: firecrawl warning (missing baseUrl)');
+    }
+    else {
+        const timeout = withTimeout(timeoutMs);
+        try {
+            const headers = { 'content-type': 'application/json' };
+            if (config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY) {
+                headers.Authorization = `Bearer ${config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY}`;
+            }
+            const response = await fetchImpl(new URL('/v1/scrape', config.fetch.baseUrl).toString(), {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ url: 'https://example.com', formats: ['markdown'] }),
+                signal: timeout.signal
+            });
+            lines.push(response.ok ? 'fetch backend: firecrawl ok' : `fetch backend: firecrawl warning (HTTP ${response.status})`);
+        }
+        catch (error) {
+            lines.push(`fetch backend: firecrawl warning (${message(error)})`);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+    return lines;
+}

package/dist/backends/factory.d.ts

@@ -0,0 +1,14 @@
+import type { WebFetchHeadlessResponse, WebFetchResponse, WebSearchResponse } from '../types.js';
+import { type BackendConfig } from './config.js';
+export type BackendSet = {
+    search: (input: {
+        query: string;
+    }) => Promise<WebSearchResponse>;
+    fetchPage: (input: {
+        url: string;
+    }) => Promise<WebFetchResponse>;
+    headlessFetch: (input: {
+        url: string;
+    }) => Promise<WebFetchHeadlessResponse>;
+};
+export declare function createBackendSet(config?: BackendConfig): BackendSet;

package/dist/backends/factory.js

@@ -0,0 +1,58 @@
+import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
+import { createSearxngSearchTool } from '../search/searxng.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
+import { createWebFetchTool } from '../tools/web-fetch.js';
+import { createWebSearchTool } from '../tools/web-search.js';
+import { DEFAULT_BACKEND_CONFIG } from './config.js';
+function invalidSearxngSearch() {
+    return async function search() {
+        const result = {
+            status: 'error',
+            results: [],
+            metadata: { backend: 'searxng', cacheHit: false },
+            error: {
+                code: 'BACKEND_CONFIG_INVALID',
+                message: 'SearXNG search requires backends.search.baseUrl.'
+            }
+        };
+        return { ...result, presentation: buildSearchPresentation(result) };
+    };
+}
+function invalidFirecrawlFetch() {
+    return async function fetchPage(url) {
+        const result = {
+            status: 'error',
+            url,
+            metadata: { method: 'firecrawl', cacheHit: false },
+            error: {
+                code: 'BACKEND_CONFIG_INVALID',
+                message: 'Firecrawl fetch requires backends.fetch.baseUrl.'
+            }
+        };
+        return { ...result, presentation: buildFetchPresentation(result) };
+    };
+}
+export function createBackendSet(config = DEFAULT_BACKEND_CONFIG) {
+    const search = config.search.provider === 'searxng'
+        ? config.search.baseUrl
+            ? createSearxngSearchTool({ baseUrl: config.search.baseUrl })
+            : invalidSearxngSearch()
+        : createWebSearchTool();
+    const fetchPage = config.fetch.provider === 'firecrawl'
+        ? config.fetch.baseUrl
+            ? createWebFetchTool({
+                fetchPage: createFirecrawlFetcher({
+                    baseUrl: config.fetch.baseUrl,
+                    apiKey: config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY
+                })
+            })
+            : createWebFetchTool({ fetchPage: invalidFirecrawlFetch() })
+        : createWebFetchTool();
+    return {
+        search,
+        fetchPage,
+        headlessFetch: createWebFetchHeadlessTool()
+    };
+}

package/dist/commands/web-agent-config.d.ts

@@ -1,10 +1,20 @@
+import { type BackendConfig } from '../backends/config.js';
 import { type ExtensionAPI } from '@mariozechner/pi-coding-agent';
 import { loadPresentationConfigLayers, type LoadedPresentationConfig } from '../presentation/config-store.js';
+import { type BrowserResolutionResult } from '../fetch/browser-resolution.js';
 import type { PresentationConfig, PresentationConfigOverride, PresentationScope } from '../presentation/types.js';
 type CommandDeps = {
     load?: () => ReturnType<typeof loadPresentationConfigLayers>;
     save?: (scope: PresentationScope, config: PresentationConfigOverride) => Promise<void>;
     reset?: (scope: PresentationScope) => Promise<void>;
+    resolveBrowser?: () => Promise<BrowserResolutionResult>;
+    runtime?: {
+        nodeVersion: string;
+        platform: string;
+        arch: string;
+    };
+    checkTypebox?: () => Promise<boolean>;
+    checkBackends?: (config: BackendConfig) => Promise<string[]>;
 };
 export type SettingsDraftState = {
     scope: PresentationScope;

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

@@ -1,7 +1,10 @@
-import { getSettingsListTheme } from '@mariozechner/pi-coding-agent';
-import { Container, SettingsList, Text } from '@mariozechner/pi-tui';
+import { DEFAULT_BACKEND_CONFIG, validateBackendConfig } from '../backends/config.js';
+import { checkBackendHealth } from '../backends/doctor.js';
+import { DynamicBorder, getSettingsListTheme } from '@mariozechner/pi-coding-agent';
+import { Container, SelectList, SettingsList, Text } from '@mariozechner/pi-tui';
 import { DEFAULT_PRESENTATION_CONFIG, mergePresentationConfigLayers, resolvePresentationMode } from '../presentation/config.js';
 import { loadPresentationConfigLayers, resetPresentationConfigScope, savePresentationConfigScope } from '../presentation/config-store.js';
+import { resolveBrowserExecutable } from '../fetch/browser-resolution.js';
 const PRESENTATION_TOOL_NAMES = ['web_explore'];
 function parseScopeToken(token) {
     return token === 'global' || token === 'project' ? token : undefined;
@@ -12,6 +15,28 @@ function clonePresentationConfig(config) {
         tools: { ...config.tools }
     };
 }
+async function defaultCheckTypebox() {
+    try {
+        await import('typebox');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatBackendSummary(config = DEFAULT_BACKEND_CONFIG) {
+    const search = config.search.baseUrl
+        ? `search: ${config.search.provider} (${config.search.baseUrl})`
+        : `search: ${config.search.provider}`;
+    const fetch = config.fetch.baseUrl
+        ? `fetch: ${config.fetch.provider} (${config.fetch.baseUrl})`
+        : `fetch: ${config.fetch.provider}`;
+    return [
+        search,
+        fetch,
+        `headless: ${config.headless.provider}`
+    ].join('\n');
+}
 function formatConfigSummary(config) {
     const lines = [`defaultMode: ${config.defaultMode}`];
     for (const toolName of PRESENTATION_TOOL_NAMES) {
@@ -137,6 +162,40 @@ export function handleSettingsShortcut(data) {
     }
     return undefined;
 }
+async function openActionMenu(ctx) {
+    return ctx.ui.custom((tui, theme, _kb, done) => {
+        const container = new Container();
+        const items = [
+            { value: 'settings', label: 'Settings', description: 'Edit presentation modes' },
+            { value: 'show', label: 'Show config', description: 'Print effective config paths and modes' },
+            { value: 'doctor', label: 'Doctor', description: 'Check runtime dependencies and browser detection' },
+            { value: 'reset-project', label: 'Reset project config', description: 'Delete project-level overrides' },
+            { value: 'reset-global', label: 'Reset global config', description: 'Delete global overrides' }
+        ];
+        container.addChild(new DynamicBorder((text) => theme.fg('accent', text)));
+        container.addChild(new Text(theme.fg('accent', theme.bold('pi-web-agent')), 1, 0));
+        const list = new SelectList(items, Math.min(items.length, 8), {
+            selectedPrefix: (text) => theme.fg('accent', text),
+            selectedText: (text) => theme.fg('accent', text),
+            description: (text) => theme.fg('muted', text),
+            scrollInfo: (text) => theme.fg('dim', text),
+            noMatch: (text) => theme.fg('warning', text)
+        });
+        list.onSelect = (item) => done(item.value);
+        list.onCancel = () => done(undefined);
+        container.addChild(list);
+        container.addChild(new Text(theme.fg('dim', '↑↓ navigate • enter select • esc cancel'), 1, 0));
+        container.addChild(new DynamicBorder((text) => theme.fg('accent', text)));
+        return {
+            render: (width) => container.render(width),
+            invalidate: () => container.invalidate(),
+            handleInput: (data) => {
+                list.handleInput?.(data);
+                tui.requestRender?.();
+            }
+        };
+    });
+}
 async function openSettingsUi(ctx, loaded, initialScope) {
     return ctx.ui.custom((_tui, theme, _kb, done) => {
         let state = createSettingsDraftState(loaded, initialScope);
@@ -182,14 +241,63 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
     const load = deps.load ?? (() => loadPresentationConfigLayers());
     const save = deps.save ?? ((scope, config) => savePresentationConfigScope({}, scope, config));
     const reset = deps.reset ?? ((scope) => resetPresentationConfigScope({}, scope));
+    const resolveBrowser = deps.resolveBrowser ?? (() => resolveBrowserExecutable({}));
+    const runtime = deps.runtime ?? {
+        nodeVersion: process.version,
+        platform: process.platform,
+        arch: process.arch
+    };
+    const checkTypebox = deps.checkTypebox ?? defaultCheckTypebox;
+    const checkBackends = deps.checkBackends ?? ((config) => checkBackendHealth(config));
     pi.registerCommand('web-agent', {
         description: 'Open settings or manage pi-web-agent presentation config',
         handler: async (args, ctx) => {
-            const [action, maybeScope] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+            let [action, maybeScope] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+            if (!action) {
+                const selectedAction = await openActionMenu(ctx);
+                if (!selectedAction)
+                    return;
+                if (selectedAction === 'reset-project') {
+                    action = 'reset';
+                    maybeScope = 'project';
+                }
+                else if (selectedAction === 'reset-global') {
+                    action = 'reset';
+                    maybeScope = 'global';
+                }
+                else {
+                    action = selectedAction;
+                }
+            }
+            if (action === 'doctor') {
+                const [typeboxOk, browser, loaded] = await Promise.all([checkTypebox(), resolveBrowser(), load()]);
+                const backendConfig = loaded.effectiveBackends ?? DEFAULT_BACKEND_CONFIG;
+                const backendIssues = validateBackendConfig(backendConfig);
+                const backendHealth = await checkBackends(backendConfig);
+                const lines = [
+                    'pi-web-agent: loaded',
+                    `runtime: node ${runtime.nodeVersion} ${runtime.platform} ${runtime.arch}`,
+                    `typebox: ${typeboxOk ? 'ok' : 'missing'}`,
+                    formatBackendSummary(backendConfig),
+                    backendIssues.length > 0 ? `backend config: warning\n${backendIssues.join('\n')}` : 'backend config: ok',
+                    ...backendHealth
+                ];
+                if (browser.ok) {
+                    lines.push(`browser: ${browser.browser} ${browser.executablePath}`);
+                }
+                else {
+                    lines.push(`browser: missing (${browser.error.code})`);
+                    lines.push(browser.error.message);
+                    lines.push('Install Chrome, Chromium, Edge, or Brave and run /web-agent doctor again.');
+                }
+                ctx.ui.notify(lines.join('\n'), 'info');
+                return;
+            }
             if (action === 'show') {
                 const loaded = await load();
                 ctx.ui.notify([
                     formatConfigSummary(loaded.effectiveConfig),
+                    formatBackendSummary(loaded.effectiveBackends ?? DEFAULT_BACKEND_CONFIG),
                     `global: ${loaded.global.path}${loaded.global.exists ? '' : ' (missing)'}`,
                     `project: ${loaded.project.path}${loaded.project.exists ? '' : ' (missing)'}`
                 ].join('\n'), 'info');
@@ -243,7 +351,7 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
                 ctx.ui.notify(`Saved ${result.scope} config`, 'info');
                 return;
             }
-            ctx.ui.notify('Use /web-agent, /web-agent show, /web-agent reset project, or /web-agent settings', 'info');
+            ctx.ui.notify('Use /web-agent, /web-agent show, /web-agent doctor, /web-agent reset project, or /web-agent settings', 'info');
         }
     });
 }

package/dist/extension.js

@@ -1,19 +1,33 @@
-import { Type } from '@sinclair/typebox';
+import { DEFAULT_BACKEND_CONFIG } from './backends/config.js';
+import { Type } from 'typebox';
 import { registerWebAgentConfigCommands } from './commands/web-agent-config.js';
 import { DEFAULT_PRESENTATION_CONFIG, resolvePresentationMode } from './presentation/config.js';
+import { createResearchWorkflow } from './orchestration/index.js';
 import { loadPresentationConfigLayers } from './presentation/config-store.js';
 import { selectPresentationView } from './presentation/select-view.js';
 import { createWebExploreTool } from './tools/web-explore.js';
-async function getEffectivePresentationConfig(pi) {
+async function loadWebAgentConfig(pi) {
     const store = pi.__presentationConfigStore;
+    return store?.load?.() ?? loadPresentationConfigLayers();
+}
+async function getEffectivePresentationConfig(pi) {
     try {
-        const loaded = await (store?.load?.() ?? loadPresentationConfigLayers());
+        const loaded = await loadWebAgentConfig(pi);
         return loaded.effectiveConfig;
     }
     catch {
         return DEFAULT_PRESENTATION_CONFIG;
     }
 }
+async function getEffectiveBackendConfig(pi) {
+    try {
+        const loaded = await loadWebAgentConfig(pi);
+        return loaded.effectiveBackends ?? DEFAULT_BACKEND_CONFIG;
+    }
+    catch {
+        return DEFAULT_BACKEND_CONFIG;
+    }
+}
 async function renderToolText(pi, toolName, details) {
     const config = await getEffectivePresentationConfig(pi);
     const mode = resolvePresentationMode(toolName, config);
@@ -21,8 +35,22 @@ async function renderToolText(pi, toolName, details) {
 }
 export default function extension(pi) {
     registerWebAgentConfigCommands(pi);
-    const webExplore = pi.__webExploreTool ??
-        createWebExploreTool();
+    const injectedWebExplore = pi.__webExploreTool;
+    let cachedBackendKey;
+    let cachedWebExplore;
+    async function getConfiguredWebExplore() {
+        if (injectedWebExplore)
+            return injectedWebExplore;
+        const backendConfig = await getEffectiveBackendConfig(pi);
+        const backendKey = JSON.stringify(backendConfig);
+        if (!cachedWebExplore || cachedBackendKey !== backendKey) {
+            cachedBackendKey = backendKey;
+            cachedWebExplore = createWebExploreTool({
+                explore: createResearchWorkflow({ backendConfig })
+            });
+        }
+        return cachedWebExplore;
+    }
     pi.on('before_agent_start', async (event) => ({
         systemPrompt: `${event.systemPrompt}\n\n` +
             'For web research questions that require finding and comparing sources, use web_explore. ' +
@@ -37,6 +65,7 @@ export default function extension(pi) {
             query: Type.String({ description: 'Web research question to explore.' })
         }),
         async execute(_toolCallId, params) {
+            const webExplore = await getConfiguredWebExplore();
             const result = await webExplore({ query: params.query });
             return {
                 content: [

package/dist/fetch/browser-resolution.d.ts

@@ -1,7 +1,9 @@
+type SupportedPlatform = NodeJS.Platform | string;
+type BrowserName = 'configured' | 'chrome' | 'edge' | 'brave' | 'chromium';
 export type BrowserResolutionResult = {
     ok: true;
     executablePath: string;
-    browser: 'configured' | 'chrome' | 'edge';
+    browser: BrowserName;
 } | {
     ok: false;
     error: {
@@ -9,7 +11,10 @@ export type BrowserResolutionResult = {
         message: string;
     };
 };
-export declare function resolveBrowserExecutable({ configuredPath, fileExists }: {
+export declare function resolveBrowserExecutable({ configuredPath, platform, env, fileExists }: {
     configuredPath?: string;
+    platform?: SupportedPlatform;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
     fileExists?: (path: string) => Promise<boolean>;
 }): Promise<BrowserResolutionResult>;
+export {};

package/dist/fetch/browser-resolution.js

@@ -1,14 +1,82 @@
-const WINDOWS_CANDIDATES = {
-    chrome: [
-        'C:/Program Files/Google/Chrome/Application/chrome.exe',
-        'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe'
-    ],
-    edge: [
-        'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
-        'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe'
-    ]
-};
-export async function resolveBrowserExecutable({ configuredPath, fileExists = defaultFileExists }) {
+const WINDOWS_CANDIDATES = [
+    {
+        browser: 'chrome',
+        paths: [
+            'C:/Program Files/Google/Chrome/Application/chrome.exe',
+            'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe'
+        ],
+        commands: ['chrome.exe', 'chrome', 'google-chrome']
+    },
+    {
+        browser: 'edge',
+        paths: [
+            'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
+            'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe'
+        ],
+        commands: ['msedge.exe', 'msedge', 'microsoft-edge']
+    },
+    {
+        browser: 'brave',
+        paths: [
+            'C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe',
+            'C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe'
+        ],
+        commands: ['brave.exe', 'brave']
+    },
+    {
+        browser: 'chromium',
+        paths: [
+            'C:/Program Files/Chromium/Application/chrome.exe',
+            'C:/Program Files (x86)/Chromium/Application/chrome.exe'
+        ],
+        commands: ['chromium.exe', 'chromium']
+    }
+];
+const MACOS_CANDIDATES = [
+    {
+        browser: 'chrome',
+        paths: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+        commands: ['google-chrome', 'chrome']
+    },
+    {
+        browser: 'edge',
+        paths: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        commands: ['microsoft-edge', 'msedge']
+    },
+    {
+        browser: 'brave',
+        paths: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
+        commands: ['brave-browser', 'brave']
+    },
+    {
+        browser: 'chromium',
+        paths: ['/Applications/Chromium.app/Contents/MacOS/Chromium'],
+        commands: ['chromium', 'chromium-browser']
+    }
+];
+const LINUX_CANDIDATES = [
+    {
+        browser: 'chrome',
+        paths: ['/usr/bin/google-chrome', '/usr/local/bin/google-chrome', '/opt/google/chrome/chrome'],
+        commands: ['google-chrome', 'google-chrome-stable', 'chrome']
+    },
+    {
+        browser: 'edge',
+        paths: ['/usr/bin/microsoft-edge', '/opt/microsoft/msedge/msedge'],
+        commands: ['microsoft-edge', 'microsoft-edge-stable', 'msedge']
+    },
+    {
+        browser: 'brave',
+        paths: ['/usr/bin/brave-browser', '/usr/local/bin/brave-browser', '/opt/brave.com/brave/brave'],
+        commands: ['brave-browser', 'brave']
+    },
+    {
+        browser: 'chromium',
+        paths: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
+        commands: ['chromium', 'chromium-browser']
+    }
+];
+export async function resolveBrowserExecutable({ configuredPath, platform = process.platform, env = process.env, fileExists = defaultFileExists }) {
     if (configuredPath) {
         if (await fileExists(configuredPath)) {
             return {
@@ -25,14 +93,19 @@ export async function resolveBrowserExecutable({ configuredPath, fileExists = de
             }
         };
     }
-    for (const path of WINDOWS_CANDIDATES.chrome) {
-        if (await fileExists(path)) {
-            return { ok: true, executablePath: path, browser: 'chrome' };
+    const candidates = getCandidatesForPlatform(platform);
+    for (const candidate of candidates) {
+        for (const path of candidate.paths) {
+            if (await fileExists(path)) {
+                return { ok: true, executablePath: path, browser: candidate.browser };
+            }
         }
     }
-    for (const path of WINDOWS_CANDIDATES.edge) {
-        if (await fileExists(path)) {
-            return { ok: true, executablePath: path, browser: 'edge' };
+    for (const candidate of candidates) {
+        for (const path of getPathCommandCandidates(candidate.commands, platform, env)) {
+            if (await fileExists(path)) {
+                return { ok: true, executablePath: path, browser: candidate.browser };
+            }
         }
     }
     return {
@@ -43,6 +116,27 @@ export async function resolveBrowserExecutable({ configuredPath, fileExists = de
         }
     };
 }
+function getCandidatesForPlatform(platform) {
+    if (platform === 'win32')
+        return WINDOWS_CANDIDATES;
+    if (platform === 'darwin')
+        return MACOS_CANDIDATES;
+    if (platform === 'linux')
+        return LINUX_CANDIDATES;
+    return [...WINDOWS_CANDIDATES, ...MACOS_CANDIDATES, ...LINUX_CANDIDATES];
+}
+function getPathCommandCandidates(commands, platform, env) {
+    const pathValue = env.PATH ?? env.Path ?? env.path;
+    if (!pathValue)
+        return [];
+    const delimiter = platform === 'win32' ? ';' : ':';
+    const dirs = pathValue.split(delimiter).filter(Boolean);
+    const extensions = platform === 'win32' ? ['', '.exe'] : [''];
+    return dirs.flatMap((dir) => commands.flatMap((command) => extensions.map((extension) => {
+        const normalizedCommand = command.toLowerCase().endsWith(extension) ? command : `${command}${extension}`;
+        return `${dir.replace(/[\\/]$/, '')}/${normalizedCommand}`;
+    })));
+}
 async function defaultFileExists(path) {
     try {
         const { access } = await import('node:fs/promises');

package/dist/fetch/firecrawl-fetch.d.ts

@@ -0,0 +1,6 @@
+import type { WebFetchResponse } from '../types.js';
+export declare function createFirecrawlFetcher({ baseUrl, apiKey, fetchImpl }: {
+    baseUrl: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}): (url: string) => Promise<WebFetchResponse>;

package/dist/fetch/firecrawl-fetch.js

@@ -0,0 +1,61 @@
+function buildScrapeUrl(baseUrl) {
+    return new URL('/v1/scrape', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`).toString();
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createFirecrawlFetcher({ baseUrl, apiKey, fetchImpl = fetch }) {
+    return async function firecrawlFetch(url) {
+        try {
+            const headers = { 'content-type': 'application/json' };
+            if (apiKey) {
+                headers.Authorization = `Bearer ${apiKey}`;
+            }
+            const response = await fetchImpl(buildScrapeUrl(baseUrl), {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ url, formats: ['markdown'] })
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const parsed = (await response.json());
+            if (parsed.success === false) {
+                throw new Error(typeof parsed.error === 'string' ? parsed.error : 'Firecrawl scrape failed.');
+            }
+            const text = typeof parsed.data?.markdown === 'string'
+                ? parsed.data.markdown
+                : typeof parsed.data?.html === 'string'
+                    ? parsed.data.html
+                    : '';
+            const resolvedUrl = typeof parsed.data?.metadata?.sourceURL === 'string'
+                ? parsed.data.metadata.sourceURL
+                : url;
+            const title = typeof parsed.data?.metadata?.title === 'string'
+                ? parsed.data.metadata.title
+                : undefined;
+            if (!text.trim()) {
+                return {
+                    status: 'needs_headless',
+                    url: resolvedUrl,
+                    metadata: { method: 'firecrawl', cacheHit: false },
+                    error: { code: 'WEAK_EXTRACTION', message: 'Firecrawl did not return useful page text.' }
+                };
+            }
+            return {
+                status: 'ok',
+                url: resolvedUrl,
+                content: { title, text },
+                metadata: { method: 'firecrawl', cacheHit: false, truncated: text.length >= 4000 }
+            };
+        }
+        catch (error) {
+            return {
+                status: 'error',
+                url,
+                metadata: { method: 'firecrawl', cacheHit: false },
+                error: { code: 'FETCH_FAILED', message: `Firecrawl scrape failed: ${errorMessage(error)}` }
+            };
+        }
+    };
+}

package/dist/orchestration/index.d.ts

@@ -1,5 +1,7 @@
+import type { BackendConfig } from '../backends/config.js';
 import type { WebFetchHeadlessResponse, WebFetchResponse, WebSearchResponse } from '../types.js';
-export declare function createResearchWorkflow({ search, fetchPage, headlessFetch }?: {
+export declare function createResearchWorkflow({ backendConfig, search, fetchPage, headlessFetch }?: {
+    backendConfig?: BackendConfig;
     search?: (input: {
         query: string;
     }) => Promise<WebSearchResponse>;

package/dist/orchestration/index.js

@@ -1,9 +1,11 @@
-import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
-import { createWebFetchTool } from '../tools/web-fetch.js';
-import { createWebSearchTool } from '../tools/web-search.js';
+import { createBackendSet } from '../backends/factory.js';
 import { createResearchOrchestrator } from './research-orchestrator.js';
 import { createResearchWorker } from './research-worker.js';
-export function createResearchWorkflow({ search = createWebSearchTool(), fetchPage = createWebFetchTool(), headlessFetch = createWebFetchHeadlessTool() } = {}) {
-    const worker = createResearchWorker({ search, fetchPage });
-    return createResearchOrchestrator({ worker, headlessFetch });
+export function createResearchWorkflow({ backendConfig, search, fetchPage, headlessFetch } = {}) {
+    const backends = createBackendSet(backendConfig);
+    const resolvedSearch = search ?? backends.search;
+    const resolvedFetchPage = fetchPage ?? backends.fetchPage;
+    const resolvedHeadlessFetch = headlessFetch ?? backends.headlessFetch;
+    const worker = createResearchWorker({ search: resolvedSearch, fetchPage: resolvedFetchPage });
+    return createResearchOrchestrator({ worker, headlessFetch: resolvedHeadlessFetch });
 }

package/dist/orchestration/research-types.d.ts

@@ -1,5 +1,5 @@
 export type ResearchSourceKind = 'official-docs' | 'official-api' | 'official-discussion' | 'community' | 'issue-thread' | 'package-page' | 'other';
-export type ResearchMethod = 'search' | 'http' | 'headless';
+export type ResearchMethod = 'search' | 'http' | 'headless' | 'firecrawl';
 export type ResearchEvidence = {
     title: string;
     url: string;

package/dist/presentation/config-store.d.ts

@@ -1,3 +1,4 @@
+import { type BackendConfig, type BackendConfigOverride } from '../backends/config.js';
 import type { PresentationConfig, PresentationConfigOverride, PresentationScope } from './types.js';
 export type PresentationConfigStoreOptions = {
     homeDir?: string;
@@ -7,12 +8,14 @@ export type PresentationConfigLayer = {
     path: string;
     exists: boolean;
     rawConfig?: PresentationConfigOverride;
+    rawBackends?: BackendConfigOverride;
     error?: string;
 };
 export type LoadedPresentationConfig = {
     global: PresentationConfigLayer;
     project: PresentationConfigLayer;
     effectiveConfig: PresentationConfig;
+    effectiveBackends: BackendConfig;
 };
 export declare function getPresentationConfigPaths(options?: PresentationConfigStoreOptions): {
     globalPath: string;

package/dist/presentation/config-store.js

@@ -1,5 +1,6 @@
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { DEFAULT_BACKEND_CONFIG, extractBackendConfigOverride, mergeBackendConfigLayers } from '../backends/config.js';
 import { DEFAULT_PRESENTATION_CONFIG, extractPresentationConfigOverride, mergePresentationConfigLayers } from './config.js';
 export function getPresentationConfigPaths(options = {}) {
     const homeDir = options.homeDir ?? process.env.USERPROFILE ?? process.env.HOME ?? '';
@@ -9,14 +10,21 @@ export function getPresentationConfigPaths(options = {}) {
         projectPath: path.join(projectDir, '.pi', 'extensions', 'pi-web-agent', 'config.json')
     };
 }
+function hasPresentationRoot(parsed) {
+    return parsed.presentation !== undefined;
+}
 async function readPresentationConfigFile(filePath) {
     try {
         const rawText = await readFile(filePath, 'utf8');
         const parsed = JSON.parse(rawText);
+        const presentationFile = hasPresentationRoot(parsed)
+            ? parsed
+            : { presentation: parsed };
         return {
             path: filePath,
             exists: true,
-            rawConfig: extractPresentationConfigOverride(parsed)
+            rawConfig: extractPresentationConfigOverride(presentationFile),
+            rawBackends: extractBackendConfigOverride(parsed)
         };
     }
     catch (error) {
@@ -48,7 +56,8 @@ export async function loadPresentationConfigLayers(options = {}) {
     return {
         global,
         project,
-        effectiveConfig: mergePresentationConfigLayers(DEFAULT_PRESENTATION_CONFIG, global.rawConfig, project.rawConfig)
+        effectiveConfig: mergePresentationConfigLayers(DEFAULT_PRESENTATION_CONFIG, global.rawConfig, project.rawConfig),
+        effectiveBackends: mergeBackendConfigLayers(DEFAULT_BACKEND_CONFIG, global.rawBackends, project.rawBackends)
     };
 }
 export async function savePresentationConfigScope(options, scope, config) {

package/dist/presentation/explore-presentation.js

@@ -1,6 +1,8 @@
 function internalReaderLabel(method) {
     if (method === 'headless')
         return 'web_fetch_headless';
+    if (method === 'firecrawl')
+        return 'firecrawl';
     if (method === 'http')
         return 'web_fetch';
     return 'web_explore';

package/dist/search/searxng.d.ts

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

package/dist/search/searxng.js

@@ -0,0 +1,66 @@
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+function buildSearchUrl(baseUrl, query) {
+    const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+    url.searchParams.set('q', query);
+    url.searchParams.set('format', 'json');
+    return url.toString();
+}
+function normalizeResults(response) {
+    return (response.results ?? []).flatMap((result) => {
+        if (typeof result.title !== 'string' || typeof result.url !== 'string') {
+            return [];
+        }
+        return [
+            {
+                title: result.title,
+                url: result.url,
+                snippet: typeof result.content === 'string' ? result.content : ''
+            }
+        ];
+    });
+}
+export function createSearxngSearchTool({ baseUrl, fetchImpl = fetch }) {
+    return async function searxngSearch({ query }) {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery) {
+            const result = {
+                status: 'error',
+                results: [],
+                metadata: { backend: 'searxng', cacheHit: false },
+                error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
+            };
+            return { ...result, presentation: buildSearchPresentation(result) };
+        }
+        try {
+            const response = await fetchImpl(buildSearchUrl(baseUrl, normalizedQuery));
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const parsed = (await response.json());
+            const results = normalizeResults(parsed);
+            const result = results.length > 0
+                ? {
+                    status: 'ok',
+                    results,
+                    metadata: { backend: 'searxng', cacheHit: false }
+                }
+                : {
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'searxng', cacheHit: false },
+                    error: { code: 'NO_RESULTS', message: 'SearXNG returned no usable results for this query.' }
+                };
+            return { ...result, presentation: buildSearchPresentation(result) };
+        }
+        catch (error) {
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            const result = {
+                status: 'error',
+                results: [],
+                metadata: { backend: 'searxng', cacheHit: false },
+                error: { code: 'FETCH_FAILED', message: `SearXNG search request failed: ${rawMessage}` }
+            };
+            return { ...result, presentation: buildSearchPresentation(result) };
+        }
+    };
+}

package/dist/tools/web-explore.d.ts

@@ -31,7 +31,7 @@ export declare function createWebExploreTool({ explore }?: {
     sources: Array<{
         title: string;
         url: string;
-        method?: "http" | "headless";
+        method?: "http" | "headless" | "firecrawl";
     }>;
     caveat?: string;
     metadata?: {

package/dist/types.d.ts

@@ -11,15 +11,15 @@ export type ToolError = {
     message: string;
 };
 export type SearchMetadata = {
-    backend: 'duckduckgo';
+    backend: 'duckduckgo' | 'searxng';
     cacheHit: boolean;
 };
 export type FetchMetadata = {
-    method: 'http' | 'headless';
+    method: 'http' | 'headless' | 'firecrawl';
     cacheHit: boolean;
     contentType?: string;
     truncated?: boolean;
-    browser?: 'configured' | 'chrome' | 'edge';
+    browser?: 'configured' | 'chrome' | 'edge' | 'brave' | 'chromium';
     navigationMs?: number;
 };
 export type ExtractedContent = {
@@ -56,7 +56,7 @@ export type WebExploreResponse = {
     sources: Array<{
         title: string;
         url: string;
-        method?: 'http' | 'headless';
+        method?: 'http' | 'headless' | 'firecrawl';
     }>;
     caveat?: string;
     metadata?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demigodmode/pi-web-agent",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
   "type": "module",
   "main": "./dist/extension.js",
@@ -56,11 +56,11 @@
     "@mozilla/readability": "^0.6.0",
     "cheerio": "^1.1.0",
     "jsdom": "^26.0.0",
-    "playwright-core": "^1.54.0"
+    "playwright-core": "^1.54.0",
+    "typebox": "^1.1.37"
   },
   "devDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.67.2",
-    "@sinclair/typebox": "^0.34.41",
+    "@mariozechner/pi-coding-agent": "^0.69.0",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.4",
@@ -69,7 +69,6 @@
     "vitest": "^3.2.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "@mariozechner/pi-coding-agent": "*"
   }
 }