🔎 feat: Native Web Search with Citation References (#7516)

* WIP: search tool integration

* WIP: Add web search capabilities and API key management to agent actions

* WIP: web search capability to agent configuration and selection

* WIP: Add web search capability to backend agent configuration

* WIP: add web search option to default agent form values

* WIP: add attachments for web search

* feat: add plugin for processing web search citations

* WIP: first pass, Citation UI

* chore: remove console.log

* feat: Add AnimatedTabs component for tabbed UI functionality

* refactor: AnimatedTabs component with CSS animations and stable ID generation

* WIP example content

* feat: SearchContext for managing search results apart from MessageContext

* feat: Enhance AnimatedTabs with underline animation and state management

* WIP: first pass, Implement dynamic tab functionality in Sources component with search results integration

* fix: Update class names for improved styling in Sources and AnimatedTabs components

* feat: Improve styling and layout in Sources component with enhanced button and item designs

* feat: Refactor Sources component to integrate OGDialog for source display and improve layout

* style: Update background color in SourceItem and SourcesGroup components for improved visibility

* refactor: Sources component to enhance SourceItem structure and improve favicon handling

* style: Adjust font size of domain text in SourceItem for better readability

* feat: Add localization for citation source and details in CompositeCitation component

* style: add theming to Citation components

* feat: Enhance SourceItem component with dialog support and improved hovercard functionality

* feat: Add localization for sources tab and image alt text in Sources component

* style: Replace divs with spans for better semantic structure in CompositeCitation and Citation components

* refactor: Sources component to use useMemo for tab generation and improve performance

* chore: bump @librechat/agents to v2.4.318

* chore: update search result types

* fix: search results retrieval in ContentParts component, re-render attachments when expected

* feat: update sources style/types to use latest search result structure

* style: enhance Dialog (expanded) SourceItem component with link wrapping and improved styling

* style: update ImageItem component styling for improved title visibility

* refactor: remove SourceItemBase component and adjust SourceItem layout for improved styling

* chore: linting twcss order

* fix: prevent FileAttachment from rendering search attachments

* fix: append underscore to responseMessageId for unique identification to prevent mapping of previous latest message's attachments

* chore: remove unused parameter 'useSpecs' from loadTools function

* chore: twcss order

* WIP: WebSearch Tool UI

* refactor: add limit parameter to StackedFavicons for customizable source display

* refactor: optimize search results memoization by making more granular and separate conerns

* refactor: integrated StackedFavicons to WebSearch mid-run

* chore: bump @librechat/agents to expose handleToolCallChunks

* chore: use typedefs from dedicated file instead of defining them in AgentClient module

* WIP: first pass, search progress results

* refactor: move createOnSearchResults function to a dedicated search module

* chore: bump @librechat/agents to v2.4.320

* WIP: first pass, search results processed UX

* refactor: consolidate context variables in createOnSearchResults function

* chore: bump @librechat/agents to v2.4.321

* feat: add guidelines for web search tool response formatting in loadTools function

* feat: add isLast prop to Part component and update WebSearch logic for improved state handling

* style: update Hovercard styles for improved UI consistency

* feat: export FaviconImage component for improved accessibility in other modules

* refactor: export getCleanDomain function and use FaviconImage in Citation component for improved source representation

* refactor: implement SourceHovercard component for consistency and DRY compliance

* fix: replace <p> with <span> for snippet and title in SourceItem and SourceHovercard for consistency

* style: `not-prose`

* style: remove 'not-prose' class for consistency in SourceItem, Citation, and SourceHovercard components, adjust style classes

* refactor: `imageUrl` on hover and prevent duplicate sources

* refactor: enhance SourcesGroup dialog layout and improve source item presentation

* refactor: reorganize Web Components, save in same directory

* feat: add 'news' refType to refTypeMap for citation sources

* style: adjust Hovercard width for improved layout

* refactor: update tool usage guidelines for improved clarity and execution

* chore: linting

* feat: add Web Search badge with initial permissions and local storage logic

* feat: add webSearch support to interface and permissions schemas

* feat: implement Web Search API key management and localization updates

* feat: refactor Web Search API key handling and integrate new search API key form

* fix: remove unnecessary visibility state from FileAttachment component

* feat: update WebSearch component to use Globe icon and localized search label

* feat: enhance ApiKeyDialog with dropdown for reranker selection and update translations

* feat: implement dropdown menus for engine, scraper, and reranker selection in ApiKeyDialog

* chore: linting and add unknown instead of `any` type

* feat: refactor ApiKeyDialog and useAuthSearchTool for improved API key management

* refactor: update ocrSchema to use template literals for default apiKey and baseURL

* feat: add web search configuration and utility functions for environment variable extraction

* fix: ensure filepath is defined before checking its prefix in useAttachmentHandler

* feat: enhance web search functionality with improved configuration and environment variable extraction for authFields

* fix: update auth type in TPluginAction and TUpdateUserPlugins to use Partial<Record<string, string>>

* feat: implement web search authentication verification and enhance webSearchAuth structure

* feat: enhance ephemeral agent handling with new web search capability and type definition

* feat: enhance isEphemeralAgent function to include web search selection

* feat: refactor verifyWebSearchAuth to improve key handling and authentication checks

* feat: implement loadWebSearchAuth function for improved web search authentication handling

* feat: enhance web search authentication with new configuration options and refactor related types

* refactor: rename search engine to search provider and update related localization keys

* feat: update verifyWebSearchAuth to handle multiple authentication types and improve error handling

* feat: update ApiKeyDialog to accept authTypes prop and remove isUserProvided check

* feat: add tests for extractWebSearchEnvVars and loadWebSearchAuth functions

* feat: enhance loadWebSearchAuth to support specific service checks for providers, scrapers, and rerankers

* fix: update web search configuration key and adjust auth result handling in loadTools function

* feat: add new progress key for repeated web searching and update localization

* chore: bump @librechat/agents to 2.4.322

* feat: enhance loadTools function to include ISO time and improve search tool logging

* feat: update StackedFavicons to handle negative start index and improve citation attribution styling and text

* chore: update .gitignore to categorize AI-related files

* fix: mobile responsiveness of sources/citations hovercards

* feat: enhance source display with improved line clamping for better readability

* chore: bump @librechat/agents to v2.4.33

* feat: add handling for image sources in references mapping

* chore: bump librechat-data-provider version to 0.7.84

* chore: bump @librechat/agents version to 2.4.34

* fix: update auth handling to support multiple auth types in tools and allow key configuration in agent panel

* chore: remove redundant agent attribution text from search form

* fix: web search auth uninstall

* refactor: convert CheckboxButton to a forwardRef component and update setValue callback signature

* feat: add triggerRef prop to ApiKeyDialog components for improved dialog control

* feat: integrate triggerRef in CodeInterpreter and WebSearch components for enhanced dialog management

* feat: enhance ApiKeyDialog with additional links for Firecrawl and Jina API key guidance

* feat: implement web search configuration handling in ApiKeyDialog and add tests for dropdown visibility

* fix: update webSearchConfig reference in config route for correct payload assignment

* feat: update ApiKeyDialog to conditionally render sections based on authTypes and modify loadWebSearchAuth to correctly categorize authentication types

* feat: refactor ApiKeyDialog and related tests to use SearchCategories and RerankerTypes enums and remove nested ternaries

* refactor: move ThinkingButton rendering to improve layout consistency in ContentParts

* feat: integrate search context into Markdown component to conditionally include unicodeCitation plugin

* chore: bump @librechat/agents to v2.4.35

* chore: remove unused 18n key

* ci: add WEB_SEARCH permission testing and update AppService tests for new webSearch configuration

* ci: add more comprehensive tests for loadWebSearchAuth to validate authentication handling and authTypes structure

* chore: remove debugging console log from web.spec.ts to clean up test output

client/src/hooks/Chat/useChatFunctions.ts

@@ -245,7 +245,7 @@ export default function useChatFunctions({
     const generation = editedText ?? latestMessage?.text ?? '';
     const responseText = isEditOrContinue ? generation : '';
 
-    const responseMessageId = editedMessageId ?? latestMessage?.messageId ?? null;
+    const responseMessageId = editedMessageId ?? latestMessage?.messageId + '_' ?? null;
     const initialResponse: TMessage = {
       sender: responseSender,
       text: responseText,

client/src/hooks/Messages/useSearchResultsByTurn.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import { TAttachment, Tools, SearchResultData } from 'librechat-data-provider';
+
+/**
+ * Hook that creates a map of turn numbers to SearchResultData from web search attachments
+ * @param attachments Array of attachment metadata
+ * @returns A map of turn numbers to their corresponding search result data
+ */
+export function useSearchResultsByTurn(attachments?: TAttachment[]) {
+  const searchResultsByTurn = useMemo(() => {
+    const turnMap: { [key: string]: SearchResultData } = {};
+
+    attachments?.forEach((attachment) => {
+      if (attachment.type === Tools.web_search && attachment[Tools.web_search]) {
+        const searchData = attachment[Tools.web_search];
+        if (searchData && typeof searchData.turn === 'number') {
+          turnMap[searchData.turn.toString()] = searchData;
+        }
+      }
+    });
+
+    return turnMap;
+  }, [attachments]);
+
+  return searchResultsByTurn;
+}

client/src/hooks/Plugins/index.ts

@@ -1,4 +1,5 @@
 export { default as useAuthCodeTool } from './useAuthCodeTool';
 export { default as usePluginInstall } from './usePluginInstall';
 export { default as useCodeApiKeyForm } from './useCodeApiKeyForm';
+export { default as useSearchApiKeyForm } from './useSearchApiKeyForm';
 export { default as usePluginDialogHelpers } from './usePluginDialogHelpers';

client/src/hooks/Plugins/useAuthSearchTool.ts

@@ -0,0 +1,84 @@
+import { useCallback } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { AuthType, Tools, QueryKeys } from 'librechat-data-provider';
+import { useUpdateUserPluginsMutation } from 'librechat-data-provider/react-query';
+
+export type SearchApiKeyFormData = {
+  serperApiKey: string;
+  firecrawlApiKey: string;
+  firecrawlApiUrl: string;
+  jinaApiKey: string;
+  cohereApiKey: string;
+};
+
+const useAuthSearchTool = (options?: { isEntityTool: boolean }) => {
+  const queryClient = useQueryClient();
+  const isEntityTool = options?.isEntityTool ?? true;
+  const updateUserPlugins = useUpdateUserPluginsMutation({
+    onMutate: (vars) => {
+      queryClient.setQueryData([QueryKeys.toolAuth, Tools.web_search], () => {
+        return {
+          authenticated: vars.action === 'install',
+          authTypes:
+            vars.action === 'install'
+              ? [
+                  ['providers', AuthType.USER_PROVIDED],
+                  ['scrapers', AuthType.USER_PROVIDED],
+                  ['rerankers', AuthType.USER_PROVIDED],
+                ]
+              : [],
+        };
+      });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries([QueryKeys.toolAuth, Tools.web_search]);
+    },
+    onError: () => {
+      queryClient.invalidateQueries([QueryKeys.toolAuth, Tools.web_search]);
+    },
+  });
+
+  const installTool = useCallback(
+    (data: SearchApiKeyFormData) => {
+      const auth = Object.entries({
+        serperApiKey: data.serperApiKey,
+        firecrawlApiKey: data.firecrawlApiKey,
+        firecrawlApiUrl: data.firecrawlApiUrl,
+        jinaApiKey: data.jinaApiKey,
+        cohereApiKey: data.cohereApiKey,
+      }).reduce(
+        (acc, [key, value]) => {
+          if (value) {
+            acc[key] = value;
+          }
+          return acc;
+        },
+        {} as Record<string, string>,
+      );
+
+      updateUserPlugins.mutate({
+        pluginKey: Tools.web_search,
+        action: 'install',
+        auth,
+        isEntityTool,
+      });
+    },
+    [updateUserPlugins, isEntityTool],
+  );
+
+  const removeTool = useCallback(() => {
+    updateUserPlugins.mutate({
+      pluginKey: Tools.web_search,
+      action: 'uninstall',
+      auth: {},
+      isEntityTool,
+    });
+  }, [updateUserPlugins, isEntityTool]);
+
+  return {
+    removeTool,
+    installTool,
+  };
+};
+
+export default useAuthSearchTool;

client/src/hooks/Plugins/useSearchApiKeyForm.ts

@@ -0,0 +1,42 @@
+import { useState, useCallback } from 'react';
+import { useForm } from 'react-hook-form';
+import useAuthSearchTool from '~/hooks/Plugins/useAuthSearchTool';
+import type { SearchApiKeyFormData } from '~/hooks/Plugins/useAuthSearchTool';
+
+export default function useSearchApiKeyForm({
+  onSubmit,
+  onRevoke,
+}: {
+  onSubmit?: () => void;
+  onRevoke?: () => void;
+}) {
+  const methods = useForm<SearchApiKeyFormData>();
+  const [isDialogOpen, setIsDialogOpen] = useState(false);
+  const { installTool, removeTool } = useAuthSearchTool({ isEntityTool: true });
+  const { reset } = methods;
+
+  const onSubmitHandler = useCallback(
+    (data: SearchApiKeyFormData) => {
+      reset();
+      installTool(data);
+      setIsDialogOpen(false);
+      onSubmit?.();
+    },
+    [onSubmit, reset, installTool],
+  );
+
+  const handleRevokeApiKey = useCallback(() => {
+    reset();
+    removeTool();
+    setIsDialogOpen(false);
+    onRevoke?.();
+  }, [reset, onRevoke, removeTool]);
+
+  return {
+    methods,
+    isDialogOpen,
+    setIsDialogOpen,
+    handleRevokeApiKey,
+    onSubmit: onSubmitHandler,
+  };
+}

client/src/hooks/SSE/useAttachmentHandler.ts

@@ -10,7 +10,7 @@ export default function useAttachmentHandler(queryClient?: QueryClient) {
   return ({ data }: { data: TAttachment; submission: EventSubmission }) => {
     const { messageId } = data;
 
-    if (queryClient && !data?.filepath?.startsWith('/api/files')) {
+    if (queryClient && data?.filepath && !data.filepath.startsWith('/api/files')) {
       queryClient.setQueryData([QueryKeys.files], (oldData: TAttachment[] | undefined) => {
         return [data, ...(oldData || [])];
       });