webagents 0.2.0__py3-none-any.whl → 0.2.3__py3-none-any.whl

webagents/agents/core/base_agent.py

@@ -20,7 +20,7 @@ import json
 import threading
 import time
 import uuid
-from typing import Dict, Any, List, Optional, Callable, Union, AsyncGenerator
+from typing import Dict, Any, List, Optional, Callable, Union, AsyncGenerator, Awaitable
 from datetime import datetime
 
 from ..skills.base import Skill, Handoff, HandoffResult
@@ -125,17 +125,21 @@ class BaseAgent:
         self._registered_hooks: Dict[str, List[Dict[str, Any]]] = {}
         self._registered_handoffs: List[Dict[str, Any]] = []
         self._registered_prompts: List[Dict[str, Any]] = []
+        self._registered_widgets: List[Dict[str, Any]] = []
         self._registered_http_handlers: List[Dict[str, Any]] = []
         self._registration_lock = threading.Lock()
         
         # Track tools overridden by external tools (per request)
         self._overridden_tools: set = set()
         
+        # Active handoff (completion handler) - set to lowest priority handoff after initialization
+        self.active_handoff: Optional[Handoff] = None
+        
         # Skills management
         self.skills: Dict[str, Skill] = {}
         
-        # Structured logger setup (align with DynamicAgentFactory style)
-        self.logger = get_logger('base_agent', 'core')
+        # Structured logger setup (use agent name as subsystem for clear log attribution)
+        self.logger = get_logger('base_agent', self.name)
         self._ensure_logger_handler()
         
         # Process model parameter and initialize skills
@@ -252,18 +256,21 @@ class BaseAgent:
                 if isinstance(handoff_item, Handoff):
                     # Direct Handoff object
                     self.register_handoff(handoff_item, source="agent")
-                    self.logger.debug(f"📨 Registered handoff target='{handoff_item.target}' type='{handoff_item.handoff_type}'")
+                    self.logger.debug(f"📨 Registered handoff target='{handoff_item.target}'")
                 elif callable(handoff_item) and hasattr(handoff_item, '_webagents_is_handoff'):
                     # Function with @handoff decorator
                     handoff_config = Handoff(
                         target=getattr(handoff_item, '_handoff_name', handoff_item.__name__),
-                        handoff_type=getattr(handoff_item, '_handoff_type', 'agent'),
-                        description=getattr(handoff_item, '_handoff_description', ''),
+                        description=getattr(handoff_item, '_handoff_prompt', ''),
                         scope=getattr(handoff_item, '_handoff_scope', self.scopes)
                     )
-                    handoff_config.metadata = {'function': handoff_item}
+                    handoff_config.metadata = {
+                        'function': handoff_item,
+                        'priority': getattr(handoff_item, '_handoff_priority', 50),
+                        'is_generator': getattr(handoff_item, '_handoff_is_generator', False)
+                    }
                     self.register_handoff(handoff_config, source="agent")
-                    self.logger.debug(f"📨 Registered handoff target='{handoff_config.target}' type='{handoff_config.handoff_type}'")
+                    self.logger.debug(f"📨 Registered handoff target='{handoff_config.target}'")
         
         # Register HTTP handlers
         if http_handlers:
@@ -286,11 +293,14 @@ class BaseAgent:
                     elif hasattr(capability_func, '_webagents_is_handoff') and capability_func._webagents_is_handoff:
                         handoff_config = Handoff(
                             target=getattr(capability_func, '_handoff_name', capability_func.__name__),
-                            handoff_type=getattr(capability_func, '_handoff_type', 'agent'),
-                            description=getattr(capability_func, '_handoff_description', ''),
+                            description=getattr(capability_func, '_handoff_prompt', ''),
                             scope=getattr(capability_func, '_handoff_scope', self.scopes)
                         )
-                        handoff_config.metadata = {'function': capability_func}
+                        handoff_config.metadata = {
+                            'function': capability_func,
+                            'priority': getattr(capability_func, '_handoff_priority', 50),
+                            'is_generator': getattr(capability_func, '_handoff_is_generator', False)
+                        }
                         self.register_handoff(handoff_config, source="agent")
                     elif hasattr(capability_func, '_webagents_is_http') and capability_func._webagents_is_http:
                         self.register_http_handler(capability_func)
@@ -381,16 +391,45 @@ class BaseAgent:
             elif hasattr(attr, '_webagents_is_handoff') and attr._webagents_is_handoff:
                 handoff_config = Handoff(
                     target=getattr(attr, '_handoff_name', attr_name),
-                    handoff_type=getattr(attr, '_handoff_type', 'agent'),
-                    description=getattr(attr, '_handoff_description', ''),
-                    scope=getattr(attr, '_handoff_scope', None)
+                    description=getattr(attr, '_handoff_prompt', ''),  # prompt becomes description
+                    scope=getattr(attr, '_handoff_scope', None),
+                    metadata={
+                        'function': attr,
+                        'priority': getattr(attr, '_handoff_priority', 50),
+                        'is_generator': getattr(attr, '_handoff_is_generator', False)
+                    }
                 )
-                handoff_config.metadata = {'function': attr}
                 self.register_handoff(handoff_config, source=skill_name)
+                
+                # Auto-create invocation tool if requested
+                if hasattr(attr, '_handoff_auto_tool') and attr._handoff_auto_tool:
+                    target_name = handoff_config.target
+                    tool_desc = getattr(attr, '_handoff_auto_tool_description', f"Switch to {target_name} handoff")
+                    
+                    # Create tool function that returns handoff request marker
+                    async def invoke_handoff_tool(skill_instance=skill):
+                        return skill_instance.request_handoff(target_name)
+                    
+                    # Register as tool
+                    invoke_handoff_tool.__name__ = f"use_{target_name}"
+                    invoke_handoff_tool._webagents_is_tool = True
+                    invoke_handoff_tool._tool_description = tool_desc
+                    invoke_handoff_tool._tool_scope = handoff_config.scope
+                    
+                    self.register_tool(
+                        invoke_handoff_tool,
+                        source=f"{skill_name}_handoff_tool"
+                    )
+                    self.logger.debug(f"🔧 Auto-registered handoff invocation tool: use_{target_name}")
             
             # Check for @http decorator
             elif hasattr(attr, '_webagents_is_http') and attr._webagents_is_http:
                 self.register_http_handler(attr, source=skill_name)
+            
+            # Check for @widget decorator
+            elif hasattr(attr, '_webagents_is_widget') and attr._webagents_is_widget:
+                scope = getattr(attr, '_widget_scope', None)
+                self.register_widget(attr, source=skill_name, scope=scope)
     
     # Central registration methods (thread-safe)
     def register_tool(self, tool_func: Callable, source: str = "manual", scope: Union[str, List[str]] = None):
@@ -407,6 +446,41 @@ class BaseAgent:
             self._registered_tools.append(tool_config)
         self.logger.debug(f"🛠️ Tool registered name='{tool_config['name']}' source='{source}' scope={scope}")
     
