fix: resolve external agent UI issues found by code reviewers

- Fix P1 global state contamination in default_app.py (session isolation)
- Fix external agent tools bypassing tools_enabled guard in chat.py
- Fix cache invalidation to include external agent selection
- Fix Chainlit Select API usage (use MultiSelect for multi-selection)
- Fix type annotations (use Optional[list[str]] instead of list)
- Fix mention detection regex for better accuracy
- Fix agent.start_async call (should be agent.achat)
- Prevent mutation of cached tools list

Addresses critical issues found by Greptile, CodeRabbit, and Copilot reviewers.
Maintains backward compatibility while fixing runtime crashes and isolation bugs.

Co-authored-by: Mervin Praison <MervinPraison@users.noreply.github.com>

Author: praisonai-triage-agent[bot]

src/praisonai/praisonai/ui/chat.py

@@ -17,6 +17,7 @@
 # Standard library imports (minimal at top level)
 import os
 import logging
+from typing import Optional
 
 # Set up minimal logging first
 logger = logging.getLogger(__name__)
@@ -31,7 +32,7 @@
 
 # Chainlit must be imported early (required by decorators)
 import chainlit as cl
-from chainlit.input_widget import TextInput, Switch, Select
+from chainlit.input_widget import TextInput, Switch, Select, MultiSelect
 from chainlit.types import ThreadDict
 import chainlit.data as cl_data
 
@@ -447,7 +448,7 @@ def auth_callback(username: str, password: str):
         logger.warning(f"Login failed for user: {username}")
         return None
 
-def _get_or_create_agent(model_name: str, tools_enabled: bool = True, selected_external_agents: list = None):
+def _get_or_create_agent(model_name: str, tools_enabled: bool = True, selected_external_agents: Optional[list[str]] = None):
     """Get or create a reusable agent for the session."""
     Agent = _get_praisonai_agent()
     if Agent is None:
