claude-mpm 5.4.85__py3-none-any.whl → 5.6.76__py3-none-any.whl

claude_mpm/core/network_config.py

@@ -0,0 +1,148 @@
+"""Centralized network port configuration for Claude MPM.
+
+This module provides the single source of truth for all network port defaults
+and environment variable names used throughout the MPM system.
+
+WHY: Previously, port defaults were hardcoded in multiple locations (config.py,
+constants.py, commander/config.py, CLI parsers), leading to inconsistencies and
+difficulty maintaining different defaults per service.
+
+USAGE:
+    from claude_mpm.core.network_config import NetworkPorts
+
+    # Get default ports
+    monitor_port = NetworkPorts.MONITOR_DEFAULT
+    commander_port = NetworkPorts.COMMANDER_DEFAULT
+
+    # Get from environment with fallback
+    port = NetworkPorts.get_monitor_port()
+"""
+
+import os
+from typing import Optional
+
+
+class NetworkPorts:
+    """Network port configuration with different defaults for each service.
+
+    Service Default Ports:
+    - Monitor: 8765 (user's preferred default)
+    - Commander: 8766
+    - Dashboard: 8767
+    - SocketIO: 8768
+
+    Port Range: 8765-8785 (21 ports available)
+
+    Environment Variables:
+    - CLAUDE_MPM_MONITOR_PORT: Override monitor port
+    - CLAUDE_MPM_COMMANDER_PORT: Override commander port
+    - CLAUDE_MPM_DASHBOARD_PORT: Override dashboard port
+    - CLAUDE_MPM_SOCKETIO_PORT: Override socketio port
+    - CLAUDE_MPM_DEFAULT_HOST: Override default host (default: 127.0.0.1)
+    """
+
+    # Default ports for each service
+    MONITOR_DEFAULT = 8765
+    COMMANDER_DEFAULT = 8766
+    DASHBOARD_DEFAULT = 8767
+    SOCKETIO_DEFAULT = 8768
+
+    # Port range configuration
+    PORT_RANGE_START = 8765
+    PORT_RANGE_END = 8785
+
+    # Default host
+    DEFAULT_HOST = "127.0.0.1"
+
+    # Environment variable names
+    ENV_MONITOR_PORT = "CLAUDE_MPM_MONITOR_PORT"
+    ENV_COMMANDER_PORT = "CLAUDE_MPM_COMMANDER_PORT"
+    ENV_DASHBOARD_PORT = "CLAUDE_MPM_DASHBOARD_PORT"
+    ENV_SOCKETIO_PORT = "CLAUDE_MPM_SOCKETIO_PORT"
+    ENV_DEFAULT_HOST = "CLAUDE_MPM_DEFAULT_HOST"
+
+    @classmethod
+    def get_monitor_port(cls, default: Optional[int] = None) -> int:
+        """Get monitor port from environment or default.
+
+        Args:
+            default: Optional override default (if not provided, uses MONITOR_DEFAULT)
+
+        Returns:
+            Port number from environment or default
+        """
+        if default is None:
+            default = cls.MONITOR_DEFAULT
+        return int(os.getenv(cls.ENV_MONITOR_PORT, default))
+
+    @classmethod
+    def get_commander_port(cls, default: Optional[int] = None) -> int:
+        """Get commander port from environment or default.
+
+        Args:
+            default: Optional override default (if not provided, uses COMMANDER_DEFAULT)
+
+        Returns:
+            Port number from environment or default
+        """
+        if default is None:
+            default = cls.COMMANDER_DEFAULT
+        return int(os.getenv(cls.ENV_COMMANDER_PORT, default))
+
+    @classmethod
+    def get_dashboard_port(cls, default: Optional[int] = None) -> int:
+        """Get dashboard port from environment or default.
+
+        Args:
+            default: Optional override default (if not provided, uses DASHBOARD_DEFAULT)
+
+        Returns:
+            Port number from environment or default
+        """
+        if default is None:
+            default = cls.DASHBOARD_DEFAULT
+        return int(os.getenv(cls.ENV_DASHBOARD_PORT, default))
+
+    @classmethod
+    def get_socketio_port(cls, default: Optional[int] = None) -> int:
+        """Get socketio port from environment or default.
+
+        Args:
+            default: Optional override default (if not provided, uses SOCKETIO_DEFAULT)
+
+        Returns:
+            Port number from environment or default
+        """
+        if default is None:
+            default = cls.SOCKETIO_DEFAULT
+        return int(os.getenv(cls.ENV_SOCKETIO_PORT, default))
+
+    @classmethod
+    def get_default_host(cls) -> str:
+        """Get default host from environment or default.
+
+        Returns:
+            Host address from environment or DEFAULT_HOST
+        """
+        return os.getenv(cls.ENV_DEFAULT_HOST, cls.DEFAULT_HOST)
+
+    @classmethod
+    def get_port_range(cls) -> range:
+        """Get the valid port range.
+
+        Returns:
+            Range object from PORT_RANGE_START to PORT_RANGE_END (inclusive)
+        """
+        return range(cls.PORT_RANGE_START, cls.PORT_RANGE_END + 1)
+
+    @classmethod
+    def is_port_in_range(cls, port: int) -> bool:
+        """Check if port is within valid range.
+
+        Args:
+            port: Port number to check
+
+        Returns:
+            True if port is in valid range, False otherwise
+        """
+        return cls.PORT_RANGE_START <= port <= cls.PORT_RANGE_END

