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

devduck/__init__.py

@@ -189,18 +189,7 @@ def manage_tools_func(
     tool_names: str = None,
     tool_path: str = None,
 ) -> Dict[str, Any]:
-    """
-    Manage the agent's tool set at runtime using ToolRegistry.
-
-    Args:
-        action: Action to perform - "list", "add", "remove", "reload"
-        package: Package name to load tools from (e.g., "strands_tools", "strands_fun_tools")
-        tool_names: Comma-separated tool names (e.g., "shell,editor,calculator")
-        tool_path: Path to a .py file to load as a tool
-
-    Returns:
-        Dict with status and content
-    """
+    """Manage the agent's tool set at runtime - add, remove, list, reload tools on the fly."""
     try:
         if not hasattr(devduck, "agent") or not devduck.agent:
             return {"status": "error", "content": [{"text": "Agent not initialized"}]}
@@ -633,7 +622,7 @@ class DevDuck:
 
             # Load tools with flexible configuration
             # Default tool config - user can override with DEVDUCK_TOOLS env var
-            default_tools = "devduck.tools:system_prompt,store_in_kb,ipc,tcp,websocket,mcp_server,state_manager,tray,ambient,agentcore_config,agentcore_invoke,agentcore_logs,agentcore_agents,install_tools,create_subagent,use_github:strands_tools:shell,editor,file_read,file_write,image_reader,load_tool,retrieve,calculator,use_agent,environment,mcp_client,speak,slack:strands_fun_tools:listen,cursor,clipboard,screen_reader,bluetooth,yolo_vision"
+            default_tools = "devduck.tools:system_prompt,store_in_kb,ipc,tcp,websocket,mcp_server,state_manager,tray,ambient,agentcore_config,agentcore_invoke,agentcore_logs,agentcore_agents,install_tools,create_subagent,use_github;strands_tools:shell,editor,file_read,file_write,image_reader,load_tool,retrieve,calculator,use_agent,environment,mcp_client,speak,slack;strands_fun_tools:listen,cursor,clipboard,screen_reader,bluetooth,yolo_vision"
 
             tools_config = os.getenv("DEVDUCK_TOOLS", default_tools)
             logger.info(f"Loading tools from config: {tools_config}")
@@ -657,7 +646,18 @@ class DevDuck:
                 tool_names: str = None,
                 tool_path: str = None,
             ) -> Dict[str, Any]:
-                """Manage the agent's tool set at runtime - add, remove, list, reload tools on the fly."""
+                """
+                Manage the agent's tool set at runtime using ToolRegistry.
+
+                Args:
+                    action: Action to perform - "list", "add", "remove", "reload"
+                    package: Package name to load tools from (e.g., "strands_tools", "strands_fun_tools") or "devduck.tools:speech_to_speech,system_prompt,..."
+                    tool_names: Comma-separated tool names (e.g., "shell,editor,calculator")
+                    tool_path: Path to a .py file to load as a tool
+
+                Returns:
+                    Dict with status and content
+                """
                 return manage_tools_func(action, package, tool_names, tool_path)
 
             # Add built-in tools to the toolset
@@ -715,39 +715,39 @@ class DevDuck:
         """
         Load tools based on DEVDUCK_TOOLS configuration.
 
-        Format: package:tool1,tool2:package2:tool3
-        Example: strands_tools:shell,editor:strands_fun_tools:clipboard
+        Format: package1:tool1,tool2;package2:tool3,tool4
+        Examples:
+          - strands_tools:shell,editor;strands_action:use_github
+          - strands_action:use_github;strands_tools:shell,use_aws
 
         Note: Only loads what's specified in config - no automatic additions
         """
         tools = []
-        current_package = None
-
-        for segment in config.split(":"):
-            segment = segment.strip()
-
-            # Check if segment is a package name (contains '.' or '_' and no ',')
-            is_package = "," not in segment and ("." in segment or "_" in segment)
-
-            if is_package:
-                # This is a package name - set as current package
-                current_package = segment
-                logger.debug(f"Switched to package: {current_package}")
-            elif "," in segment:
-                # Tool list from current package
-                if current_package:
-                    for tool_name in segment.split(","):
-                        tool_name = tool_name.strip()
-                        tool = self._load_single_tool(current_package, tool_name)
-                        if tool:
-                            tools.append(tool)
-            elif current_package:
-                # Single tool from current package
-                tool = self._load_single_tool(current_package, segment)
+
+        # Split by semicolon to get package groups
+        groups = config.split(";")
+
+        for group in groups:
+            group = group.strip()
+            if not group:
+                continue
+
+            # Split by colon to get package:tools
+            parts = group.split(":", 1)
+            if len(parts) != 2:
+                logger.warning(f"Invalid format: {group}")
+                continue
+
+            package = parts[0].strip()
+            tools_str = parts[1].strip()
+
+            # Parse tools (comma-separated)
+            tool_names = [t.strip() for t in tools_str.split(",") if t.strip()]
+
+            for tool_name in tool_names:
+                tool = self._load_single_tool(package, tool_name)
                 if tool:
                     tools.append(tool)
-            else:
-                logger.warning(f"Skipping segment '{segment}' - no package set")
 
         logger.info(f"Loaded {len(tools)} tools from configuration")
         return tools
@@ -1094,9 +1094,11 @@ You have full access to your own source code for self-awareness and self-modific
 
 ## Tool Configuration:
 Set DEVDUCK_TOOLS for custom tools:
-- Format: package:tool1,tool2:package2:tool3
-- Example: strands_tools:shell,editor:strands_fun_tools:clipboard
+- Format: package1:tool1,tool2;package2:tool3,tool4
+- Example: strands_tools:shell,editor;strands_fun_tools:clipboard
 - Tools are filtered - only specified tools are loaded
+- Load the speech_to_speech tool when it's needed
+- Offload the tools when you don't need
 
 ## MCP Integration:
 - **Expose as MCP Server** - Use mcp_server() to expose devduck via MCP protocol

devduck/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.7.2'
-__version_tuple__ = version_tuple = (0, 7, 2)
+__version__ = version = '1.1.0'
+__version_tuple__ = version_tuple = (1, 1, 0)
 
 __commit_id__ = commit_id = None

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}"

{devduck-0.7.2.dist-info → devduck-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devduck
-Version: 0.7.2
+Version: 1.1.0
 Summary: 🦆 Extreme minimalist self-adapting AI agent - one file, self-healing, runtime dependencies
 Author-email: Cagatay Cali <cagataycali@icloud.com>
 License: Apache-2.0
@@ -31,6 +31,7 @@ Requires-Dist: prompt_toolkit
 Requires-Dist: strands-agents[ollama]
 Requires-Dist: strands-agents[anthropic]
 Requires-Dist: strands-agents[openai]
+Requires-Dist: strands-agents[bidi-all]; sys_platform == "darwin"
 Requires-Dist: strands-agents[otel]
 Requires-Dist: strands-agents-tools
 Requires-Dist: strands-fun-tools[all]; sys_platform == "darwin"
@@ -239,7 +240,7 @@ install_tools(action="list_loaded")
 
 ### Static Tool Configuration
 
-**Format:** `package:tool1,tool2:package2:tool3`
+**Format:** `package1:tool1,tool2;package2:tool3,tool4`
 
 ```bash
 # Minimal (shell + editor only)
@@ -249,7 +250,7 @@ export DEVDUCK_TOOLS="strands_tools:shell,editor"
 export DEVDUCK_TOOLS="strands_tools:shell,editor,file_read,file_write,calculator"
 
 # Full stack + GitHub
-export DEVDUCK_TOOLS="devduck.tools:tcp,websocket,mcp_server,use_github:strands_tools:shell,editor,file_read"
+export DEVDUCK_TOOLS="devduck.tools:tcp,websocket,mcp_server,use_github;strands_tools:shell,editor,file_read"
 
 devduck
 ```
@@ -572,7 +573,7 @@ devduck
 | `LITELLM_API_KEY` | - | LiteLLM API key (auto-detected) |
 | `LLAMAAPI_API_KEY` | - | LlamaAPI key (auto-detected) |
 | **Tools** | | |
-| `DEVDUCK_TOOLS` | 38 tools | Format: `package:tool1,tool2:package2:tool3` |
+| `DEVDUCK_TOOLS` | 38 tools | Format: `package1:tool1,tool2;package2:tool3` |
 | `DEVDUCK_LOAD_TOOLS_FROM_DIR` | `false` | Auto-load from `./tools/` directory |
 | **Memory** | | |
 | `DEVDUCK_KNOWLEDGE_BASE_ID` | - | Bedrock KB ID for auto-RAG |

{devduck-0.7.2.dist-info → devduck-1.1.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
-devduck/__init__.py,sha256=jsamv9JKRuP5ludIQm3WAZWNd_MUPcN6Z60nerTJP5E,71612
+devduck/__init__.py,sha256=P7xQxthfPj2sDfcxn-kwA24gtBbtfDYu2Tf_y8KuEic,71545
 devduck/__main__.py,sha256=aeF2RR4k7lzSR2X1QKV9XQPCKhtsH0JYUv2etBBqmL0,145
-devduck/_version.py,sha256=69rtUS5MR_8CGRaNqkaDM6V4ZDI_8FTMw2vDLxrWg0Q,704
+devduck/_version.py,sha256=ePNVzJOkxR8FY5bezqKQ_fgBRbzH1G7QTaRDHvGQRAY,704
 devduck/agentcore_handler.py,sha256=0DKJTTjoH9P8a70G0f5dOIIwy6bjqaN46voAWaSOpDY,2221
 devduck/test_redduck.py,sha256=ILtKKMuoyVfmhnibmbojpbOsqbcKooZv4j9qtE2LWdw,1750
 devduck/tools/__init__.py,sha256=AmIy8MInaClaZ71fqzy4EQJnBWsLkrv4QW9IIN7UQyw,1367
@@ -15,6 +15,7 @@ devduck/tools/create_subagent.py,sha256=UzRz9BmU4PbTveZROEpZ311aH-u-i6x89gttu-Cn
 devduck/tools/install_tools.py,sha256=3uzRg5lEHX-L6gxnFn3mIKjGYDJ3h_AdwGnEwKA9qR0,14284
 devduck/tools/ipc.py,sha256=e3KJeR2HmCKEtVLGNOtf6CeFi3pTDehwd7Fu4JJ19Ms,18607
 devduck/tools/mcp_server.py,sha256=Ybp0PcJKW2TOvghsRL-i8Guqc9WokPwOD2bhVgzoj6Q,21490
+devduck/tools/speech_to_speech.py,sha256=rw9Olrdd_JvfeInk1ZeztVzSSuw5QQ_2Vnt-WbtLu50,28627
 devduck/tools/state_manager.py,sha256=hrleqdVoCboNd8R3wDRUXVKYCZdGoe1j925i948LTHc,10563
 devduck/tools/store_in_kb.py,sha256=-JM-oRQKR3FBubKHFHmXRnZSvi9dVgHxG0lismMgG2k,6861
 devduck/tools/system_prompt.py,sha256=waAdmvRhyulorw_tLqpqUJN_AahuaeF2rXqjMqN7IRY,16905
@@ -22,9 +23,9 @@ devduck/tools/tcp.py,sha256=w2m_Jf6vZ4NYu0AwgZd7C7eKs4No2EVHZ2WYIl_Bt0A,22017
 devduck/tools/tray.py,sha256=FgVhUtLdsdv5_ERK-RyAIpDE8Zb0IfoqhHQdwMxrHUQ,7547
 devduck/tools/use_github.py,sha256=nr3JSGk48mKUobpgW__2gu6lFyUj93a1XRs3I6vH8W4,13682
 devduck/tools/websocket.py,sha256=A8bqgdDZs8hcf2HctkJzQOzMvb5mXUC7YZ-xqkOyn94,16959
-devduck-0.7.2.dist-info/licenses/LICENSE,sha256=UANcoWwfVeuM9597WUkjEQbzqIUH0bJoE9Tpwgj_LvU,11345
-devduck-0.7.2.dist-info/METADATA,sha256=za19Gpk4RiF-EI1LE2bY0wLH055aMBVffE4Z0rzJmZ8,21781
-devduck-0.7.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-devduck-0.7.2.dist-info/entry_points.txt,sha256=BAMQaIg_BLZQOTk12bT7hy1dE9oGPLt-_dTbI4cnBnQ,40
-devduck-0.7.2.dist-info/top_level.txt,sha256=ySXWlVronp8xHYfQ_Hdfr463e0EnbWuqyuxs94EU7yk,8
-devduck-0.7.2.dist-info/RECORD,,
+devduck-1.1.0.dist-info/licenses/LICENSE,sha256=UANcoWwfVeuM9597WUkjEQbzqIUH0bJoE9Tpwgj_LvU,11345
+devduck-1.1.0.dist-info/METADATA,sha256=UM7NICyyRNPlMkvh-qKaGktgJGjxEi6qboUeIzLmwvo,21855
+devduck-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+devduck-1.1.0.dist-info/entry_points.txt,sha256=PJ8gvdi2MnKEK8yCwcmZDeLQ-lx94EV_jp4-v8AKuTA,58
+devduck-1.1.0.dist-info/top_level.txt,sha256=ySXWlVronp8xHYfQ_Hdfr463e0EnbWuqyuxs94EU7yk,8
+devduck-1.1.0.dist-info/RECORD,,

{devduck-0.7.2.dist-info → devduck-1.1.0.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+dev = devduck:cli
 devduck = devduck:cli