feat(chat): add web search mode toggle for Chat Shell #790

johnny0120 · 2025-12-31T01:40:05Z

Implement frontend control for web search behavior in Chat mode with three selectable modes:

Auto: AI decides whether to search (default behavior)
On: Force search with specified engine
Off: Disable search completely

Changes include:

Extended SearchEngineSelector component with three-state mode
Added web search state management with localStorage persistence
Updated WebSocket payload to support force/disable search flags
Added force web search prompt injection in backend
Implemented search tool registration logic based on mode
Added i18n translations for search modes (zh-CN and en)

The feature is only visible for Chat Shell bots when WEB_SEARCH_ENABLED is true in backend configuration.

Summary by CodeRabbit

New Features
- Added web search mode selector with three options: auto (AI-determined), on (force search), and off (disable search)
- Implemented search engine selection interface for configurable web search providers
- Added UI controls and localization for web search configuration in English and Chinese

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Implement frontend control for web search behavior in Chat mode with three selectable modes: - Auto: AI decides whether to search (default behavior) - On: Force search with specified engine - Off: Disable search completely Changes include: - Extended SearchEngineSelector component with three-state mode - Added web search state management with localStorage persistence - Updated WebSocket payload to support force/disable search flags - Added force web search prompt injection in backend - Implemented search tool registration logic based on mode - Added i18n translations for search modes (zh-CN and en) The feature is only visible for Chat Shell bots when WEB_SEARCH_ENABLED is true in backend configuration.

coderabbitai · 2025-12-31T01:40:19Z

📝 Walkthrough

Walkthrough

This PR implements granular web search configuration controls across the full stack. It adds two new boolean flags (force_web_search and disable_web_search) to message payloads and agent configuration, redesigns the frontend web search mode selector from a toggle to a three-state model (auto/on/off), and integrates web search preferences with localStorage persistence throughout the chat workflow.

Changes

Cohort / File(s)	Summary
Backend WebSocket/Payload Models `backend/app/api/ws/events.py`, `backend/app/services/chat/config/stream_config.py`, `frontend/src/types/socket.ts`	Added `force_web_search` and `disable_web_search` boolean fields to ChatSendPayload and WebSocketStreamConfig to enable granular web search control per message.
Backend Agent/Config Integration `backend/app/chat_shell/agent.py`, `backend/app/services/chat/streaming/ws_handler.py`	Extended AgentConfig with `force_web_search` field and updated ws_handler to conditionally add WebSearchTool (respecting `disable_web_search`) and forward config flags.
Backend Prompt Building `backend/app/chat_shell/prompts/builder.py`	Added FORCE_WEB_SEARCH_PROMPT constant and `append_force_web_search_prompt()` function; updated `build_system_prompt()` signature to accept and conditionally apply force web search instructions. ⚠️ Note: Duplicate definitions detected in module.
Backend Streaming Pipeline `backend/app/services/chat/trigger/core.py`	Propagated web search flags (force_web_search, disable_web_search) from ChatSendPayload into WebSocketStreamConfig during streaming initialization.
Frontend State Management `frontend/src/features/tasks/components/chat/useChatAreaState.ts`, `frontend/src/features/tasks/components/chat/useChatStreamHandlers.tsx`	Introduced WebSearchMode type and integrated web search state with localStorage persistence; threaded web search configuration (mode and engine selection) through message-sending handlers.
Frontend Chat Components `frontend/src/features/tasks/components/chat/ChatArea.tsx`, `frontend/src/features/tasks/components/input/ChatInputCard.tsx`	Added web search state initialization (fetching enabled status and available engines) and propagated web search props through component hierarchy.
Frontend Web Search UI `frontend/src/features/tasks/components/input/ChatInputControls.tsx`, `frontend/src/features/tasks/components/selector/SearchEngineSelector.tsx`	Integrated SearchEngineSelector component into input controls; redesigned selector from boolean toggle to WebSearchMode dropdown (auto/on/off) with dynamic engine selection and mode-specific UI presentation.
Frontend Types & Context `frontend/src/features/tasks/contexts/chatStreamContext.tsx`	Extended ChatMessageRequest and ChatSendPayload with `force_web_search` and `disable_web_search` optional fields; propagated flags through sendMessage flow.
Localization `frontend/src/i18n/locales/en/chat.json`, `frontend/src/i18n/locales/zh-CN/chat.json`	Added translations for new web search mode options: select_mode, mode_auto (with description), mode_on (with description), mode_off (with description) in English and Chinese.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

feat(chat): support multiple file attachments in a single chat message #665: Modifies ChatSendPayload structure with additional field additions, sharing the same backend payload extension point.
Weagent/add web search feature #367: Implements per-message web search controls across streaming config and chat handlers, using overlapping service/handler surfaces.
feat: add web search selector #387: Implements complementary web search feature surface with frontend selector UI and backend tool integration, sharing payload and configuration infrastructure.

Suggested reviewers

qdaxb
feifei325

Poem