+    def register_widget(self, widget_func: Callable, source: str = "manual", scope: Union[str, List[str]] = None):
+        """Register a widget function
+        
+        Widgets are registered both as widgets (for browser filtering) and as tools (for execution).
+        """
+        widget_name = getattr(widget_func, '_widget_name', widget_func.__name__)
+        widget_definition = getattr(widget_func, '_webagents_widget_definition', {})
+        
+        with self._registration_lock:
+            # Register as widget (for browser filtering)
+            widget_config = {
+                'function': widget_func,
+                'source': source,
+                'scope': scope,
+                'name': widget_name,
+                'description': getattr(widget_func, '_widget_description', widget_func.__doc__ or ''),
+                'definition': widget_definition,
+                'template': getattr(widget_func, '_widget_template', None)
+            }
+            self._registered_widgets.append(widget_config)
+            
+            # Also register as tool (for execution)
+            # This allows _get_tool_function_by_name to find it and mark it as internal
+            tool_config = {
+                'function': widget_func,
+                'name': widget_name,
+                'description': getattr(widget_func, '_widget_description', widget_func.__doc__ or ''),
+                'definition': widget_definition,
+                'source': source,
+                'scope': scope
+            }
+            self._registered_tools.append(tool_config)
+            
+        self.logger.debug(f"🎨 Widget registered name='{widget_name}' source='{source}' scope={scope} (also registered as tool for execution)")
+    
     def register_hook(self, event: str, handler: Callable, priority: int = 50, source: str = "manual", scope: Union[str, List[str]] = None):
         """Register a hook handler for an event"""
         with self._registration_lock:
@@ -426,13 +500,102 @@ class BaseAgent:
         self.logger.debug(f"🪝 Hook registered event='{event}' priority={priority} source='{source}' scope={scope}")
     
     def register_handoff(self, handoff_config: Handoff, source: str = "manual"):
-        """Register a handoff configuration"""
+        """Register a handoff configuration with priority-based default selection
+        
+        Args:
+            handoff_config: Handoff configuration
+            source: Source of registration (skill name, "agent", "manual")
+        """
         with self._registration_lock:
+            function = handoff_config.metadata.get('function')
+            
+            # Auto-detect if generator
+            is_generator = inspect.isasyncgenfunction(function) if function else False
+            priority = handoff_config.metadata.get('priority', 50)
+            
+            # Store metadata
+            handoff_config.metadata.update({
+                'is_generator': is_generator,
+                'priority': priority
+            })
+            
             self._registered_handoffs.append({
                 'config': handoff_config,
                 'source': source
             })
-        self.logger.debug(f"📨 Handoff registered target='{handoff_config.target}' type='{handoff_config.handoff_type}' source='{source}'")
+            
+            # Sort handoffs by priority (lower = higher priority)
+            self._registered_handoffs.sort(key=lambda x: (
+                x['config'].metadata.get('priority', 50),  # Primary: priority
+                x['source'],  # Secondary: source name
+                x['config'].target  # Tertiary: target name
+            ))
+            
+            # Set as default if this is the highest priority handoff
+            if not self.active_handoff or priority < self.active_handoff.metadata.get('priority', 50):
+                self.active_handoff = handoff_config
+                self.logger.info(f"📨 Set default handoff: {handoff_config.target} (priority={priority})")
+        
+        self.logger.debug(
+            f"📨 Handoff registered target='{handoff_config.target}' "
+            f"priority={priority} generator={is_generator} source='{source}'"
+        )
+        
+        # Register handoff's prompt if present
+        if handoff_config.description:
+            self._register_handoff_prompt(handoff_config, source)
+    
+    def get_handoff_by_target(self, target_name: str) -> Optional[Handoff]:
+        """Get handoff configuration by target name
+        
+        Args:
+            target_name: Target name of the handoff (e.g., 'openai_workflow', 'specialist_agent')
+        
+        Returns:
+            Handoff configuration if found, None otherwise
+        """
+        with self._registration_lock:
+            for entry in self._registered_handoffs:
+                if entry['config'].target == target_name:
+                    return entry['config']
+        return None
+
+    def list_available_handoffs(self) -> List[Dict[str, Any]]:
+        """List all registered handoffs with their metadata
+        
+        Returns:
+            List of dicts with: target, description, priority, source, scope
+        """
+        with self._registration_lock:
+            return [
+                {
+                    'target': entry['config'].target,
+                    'description': entry['config'].description,
+                    'priority': entry['config'].metadata.get('priority', 50),
+                    'source': entry['source'],
+                    'scope': entry['config'].scope
+                }
+                for entry in self._registered_handoffs
+            ]
+    
+    def _register_handoff_prompt(self, handoff_config: Handoff, source: str):
+        """Register handoff's prompt as dynamic prompt provider"""
+        prompt_text = handoff_config.description
+        priority = handoff_config.metadata.get('priority', 50)
+        
+        # Create prompt provider function
+        def handoff_prompt_provider(context=None):
+            return prompt_text
+        
+        # Register as prompt with same priority as handoff
+        self.register_prompt(
+            handoff_prompt_provider,
+            priority=priority,
+            source=f"{source}_handoff_prompt",
+            scope=handoff_config.scope
+        )
+        
+        self.logger.debug(f"📨 Registered handoff prompt for '{handoff_config.target}'")
     
     def register_prompt(self, prompt_func: Callable, priority: int = 50, source: str = "manual", scope: Union[str, List[str]] = None):
         """Register a prompt provider function"""
@@ -554,6 +717,11 @@ class BaseAgent:
         with self._registration_lock:
             return self._registered_tools.copy()
     
+    def get_all_widgets(self) -> List[Dict[str, Any]]:
+        """Get all registered widgets regardless of scope"""
+        with self._registration_lock:
+            return self._registered_widgets.copy()
+    
     def get_all_http_handlers(self) -> List[Dict[str, Any]]:
         """Get all registered HTTP handlers"""
         with self._registration_lock:
@@ -641,7 +809,7 @@ class BaseAgent:
                 # Log prompt execution error but continue
                 self.logger.warning(f"⚠️ Prompt execution error handler='{getattr(handler, '__name__', str(handler))}' error='{e}'")
         
-        prompt_parts.append(f"Your name is {self.name}, you are an AI agent in the Internet of Agents. Current time: {datetime.now().isoformat()}")
+        prompt_parts.append(f"@{self.name}, time: {datetime.now().isoformat()}")
         
         # Combine all prompt parts with newlines
         return "\n\n".join(prompt_parts) if prompt_parts else ""
@@ -688,18 +856,65 @@ class BaseAgent:
                 original_content = message.get("content", "")
                 base_instructions = self.instructions or ""
                 parts = []
+                
+                # Add base instructions first (agent-specific + CORE_SYSTEM_PROMPT)
                 if base_instructions:
                     parts.append(base_instructions)
+                
+                # Only add original_content if it's not already in base_instructions
+                # (prevents duplicate CORE_SYSTEM_PROMPT)
                 if original_content:
-                    parts.append(original_content)
+                    # Check if original_content is substantially different from base_instructions
+                    # Skip if it's just the CORE_SYSTEM_PROMPT that's already in base_instructions
+                    original_trimmed = original_content.strip()
+                    base_trimmed = base_instructions.strip()
+                    
+                    # If original is not a substring of base, it's new content - add it
+                    if original_trimmed and original_trimmed not in base_trimmed:
+                        parts.append(original_content)
+                    else:
+                        self.logger.debug("🔧 Skipped duplicate original_content (already in base_instructions)")
+                
+                # Check if dynamic_prompts contains content already in base_instructions
+                # This prevents CORE_SYSTEM_PROMPT duplication when it's included in both
                 if dynamic_prompts:
-                    parts.append(dynamic_prompts)
+                    dynamic_trimmed = dynamic_prompts.strip()
+                    # Check if dynamic content is substantially overlapping with base instructions
+                    # If >80% of dynamic content is already in base, skip it (likely duplicate CORE_SYSTEM_PROMPT)
+                    if base_trimmed and len(dynamic_trimmed) > 100:
+                        # Count how many lines from dynamic are already in base
+                        dynamic_lines = set(line.strip() for line in dynamic_trimmed.split('\n') if line.strip())
+                        matching_lines = sum(1 for line in dynamic_lines if line in base_trimmed)
+                        overlap_ratio = matching_lines / len(dynamic_lines) if dynamic_lines else 0
+                        
+                        if overlap_ratio > 0.8:
+                            self.logger.debug(f"🔧 Skipped duplicate dynamic_prompts ({overlap_ratio:.1%} overlap with base_instructions)")
+                        else:
+                            parts.append(dynamic_prompts)
+                    else:
+                        parts.append(dynamic_prompts)
+                
                 enhanced_content = "\n\n".join(parts).strip()
                 enhanced_messages.append({
                     **message,
                     "content": enhanced_content
                 })
                 self.logger.debug("🔧 Enhanced existing system message")
+                
+                # Log system prompt breakdown for optimization
+                breakdown = []
+                if base_instructions:
+                    breakdown.append(f"  - Base instructions: {len(base_instructions)} chars")
+                if original_content and original_content.strip() not in base_instructions.strip():
+                    breakdown.append(f"  - Original content: {len(original_content)} chars")
+                if dynamic_prompts:
+                    breakdown.append(f"  - Dynamic prompts: {len(dynamic_prompts)} chars")
+                
+                # Only log on first request (2 messages: system + first user message)
+                # Skip if conversation has more history
+                incoming_count = len([m for m in messages if m.get("role") in ("user", "assistant")])
+                if incoming_count <= 1:  # First user message only
+                    self.logger.info(f"📋 System prompt: {len(enhanced_content)} chars\n" + "\n".join(breakdown))
             else:
                 enhanced_messages.append(message)
         
@@ -714,11 +929,113 @@ class BaseAgent:
                 "content": system_content
             })
             self.logger.debug("🔧 Created new system message with base instructions + dynamic prompts")
+            
+            # Only log on first request (1 message: first user message)
+            incoming_count = len([m for m in messages if m.get("role") in ("user", "assistant")])
+            if incoming_count <= 1:
+                self.logger.info(f"📋 System prompt: {len(system_content)} chars\n  - Base instructions: {len(base_instructions)} chars\n  - Dynamic prompts: {len(dynamic_prompts)} chars")
         
         self.logger.debug(f"📦 Enhanced messages count={len(enhanced_messages)}")
         
         return enhanced_messages
     
+    # Handoff execution methods
+    
+    def _execute_handoff(
+        self,
+        handoff_config: Handoff,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None,
+        stream: bool = False,
+        **kwargs
+    ) -> Union['Awaitable[Dict[str, Any]]', 'AsyncGenerator[Dict[str, Any], None]']:
+        """Execute handoff - returns appropriate type based on mode
+        
+        Args:
+            handoff_config: Handoff configuration to execute
+            messages: Conversation messages
+            tools: Available tools
+            stream: Whether to stream response
+            **kwargs: Additional arguments to pass to handoff function
+        
+        Returns:
+            - If stream=False: Awaitable[Dict] (coroutine to await)
+            - If stream=True: AsyncGenerator (async iterator - NO await!)
+        
+        Note: Caller must handle appropriately:
+            - Non-streaming: response = await self._execute_handoff(..., stream=False)
+            - Streaming: async for chunk in self._execute_handoff(..., stream=True)
+        """
+        function = handoff_config.metadata.get('function')
+        is_generator = handoff_config.metadata.get('is_generator', False)
+        
+        if not function:
+            raise ValueError(f"No function for handoff: {handoff_config.target}")
+        
+        call_kwargs = {'messages': messages, 'tools': tools, **kwargs}
+        
+        if stream:
+            # STREAMING MODE - return AsyncGenerator
+            if is_generator:
+                # Generator function - return directly (NO await!)
+                return function(**call_kwargs)
+            else:
+                # Regular async function - adapt to streaming
+                return self._adapt_response_to_streaming(function, call_kwargs)
+        else:
+            # NON-STREAMING MODE - return Awaitable[Dict]
+            if is_generator:
+                # Generator function - consume all chunks to response
+                return self._consume_generator_to_response(function(**call_kwargs))
+            else:
+                # Regular async function - return coroutine directly (NO await!)
+                return function(**call_kwargs)
+    
+    async def _consume_generator_to_response(
+        self,
+        generator: 'AsyncGenerator[Dict[str, Any], None]'
+    ) -> Dict[str, Any]:
+        """Consume streaming generator and return final response
+        
+        Used when generator handoff is called in non-streaming mode.
+        Reconstructs full response from chunks.
+        
+        Args:
+            generator: Async generator yielding streaming chunks
+        
+        Returns:
+            Full OpenAI-compatible response dict
+        """
+        chunks = []
+        async for chunk in generator:
+            chunks.append(chunk)
+        
+        # Reconstruct full response from chunks
+        return self._reconstruct_response_from_chunks(chunks)
+    
+    async def _adapt_response_to_streaming(
+        self,
+        function: Callable,
+        call_kwargs: Dict[str, Any]
+    ) -> 'AsyncGenerator[Dict[str, Any], None]':
+        """Adapt non-streaming function to streaming by wrapping response as chunk
+        
+        Used when regular handoff is called in streaming mode.
+        
+        Args:
+            function: The handoff function to call
+            call_kwargs: Arguments to pass to function
+        
+        Yields:
+            Single streaming chunk containing full response
+        """
+        # Call function
+        response = await function(**call_kwargs)
+        
+        # Convert to streaming chunk and yield once
+        chunk = self._convert_response_to_streaming_chunk(response)
+        yield chunk
+    
     # Tool execution methods
     def _get_tool_function_by_name(self, function_name: str) -> Optional[Callable]:
         """Get a registered tool function by name, respecting external tool overrides"""
@@ -745,6 +1062,8 @@ class BaseAgent:
         else:
             self.logger.debug(f"🔧 Using existing tool_call_id '{tool_call_id}' for {function_name}")
         
+        # Finalization runs at end-of-loop or on exception
+
         try:
             # Parse function arguments
             function_args = json.loads(function_args_str)
@@ -851,6 +1170,10 @@ class BaseAgent:
             )
             set_context(context)
         
+        # Get the default handoff (first registered handoff) to reset to at end of turn
+        # Define this BEFORE the try block so it's available in the except block
+        default_handoff = self._registered_handoffs[0]['config'] if self._registered_handoffs else self.active_handoff
+        
         try:
             # Ensure all skills are initialized with agent reference
             await self._ensure_skills_initialized()
@@ -861,12 +1184,15 @@ class BaseAgent:
             # Merge external tools with agent tools
             all_tools = self._merge_tools(tools or [])
             
