claude-mpm 5.4.48__py3-none-any.whl → 5.6.34__py3-none-any.whl

claude_mpm/commander/instance_manager.py

@@ -0,0 +1,450 @@
+"""Manages running Claude Code/MPM instances."""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.commander.adapters import (
+    AdapterResponse,
+    ClaudeCodeAdapter,
+    ClaudeCodeCommunicationAdapter,
+)
+from claude_mpm.commander.frameworks.base import BaseFramework, InstanceInfo
+from claude_mpm.commander.frameworks.claude_code import ClaudeCodeFramework
+from claude_mpm.commander.frameworks.mpm import MPMFramework
+from claude_mpm.commander.tmux_orchestrator import TmuxOrchestrator
+
+logger = logging.getLogger(__name__)
+
+
+class InstanceNotFoundError(Exception):
+    """Raised when an instance is not found."""
+
+    def __init__(self, name: str):
+        super().__init__(f"Instance not found: {name}")
+        self.name = name
+
+
+class FrameworkNotFoundError(Exception):
+    """Raised when a framework is not found or not available."""
+
+    def __init__(self, framework: str):
+        super().__init__(f"Framework not found or not available: {framework}")
+        self.framework = framework
+
+
+class InstanceAlreadyExistsError(Exception):
+    """Raised when trying to start an instance that already exists."""
+
+    def __init__(self, name: str):
+        super().__init__(f"Instance already exists: {name}")
+        self.name = name
+
+
+class InstanceManager:
+    """Manages lifecycle of Claude instances.
+
+    The InstanceManager coordinates framework selection, instance startup,
+    and tracking of running instances across the TmuxOrchestrator.
+
+    Attributes:
+        orchestrator: TmuxOrchestrator for managing tmux sessions/panes
+
+    Example:
+        >>> orchestrator = TmuxOrchestrator()
+        >>> manager = InstanceManager(orchestrator)
+        >>> frameworks = manager.list_frameworks()
+        >>> print(frameworks)
+        ['cc', 'mpm']
+        >>> instance = await manager.start_instance(
+        ...     "myapp",
+        ...     Path("/Users/user/myapp"),
+        ...     framework="cc"
+        ... )
+        >>> print(instance.name, instance.framework)
+        myapp cc
+    """
+
+    def __init__(self, orchestrator: TmuxOrchestrator):
+        """Initialize the instance manager.
+
+        Args:
+            orchestrator: TmuxOrchestrator for managing tmux sessions/panes
+        """
+        self.orchestrator = orchestrator
+        self._instances: dict[str, InstanceInfo] = {}
+        self._frameworks = self._load_frameworks()
+        self._adapters: dict[str, ClaudeCodeCommunicationAdapter] = {}
+
+    def _load_frameworks(self) -> dict[str, BaseFramework]:
+        """Load available frameworks.
+
+        Returns:
+            Dict mapping framework name to framework instance
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> frameworks = manager._load_frameworks()
+            >>> print(frameworks.keys())
+            dict_keys(['cc', 'mpm'])
+        """
+        frameworks = {}
+        for framework_class in [ClaudeCodeFramework, MPMFramework]:
+            framework = framework_class()
+            if framework.is_available():
+                frameworks[framework.name] = framework
+                logger.info(
+                    f"Loaded framework: {framework.name} ({framework.display_name})"
+                )
+            else:
+                logger.warning(
+                    f"Framework not available: {framework.name} ({framework.display_name})"
+                )
+
+        return frameworks
+
+    def list_frameworks(self) -> list[str]:
+        """List available framework names.
+
+        Returns:
+            List of framework names (e.g., ["cc", "mpm"])
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> frameworks = manager.list_frameworks()
+            >>> print(frameworks)
+            ['cc', 'mpm']
+        """
+        return list(self._frameworks.keys())
+
+    async def start_instance(
+        self, name: str, project_path: Path, framework: str = "cc"
+    ) -> InstanceInfo:
+        """Start a new instance.
+
+        Args:
+            name: Instance name (e.g., "myapp")
+            project_path: Path to project directory
+            framework: Framework to use ("cc" or "mpm")
+
+        Returns:
+            InstanceInfo with tmux session details
+
+        Raises:
+            FrameworkNotFoundError: If framework is not available
+            InstanceAlreadyExistsError: If instance already exists
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> instance = await manager.start_instance(
+            ...     "myapp",
+            ...     Path("/Users/user/myapp"),
+            ...     framework="cc"
+            ... )
+            >>> print(instance.name, instance.framework)
+            myapp cc
+        """
+        # Check if instance already exists
+        if name in self._instances:
+            raise InstanceAlreadyExistsError(name)
+
+        # Get framework
+        if framework not in self._frameworks:
+            raise FrameworkNotFoundError(framework)
+
+        framework_obj = self._frameworks[framework]
+
+        # Get git info
+        git_branch, git_status = framework_obj.get_git_info(project_path)
+
+        # Ensure tmux session exists
+        self.orchestrator.create_session()
+
+        # Create pane
+        pane_target = self.orchestrator.create_pane(name, str(project_path))
+
+        # Start framework in pane
+        startup_cmd = framework_obj.get_startup_command(project_path)
+        self.orchestrator.send_keys(pane_target, startup_cmd)
+
+        # Create communication adapter for the instance (only for Claude Code for now)
+        # Do this BEFORE creating InstanceInfo so we can set connected=True
+        has_adapter = False
+        if framework == "cc":
+            runtime_adapter = ClaudeCodeAdapter()
+            comm_adapter = ClaudeCodeCommunicationAdapter(
+                orchestrator=self.orchestrator,
+                pane_target=pane_target,
+                runtime_adapter=runtime_adapter,
+            )
+            self._adapters[name] = comm_adapter
+            has_adapter = True
+            logger.debug(f"Created communication adapter for instance '{name}'")
+
+        # Create instance info
+        instance = InstanceInfo(
+            name=name,
+            project_path=project_path,
+            framework=framework,
+            tmux_session=self.orchestrator.session_name,
+            pane_target=pane_target,
+            git_branch=git_branch,
+            git_status=git_status,
+            connected=has_adapter,
+        )
+
+        # Track instance
+        self._instances[name] = instance
+
+        logger.info(
+            f"Started instance '{name}' with framework '{framework}' at {project_path}"
+        )
+
+        return instance
+
+    async def stop_instance(self, name: str) -> bool:
+        """Stop an instance.
+
+        Args:
+            name: Instance name
+
+        Returns:
+            True if instance was stopped
+
+        Raises:
+            InstanceNotFoundError: If instance not found
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> await manager.stop_instance("myapp")
+            True
+        """
+        if name not in self._instances:
+            raise InstanceNotFoundError(name)
+
+        instance = self._instances[name]
+
+        # Kill tmux pane
+        self.orchestrator.kill_pane(instance.pane_target)
+
+        # Remove adapter if exists
+        if name in self._adapters:
+            del self._adapters[name]
+            instance.connected = False
+            logger.debug(f"Removed adapter for instance '{name}'")
+
+        # Remove from tracking
+        del self._instances[name]
+
+        logger.info(f"Stopped instance '{name}'")
+
+        return True
+
+    def get_instance(self, name: str) -> Optional[InstanceInfo]:
+        """Get instance by name.
+
+        Args:
+            name: Instance name
+
+        Returns:
+            InstanceInfo if found, None otherwise
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> instance = manager.get_instance("myapp")
+            >>> if instance:
+            ...     print(instance.name, instance.framework)
+            myapp cc
+        """
+        return self._instances.get(name)
+
+    def list_instances(self) -> list[InstanceInfo]:
+        """List all running instances.
+
+        Returns:
+            List of InstanceInfo for all running instances
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> instances = manager.list_instances()
+            >>> for instance in instances:
+            ...     print(instance.name, instance.framework)
+            myapp cc
+            otherapp mpm
+        """
+        return list(self._instances.values())
+
+    async def send_to_instance(
+        self, name: str, message: str, wait_for_response: bool = False
+    ) -> Optional[AdapterResponse]:
+        """Send a message/command to an instance.
+
+        Args:
+            name: Instance name
+            message: Message to send
+            wait_for_response: If True, wait for and return response
+
+        Returns:
+            AdapterResponse if wait_for_response=True, None otherwise
+
+        Raises:
+            InstanceNotFoundError: If instance not found
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> # Send without waiting
+            >>> await manager.send_to_instance("myapp", "Fix the bug in main.py")
+            >>> # Send and wait for response
+            >>> response = await manager.send_to_instance(
+            ...     "myapp", "Fix the bug", wait_for_response=True
+            ... )
+            >>> print(response.content)
+        """
+        if name not in self._instances:
+            raise InstanceNotFoundError(name)
+
+        instance = self._instances[name]
+
+        # Use adapter if available
+        if name in self._adapters:
+            adapter = self._adapters[name]
+            await adapter.send(message)
+            logger.info(
+                f"Sent message via adapter to instance '{name}': {message[:50]}..."
+            )
+
+            if wait_for_response:
+                return await adapter.receive()
+            return None
+
+        # Fallback to direct tmux if no adapter
+        self.orchestrator.send_keys(instance.pane_target, message)
+        logger.info(f"Sent message to instance '{name}': {message[:50]}...")
+        return None
+
+    def get_adapter(self, name: str) -> Optional[ClaudeCodeCommunicationAdapter]:
+        """Get communication adapter for an instance.
+
+        Args:
+            name: Instance name
+
+        Returns:
+            ClaudeCodeCommunicationAdapter if exists, None otherwise
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> adapter = manager.get_adapter("myapp")
+            >>> if adapter:
+            ...     await adapter.send("Create a new file")
+            ...     async for chunk in adapter.stream_response():
+            ...         print(chunk, end='')
+        """
+        return self._adapters.get(name)
+
+    async def rename_instance(self, old_name: str, new_name: str) -> bool:
+        """Rename an instance.
+
+        Args:
+            old_name: Current instance name
+            new_name: New instance name
+
+        Returns:
+            True if renamed successfully
+
+        Raises:
+            InstanceNotFoundError: If old_name doesn't exist
+            InstanceAlreadyExistsError: If new_name already exists
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> await manager.rename_instance("myapp", "myapp-v2")
+            True
+        """
+        # Validate old_name exists
+        if old_name not in self._instances:
+            raise InstanceNotFoundError(old_name)
+
+        # Validate new_name doesn't exist
+        if new_name in self._instances:
+            raise InstanceAlreadyExistsError(new_name)
+
+        # Get instance and update name
+        instance = self._instances[old_name]
+        instance.name = new_name
+
+        # Update _instances dict (remove old key, add new)
+        del self._instances[old_name]
+        self._instances[new_name] = instance
+
+        # Update _adapters dict if exists
+        if old_name in self._adapters:
+            adapter = self._adapters[old_name]
+            del self._adapters[old_name]
+            self._adapters[new_name] = adapter
+            logger.debug(f"Moved adapter from '{old_name}' to '{new_name}'")
+
+        logger.info(f"Renamed instance from '{old_name}' to '{new_name}'")
+
+        return True
+
+    async def close_instance(self, name: str) -> bool:
+        """Close and remove an instance.
+
+        Alias for stop_instance that provides clearer semantics for closing.
+
+        Args:
+            name: Instance name to close
+
+        Returns:
+            True if closed successfully
+
+        Raises:
+            InstanceNotFoundError: If instance not found
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> await manager.close_instance("myapp")
+            True
+        """
+        return await self.stop_instance(name)
+
+    async def disconnect_instance(self, name: str) -> bool:
+        """Disconnect from an instance without closing it.
+
+        The instance keeps running but we stop communication.
+        Removes the adapter while keeping the instance tracked.
+
+        Args:
+            name: Instance name to disconnect from
+
+        Returns:
+            True if disconnected successfully
+
+        Raises:
+            InstanceNotFoundError: If instance not found
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> await manager.disconnect_instance("myapp")
+            True
+            >>> # Instance still running, but no adapter connection
+            >>> adapter = manager.get_adapter("myapp")
+            >>> print(adapter)
+            None
+        """
+        # Validate instance exists
+        if name not in self._instances:
+            raise InstanceNotFoundError(name)
+
+        instance = self._instances[name]
+
+        # Remove adapter if exists (but keep instance)
+        if name in self._adapters:
+            # Could add cleanup here if adapter has resources to close
+            del self._adapters[name]
+            instance.connected = False
+            logger.info(f"Disconnected from instance '{name}' (instance still running)")
+        else:
+            logger.debug(f"No adapter to disconnect for instance '{name}'")
+
+        return True

claude_mpm/commander/llm/__init__.py

@@ -0,0 +1,6 @@
+"""LLM integration for Commander chat interface and summarization."""
+
+from .openrouter_client import OpenRouterClient, OpenRouterConfig
+from .summarizer import OutputSummarizer
+
+__all__ = ["OpenRouterClient", "OpenRouterConfig", "OutputSummarizer"]

claude_mpm/commander/llm/openrouter_client.py

@@ -0,0 +1,167 @@
+"""OpenRouter LLM client for Commander chat interface."""
+
+import os
+from dataclasses import dataclass
+from typing import AsyncIterator
+
+import httpx
+
+
+@dataclass
+class OpenRouterConfig:
+    """Configuration for OpenRouter API client."""
+
+    api_key: str | None = None  # Falls back to OPENROUTER_API_KEY env
+    model: str = "anthropic/claude-3.5-sonnet"
+    base_url: str = "https://openrouter.ai/api/v1"
+    max_tokens: int = 4096
+    temperature: float = 0.7
+
+
+class OpenRouterClient:
+    """Async client for OpenRouter API."""
+
+    def __init__(self, config: OpenRouterConfig | None = None):
+        """Initialize client with config.
+
+        Args:
+            config: OpenRouter configuration. Defaults to OpenRouterConfig().
+
+        Raises:
+            ValueError: If OPENROUTER_API_KEY is not set.
+        """
+        self.config = config or OpenRouterConfig()
+        self._api_key = self.config.api_key or os.getenv("OPENROUTER_API_KEY")
+        if not self._api_key:
+            raise ValueError("OPENROUTER_API_KEY not set")
+
+    async def chat(self, messages: list[dict], system: str | None = None) -> str:
+        """Send chat completion request, return response content.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys.
+            system: Optional system prompt.
+
+        Returns:
+            Response content from the model.
+
+        Raises:
+            httpx.HTTPStatusError: If API request fails.
+        """
+        async with httpx.AsyncClient() as client:
+            # Build request payload
+            payload = {
+                "model": self.config.model,
+                "messages": messages,
+                "max_tokens": self.config.max_tokens,
+                "temperature": self.config.temperature,
+            }
+
+            if system:
+                payload["system"] = system
+
+            # Send request
+            response = await client.post(
+                f"{self.config.base_url}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Content-Type": "application/json",
+                },
+                json=payload,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+
+            # Extract content from response
+            data = response.json()
+            return data["choices"][0]["message"]["content"]
+
+    async def chat_stream(
+        self, messages: list[dict], system: str | None = None
+    ) -> AsyncIterator[str]:
+        """Stream chat completion, yield chunks.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys.
+            system: Optional system prompt.
+
+        Yields:
+            Content chunks from the streaming response.
+
+        Raises:
+            httpx.HTTPStatusError: If API request fails.
+        """
+        async with httpx.AsyncClient() as client:
+            # Build request payload
+            payload = {
+                "model": self.config.model,
+                "messages": messages,
+                "max_tokens": self.config.max_tokens,
+                "temperature": self.config.temperature,
+                "stream": True,
+            }
+
+            if system:
+                payload["system"] = system
+
+            # Send streaming request
+            async with client.stream(
+                "POST",
+                f"{self.config.base_url}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Content-Type": "application/json",
+                },
+                json=payload,
+                timeout=30.0,
+            ) as response:
+                response.raise_for_status()
+
+                # Parse SSE stream
+                async for line in response.aiter_lines():
+                    if not line.strip():
+                        continue
+
+                    # SSE format: "data: {json}"
+                    if line.startswith("data: "):
+                        data_str = line[6:]  # Remove "data: " prefix
+
+                        # Check for stream end
+                        if data_str == "[DONE]":
+                            break
+
+                        # Parse JSON chunk
+                        import json
+
+                        try:
+                            data = json.loads(data_str)
+                            delta = data["choices"][0].get("delta", {})
+                            if "content" in delta:
+                                yield delta["content"]
+                        except (json.JSONDecodeError, KeyError, IndexError):
+                            # Skip malformed chunks
+                            continue
+
+    async def summarize(self, text: str, max_length: int = 500) -> str:
+        """Summarize text to max_length characters.
+
+        Args:
+            text: Text to summarize.
+            max_length: Maximum length of summary in characters.
+
+        Returns:
+            Summarized text.
+        """
+        messages = [
+            {
+                "role": "user",
+                "content": f"Summarize the following text in approximately {max_length} characters or less:\n\n{text}",
+            }
+        ]
+
+        system = (
+            "You are a concise summarization assistant. "
+            "Provide clear, accurate summaries that capture the key points."
+        )
+
+        return await self.chat(messages, system=system)

claude_mpm/commander/llm/summarizer.py

@@ -0,0 +1,70 @@
+"""Summarizes Claude Code output for user display."""
+
+from .openrouter_client import OpenRouterClient
+
+
+class OutputSummarizer:
+    """Summarizes long output from Claude Code instances."""
+
+    def __init__(self, client: OpenRouterClient):
+        """Initialize with OpenRouter client.
+
+        Args:
+            client: OpenRouterClient instance for LLM requests.
+        """
+        self.client = client
+
+    async def summarize(self, output: str, context: str | None = None) -> str:
+        """Summarize Claude Code output.
+
+        Args:
+            output: Raw output from Claude Code.
+            context: Optional context about what was requested.
+
+        Returns:
+            Concise summary of the output.
+        """
+        # Build summarization prompt
+        if context:
+            prompt = f"""Summarize the following Claude Code output.
+
+Context: {context}
+
+Output:
+{output}
+
+Provide a concise summary (2-3 sentences) that captures:
+1. What action was taken
+2. The key result or outcome
+3. Any important warnings or next steps
+
+Summary:"""
+        else:
+            prompt = f"""Summarize the following Claude Code output in 2-3 sentences.
+
+Output:
+{output}
+
+Summary:"""
+
+        messages = [{"role": "user", "content": prompt}]
+
+        system = (
+            "You are a technical summarization assistant. "
+            "Provide clear, concise summaries of command output and code execution results. "
+            "Focus on actionable information and key outcomes."
+        )
+
+        return await self.client.chat(messages, system=system)
+
+    def needs_summarization(self, output: str, threshold: int = 500) -> bool:
+        """Check if output is long enough to warrant summarization.
+
+        Args:
+            output: Output text to check.
+            threshold: Character count threshold for summarization.
+
+        Returns:
+            True if output exceeds threshold, False otherwise.
+        """
+        return len(output) > threshold