🐰 A rabbit hops through web search modes
Auto, on, and off it goes
Force a search or disable it flat
Backend config, frontend chat
Search preferences, localStorage'd and free
Web knowledge at the click, you see! 🌐

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a web search mode toggle feature for Chat Shell, which aligns with the core functionality introduced across frontend and backend.
Docstring Coverage	✅ Passed	Docstring coverage is 84.62% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (2)

backend/app/services/chat/config/stream_config.py (1)

58-59: Add validation for mutually exclusive flags.

Similar to the frontend, force_web_search and disable_web_search are mutually exclusive but not enforced. When both are True, the behavior is ambiguous. Consider adding a validation method to the dataclass:

🔎 Proposed validation

 @dataclass
 class WebSocketStreamConfig:
     """Configuration for WebSocket streaming.
 
     Attributes:
         task_id: Task ID for the chat session
         subtask_id: Assistant subtask ID
         task_room: WebSocket room name for broadcasting
 
         user_id: User ID for permission checks and history loading
         user_name: User name for group chat message prefix
         is_group_chat: Whether this is a group chat (affects message prefix and history truncation)
 
         message_id: Assistant's message_id for frontend ordering
         user_message_id: User's message_id for history exclusion (prevents duplicate messages)
 
         enable_web_search: Enable web search tool
         search_engine: Specific search engine to use
 
         bot_name: Bot name for MCP server loading
         bot_namespace: Bot namespace
         shell_type: Shell type (Chat, ClaudeCode, Agno) for frontend display
         extra_tools: Additional tools (e.g., KnowledgeBaseTool)
     """
 
     # Task identification
     task_id: int
     subtask_id: int
     task_room: str
 
     # User context
     user_id: int
     user_name: str
     is_group_chat: bool = False
 
     # Message ordering context
     message_id: int | None = None  # Assistant's message_id for ordering in frontend
     user_message_id: int | None = None  # User's message_id for history exclusion
 
     # Feature flags
     enable_tools: bool = True  # Enable tools (MCP, web search, skills, etc.)
     enable_web_search: bool = False
     search_engine: str | None = None
     force_web_search: bool = False  # Force AI to perform web search at least once
     disable_web_search: bool = False  # Completely disable web search tool
 
     # Prompt enhancement options
     enable_clarification: bool = False
     enable_deep_thinking: bool = True
     skills: list[dict] = field(
         default_factory=list
     )  # Skill metadata for prompt injection
 
     # Bot configuration
     bot_name: str = ""
     bot_namespace: str = "default"
     shell_type: str = "Chat"  # Shell type for frontend display
     extra_tools: list[BaseTool] = field(default_factory=list)
 
+    def __post_init__(self):
+        """Validate that mutually exclusive flags are not both set."""
+        if self.force_web_search and self.disable_web_search:
+            raise ValueError(
+                "force_web_search and disable_web_search cannot both be True"
+            )
+
     def get_username_for_message(self) -> str | None:
         """Get username for message prefix in group chat mode."""
         return self.user_name if self.is_group_chat else None

backend/app/api/ws/events.py (1)

106-113: Consider adding validation for mutually exclusive flags.

The force_web_search and disable_web_search flags are semantically mutually exclusive—enabling both simultaneously would be contradictory. While the frontend appears to handle this correctly, consider adding a Pydantic model_validator to enforce this constraint at the API boundary.
🔎 Optional: Add model validator
+from pydantic import BaseModel, Field, model_validator
+
 class ChatSendPayload(BaseModel):
     """Payload for chat:send event."""
     # ... existing fields ...
     force_web_search: bool = Field(
         False, description="Force AI to perform web search at least once"
     )
     disable_web_search: bool = Field(
         False, description="Completely disable web search tool"
     )
+
+    @model_validator(mode='after')
+    def validate_web_search_flags(self) -> 'ChatSendPayload':
+        if self.force_web_search and self.disable_web_search:
+            raise ValueError("Cannot both force and disable web search")
+        return self

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 38f4c24 and da7bae1.

📒 Files selected for processing (16)

backend/app/api/ws/events.py
backend/app/chat_shell/agent.py
backend/app/chat_shell/prompts/builder.py
backend/app/services/chat/config/stream_config.py
backend/app/services/chat/streaming/ws_handler.py
backend/app/services/chat/trigger/core.py
frontend/src/features/tasks/components/chat/ChatArea.tsx
frontend/src/features/tasks/components/chat/useChatAreaState.ts
frontend/src/features/tasks/components/chat/useChatStreamHandlers.tsx
frontend/src/features/tasks/components/input/ChatInputCard.tsx
frontend/src/features/tasks/components/input/ChatInputControls.tsx
frontend/src/features/tasks/components/selector/SearchEngineSelector.tsx
frontend/src/features/tasks/contexts/chatStreamContext.tsx
frontend/src/i18n/locales/en/chat.json
frontend/src/i18n/locales/zh-CN/chat.json
frontend/src/types/socket.ts

🧰 Additional context used

📓 Path-based instructions (9)

**/*.{py,ts,tsx,js,jsx}