-            # Find primary LLM skill
-            llm_skill = self.skills.get("primary_llm")
-            if not llm_skill:
-                raise ValueError("No LLM skill configured")
+            # Ensure we have an active handoff (completion handler)
+            if not self.active_handoff:
+                raise ValueError(
+                    f"No handoff registered for agent '{self.name}'. "
+                    "Agent needs at least one skill with @handoff decorator or "
+                    "manual handoff registration via register_handoff()."
+                )
             
-            # Enhance messages with dynamic prompts before first LLM call
+            # Enhance messages with dynamic prompts before first handoff call
             enhanced_messages = await self._enhance_messages_with_prompts(messages, context)
             
             # Maintain conversation history for agentic loop
@@ -880,14 +1206,36 @@ class BaseAgent:
             while tool_iterations < max_tool_iterations:
                 tool_iterations += 1
                 
-                # Debug logging for LLM call
-                self.logger.debug(f"🚀 Calling LLM for agent '{self.name}' (iteration {tool_iterations}) with {len(all_tools)} tools")
+                # Debug logging for handoff call
+                handoff_name = self.active_handoff.target
+                self.logger.debug(f"🚀 Calling handoff '{handoff_name}' for agent '{self.name}' (iteration {tool_iterations}) with {len(all_tools)} tools")
                 
-                # Enhanced debugging: Log conversation history before LLM call
+                # Enhanced debugging: Log conversation history before handoff call
                 self.logger.debug(f"📝 ITERATION {tool_iterations} - Conversation history ({len(conversation_messages)} messages):")
                 for i, msg in enumerate(conversation_messages):
                     role = msg.get('role', 'unknown')
-                    content_preview = str(msg.get('content', ''))[:100] + ('...' if len(str(msg.get('content', ''))) > 100 else '')
+                    content = msg.get('content', '')
+                    
+                    # Truncate data URLs in content to avoid logging huge base64 strings
+                    if isinstance(content, list):
+                        # Multimodal content - check for image_url parts
+                        content_summary = []
+                        for part in content:
+                            if isinstance(part, dict) and part.get('type') == 'image_url':
+                                url = part.get('image_url', {}).get('url', '')
+                                if url.startswith('data:'):
+                                    content_summary.append('[data:image]')
+                                else:
+                                    content_summary.append(f'[image:{url[:50]}...]')
+                            elif isinstance(part, dict) and part.get('type') == 'text':
+                                text = part.get('text', '')[:50]
+                                content_summary.append(f'"{text}..."' if len(part.get('text', '')) > 50 else f'"{text}"')
+                            else:
+                                content_summary.append(str(part)[:30])
+                        content_preview = ', '.join(content_summary)
+                    else:
+                        content_preview = str(content)[:100] + ('...' if len(str(content)) > 100 else '')
+                    
                     tool_calls = msg.get('tool_calls', [])
                     tool_call_id = msg.get('tool_call_id', '')
                     
@@ -906,12 +1254,27 @@ class BaseAgent:
                     else:
                         self.logger.debug(f"  [{i}] {role.upper()}: {content_preview}")
                 
-                # Call LLM with current conversation history
-                response = await llm_skill.chat_completion(conversation_messages, tools=all_tools, stream=False)
+                # Execute before_llm_call hooks to allow message preprocessing
+                context.set('conversation_messages', conversation_messages)
+                context.set('tools', all_tools)
+                context = await self._execute_hooks("before_llm_call", context)
+                conversation_messages = context.get('conversation_messages', conversation_messages)
+                all_tools = context.get('tools', all_tools)
+                
+                # Call active handoff with current conversation history
+                response = await self._execute_handoff(
+                    self.active_handoff,
+                    conversation_messages,
+                    tools=all_tools,
+                    stream=False
+                )
                 
                 # Store LLM response in context for cost tracking
                 context.set('llm_response', response)
                 
+                # Execute after_llm_call hooks
+                context = await self._execute_hooks("after_llm_call", context)
+                
                 # Log LLM token usage
                 self._log_llm_usage(response, streaming=False)
                 
@@ -927,7 +1290,7 @@ class BaseAgent:
                         content = message.content if hasattr(message, 'content') else message.get('content', '')
                         tool_calls = message.tool_calls if hasattr(message, 'tool_calls') else message.get('tool_calls', [])
                         
-                        content_preview = str(content)[:100] + ('...' if len(str(content)) > 100 else '') if content else '[None]'
+                        content_preview = str(content)[:500] + ('...' if len(str(content)) > 500 else '') if content else '[None]'
                         self.logger.debug(f"  Content: {content_preview}")
                         self.logger.debug(f"  Finish reason: {finish_reason}")
                         
@@ -1083,6 +1446,40 @@ class BaseAgent:
                     # Execute tool
                     result = await self._execute_single_tool(tool_call)
                     
+                    # Check if tool result is a handoff request
+                    if isinstance(result.get('content', ''), str) and result.get('content', '').startswith("__HANDOFF_REQUEST__:"):
+                        target_name = result.get('content', '').split(":", 1)[1]
+                        self.logger.info(f"🔀 Dynamic handoff requested to: {target_name}")
+                        
+                        # Find the requested handoff
+                        requested_handoff = self.get_handoff_by_target(target_name)
+                        if not requested_handoff:
+                            # Invalid target - add error to conversation and continue
+                            error_msg = f"❌ Handoff target '{target_name}' not found"
+                            self.logger.warning(error_msg)
+                            tool_message = {
+                                "role": "tool",
+                                "tool_call_id": tool_call["id"],
+                                "content": error_msg
+                            }
+                            conversation_messages.append(tool_message)
+                            continue
+                        
+                        # Switch to the requested handoff - don't execute inline
+                        self.active_handoff = requested_handoff
+                        self.logger.info(f"🔀 Switching active handoff to: {target_name}")
+                        
+                        # Add tool result to conversation
+                        tool_message = {
+                            "role": "tool",
+                            "tool_call_id": tool_call["id"],
+                            "content": f"✓ Switching to {target_name}"
+                        }
+                        conversation_messages.append(tool_message)
+                        
+                        # Break from tool execution - the agentic loop will continue with new handoff
+                        break
+                    
                     # Enhanced debugging: Log tool result
                     result_content = result.get('content', '')
                     result_preview = result_content[:200] + ('...' if len(result_content) > 200 else '')
@@ -1124,11 +1521,26 @@ class BaseAgent:
             # Execute finalize_connection hooks
             context = await self._execute_hooks("finalize_connection", context)
             
+            # Reset to default handoff for next turn
+            if self.active_handoff != default_handoff and default_handoff is not None:
+                from_target = self.active_handoff.target if self.active_handoff else 'None'
+                to_target = default_handoff.target if default_handoff else 'None'
+                self.logger.info(f"🔄 Resetting active handoff from '{from_target}' to default '{to_target}'")
+                self.active_handoff = default_handoff
+            
             return response
             
         except Exception as e:
             # Handle errors and cleanup
             self.logger.exception(f"💥 Agent execution error agent='{self.name}' error='{e}'")
+            
+            # Reset to default handoff even on error
+            if self.active_handoff != default_handoff and default_handoff is not None:
+                from_target = self.active_handoff.target if self.active_handoff else 'None'
+                to_target = default_handoff.target if default_handoff else 'None'
+                self.logger.info(f"🔄 Resetting active handoff from '{from_target}' to default '{to_target}' (error path)")
+                self.active_handoff = default_handoff
+            
             await self._execute_hooks("finalize_connection", context)
             raise
     
