@demigodmode/pi-web-agent 1.10.0 → 1.12.0

package/dist/search/fanout.js

@@ -1,5 +1,7 @@
 import { buildSearchPresentation } from '../presentation/search-presentation.js';
 import { canonicalizeUrl } from '../orchestration/url.js';
+import { failureOf, isTerminalFailure } from '../backends/failure.js';
+import { RETRY_BASE_MS, RETRY_JITTER_MS } from '../backends/fallback-policy.js';
 const FANOUT_MIN_RESULTS = 3;
 function hostOf(url) {
     try {
@@ -44,75 +46,112 @@ function merge(lists) {
 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) {
+export const FANOUT_PROVIDER_TIMEOUT_MS = 8000;
+const BACKSTOP_MARGIN_MS = 250;
+/** Longest a policy-wrapped provider can legitimately take: two timed-out calls and the retry sleep. */
+export function fanoutBackstopMs(timeoutMs) {
+    return 2 * timeoutMs + RETRY_BASE_MS + RETRY_JITTER_MS + BACKSTOP_MARGIN_MS;
+}
+/**
+ * Per-call timeout. Wrap it INSIDE the retry policy so a stalled call is a transient
+ * failure the policy can retry once (#55).
+ */
+export function withCallTimeout(search, timeoutMs, name) {
+    return (input) => withTimeout(search(input), timeoutMs, name);
+}
+/** A provider that doesn't answer in time (or throws) counts as a transient failure, so one
+ *  slow/unreachable provider (e.g. a down self-hosted SearXNG) can't stall the whole fanout. */
+function withTimeout(promise, ms, name) {
+    const timedOut = () => ({
+        status: 'error',
+        results: [],
+        metadata: { backend: name, cacheHit: false },
+        error: { code: 'FETCH_FAILED', message: `${name} did not answer in time.`, failure: { kind: 'transient' } }
+    });
     return new Promise((resolve) => {
-        const timer = setTimeout(() => resolve(undefined), ms);
+        const timer = setTimeout(() => resolve(timedOut()), ms);
+        timer.unref?.();
         promise.then((value) => {
             clearTimeout(timer);
             resolve(value);
         }, () => {
             clearTimeout(timer);
-            resolve(undefined);
+            resolve(timedOut());
         });
     });
 }
+function outcomeOf(name, response) {
+    const failure = failureOf(response);
+    if (!failure) {
+        return response.results.length > 0 ? { provider: name, outcome: 'results', count: response.results.length } : { provider: name, outcome: 'empty' };
+    }
+    const skipped = response.metadata.attempts?.find((a) => a.outcome === 'skipped');
+    return skipped
+        ? { provider: name, outcome: 'skipped', failure, ...(skipped.skipReason ? { skipReason: skipped.skipReason } : {}) }
+        : { provider: name, outcome: 'failed', failure };
+}
 export function createFanoutSearch({ providers, mode, timeoutMs = FANOUT_PROVIDER_TIMEOUT_MS }) {
+    const backstopMs = fanoutBackstopMs(timeoutMs);
     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 };
+            const responses = await Promise.all(set.map((p) => withTimeout(p.search({ query }), backstopMs, p.name)));
+            return set.map((provider, i) => ({ provider, response: responses[i] }));
         }
-        function finalize(lists, skipped, resolvedMode) {
-            if (lists.length === 0) {
-                const fanout = { mode: resolvedMode, providers: [] };
-                if (skipped.length > 0)
-                    fanout.skipped = skipped;
+        function finalize(entries, resolvedMode) {
+            const outcomes = entries.map(({ provider, response }) => outcomeOf(provider.name, response));
+            const attempts = entries.flatMap(({ response }) => response.metadata.attempts ?? []);
+            const contributing = entries.filter((_, i) => outcomes[i].outcome === 'results');
+            const fanout = {
+                mode: resolvedMode,
+                providers: contributing.map(({ provider }) => provider.name),
+                outcomes
+            };
+            const skippedNames = outcomes.filter((o) => o.outcome !== 'results').map((o) => o.provider);
+            if (skippedNames.length > 0)
+                fanout.skipped = skippedNames;
+            // 1. terminal
+            const terminal = entries.find(({ response }) => isTerminalFailure(failureOf(response)));
+            if (terminal) {
+                return withPresentation({ ...terminal.response, metadata: { ...terminal.response.metadata, backend: primary.name, fanout, attempts } });
+            }
+            const unavailable = outcomes
+                .filter((o) => o.outcome === 'failed' || o.outcome === 'skipped')
+                .map((o) => ({ provider: o.provider, kind: o.failure.kind }));
+            const coverage = unavailable.length > 0 ? { coverage: { partial: true, unavailable } } : {};
+            // 2. results
+            if (contributing.length > 0) {
                 return withPresentation({
-                    status: 'error',
-                    results: [],
-                    metadata: { backend: primary.name, cacheHit: false, fanout },
-                    error: { code: 'FANOUT_NO_RESULTS', message: 'No fanout provider returned usable results.' }
+                    status: 'ok',
+                    results: merge(contributing.map(({ provider, response }) => ({ name: provider.name, results: response.results }))),
+                    metadata: { backend: primary.name, cacheHit: false, fanout, attempts, ...coverage }
                 });
             }
-            const fanout = { mode: resolvedMode, providers: lists.map((l) => l.name) };
-            if (skipped.length > 0)
-                fanout.skipped = skipped;
+            // 3. valid empty
+            if (outcomes.some((o) => o.outcome === 'empty')) {
+                return withPresentation({ status: 'ok', results: [], metadata: { backend: primary.name, cacheHit: false, fanout, attempts, ...coverage } });
+            }
+            // 4. all failed or skipped: non-terminal. A bad_request anywhere wins so an outer
+            // chain never falls back on it, whatever order the providers ran in.
+            const badRequest = outcomes.find((o) => o.failure?.kind === 'bad_request')?.failure;
+            const lastFailure = badRequest ?? [...outcomes].reverse().find((o) => o.failure)?.failure ?? { kind: 'bad_response' };
             return withPresentation({
-                status: 'ok',
-                results: merge(lists),
-                metadata: { backend: primary.name, cacheHit: false, fanout }
+                status: 'error',
+                results: [],
+                metadata: { backend: primary.name, cacheHit: false, fanout, attempts },
+                error: { code: 'FANOUT_ALL_FAILED', message: 'Every fanout provider failed or was unavailable.', failure: lastFailure }
             });
         }
         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 primaryResponse = await withTimeout(primary.search({ query }), backstopMs, primary.name);
+            if (isTerminalFailure(failureOf(primaryResponse))) {
+                return finalize([{ provider: primary, response: primaryResponse }], 'auto');
+            }
+            if (primaryResponse.status === 'ok' && primaryResponse.results.length > 0 && !primaryLooksWeak(primaryResponse.results)) {
+                return withPresentation(primaryResponse); // 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');
+            return finalize([{ provider: primary, response: primaryResponse }, ...(await runSet(rest))], 'auto');
         }
-        const { contributing, skipped } = await runSet(providers);
-        return finalize(contributing, skipped, 'on');
+        return finalize(await runSet(providers), 'on');
     };
 }

package/dist/search/json-provider.d.ts

@@ -0,0 +1,32 @@
+import type { SearchProviderName, SearchResult, WebSearchResponse } from '../types.js';
+export type Normalized = {
+    rawCount: number;
+    results: SearchResult[];
+};
+export type JsonSearchProviderOptions = {
+    name: Exclude<SearchProviderName, 'duckduckgo'>;
+    label: string;
+    /** Omit for providers that need no key (SearXNG, keyless Tavily). */
+    apiKey?: string;
+    requiresKey?: boolean;
+    missingKeyMessage?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    request: (query: string) => {
+        url: string;
+        init?: RequestInit;
+    };
+    /** Returns undefined when the body does not have the documented shape. */
+    normalize: (json: unknown) => Normalized | undefined;
+    /** A 200 that is empty only because the provider degraded (e.g. SearXNG engines suspended). */
+    isDegradedEmpty?: (json: unknown) => boolean;
+};
+/**
+ * Classifies only; the fallback policy decides what to do (#55).
+ * Valid empty responses are `ok` with `[]`; anything malformed or degraded is `bad_response`.
+ */
+export declare function createJsonSearchProvider(options: JsonSearchProviderOptions): ({ query }: {
+    query: string;
+}) => Promise<WebSearchResponse>;
+/** Shared normalizer for `{ results: [{ title, url, <snippetField> }] }` bodies. */
+export declare function normalizeResultsArray(json: unknown, arrayPath: (body: any) => unknown, snippetField: string): Normalized | undefined;

package/dist/search/json-provider.js

@@ -0,0 +1,76 @@
+import { classifyHttpFailure, readResponseParts } from '../backends/provider-failure.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
+function respond(result) {
+    return { ...result, presentation: buildSearchPresentation(result) };
+}
+/**
+ * Classifies only; the fallback policy decides what to do (#55).
+ * Valid empty responses are `ok` with `[]`; anything malformed or degraded is `bad_response`.
+ */
+export function createJsonSearchProvider(options) {
+    const { name, label, fetchImpl = fetch, now = Date.now } = options;
+    const requiresKey = options.requiresKey ?? true;
+    const error = (code, message, failure) => respond({ status: 'error', results: [], metadata: { backend: name, cacheHit: false }, error: { code, message, failure } });
+    return async function search({ query }) {
+        const normalizedQuery = query.trim();
+        if (!normalizedQuery) {
+            return error('INVALID_QUERY', 'Query must not be empty.', { kind: 'bad_request' });
+        }
+        if (requiresKey && !options.apiKey?.trim()) {
+            return error('BACKEND_CONFIG_INVALID', options.missingKeyMessage ?? `${label} search is not configured.`, {
+                kind: 'not_configured'
+            });
+        }
+        const { url, init } = options.request(normalizedQuery);
+        let response;
+        try {
+            // No init for plain GETs, so callers and tests see fetch(url) exactly.
+            response = await (init ? fetchImpl(url, init) : fetchImpl(url));
+        }
+        catch (thrown) {
+            const message = thrown instanceof Error ? thrown.message : String(thrown);
+            return error('FETCH_FAILED', `${label} search request failed: ${message}`, { kind: 'transient' });
+        }
+        let parts;
+        try {
+            parts = await readResponseParts(response);
+        }
+        catch (thrown) {
+            const message = thrown instanceof Error ? thrown.message : String(thrown);
+            return error('FETCH_FAILED', `${label} search response could not be read: ${message}`, { kind: 'transient' });
+        }
+        if (!response.ok) {
+            return error('FETCH_FAILED', `${label} search request failed: HTTP ${response.status}`, classifyHttpFailure(name, parts, now()));
+        }
+        const normalized = parts.json === undefined ? undefined : options.normalize(parts.json);
+        if (!normalized || (normalized.rawCount > 0 && normalized.results.length === 0)) {
+            return error('BAD_RESPONSE', `${label} returned a response that did not match the expected format.`, {
+                kind: 'bad_response',
+                httpStatus: response.status
+            });
+        }
+        if (normalized.results.length === 0 && options.isDegradedEmpty?.(parts.json)) {
+            return error('BAD_RESPONSE', `${label} returned no results because some of its sources were unavailable.`, {
+                kind: 'bad_response',
+                httpStatus: response.status
+            });
+        }
+        return respond({ status: 'ok', results: normalized.results, metadata: { backend: name, cacheHit: false } });
+    };
+}
+/** Shared normalizer for `{ results: [{ title, url, <snippetField> }] }` bodies. */
+export function normalizeResultsArray(json, arrayPath, snippetField) {
+    if (!json || typeof json !== 'object')
+        return undefined;
+    const raw = arrayPath(json);
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw))
+        return undefined;
+    return {
+        rawCount: raw.length,
+        results: raw.flatMap((item) => item && typeof item.title === 'string' && typeof item.url === 'string'
+            ? [{ title: item.title, url: item.url, snippet: typeof item[snippetField] === 'string' ? item[snippetField] : '' }]
+            : [])
+    };
+}

