feat(agentStudio): surface thread depth error

Author: pipeline1987

package.json

@@ -47,6 +47,7 @@
     "@rollup/plugin-terser": "0.4.4",
     "@stylistic/eslint-plugin": "2.13.0",
     "@testing-library/dom": "10.4.0",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "8.20.0",

packages/docsearch-css/src/sidepanel.css

@@ -623,6 +623,11 @@ html[data-theme="dark"] .DocSearch-Sidepanel-Prompt--stop:hover {
   flex-direction: column;
 }
 
+.DocSearch-Sidepanel-ConversationScreen-threadDepth {
+  margin: 0 1rem 0.75rem;
+  flex-shrink: 0;
+}
+
 @media screen and (min-width: 769px) {
   .DocSearch-Sidepanel-ConversationScreen {
     padding: 1rem 0;

packages/docsearch-react/src/AskAiScreen.tsx

@@ -9,7 +9,12 @@ import type { StoredSearchPlugin } from './stored-searches';
 import { ToolCall } from './ToolCall';
 import type { InternalDocSearchHit, StoredAskAiState } from './types';
 import type { AIMessage } from './types/AskiAi';
-import { extractLinksFromMessage, getMessageContent, isThreadDepthError } from './utils/ai';
+import {
+  extractLinksFromMessage,
+  filterExchangesForThreadDepthError,
+  getMessageContent,
+  isThreadDepthError,
+} from './utils/ai';
 import { groupConsecutiveToolResults } from './utils/groupConsecutiveToolResults';
 
 export type AskAiScreenTranslations = Partial<{
@@ -392,17 +397,7 @@ 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;
+    return filterExchangesForThreadDepthError(grouped, hasThreadDepthError);
   }, [messages, hasThreadDepthError]);
 
   const handleSearchQueryClick = (query: string): void => {

packages/docsearch-react/src/Sidepanel/ConversationScreen.tsx

@@ -9,7 +9,7 @@ import type { StoredSearchPlugin } from '../stored-searches';
 import { ToolCall, type ToolCallTranslations } from '../ToolCall';
 import type { StoredAskAiState } from '../types';
 import { isAIToolPart, type AIMessage } from '../types/AskiAi';
-import { extractLinksFromMessage, getMessageContent } from '../utils/ai';
+import { extractLinksFromMessage, getMessageContent, isThreadDepthError } from '../utils/ai';
 import { groupConsecutiveToolResults } from '../utils/groupConsecutiveToolResults';
 
 import { AggregatedSearchBlock } from './AggregatedSearchBlock';
@@ -60,7 +60,15 @@ export type ConversationScreenTranslations = Partial<
     /**
      * Error title shown if there is an error while chatting.
      */
-    errorTitleText;
+    errorTitleText: string;
+    /**
+     * Message shown when thread depth limit is exceeded (AI-217).
+     */
+    threadDepthExceededMessage: string;
+    /**
+     * Button label to start a new conversation after a thread depth error.
+     */
+    startNewConversationButtonText: string;
   }
 >;
 
@@ -72,6 +80,8 @@ export type ConversationScreenProps = {
   handleFeedback?: (messageId: string, thumbs: 0 | 1) => Promise<void>;
   streamError?: Error;
   agentStudio?: boolean;
+  showThreadDepthError?: boolean;
+  onThreadDepthNewConversation?: () => void;
 };
 
 type ConversationnExchangeProps = {
@@ -105,6 +115,8 @@ const ConversationExchange = React.forwardRef<HTMLDivElement, ConversationnExcha
       errorTitleText = 'Chat error',
     } = translations;
 
+    const isThreadDepth = isThreadDepthError(streamError);
+
     const assistantContent = useMemo(() => getMessageContent(assistantMessage), [assistantMessage]);
     const userContent = useMemo(() => getMessageContent(userMessage), [userMessage]);
 
@@ -130,7 +142,7 @@ const ConversationExchange = React.forwardRef<HTMLDivElement, ConversationnExcha
           </div>
           <div className="DocSearch-AskAiScreen-Message DocSearch-AskAiScreen-Message--assistant">
             <div className="DocSearch-AskAiScreen-MessageContent">
-              {status === 'error' && streamError && isLastExchange && (
+              {status === 'error' && streamError && isLastExchange && !isThreadDepth && (
                 <div className="DocSearch-AskAiScreen-MessageContent DocSearch-AskAiScreen-Error">
                   <AlertIcon />
                   <div className="DocSearch-AskAiScreen-Error-Content">
@@ -233,9 +245,19 @@ const ConversationExchange = React.forwardRef<HTMLDivElement, ConversationnExcha
 );
 
 export const ConversationScreen = memo(
-  ({ exchanges, translations = {}, handleFeedback, ...props }: ConversationScreenProps): JSX.Element => {
-    const { conversationDisclaimer = 'Answers are generated with AI which can make mistakes. Verify responses.' } =
-      translations;
+  ({
+    exchanges,
+    translations = {},
+    handleFeedback,
+    showThreadDepthError = false,
+    onThreadDepthNewConversation,
+    ...props
+  }: ConversationScreenProps): JSX.Element => {
+    const {
+      conversationDisclaimer = '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 mostRecentExchangeRef = React.useRef<HTMLDivElement>(null);
     const totalExchanges = exchanges.length;
@@ -252,6 +274,23 @@ export const ConversationScreen = memo(
 
     return (
       <div className="DocSearch-Sidepanel-ConversationScreen">
+        {showThreadDepthError && onThreadDepthNewConversation ? (
+          <div className="DocSearch-AskAiScreen-MessageContent DocSearch-AskAiScreen-Error DocSearch-AskAiScreen-Error--ThreadDepth DocSearch-Sidepanel-ConversationScreen-threadDepth">
+            <div className="DocSearch-AskAiScreen-Error-Content">
+              <p>
+                {threadDepthExceededMessage}{' '}
+                <button
+                  type="button"
+                  className="DocSearch-ThreadDepthError-Link"
+                  onClick={onThreadDepthNewConversation}
+                >
+                  {startNewConversationButtonText}
+                </button>{' '}
+                to continue.
+              </p>
+            </div>
+          </div>
+        ) : null}
         <p className="DocSearch-Sidepanel-ConversationScreen-disclaimer">{conversationDisclaimer}</p>
 
         {exchanges.slice().map((exchange, idx) => {

packages/docsearch-react/src/Sidepanel/PromptForm.tsx

@@ -22,8 +22,18 @@ export type PromptFormTranslations = Partial<{
    * Disclaimer text displayed beneath the prompt form.
    **/
   promptDisclaimerText: string;
+  /**
+   * Visually hidden label text (`aria-labelledby`); usually keyboard hints for the textarea.
+   **/
   promptLabelText: string;
+  /**
+   * Accessible name for the textarea (`aria-label`).
+   **/
   promptAriaLabelText: string;
+  /**
+   * Placeholder when the conversation hit the thread depth limit (AI-217).
+   **/
+  threadDepthErrorPlaceholder: string;
 }>;
 
 type Props = {
@@ -32,12 +42,17 @@ type Props = {
   translations?: PromptFormTranslations;
   onSend: (prompt: string) => void;
   onStopStreaming: () => void;
+  /** When true, the prompt is disabled (same as modal SearchBox in Ask AI mode). */
+  isThreadDepthError?: boolean;
 };
 
 const MAX_PROMPT_ROWS = 8;
 
 export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
-  ({ exchanges, isStreaming, translations = {}, onSend, onStopStreaming }, ref): JSX.Element => {
+  (
+    { exchanges, isStreaming, translations = {}, onSend, onStopStreaming, isThreadDepthError = false },
+    ref,
+  ): JSX.Element => {
     const isMobile = useIsMobile();
     const [userPrompt, setUserPrompt] = React.useState('');
     const promptRef = React.useRef<HTMLTextAreaElement>(null);
@@ -51,6 +66,7 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
       promptDisclaimerText = 'Answers are generated with AI which can make mistakes.',
       promptLabelText = 'Press Enter to send, or Shift and Enter for new line.',
       promptAriaLabelText = 'Prompt input',
+      threadDepthErrorPlaceholder = 'Conversation limit reached',
     } = translations;
 
     const managePromptHeight = (): void => {
@@ -74,7 +90,7 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
     };
 
     const handleSend = (): void => {
-      if (isStreaming) return;
+      if (isStreaming || isThreadDepthError) return;
 
       const prompt = userPrompt.trim();
 
@@ -93,7 +109,7 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
 
     const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>): void => {
       // Allow Enter to work normally (new line) when streaming
-      if (isStreaming) return;
+      if (isStreaming || isThreadDepthError) return;
 
       if (e.key === 'Enter' && !e.shiftKey) {
         e.preventDefault();
@@ -108,7 +124,9 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
 
     let promptPlaceholder = promptPlaceholderText;
 
-    if (isStreaming) {
+    if (isThreadDepthError) {
+      promptPlaceholder = threadDepthErrorPlaceholder;
+    } else if (isStreaming) {
       promptPlaceholder = promptAnsweringText;
     } else if (exchanges.length > 0) {
       promptPlaceholder = promptAskAnotherQuestionText;
@@ -121,7 +139,7 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
           onSubmit={(e) => {
             e.preventDefault();
 
-            if (isStreaming) return;
+            if (isStreaming || isThreadDepthError) return;
 
             handleSend();
           }}
@@ -136,6 +154,7 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
             autoComplete="off"
             translate="no"
             rows={isMobile ? 1 : 2}
+            disabled={isThreadDepthError}
             onKeyDown={handleKeyDown}
             onInput={managePromptHeight}
             onChange={(e) => setUserPrompt(e.target.value)}
@@ -154,7 +173,7 @@ export const PromptForm = React.forwardRef<HTMLTextAreaElement, Props>(
                 <StopIcon />
               </button>
             )}
-            {!isStreaming && (
+            {!isStreaming && !isThreadDepthError && (
               <button
                 type="submit"
                 aria-label="Send question"

packages/docsearch-react/src/Sidepanel/Sidepanel.tsx

@@ -9,7 +9,7 @@ import { useAskAi } from '../useAskAi';
 import { useIsMobile } from '../useIsMobile';
 import { useSearchClient } from '../useSearchClient';
 import { useSuggestedQuestions } from '../useSuggestedQuestions';
-import { buildDummyAskAiHit } from '../utils/ai';
+import { buildDummyAskAiHit, filterExchangesForThreadDepthError, isThreadDepthError } from '../utils/ai';
 
 import { ConversationHistoryScreen } from './ConversationHistoryScreen';
 import type { ConversationScreenTranslations } from './ConversationScreen';
@@ -203,6 +203,19 @@ function SidepanelInner(
     searchClient,
   });
 
+  const hasThreadDepthError = React.useMemo(
+    () => status === 'error' && isThreadDepthError(askAiError),
+    [status, askAiError],
+  );
+
+  const displayExchanges = React.useMemo(
+    () => filterExchangesForThreadDepthError(exchanges, hasThreadDepthError),
+    [exchanges, hasThreadDepthError],
+  );
+
+  const showThreadDepthBanner =
+    sidepanelState === 'conversation' && hasThreadDepthError && messages.some((m) => m.role === 'assistant');
+
   const prevStatus = React.useRef(status);
 
   const handleSend = (prompt: string): void => {
@@ -373,7 +386,7 @@ function SidepanelInner(
       <aside id="docsearch-sidepanel" className={`DocSearch-Sidepanel ${sidepanelState}`}>
         <SidepanelHeader
           sidepanelState={sidepanelState}
-          exchanges={exchanges}
+          exchanges={displayExchanges}
           setSidepanelState={setSidepanelState}
           hasConversations={conversations.getAll().length > 0}
           isStreaming={isStreaming}
@@ -391,13 +404,15 @@ function SidepanelInner(
           )}
           {sidepanelState === 'conversation' && (
             <ConversationScreen
-              exchanges={exchanges}
+              exchanges={displayExchanges}
               status={status}
               conversations={conversations}
               handleFeedback={sendFeedback}
               translations={translations.conversationScreen}
               streamError={askAiError}
               agentStudio={agentStudio}
+              showThreadDepthError={showThreadDepthBanner}
+              onThreadDepthNewConversation={handleStartNewConversation}
             />
           )}
           {sidepanelState === 'conversation-history' && (
@@ -406,9 +421,10 @@ function SidepanelInner(
         </div>
         <PromptForm
           ref={promptInputRef}
-          exchanges={exchanges}
+          exchanges={displayExchanges}
           isStreaming={isStreaming}
           translations={translations.promptForm}
+          isThreadDepthError={showThreadDepthBanner}
           onSend={handleSend}
           onStopStreaming={handleStopStreaming}
         />

packages/docsearch-react/src/__tests__/askai.test.tsx

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react';
+import { render, within } from '@testing-library/react';
 import type { UIMessage } from 'ai';
 import React from 'react';
 import { describe, it, expect } from 'vitest';
@@ -42,4 +42,44 @@ describe('AskAiScreen', () => {
 
     expect(getByText('oh no')).toBeInTheDocument();
   });
+
+  it('surfaces thread depth (AI-217) with a banner and hides the generic chat error', () => {
+    const messages: UIMessage[] = [
+      {
+        id: '1',
+        role: 'user',
+        parts: [{ type: 'text', text: 'first' }],
+      },
+      {
+        id: '2',
+        role: 'assistant',
+        parts: [{ type: 'text', text: 'answer' }],
+      },
+      {
+        id: '3',
+        role: 'user',
+        parts: [{ type: 'text', text: 'follow-up' }],
+      },
+    ];
+
+    const onNewConversation = (): void => {};
+
+    const { container, getByText } = render(
+      <AskAiScreen
+        {...baseProps}
+        messages={messages}
+        status="error"
+        askAiError={new Error('AI-217 - Thread depth exceeded')}
+        onNewConversation={onNewConversation}
+      />,
+    );
+
+    expect(
+      getByText('This conversation is now closed to keep responses accurate.', { exact: false }),
+    ).toBeInTheDocument();
+    expect(getByText('Start a new conversation')).toBeInTheDocument();
+    // Bound queries from `render()` use `baseElement` (often `document.body`), so a prior test can still
+    // match. Restrict to this instance's root so we only assert on this tree.
+    expect(within(container).queryByText('Chat error')).not.toBeInTheDocument();
+  });
 });

packages/docsearch-react/src/index.ts

@@ -1,3 +1,5 @@
+export { filterExchangesForThreadDepthError, isThreadDepthError } from './utils/ai';
+
 export * from './DocSearch';
 export * from './DocSearchButton';
 export * from './DocSearchModal';