@@ -1278,6 +1690,10 @@ class BaseAgent:
             )
             set_context(context)
         
+        # Get the default handoff (first registered handoff) to reset to at end of turn
+        # Define this BEFORE the try block so it's available in the except block
+        default_handoff = self._registered_handoffs[0]['config'] if self._registered_handoffs else self.active_handoff
+        
         try:
             # Ensure all skills are initialized with agent reference
             await self._ensure_skills_initialized()
@@ -1288,12 +1704,15 @@ class BaseAgent:
             # Merge external tools
             all_tools = self._merge_tools(tools or [])
             
-            # Find primary LLM skill
-            llm_skill = self.skills.get("primary_llm")
-            if not llm_skill:
-                raise ValueError("No LLM skill configured")
+            # Ensure we have an active handoff (completion handler)
+            if not self.active_handoff:
+                raise ValueError(
+                    f"No handoff registered for agent '{self.name}'. "
+                    "Agent needs at least one skill with @handoff decorator or "
+                    "manual handoff registration via register_handoff()."
+                )
             
-            # Enhance messages with dynamic prompts before first LLM call
+            # Enhance messages with dynamic prompts before first handoff call
             enhanced_messages = await self._enhance_messages_with_prompts(messages, context)
             
             # Maintain conversation history for agentic loop
@@ -1302,18 +1721,47 @@ class BaseAgent:
             # Agentic loop for streaming
             max_tool_iterations = 10
             tool_iterations = 0
+            pending_handoff_tag = None  # Store handoff tag to prepend to next iteration's first chunk
+            in_thinking_block = False  # Track if we're currently in a <think> block
+            pending_widget_html = None  # Store widget HTML from tool results to inject into next LLM response
+            first_chunk_of_iteration = False  # Track if this is the first chunk after tool calls (need space)
             
             while tool_iterations < max_tool_iterations:
                 tool_iterations += 1
+                # Mark that we need a space at the start of this iteration if it's not the first one
+                if tool_iterations > 1:
+                    first_chunk_of_iteration = True
                 
                 # Debug logging
-                self.logger.debug(f"🚀 Streaming LLM for agent '{self.name}' (iteration {tool_iterations}) with {len(all_tools)} tools")
+                handoff_name = self.active_handoff.target
+                self.logger.debug(f"🚀 Streaming handoff '{handoff_name}' for agent '{self.name}' (iteration {tool_iterations}) with {len(all_tools)} tools")
                 
-                # Enhanced debugging: Log conversation history before streaming LLM call
+                # Enhanced debugging: Log conversation history before streaming handoff call
                 self.logger.debug(f"📝 STREAMING ITERATION {tool_iterations} - Conversation history ({len(conversation_messages)} messages):")
                 for i, msg in enumerate(conversation_messages):
                     role = msg.get('role', 'unknown')
-                    content_preview = str(msg.get('content', ''))[:100] + ('...' if len(str(msg.get('content', ''))) > 100 else '')
+                    content = msg.get('content', '')
+                    
+                    # Truncate data URLs in content to avoid logging huge base64 strings
+                    if isinstance(content, list):
+                        # Multimodal content - check for image_url parts
+                        content_summary = []
+                        for part in content:
+                            if isinstance(part, dict) and part.get('type') == 'image_url':
+                                url = part.get('image_url', {}).get('url', '')
+                                if url.startswith('data:'):
+                                    content_summary.append('[data:image]')
+                                else:
+                                    content_summary.append(f'[image:{url[:50]}...]')
+                            elif isinstance(part, dict) and part.get('type') == 'text':
+                                text = part.get('text', '')[:50]
+                                content_summary.append(f'"{text}..."' if len(part.get('text', '')) > 50 else f'"{text}"')
+                            else:
+                                content_summary.append(str(part)[:30])
+                        content_preview = ', '.join(content_summary)
+                    else:
+                        content_preview = str(content)[:100] + ('...' if len(str(content)) > 100 else '')
+                    
                     tool_calls = msg.get('tool_calls', [])
                     tool_call_id = msg.get('tool_call_id', '')
                     
@@ -1332,13 +1780,30 @@ class BaseAgent:
                     else:
                         self.logger.debug(f"  [{i}] {role.upper()}: {content_preview}")
                 
-                # Stream from LLM and collect chunks
+                # Execute before_llm_call hooks to allow message preprocessing
+                context.set('conversation_messages', conversation_messages)
+                context.set('tools', all_tools)
+                context = await self._execute_hooks("before_llm_call", context)
+                conversation_messages = context.get('conversation_messages', conversation_messages)
+                all_tools = context.get('tools', all_tools)
+                
+                # Stream from active handoff and collect chunks
+                # NOTE: NO await! _execute_handoff returns generator directly in streaming mode
                 full_response_chunks = []
                 held_chunks = []  # Chunks with tool fragments
                 tool_calls_detected = False
+                waiting_for_usage_after_tool_calls = False  # Track if we're waiting for usage chunk
+                chunks_since_tool_calls = 0  # Safety counter to avoid waiting forever
                 chunk_count = 0
                 
-                async for chunk in llm_skill.chat_completion_stream(conversation_messages, tools=all_tools):
+                stream_gen = self._execute_handoff(
+                    self.active_handoff,
+                    conversation_messages,
+                    tools=all_tools,
+                    stream=True
+                )
+                
+                async for chunk in stream_gen:
                     chunk_count += 1
                     
                     # Execute on_chunk hooks
@@ -1357,34 +1822,169 @@ class BaseAgent:
                     
                     # Check if we have tool call fragments
                     if delta_tool_calls is not None:
+                        # Before holding tool call chunks, yield any text content in this chunk
+                        # This prevents cutting off mid-word/mid-sentence before tool calls
+                        if delta.get('content'):
+                            text_chunk = dict(modified_chunk)
+                            text_chunk['choices'] = [dict(choice)]
+                            text_chunk['choices'][0]['delta'] = {'content': delta['content']}
+                            self.logger.debug(f"💬 STREAMING: Yielding text content before tool call: {delta['content'][:50]}...")
+                            yield text_chunk
+                        
                         held_chunks.append(modified_chunk)
                         self.logger.debug(f"🔧 STREAMING: Tool call fragment in chunk #{chunk_count}")
                         continue  # Don't yield tool fragments
                     
                     # Check if tool calls are complete
-                    if finish_reason == "tool_calls":
+                    # IMPORTANT: Only break if we actually have tool call data accumulated
+                    if finish_reason == "tool_calls" and held_chunks:
                         tool_calls_detected = True
-                        self.logger.debug(f"🔧 STREAMING: Tool calls complete at chunk #{chunk_count}")
-                        break  # Exit streaming loop to process tools
+                        waiting_for_usage_after_tool_calls = True
+                        self.logger.debug(f"🔧 STREAMING: Tool calls complete at chunk #{chunk_count}, waiting for usage")
+                        # Don't break yet - continue to get usage chunk
+                        continue
+                    
+                    # If we're waiting for usage after tool_calls, check if this chunk has it
+                    if waiting_for_usage_after_tool_calls:
+                        chunks_since_tool_calls += 1
+                        # Log usage if present
+                        if modified_chunk.get('usage'):
+                            self.logger.debug(f"💰 Got usage chunk after tool_calls at chunk #{chunk_count}, logging and breaking")
+                            # Let the usage logging below handle it
+                        if modified_chunk.get('usage') or chunks_since_tool_calls > 5:
+                            # Break either when we get usage or after waiting too long
+                            if chunks_since_tool_calls > 5 and not modified_chunk.get('usage'):
+                                self.logger.debug(f"⚠️ No usage after {chunks_since_tool_calls} chunks, breaking anyway")
+                            break  # Exit streaming loop to process tools
+                        # Continue consuming chunks until we get usage or run out
+                        continue
                     
                     # Yield content chunks
                     # - In first iteration: yield all non-tool chunks for real-time display
                     # - In subsequent iterations: yield the final response after tools
                     if not delta_tool_calls:
+                        # Track thinking block state (ensure content is a string, not None)
+                        content = delta.get('content') or ''
+                        if '<think>' in content:
+                            in_thinking_block = True
+                        if '</think>' in content:
+                            in_thinking_block = False
+                        
+                        # Handle content modifications for first chunk of iteration
+                        if delta.get('content') and (pending_handoff_tag or pending_widget_html or first_chunk_of_iteration):
+                            modified_chunk = dict(modified_chunk)
+                            modified_chunk['choices'] = [dict(modified_chunk['choices'][0])]
+                            modified_chunk['choices'][0]['delta'] = dict(modified_chunk['choices'][0].get('delta', {}))
+                            
+                            # Prepend widget HTML first (if present), then handoff tag
+                            prepend_content = ''
+                            if pending_widget_html:
+                                prepend_content += pending_widget_html
+                                self.logger.debug(f"🎨 Injecting widget HTML into first chunk (len={len(pending_widget_html)})")
+                                pending_widget_html = None  # Clear after using
+                            if pending_handoff_tag:
+                                prepend_content += pending_handoff_tag
+                                self.logger.debug(f"🔀 Prepended handoff tag to first chunk: {pending_handoff_tag[:50]}")
+                                pending_handoff_tag = None  # Clear after using
+                            
+                            # Get the new content
+                            new_content = modified_chunk['choices'][0]['delta'].get('content', '')
+                            
+                            # If this is the first chunk of a new iteration (after tool calls), ensure space
+                            if first_chunk_of_iteration and new_content:
+                                # Add a space at the start if the content doesn't already start with whitespace
+                                if not new_content[0].isspace():
+                                    new_content = ' ' + new_content
+                                    self.logger.debug(f"➕ Added space to start of first chunk in iteration {tool_iterations}")
+                                first_chunk_of_iteration = False  # Clear flag after first chunk
+                            
+                            # Ensure proper spacing between prepended content and new content
+                            # Add a space if prepended content doesn't end with whitespace and new content doesn't start with whitespace
+                            if prepend_content and new_content and not prepend_content[-1].isspace() and not new_content[0].isspace():
+                                modified_chunk['choices'][0]['delta']['content'] = prepend_content + ' ' + new_content
+                            else:
+                                modified_chunk['choices'][0]['delta']['content'] = prepend_content + new_content
                         yield modified_chunk
                     
-                    # Log usage if final chunk
-                    if finish_reason and modified_chunk.get('usage'):
+                    # Log usage if present in chunk (LiteLLM sends usage in separate chunk)
+                    if modified_chunk.get('usage'):
+                        self.logger.debug(f"💰 Found usage in streaming chunk #{chunk_count}, logging to context")
                         self._log_llm_usage(modified_chunk, streaming=True)
                 
                 # If no tool calls detected, we're done
                 if not tool_calls_detected:
+                    # Check if we got any content at all
+                    total_content = ""
+                    for chunk in full_response_chunks:
+                        choice = chunk.get("choices", [{}])[0] if isinstance(chunk, dict) else {}
+                        delta = choice.get("delta", {}) if isinstance(choice, dict) else {}
+                        delta_content = delta.get("content", "")
+                        if delta_content:
+                            total_content += delta_content
+                    
+                    if not total_content and chunk_count > 0:
+                        self.logger.warning(f"⚠️ LLM generated {chunk_count} chunks but NO content! This may be a safety filter or empty response issue.")
+                        self.logger.warning(f"⚠️ First chunk details:")
+                        if full_response_chunks:
+                            first_chunk = full_response_chunks[0]
+                            self.logger.warning(f"   - Keys: {first_chunk.keys() if isinstance(first_chunk, dict) else 'not a dict'}")
+                            if isinstance(first_chunk, dict) and 'choices' in first_chunk:
+                                self.logger.warning(f"   - Choices: {first_chunk['choices']}")
+                        
+                        # CRITICAL FIX: Yield error message to client when LLM returns no content
+                        self.logger.warning(f"⚠️ Yielding error message to client due to empty LLM response")
+                        error_message = "I apologize, but I encountered an issue generating a response. This might be due to content filtering or a temporary problem. Please try rephrasing your request."
+                        
+                        # Get metadata from first chunk if available
+                        first_chunk = full_response_chunks[0] if full_response_chunks else {}
+                        
+                        # Yield error content chunk
+                        yield {
+                            "id": first_chunk.get("id", "error"),
+                            "created": first_chunk.get("created", 0),
+                            "model": first_chunk.get("model", "unknown"),
+                            "object": "chat.completion.chunk",
+                            "choices": [{
+                                "index": 0,
+                                "delta": {"role": "assistant", "content": error_message},
+                                "finish_reason": None
+                            }]
+                        }
+                        
+                        # Yield finish chunk
+                        yield {
+                            "id": first_chunk.get("id", "error"),
+                            "created": first_chunk.get("created", 0),
+                            "model": first_chunk.get("model", "unknown"),
+                            "object": "chat.completion.chunk",
+                            "choices": [{
+                                "index": 0,
+                                "delta": {},
+                                "finish_reason": "stop"
+                            }]
+                        }
+                    else:
+                        self.logger.debug(f"✅ Streaming finished with content (len={len(total_content)}) after {tool_iterations} iteration(s)")
+                    
+                    # CRITICAL FIX: Reconstruct and store LLM response for payment tracking
+                    # Even when there are no tool calls, we need to track LLM costs
+                    if full_response_chunks:
+                        final_response = self._reconstruct_response_from_chunks(full_response_chunks)
+                        context.set('llm_response', final_response)
+                        # NOTE: Usage is already logged at line 1682 when the usage chunk arrives
+                    
                     self.logger.debug(f"✅ Streaming finished (no tool calls) after {tool_iterations} iteration(s)")
                     break
                 
                 # Reconstruct response from chunks to process tool calls
                 full_response = self._reconstruct_response_from_chunks(full_response_chunks)
                 
+                # Store LLM response in context and execute after_llm_call hooks
+                context.set('llm_response', full_response)
+                # NOTE: Usage is already logged at line 1683 when the usage chunk arrives
+                context = await self._execute_hooks("after_llm_call", context)
+                full_response = context.get('llm_response', full_response)
+                
                 if not self._has_tool_calls(full_response):
                     # No tool calls after all - shouldn't happen but handle gracefully
                     self.logger.debug("🔧 STREAMING: No tool calls found in reconstructed response")