claude_mpm/core/oneshot_session.py

@@ -11,7 +11,7 @@ defines the interface it needs.
 
 import contextlib
 import os
-import subprocess
+import subprocess  # nosec B404
 import tempfile
 import time
 import uuid
@@ -86,11 +86,12 @@ class OneshotSession:
         Returns:
             True if successful, False otherwise
         """
-        # Deploy system agents
-        if not self.runner.setup_agents():
-            print("Continuing without native agents...")
+        # NOTE: System agents are deployed via reconciliation during startup.
+        # The reconciliation process respects user configuration and handles
+        # both native and custom mode deployment. No need to call setup_agents() here.
 
-        # Deploy project-specific agents
+        # Deploy project-specific agents from .claude-mpm/agents/
+        # This is separate from system agents and handles user-defined agents
         self.runner.deploy_project_agents_to_claude()
 
         return True
@@ -225,7 +226,7 @@ class OneshotSession:
             if len(cmd) > 5:
                 self.logger.debug(f"Command has {len(cmd)} arguments total")
 
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603
                 cmd, capture_output=True, text=True, env=env, check=False
             )
 

claude_mpm/core/output_style_manager.py

@@ -27,7 +27,9 @@ _CACHED_CLAUDE_VERSION: Optional[str] = None
 _VERSION_DETECTED: bool = False
 
 # Output style types
-OutputStyleType = Literal["professional", "teaching", "founders"]
+OutputStyleType = Literal[
+    "professional", "teaching", "research", "founders"
+]  # "founders" is deprecated, use "research"
 
 
 class StyleConfig(TypedDict):
@@ -44,7 +46,7 @@ class OutputStyleManager:
     Supports three output styles:
     - professional: Default Claude MPM style (claude-mpm.md)
     - teaching: Adaptive teaching mode (claude-mpm-teacher.md)
-    - founders: Non-technical mode for startup founders (claude-mpm-founders.md)
+    - research: Codebase research mode for founders, PMs, and developers (claude-mpm-research.md)
     """
 
     def __init__(self) -> None:
@@ -72,12 +74,20 @@ class OutputStyleManager:
                 target=self.output_style_dir / "claude-mpm-teacher.md",
                 name="Claude MPM Teacher",
             ),
+            "research": StyleConfig(
+                source=Path(__file__).parent.parent
+                / "agents"
+                / "CLAUDE_MPM_RESEARCH_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm-research.md",
+                name="Claude MPM Research",
+            ),
+            # Backward compatibility alias (deprecated)
             "founders": StyleConfig(
                 source=Path(__file__).parent.parent
                 / "agents"
-                / "CLAUDE_MPM_FOUNDERS_OUTPUT_STYLE.md",
-                target=self.output_style_dir / "claude-mpm-founders.md",
-                name="Claude MPM Founders",
+                / "CLAUDE_MPM_RESEARCH_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm-research.md",
+                name="Claude MPM Research",
             ),
         }
 
