feat(askai): add thread depth limit logic (#2812)

Author: vascobettencourt

bundlesize.config.json

@@ -18,7 +18,7 @@
     },
     {
       "path": "packages/docsearch-modal/dist/umd/index.js",
-      "maxSize": "113 kB"
+      "maxSize": "113.5 kB"
     }
   ]
 }

packages/docsearch-css/src/modal.css

@@ -919,6 +919,46 @@ assistive tech users */
   color: var(--docsearch-error-color);
 }
 
+/* Thread Depth Error - positioned below input */
+.DocSearch-AskAiScreen-Error--ThreadDepth {
+  margin: 12px 0 8px 0;
+  color: var(--docsearch-text-color);
+  font-size: 12px;
+  border: 1px solid #febdc5;
+  animation: slideDown 0.3s ease-out;
+  width: 100%;
+}
+
+@keyframes slideDown {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.DocSearch-ThreadDepthError-Link {
+  color: var(--docsearch-highlight-color);
+  text-decoration: underline;
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+  font-size: inherit;
+  font-family: inherit;
+}
+
+.DocSearch-ThreadDepthError-Link:hover {
+  opacity: 0.8;
+}
+
+.DocSearch-ThreadDepthError-Link:active {
+  color: rgb(153 27 27);
+}
+
 .DocSearch-AskAiScreen-FeedbackText {
   font-size: 0.7em;
   font-weight: 400;
@@ -1457,7 +1497,9 @@ assistive tech users */
   flex-direction: column;
   border-radius: var(--docsearch-border-radius);
   background-color: var(--docsearch-dropdown-menu-background);
-  box-shadow: 0px 0px 0px 1px #21243D0D, 0px 8px 16px -4px #21243D40;
+  box-shadow:
+    0px 0px 0px 1px #21243d0d,
+    0px 8px 16px -4px #21243d40;
   min-width: 195px;
   inset-block-start: calc(100% + 12px);
   z-index: 422;

packages/docsearch-react/src/AskAiScreen.tsx

@@ -8,7 +8,7 @@ import type { ScreenStateProps } from './ScreenState';
 import type { StoredSearchPlugin } from './stored-searches';
 import type { InternalDocSearchHit, StoredAskAiState } from './types';
 import type { AIMessage } from './types/AskiAi';
-import { extractLinksFromMessage, getMessageContent } from './utils/ai';
+import { extractLinksFromMessage, getMessageContent, isThreadDepthError } from './utils/ai';
 import { groupConsecutiveToolResults } from './utils/groupConsecutiveToolResults';
 
 export type AskAiScreenTranslations = Partial<{
@@ -52,13 +52,22 @@ export type AskAiScreenTranslations = Partial<{
    * Error title shown if there is an error while chatting.
    */
   errorTitleText: string;
+  /**
+   * Message shown when thread depth limit is exceeded (AI-217 error).
+   */
+  threadDepthExceededMessage: string;
+  /**
+   * Button text for starting a new conversation after thread depth error.
+   */
+  startNewConversationButtonText: string;
 }>;
 
 type AskAiScreenProps = Omit<ScreenStateProps<InternalDocSearchHit>, 'translations'> & {
   messages: AIMessage[];
   status: UseChatHelpers<AIMessage>['status'];
   askAiError?: Error;
   translations?: AskAiScreenTranslations;
+  onNewConversation: () => void;
 };
 
 interface AskAiScreenHeaderProps {
@@ -100,6 +109,8 @@ function AskAiExchangeCard({
 
   const { stoppedStreamingText = 'You stopped this response', errorTitleText = 'Chat error' } = translations;
 
+  const isThreadDepth = isThreadDepthError(askAiError);
+
   const assistantContent = useMemo(() => getMessageContent(assistantMessage), [assistantMessage]);
   const userContent = useMemo(() => getMessageContent(userMessage), [userMessage]);
 
@@ -127,7 +138,7 @@ function AskAiExchangeCard({
         </div>
         <div className="DocSearch-AskAiScreen-Message DocSearch-AskAiScreen-Message--assistant">
           <div className="DocSearch-AskAiScreen-MessageContent">
-            {loadingStatus === 'error' && askAiError && isLastExchange && (
+            {loadingStatus === 'error' && askAiError && isLastExchange && !isThreadDepth && (
               <div className="DocSearch-AskAiScreen-MessageContent DocSearch-AskAiScreen-Error">
                 <AlertIcon />
                 <div className="DocSearch-AskAiScreen-Error-Content">
@@ -375,9 +386,18 @@ function AskAiSourcesPanel({ urlsToDisplay, relatedSourcesText }: AskAiSourcesPa
 }
 
 export function AskAiScreen({ translations = {}, ...props }: AskAiScreenProps): JSX.Element | null {
-  const { disclaimerText = 'Answers are generated with AI which can make mistakes. Verify responses.' } = translations;
+  const {
+    disclaimerText = 'Answers are generated with AI which can make mistakes. Verify responses.',
+    threadDepthExceededMessage = 'This conversation is now closed to keep responses accurate.',
+    startNewConversationButtonText = 'Start a new conversation',
+  } = translations;
 
-  const { messages } = props;
+  const { messages, askAiError, status } = props;
+
+  // Check if there's a thread depth error
+  const hasThreadDepthError = useMemo(() => {
+    return status === 'error' && isThreadDepthError(askAiError);
+  }, [status, askAiError]);
 
   // Group messages into exchanges (user + assistant pairs)
   const exchanges: Exchange[] = useMemo(() => {
@@ -392,17 +412,47 @@ export function AskAiScreen({ translations = {}, ...props }: AskAiScreenProps):
         }
       }
     }
+
+    // If there's a thread depth error, remove the last exchange (the one that triggered the error)
+    // We only want to show successful exchanges
+    if (hasThreadDepthError && grouped.length > 0) {
+      // Check if the last exchange has no assistant message (failed to complete)
+      const lastExchange = grouped[grouped.length - 1];
+      if (!lastExchange.assistantMessage) {
+        grouped.pop();
+      }
+    }
+
     return grouped;
-  }, [messages]);
+  }, [messages, hasThreadDepthError]);
 
   const handleSearchQueryClick = (query: string): void => {
     props.onAskAiToggle(false);
     props.setQuery(query);
   };
 
+  // Only show the thread depth error if we have assistant messages
+  const showThreadDepthError = hasThreadDepthError && messages.some((m) => m.role === 'assistant');
+
   return (
     <div className="DocSearch-AskAiScreen DocSearch-AskAiScreen-Container">
+      {/* Thread Depth Error */}
+      {showThreadDepthError && (
+        <div className="DocSearch-AskAiScreen-MessageContent DocSearch-AskAiScreen-Error DocSearch-AskAiScreen-Error--ThreadDepth">
+          <div className="DocSearch-AskAiScreen-Error-Content">
+            <p>
+              {threadDepthExceededMessage}{' '}
+              <button type="button" className="DocSearch-ThreadDepthError-Link" onClick={props.onNewConversation}>
+                {startNewConversationButtonText}
+              </button>{' '}
+              to continue.
+            </p>
+          </div>
+        </div>
+      )}
+
       <AskAiScreenHeader disclaimerText={disclaimerText} />
+
       <div className="DocSearch-AskAiScreen-Body">
         <div className="DocSearch-AskAiScreen-ExchangesList">
           {exchanges

packages/docsearch-react/src/DocSearchModal.tsx

@@ -37,7 +37,7 @@ import { useSuggestedQuestions } from './useSuggestedQuestions';
 import { useTouchEvents } from './useTouchEvents';
 import { useTrapFocus } from './useTrapFocus';
 import { groupBy, identity, noop, removeHighlightTags, isModifierEvent, scrollTo as scrollToUtils } from './utils';
-import { buildDummyAskAiHit } from './utils/ai';
+import { buildDummyAskAiHit, isThreadDepthError } from './utils/ai';
 import { manageLocalStorageQuota } from './utils/storage';
 
 export type ModalTranslations = Partial<{
@@ -459,6 +459,11 @@ export function DocSearchModal({
     prevStatus.current = status;
   }, [status, messages, conversations, disableUserPersonalization, stoppedStream]);
 
+  // Check if there's a thread depth error (AI-217)
+  const hasThreadDepthError = React.useMemo(() => {
+    return status === 'error' && isThreadDepthError(askAiError as Error | undefined);
+  }, [status, askAiError]);
+
   const createSyntheticParent = React.useCallback(function createSyntheticParent(
     item: InternalDocSearchHit,
   ): InternalDocSearchHit {
@@ -527,8 +532,6 @@ export function DocSearchModal({
   const handleSelectAskAiQuestion = React.useCallback(
     (toggle: boolean, query: string, suggestedQuestion: SuggestedQuestionHit | undefined = undefined) => {
       if (toggle && askAiState === 'new-conversation') {
-        // We're starting a new conversation, clear out current messages
-        setMessages([]);
         setAskAiState('initial');
       }
 
@@ -571,7 +574,7 @@ export function DocSearchModal({
         autocompleteRef.current.setQuery('');
       }
     },
-    [onAskAiToggle, sendMessage, askAiState, setAskAiState, setMessages],
+    [onAskAiToggle, sendMessage, askAiState, setAskAiState],
   );
 
   // feedback handler
@@ -821,6 +824,7 @@ export function DocSearchModal({
   };
 
   const handleNewConversation = (): void => {
+    setMessages([]);
     setAskAiState('new-conversation');
   };
 
@@ -871,8 +875,10 @@ export function DocSearchModal({
             translations={searchBoxTranslations}
             isAskAiActive={isAskAiActive}
             askAiStatus={status}
+            askAiError={askAiError}
             askAiState={askAiState}
             setAskAiState={setAskAiState}
+            isThreadDepthError={hasThreadDepthError && askAiState !== 'new-conversation'}
             onClose={onClose}
             onAskAiToggle={onAskAiToggle}
             onAskAgain={(query) => {
@@ -910,6 +916,7 @@ export function DocSearchModal({
               suggestedQuestions={suggestedQuestions}
               selectSuggestedQuestion={selectSuggestedQuestion}
               onAskAiToggle={onAskAiToggle}
+              onNewConversation={handleNewConversation}
               onItemClick={(item, event) => {
                 // if the item is askAI toggle the screen
                 if (item.type === 'askAI' && item.query) {

packages/docsearch-react/src/ScreenState.tsx

@@ -55,6 +55,7 @@ export interface ScreenStateProps<TItem extends BaseItem>
   selectAskAiQuestion: (toggle: boolean, query: string) => void;
   suggestedQuestions: SuggestedQuestionHit[];
   selectSuggestedQuestion: (question: SuggestedQuestionHit) => void;
+  onNewConversation: () => void;
 }
 
 export const ScreenState = React.memo(

packages/docsearch-react/src/SearchBox.tsx

@@ -35,6 +35,7 @@ export type SearchBoxTranslations = Partial<{
   conversationHistoryTitle: string;
   startNewConversationText: string;
   viewConversationHistoryText: string;
+  threadDepthErrorPlaceholder: string;
 }>;
 
 interface SearchBoxProps
@@ -49,12 +50,14 @@ interface SearchBoxProps
   placeholder: string;
   isAskAiActive: boolean;
   askAiStatus: UseChatHelpers<AIMessage>['status'];
+  askAiError?: Error;
   isFromSelection: boolean;
   translations?: SearchBoxTranslations;
   askAiState: AskAiState;
   setAskAiState: (state: AskAiState) => void;
   onNewConversation: () => void;
   onViewConversationHistory: () => void;
+  isThreadDepthError?: boolean;
 }
 
 export function SearchBox({
@@ -77,6 +80,7 @@ export function SearchBox({
     conversationHistoryTitle = 'My conversation history',
     startNewConversationText = 'Start a new conversation',
     viewConversationHistoryText = 'Conversation history',
+    threadDepthErrorPlaceholder = 'Conversation limit reached',
   } = translations;
   const { onReset } = props.getFormProps({
     inputElement: props.inputRef.current,
@@ -116,12 +120,20 @@ export function SearchBox({
   const isAskAiStreaming = props.askAiStatus === 'streaming' || props.askAiStatus === 'submitted';
   const isKeywordSearchLoading = props.state.status === 'stalled';
   const renderMoreOptions = props.isAskAiActive && askAiState !== 'conversation-history';
+
+  // Use the thread depth error state passed from parent
+  const isThreadDepthError = props.isThreadDepthError || false;
   let searchPlaceholder = props.placeholder;
 
   if (askAiState === 'new-conversation') {
     searchPlaceholder = newConversationPlaceholder;
   }
 
+  // Override placeholder when thread depth error occurs (only in Ask AI mode)
+  if (isThreadDepthError && props.isAskAiActive) {
+    searchPlaceholder = threadDepthErrorPlaceholder;
+  }
+
   let heading: string | null = null;
 
   if (isAskAiStreaming) {
@@ -174,18 +186,24 @@ export function SearchBox({
       }
       origOnChange?.(e);
     },
-    disabled: isAskAiStreaming,
+    disabled: isAskAiStreaming || (isThreadDepthError && props.isAskAiActive),
   };
 
   const handleAskAiBackClick = React.useCallback((): void => {
+    // If there's a thread depth error, start a new conversation instead of exiting
+    if (isThreadDepthError) {
+      props.onNewConversation();
+      return;
+    }
+
     if (askAiState === 'conversation-history') {
       onAskAiToggle(true);
       setAskAiState('initial');
       return;
     }
 
     onAskAiToggle(false);
-  }, [askAiState, onAskAiToggle, setAskAiState]);
+  }, [askAiState, isThreadDepthError, onAskAiToggle, setAskAiState, props]);
 
   return (
     <>

packages/docsearch-react/src/utils/ai.ts

@@ -95,3 +95,12 @@ export const buildDummyAskAiHit = (query: string, messages: AIMessage[]): Stored
 
 export const getMessageContent = (message: AIMessage | null): TextUIPart | undefined =>
   message?.parts.find((part) => part.type === 'text');
+
+/**
+ * Helper function to check if error is a thread depth error (AI-217).
+ */
+export function isThreadDepthError(error?: Error): boolean {
+  if (!error) return false;
+
+  return error.message?.includes('AI-217') || false;
+}

packages/website/docs/v4/askai-errors.mdx

@@ -110,6 +110,12 @@ This error occurs when the SDK could not load the provider’s API key successfu
 
 > **Solution**: Ensure the API key for the chosen LLM provider is correct and has all of the correct permissions added to it.
 
+### AI-217 - Thread Depth Exceeded {#ai-217}
+
+The conversation has reached its maximum depth limit and can no longer accept follow-up questions.
+
+> **Solution**: Start a new conversation to continue. The conversation depth limit is configured per assistant to maintain response accuracy and prevent conversation drift.
+
 [1]: /docs/api#askai
 [2]: https://sitesearch.algolia.com/docs/experiences/search-askai#configuration
 [3]: https://www.algolia.com/doc/guides/algolia-ai/askai/reference/api