@demigodmode/pi-web-agent 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -18,9 +18,24 @@ The format is intentionally simple and release-oriented.
 ### Breaking
 - None.
 
+## [1.9.0] - 2026-08-15
+### Added
+- Search fanout. Ask a hard question and web_explore can now hit several of your configured search backends at once, dedupe the merged results, and rank the pages that more than one provider agreed on to the top. Off by default. Flip it to on or auto in Settings → Backends (auto only fans out when the first provider comes back thin, so easy queries stay cheap). Preview/verbose shows which providers ran and which got skipped. (#35)
+
+### Changed
+- None.
+
+### Fixed
+- web_explore can finally summarize a link you hand it. Paste a GitHub file/issue/PR, a PDF, or a YouTube URL and ask for a summary: it now reads the actual content (raw source, extracted PDF text, the video transcript) and gives the model the whole thing. 1.8.0 added these readers but then squeezed everything down to a ~180-char snippet before the model ever saw it, so summaries were basically guesswork. Now they're grounded in the real text (long content still capped around 24k characters). (#40, #41)
+- Fanout won't stall on a dead provider anymore. Each one gets an 8s timeout, so an unreachable self-hosted SearXNG can't hang a whole research pass. (#35)
+- Fanout only offers and queries the providers you've actually set up (keyless DuckDuckGo, SearXNG when you give it a URL, the hosted ones only when their key is present) instead of acting like all six are on. (#35)
+
+### Breaking
+- None.
+
 ## [1.8.0] - 2026-08-14
 ### Added
-- Read the content behind GitHub, PDF, and YouTube links directly instead of the page shell. GitHub files, issues and PRs come from the API/raw endpoints (optional `GITHUB_TOKEN` raises the rate limit), PDFs are parsed with unpdf, and YouTube links return the transcript. All keyless. Scanned PDFs and caption-less videos are caveated rather than failing. (#39, #40, #41)
+- Read the content behind GitHub, PDF, and YouTube links directly instead of the page shell. GitHub files, issues and PRs come from the API/raw endpoints (optional `GITHUB_TOKEN` raises the rate limit), PDFs are parsed with unpdf, and YouTube links return the transcript (long content capped around 24k characters). All keyless. Scanned PDFs and caption-less videos are caveated rather than failing. (#39, #40, #41)
 
 ### Changed
 - None.

package/dist/backends/config.d.ts

@@ -1,8 +1,13 @@
+import type { FanoutMode, SearchProviderName } from '../types.js';
 export type SearxngOptions = {
     categories?: string[];
     language?: string;
     safesearch?: 0 | 1 | 2;
 };
+export type FanoutConfig = {
+    mode: FanoutMode;
+    providers?: SearchProviderName[];
+};
 export type FirecrawlOptions = {
     formats?: string[];
     onlyMainContent?: boolean;
@@ -12,6 +17,7 @@ export type SearchBackendConfig = {
     baseUrl?: string;
     fallback?: 'duckduckgo';
     options?: SearxngOptions;
+    fanout?: FanoutConfig;
 };
 export type FetchBackendConfig = {
     provider: 'http' | 'firecrawl';
@@ -40,6 +46,7 @@ export type BackendConfigFile = {
             baseUrl?: unknown;
             fallback?: unknown;
             options?: unknown;
+            fanout?: unknown;
         };
         fetch?: {
             provider?: unknown;
@@ -54,6 +61,7 @@ export type BackendConfigFile = {
     };
 };
 export declare const DEFAULT_BACKEND_CONFIG: BackendConfig;
+export declare function usableSearchProviders(search: SearchBackendConfig, env?: NodeJS.ProcessEnv): SearchProviderName[];
 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

@@ -35,6 +35,38 @@ function extractFirecrawlOptions(value) {
         options.onlyMainContent = raw.onlyMainContent;
     return Object.keys(options).length > 0 ? options : undefined;
 }
+const PROVIDER_NAMES = ['duckduckgo', 'searxng', 'brave', 'youcom', 'exa', 'tavily'];
+export function usableSearchProviders(search, env = process.env) {
+    // Match the provider implementations, which treat a blank/whitespace key as unconfigured.
+    const usable = ['duckduckgo']; // keyless, always usable
+    if (search.baseUrl?.trim())
+        usable.push('searxng');
+    if (env.PI_WEB_AGENT_BRAVE_API_KEY?.trim())
+        usable.push('brave');
+    if (env.YDC_API_KEY?.trim())
+        usable.push('youcom');
+    if (env.EXA_API_KEY?.trim())
+        usable.push('exa');
+    if (env.TAVILY_API_KEY?.trim())
+        usable.push('tavily');
+    return usable;
+}
+function extractFanoutConfig(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    if (raw.mode !== 'off' && raw.mode !== 'on' && raw.mode !== 'auto')
+        return undefined;
+    const config = { mode: raw.mode };
+    if (Array.isArray(raw.providers)) {
+        const providers = raw.providers.filter((p) => typeof p === 'string' && PROVIDER_NAMES.includes(p));
+        if (providers.length !== raw.providers.length)
+            return undefined; // fail loud on any invalid entry
+        if (providers.length > 0)
+            config.providers = providers;
+    }
+    return config;
+}
 export function extractBackendConfigOverride(file) {
     const backends = file?.backends;
     const override = {};
@@ -58,6 +90,10 @@ export function extractBackendConfigOverride(file) {
             }
         }
     }
+    const fanout = extractFanoutConfig(backends?.search?.fanout);
+    if (fanout) {
+        override.search = { ...(override.search ?? {}), fanout };
+    }
     if (backends?.fetch?.provider === 'http' || backends?.fetch?.provider === 'firecrawl') {
         override.fetch = { provider: backends.fetch.provider };
         if (typeof backends.fetch.baseUrl === 'string') {
@@ -106,6 +142,15 @@ export function validateBackendConfig(config) {
     if (config.fetch.options?.formats && config.fetch.options.formats.length === 0) {
         issues.push('fetch options.formats must contain at least one format when provided');
     }
+    const fanout = config.search.fanout;
+    if (fanout) {
+        if (fanout.mode !== 'off' && fanout.mode !== 'on' && fanout.mode !== 'auto') {
+            issues.push('search fanout.mode must be off, on, or auto');
+        }
+        if (fanout.providers?.includes('searxng') && !config.search.baseUrl) {
+            issues.push('search fanout with searxng requires backends.search.baseUrl');
+        }
+    }
     return issues;
 }
 function mergeSearchConfig(current, override) {

package/dist/backends/doctor.js

@@ -208,6 +208,39 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
     if (config.search.fallback) {
         lines.push(`search fallback: ${config.search.fallback}`);
     }
+    if (config.search.fanout && config.search.fanout.mode !== 'off') {
+        const providers = config.search.fanout.providers || ['duckduckgo', 'searxng', 'brave', 'youcom', 'exa', 'tavily'];
+        lines.push(`search fanout: ${config.search.fanout.mode} (${providers.join(', ')})`);
+        for (const provider of providers) {
+            if (provider === 'searxng' && !config.search.baseUrl) {
+                lines.push('search fanout provider searxng warning (missing baseUrl)');
+            }
+            else if (provider === 'brave') {
+                const apiKey = process.env.PI_WEB_AGENT_BRAVE_API_KEY;
+                if (!apiKey?.trim()) {
+                    lines.push('search fanout provider brave warning (missing PI_WEB_AGENT_BRAVE_API_KEY)');
+                }
+            }
+            else if (provider === 'youcom') {
+                const apiKey = process.env.YDC_API_KEY;
+                if (!apiKey?.trim()) {
+                    lines.push('search fanout provider youcom warning (missing YDC_API_KEY)');
+                }
+            }
+            else if (provider === 'exa') {
+                const apiKey = process.env.EXA_API_KEY;
+                if (!apiKey?.trim()) {
+                    lines.push('search fanout provider exa warning (missing EXA_API_KEY)');
+                }
+            }
+            else if (provider === 'tavily') {
+                const apiKey = process.env.TAVILY_API_KEY;
+                if (!apiKey?.trim()) {
+                    lines.push('search fanout provider tavily warning (missing TAVILY_API_KEY)');
+                }
+            }
+        }
+    }
     if (config.fetch.provider === 'http') {
         lines.push('fetch backend: http');
     }

package/dist/backends/factory.js

@@ -4,12 +4,13 @@ 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 { createFanoutSearch } from '../search/fanout.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';
+import { DEFAULT_BACKEND_CONFIG, usableSearchProviders } from './config.js';
 import { createSpecialContentResolver } from '../readers/resolver.js';
 import { createGithubReader } from '../readers/github-reader.js';
 import { createPdfReader } from '../readers/pdf-reader.js';
@@ -86,6 +87,25 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
     const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
     const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
     const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
+    function buildProviderSearch(name) {
+        switch (name) {
+            case 'searxng':
+                return config.search.baseUrl
+                    ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
+                    : invalidSearxngSearch();
+            case 'brave':
+                return createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY });
+            case 'youcom':
+                return createYouComSearch({ apiKey: process.env.YDC_API_KEY });
+            case 'exa':
+                return createExaSearch({ apiKey: process.env.EXA_API_KEY });
+            case 'tavily':
+                return createTavilySearch({ apiKey: process.env.TAVILY_API_KEY });
+            case 'duckduckgo':
+            default:
+                return createDuckDuckGoSearch();
+        }
+    }
     let search = config.search.provider === 'searxng'
         ? config.search.baseUrl
             ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
@@ -114,6 +134,21 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
     if (config.search.provider === 'tavily' && config.search.fallback === 'duckduckgo') {
         search = withSearchFallback(search, createDuckDuckGoSearch(), 'tavily');
     }
+    const fanoutConfig = config.search.fanout;
+    if (fanoutConfig && fanoutConfig.mode !== 'off') {
+        const baseNames = fanoutConfig.providers && fanoutConfig.providers.length > 0
+            ? fanoutConfig.providers
+            : usableSearchProviders(config.search);
+        // A configured DuckDuckGo fallback must still be honored under fanout: fold it into the set.
+        const providerNames = config.search.fallback === 'duckduckgo' && !baseNames.includes('duckduckgo')
+            ? [...baseNames, 'duckduckgo']
+            : baseNames;
+        const ordered = [config.search.provider, ...providerNames.filter((n) => n !== config.search.provider)].filter((n, i, arr) => arr.indexOf(n) === i);
+        search = createFanoutSearch({
+            providers: ordered.map((name) => ({ name, search: buildProviderSearch(name) })),
+            mode: fanoutConfig.mode
+        });
+    }
     const httpFetch = createHttpFetch();
     let fetchPage = config.fetch.provider === 'firecrawl'
         ? config.fetch.baseUrl

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

@@ -1,4 +1,4 @@
-import { DEFAULT_BACKEND_CONFIG, mergeBackendConfigLayers, validateBackendConfig } from '../backends/config.js';
+import { DEFAULT_BACKEND_CONFIG, mergeBackendConfigLayers, validateBackendConfig, usableSearchProviders } from '../backends/config.js';
 import { checkBackendHealth } from '../backends/doctor.js';
 import { DynamicBorder, getSettingsListTheme } from '@earendil-works/pi-coding-agent';
 import { Container, Input, SelectList, SettingsList, Text } from '@earendil-works/pi-tui';
@@ -20,7 +20,10 @@ function cloneBackendConfig(config) {
     return {
         search: {
             ...config.search,
-            options: config.search.options ? { ...config.search.options } : undefined
+            options: config.search.options ? { ...config.search.options } : undefined,
+            fanout: config.search.fanout
+                ? { mode: config.search.fanout.mode, providers: config.search.fanout.providers ? [...config.search.fanout.providers] : undefined }
+                : undefined
         },
         fetch: {
             ...config.fetch,
@@ -54,12 +57,16 @@ async function defaultCheckTypebox() {
     }
 }
 function formatSearchOptions(config) {
-    return [
+    const parts = [
         config.fallback ? `fallback ${config.fallback}` : undefined,
         config.options?.categories?.length ? `categories ${config.options.categories.join(',')}` : undefined,
         config.options?.language ? `language ${config.options.language}` : undefined,
-        config.options?.safesearch !== undefined ? `safesearch ${config.options.safesearch}` : undefined
-    ].filter(Boolean).join(' ');
+        config.options?.safesearch !== undefined ? `safesearch ${config.options.safesearch}` : undefined,
+        config.fanout && config.fanout.mode !== 'off'
+            ? `fanout ${config.fanout.mode} (${(config.fanout.providers || usableSearchProviders(config)).join(', ')})`
+            : undefined
+    ].filter(Boolean);
+    return parts.join(' ');
 }
 function formatFetchOptions(config) {
     return [
@@ -155,6 +162,9 @@ export function createBackendUrlEditor(theme, label, placeholderUrl, onOpenChang
     };
 }
 function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange) {
+    const usable = usableSearchProviders(backends.search);
+    const fanoutMode = backends.search.fanout?.mode ?? 'off';
+    const fanoutProviders = backends.search.fanout?.providers ?? usable;
     return [
         {
             id: 'scope',
@@ -180,6 +190,18 @@ function buildBackendSettingsItems(scope, backends, theme, onUrlEditorOpenChange
             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:search:fanout:mode',
+            label: 'Search fanout',
+            currentValue: fanoutMode,
+            values: ['off', 'on', 'auto']
+        },
+        ...(fanoutMode !== 'off' ? usable.map((provider) => ({
+            id: `backend:search:fanout:provider:${provider}`,
+            label: `  ${provider}`,
+            currentValue: fanoutProviders.includes(provider) ? 'included' : 'excluded',
+            values: ['included', 'excluded']
+        })) : []),
         {
             id: 'backend:secret:brave',
             label: 'Brave API key',
@@ -333,6 +355,40 @@ export function applySettingsValue(state, id, newValue) {
             delete currentBackends.search.fallback;
         }
     }
+    if (id === 'backend:search:fanout:mode') {
+        if (newValue === 'off') {
+            currentBackends.search.fanout = { mode: 'off' };
+        }
+        else if (newValue === 'on' || newValue === 'auto') {
+            currentBackends.search.fanout = {
+                mode: newValue,
+                providers: undefined
+            };
+        }
+    }
+    if (id.startsWith('backend:search:fanout:provider:')) {
+        const providerName = id.slice('backend:search:fanout:provider:'.length);
+        const usableProviders = usableSearchProviders(currentBackends.search);
+        // Ensure fanout exists
+        if (!currentBackends.search.fanout) {
+            currentBackends.search.fanout = { mode: 'on', providers: undefined };
+        }
+        // Materialize the provider list if it's currently undefined; use usable providers instead of all
+        const currentProviders = currentBackends.search.fanout.providers ?? usableProviders;
+        if (newValue === 'excluded') {
+            // Remove the provider from the list
+            const filtered = currentProviders.filter((p) => p !== providerName);
+            // never allow an empty set: keep at least one provider (empty would be read as "all")
+            if (filtered.length > 0) {
+                currentBackends.search.fanout.providers = filtered;
+            }
+        }
+        else if (newValue === 'included') {
+            // Add the provider back, maintaining canonical order using usable providers
+            const result = usableProviders.filter((p) => currentProviders.includes(p) || p === providerName);
+            currentBackends.search.fanout.providers = result;
+        }
+    }
     if (id === 'backend:search:baseUrl') {
         if (newValue.trim()) {
             currentBackends.search.provider = 'searxng';
@@ -400,7 +456,8 @@ export function collapseBackendConfigToOverride(config, inheritedConfig) {
             : {
                 ...(config.search.baseUrl !== inheritedConfig.search.baseUrl ? { baseUrl: config.search.baseUrl } : {}),
                 ...(config.search.fallback !== inheritedConfig.search.fallback ? { fallback: config.search.fallback } : {}),
-                ...(!sameJson(config.search.options, inheritedConfig.search.options) ? { options: config.search.options } : {})
+                ...(!sameJson(config.search.options, inheritedConfig.search.options) ? { options: config.search.options } : {}),
+                ...(!sameJson(config.search.fanout, inheritedConfig.search.fanout) ? { fanout: config.search.fanout } : {})
             };
         if (config.search.provider !== inheritedConfig.search.provider) {
             override.search.provider = config.search.provider;

package/dist/extension.js

@@ -7,6 +7,30 @@ import { loadPresentationConfigLayers } from './presentation/config-store.js';
 import { selectPresentationView } from './presentation/select-view.js';
 import { createWebExploreTool } from './tools/web-explore.js';
 import { getUpdateChangelogNotice } from './changelog-notice.js';
+import { Text } from '@earendil-works/pi-tui';
+/**
+ * What the model receives as the tool result: the actual synthesized findings (which for a
+ * direct GitHub/PDF/YouTube read is the full extracted content), plus source citations and any
+ * caveat. This is separate from the terminal display (see renderResult), so the model always
+ * gets the substance regardless of the user's compact/preview/verbose presentation setting.
+ */
+function serializeForModel(result) {
+    if (result.status === 'error') {
+        return `Research failed: ${result.error?.message ?? 'Unknown research failure.'}`;
+    }
+    if (result.findings.length === 0 && result.sources.length === 0) {
+        return 'No usable evidence found.';
+    }
+    return [
+        result.findings.join('\n\n'),
+        result.sources.length
+            ? `Sources:\n${result.sources.map((source) => `- ${source.title}: ${source.url}`).join('\n')}`
+            : undefined,
+        result.caveat
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+}
 async function loadWebAgentConfig(pi) {
     const store = pi.__presentationConfigStore;
     return store?.load?.() ?? loadPresentationConfigLayers();
@@ -29,11 +53,6 @@ async function getEffectiveBackendConfig(pi) {
         return DEFAULT_BACKEND_CONFIG;
     }
 }
-async function renderToolText(pi, toolName, details) {
-    const config = await getEffectivePresentationConfig(pi);
-    const mode = resolvePresentationMode(toolName, config);
-    return selectPresentationView(details.presentation, mode) ?? JSON.stringify(details, null, 2);
-}
 export default function extension(pi) {
     registerWebAgentConfigCommands(pi);
     const injectedWebExplore = pi.__webExploreTool;
@@ -79,16 +98,38 @@ export default function extension(pi) {
         async execute(_toolCallId, params) {
             const webExplore = await getConfiguredWebExplore();
             const result = await webExplore({ query: params.query });
+            // Terminal display honors the user's presentation mode; the model gets the full findings.
+            // The fallback must stay terse: never fall back to serializeForModel here, or a missing
+            // presentation would dump the full findings into the terminal.
+            const mode = resolvePresentationMode('web_explore', await getEffectivePresentationConfig(pi));
+            const terseFallback = 'web_explore result';
+            const terminalText = selectPresentationView(result.presentation, mode) ?? terseFallback;
+            const terminalTextExpanded = selectPresentationView(result.presentation, 'verbose') ?? terminalText;
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: await renderToolText(pi, 'web_explore', result)
-                    }
-                ],
-                details: result,
+                content: [{ type: 'text', text: serializeForModel(result) }],
+                details: { ...result, terminalText, terminalTextExpanded },
                 isError: result.status === 'error'
             };
+        },
+        renderResult(toolResult, options) {
+            const details = toolResult.details;
+            try {
+                // Legacy fallback: results persisted before this change carry `presentation` but no
+                // `terminalText`, so old sessions stay readable instead of rendering blank.
+                const legacy = options.expanded
+                    ? details?.presentation?.views?.verbose ?? details?.presentation?.views?.compact
+                    : details?.presentation?.views?.compact;
+                const text = (options.expanded ? details?.terminalTextExpanded : details?.terminalText) ??
+                    details?.terminalText ??
+                    legacy ??
+                    'web_explore result';
+                return new Text(text, 0, 0);
+            }
+            catch {
+                // Never throw: a thrown renderer makes Pi fall back to raw content, which would dump
+                // the full model-facing findings into the terminal.
+                return new Text('web_explore result', 0, 0);
+            }
         }
     });
 }

package/dist/orchestration/direct-url.js

@@ -1,13 +1,4 @@
-const TRACKING_PARAMS = new Set([
-    'utm_source',
-    'utm_medium',
-    'utm_campaign',
-    'utm_term',
-    'utm_content',
-    'utm_name',
-    'fbclid',
-    'gclid'
-]);
+import { canonicalizeUrl } from './url.js';
 function stripTrailingPunctuation(raw) {
     let next = raw.trim();
     while (/[),.;!?\]]$/.test(next)) {
@@ -19,21 +10,7 @@ function stripTrailingPunctuation(raw) {
     return next;
 }
 function normalizeDirectUrl(raw) {
-    try {
-        const url = new URL(stripTrailingPunctuation(raw));
-        if (url.protocol !== 'http:' && url.protocol !== 'https:')
-            return undefined;
-        for (const key of [...url.searchParams.keys()]) {
-            if (TRACKING_PARAMS.has(key.toLowerCase())) {
-                url.searchParams.delete(key);
-            }
-        }
-        url.hash = '';
-        return url.toString().replace(/\/$/, '');
-    }
-    catch {
-        return undefined;
-    }
+    return canonicalizeUrl(stripTrailingPunctuation(raw), { canonicalizeHost: false });
 }
 export function extractDirectUrls(query) {
     const matches = query.match(/https?:\/\/\S+/gi) ?? [];

package/dist/orchestration/evidence-quality.d.ts

@@ -7,6 +7,7 @@ export type EvidenceQualityReport = {
         community: number;
         thread: number;
         packagePage: number;
+        primaryContent: number;
         distinctHosts: number;
     };
     flags: {

package/dist/orchestration/evidence-quality.js

@@ -25,10 +25,11 @@ export function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }) {
     const community = evidence.filter((item) => item.sourceKind === 'community').length;
     const thread = evidence.filter((item) => item.sourceKind === 'issue-thread' || item.sourceKind === 'official-discussion').length;
     const packagePage = evidence.filter((item) => item.sourceKind === 'package-page').length;
+    const primaryContent = evidence.filter((item) => item.sourceKind === 'primary-content').length;
     const distinctHosts = new Set(evidence.map((item) => hostname(item.url))).size;
     const hasOfficialEvidence = official > 0;
-    const hasOnlyCommunityEvidence = evidence.length > 0 && official === 0;
-    const hasLowDiversity = evidence.length > 1 && distinctHosts <= 1;
+    const hasOnlyCommunityEvidence = evidence.length > 0 && official === 0 && primaryContent === 0;
+    const hasLowDiversity = evidence.length > 1 && distinctHosts <= 1 && primaryContent === 0;
     const hasUnreadableDirectSource = gaps.some((gap) => /Direct URL could not be read reliably/i.test(gap.message));
     const hasUnreadableThreadSource = gaps.some((gap) => /Thread source could not be read reliably/i.test(gap.message));
     const hasPossibleConflict = hasConflictMarkers(evidence);
@@ -47,6 +48,7 @@ export function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }) {
             community,
             thread,
             packagePage,
+            primaryContent,
             distinctHosts
         },
         flags: {

package/dist/orchestration/evidence-ranker.js

@@ -1,5 +1,7 @@
 function sourceRank(sourceKind) {
     switch (sourceKind) {
+        case 'primary-content':
+            return -1;
         case 'official-docs':
             return 0;
         case 'official-api':

package/dist/orchestration/index.d.ts

@@ -24,6 +24,8 @@ export declare function createResearchWorkflow({ backendConfig, search, fetchPag
             headlessAttempts: number;
             exhaustedBudget: boolean;
             caveatReasons: import("./evidence-quality.js").EvidenceCaveatReason[];
+            fanoutProviders: import("../types.js").SearchProviderName[] | undefined;
+            fanoutSkipped: import("../types.js").SearchProviderName[] | undefined;
         };
     }>;
 };

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

@@ -1,4 +1,4 @@
-import type { WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
+import type { SearchProviderName, WebFetchHeadlessResponse, WebFetchResponse } from '../types.js';
 import type { ResearchEvidence, ResearchOrchestratorDecision, ResearchWorkerResult } from './research-types.js';
 import { type EvidenceCaveatReason } from './evidence-quality.js';
 export declare function createResearchOrchestrator({ worker, fetchDirect, headlessFetch }: {
@@ -28,6 +28,8 @@ export declare function createResearchOrchestrator({ worker, fetchDirect, headle
             headlessAttempts: number;
             exhaustedBudget: boolean;
             caveatReasons: EvidenceCaveatReason[];
+            fanoutProviders: SearchProviderName[] | undefined;
+            fanoutSkipped: SearchProviderName[] | undefined;
         };
     }>;
 };

package/dist/orchestration/research-orchestrator.js

@@ -13,6 +13,9 @@ function classifyEvidenceUrl(url) {
 function summarizeText(text, maxLength = 180) {
     return text.replace(/\s+/g, ' ').trim().slice(0, maxLength);
 }
+function isReaderMethod(method) {
+    return method === 'github' || method === 'pdf' || method === 'youtube';
+}
 function isBotCheckContent({ title = '', text }) {
     return /performing security verification|security service|verify you are not a bot|just a moment|checking your browser/i.test(`${title}\n${text}`);
 }
@@ -21,6 +24,16 @@ function evidenceFromFetch(result) {
         return null;
     if (isBotCheckContent({ title: result.content.title, text: result.content.text }))
         return null;
+    if (isReaderMethod(result.metadata.method)) {
+        return {
+            title: result.content.title ?? result.url,
+            url: result.url,
+            sourceKind: 'primary-content',
+            method: result.metadata.method,
+            summary: result.content.text,
+            supports: [result.content.text]
+        };
+    }
     return {
         title: result.content.title ?? result.url,
         url: result.url,
@@ -66,13 +79,15 @@ function shouldRetryDirectWithHeadless(result, evidence) {
         return false;
     return classifySourceProfile(result.url).shouldPreferHeadlessWhenWeak;
 }
-function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget, caveatReasons = [] }) {
+function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget, caveatReasons = [], fanoutProviders, fanoutSkipped }) {
     return {
         searchPasses: previousQueries.length,
         fetchedPages: allEvidence.length + allGaps.length + allLowValueOutcomes.length,
         headlessAttempts,
         exhaustedBudget,
-        caveatReasons
+        caveatReasons,
+        fanoutProviders,
+        fanoutSkipped
     };
 }
 function decisionForAnswer({ action, query, ranked, exhaustedBudget }) {
@@ -99,6 +114,13 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
             const suggestedHeadlessUrls = [];
             let headlessAttempts = 0;
             let lastPass;
+            const fanoutProvidersSeen = new Set();
+            const fanoutSkippedSeen = new Set();
+            function fanoutSnapshot() {
+                const providers = fanoutProvidersSeen.size ? [...fanoutProvidersSeen] : undefined;
+                const skipped = [...fanoutSkippedSeen].filter((p) => !fanoutProvidersSeen.has(p));
+                return { fanoutProviders: providers, fanoutSkipped: skipped.length ? skipped : undefined };
+            }
             if (fetchDirect) {
                 for (const url of extractDirectUrls(query).slice(0, 3)) {
                     const directResult = await fetchDirect({ url });
@@ -134,6 +156,35 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                     }
                 }
             }
+            if (allEvidence.some((item) => item.sourceKind === 'primary-content')) {
+                const ranked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+                const quality = analyzeEvidenceQuality({
+                    evidence: ranked,
+                    gaps: allGaps,
+                    lowValueOutcomes: allLowValueOutcomes
+                });
+                return {
+                    decision: decisionForAnswer({ action: 'answer', query, ranked, exhaustedBudget: false }),
+                    evidence: ranked,
+                    workerPass: combinedWorkerPass({
+                        lastPass,
+                        previousQueries,
+                        allGaps,
+                        allLowValueOutcomes,
+                        exhaustedBudget: false
+                    }),
+                    metadata: buildMetadata({
+                        previousQueries,
+                        allEvidence,
+                        allGaps,
+                        allLowValueOutcomes,
+                        headlessAttempts,
+                        exhaustedBudget: false,
+                        caveatReasons: quality.caveatReasons,
+                        ...fanoutSnapshot()
+                    })
+                };
+            }
             for (let passIndex = 0; passIndex < DEFAULT_MAX_PASSES; passIndex++) {
                 const queries = planSearchQueries({
                     originalQuery: query,
@@ -149,6 +200,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                         maxFetches: DEFAULT_MAX_FETCHES_PER_PASS
                     });
                     lastPass = pass;
+                    pass.fanoutProviders?.forEach((p) => fanoutProvidersSeen.add(p));
+                    pass.fanoutSkipped?.forEach((p) => fanoutSkippedSeen.add(p));
                     allEvidence.push(...pass.evidence);
                     allGaps.push(...pass.gaps);
                     allLowValueOutcomes.push(...pass.lowValueOutcomes);
@@ -213,7 +266,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                                     allLowValueOutcomes,
                                     headlessAttempts,
                                     exhaustedBudget,
-                                    caveatReasons: updatedQuality.caveatReasons
+                                    caveatReasons: updatedQuality.caveatReasons,
+                                    ...fanoutSnapshot()
                                 })
                             };
                         }
@@ -239,7 +293,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                                 allLowValueOutcomes,
                                 headlessAttempts,
                                 exhaustedBudget: false,
-                                caveatReasons: quality.caveatReasons
+                                caveatReasons: quality.caveatReasons,
+                                ...fanoutSnapshot()
                             })
                         };
                     }
@@ -262,7 +317,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                                 allLowValueOutcomes,
                                 headlessAttempts,
                                 exhaustedBudget,
-                                caveatReasons: quality.caveatReasons
+                                caveatReasons: quality.caveatReasons,
+                                ...fanoutSnapshot()
                             })
                         };
                     }
@@ -291,7 +347,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                     allLowValueOutcomes,
                     headlessAttempts,
                     exhaustedBudget: true,
-                    caveatReasons: quality.caveatReasons
+                    caveatReasons: quality.caveatReasons,
+                    ...fanoutSnapshot()
                 })
             };
         }

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

@@ -1,4 +1,5 @@
-export type ResearchSourceKind = 'official-docs' | 'official-api' | 'official-discussion' | 'community' | 'issue-thread' | 'package-page' | 'other';
+import type { SearchProviderName } from '../types.js';
+export type ResearchSourceKind = 'primary-content' | 'official-docs' | 'official-api' | 'official-discussion' | 'community' | 'issue-thread' | 'package-page' | 'other';
 export type ResearchMethod = 'search' | 'http' | 'headless' | 'firecrawl' | 'github' | 'pdf' | 'youtube';
 export type ResearchEvidence = {
     title: string;
@@ -24,12 +25,16 @@ export type ResearchWorkerResult = {
     lowValueOutcomes: ResearchLowValueOutcome[];
     suggestedHeadlessUrl?: string;
     exhaustedBudget: boolean;
+    fanoutProviders?: SearchProviderName[];
+    fanoutSkipped?: SearchProviderName[];
 };
 export type ResearchRunMetadata = {
     searchPasses: number;
     fetchedPages: number;
     headlessAttempts: number;
     exhaustedBudget: boolean;
+    fanoutProviders?: SearchProviderName[];
+    fanoutSkipped?: SearchProviderName[];
 };
 export type ResearchOrchestratorDecision = {
     action: 'answer';

package/dist/orchestration/research-worker.js

@@ -6,6 +6,9 @@ function classifySource(url) {
 function summarizeText(text, maxLength = 180) {
     return text.replace(/\s+/g, ' ').trim().slice(0, maxLength);
 }
+function isReaderMethod(method) {
+    return method === 'github' || method === 'pdf' || method === 'youtube';
+}
 function isBotCheckContent({ title = '', text }) {
     return /performing security verification|security service|verify you are not a bot|just a moment|checking your browser/i.test(`${title}\n${text}`);
 }
@@ -15,6 +18,18 @@ function evidenceFromFetch(fetched, fallbackTitle) {
         return null;
     if (isBotCheckContent({ title: content.title, text: content.text }))
         return null;
+    // A successful reader read with usable text is primary content, exempt from the
+    // package-page filter below.
+    if (isReaderMethod(fetched.metadata.method) && content.text.trim()) {
+        return {
+            title: content.title ?? fallbackTitle,
+            url: fetched.url,
+            sourceKind: 'primary-content',
+            method: fetched.metadata.method,
+            summary: content.text,
+            supports: [content.text]
+        };
+    }
     const sourceKind = classifySource(fetched.url);
     if (sourceKind === 'package-page') {
         return null;
@@ -65,6 +80,8 @@ export function createResearchWorker({ search, fetchPage }) {
                 };
             }
             const searchResult = await search({ query });
+            const fanoutProviders = searchResult.metadata.fanout?.providers;
+            const fanoutSkipped = searchResult.metadata.fanout?.skipped;
             if (searchResult.status !== 'ok') {
                 return {
                     searchQueries,
@@ -77,7 +94,9 @@ export function createResearchWorker({ search, fetchPage }) {
                     ],
                     lowValueOutcomes,
                     suggestedHeadlessUrl,
-                    exhaustedBudget: false
+                    exhaustedBudget: false,
+                    fanoutProviders,
+                    fanoutSkipped
                 };
             }
             if (searchResult.results.length === 0) {
@@ -92,7 +111,9 @@ export function createResearchWorker({ search, fetchPage }) {
                         }
                     ],
                     suggestedHeadlessUrl,
-                    exhaustedBudget: false
+                    exhaustedBudget: false,
+                    fanoutProviders,
+                    fanoutSkipped
                 };
             }
             const candidates = selectCandidates({
@@ -133,7 +154,9 @@ export function createResearchWorker({ search, fetchPage }) {
                 gaps,
                 lowValueOutcomes,
                 suggestedHeadlessUrl,
-                exhaustedBudget: false
+                exhaustedBudget: false,
+                fanoutProviders,
+                fanoutSkipped
             };
         }
     };

package/dist/orchestration/url.d.ts

@@ -0,0 +1,6 @@
+declare const TRACKING_PARAMS: Set<string>;
+/** Canonical form for dedupe/comparison. Returns undefined for non-http(s) or unparseable input. */
+export declare function canonicalizeUrl(raw: string, options?: {
+    canonicalizeHost?: boolean;
+}): string | undefined;
+export { TRACKING_PARAMS };

package/dist/orchestration/url.js

@@ -0,0 +1,34 @@
+const TRACKING_PARAMS = new Set([
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_term',
+    'utm_content',
+    'utm_name',
+    'fbclid',
+    'gclid'
+]);
+/** Canonical form for dedupe/comparison. Returns undefined for non-http(s) or unparseable input. */
+export function canonicalizeUrl(raw, options = {}) {
+    const { canonicalizeHost = true } = options;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return undefined;
+    if (canonicalizeHost) {
+        url.hostname = url.hostname.replace(/^www\./, '');
+    }
+    for (const key of [...url.searchParams.keys()]) {
+        if (TRACKING_PARAMS.has(key.toLowerCase())) {
+            url.searchParams.delete(key);
+        }
+    }
+    url.hash = '';
+    return url.toString().replace(/\/$/, '');
+}
+export { TRACKING_PARAMS };

package/dist/presentation/explore-presentation.js

@@ -22,8 +22,15 @@ export function buildExplorePresentation(result) {
             }
         };
     }
+    const fanoutProviders = result.metadata?.fanoutProviders;
+    const fanoutSkipped = result.metadata?.fanoutSkipped;
+    const fanoutNote = fanoutProviders?.length
+        ? ` (fanout: ${fanoutProviders.join(', ')}${fanoutSkipped?.length ? `; skipped: ${fanoutSkipped.join(', ')}` : ''})`
+        : fanoutSkipped?.length
+            ? ` (fanout; skipped: ${fanoutSkipped.join(', ')})`
+            : '';
     const internalSummary = result.metadata
-        ? `Internal research: web_search ×${result.metadata.searchPasses}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
+        ? `Internal research: web_search ×${result.metadata.searchPasses}${fanoutNote}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
         : undefined;
     const hasEvidence = result.findings.length > 0 || result.sources.length > 0;
     const evidenceLines = hasEvidence
@@ -46,12 +53,13 @@ export function buildExplorePresentation(result) {
     ]
         .filter((line) => line !== undefined)
         .join('\n');
+    const compact = hasEvidence
+        ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
+        : 'No usable evidence found';
     return {
         mode: 'compact',
         views: {
-            compact: hasEvidence
-                ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
-                : 'No usable evidence found',
+            compact,
             preview,
             verbose
         },

package/dist/presentation/search-presentation.js

@@ -1,12 +1,24 @@
+function fanoutNote(result) {
+    const f = result.metadata.fanout;
+    if (!f)
+        return '';
+    if (f.providers.length) {
+        return ` (fanout: ${f.providers.join(', ')}${f.skipped?.length ? `; skipped: ${f.skipped.join(', ')}` : ''})`;
+    }
+    if (f.skipped?.length) {
+        return ` (fanout; skipped: ${f.skipped.join(', ')})`;
+    }
+    return '';
+}
 function formatCompact(result) {
     const fallbackPrefix = result.metadata.fallbackFrom
         ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.backend} fallback. `
         : '';
     if (result.status === 'error') {
-        return `${fallbackPrefix}Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
+        return `${fallbackPrefix}Search failed: ${result.error?.message ?? 'Unknown search failure.'}${fanoutNote(result)}`;
     }
     const suffix = result.results.length === 1 ? 'result' : 'results';