@@ -456,32 +457,35 @@ def _get_or_create_agent(model_name: str, tools_enabled: bool = True, selected_e
     # Get cached agent from session
     cached_agent = cl.user_session.get("_cached_agent")
     cached_model = cl.user_session.get("_cached_agent_model")
+    cached_external_agents = cl.user_session.get("_cached_external_agents", [])
 
-    # Reuse if model matches
-    if cached_agent is not None and cached_model == model_name:
+    # Reuse if model and external agents match
+    if (cached_agent is not None and 
+        cached_model == model_name and
+        cached_external_agents == (selected_external_agents or [])):
         return cached_agent
 
     # Create new agent with interactive tools
     _profile_start("create_agent")
     tools = []
     if tools_enabled:
-        tools = _get_interactive_tools()
+        tools = list(_get_interactive_tools())  # Copy to avoid mutation
         # Add Tavily if available
         if os.getenv("TAVILY_API_KEY"):
             tools.append(tavily_web_search)
-    
-    # Add external agent tools
-    if selected_external_agents:
-        handler = _get_external_agents_handler()
-        if handler:
-            for agent_name in selected_external_agents:
-                try:
-                    integration = handler.get_integration(agent_name)
-                    if integration and integration.is_available:
-                        tools.append(integration.as_tool())
-                        logger.info(f"Added external agent tool: {agent_name}")
-                except Exception as e:
-                    logger.warning(f"Could not load external agent {agent_name}: {e}")
+        
+        # Add external agent tools (only when tools are enabled)
+        if selected_external_agents:
+            handler = _get_external_agents_handler()
+            if handler:
+                for agent_name in selected_external_agents:
+                    try:
+                        integration = handler.get_integration(agent_name)
+                        if integration and integration.is_available:
+                            tools.append(integration.as_tool())
+                            logger.info(f"Added external agent tool: {agent_name}")
+                    except Exception as e:
+                        logger.warning(f"Could not load external agent {agent_name}: {e}")
 
     # Build instructions based on available tools
     instructions = """You are a helpful AI assistant with access to powerful tools.
@@ -534,11 +538,12 @@ async def start():
 
     # Get available external agents for settings
     available_external_agents = _check_available_external_agents()
-    external_agent_options = []
+    # Build agent options dict for MultiSelect
+    external_agent_options = {}
     for agent_name, is_available in available_external_agents.items():
         if is_available:
             description = _EXTERNAL_AGENT_DESCRIPTIONS.get(agent_name, agent_name)
-            external_agent_options.append(cl.SelectOption(label=description, value=agent_name))
+            external_agent_options[description] = agent_name
 
     settings_widgets = [
         TextInput(
@@ -557,12 +562,11 @@ async def start():
     # Add external agents selector if any are available
     if external_agent_options:
         settings_widgets.append(
-            Select(
+            MultiSelect(
                 id="external_agents",
                 label="External AI Agents (Select multiple)",
-                options=external_agent_options,
-                initial=selected_external_agents,
-                multiple=True
+                items=external_agent_options,
+                initial=selected_external_agents
             )
         )
 
@@ -882,11 +886,12 @@ async def on_chat_resume(thread: ThreadDict):
     logger.debug(f"Model name: {model_name}")
     # Get available external agents for settings
     available_external_agents = _check_available_external_agents()
-    external_agent_options = []
+    # Build agent options dict for MultiSelect
+    external_agent_options = {}
     for agent_name, is_available in available_external_agents.items():
         if is_available:
             description = _EXTERNAL_AGENT_DESCRIPTIONS.get(agent_name, agent_name)
-            external_agent_options.append(cl.SelectOption(label=description, value=agent_name))
+            external_agent_options[description] = agent_name
 
     settings_widgets = [
         TextInput(
@@ -904,12 +909,11 @@ async def on_chat_resume(thread: ThreadDict):
 
     if external_agent_options:
         settings_widgets.append(
-            Select(
+            MultiSelect(
                 id="external_agents",
                 label="External AI Agents (Select multiple)",
-                options=external_agent_options,
-                initial=selected_external_agents,
-                multiple=True
+                items=external_agent_options,
+                initial=selected_external_agents
             )
         )
 

src/praisonai/praisonai/ui/code.py

@@ -11,6 +11,7 @@
 # Standard library imports (minimal at top level)
 import os
 import logging
+from typing import Optional
 
 # Set up minimal logging first
 logger = logging.getLogger(__name__)
@@ -25,7 +26,7 @@
 
 # Chainlit must be imported early (required by decorators)
 import chainlit as cl
-from chainlit.input_widget import TextInput, Switch, Select
+from chainlit.input_widget import TextInput, Switch, Select, MultiSelect
 from chainlit.types import ThreadDict
 import chainlit.data as cl_data
 
@@ -461,7 +462,7 @@ def _check_available_external_agents():
         return handler.check_availability()
     return {}
 
-def _get_or_create_agent(model_name: str, tools_enabled: bool = True, claude_code_enabled: bool = False, selected_external_agents: list = None):
+def _get_or_create_agent(model_name: str, tools_enabled: bool = True, claude_code_enabled: bool = False, selected_external_agents: Optional[list[str]] = None):
     """Get or create a reusable agent for the session."""
     Agent = _get_praisonai_agent()
     if Agent is None:
@@ -561,11 +562,12 @@ async def start():
 
     # Get available external agents for settings
     available_external_agents = _check_available_external_agents()
-    external_agent_options = []
+    # Build agent options dict for MultiSelect
+    external_agent_options = {}
     for agent_name, is_available in available_external_agents.items():
         if is_available:
             description = _EXTERNAL_AGENT_DESCRIPTIONS.get(agent_name, agent_name)
-            external_agent_options.append(cl.SelectOption(label=description, value=agent_name))
+            external_agent_options[description] = agent_name
 
     settings_widgets = [
         TextInput(
@@ -588,12 +590,11 @@ async def start():
 
     if external_agent_options:
         settings_widgets.append(
-            Select(
+            MultiSelect(
                 id="external_agents",
                 label="External AI Agents (Select multiple)",
-                options=external_agent_options,
-                initial=selected_external_agents,
-                multiple=True
+                items=external_agent_options,
+                initial=selected_external_agents
             )
         )
 
@@ -856,11 +857,12 @@ async def on_chat_resume(thread: ThreadDict):
     logger.debug(f"Model name: {model_name}")
     # Get available external agents for settings
     available_external_agents = _check_available_external_agents()
-    external_agent_options = []
+    # Build agent options dict for MultiSelect
+    external_agent_options = {}
     for agent_name, is_available in available_external_agents.items():
         if is_available:
             description = _EXTERNAL_AGENT_DESCRIPTIONS.get(agent_name, agent_name)
-            external_agent_options.append(cl.SelectOption(label=description, value=agent_name))
+            external_agent_options[description] = agent_name
 
     settings_widgets = [
         TextInput(
@@ -883,12 +885,11 @@ async def on_chat_resume(thread: ThreadDict):
 
     if external_agent_options:
         settings_widgets.append(
-            Select(
+            MultiSelect(
                 id="external_agents",
                 label="External AI Agents (Select multiple)",
-                options=external_agent_options,
-                initial=selected_external_agents,
-                multiple=True
+                items=external_agent_options,
+                initial=selected_external_agents
             )
         )
 

src/praisonai/praisonai/ui_chat/default_app.py

@@ -22,10 +22,8 @@
 aiui.set_theme(preset="blue", dark_mode=True, radius="lg")
 aiui.set_pages(["chat"])
 
-# Global state for external agents
-_available_agents = {}
-_selected_agents = []
-_agent_instance = None
+# Module-level cache for available agents (read-only)
+_available_agents_cache = {}
 
 
 def _get_external_agents_handler():
@@ -47,12 +45,17 @@ def _check_available_agents() -> Dict[str, bool]:
 
 def _get_agent_with_tools(model: str, selected_agents: List[str]):
     """Create or get cached PraisonAI agent with external agent tools."""
-    global _agent_instance
+    # Get session-scoped state
+    if not hasattr(aiui, 'session_state'):
+        session_state = {}
+    else:
+        session_state = aiui.session_state
 
     # Simple caching based on model and selected agents
     cache_key = f"{model}:{','.join(sorted(selected_agents))}"
-    if _agent_instance and getattr(_agent_instance, '_cache_key', '') == cache_key:
-        return _agent_instance
+    cached_agent = session_state.get('agent_instance')
+    if cached_agent and getattr(cached_agent, '_cache_key', '') == cache_key:
+        return cached_agent
 
     try:
         from praisonaiagents import Agent
@@ -78,7 +81,7 @@ def _get_agent_with_tools(model: str, selected_agents: List[str]):
             tools=tools if tools else None
         )
         agent._cache_key = cache_key
-        _agent_instance = agent
+        session_state['agent_instance'] = agent
         return agent
 
     except ImportError:
@@ -89,13 +92,18 @@ def _get_agent_with_tools(model: str, selected_agents: List[str]):
 @aiui.sidebar
 async def external_agents_settings():
     """Render external agents selection in sidebar."""
-    global _available_agents, _selected_agents
+    # Get session-scoped state
+    if not hasattr(aiui, 'session_state'):
+        # Fallback if session_state not available
+        session_state = {}
+    else:
+        session_state = aiui.session_state
 
-    # Check available agents (cached)
-    if not _available_agents:
-        _available_agents = _check_available_agents()
+    # Check available agents (cached at module level for performance)
+    if not _available_agents_cache:
+        _available_agents_cache.update(_check_available_agents())
 
-    if not _available_agents:
+    if not any(_available_agents_cache.values()):
         aiui.markdown("**No External Agents**")
         aiui.markdown("No external AI agents are installed. Install them to enable delegation:")
         aiui.markdown("- `curl -fsSL https://claude.ai/install.sh | sh` (Claude Code)")
@@ -113,11 +121,14 @@ async def external_agents_settings():
         "cursor": "Cursor CLI (IDE tasks)"
     }
 
+    # Get current selection from session state
+    current_selection = session_state.get('selected_agents', [])
     updated_selection = []
-    for agent_name, is_available in _available_agents.items():
+    
+    for agent_name, is_available in _available_agents_cache.items():
         if is_available:
             description = agent_descriptions.get(agent_name, agent_name)
-            is_selected = agent_name in _selected_agents
+            is_selected = agent_name in current_selection
 
             # Create toggle button as checkbox alternative
             if is_selected:
@@ -134,12 +145,11 @@ async def external_agents_settings():
                     # Button clicked - add to selection (toggle on)
                     updated_selection.append(agent_name)
 
-    # Update global selection if changed
-    if updated_selection != _selected_agents:
-        _selected_agents = updated_selection
+    # Update session-scoped selection if changed
+    if updated_selection != current_selection:
+        session_state['selected_agents'] = updated_selection
         # Clear agent cache to recreate with new tools
-        global _agent_instance
-        _agent_instance = None
+        session_state['agent_instance'] = None
 
         if updated_selection:
             aiui.success(f"External agents enabled: {', '.join(updated_selection)}")
@@ -172,8 +182,15 @@ async def on_message(message: str):
 
     model = os.getenv("PRAISONAI_MODEL", "gpt-4o-mini")
 
+    # Get session-scoped state
+    if not hasattr(aiui, 'session_state'):
+        session_state = {}
+    else:
+        session_state = aiui.session_state
+    
     # Try to use PraisonAI agent with external agents
-    agent = _get_agent_with_tools(model, _selected_agents)
+    selected_agents = session_state.get('selected_agents', [])
+    agent = _get_agent_with_tools(model, selected_agents)
     if agent:
         try:
             # Check for @mentions for direct delegation
@@ -185,18 +202,20 @@ async def on_message(message: str):
             }
 
             mentioned_agent = None
+            import re
             for mention, agent_name in agent_mentions.items():
-                if mention in message.lower() and agent_name in _selected_agents:
-                    mentioned_agent = agent_name
-                    # Remove mention from message
-                    message = message.replace(mention, "").replace(mention.title(), "").strip()
-                    break
+                if agent_name in selected_agents:
+                    pattern = re.compile(rf'(?<!\w){re.escape(mention)}\b', re.IGNORECASE)
+                    if pattern.search(message):
+                        mentioned_agent = agent_name
+                        message = pattern.sub("", message).strip()
+                        break
 
             if mentioned_agent:
                 await aiui.say(f"🤖 Delegating to {mentioned_agent}...")
 
             # Use PraisonAI agent (supports async)
-            response = await agent.start_async(message)
+            response = await agent.achat(message)
             if hasattr(response, 'content'):
                 content = response.content
             elif hasattr(response, 'result'):