@@ -287,6 +297,9 @@ class OutputStyleManager:
             target_path = style_config["target"]
             style_name = style_config["name"]
 
+            # Check if this is a fresh install (file doesn't exist yet)
+            is_fresh_install = not target_path.exists()
+
             # If content not provided, read from source
             if content is None:
                 content = self.extract_output_style_content(style=style)
@@ -300,7 +313,9 @@ class OutputStyleManager:
 
             # Activate the style if requested
             if activate:
-                self._activate_output_style(style_name)
+                self._activate_output_style(
+                    style_name, is_fresh_install=is_fresh_install
+                )
 
             return True
 
@@ -308,12 +323,21 @@ class OutputStyleManager:
             self.logger.error(f"Failed to deploy {style} style: {e}")
             return False
 
-    def _activate_output_style(self, style_name: str = "Claude MPM") -> bool:
+    def _activate_output_style(
+        self, style_name: str = "Claude MPM", is_fresh_install: bool = False
+    ) -> bool:
         """
         Update Claude Code settings to activate a specific output style.
 
+        Only activates the style if:
+        1. No active style is currently set (first deployment), OR
+        2. This is a fresh install (style file didn't exist before deployment)
+
+        This preserves user preferences if they've manually changed their active style.
+
         Args:
             style_name: Name of the style to activate (e.g., "Claude MPM", "Claude MPM Teacher")
+            is_fresh_install: Whether this is a fresh install (style file didn't exist before)
 
         Returns:
             True if activated successfully, False otherwise
@@ -332,8 +356,15 @@ class OutputStyleManager:
             # Check current active style
             current_style = settings.get("activeOutputStyle")
 
-            # Update active output style if different
-            if current_style != style_name:
+            # Only set activeOutputStyle if:
+            # 1. No active style is set (first deployment), OR
+            # 2. Current style is "default" (not a real user preference), OR
+            # 3. This is a fresh install (file didn't exist before deployment)
+            should_activate = (
+                current_style is None or current_style == "default" or is_fresh_install
+            )
+
+            if should_activate and current_style != style_name:
                 settings["activeOutputStyle"] = style_name
 
                 # Ensure settings directory exists
@@ -348,7 +379,10 @@ class OutputStyleManager:
                     f"✅ Activated {style_name} output style (was: {current_style or 'none'})"
                 )
             else:
-                self.logger.debug(f"{style_name} output style already active")
+                self.logger.debug(
+                    f"Preserving user preference: {current_style or 'none'} "
+                    f"(skipping activation of {style_name})"
+                )
 
             return True
 
@@ -442,6 +476,10 @@ class OutputStyleManager:
         """
         results: Dict[str, bool] = {}
 
+        # Check if professional style exists BEFORE deployment
+        # This determines if this is a fresh install
+        professional_style_existed = self.styles["professional"]["target"].exists()
+
         for style_type_key in self.styles:
             # Deploy without activation
             # Cast is safe because we know self.styles keys are OutputStyleType
@@ -449,9 +487,11 @@ class OutputStyleManager:
             success = self.deploy_output_style(style=style_type, activate=False)
             results[style_type] = success
 
-        # Activate the default style if requested
+        # Activate the default style if requested AND this is first deployment
         if activate_default and results.get("professional", False):
-            self._activate_output_style("Claude MPM")
+            self._activate_output_style(
+                "Claude MPM", is_fresh_install=not professional_style_existed
+            )
 
         return results
 

claude_mpm/core/socketio_pool.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Socket.IO connection pool for efficient client connection management.
 
 This module provides a connection pool to reuse Socket.IO client connections,
@@ -31,12 +30,21 @@ except ImportError:
 # Import constants for configuration
 try:
     from claude_mpm.core.constants import NetworkConfig
+    from claude_mpm.core.network_config import NetworkPorts
 except ImportError:
     # Fallback if constants module not available
+    class NetworkPorts:
+        MONITOR_DEFAULT = 8765
+        COMMANDER_DEFAULT = 8766
+        DASHBOARD_DEFAULT = 8767
+        SOCKETIO_DEFAULT = 8768
+        PORT_RANGE_START = 8765
+        PORT_RANGE_END = 8785
+
     class NetworkConfig:
-        DEFAULT_DASHBOARD_PORT = 8765
+        DEFAULT_DASHBOARD_PORT = 8767
         SOCKETIO_PORT_RANGE = (8765, 8785)
-        DEFAULT_SOCKETIO_PORT = 8765
+        DEFAULT_SOCKETIO_PORT = 8768
 
     socketio = None
 
@@ -184,9 +192,14 @@ class SocketIOConnectionPool:
         self.health_running = False
         self.last_health_check = datetime.now(timezone.utc)
 
-        # Server configuration
-        self.server_url = None
-        self.server_port = None
+        # Server configuration - use default immediately, update async
+        self.server_port = int(
+            os.environ.get(
+                "CLAUDE_MPM_SOCKETIO_PORT", str(NetworkConfig.DEFAULT_SOCKETIO_PORT)
+            )
+        )
+        self.server_url = f"http://localhost:{self.server_port}"
+        self._port_detection_complete = False
 
         # Pool lifecycle
         self._running = False
@@ -200,7 +213,10 @@ class SocketIOConnectionPool:
             return
 
         self._running = True
-        self._detect_server()
+
+        # Start async port detection in background (non-blocking)
+        # Default port is already set in __init__, this just updates if a better one is found
+        self._detect_server_async()
 
         # Start batch processing thread
         self.batch_running = True
@@ -266,14 +282,29 @@ class SocketIOConnectionPool:
 
         self.logger.info("Socket.IO connection pool stopped")
 
+    def _detect_server_async(self):
+        """Start server detection in background thread.
+
+        This runs port scanning asynchronously to avoid blocking the main thread.
+        The default port is already set in __init__, so this just updates if a better one is found.
+        """
+        threading.Thread(
+            target=self._detect_server, daemon=True, name="port-detect"
+        ).start()
+
     def _detect_server(self):
-        """Detect Socket.IO server configuration."""
-        # Check environment variable first
+        """Detect Socket.IO server configuration.
+
+        This method scans ports to find a running Socket.IO server.
+        It's designed to be run in a background thread to avoid blocking.
+        """
+        # Check environment variable first - if set, use it and skip detection
         env_port = os.environ.get("CLAUDE_MPM_SOCKETIO_PORT")
         if env_port:
             try:
                 self.server_port = int(env_port)
                 self.server_url = f"http://localhost:{self.server_port}"
+                self._port_detection_complete = True
                 self.logger.debug(
                     f"Using Socket.IO server from environment: {self.server_url}"
                 )
@@ -302,19 +333,20 @@ class SocketIOConnectionPool:
         for port in common_ports:
             try:
                 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-                    s.settimeout(0.05)
+                    # Use 10ms timeout (reduced from 50ms) for faster scanning
+                    s.settimeout(0.01)
                     result = s.connect_ex(("localhost", port))
                     if result == 0:
                         self.server_port = port
                         self.server_url = f"http://localhost:{port}"
+                        self._port_detection_complete = True
                         self.logger.debug(f"Detected Socket.IO server on port {port}")
                         return
-            except Exception:
+            except Exception:  # nosec B112 - intentional: skip ports that fail
                 continue
 
-        # Fall back to default
-        self.server_port = NetworkConfig.DEFAULT_DASHBOARD_PORT
-        self.server_url = f"http://localhost:{self.server_port}"
+        # Keep default port set in __init__, mark detection complete
+        self._port_detection_complete = True
         self.logger.debug(f"Using default Socket.IO server: {self.server_url}")
 
     def _create_client(self) -> Optional[socketio.AsyncClient]:
@@ -579,7 +611,7 @@ class SocketIOConnectionPool:
                     loop.stop()
                     loop.run_until_complete(loop.shutdown_asyncgens())
                     loop.close()
-                except Exception:
+                except Exception:  # nosec B110 - intentional: cleanup best-effort
                     pass
 
     async def _connect_client(self, client: socketio.AsyncClient):

claude_mpm/core/unified_config.py

@@ -73,15 +73,19 @@ class AgentConfig(BaseModel):
     )
 
     # Required agents that are always deployed