@@ -1457,10 +2057,8 @@ class BaseAgent:
                     final_chunk = self._convert_response_to_chunk(final_response)
                     yield final_chunk
                     
-                    # Execute cleanup hooks
-                    context = await self._execute_hooks("on_message", context)
-                    context = await self._execute_hooks("finalize_connection", context)
-                    return
+                    # Exit the loop; finalization runs after the loop
+                    break
                 
                 # All tools are internal - execute and continue loop
                 self.logger.debug(f"⚙️ Executing {len(internal_tools)} internal tool(s)")
@@ -1510,6 +2108,59 @@ class BaseAgent:
                     # Execute tool
                     result = await self._execute_single_tool(tool_call)
                     
+                    # Check if tool result is a handoff request
+                    if isinstance(result.get('content', ''), str) and result.get('content', '').startswith("__HANDOFF_REQUEST__:"):
+                        target_name = result.get('content', '').split(":", 1)[1]
+                        self.logger.info(f"🔀 Dynamic handoff requested to: {target_name}")
+                        
+                        # Find the requested handoff
+                        requested_handoff = self.get_handoff_by_target(target_name)
+                        if not requested_handoff:
+                            # Invalid target - yield error and continue
+                            error_msg = f"❌ Handoff target '{target_name}' not found"
+                            self.logger.warning(error_msg)
+                            yield {
+                                "choices": [{
+                                    "delta": {"content": error_msg},
+                                    "finish_reason": None
+                                }]
+                            }
+                            # Add to conversation and continue loop
+                            tool_message = {
+                                "role": "tool",
+                                "tool_call_id": tool_call["id"],
+                                "content": error_msg
+                            }
+                            conversation_messages.append(tool_message)
+                            continue
+                        
+                        # Switch to the requested handoff - don't execute inline
+                        self.active_handoff = requested_handoff
+                        self.logger.info(f"🔀 Switching active handoff to: {target_name}")
+                        
+                        # Build handoff tag with optional thinking closure
+                        handoff_tag_parts = []
+                        if in_thinking_block:
+                            self.logger.debug(f"🔀 Will close open thinking block before handoff")
+                            handoff_tag_parts.append("</think>\n\n")
+                            in_thinking_block = False
+                        handoff_tag_parts.append(f"<handoff>Handoff to {target_name}</handoff>\n\n")
+                        
+                        # Store handoff indicator to prepend to next iteration's first chunk
+                        pending_handoff_tag = "".join(handoff_tag_parts)
+                        self.logger.debug(f"🔀 Stored handoff indicator for next iteration: {pending_handoff_tag[:100]}")
+                        
+                        # Add tool result to conversation
+                        tool_message = {
+                            "role": "tool",
+                            "tool_call_id": tool_call["id"],
+                            "content": f"✓ Switching to {target_name}"
+                        }
+                        conversation_messages.append(tool_message)
+                        
+                        # Break from tool execution - the agentic loop will continue with new handoff
+                        break
+                    
                     # Enhanced debugging: Log streaming tool result
                     result_content = result.get('content', '')
                     result_preview = result_content[:200] + ('...' if len(result_content) > 200 else '')
@@ -1522,6 +2173,12 @@ class BaseAgent:
                     else:
                         self.logger.debug(f"✅ STREAMING ITERATION {tool_iterations} - Tool call ID matches: {tc_id}")
                     
+                    # Check if result contains widget HTML - store it to prepend to next LLM response
+                    if result_content and '<widget' in result_content:
+                        self.logger.debug(f"🎨 Widget detected in tool result (len={len(result_content)}), will inject into next LLM response")
+                        # Store widget HTML to prepend to first chunk of next iteration
+                        pending_widget_html = f"\n\n{result_content}\n\n"
+                    
                     # Add result to conversation
                     conversation_messages.append(result)
                     
@@ -1535,13 +2192,40 @@ class BaseAgent:
             if tool_iterations >= max_tool_iterations:
                 self.logger.warning(f"⚠️ Reached max tool iterations ({max_tool_iterations})")
             
-            # Execute final hooks
-            context = await self._execute_hooks("on_message", context)
-            context = await self._execute_hooks("finalize_connection", context)
+            # Finalize after breaking out (normal end)
+            self.logger.debug("🔚 Executing finalization hooks")
+            try:
+                context = await self._execute_hooks("on_message", context)
+                context = await self._execute_hooks("finalize_connection", context)
+                self.logger.debug("✅ Finalization hooks completed")
+            except Exception as hook_error:
+                self.logger.error(f"Error executing finalization hooks: {hook_error}")
+            
+            # Reset to default handoff for next turn (always, even if hooks failed)
+            if self.active_handoff != default_handoff and default_handoff is not None:
+                from_target = self.active_handoff.target if self.active_handoff else 'None'
+                to_target = default_handoff.target if default_handoff else 'None'
+                self.logger.info(f"🔄 Resetting active handoff from '{from_target}' to default '{to_target}'")
+                self.active_handoff = default_handoff
             
         except Exception as e:
             self.logger.exception(f"💥 Streaming execution error agent='{self.name}' error='{e}'")
-            await self._execute_hooks("finalize_connection", context)
+            # Finalize even on error
+            self.logger.debug("🔚 Executing finalization hooks (error path)")
+            try:
+                context = await self._execute_hooks("on_message", context)
+                context = await self._execute_hooks("finalize_connection", context)
+                self.logger.debug("✅ Finalization hooks completed")
+            except Exception as hook_error:
+                self.logger.error(f"Error executing finalization hooks: {hook_error}")
+            
+            # Reset to default handoff for next turn (always, even on error)
+            if self.active_handoff != default_handoff and default_handoff is not None:
+                from_target = self.active_handoff.target if self.active_handoff else 'None'
+                to_target = default_handoff.target if default_handoff else 'None'
+                self.logger.info(f"🔄 Resetting active handoff from '{from_target}' to default '{to_target}' (error path)")
+                self.active_handoff = default_handoff
+            
             raise
     
     def _reconstruct_response_from_chunks(self, chunks: List[Dict[str, Any]]) -> Dict[str, Any]:
@@ -1561,15 +2245,34 @@ class BaseAgent:
         # Reconstruct from streaming delta chunks
         logger.debug(f"🔧 RECONSTRUCTION: Reconstructing from {len(chunks)} delta chunks")
         
-        # Accumulate streaming tool call data
+        # Accumulate streaming data (both content and tool calls)
         accumulated_tool_calls = {}
+        accumulated_content = []
+        role = "assistant"
         final_chunk = chunks[-1] if chunks else {}
+        finish_reason = None
         
         for i, chunk in enumerate(chunks):
             choice = chunk.get("choices", [{}])[0]
             delta = choice.get("delta", {}) if isinstance(choice, dict) else {}
             delta_tool_calls = delta.get("tool_calls") if isinstance(delta, dict) else None
             
+            # Accumulate content from deltas
+            delta_content = delta.get("content") if isinstance(delta, dict) else None
+            if delta_content:
+                accumulated_content.append(delta_content)
+            
+            # Capture role if present
+            delta_role = delta.get("role") if isinstance(delta, dict) else None
+            if delta_role:
+                role = delta_role
+            
+            # Capture finish_reason
+            choice_finish = choice.get("finish_reason") if isinstance(choice, dict) else None
+            if choice_finish:
+                finish_reason = choice_finish
+            
+            # Accumulate tool calls
             if delta_tool_calls:
                 for tool_call in delta_tool_calls:
                     tool_index = tool_call.get("index", 0)
@@ -1633,8 +2336,31 @@ class BaseAgent:
             logger.debug(f"🔧 RECONSTRUCTION: Reconstructed {len(tool_calls_list)} tool calls")
             return reconstructed
         
-        # No tool calls found, return the last chunk
-        logger.debug(f"🔧 RECONSTRUCTION: No tool calls found, returning last chunk")
+        # No tool calls found - check if we have content to return
+        content_text = "".join(accumulated_content) if accumulated_content else None
+        
+        if content_text or finish_reason:
+            # Create a proper response with message format
+            logger.debug(f"🔧 RECONSTRUCTION: No tool calls, reconstructing content response (content_len={len(content_text) if content_text else 0})")
+            reconstructed = {
+                "id": final_chunk.get("id", "chatcmpl-reconstructed"),
+                "created": final_chunk.get("created", 0),
+                "model": final_chunk.get("model", "unknown"),
+                "object": "chat.completion",
+                "choices": [{
+                    "index": 0,
+                    "finish_reason": finish_reason or "stop",
+                    "message": {
+                        "role": role,
+                        "content": content_text
+                    }
+                }],
+                "usage": final_chunk.get("usage", {})
+            }
+            return reconstructed
+        
+        # No content and no tool calls - return last chunk as-is (shouldn't happen often)
+        logger.warning(f"🔧 RECONSTRUCTION: No tool calls and no content found, returning last chunk as-is")
         return final_chunk
     
     def _convert_response_to_chunk(self, response: Dict[str, Any]) -> Dict[str, Any]:
@@ -1694,6 +2420,32 @@ class BaseAgent:
         except Exception:
             return
     
+    def _is_browser_request(self, context=None) -> bool:
+        """Check if the request came from a browser based on User-Agent header
+        
+        Args:
+            context: Optional context object (uses get_context() if not provided)
+        
+        Returns:
+            True if User-Agent contains browser markers (Mozilla, Chrome, Safari, Firefox)
+        """
+        if context is None:
+            context = get_context()
+        
+        if not context or not hasattr(context, 'request') or not context.request:
+            self.logger.debug("🌐 No context or request available for browser detection")
+            return False
+        
+        user_agent = context.request.headers.get('user-agent', '').lower() if hasattr(context.request, 'headers') else ''
+        
+        # Check for common browser User-Agent markers
+        browser_markers = ['mozilla', 'chrome', 'safari', 'firefox', 'edge']
+        is_browser = any(marker in user_agent for marker in browser_markers)
+        
+        self.logger.debug(f"🌐 User-Agent: {user_agent[:100] if user_agent else '(empty)'} -> is_browser: {is_browser}")
+        
+        return is_browser
+    
     def _merge_tools(self, external_tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """Merge external tools with agent tools - external tools have priority"""
         # Clear previous overrides (fresh for each request)
@@ -1703,8 +2455,50 @@ class BaseAgent:
         context = get_context()
         auth_scope = context.auth_scope if context else "all"
         
+        # Get all agent tools (now includes widgets since they're also registered as tools)
         agent_tools = self.get_tools_for_scope(auth_scope)
-        agent_tool_defs = [tool['definition'] for tool in agent_tools if tool.get('definition')]
+        
+        # Get widget names for filtering
+        widget_names = {w['name'] for w in self._registered_widgets}
+        
+        # Filter widgets out of regular tools list (we'll add them conditionally below)
+        agent_tools_no_widgets = [tool for tool in agent_tools if tool.get('name') not in widget_names]
+        agent_tool_defs = [tool['definition'] for tool in agent_tools_no_widgets if tool.get('definition')]
+        
+        # Add widgets only for browser requests
+        is_browser = self._is_browser_request(context)
+        self.logger.debug(f"🌐 Browser request check: {is_browser}")
+        if is_browser:
+            agent_widgets = self.get_all_widgets()
+            self.logger.debug(f"🎨 Found {len(agent_widgets)} registered widgets")
+            scope_hierarchy = {"admin": 3, "owner": 2, "all": 1}
+            user_level = scope_hierarchy.get(auth_scope, 1)
+            
+            # Convert widget configs to tool-like definitions for LLM context
+            widgets_added = 0
+            for widget in agent_widgets:
+                # Filter by scope (similar to tools)
+                widget_scope = widget.get('scope', 'all')
+                scope_matched = False
+                
+                if isinstance(widget_scope, list):
+                    # If scope is a list, check if user scope is in it
+                    if auth_scope in widget_scope or 'all' in widget_scope:
+                        scope_matched = True
+                else:
+                    # Single scope - check hierarchy
+                    required_level = scope_hierarchy.get(widget_scope, 1)
+                    if user_level >= required_level:
+                        scope_matched = True
+                
+                if scope_matched:
+                    widget_def = widget.get('definition')
+                    if widget_def:
+                        agent_tool_defs.append(widget_def)
+                        widgets_added += 1
+            
+            if widgets_added > 0:
+                self.logger.debug(f"🎨 Added {widgets_added} widgets for browser request")
         
         # Debug logging
         logger = self.logger
@@ -1808,26 +2602,28 @@ class BaseAgent:
         
         return decorator
     
-    def handoff(self, name: Optional[str] = None, handoff_type: str = "agent", 
-                description: Optional[str] = None, scope: Union[str, List[str]] = "all"):
+    def handoff(self, name: Optional[str] = None, prompt: Optional[str] = None, 
+                scope: Union[str, List[str]] = "all", priority: int = 50):
         """Register a handoff directly on the agent instance
         
         Usage:
-            @agent.handoff(handoff_type="agent")
-            async def escalate_to_supervisor(issue: str):
-                return HandoffResult(result=f"Escalated: {issue}", handoff_type="agent")
+            @agent.handoff(name="specialist", prompt="Hand off to specialist")
+            async def escalate_to_supervisor(messages, tools=None, **kwargs):
+                return {"choices": [{"message": {"role": "assistant", "content": "Escalated"}}]}
         """
         def decorator(func: Callable) -> Callable:
             from ..tools.decorators import handoff as handoff_decorator
-            decorated_func = handoff_decorator(name=name, handoff_type=handoff_type, 
-                                             description=description, scope=scope)(func)
+            decorated_func = handoff_decorator(name=name, prompt=prompt, scope=scope, priority=priority)(func)
             handoff_config = Handoff(
                 target=getattr(decorated_func, '_handoff_name', decorated_func.__name__),
-                handoff_type=getattr(decorated_func, '_handoff_type', 'agent'),
-                description=getattr(decorated_func, '_handoff_description', ''),
+                description=getattr(decorated_func, '_handoff_prompt', ''),
                 scope=getattr(decorated_func, '_handoff_scope', scope)
             )
-            handoff_config.metadata = {'function': decorated_func}
+            handoff_config.metadata = {
+                'function': decorated_func,
+                'priority': getattr(decorated_func, '_handoff_priority', priority),
+                'is_generator': getattr(decorated_func, '_handoff_is_generator', False)
+            }
             self.register_handoff(handoff_config, source="agent")
             return decorated_func