@demigodmode/pi-web-agent 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -18,6 +18,37 @@ The format is intentionally simple and release-oriented.
 ### Breaking
 - None.
 
+## [1.5.0] - 2026-06-16
+### Added
+- Added Brave Search as the first hosted search backend for `web_explore`, giving users a high-quality API-backed discovery option without running their own SearXNG instance.
+- Added optional Brave → DuckDuckGo fallback so hosted search can degrade gracefully instead of failing hard when the Brave API is unavailable or misconfigured.
+- Added a dedicated Brave search adapter that feeds the existing `web_explore` research pipeline, so Brave improves source discovery while the package still handles fetching, ranking, evidence quality, synthesis, and caveats.
+
+### Changed
+- `/web-agent settings` now treats Brave as a first-class search backend while keeping API keys out of config files; users configure `PI_WEB_AGENT_BRAVE_API_KEY` in their environment instead.
+- `/web-agent doctor` now reports Brave setup status, warns when `PI_WEB_AGENT_BRAVE_API_KEY` is missing, and validates configured Brave access when a key is present.
+- Backend config validation and fallback metadata now understand Brave, including clear `fallbackFrom: 'brave'` reporting when DuckDuckGo fallback is used.
+
+### Fixed
+- Nothing yet.
+
+### Breaking
+- None.
+
+## [1.4.0] - 2026-06-09
+### Added
+- Added evidence quality analysis for `web_explore`, including source diversity, unreadable source, bot-check, and possible conflict signals.
+
+### Changed
+- `web_explore` now uses source quality signals before deciding whether to answer, search again, or answer with a caveat.
+- Partial research caveats are now more specific when evidence is community-only, low-diversity, blocked, or cautionary.
+
+### Fixed
+- Nothing yet.
+
+### Breaking
+- None.
+
 ## [1.3.0] - 2026-06-04
 ### Added
 - Added direct URL handling in `web_explore` so linked pages are read before search results.

package/README.md

@@ -8,9 +8,9 @@
 
 Most agent web tools blur search, fetch, browser rendering, and research into one vague thing. `pi-web-agent` exposes one public research tool, `web_explore`, and keeps search/fetch/headless work inside that bounded workflow.
 
-The point is keeping the model-facing boundary simple: ask `web_explore` to research a question, and it handles direct links, discovery, HTTP reads, targeted browser rendering, source ranking, and caveats internally.
+The point is keeping the model-facing boundary simple: ask `web_explore` to research a question, and it handles direct links, discovery, HTTP reads, targeted browser rendering, source ranking, source-quality checks, and caveats internally.
 
-That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust.
+That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust. Bot-check pages, narrow source sets, unreadable threads, and cautionary/conflicting evidence should show up as caveats instead of fake confidence.
 
 ## Install
 
@@ -109,7 +109,7 @@ Example:
 }
 ```
 
-Backend config is also supported. Defaults remain DuckDuckGo search, plain HTTP fetch, and local-browser headless fallback with managed Chromium fallback configured.
+Backend config is also supported. Defaults remain DuckDuckGo search, plain HTTP fetch, and local-browser headless fallback with managed Chromium fallback configured. If you have a Brave Search API key, Brave can be selected as a hosted search backend while `web_explore` still handles page reading, ranking, and caveats itself.
 
 Backend settings can be changed from:
 
@@ -117,7 +117,7 @@ Backend settings can be changed from:
 /web-agent settings
 ```
 
-Choose **Backends** to edit search/fetch providers, fallback behavior, and SearXNG or Firecrawl base URLs interactively. Firecrawl API keys should stay in environment variables rather than being written into config files.
+Choose **Backends** to edit search/fetch providers, fallback behavior, and SearXNG or Firecrawl base URLs interactively. Brave Search uses `PI_WEB_AGENT_BRAVE_API_KEY`. Firecrawl API keys should also stay in environment variables rather than being written into config files.
 
 If you already run SearXNG or Firecrawl, see the self-hosted backend guide:
 

package/dist/backends/config.d.ts

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

package/dist/backends/config.js

@@ -38,17 +38,21 @@ function extractFirecrawlOptions(value) {
 export function extractBackendConfigOverride(file) {
     const backends = file?.backends;
     const override = {};
-    if (backends?.search?.provider === 'duckduckgo' || backends?.search?.provider === 'searxng') {
+    if (backends?.search?.provider === 'duckduckgo' ||
+        backends?.search?.provider === 'searxng' ||
+        backends?.search?.provider === 'brave') {
         override.search = { provider: backends.search.provider };
-        if (typeof backends.search.baseUrl === 'string') {
+        if (backends.search.provider === 'searxng' && typeof backends.search.baseUrl === 'string') {
             override.search.baseUrl = backends.search.baseUrl;
         }
         if (backends.search.fallback === 'duckduckgo') {
             override.search.fallback = 'duckduckgo';
         }
-        const options = extractSearxngOptions(backends.search.options);
-        if (options) {
-            override.search.options = options;
+        if (backends.search.provider === 'searxng') {
+            const options = extractSearxngOptions(backends.search.options);
+            if (options) {
+                override.search.options = options;
+            }
         }
     }
     if (backends?.fetch?.provider === 'http' || backends?.fetch?.provider === 'firecrawl') {
@@ -80,8 +84,8 @@ export function validateBackendConfig(config) {
     if (config.fetch.provider === 'firecrawl' && !config.fetch.baseUrl) {
         issues.push('fetch provider firecrawl requires backends.fetch.baseUrl');
     }
-    if (config.search.fallback === 'duckduckgo' && config.search.provider !== 'searxng') {
-        issues.push('search fallback duckduckgo is only supported when search provider is searxng');
+    if (config.search.fallback === 'duckduckgo' && config.search.provider !== 'searxng' && config.search.provider !== 'brave') {
+        issues.push('search fallback duckduckgo is only supported when search provider is searxng or brave');
     }
     if (config.fetch.fallback === 'http' && config.fetch.provider !== 'firecrawl') {
         issues.push('fetch fallback http is only supported when fetch provider is firecrawl');

package/dist/backends/doctor.js

@@ -6,6 +6,12 @@ function withTimeout(timeoutMs) {
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function braveDoctorUrl() {
+    const url = new URL('https://api.search.brave.com/res/v1/web/search');
+    url.searchParams.set('q', 'pi-web-agent-doctor');
+    url.searchParams.set('count', '1');
+    return url.toString();
+}
 function searxngDoctorUrl(baseUrl, options = {}) {
     const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     url.searchParams.set('q', 'pi-web-agent-doctor');
@@ -30,6 +36,39 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
     if (config.search.provider === 'duckduckgo') {
         lines.push('search backend: duckduckgo');
     }
+    else if (config.search.provider === 'brave') {
+        const apiKey = process.env.PI_WEB_AGENT_BRAVE_API_KEY;
+        if (!apiKey?.trim()) {
+            lines.push('search backend: brave warning (missing PI_WEB_AGENT_BRAVE_API_KEY)');
+        }
+        else {
+            const timeout = withTimeout(timeoutMs);
+            try {
+                const response = await fetchImpl(braveDoctorUrl(), {
+                    headers: {
+                        Accept: 'application/json',
+                        'X-Subscription-Token': apiKey
+                    },
+                    signal: timeout.signal
+                });
+                if (!response.ok) {
+                    lines.push(`search backend: brave warning (HTTP ${response.status})`);
+                }
+                else {
+                    const json = (await response.json());
+                    lines.push(Array.isArray(json.web?.results)
+                        ? 'search backend: brave ok'
+                        : 'search backend: brave warning (unexpected response)');
+                }
+            }
+            catch (error) {
+                lines.push(`search backend: brave warning (${message(error)})`);
+            }
+            finally {
+                timeout.done();
+            }
+        }
+    }
     else if (!config.search.baseUrl) {
         lines.push('search backend: searxng warning (missing baseUrl)');
     }

package/dist/backends/factory.d.ts

@@ -1,4 +1,5 @@
 import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
+import { createBraveSearchTool } from '../search/brave.js';
 import { createSearxngSearchTool } from '../search/searxng.js';
 import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
 import { createWebFetchTool } from '../tools/web-fetch.js';
@@ -19,6 +20,7 @@ export type BackendSet = {
 export type BackendFactoryDeps = {
     createDuckDuckGoSearch?: typeof createWebSearchTool;
     createSearxngSearch?: typeof createSearxngSearchTool;
+    createBraveSearch?: typeof createBraveSearchTool;
     createHttpFetch?: typeof createWebFetchTool;
     createFirecrawlFetch?: typeof createFirecrawlFetcher;
     createHeadlessFetch?: typeof createWebFetchHeadlessTool;

package/dist/backends/factory.js

@@ -1,4 +1,5 @@
 import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
+import { createBraveSearchTool } from '../search/brave.js';
 import { createSearxngSearchTool } from '../search/searxng.js';
 import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
 import { buildSearchPresentation } from '../presentation/search-presentation.js';
@@ -34,7 +35,7 @@ function invalidFirecrawlFetch() {
         return { ...result, presentation: buildFetchPresentation(result) };
     };
 }
-function withSearchFallback(primary, fallback) {
+function withSearchFallback(primary, fallback, fallbackFrom) {
     return async (input) => {
         const first = await primary(input);
         if (first.status !== 'error')
@@ -44,8 +45,8 @@ function withSearchFallback(primary, fallback) {
             ...second,
             metadata: {
                 ...second.metadata,
-                fallbackFrom: 'searxng',
-                fallbackReason: first.error?.message ?? 'SearXNG search failed.'
+                fallbackFrom,
+                fallbackReason: first.error?.message ?? `${fallbackFrom} search failed.`
             }
         };
         return { ...result, presentation: buildSearchPresentation(result) };
@@ -71,6 +72,7 @@ function withFetchFallback(primary, fallback) {
 export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
     const createDuckDuckGoSearch = deps.createDuckDuckGoSearch ?? createWebSearchTool;
     const createSearxngSearch = deps.createSearxngSearch ?? createSearxngSearchTool;
+    const createBraveSearch = deps.createBraveSearch ?? createBraveSearchTool;
     const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
     const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
     const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
@@ -78,9 +80,14 @@ export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
         ? config.search.baseUrl
             ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
             : invalidSearxngSearch()
-        : createDuckDuckGoSearch();
+        : config.search.provider === 'brave'
+            ? createBraveSearch({ apiKey: process.env.PI_WEB_AGENT_BRAVE_API_KEY })
+            : createDuckDuckGoSearch();
     if (config.search.provider === 'searxng' && config.search.fallback === 'duckduckgo') {
-        search = withSearchFallback(search, createDuckDuckGoSearch());
+        search = withSearchFallback(search, createDuckDuckGoSearch(), 'searxng');
+    }
+    if (config.search.provider === 'brave' && config.search.fallback === 'duckduckgo') {
+        search = withSearchFallback(search, createDuckDuckGoSearch(), 'brave');
     }
     const httpFetch = createHttpFetch();
     let fetchPage = config.fetch.provider === 'firecrawl'

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

@@ -124,7 +124,7 @@ function buildBackendSettingsItems(scope, backends) {
             id: 'backend:search:provider',
             label: 'Search backend',
             currentValue: backends.search.provider,
-            values: ['duckduckgo', 'searxng']
+            values: ['duckduckgo', 'searxng', 'brave']
         },
         {
             id: 'backend:search:baseUrl',
@@ -134,9 +134,15 @@ function buildBackendSettingsItems(scope, backends) {
         },
         {
             id: 'backend:search:fallback',
-            label: 'SearXNG fallback',
-            currentValue: backends.search.provider === 'searxng' ? backends.search.fallback ?? 'off' : 'off',
-            values: backends.search.provider === 'searxng' ? ['off', 'duckduckgo'] : ['off']
+            label: 'Search fallback',
+            currentValue: backends.search.provider === 'searxng' || backends.search.provider === 'brave' ? backends.search.fallback ?? 'off' : 'off',
+            values: backends.search.provider === 'searxng' || backends.search.provider === 'brave' ? ['off', 'duckduckgo'] : ['off']
+        },
+        {
+            id: 'backend:secret:brave',
+            label: 'Brave API key',
+            currentValue: 'env var',
+            values: ['env var']
         },
         {
             id: 'backend:fetch:provider',
@@ -249,22 +255,26 @@ export function applySettingsValue(state, id, newValue) {
         }
         currentDraft.tools = nextTools;
     }
-    if (id === 'backend:search:provider' && (newValue === 'duckduckgo' || newValue === 'searxng')) {
+    if (id === 'backend:search:provider' && (newValue === 'duckduckgo' || newValue === 'searxng' || newValue === 'brave')) {
         currentBackends.search.provider = newValue;
+        if (newValue !== 'searxng') {
+            delete currentBackends.search.baseUrl;
+            delete currentBackends.search.options;
+        }
         if (newValue === 'duckduckgo') {
             delete currentBackends.search.fallback;
         }
     }
     if (id === 'backend:search:fallback') {
-        if (newValue === 'duckduckgo' && currentBackends.search.provider === 'searxng') {
+        if (newValue === 'duckduckgo' && (currentBackends.search.provider === 'searxng' || currentBackends.search.provider === 'brave')) {
             currentBackends.search.fallback = 'duckduckgo';
         }
-        else if (newValue === 'off' || currentBackends.search.provider !== 'searxng') {
+        else {
             delete currentBackends.search.fallback;
         }
     }
     if (id === 'backend:search:baseUrl') {
-        if (newValue.trim()) {
+        if (currentBackends.search.provider === 'searxng' && newValue.trim()) {
             currentBackends.search.baseUrl = newValue.trim();
         }
         else {

package/dist/orchestration/answer-synthesizer.d.ts

@@ -1,7 +1,9 @@
 import type { ResearchEvidence } from './research-types.js';
-export declare function synthesizeAnswer({ evidence, partial }: {
+import type { EvidenceCaveatReason } from './evidence-quality.js';
+export declare function synthesizeAnswer({ evidence, partial, caveatReasons }: {
     evidence: ResearchEvidence[];
     partial: boolean;
+    caveatReasons?: EvidenceCaveatReason[];
 }): {
     findings: string[];
     caveat: string | undefined;

package/dist/orchestration/answer-synthesizer.js

@@ -1,7 +1,39 @@
 function normalizeSummary(summary) {
     return summary.replace(/\s+/g, ' ').trim();
 }
-export function synthesizeAnswer({ evidence, partial }) {
+function sentenceForReason(reason) {
+    switch (reason) {
+        case 'community-only':
+            return 'the strongest readable sources were mostly community/practical context';
+        case 'low-diversity':
+            return 'the source set was narrow';
+        case 'unreadable-direct-source':
+            return 'one or more linked sources could not be read reliably';
+        case 'unreadable-thread-source':
+            return 'one or more thread sources could not be read reliably';
+        case 'possible-conflict':
+            return 'readable sources include cautionary or possibly conflicting guidance';
+        case 'bot-check':
+            return 'some candidate sources showed bot-check or security verification pages';
+    }
+}
+function joinReasons(reasons) {
+    if (reasons.length === 0)
+        return '';
+    if (reasons.length === 1)
+        return reasons[0];
+    return `${reasons.slice(0, -1).join(', ')}, and ${reasons.at(-1)}`;
+}
+function caveatText(partial, caveatReasons = []) {
+    if (!partial)
+        return undefined;
+    const specificReasons = caveatReasons.map(sentenceForReason);
+    if (specificReasons.length > 0) {
+        return `Evidence is partial: ${joinReasons(specificReasons)}.`;
+    }
+    return 'Evidence is partial, so this answer is based on the strongest source found within the bounded research budget.';
+}
+export function synthesizeAnswer({ evidence, partial, caveatReasons = [] }) {
     const findings = evidence.slice(0, 5).map((item) => {
         const summary = normalizeSummary(item.summary);
         return item.sourceKind === 'community' || item.sourceKind === 'issue-thread'
@@ -10,8 +42,6 @@ export function synthesizeAnswer({ evidence, partial }) {
     });
     return {
         findings,
-        caveat: partial
-            ? 'Evidence is partial, so this answer is based on the strongest source found within the bounded research budget.'
-            : undefined
+        caveat: caveatText(partial, caveatReasons)
     };
 }

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

@@ -0,0 +1,26 @@
+import type { ResearchEvidence, ResearchGap, ResearchLowValueOutcome } from './research-types.js';
+export type EvidenceCaveatReason = 'community-only' | 'low-diversity' | 'unreadable-direct-source' | 'unreadable-thread-source' | 'possible-conflict' | 'bot-check';
+export type EvidenceQualityReport = {
+    counts: {
+        total: number;
+        official: number;
+        community: number;
+        thread: number;
+        packagePage: number;
+        distinctHosts: number;
+    };
+    flags: {
+        hasOfficialEvidence: boolean;
+        hasOnlyCommunityEvidence: boolean;
+        hasLowDiversity: boolean;
+        hasUnreadableDirectSource: boolean;
+        hasUnreadableThreadSource: boolean;
+        hasPossibleConflict: boolean;
+    };
+    caveatReasons: EvidenceCaveatReason[];
+};
+export declare function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }: {
+    evidence: ResearchEvidence[];
+    gaps: ResearchGap[];
+    lowValueOutcomes: ResearchLowValueOutcome[];
+}): EvidenceQualityReport;

package/dist/orchestration/evidence-quality.js

@@ -0,0 +1,62 @@
+function hostname(url) {
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return url.toLowerCase();
+    }
+}
+function hasConflictMarkers(evidence) {
+    const combined = evidence
+        .flatMap((item) => [item.summary, ...item.supports])
+        .join('\n')
+        .toLowerCase();
+    const caution = /\bdeprecated\b|not recommended|use at your own risk|should not/.test(combined);
+    const positiveText = combined.replace(/not recommended/g, '');
+    const positive = /\brecommended\b/.test(positiveText);
+    return positive && caution;
+}
+function addReason(reasons, reason, enabled) {
+    if (enabled && !reasons.includes(reason))
+        reasons.push(reason);
+}
+export function analyzeEvidenceQuality({ evidence, gaps, lowValueOutcomes }) {
+    const official = evidence.filter((item) => item.sourceKind === 'official-docs' || item.sourceKind === 'official-api').length;
+    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 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 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);
+    const hasBotCheck = lowValueOutcomes.some((outcome) => outcome.kind === 'bot-check');
+    const caveatReasons = [];
+    addReason(caveatReasons, 'community-only', hasOnlyCommunityEvidence);
+    addReason(caveatReasons, 'low-diversity', hasLowDiversity);
+    addReason(caveatReasons, 'unreadable-direct-source', hasUnreadableDirectSource);
+    addReason(caveatReasons, 'unreadable-thread-source', hasUnreadableThreadSource);
+    addReason(caveatReasons, 'possible-conflict', hasPossibleConflict);
+    addReason(caveatReasons, 'bot-check', hasBotCheck);
+    return {
+        counts: {
+            total: evidence.length,
+            official,
+            community,
+            thread,
+            packagePage,
+            distinctHosts
+        },
+        flags: {
+            hasOfficialEvidence,
+            hasOnlyCommunityEvidence,
+            hasLowDiversity,
+            hasUnreadableDirectSource,
+            hasUnreadableThreadSource,
+            hasPossibleConflict
+        },
+        caveatReasons
+    };
+}

package/dist/orchestration/index.d.ts

@@ -23,6 +23,7 @@ export declare function createResearchWorkflow({ backendConfig, search, fetchPag
             fetchedPages: number;
             headlessAttempts: number;
             exhaustedBudget: boolean;
+            caveatReasons: import("./evidence-quality.js").EvidenceCaveatReason[];
         };
     }>;
 };

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

@@ -1,5 +1,6 @@
 import type { 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 }: {
     worker: {
         run: (input: {
@@ -26,6 +27,7 @@ export declare function createResearchOrchestrator({ worker, fetchDirect, headle
             fetchedPages: number;
             headlessAttempts: number;
             exhaustedBudget: boolean;
+            caveatReasons: EvidenceCaveatReason[];
         };
     }>;
 };

package/dist/orchestration/research-orchestrator.js

@@ -3,6 +3,7 @@ import { planSearchQueries } from './query-planner.js';
 import { classifySourceProfile } from './source-profile.js';
 import { extractDirectUrls } from './direct-url.js';
 import { decideNextResearchStep } from './stop-decider.js';
+import { analyzeEvidenceQuality } from './evidence-quality.js';
 const DEFAULT_MAX_PASSES = 3;
 const DEFAULT_MAX_FETCHES_PER_PASS = 4;
 const DEFAULT_MAX_HEADLESS_ATTEMPTS = 2;
@@ -65,15 +66,16 @@ function shouldRetryDirectWithHeadless(result, evidence) {
         return false;
     return classifySourceProfile(result.url).shouldPreferHeadlessWhenWeak;
 }
-function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget }) {
+function buildMetadata({ previousQueries, allEvidence, allGaps, allLowValueOutcomes, headlessAttempts, exhaustedBudget, caveatReasons = [] }) {
     return {
         searchPasses: previousQueries.length,
         fetchedPages: allEvidence.length + allGaps.length + allLowValueOutcomes.length,
         headlessAttempts,
-        exhaustedBudget
+        exhaustedBudget,
+        caveatReasons
     };
 }
-function decisionForAnswer(action, query, ranked) {
+function decisionForAnswer({ action, query, ranked, exhaustedBudget }) {
     if (action === 'answer') {
         return {
             action: 'answer',
@@ -83,7 +85,7 @@ function decisionForAnswer(action, query, ranked) {
     }
     return {
         action: 'research-again',
-        rationale: 'Research budget exhausted; answer with caveat.',
+        rationale: exhaustedBudget ? 'Research budget exhausted; answer with caveat.' : 'Evidence has quality caveats; answer with caveat.',
         followupQuery: query
     };
 }
@@ -153,13 +155,19 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                     if (pass.suggestedHeadlessUrl)
                         suggestedHeadlessUrls.push(pass.suggestedHeadlessUrl);
                     const ranked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+                    const quality = analyzeEvidenceQuality({
+                        evidence: ranked,
+                        gaps: allGaps,
+                        lowValueOutcomes: allLowValueOutcomes
+                    });
                     const decision = decideNextResearchStep({
                         evidence: ranked,
                         suggestedHeadlessUrls,
                         passIndex,
                         maxPasses: DEFAULT_MAX_PASSES,
                         headlessAttempts,
-                        maxHeadlessAttempts: DEFAULT_MAX_HEADLESS_ATTEMPTS
+                        maxHeadlessAttempts: DEFAULT_MAX_HEADLESS_ATTEMPTS,
+                        quality
                     });
                     if (decision.action === 'headless') {
                         headlessAttempts++;
@@ -168,23 +176,35 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                         if (headlessEvidence) {
                             allEvidence.push(headlessEvidence);
                             const updatedRanked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+                            const updatedQuality = analyzeEvidenceQuality({
+                                evidence: updatedRanked,
+                                gaps: allGaps,
+                                lowValueOutcomes: allLowValueOutcomes
+                            });
                             const updatedDecision = decideNextResearchStep({
                                 evidence: updatedRanked,
                                 suggestedHeadlessUrls: [],
                                 passIndex,
                                 maxPasses: DEFAULT_MAX_PASSES,
                                 headlessAttempts,
-                                maxHeadlessAttempts: DEFAULT_MAX_HEADLESS_ATTEMPTS
+                                maxHeadlessAttempts: DEFAULT_MAX_HEADLESS_ATTEMPTS,
+                                quality: updatedQuality
                             });
+                            const exhaustedBudget = updatedDecision.action !== 'answer' && passIndex + 1 >= DEFAULT_MAX_PASSES;
                             return {
-                                decision: decisionForAnswer(updatedDecision.action === 'answer' ? 'answer' : 'answer-with-caveat', query, updatedRanked),
+                                decision: decisionForAnswer({
+                                    action: updatedDecision.action === 'answer' ? 'answer' : 'answer-with-caveat',
+                                    query,
+                                    ranked: updatedRanked,
+                                    exhaustedBudget
+                                }),
                                 evidence: updatedRanked,
                                 workerPass: combinedWorkerPass({
                                     lastPass,
                                     previousQueries,
                                     allGaps,
                                     allLowValueOutcomes,
-                                    exhaustedBudget: updatedDecision.action !== 'answer'
+                                    exhaustedBudget
                                 }),
                                 metadata: buildMetadata({
                                     previousQueries,
@@ -192,7 +212,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                                     allGaps,
                                     allLowValueOutcomes,
                                     headlessAttempts,
-                                    exhaustedBudget: updatedDecision.action !== 'answer'
+                                    exhaustedBudget,
+                                    caveatReasons: updatedQuality.caveatReasons
                                 })
                             };
                         }
@@ -217,20 +238,22 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                                 allGaps,
                                 allLowValueOutcomes,
                                 headlessAttempts,
-                                exhaustedBudget: false
+                                exhaustedBudget: false,
+                                caveatReasons: quality.caveatReasons
                             })
                         };
                     }
                     if (decision.action === 'answer' || decision.action === 'answer-with-caveat') {
+                        const exhaustedBudget = decision.action === 'answer-with-caveat' && passIndex + 1 >= DEFAULT_MAX_PASSES;
                         return {
-                            decision: decisionForAnswer(decision.action, query, ranked),
+                            decision: decisionForAnswer({ action: decision.action, query, ranked, exhaustedBudget }),
                             evidence: ranked,
                             workerPass: combinedWorkerPass({
                                 lastPass,
                                 previousQueries,
                                 allGaps,
                                 allLowValueOutcomes,
-                                exhaustedBudget: decision.action === 'answer-with-caveat'
+                                exhaustedBudget
                             }),
                             metadata: buildMetadata({
                                 previousQueries,
@@ -238,15 +261,21 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                                 allGaps,
                                 allLowValueOutcomes,
                                 headlessAttempts,
-                                exhaustedBudget: decision.action === 'answer-with-caveat'
+                                exhaustedBudget,
+                                caveatReasons: quality.caveatReasons
                             })
                         };
                     }
                 }
             }
             const ranked = rankEvidence(allEvidence.filter((item) => item.sourceKind !== 'package-page'));
+            const quality = analyzeEvidenceQuality({
+                evidence: ranked,
+                gaps: allGaps,
+                lowValueOutcomes: allLowValueOutcomes
+            });
             return {
-                decision: decisionForAnswer('answer-with-caveat', query, ranked),
+                decision: decisionForAnswer({ action: 'answer-with-caveat', query, ranked, exhaustedBudget: true }),
                 evidence: ranked,
                 workerPass: combinedWorkerPass({
                     lastPass,
@@ -261,7 +290,8 @@ export function createResearchOrchestrator({ worker, fetchDirect, headlessFetch
                     allGaps,
                     allLowValueOutcomes,
                     headlessAttempts,
-                    exhaustedBudget: true
+                    exhaustedBudget: true,
+                    caveatReasons: quality.caveatReasons
                 })
             };
         }

package/dist/orchestration/research-worker.js

@@ -6,10 +6,15 @@ function classifySource(url) {
 function summarizeText(text, maxLength = 180) {
     return text.replace(/\s+/g, ' ').trim().slice(0, maxLength);
 }
+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}`);
+}
 function evidenceFromFetch(fetched, fallbackTitle) {
     const content = fetched.content;
     if (fetched.status !== 'ok' || !content)
         return null;
+    if (isBotCheckContent({ title: content.title, text: content.text }))
+        return null;
     const sourceKind = classifySource(fetched.url);
     if (sourceKind === 'package-page') {
         return null;
@@ -26,6 +31,13 @@ function evidenceFromFetch(fetched, fallbackTitle) {
 function lowValueOutcomeFromFetch(fetched) {
     if (fetched.status !== 'ok' || !fetched.content)
         return null;
+    if (isBotCheckContent({ title: fetched.content.title, text: fetched.content.text })) {
+        return {
+            kind: 'bot-check',
+            url: fetched.url,
+            message: 'Fetched page showed a bot-check or security verification page.'
+        };
+    }
     if (classifySource(fetched.url) !== 'package-page')
         return null;
     return {

package/dist/orchestration/stop-decider.d.ts

@@ -1,4 +1,5 @@
 import type { ResearchEvidence } from './research-types.js';
+import type { EvidenceQualityReport } from './evidence-quality.js';
 export type ResearchStepDecision = {
     action: 'answer';
 } | {
@@ -9,11 +10,12 @@ export type ResearchStepDecision = {
     action: 'headless';
     url: string;
 };
-export declare function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts }: {
+export declare function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts, quality }: {
     evidence: ResearchEvidence[];
     suggestedHeadlessUrls: string[];
     passIndex: number;
     maxPasses: number;
     headlessAttempts: number;
     maxHeadlessAttempts: number;
+    quality?: EvidenceQualityReport;
 }): ResearchStepDecision;

package/dist/orchestration/stop-decider.js

@@ -1,7 +1,35 @@
 import { hasOfficialEvidence, strongEvidenceCount } from './evidence-ranker.js';
-export function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts }) {
-    if (strongEvidenceCount(evidence) >= 2 && hasOfficialEvidence(evidence)) {
-        return { action: 'answer' };
+function activeCaveatReasons(evidence, quality) {
+    const reasons = quality?.caveatReasons ?? [];
+    if (!hasOfficialDocsAndApi(evidence))
+        return reasons;
+    return reasons.filter((reason) => reason !== 'low-diversity');
+}
+function hasQualityConcern(evidence, quality) {
+    return activeCaveatReasons(evidence, quality).length > 0;
+}
+function hasOfficialDocsAndApi(evidence) {
+    return evidence.some((item) => item.sourceKind === 'official-docs') &&
+        evidence.some((item) => item.sourceKind === 'official-api');
+}
+function shouldSearchForBetterQuality({ evidence, quality, passIndex, maxPasses }) {
+    if (!quality)
+        return false;
+    if (passIndex + 1 >= maxPasses)
+        return false;
+    if (quality.flags.hasOnlyCommunityEvidence)
+        return true;
+    if (quality.flags.hasLowDiversity && !hasOfficialDocsAndApi(evidence))
+        return true;
+    return false;
+}
+export function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts, quality }) {
+    const strongEnough = strongEvidenceCount(evidence) >= 2 && hasOfficialEvidence(evidence);
+    if (strongEnough && shouldSearchForBetterQuality({ evidence, quality, passIndex, maxPasses })) {
+        return { action: 'search-again' };
+    }
+    if (strongEnough) {
+        return hasQualityConcern(evidence, quality) ? { action: 'answer-with-caveat' } : { action: 'answer' };
     }
     const headlessUrl = suggestedHeadlessUrls.find((url) => !url.includes('npmjs.com/package/'));
     if (headlessUrl && headlessAttempts < maxHeadlessAttempts) {

package/dist/search/brave.d.ts

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

package/dist/search/brave.js

@@ -0,0 +1,83 @@
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+const BRAVE_WEB_SEARCH_URL = 'https://api.search.brave.com/res/v1/web/search';
+function resultWithPresentation(result) {
+    return { ...result, presentation: buildSearchPresentation(result) };
+}
+function normalizeResults(response) {
+    return (response.web?.results ?? []).flatMap((item) => {
+        if (typeof item.title !== 'string' || typeof item.url !== 'string') {
+            return [];
+        }
+        return [
+            {
+                title: item.title,
+                url: item.url,
+                snippet: typeof item.description === 'string' ? item.description : ''
+            }
+        ];
+    });
+}
+function buildBraveUrl(query) {
+    const url = new URL(BRAVE_WEB_SEARCH_URL);
+    url.searchParams.set('q', query);
+    return url.toString();
+}
+export function createBraveSearchTool({ apiKey, fetchImpl = fetch }) {
+    return async function braveSearch({ query }) {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery) {
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'brave', cacheHit: false },
+                error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
+            });
+        }
+        if (!apiKey?.trim()) {
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'brave', cacheHit: false },
+                error: {
+                    code: 'BACKEND_CONFIG_INVALID',
+                    message: 'Brave search requires PI_WEB_AGENT_BRAVE_API_KEY.'
+                }
+            });
+        }
+        try {
+            const response = await fetchImpl(buildBraveUrl(normalizedQuery), {
+                headers: {
+                    Accept: 'application/json',
+                    'X-Subscription-Token': apiKey
+                }
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const parsed = (await response.json());
+            const results = normalizeResults(parsed);
+            if (results.length === 0) {
+                return resultWithPresentation({
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'brave', cacheHit: false },
+                    error: { code: 'NO_RESULTS', message: 'Brave returned no usable results for this query.' }
+                });
+            }
+            return resultWithPresentation({
+                status: 'ok',
+                results,
+                metadata: { backend: 'brave', cacheHit: false }
+            });
+        }
+        catch (error) {
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            return resultWithPresentation({
+                status: 'error',
+                results: [],
+                metadata: { backend: 'brave', cacheHit: false },
+                error: { code: 'FETCH_FAILED', message: `Brave search request failed: ${rawMessage}` }
+            });
+        }
+    };
+}

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

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

package/dist/tools/web-explore.js

@@ -25,7 +25,8 @@ export function createWebExploreTool({ explore = createResearchWorkflow() } = {}
         }));
         const synthesized = synthesizeAnswer({
             evidence: result.evidence,
-            partial: result.decision.action !== 'answer'
+            partial: result.decision.action !== 'answer',
+            caveatReasons: result.metadata?.caveatReasons
         });
         const shaped = {
             status: 'ok',

package/dist/types.d.ts

@@ -11,9 +11,9 @@ export type ToolError = {
     message: string;
 };
 export type SearchMetadata = {
-    backend: 'duckduckgo' | 'searxng';
+    backend: 'duckduckgo' | 'searxng' | 'brave';
     cacheHit: boolean;
-    fallbackFrom?: 'searxng';
+    fallbackFrom?: 'searxng' | 'brave';
     fallbackReason?: string;
 };
 export type FetchMetadata = {
@@ -68,6 +68,7 @@ export type WebExploreResponse = {
         fetchedPages: number;
         headlessAttempts: number;
         exhaustedBudget: boolean;
+        caveatReasons?: string[];
     };
     presentation?: PresentationEnvelope;
     error?: ToolError;

package/package.json

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