+    # Standard 7 core agents for essential PM workflow functionality
+    # These are auto-deployed when no agents are specified in configuration
     required: List[str] = Field(
         default_factory=lambda: [
-            "research",
-            "mpm-skills-manager",
-            "mpm-agent-manager",
-            "memory-manager",
-            "ticketing",
+            "engineer",  # General-purpose implementation
+            "research",  # Codebase exploration and analysis
+            "qa",  # Testing and quality assurance
+            "web-qa",  # Browser-based testing specialist
+            "documentation",  # Documentation generation
+            "ops",  # Basic deployment operations
+            "ticketing",  # Ticket tracking (essential for PM workflow)
         ],
-        description="Agents that are always deployed (core system agents)",
+        description="Agents that are always deployed (standard 7 core agents)",
     )
 
     include_universal: bool = Field(

claude_mpm/core/unified_paths.py

@@ -76,6 +76,7 @@ class DeploymentContext(Enum):
     EDITABLE_INSTALL = "editable_install"
     PIP_INSTALL = "pip_install"
     PIPX_INSTALL = "pipx_install"
+    UV_TOOLS = "uv_tools"
     SYSTEM_PACKAGE = "system_package"
 
 
@@ -190,113 +191,100 @@ class PathContext:
 
         Priority order:
         1. Environment variable override (CLAUDE_MPM_DEV_MODE)
-        2. Current working directory is a claude-mpm development project
-        3. Editable installation detection
-        4. Path-based detection (development, pipx, system, pip)
+        2. Package installation path (uv tools, pipx, site-packages, editable)
+        3. Current working directory (opt-in with CLAUDE_MPM_PREFER_LOCAL_SOURCE)
+
+        This ensures installed packages use their installation paths rather than
+        accidentally picking up development paths from CWD.
         """
-        # Check for environment variable override
+        # 1. Explicit environment variable override
         if os.environ.get("CLAUDE_MPM_DEV_MODE", "").lower() in ("1", "true", "yes"):
             logger.debug(
                 "Development mode forced via CLAUDE_MPM_DEV_MODE environment variable"
             )
             return DeploymentContext.DEVELOPMENT
 
-        # Check if current working directory is a claude-mpm development project
-        # This handles the case where pipx claude-mpm is run from within the dev directory
-        cwd = _safe_cwd()
-        current = cwd
-        for _ in range(5):  # Check up to 5 levels up from current directory
-            if (current / "pyproject.toml").exists() and (
-                current / "src" / "claude_mpm"
-            ).exists():
-                # Check if this is the claude-mpm project
-                try:
-                    pyproject_content = (current / "pyproject.toml").read_text()
-                    if (
-                        'name = "claude-mpm"' in pyproject_content
-                        or '"claude-mpm"' in pyproject_content
-                    ):
-                        logger.debug(
-                            f"Detected claude-mpm development directory at {current}"
-                        )
-                        logger.debug(
-                            "Using development mode for local source preference"
-                        )
-                        return DeploymentContext.DEVELOPMENT
-                except Exception:  # nosec B110
-                    pass
-            if current == current.parent:
-                break
-            current = current.parent
-
+        # 2. Check where the actual package is installed
         try:
             import claude_mpm
 
             module_path = Path(claude_mpm.__file__).parent
+            package_str = str(module_path)
 
-            # First check if this is an editable install, regardless of path
-            # This is important for cases where pipx points to a development installation
-            if PathContext._is_editable_install():
-                logger.debug("Detected editable/development installation")
-                # Check if we should use development paths
-                # This could be because we're in a src/ directory or running from dev directory
-                if module_path.parent.name == "src":
-                    return DeploymentContext.DEVELOPMENT
-                if "pipx" in str(module_path):
-                    # Running via pipx but from within a development directory
-                    # Use development mode to prefer local source over pipx installation
-                    cwd = _safe_cwd()
-                    current = cwd
-                    for _ in range(5):
-                        if (current / "src" / "claude_mpm").exists() and (
-                            current / "pyproject.toml"
-                        ).exists():
-                            logger.debug(
-                                "Running pipx from development directory, using development mode"
-                            )
-                            return DeploymentContext.DEVELOPMENT
-                        if current == current.parent:
-                            break
-                        current = current.parent
-                    return DeploymentContext.EDITABLE_INSTALL
-                return DeploymentContext.EDITABLE_INSTALL
+            # UV tools installation (~/.local/share/uv/tools/)
+            if "/.local/share/uv/tools/" in package_str:
+                logger.debug(f"Detected uv tools installation at {module_path}")
+                return DeploymentContext.UV_TOOLS
 
-            # Check for development mode based on directory structure
-            # module_path is typically /path/to/project/src/claude_mpm
-            if (
-                module_path.parent.name == "src"
-                and (module_path.parent.parent / "src" / "claude_mpm").exists()
-            ):
+            # pipx installation (~/.local/pipx/venvs/)
+            if "/.local/pipx/venvs/" in package_str or "/pipx/" in package_str:
+                logger.debug(f"Detected pipx installation at {module_path}")
+                return DeploymentContext.PIPX_INSTALL
+
+            # site-packages (pip install) - but not editable
+            if "/site-packages/" in package_str and "/src/" not in package_str:
+                logger.debug(f"Detected pip installation at {module_path}")
+                return DeploymentContext.PIP_INSTALL
+
+            # Editable install (pip install -e) - module in src/
+            if module_path.parent.name == "src":
+                # Check if this is truly an editable install
+                if PathContext._is_editable_install():
+                    logger.debug(f"Detected editable installation at {module_path}")
+                    return DeploymentContext.EDITABLE_INSTALL
+                # Module in src/ but not editable - development mode
                 logger.debug(
                     f"Detected development mode via directory structure at {module_path}"
                 )
                 return DeploymentContext.DEVELOPMENT
 
-            # Check for pipx install
-            if "pipx" in str(module_path):
-                logger.debug(f"Detected pipx installation at {module_path}")
-                return DeploymentContext.PIPX_INSTALL
-
-            # Check for system package
-            if "dist-packages" in str(module_path):
+            # dist-packages (system package manager)
+            if "dist-packages" in package_str:
                 logger.debug(f"Detected system package installation at {module_path}")
                 return DeploymentContext.SYSTEM_PACKAGE
 
-            # Check for site-packages (could be pip or editable)
-            if "site-packages" in str(module_path):
-                # Already checked for editable above, so this is a regular pip install
-                logger.debug(f"Detected pip installation at {module_path}")
-                return DeploymentContext.PIP_INSTALL
-
-            # Default to pip install
+            # Default to pip install for any other installation
             logger.debug(f"Defaulting to pip installation for {module_path}")
             return DeploymentContext.PIP_INSTALL
 
         except ImportError:
             logger.debug(
-                "ImportError during context detection, defaulting to development"
+                "ImportError during module path detection, checking CWD as fallback"
             )
-            return DeploymentContext.DEVELOPMENT
+
+        # 3. CWD-based detection (OPT-IN ONLY for explicit development work)
+        # Only use CWD if explicitly requested or no package installation found
+        if os.environ.get("CLAUDE_MPM_PREFER_LOCAL_SOURCE", "").lower() in (
+            "1",
+            "true",
+            "yes",
+        ):
+            cwd = _safe_cwd()
+            current = cwd
+            for _ in range(5):  # Check up to 5 levels up from current directory
+                if (current / "pyproject.toml").exists() and (
+                    current / "src" / "claude_mpm"
+                ).exists():
+                    # Check if this is the claude-mpm project
+                    try:
+                        pyproject_content = (current / "pyproject.toml").read_text()
+                        if (
+                            'name = "claude-mpm"' in pyproject_content
+                            or '"claude-mpm"' in pyproject_content
+                        ):
+                            logger.debug(
+                                f"CLAUDE_MPM_PREFER_LOCAL_SOURCE: Using development directory at {current}"
+                            )
+                            return DeploymentContext.DEVELOPMENT
+                    except Exception:  # nosec B110
+                        pass
+                if current == current.parent:
+                    break
+                current = current.parent
+
+        # Final fallback: assume development mode
+        logger.debug("No installation detected, defaulting to development mode")
+        return DeploymentContext.DEVELOPMENT
 
 
 class UnifiedPathManager: