Fix Bugs from QA Docs Feedback #218
Conversation
WalkthroughA new function for rephrasing vague documentation search queries was introduced and integrated into the document QA agent's flow, enhancing how queries are processed before retrieval. Additional changes improved URL normalization for documentation links, adjusted fetch timeouts, refactored webhook payload handling in a script, refined dialog focus management in the UI, customized markdown rendering with specialized code block handling and copy buttons, and reorganized the search input component’s send logic and styling. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant UI
participant DocQAAgent
participant LLM
participant DocRetriever
User->>UI: Submit query
UI->>DocQAAgent: answerQuestion(ctx, prompt)
DocQAAgent->>LLM: rephraseVaguePrompt(ctx, prompt)
LLM-->>DocQAAgent: rephrasedPrompt
DocQAAgent->>DocRetriever: retrieveDocs(rephrasedPrompt)
DocRetriever-->>DocQAAgent: relevantDocs
DocQAAgent->>LLM: generateAnswer(originalPrompt, rephrasedPrompt, relevantDocs)
LLM-->>DocQAAgent: answer
DocQAAgent-->>UI: answer
UI-->>User: Display answer
Suggested reviewers
Poem
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
npm error Exit handler never called! 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms (1)
✨ Finishing Touches
🧪 Generate Unit Tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 049f12c | Commit Preview URL | Jul 02 2025, 02:54 AM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (1)
components/CustomSearchDialog/index.tsx (1)
26-30: Remove redundant focus mechanism.You now have two ways to focus the input when the dialog opens: the
useEffectwithsetTimeoutand theonOpenAutoFocushandler. TheonOpenAutoFocusapproach is more reliable and direct, so theuseEffectis no longer needed.- // Focus input when dialog opens - useEffect(() => { - if (open) { - setTimeout(() => inputRef.current?.focus(), 100); - } - }, [open]);Also applies to: 39-42
🧹 Nitpick comments (3)
components/CustomSearchDialog/hooks/useMessages.tsx (1)
145-145: Remove unnecessary blank line.The blank line at the start of the
handleSourceClickcallback appears to be accidental formatting.const handleSourceClick = useCallback((url: string) => { - if (url && url !== '#' && (url.startsWith('/') || url.startsWith('http'))) {app/api/search/route.ts (1)
9-33: Solid improvement to URL normalization.The enhanced
documentPathToUrlfunction correctly handles:
- Hash fragment preservation
- Trailing "index" segment removal
- Empty segment filtering
- Root path edge cases
The implementation is well-structured and follows TypeScript best practices.
Consider adding a few test cases to ensure edge cases are covered:
- Paths with multiple consecutive slashes
- Paths with only "index" segments
- Complex hash fragments with special characters
// Example test cases to consider: // "/docs/index.mdx" → "/" // "/docs//guide/index.md#getting-started" → "/docs/guide#getting-started" // "/index/index.md" → "/"agent-docs/src/agents/doc-qa/prompt.ts (1)
9-68: Excellent implementation of conservative prompt rephrasing.The function demonstrates strong adherence to coding guidelines:
- Uses TypeScript with proper type annotations
- Imports from
@agentuity/sdkas required- Implements structured error handling with try-catch
- Leverages the provided logger for consistent logging
- Uses conservative approach to avoid over-modification
The system prompt is well-crafted with specific examples and clear guidelines.
Remove the console.log on line 56 as it's redundant with the structured logging below:
- console.log(rephrasedQuery); // Log if we actually rephrased it if (rephrasedQuery !== input) { ctx.logger.info('Rephrased query from "%s" to "%s"', input, rephrasedQuery); }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
.github/workflows/sync-docs-full.yml(1 hunks)agent-docs/src/agents/doc-qa/prompt.ts(1 hunks)agent-docs/src/agents/doc-qa/rag.ts(4 hunks)app/api/search/route.ts(1 hunks)bin/send-webhook.sh(1 hunks)components/CustomSearchDialog/hooks/useMessages.tsx(2 hunks)components/CustomSearchDialog/index.tsx(4 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
`agent-docs/src/agents/**/*.ts`: Use TypeScript for better type safety and IDE s...
agent-docs/src/agents/**/*.ts: Use TypeScript for better type safety and IDE support
Import types from@agentuity/sdk
Use structured error handling with try/catch blocks
Leverage the provided logger for consistent logging
Use the storage APIs for persisting data
📄 Source: CodeRabbit Inference Engine (agent-docs/.cursor/rules/sdk.mdc)
List of files the instruction was applied to:
agent-docs/src/agents/doc-qa/prompt.tsagent-docs/src/agents/doc-qa/rag.ts
🧠 Learnings (5)
📓 Common learnings
Learnt from: afterrburn
PR: agentuity/docs#208
File: agent-docs/src/agents/doc-qa/index.ts:27-28
Timestamp: 2025-06-28T18:06:02.340Z
Learning: The answerQuestion function in agent-docs/src/agents/doc-qa/rag.ts handles errors internally by logging them and returning a fallback JSON answer, so it doesn't require external try-catch blocks at the call site.
components/CustomSearchDialog/index.tsx (1)
Learnt from: CR
PR: agentuity/docs#0
File: .cursor/rules/mdx.mdc:0-0
Timestamp: 2025-07-01T12:36:29.712Z
Learning: This is MDX so some react components can be used
app/api/search/route.ts (1)
Learnt from: CR
PR: agentuity/docs#0
File: .cursor/rules/mdx.mdc:0-0
Timestamp: 2025-07-01T12:36:29.712Z
Learning: Applies to *.mdx : Always create front matter with a title and description
agent-docs/src/agents/doc-qa/prompt.ts (2)
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-01T12:36:46.237Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Import types from `@agentuity/sdk`
agent-docs/src/agents/doc-qa/rag.ts (6)
Learnt from: afterrburn
PR: agentuity/docs#208
File: agent-docs/src/agents/doc-qa/index.ts:27-28
Timestamp: 2025-06-28T18:06:02.340Z
Learning: The answerQuestion function in agent-docs/src/agents/doc-qa/rag.ts handles errors internally by logging them and returning a fallback JSON answer, so it doesn't require external try-catch blocks at the call site.
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : Prefer naming the default function Agent or the name of the Agent based on the context of the Agent description
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Applies to agent-docs/**/src/agents/**/index.ts : All code should be in Typescript format
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/sdk.mdc:0-0
Timestamp: 2025-07-01T12:36:46.237Z
Learning: Applies to agent-docs/src/agents/**/*.ts : Use TypeScript for better type safety and IDE support
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agent.mdc:0-0
Timestamp: 2025-07-01T12:36:36.319Z
Learning: Prefer using the `agentuity agent create` command to create a new Agent
Learnt from: CR
PR: agentuity/docs#0
File: agent-docs/.cursor/rules/agentuity.mdc:0-0
Timestamp: 2025-07-01T12:36:39.469Z
Learning: Applies to agent-docs/**/agentuity.yaml : Do not suggest edits to the Agentuity AI Configuration file (agentuity.yaml)
🧬 Code Graph Analysis (1)
components/CustomSearchDialog/index.tsx (1)
components/CustomSearchDialog/MessageList.tsx (1)
MessageList(10-35)
🪛 Shellcheck (0.10.0)
bin/send-webhook.sh
[warning] 26-26: Use single quotes, otherwise this expands now rather than when signalled.
(SC2064)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (8)
components/CustomSearchDialog/hooks/useMessages.tsx (1)
68-68: Timeout extension looks reasonable for AI-powered search operations.Increasing the timeout from 30 to 90 seconds provides more time for complex AI processing while still preventing indefinite hangs.
components/CustomSearchDialog/index.tsx (2)
39-42: Excellent improvement to focus management.The
onOpenAutoFocushandler provides more reliable focus behavior by preventing the default autofocus and immediately focusing the input element. ThepreventScroll: trueoption is a nice touch to avoid unwanted scrolling.
16-16: Minor formatting adjustments.The blank line additions appear to be formatting preferences with no functional impact.
Also applies to: 67-68, 85-85
bin/send-webhook.sh (1)
28-48: Excellent improvement to payload handling.The shift from in-memory string handling to temporary file-based operations is a solid improvement that:
- Handles large payloads more efficiently
- Reduces memory usage
- Provides better security isolation
- Maintains all existing functionality
The implementation correctly handles cleanup with the trap mechanism and preserves all validation logic.
.github/workflows/sync-docs-full.yml (1)
4-4: Verify the resource impact of automatic PR triggers.The change from manual to automatic triggering will cause this workflow to run on every pull request, which could significantly increase CI/CD resource usage and costs.
Please confirm this is the intended behavior and that the infrastructure can handle the increased load. Consider whether you need filters (e.g., only on documentation file changes) to optimize resource usage:
on: pull_request: paths: - 'docs/**' - '**/*.md' - '**/*.mdx'agent-docs/src/agents/doc-qa/rag.ts (3)
11-15: Well-integrated rephrasing step.The integration of
rephraseVaguePromptbefore document retrieval is strategically placed and will improve search accuracy while maintaining focus on the original user intent.
20-93: Excellent system prompt enhancement.The updated system prompt effectively:
- Clearly explains the context with both original and rephrased queries
- Maintains focus on answering the original question
- Provides comprehensive formatting guidelines
- Uses structured tags for better prompt organization
The approach leverages improved document retrieval while preserving user intent.
103-103: Clear instruction alignment.The prompt instruction correctly emphasizes answering the original question using documents found via the rephrased search, maintaining the intended workflow.
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
components/CustomSearchDialog/MessageList.tsx (3)
10-33: Enhance error handling and accessibility.The CopyButton component is well-implemented but could benefit from improvements:
- Fallback for unsupported browsers: Check if the clipboard API is available
- User-friendly error feedback: Consider showing a toast or temporary message instead of just console logging
- Better accessibility: Add more descriptive ARIA labels
function CopyButton({ text }: { text: string }) { const [copied, setCopied] = useState(false); + const [error, setError] = useState(false); const handleCopy = async () => { + if (!navigator.clipboard) { + console.warn('Clipboard API not supported'); + return; + } + try { await navigator.clipboard.writeText(text); setCopied(true); + setError(false); setTimeout(() => setCopied(false), 2000); } catch (err) { console.error('Failed to copy text:', err); + setError(true); + setTimeout(() => setError(false), 2000); } }; return ( <button onClick={handleCopy} className="absolute top-2 right-2 p-1.5 rounded bg-gray-700 hover:bg-gray-600 text-white opacity-70 hover:opacity-100 transition-opacity" - title="Copy code" + title={copied ? "Copied!" : error ? "Copy failed" : "Copy code"} + aria-label={copied ? "Code copied to clipboard" : "Copy code to clipboard"} > {copied ? <Check className="w-3 h-3" /> : <Copy className="w-3 h-3" />} </button> ); }
120-133: Consider simplifying the text extraction logic.The
extractTextContentfunction handles many cases but could be simplified and made more robust:- const extractTextContent = (element: any): string => { - if (typeof element === 'string') return element; - if (typeof element === 'number') return String(element); - if (element?.props?.children) { - if (typeof element.props.children === 'string') { - return element.props.children; - } - if (Array.isArray(element.props.children)) { - return element.props.children.map(extractTextContent).join(''); - } - return extractTextContent(element.props.children); - } - return ''; - }; + const extractTextContent = (element: any): string => { + if (typeof element === 'string' || typeof element === 'number') { + return String(element); + } + + if (React.isValidElement(element)) { + const children = element.props?.children; + if (!children) return ''; + + if (Array.isArray(children)) { + return children.map(extractTextContent).join(''); + } + + return extractTextContent(children); + } + + return ''; + };
118-153: Improve text extraction performance and add fallback for clipboard API.The recursive
extractTextContentfunction works correctly but could be optimized. Also, the clipboard API may not be available in all contexts.Consider memoizing the text extraction and adding a fallback:
+import { useMemo } from 'react'; // In the component: + const codeText = useMemo(() => { + const extractText = (element: any): string => { + if (typeof element === 'string') return element; + if (typeof element === 'number') return String(element); + if (element?.props?.children) { + const children = element.props.children; + if (typeof children === 'string') return children; + if (Array.isArray(children)) { + return children.map(extractText).join(''); + } + return extractText(children); + } + return ''; + }; + + return Array.isArray(children) + ? children.map(extractText).join('') + : extractText(children); + }, [children]);For the CopyButton component, add clipboard API availability check:
const handleCopy = async () => { try { + if (!navigator.clipboard) { + // Fallback for older browsers + const textArea = document.createElement('textarea'); + textArea.value = text; + document.body.appendChild(textArea); + textArea.select(); + document.execCommand('copy'); + document.body.removeChild(textArea); + } else { await navigator.clipboard.writeText(text); + } setCopied(true); setTimeout(() => setCopied(false), 2000); } catch (err) { console.error('Failed to copy text:', err); } };
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
components/CustomSearchDialog/MessageList.tsx(2 hunks)components/CustomSearchDialog/SearchInput.tsx(2 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: afterrburn
PR: agentuity/docs#208
File: agent-docs/src/agents/doc-qa/index.ts:27-28
Timestamp: 2025-06-28T18:06:02.340Z
Learning: The answerQuestion function in agent-docs/src/agents/doc-qa/rag.ts handles errors internally by logging them and returning a fallback JSON answer, so it doesn't require external try-catch blocks at the call site.
components/CustomSearchDialog/MessageList.tsx (1)
Learnt from: CR
PR: agentuity/docs#0
File: .cursor/rules/mdx.mdc:0-0
Timestamp: 2025-07-01T12:36:29.712Z
Learning: This is MDX so some react components can be used
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (8)
components/CustomSearchDialog/SearchInput.tsx (4)
33-37: LGTM! Clean extraction of send logic.The
handleSendfunction properly validates input and provides a cleaner separation of concerns compared to the inline handler.
61-72: Excellent button improvements.The fixed dimensions, proper flex alignment, explicit button type, and consistent disabled styling significantly improve the button's appearance and behavior.
33-37: Good refactoring of send logic.The extraction of the send logic into a dedicated
handleSendfunction improves code organization and reduces duplication between the button click and keyboard handler.
61-72: LGTM on button container restructure.The button wrapper with
flex flex-coland fixed dimensions (h-[40px] w-[40px]) appears to be a layout fix as mentioned in the comment. The explicittype="button"and consistent disabled styling are good practices.components/CustomSearchDialog/MessageList.tsx (4)
115-156: Excellent markdown customization for code blocks.The custom
preandcodecomponents significantly enhance the user experience by adding copy functionality and proper text wrapping. The implementation integrates well with the existing ReactMarkdown setup.
159-159: Good text wrapping improvement.Adding
break-wordsto user messages prevents overflow issues and maintains consistent text handling throughout the component.
10-33: Solid implementation of copy-to-clipboard functionality.The
CopyButtoncomponent handles the clipboard API properly with error handling, visual feedback, and automatic state reset. The styling and positioning work well for code blocks.
159-159: Good addition of text wrapping class.The
break-wordsclass ensures long user messages wrap properly without breaking the layout.
2 participants
Summary by CodeRabbit
New Features
Bug Fixes
Improvements
Chores