devduck 0.7.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

devduck/tools/speech_to_speech.py

@@ -0,0 +1,750 @@
+"""Real-time speech-to-speech bidirectional streaming tool for DevDuck.
+
+Provides background speech-to-speech conversation capability using Strands
+experimental bidirectional streaming with full model provider support, tool
+inheritance, and comprehensive configuration options.
+
+This tool creates isolated bidirectional agent sessions that run in background
+threads, enabling real-time voice conversations with AI models while the parent
+agent remains responsive.
+
+Key Features:
+- **Background Execution:** Runs in separate thread - parent agent stays responsive
+- **Real-Time Audio:** Microphone input and speaker output with pyaudio
+- **Tool Inheritance:** Automatically inherits ALL tools from parent agent
+- **System Prompt Inheritance:** Combines parent agent's prompt with custom prompts
+- **Multiple Providers:** Nova Sonic, OpenAI Realtime API, Gemini Live
+- **Full Configuration:** Per-provider custom settings and parameters
+- **Environment API Keys:** Auto-loads API keys from environment variables
+- **Built-in Stop:** Uses SDK's stop_conversation tool for graceful termination
+- **Auto-Interruption:** Built-in VAD for natural conversation flow
+- **Conversation History:** Automatically saves transcripts to files
+
+Supported Providers:
+-------------------
+1. **Nova Sonic (AWS Bedrock):**
+   - Region: us-east-1, eu-north-1, ap-northeast-1
+   - Model: amazon.nova-2-sonic-v1:0 (configurable)
+   - Voices: tiffany, matthew, amy, ambre, florian, beatrice, lorenzo, greta, lennart, lupe, carlos
+   - Requires AWS credentials (boto3 credential chain)
+
+2. **OpenAI Realtime API:**
+   - Models: gpt-realtime, gpt-4o-realtime-preview (configurable)
+   - Requires OPENAI_API_KEY environment variable
+   - Custom session config support
+
+3. **Gemini Live:**
+   - Model: gemini-2.5-flash-native-audio-preview-09-2025 (configurable)
+   - Requires GOOGLE_API_KEY or GEMINI_API_KEY environment variable
+   - Live config customization
+
+Configuration Examples:
+----------------------
+# Nova Sonic with custom voice
+model_settings = {
+    "provider_config": {
+        "audio": {"voice": "matthew"}
+    },
+    "client_config": {"region": "us-east-1"}
+}
+
+# OpenAI Realtime with custom model
+model_settings = {
+    "model_id": "gpt-4o-realtime-preview",
+    "provider_config": {
+        "audio": {"voice": "coral"}
+    }
+}
+
+# Gemini Live with custom voice
+model_settings = {
+    "model_id": "gemini-2.5-flash-native-audio-preview-09-2025",
+    "provider_config": {
+        "audio": {"voice": "Kore"}
+    }
+}
+"""
+
+import os
+import asyncio
+import tempfile
+import json
+import logging
+import threading
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from strands import tool
+from strands.experimental.bidi.agent.agent import BidiAgent
+from strands.experimental.bidi.models.gemini_live import BidiGeminiLiveModel
+from strands.experimental.bidi.models.nova_sonic import BidiNovaSonicModel
+from strands.experimental.bidi.models.openai_realtime import BidiOpenAIRealtimeModel
+from strands.experimental.bidi.io.audio import BidiAudioIO
+
+logger = logging.getLogger(__name__)
+
+# Global session tracking
+_active_sessions = {}
+_session_lock = threading.Lock()
+
+# Session history storage location
+BASE_DIR = Path(os.getenv("DEVDUCK_HOME", tempfile.gettempdir()))
+HISTORY_DIR = BASE_DIR / ".devduck" / "speech_sessions"
+HISTORY_DIR.mkdir(parents=True, exist_ok=True)
+
+
+class SpeechSession:
+    """Manages a speech-to-speech conversation session with full lifecycle management."""
+
+    def __init__(
+        self,
+        session_id: str,
+        agent: BidiAgent,
+    ):
+        """Initialize speech session.
+
+        Args:
+            session_id: Unique session identifier
+            agent: BidiAgent instance
+        """
+        self.session_id = session_id
+        self.agent = agent
+        self.active = False
+        self.thread = None
+        self.loop = None
+        self.history_file = HISTORY_DIR / f"{session_id}.json"
+
+    def start(self) -> None:
+        """Start the speech session in background thread."""
+        if self.active:
+            raise ValueError("Session already active")
+
+        self.active = True
+        self.thread = threading.Thread(target=self._run_session, daemon=True)
+        self.thread.start()
+
+    def stop(self) -> None:
+        """Stop the speech session and cleanup resources."""
+        if not self.active:
+            return
+
+        self.active = False
+
+        # Stop the bidi agent using its event loop
+        if self.loop and self.loop.is_running():
+            # Schedule stop in the session's event loop and wait for it
+            future = asyncio.run_coroutine_threadsafe(self.agent.stop(), self.loop)
+            try:
+                # Wait up to 3 seconds for stop to complete
+                future.result(timeout=3.0)
+                logger.info(
+                    f"Successfully stopped bidi agent for session {self.session_id}"
+                )
+            except Exception as e:
+                logger.warning(f"Error stopping bidi agent: {e}")
+
+        if self.thread:
+            self.thread.join(timeout=5.0)
+
+        # Save conversation history after session ends
+        self._save_history()
+
+    def _save_history(self) -> None:
+        """Save conversation history to file."""
+        try:
+            history_data = {
+                "session_id": self.session_id,
+                "timestamp": datetime.now().isoformat(),
+                "messages": self.agent.messages,
+            }
+
+            with open(self.history_file, "w") as f:
+                json.dump(history_data, f, indent=2)
+
+            logger.info(f"Saved conversation history to {self.history_file}")
+        except Exception as e:
+            logger.error(f"Failed to save history: {e}")
+
+    def _run_session(self) -> None:
+        """Main session runner in background thread."""
+        try:
+            # Create event loop for this thread
+            self.loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self.loop)
+
+            # Run the async session
+            self.loop.run_until_complete(self._async_session())
+        except Exception as e:
+            error_msg = f"Session error: {e}\n{traceback.format_exc()}"
+            logger.debug(error_msg)
+            print(f"\n🦆 Session error: {e}")
+        finally:
+            if self.loop:
+                self.loop.close()
+
+    async def _async_session(self) -> None:
+        """Async session management using BidiAudioIO."""
+        try:
+            # Create audio I/O
+            audio_io = BidiAudioIO()
+
+            # Run agent with audio I/O
+            await self.agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()])
+
+        except Exception as e:
+            logger.debug(f"Async session error: {e}\n{traceback.format_exc()}")
+
+
+@tool
+def speech_to_speech(
+    action: str,
+    provider: str = "novasonic",
+    system_prompt: Optional[str] = None,
+    session_id: Optional[str] = None,
+    model_settings: Optional[Dict[str, Any]] = None,
+    tools: Optional[List[str]] = None,
+    agent: Optional[Any] = None,
+    load_history_from: Optional[str] = None,
+) -> str:
+    """Start, stop, or manage speech-to-speech conversations.
+
+    Creates a background bidirectional streaming session for real-time voice
+    conversations with AI. Supports full model configuration, tool inheritance,
+    and multiple model providers with custom settings.
+
+    Args:
+        action: Action to perform:
+            - "start": Start new speech session
+            - "stop": Stop session(s)
+            - "status": Get session status
+            - "list_history": List saved conversation histories
+            - "read_history": Read a specific conversation history
+        provider: Model provider to use:
+            - "novasonic": AWS Bedrock Nova Sonic
+            - "openai": OpenAI Realtime API
+            - "gemini_live": Google Gemini Live
+        system_prompt: Custom system prompt for the agent. This will be appended
+            to the parent agent's system prompt (if available). If not provided,
+            uses default prompt that encourages tool usage.
+        session_id: Session identifier:
+            - For "start": Custom ID (auto-generated if not provided)
+            - For "stop": Specific session to stop (stops all if not provided)
+            - For "read_history": Session ID to read history from
+            - For "status": Not used
+        model_settings: Provider-specific configuration dictionary. Structure:
+            {
+                "model_id": "model-name",
+                "provider_config": {
+                    "audio": {"voice": "voice-name"},
+                    "inference": {...}
+                },
+                "client_config": {
+                    "region": "us-east-1",  # for Nova Sonic
+                    "api_key": "key"  # for OpenAI/Gemini (auto-loaded from env if not provided)
+                }
+            }
+
+            Examples:
+            - Nova Sonic with custom voice:
+              {"provider_config": {"audio": {"voice": "matthew"}}}
+
+            - OpenAI with custom model:
+              {"model_id": "gpt-4o-realtime-preview"}
+
+            - Gemini with custom voice:
+              {"provider_config": {"audio": {"voice": "Kore"}}}
+        tools: List of tool names to make available. If not provided,
+            inherits ALL tools from parent agent.
+        agent: Parent agent (automatically passed by Strands framework)
+        load_history_from: Optional session ID to load conversation history from
+            when starting a new session (provides context continuity)
+
+    Returns:
+        str: Status message with session details or error information
+
+    Environment Variables:
+        - OPENAI_API_KEY: Required for OpenAI Realtime API (if not in model_settings)
+        - GOOGLE_API_KEY or GEMINI_API_KEY: Required for Gemini Live (if not in model_settings)
+        - AWS credentials: Required for Nova Sonic (boto3 default credential chain)
+
+    Nova Sonic Voice Options:
+        - English (US): tiffany (feminine), matthew (masculine)
+        - English (GB): amy (feminine)
+        - French: ambre (feminine), florian (masculine)
+        - Italian: beatrice (feminine), lorenzo (masculine)
+        - German: greta (feminine), lennart (masculine)
+        - Spanish: lupe (feminine), carlos (masculine)
+    """
+
+    if action == "start":
+        return _start_speech_session(
+            provider,
+            system_prompt,
+            session_id,
+            model_settings,
+            tools,
+            agent,
+            load_history_from,
+        )
+    elif action == "stop":
+        return _stop_speech_session(session_id)
+    elif action == "status":
+        return _get_session_status()
+    elif action == "list_history":
+        return _list_conversation_histories()
+    elif action == "read_history":
+        return _read_conversation_history(session_id)
+    else:
+        return f"Unknown action: {action}"
+
+
+def _create_speech_session_tool(current_session_id: str, bidi_agent: BidiAgent):
+    """Create a speech_session tool for the given session.
+
+    This tool is attached to each bidi agent instance to allow session management
+    from within the speech conversation.
+    """
+
+    @tool
+    def speech_session(
+        action: str,
+        session_id: Optional[str] = None,
+    ) -> str:
+        """Manage the current speech conversation session.
+
+        Actions:
+        - "stop": Stop the current conversation
+        - "status": Get session status
+        - "list_history": List all saved conversation histories
+        - "read_history": Read a specific conversation history
+
+        Args:
+            action: Action to perform
+            session_id: Session ID (required for read_history)
+
+        Returns:
+            Status message
+        """
+        if action == "stop":
+            try:
+                # Stop the session (which will call bidi_agent.stop() properly)
+                with _session_lock:
+                    if current_session_id in _active_sessions:
+                        _active_sessions[current_session_id].stop()
+                        del _active_sessions[current_session_id]
+                        return "Conversation stopped successfully."
+                    else:
+                        return f"Session {current_session_id} not found in active sessions."
+            except Exception as e:
+                logger.error(f"Error stopping conversation: {e}")
+                return f"Error stopping conversation: {e}"
+
+        elif action == "status":
+            return _get_session_status()
+
+        elif action == "list_history":
+            return _list_conversation_histories()
+
+        elif action == "read_history":
+            return _read_conversation_history(session_id)
+
+        else:
+            return f"Unknown action: {action}. Available: stop, status, list_history, read_history"
+
+    return speech_session
+
+
+def _start_speech_session(
+    provider: str,
+    system_prompt: Optional[str],
+    session_id: Optional[str],
+    model_settings: Optional[Dict[str, Any]],
+    tool_names: Optional[List[str]],
+    parent_agent: Optional[Any],
+    load_history_from: Optional[str],
+) -> str:
+    """Start a speech-to-speech session with full configuration support."""
+    try:
+        # Generate session ID if not provided
+        if not session_id:
+            session_id = f"speech_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+        # Check if session already exists
+        with _session_lock:
+            if session_id in _active_sessions:
+                return f"❌ Session already exists: {session_id}"
+
+        # Create model based on provider with custom settings
+        model_settings = model_settings or {}
+        model_info = f"{provider}"
+
+        try:
+            if provider == "novasonic":
+                # Nova Sonic only available in: us-east-1, eu-north-1, ap-northeast-1
+                default_settings = {
+                    "model_id": "amazon.nova-2-sonic-v1:0",
+                    "provider_config": {
+                        "audio": {
+                            "voice": "tiffany",
+                        },
+                    },
+                    "client_config": {"region": "us-east-1"},
+                }
+
+                # Merge user settings with defaults (deep merge for nested dicts)
+                if model_settings:
+                    # Merge top-level keys
+                    for key, value in model_settings.items():
+                        if (
+                            key in default_settings
+                            and isinstance(default_settings[key], dict)
+                            and isinstance(value, dict)
+                        ):
+                            # Deep merge for nested dicts
+                            default_settings[key].update(value)
+                        else:
+                            default_settings[key] = value
+
+                model = BidiNovaSonicModel(**default_settings)
+                region = default_settings.get("client_config", {}).get(
+                    "region", "us-east-1"
+                )
+                voice = (
+                    default_settings.get("provider_config", {})
+                    .get("audio", {})
+                    .get("voice", "tiffany")
+                )
+                model_info = f"Nova Sonic ({region}, voice: {voice})"
+
+            elif provider == "openai":
+                # Read API key from environment if not provided in model_settings
+                default_settings = {
+                    "model_id": "gpt-realtime",
+                    "client_config": {
+                        "api_key": os.getenv("OPENAI_API_KEY"),
+                    },
+                }
+
+                # Merge user settings
+                if model_settings:
+                    for key, value in model_settings.items():
+                        if (
+                            key in default_settings
+                            and isinstance(default_settings[key], dict)
+                            and isinstance(value, dict)
+                        ):
+                            default_settings[key].update(value)
+                        else:
+                            default_settings[key] = value
+
+                # Check if API key is available
+                if not default_settings.get("client_config", {}).get("api_key"):
+                    return "❌ OpenAI API key not found. Set OPENAI_API_KEY environment variable or provide in model_settings['client_config']['api_key']"
+
+                model = BidiOpenAIRealtimeModel(**default_settings)
+                model_id = default_settings.get("model_id", "gpt-realtime")
+                voice = (
+                    default_settings.get("provider_config", {})
+                    .get("audio", {})
+                    .get("voice", "default")
+                )
+                model_info = f"OpenAI Realtime ({model_id}, voice: {voice})"
+
+            elif provider == "gemini_live":
+                # Read API key from environment if not provided in model_settings
+                api_key = os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
+
+                default_settings = {
+                    "model_id": "gemini-2.5-flash-native-audio-preview-09-2025",
+                    "client_config": {
+                        "api_key": api_key,
+                    },
+                }
+
+                # Merge user settings
+                if model_settings:
+                    for key, value in model_settings.items():
+                        if (
+                            key in default_settings
+                            and isinstance(default_settings[key], dict)
+                            and isinstance(value, dict)
+                        ):
+                            default_settings[key].update(value)
+                        else:
+                            default_settings[key] = value
+
+                # Check if API key is available
+                if not default_settings.get("client_config", {}).get("api_key"):
+                    return "❌ Google/Gemini API key not found. Set GOOGLE_API_KEY or GEMINI_API_KEY environment variable or provide in model_settings['client_config']['api_key']"
+
+                model = BidiGeminiLiveModel(**default_settings)
+                model_id = default_settings.get("model_id", "gemini-2.5-flash-live")
+                voice = (
+                    default_settings.get("provider_config", {})
+                    .get("audio", {})
+                    .get("voice", "default")
+                )
+                model_info = f"Gemini Live ({model_id}, voice: {voice})"
+
+            else:
+                return f"❌ Unknown provider: {provider}. Supported: novasonic, openai, gemini_live"
+        except Exception as e:
+            return f"❌ Error creating {provider} model: {e}\n\nCheck your configuration and credentials."
+
+        # Get parent agent's tools
+        tools = []
+        inherited_count = 0
+
+        if parent_agent and hasattr(parent_agent, "tool_registry"):
+            try:
+                # Get all tool functions from parent agent's registry
+                registry_dict = parent_agent.tool_registry.registry
+
+                # If specific tools requested, filter; otherwise inherit all
+                if tool_names:
+                    # User specified tool names - only include those
+                    for tool_name in tool_names:
+                        if tool_name not in ["speech_to_speech"]:
+                            tool_func = registry_dict.get(tool_name)
+                            if tool_func:
+                                tools.append(tool_func)
+                                inherited_count += 1
+                            else:
+                                logger.warning(
+                                    f"Tool '{tool_name}' not found in parent agent's registry"
+                                )
+                else:
+                    # No specific tools - inherit all except excluded
+                    for tool_name, tool_func in registry_dict.items():
+                        if tool_name not in ["speech_to_speech"]:
+                            tools.append(tool_func)
+                            inherited_count += 1
+
+            except Exception as e:
+                logger.warning(f"Could not inherit tools from parent agent: {e}")
+
+        # Load conversation history if requested
+        messages = None
+        if load_history_from:
+            history_file = HISTORY_DIR / f"{load_history_from}.json"
+            if history_file.exists():
+                try:
+                    with open(history_file, "r") as f:
+                        history_data = json.load(f)
+                        messages = history_data.get("messages", [])
+                        logger.info(
+                            f"Loaded {len(messages)} messages from {load_history_from}"
+                        )
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to load history from {load_history_from}: {e}"
+                    )
+
+        # Build system prompt: parent prompt + custom prompt
+        final_system_prompt = ""
+
+        # Get parent agent's system prompt if available
+        if parent_agent and hasattr(parent_agent, "system_prompt"):
+            parent_prompt = parent_agent.system_prompt or ""
+            if parent_prompt:
+                final_system_prompt = parent_prompt
+
+        # Add custom system prompt
+        if system_prompt:
+            if final_system_prompt:
+                final_system_prompt = f"{final_system_prompt}\n\n{system_prompt}"
+            else:
+                final_system_prompt = system_prompt
+
+        # Use default system prompt if nothing provided
+        if not final_system_prompt:
+            final_system_prompt = """You are a helpful AI assistant with access to powerful tools.
+- To stop the conversation → Use speech_session tool with action="stop"
+Keep your voice responses brief and natural."""
+
+        # Create bidirectional agent with inherited tools (speech_session will be added after)
+        bidi_agent = BidiAgent(
+            model=model,
+            tools=tools,
+            system_prompt=final_system_prompt,
+            messages=messages,
+        )
+
+        # Create and add speech_session tool to agent's registry
+        # This allows user to manage the session from within the conversation
+        speech_session_tool = _create_speech_session_tool(session_id, bidi_agent)
+        bidi_agent.tool_registry.registry["speech_session"] = speech_session_tool
+
+        # Create and start session
+        session = SpeechSession(
+            session_id=session_id,
+            agent=bidi_agent,
+        )
+
+        session.start()
+
+        # Register session
+        with _session_lock:
+            _active_sessions[session_id] = session
+
+        # Build settings summary
+        settings_summary = ""
+        if model_settings:
+            settings_lines = []
+            for key, value in model_settings.items():
+                if key not in ["api_key", "secret"]:  # Hide sensitive data
+                    settings_lines.append(f"  - {key}: {value}")
+            if settings_lines:
+                settings_summary = "\n**Model Settings:**\n" + "\n".join(settings_lines)
+
+        # Add history info if loaded
+        history_info = ""
+        if messages:
+            history_info = f"\n**Loaded History:** {len(messages)} messages from session '{load_history_from}'"
+
+        return f"""✅ Speech session started!
+
+**Session ID:** {session_id}
+**Provider:** {model_info}
+**Tools:** {inherited_count + 1} tools available (includes speech_session){settings_summary}{history_info}
+**History Location:** {session.history_file}
+
+The session is running in the background. Speak into your microphone to interact!
+
+**To manage the session during conversation:**
+- Stop: Say "stop the session" or "end conversation"
+- Check status: Say "check session status"  
+- List histories: Say "list conversation histories"
+
+**External Commands:**
+- Check status: speech_to_speech(action="status")
+- Stop session: speech_to_speech(action="stop", session_id="{session_id}")
+- List histories: speech_to_speech(action="list_history")
+- Read history: speech_to_speech(action="read_history", session_id="{session_id}")
+"""
+
+    except Exception as e:
+        logger.error(f"Error starting speech session: {e}\n{traceback.format_exc()}")
+        return f"❌ Error starting session: {e}\n\nCheck logs for details."
+
+
+def _stop_speech_session(session_id: Optional[str]) -> str:
+    """Stop a speech session."""
+    with _session_lock:
+        if not session_id:
+            if not _active_sessions:
+                return "❌ No active sessions"
+            # Stop all sessions
+            session_ids = list(_active_sessions.keys())
+            for sid in session_ids:
+                _active_sessions[sid].stop()
+                del _active_sessions[sid]
+            return f"✅ Stopped {len(session_ids)} session(s)"
+
+        if session_id not in _active_sessions:
+            return f"❌ Session not found: {session_id}"
+
+        session = _active_sessions[session_id]
+        session.stop()
+        del _active_sessions[session_id]
+
+        return f"✅ Session stopped: {session_id}"
+
+
+def _get_session_status() -> str:
+    """Get status of all active sessions."""
+    with _session_lock:
+        if not _active_sessions:
+            return "No active speech sessions"
+
+        status_lines = ["**Active Speech Sessions:**\n"]
+        for session_id, session in _active_sessions.items():
+            status_lines.append(
+                f"- **{session_id}**\n"
+                f"  - Active: {'✅' if session.active else '❌'}\n"
+                f"  - History File: {session.history_file}"
+            )
+
+        return "\n".join(status_lines)
+
+
+def _list_conversation_histories() -> str:
+    """List all saved conversation histories."""
+    history_files = sorted(
+        HISTORY_DIR.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True
+    )
+
+    if not history_files:
+        return f"No saved conversation histories found in {HISTORY_DIR}"
+
+    lines = [f"**Saved Conversation Histories** ({len(history_files)} total):\n"]
+    lines.append(f"Location: {HISTORY_DIR}\n")
+
+    for history_file in history_files:
+        try:
+            with open(history_file, "r") as f:
+                data = json.load(f)
+                session_id = data.get("session_id", history_file.stem)
+                timestamp = data.get("timestamp", "unknown")
+                message_count = len(data.get("messages", []))
+
+                lines.append(
+                    f"- **{session_id}**\n"
+                    f"  - Timestamp: {timestamp}\n"
+                    f"  - Messages: {message_count}\n"
+                    f"  - File: {history_file.name}"
+                )
+        except Exception as e:
+            lines.append(f"- **{history_file.stem}** (error reading: {e})")
+
+    return "\n".join(lines)
+
+
+def _read_conversation_history(session_id: Optional[str]) -> str:
+    """Read a specific conversation history."""
+    if not session_id:
+        return "❌ session_id required for read_history action"
+
+    history_file = HISTORY_DIR / f"{session_id}.json"
+
+    if not history_file.exists():
+        return f"❌ No history found for session: {session_id}\n\nAvailable histories:\n{_list_conversation_histories()}"
+
+    try:
+        with open(history_file, "r") as f:
+            data = json.load(f)
+
+        messages = data.get("messages", [])
+        timestamp = data.get("timestamp", "unknown")
+
+        lines = [
+            f"**Conversation History: {session_id}**\n",
+            f"Timestamp: {timestamp}",
+            f"Messages: {len(messages)}\n",
+            "---\n",
+        ]
+
+        # Format messages
+        for i, msg in enumerate(messages, 1):
+            role = msg.get("role", "unknown")
+            content_blocks = msg.get("content", [])
+
+            lines.append(f"**{i}. {role.upper()}:**")
+
+            for block in content_blocks:
+                if "text" in block:
+                    lines.append(f"  {block['text']}")
+                elif "toolUse" in block:
+                    tool_use = block["toolUse"]
+                    lines.append(f"  [Tool Call: {tool_use['name']}]")
+                elif "toolResult" in block:
+                    lines.append(f"  [Tool Result]")
+
+            lines.append("")
+
+        return "\n".join(lines)
+
+    except Exception as e:
+        return f"❌ Error reading history: {e}"