@librechat/agents 3.7.9 → 3.7.11

package/src/tools/search/search.ts

@@ -1,9 +1,14 @@
 import axios from 'axios';
 import { RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
 import type * as t from './types';
-import { getAttribution, createDefaultLogger } from './utils';
+import {
+  getAttribution,
+  createDefaultLogger,
+  formatErrorForLog,
+} from './utils';
 import { createKeenableAPI } from './keenable-search';
 import { createTavilyAPI } from './tavily-search';
+import { createSearchMetrics } from './metrics';
 import { createCrwAPI } from './crw-search';
 import { BaseReranker } from './rerankers';
 
@@ -139,50 +144,67 @@ function createSourceUpdateCallback(sourceMap: Map<string, t.ValidSource>) {
   };
 }
 
+/** Returns undefined without logging when there is nothing to rank: an empty
+ * scrape is already counted by the scrape summary, and a missing reranker is
+ * reported once at tool construction rather than once per source. */
 const getHighlights = async ({
   query,
   content,
   reranker,
+  metrics,
   topResults = 5,
   maxContentLength = DEFAULT_MAX_CONTENT_LENGTH,
   chunkOptions,
-  logger,
 }: {
   content: string;
   query: string;
   reranker?: BaseReranker;
+  metrics: t.SearchMetrics;
   topResults?: number;
   maxContentLength?: number;
   chunkOptions?: { chunkSize: number; chunkOverlap: number };
-  logger?: t.Logger;
 }): Promise<t.Highlight[] | undefined> => {
-  const logger_ = logger || createDefaultLogger();
-
-  if (!content) {
-    logger_.warn('No content provided for highlights');
-    return;
-  }
-  if (!reranker) {
-    logger_.warn('No reranker provided for highlights');
+  if (!content || !reranker) {
     return;
   }
 
+  /** Both failures are this reranker's attempt for this source, so they stay
+   * in its phase — but they are caught separately: sharing one `catch` would
+   * report a reranker that threw as a chunking failure, with a chunk count
+   * of zero for text that split fine. */
+  const chunkStartedAt = Date.now();
+  let documents: string[];
   try {
-    const documents = await chunker.splitText(
+    documents = await chunker.splitText(
       truncateContent(content, maxContentLength),
       chunkOptions
     );
-    if (Array.isArray(documents)) {
-      return await reranker.rerank(query, documents, topResults);
-    } else {
-      logger_.error(
-        'Expected documents to be an array, got:',
-        typeof documents
-      );
-      return;
-    }
   } catch (error) {
-    logger_.error('Error in content processing:', error);
+    metrics.recordRerank({
+      provider: reranker.provider,
+      chunks: 0,
+      results: 0,
+      durationMs: Date.now() - chunkStartedAt,
+      reason: 'chunk_error',
+      error: formatErrorForLog(error),
+    });
+    return;
+  }
+
+  const rerankStartedAt = Date.now();
+  try {
+    return await reranker.rerank(query, documents, topResults, metrics);
+  } catch (error) {
+    /** The bundled rerankers absorb their own failures and record the
+     * observation themselves; a custom implementation may reject instead. */
+    metrics.recordRerank({
+      provider: reranker.provider,
+      chunks: documents.length,
+      results: 0,
+      durationMs: Date.now() - rerankStartedAt,
+      reason: 'error',
+      error: formatErrorForLog(error),
+    });
     return;
   }
 };
@@ -598,54 +620,94 @@ export const createSourceProcessor = (
       };
     }
 
-    logger_.error(
-      `Error scraping ${url}: ${response.error ?? 'Unknown error'}`
-    );
     return { url, attribution, error: true, content: '' };
   };
 
   const addHighlights = async (
     result: t.ScrapeResult,
     query: string,
+    metrics: t.SearchMetrics,
     onGetHighlights: t.SearchToolConfig['onGetHighlights']
   ): Promise<t.ScrapeResult> => {
-    if (result.error != null) {
-      return result;
+    const highlights = await getHighlights({
+      query,
+      reranker,
+      metrics,
+      topResults,
+      content: result.content,
+      maxContentLength,
+      chunkOptions,
+    });
+    if (onGetHighlights) {
+      onGetHighlights(result.url);
     }
+    return { ...result, highlights };
+  };
+
+  /** Scrape and rerank one link, recording the single observation that link
+   * contributes to the run summary — the only place a per-link outcome is
+   * reported, so nothing here logs per link. */
+  const processLink = async (
+    url: string,
+    response: t.AnyScraperResponse,
+    query: string,
+    metrics: t.SearchMetrics,
+    onGetHighlights: t.SearchToolConfig['onGetHighlights']
+  ): Promise<t.ScrapeResult> => {
+    /** `extractContent`/`extractMetadata` are the scraper implementation's
+     * code: one malformed response must not reject alongside its siblings,
+     * which would discard their results and their observations with them. */
+    let scraped: t.ScrapeResult;
     try {
-      const highlights = await getHighlights({
-        query,
-        reranker,
-        topResults,
-        content: result.content,
-        maxContentLength,
-        chunkOptions,
-        logger: logger_,
-      });
-      if (onGetHighlights) {
-        onGetHighlights(result.url);
-      }
-      return { ...result, highlights };
+      scraped = processResponse(url, response);
     } catch (error) {
-      logger_.error('Error processing scraped content:', error);
-      return result;
+      metrics.recordScrape({ url, error: String(error) });
+      return { url, error: true, content: '' };
     }
+    if (scraped.error === true) {
+      metrics.recordScrape({ url, error: response.error ?? 'Unknown error' });
+      return scraped;
+    }
+    /** `getHighlights` absorbs its own failures, so only a throwing
+     * `onGetHighlights` consumer reaches here; one bad callback must not
+     * discard the sibling links awaiting alongside it. */
+    const result = await addHighlights(
+      scraped,
+      query,
+      metrics,
+      onGetHighlights
+    ).catch((error) => {
+      logger_.error('Error processing scraped content:', error);
+      return scraped;
+    });
+    metrics.recordScrape({
+      url,
+      chars: result.content.length,
+      highlights: result.highlights?.length ?? 0,
+    });
+    return result;
   };
 
   const webScraper = {
     scrapeMany: async ({
       query,
       links,
+      metrics,
       onGetHighlights,
     }: {
       query: string;
       links: string[];
+      metrics: t.SearchMetrics;
       onGetHighlights: t.SearchToolConfig['onGetHighlights'];
     }): Promise<Array<t.ScrapeResult>> => {
-      logger_.debug(`Scraping ${links.length} links`);
-      try {
-        let responses: Array<[string, t.AnyScraperResponse]>;
+      let responses: Array<[string, t.AnyScraperResponse]>;
 
+      /** Scoped to acquisition alone. A batch `scrapeUrls` that rejects
+       * yields no per-link responses, so nothing downstream will ever report
+       * these links — without recording them here a total outage would flush
+       * no scrape summary at all, reading exactly like a search that never
+       * scraped anything. */
+      try {
         if (scraper.scrapeUrls) {
           responses = await scraper.scrapeUrls(links);
         } else {
@@ -653,25 +715,32 @@ export const createSourceProcessor = (
             links.map((link) =>
               scraper
                 .scrapeUrl(link, {})
-                .catch((error): [string, t.AnyScraperResponse] => {
-                  logger_.error(`Error scraping ${link}:`, error);
-                  return [link, { success: false, error: String(error) }];
-                })
+                .catch((error): [string, t.AnyScraperResponse] => [
+                  link,
+                  { success: false, error: String(error) },
+                ])
             )
           );
         }
+      } catch (error) {
+        logger_.error('Error in scrapeMany:', error);
+        const message = String(error);
+        for (const link of links) {
+          metrics.recordScrape({ url: link, error: message });
+        }
+        return [];
+      }
 
-        const withHighlights = await Promise.all(
+      try {
+        return await Promise.all(
           responses.map(([url, response]) =>
-            addHighlights(
-              processResponse(url, response),
-              query,
-              onGetHighlights
-            )
+            processLink(url, response, query, metrics, onGetHighlights)
           )
         );
-        return withHighlights;
       } catch (error) {
+        /** `processLink` absorbs its own failures and has already recorded
+         * whatever it reached, so this only preserves the soft failure the
+         * caller has always seen — it must not re-count these links. */
         logger_.error('Error in scrapeMany:', error);
         return [];
       }
@@ -682,12 +751,14 @@ export const createSourceProcessor = (
     links,
     query,
     target,
+    metrics,
     onGetHighlights,
     onContentScraped,
   }: {
     links: string[];
     query: string;
     target: number;
+    metrics: t.SearchMetrics;
     onGetHighlights: t.SearchToolConfig['onGetHighlights'];
     onContentScraped?: (link: string, update?: Partial<t.ValidSource>) => void;
   }): Promise<void> => {
@@ -695,6 +766,7 @@ export const createSourceProcessor = (
     // const remainingLinks = links.slice(target).reverse();
     const results = await webScraper.scrapeMany({
       query,
+      metrics,
       links: initialLinks,
       onGetHighlights,
     });
@@ -719,7 +791,11 @@ export const createSourceProcessor = (
     news,
     proMode = true,
     onGetHighlights,
+    metrics: ownerMetrics,
   }: t.ProcessSourcesFields): Promise<t.SearchResultData> => {
+    /** The caller owns the collector when it supplies one — it has phases of
+     * its own to fold in and flushes them together. */
+    const metrics = ownerMetrics ?? createSearchMetrics(logger_);
     try {
       if (!result.data) {
         return {
@@ -759,6 +835,7 @@ export const createSourceProcessor = (
         const onContentScraped = createSourceUpdateCallback(wikiSourceMap);
         await fetchContents({
           query,
+          metrics,
           target: 1,
           onGetHighlights,
           onContentScraped,
@@ -809,6 +886,7 @@ export const createSourceProcessor = (
         promises.push(
           fetchContents({
             query,
+            metrics,
             onGetHighlights,
             onContentScraped,
             links: organicLinks,
@@ -822,6 +900,7 @@ export const createSourceProcessor = (
         promises.push(
           fetchContents({
             query,
+            metrics,
             onGetHighlights,
             onContentScraped,
             links: topStoryLinks,
@@ -851,6 +930,10 @@ export const createSourceProcessor = (
         ...result.data,
         error: error instanceof Error ? error.message : String(error),
       };
+    } finally {
+      if (ownerMetrics == null) {
+        metrics.flush();
+      }
     }
   };
 

package/src/tools/search/tool.ts

@@ -21,6 +21,7 @@ import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { createCrwScraper } from './crw-scraper';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
+import { createSearchMetrics } from './metrics';
 import { createDefaultLogger } from './utils';
 import { createReranker } from './rerankers';
 import { Constants } from '@/common';
@@ -65,6 +66,50 @@ export function resolveSearchOutcome(
   return `Found ${count} result${count === 1 ? '' : 's'} for "${query}"`;
 }
 
+/** Distinct rows across the main search's two collections. SearXNG derives
+ * both from one result array — a row matching its news heuristic lands in
+ * `organic` and `topStories` alike — so summing the lengths would report
+ * more rows than the provider actually returned. */
+const countWebResults = (data: t.SearchResultData): number => {
+  const organic = data.organic ?? [];
+  const topStories = data.topStories ?? [];
+  if (organic.length === 0 || topStories.length === 0) {
+    return organic.length + topStories.length;
+  }
+
+  const links = new Set<string>();
+  let unlinked = 0;
+  for (const row of [...organic, ...topStories]) {
+    if (row.link) {
+      links.add(row.link);
+      continue;
+    }
+    /** Nothing to dedupe a blank link against, so it counts on its own. */
+    unlinked += 1;
+  }
+  return links.size + unlinked;
+};
+
+/** Rows a sub-search contributed, for the run summary's per-type breakdown. */
+const countResults = (
+  type: t.SubSearchType,
+  data?: t.SearchResultData
+): number => {
+  if (data == null) {
+    return 0;
+  }
+  if (type === 'images') {
+    return data.images?.length ?? 0;
+  }
+  if (type === 'videos') {
+    return data.videos?.length ?? 0;
+  }
+  if (type === 'news') {
+    return data.news?.length ?? 0;
+  }
+  return countWebResults(data);
+};
+
 /**
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link
@@ -79,6 +124,8 @@ export async function executeParallelSearches({
   videos,
   news,
   logger,
+  provider = 'unknown',
+  metrics,
 }: {
   searchAPI: ReturnType<typeof createSearchAPI>;
   query: string;
@@ -89,78 +136,81 @@ export async function executeParallelSearches({
   videos: boolean;
   news: boolean;
   logger: t.Logger;
+  /** Labels the provider in the run summary. Optional so the pre-existing
+   * call contract still holds for callers outside this package. */
+  provider?: string;
+  /** Collector owned by the caller. Without one, this call opens and flushes
+   * its own, so a direct caller still gets the single summary line. */
+  metrics?: t.SearchMetrics;
 }): Promise<t.SearchResult> {
+  const collector = metrics ?? createSearchMetrics(logger);
+  /** A rejected main search is fatal, but rethrowing it from the task itself
+   * would settle `Promise.all` while its siblings are still in flight, and
+   * their observations would then land in an already-flushed phase. Every
+   * task resolves; the failure is held here and raised once all have run. */
+  let mainFailure: { error: unknown } | undefined;
+
+  /** Sub-searches resolve rather than reject so their siblings still merge.
+   * A rejected MAIN search rethrows the provider's own error below — callers
+   * have always seen that error object, not a wrapped copy. */
+  const runSearch = async (type: t.SubSearchType): Promise<t.SearchResult> => {
+    const startedAt = Date.now();
+    try {
+      const result = await searchAPI.getSources({
+        query,
+        date,
+        country,
+        safeSearch,
+        ...(type !== 'web' && { type }),
+      });
+      collector.recordSearch({
+        provider,
+        type,
+        results: countResults(type, result.data),
+        durationMs: Date.now() - startedAt,
+        error: result.success ? undefined : (result.error ?? 'Search failed'),
+      });
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      collector.recordSearch({
+        provider,
+        type,
+        results: 0,
+        durationMs: Date.now() - startedAt,
+        error: message,
+        thrown: true,
+      });
+      if (type === 'web') {
+        mainFailure = { error };
+      }
+      return { success: false, error: message };
+    }
+  };
+
   // Prepare all search tasks to run in parallel
-  const searchTasks: Promise<t.SearchResult>[] = [
-    // Main search
-    searchAPI.getSources({
-      query,
-      date,
-      country,
-      safeSearch,
-    }),
-  ];
+  const searchTasks: Promise<t.SearchResult>[] = [runSearch('web')];
 
   if (images) {
-    searchTasks.push(
-      searchAPI
-        .getSources({
-          query,
-          date,
-          country,
-          safeSearch,
-          type: 'images',
-        })
-        .catch((error) => {
-          logger.error('Error fetching images:', error);
-          return {
-            success: false,
-            error: `Images search failed: ${error instanceof Error ? error.message : String(error)}`,
-          };
-        })
-    );
+    searchTasks.push(runSearch('images'));
   }
   if (videos) {
-    searchTasks.push(
-      searchAPI
-        .getSources({
-          query,
-          date,
-          country,
-          safeSearch,
-          type: 'videos',
-        })
-        .catch((error) => {
-          logger.error('Error fetching videos:', error);
-          return {
-            success: false,
-            error: `Videos search failed: ${error instanceof Error ? error.message : String(error)}`,
-          };
-        })
-    );
+    searchTasks.push(runSearch('videos'));
   }
   if (news) {
-    searchTasks.push(
-      searchAPI
-        .getSources({
-          query,
-          date,
-          country,
-          safeSearch,
-          type: 'news',
-        })
-        .catch((error) => {
-          logger.error('Error fetching news:', error);
-          return {
-            success: false,
-            error: `News search failed: ${error instanceof Error ? error.message : String(error)}`,
-          };
-        })
-    );
+    searchTasks.push(runSearch('news'));
   }
 
-  // Run all searches in parallel
+  // Run all searches in parallel. No task rejects, so every observation is
+  // recorded before the collector is flushed or a failure is raised.
   const results = await Promise.all(searchTasks);
+  if (metrics == null) {
+    collector.flush();
+  }
+
+  if (mainFailure != null) {
+    throw mainFailure.error;
+  }
 
   // Get the main search result (first result)
   const mainResult = results[0];
@@ -239,6 +289,7 @@ export async function executeParallelSearches({
 
 function createSearchProcessor({
   searchAPI,
+  provider,
   safeSearch,
   supportsImages,
   supportsVideos,
@@ -249,6 +300,7 @@ function createSearchProcessor({
   separatorExpandBy,
   logger,
 }: {
+  provider: string;
   safeSearch: t.SearchToolConfig['safeSearch'];
   supportsImages: boolean;
   supportsVideos: boolean;
@@ -281,6 +333,10 @@ function createSearchProcessor({
     videos?: boolean;
     news?: boolean;
   }): Promise<t.SearchResultData> {
+    /** One collector for the whole call: the provider, scrape, and rerank
+     * phases each fold into counters and flush together, so a search costs a
+     * bounded handful of lines instead of a few per source. */
+    const metrics = createSearchMetrics(logger);
     try {
       // Execute parallel searches and merge results
       const searchResult = await executeParallelSearches({
@@ -293,6 +349,8 @@ function createSearchProcessor({
         videos: supportsVideos && videos,
         news: supportsNews && news,
         logger,
+        provider,
+        metrics,
       });
 
       onSearchResults?.(searchResult);
@@ -300,6 +358,7 @@ function createSearchProcessor({
       const processedSources = await sourceProcessor.processSources({
         query,
         news,
+        metrics,
         result: searchResult,
         proMode,
         onGetHighlights,
@@ -322,6 +381,8 @@ function createSearchProcessor({
         relatedSearches: [],
         error: error instanceof Error ? error.message : String(error),
       };
+    } finally {
+      metrics.flush();
     }
   };
 }
@@ -585,7 +646,9 @@ export const createSearchTool = (
     logger,
   });
 
-  if (!selectedReranker) {
+  /** `none` is a deliberate opt-out that `createReranker` already reports;
+   * only an unusable configuration warrants a warning here. */
+  if (!selectedReranker && rerankerType !== 'none') {
     logger.warn('No reranker selected. Using default ranking.');
   }
 
@@ -605,6 +668,7 @@ export const createSearchTool = (
 
   const search = createSearchProcessor({
     searchAPI,
+    provider: searchProvider,
     safeSearch,
     // Keenable is organic-only: its API ignores `type`, so image/news
     // sub-searches would spend rate limit and merge nothing.