package/dist/search/searxng.d.ts

@@ -1,9 +1,8 @@
 import type { SearxngOptions } from '../backends/config.js';
-import type { WebSearchResponse } from '../types.js';
 export declare function createSearxngSearchTool({ baseUrl, options, fetchImpl }: {
     baseUrl: string;
     options?: SearxngOptions;
     fetchImpl?: typeof fetch;
 }): ({ query }: {
     query: string;
-}) => Promise<WebSearchResponse>;
+}) => Promise<import("../types.js").WebSearchResponse>;

package/dist/search/searxng.js

@@ -1,4 +1,4 @@
-import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { createJsonSearchProvider, normalizeResultsArray } from './json-provider.js';
 function buildSearchUrl(baseUrl, query, options = {}) {
     const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     url.searchParams.set('q', query);
@@ -11,62 +11,20 @@ function buildSearchUrl(baseUrl, query, options = {}) {
         url.searchParams.set('safesearch', String(options.safesearch));
     return url.toString();
 }
-function normalizeResults(response) {
-    return (response.results ?? []).flatMap((result) => {
-        if (typeof result.title !== 'string' || typeof result.url !== 'string') {
-            return [];
-        }
-        return [
-            {
-                title: result.title,
-                url: result.url,
-                snippet: typeof result.content === 'string' ? result.content : ''
-            }
-        ];
-    });
-}
 export function createSearxngSearchTool({ baseUrl, options, fetchImpl = fetch }) {
-    return async function searxngSearch({ query }) {
-        const normalizedQuery = query.trim();
-        if (!normalizedQuery) {
-            const result = {
-                status: 'error',
-                results: [],
-                metadata: { backend: 'searxng', cacheHit: false },
-                error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
-            };
-            return { ...result, presentation: buildSearchPresentation(result) };
+    return createJsonSearchProvider({
+        name: 'searxng',
+        label: 'SearXNG',
+        requiresKey: false,
+        fetchImpl,
+        request: (query) => ({ url: buildSearchUrl(baseUrl, query, options) }),
+        normalize: (json) => normalizeResultsArray(json, (body) => body.results, 'content'),
+        // Suspended upstream engines still answer 200; version-dependent field (UNVERIFIED everywhere).
+        isDegradedEmpty: (json) => {
+            const unresponsive = json.unresponsive_engines;
+            if (Array.isArray(unresponsive))
+                return unresponsive.length > 0;
+            return !!unresponsive && typeof unresponsive === 'object' && Object.keys(unresponsive).length > 0;
         }
-        try {
-            const response = await fetchImpl(buildSearchUrl(baseUrl, normalizedQuery, options));
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
-            }
-            const parsed = (await response.json());
-            const results = normalizeResults(parsed);
-            const result = results.length > 0
-                ? {
-                    status: 'ok',
-                    results,
-                    metadata: { backend: 'searxng', cacheHit: false }
-                }
-                : {
-                    status: 'error',
-                    results: [],
-                    metadata: { backend: 'searxng', cacheHit: false },
-                    error: { code: 'NO_RESULTS', message: 'SearXNG returned no usable results for this query.' }
-                };
-            return { ...result, presentation: buildSearchPresentation(result) };
-        }
-        catch (error) {
-            const rawMessage = error instanceof Error ? error.message : String(error);
-            const result = {
-                status: 'error',
-                results: [],
-                metadata: { backend: 'searxng', cacheHit: false },
-                error: { code: 'FETCH_FAILED', message: `SearXNG search request failed: ${rawMessage}` }
-            };
-            return { ...result, presentation: buildSearchPresentation(result) };
-        }
-    };
+    });
 }

package/dist/search/tavily.d.ts

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

package/dist/search/tavily.js

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

package/dist/search/youcom.d.ts

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

package/dist/search/youcom.js

@@ -1,81 +1,20 @@
-import { buildSearchPresentation } from '../presentation/search-presentation.js';
+import { createJsonSearchProvider, normalizeResultsArray } from './json-provider.js';
 const YOUCOM_SEARCH_URL = 'https://api.you.com/v1/agents/search';
-function resultWithPresentation(result) {
-    return { ...result, presentation: buildSearchPresentation(result) };
-}
-function normalizeResults(response) {
-    return (response.results ?? []).flatMap((item) => {
-        if (typeof item.title !== 'string' || typeof item.url !== 'string') {
-            return [];
-        }
-        return [
-            {
-                title: item.title,
-                url: item.url,
-                snippet: typeof item.snippet === 'string' ? item.snippet : ''
-            }
-        ];
-    });
-}
 export function createYouComSearchTool({ apiKey, fetchImpl = fetch }) {
-    return async function youComSearch({ query }) {
-        const normalizedQuery = query.trim();
-        if (!normalizedQuery) {
-            return resultWithPresentation({
-                status: 'error',
-                results: [],
-                metadata: { backend: 'youcom', cacheHit: false },
-                error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
-            });
-        }
-        if (!apiKey?.trim()) {
-            return resultWithPresentation({
-                status: 'error',
-                results: [],
-                metadata: { backend: 'youcom', cacheHit: false },
-                error: {
-                    code: 'BACKEND_CONFIG_INVALID',
-                    message: 'You.com search requires YDC_API_KEY.'
-                }
-            });
-        }
-        try {
-            const response = await fetchImpl(YOUCOM_SEARCH_URL, {
+    return createJsonSearchProvider({
+        name: 'youcom',
+        label: 'You.com',
+        apiKey,
+        missingKeyMessage: 'You.com search requires YDC_API_KEY.',
+        fetchImpl,
+        request: (query) => ({
+            url: YOUCOM_SEARCH_URL,
+            init: {
                 method: 'POST',
-                headers: {
-                    Accept: 'application/json',
-                    'Content-Type': 'application/json',
-                    'X-API-Key': apiKey
-                },
-                body: JSON.stringify({ query: normalizedQuery, max_results: 10 })
-            });
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}`);
-            }
-            const parsed = (await response.json());
-            const results = normalizeResults(parsed);
-            if (results.length === 0) {
-                return resultWithPresentation({
-                    status: 'error',
-                    results: [],
-                    metadata: { backend: 'youcom', cacheHit: false },
-                    error: { code: 'NO_RESULTS', message: 'You.com returned no usable results for this query.' }
-                });
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'X-API-Key': apiKey ?? '' },
+                body: JSON.stringify({ query, max_results: 10 })
             }
-            return resultWithPresentation({
-                status: 'ok',
-                results,
-                metadata: { backend: 'youcom', cacheHit: false }
-            });
-        }
-        catch (error) {
-            const rawMessage = error instanceof Error ? error.message : String(error);
-            return resultWithPresentation({
-                status: 'error',
-                results: [],
-                metadata: { backend: 'youcom', cacheHit: false },
-                error: { code: 'FETCH_FAILED', message: `You.com search request failed: ${rawMessage}` }
-            });
-        }
-    };
+        }),
+        normalize: (json) => normalizeResultsArray(json, (body) => body.results, 'snippet')
+    });
 }

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

@@ -11,6 +11,10 @@ export declare function createWebExploreTool({ explore }?: {
             evidence: ResearchEvidence[];
             workerPass: unknown;
             metadata?: WebExploreResponse['metadata'];
+            terminalFailure?: {
+                code: string;
+                message: string;
+            };
         }>;
     } | ((input: {
         query: string;
@@ -21,6 +25,10 @@ export declare function createWebExploreTool({ explore }?: {
         evidence: ResearchEvidence[];
         workerPass: unknown;
         metadata?: WebExploreResponse['metadata'];
+        terminalFailure?: {
+            code: string;
+            message: string;
+        };
     }>);
 }): ({ query }: {
     query: string;
@@ -42,6 +50,7 @@ export declare function createWebExploreTool({ explore }?: {
         caveatReasons?: string[];
         fanoutProviders?: import("../types.js").SearchProviderName[];
         fanoutSkipped?: import("../types.js").SearchProviderName[];
+        attempts?: import("../types.js").Attempt[];
     };
     error?: import("../types.js").ToolError;
 }>;

package/dist/tools/web-explore.js

@@ -18,15 +18,29 @@ export function createWebExploreTool({ explore = createResearchWorkflow() } = {}
             };
         }
         const result = await runExplore({ query: normalizedQuery });
+        if (result.terminalFailure) {
+            const failed = {
+                status: 'error',
+                findings: [],
+                sources: [],
+                error: result.terminalFailure,
+                metadata: result.metadata
+            };
+            return { ...failed, presentation: buildExplorePresentation(failed) };
+        }
         const sources = result.evidence.slice(0, 4).map((item) => ({
             title: item.title,
             url: item.url,
             method: item.method
         }));
+        const reasons = (result.metadata?.caveatReasons ?? []);
+        const decisionPartial = result.decision.action !== 'answer';
+        const coveragePartial = reasons.includes('partial-search-coverage');
         const synthesized = synthesizeAnswer({
             evidence: result.evidence,
-            partial: result.decision.action !== 'answer',
-            caveatReasons: result.metadata?.caveatReasons
+            partial: decisionPartial || coveragePartial,
+            // A confident answer with partial coverage mentions only the coverage, not unrelated quality notes.
+            caveatReasons: decisionPartial ? reasons : ['partial-search-coverage']
         });
         const shaped = {
             status: 'ok',