-    return `${fallbackPrefix}Found ${result.results.length} ${suffix}`;
+    return `${fallbackPrefix}Found ${result.results.length} ${suffix}${fanoutNote(result)}`;
 }
 export function buildSearchPresentation(result) {
     const preview = result.results

package/dist/readers/github-reader.js

@@ -1,3 +1,4 @@
+import { READER_TEXT_CAP } from './limits.js';
 function parseGithub(url) {
     try {
         return new URL(url);
@@ -51,12 +52,12 @@ function fail(url, message) {
     };
 }
 function okResponse(url, title, text) {
-    const capped = text.slice(0, 4000);
+    const capped = text.slice(0, READER_TEXT_CAP);
     return {
         status: 'ok',
         url,
         content: { title, text: capped },
-        metadata: { method: 'github', cacheHit: false, truncated: text.length >= 4000 }
+        metadata: { method: 'github', cacheHit: false, truncated: text.length >= READER_TEXT_CAP }
     };
 }
 export function createGithubReader({ fetchImpl = fetch, token = process.env.GITHUB_TOKEN } = {}) {

package/dist/readers/limits.d.ts

@@ -0,0 +1,3 @@
+/** Max characters a special-content reader returns. Large enough for a typical transcript
+ *  or a medium PDF; very long documents still truncate (section-aware chunking is future work). */
+export declare const READER_TEXT_CAP = 24000;

package/dist/readers/limits.js

@@ -0,0 +1,3 @@
+/** Max characters a special-content reader returns. Large enough for a typical transcript
+ *  or a medium PDF; very long documents still truncate (section-aware chunking is future work). */
+export const READER_TEXT_CAP = 24000;

package/dist/readers/pdf-reader.js

@@ -1,4 +1,5 @@
 import { extractText, getDocumentProxy, getMeta } from 'unpdf';
+import { READER_TEXT_CAP } from './limits.js';
 async function defaultExtract(bytes) {
     const pdf = await getDocumentProxy(bytes);
     const [{ text }, meta] = await Promise.all([
@@ -58,8 +59,8 @@ export function createPdfReader({ fetchImpl = fetch, extractPdfText = defaultExt
                 return {
                     status: 'ok',
                     url,
-                    content: { title: extracted.title ?? filenameFromUrl(url), text: text.slice(0, 4000) },
-                    metadata: { method: 'pdf', cacheHit: false, contentType: 'application/pdf', truncated: text.length >= 4000 }
+                    content: { title: extracted.title ?? filenameFromUrl(url), text: text.slice(0, READER_TEXT_CAP) },
+                    metadata: { method: 'pdf', cacheHit: false, contentType: 'application/pdf', truncated: text.length >= READER_TEXT_CAP }
                 };
             }
             catch (err) {

package/dist/readers/youtube-reader.js

@@ -1,4 +1,5 @@
 import { getSubtitles, getVideoDetails } from 'youtube-caption-extractor';
+import { READER_TEXT_CAP } from './limits.js';
 function extractVideoId(url) {
     let parsed;
     try {
@@ -53,8 +54,8 @@ export function createYoutubeReader({ fetchSubtitles = getSubtitles, fetchDetail
                 return {
                     status: 'ok',
                     url,
-                    content: { title: details.title ?? `YouTube ${videoID}`, text: transcript.slice(0, 4000) },
-                    metadata: { method: 'youtube', cacheHit: false, truncated: transcript.length >= 4000 }
+                    content: { title: details.title ?? `YouTube ${videoID}`, text: transcript.slice(0, READER_TEXT_CAP) },
+                    metadata: { method: 'youtube', cacheHit: false, truncated: transcript.length >= READER_TEXT_CAP }
                 };
             }
             catch (err) {

package/dist/search/fanout.d.ts

@@ -0,0 +1,14 @@
+import type { FanoutMode, SearchProviderName, WebSearchResponse } from '../types.js';
+export type FanoutProvider = {
+    name: SearchProviderName;
+    search: (input: {
+        query: string;
+    }) => Promise<WebSearchResponse>;
+};
+export declare function createFanoutSearch({ providers, mode, timeoutMs }: {
+    providers: FanoutProvider[];
+    mode: Exclude<FanoutMode, 'off'>;
+    timeoutMs?: number;
+}): ({ query }: {
+    query: string;
+}) => Promise<WebSearchResponse>;

package/dist/search/fanout.js

@@ -0,0 +1,118 @@
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { canonicalizeUrl } from '../orchestration/url.js';
+const FANOUT_MIN_RESULTS = 3;
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+function primaryLooksWeak(results) {
+    if (results.length < FANOUT_MIN_RESULTS)
+        return true;
+    const hosts = new Set(results.map((r) => hostOf(r.url)).filter(Boolean));
+    return hosts.size <= 1;
+}
+function merge(lists) {
+    const byKey = new Map();
+    for (const { name, results } of lists) {
+        const seenThisProvider = new Set();
+        results.forEach((result, index) => {
+            const key = canonicalizeUrl(result.url) ?? result.url;
+            if (seenThisProvider.has(key))
+                return; // ignore duplicates within a single provider's own list
+            seenThisProvider.add(key);
+            const existing = byKey.get(key);
+            if (!existing) {
+                byKey.set(key, { result: { ...result }, providers: new Set([name]), bestRank: index });
+                return;
+            }
+            existing.providers.add(name);
+            existing.bestRank = Math.min(existing.bestRank, index);
+            if ((result.title?.length ?? 0) > (existing.result.title?.length ?? 0))
+                existing.result.title = result.title;
+            if ((result.snippet?.length ?? 0) > (existing.result.snippet?.length ?? 0))
+                existing.result.snippet = result.snippet;
+        });
+    }
+    return [...byKey.values()]
+        .sort((a, b) => b.providers.size - a.providers.size || a.bestRank - b.bestRank)
+        .map((entry) => entry.result);
+}
+function withPresentation(result) {
+    return { ...result, presentation: buildSearchPresentation(result) };
+}
+const FANOUT_PROVIDER_TIMEOUT_MS = 8000;
+/** Resolve to undefined if the provider doesn't answer in time, so one slow/unreachable
+ *  provider (e.g. a down self-hosted SearXNG) can't stall the whole fanout across passes. */
+function withTimeout(promise, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, () => {
+            clearTimeout(timer);
+            resolve(undefined);
+        });
+    });
+}
+export function createFanoutSearch({ providers, mode, timeoutMs = FANOUT_PROVIDER_TIMEOUT_MS }) {
+    return async function fanoutSearch({ query }) {
+        const [primary, ...rest] = providers;
+        async function runSet(set) {
+            const settled = await Promise.all(set.map((p) => withTimeout(p.search({ query }), timeoutMs)));
+            const contributing = [];
+            const skipped = [];
+            set.forEach((provider, i) => {
+                const value = settled[i];
+                if (value && value.status === 'ok' && value.results.length > 0) {
+                    contributing.push({ name: provider.name, results: value.results });
+                }
+                else {
+                    skipped.push(provider.name);
+                }
+            });
+            return { contributing, skipped };
+        }
+        function finalize(lists, skipped, resolvedMode) {
+            if (lists.length === 0) {
+                const fanout = { mode: resolvedMode, providers: [] };
+                if (skipped.length > 0)
+                    fanout.skipped = skipped;
+                return withPresentation({
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: primary.name, cacheHit: false, fanout },
+                    error: { code: 'FANOUT_NO_RESULTS', message: 'No fanout provider returned usable results.' }
+                });
+            }
+            const fanout = { mode: resolvedMode, providers: lists.map((l) => l.name) };
+            if (skipped.length > 0)
+                fanout.skipped = skipped;
+            return withPresentation({
+                status: 'ok',
+                results: merge(lists),
+                metadata: { backend: primary.name, cacheHit: false, fanout }
+            });
+        }
+        if (mode === 'auto') {
+            const primaryOutcome = await withTimeout(primary.search({ query }), timeoutMs);
+            const primaryResults = primaryOutcome?.status === 'ok' ? primaryOutcome.results : [];
+            if (primaryResults.length > 0 && !primaryLooksWeak(primaryResults)) {
+                return withPresentation(primaryOutcome); // strong primary: no fanout
+            }
+            const { contributing, skipped } = await runSet(rest);
+            const lists = [
+                ...(primaryResults.length ? [{ name: primary.name, results: primaryResults }] : []),
+                ...contributing
+            ];
+            const allSkipped = [...(primaryResults.length ? [] : [primary.name]), ...skipped];
+            return finalize(lists, allSkipped, 'auto');
+        }
+        const { contributing, skipped } = await runSet(providers);
+        return finalize(contributing, skipped, 'on');
+    };
+}

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

@@ -40,6 +40,8 @@ export declare function createWebExploreTool({ explore }?: {
         headlessAttempts: number;
         exhaustedBudget: boolean;
         caveatReasons?: string[];
+        fanoutProviders?: import("../types.js").SearchProviderName[];
+        fanoutSkipped?: import("../types.js").SearchProviderName[];
     };
     error?: import("../types.js").ToolError;
 }>;

package/dist/types.d.ts

@@ -6,6 +6,13 @@ export type SearchResult = {
     url: string;
     snippet: string;
 };
+export type SearchProviderName = 'duckduckgo' | 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
+export type FanoutMode = 'off' | 'on' | 'auto';
+export type FanoutMetadata = {
+    mode: Exclude<FanoutMode, 'off'>;
+    providers: SearchProviderName[];
+    skipped?: SearchProviderName[];
+};
 export type ToolError = {
     code: string;
     message: string;
@@ -15,6 +22,7 @@ export type SearchMetadata = {
     cacheHit: boolean;
     fallbackFrom?: 'searxng' | 'brave' | 'youcom' | 'exa' | 'tavily';
     fallbackReason?: string;
+    fanout?: FanoutMetadata;
 };
 export type FetchMethod = 'http' | 'headless' | 'firecrawl' | 'github' | 'pdf' | 'youtube';
 export type FetchMetadata = {
@@ -70,6 +78,8 @@ export type WebExploreResponse = {
         headlessAttempts: number;
         exhaustedBudget: boolean;
         caveatReasons?: string[];
+        fanoutProviders?: SearchProviderName[];
+        fanoutSkipped?: SearchProviderName[];
     };
     presentation?: PresentationEnvelope;
     error?: ToolError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demigodmode/pi-web-agent",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
   "type": "module",
   "main": "./dist/extension.js",